Manuais:ERP.Net/API/EBoleto

De unimake
Revisão de 10h39min de 20 de fevereiro de 2019 por Marcelo (discussão | contribs) (→‎Possíveis comandos para execução)
Ir para: navegação, pesquisa

E-Boleto - Sistema emissor de boletos eletrônicos.

Acessando a API

Para realizar o acesso à API é necessário estar logado no serviço.
Verifique como realizar a autenticação na página Autenticando na API.

Realizando a emissão de um boleto

Entendendo as propriedades de envio

Antes de iniciarmos com os exemplos. Verifique as definições dos campos para o envio dos boletos.

NomePagador Tipo Descrição Obrigatoriedade
agencia String Código da Cooperativa do beneficiário Obrigatório
posto String Código do Posto do beneficiário Obrigatório
CodigoCedente String Código do Convênio de Cobrança do beneficiário Obrigatório
nossoNumero String Nosso Número Opcional
codigoPagador String Código Pagador Opcional
tipoPessoa Domínios:


0
1

Tipo de pessoa do pagador, podendo ser:


0 - PESSOA FISICA
1 - PESSOA JURIDICA

Obrigatório
cpfCnpj String CPF e/ou CNPJ do pagador Obrigatório
nomePagador String Nome do pagador Obrigatório
EnderecoPagador String Endereço do pagador Opcional. Será obrigatório se o código do pagador não for informado.
cidade String Cidade do pagador Opcional. Será obrigatório se o código do pagador não for informado.
uf String Estado do pagador Opcional. Será obrigatório se o código do pagador não for informado.
cep String CEP do pagador Obrigatório
telefone String Telefone mais DDD do pagador Opcional. Será obrigatório se o código do pagador não for informado.
email String Endereço de E mail do pagador. Opcional. Será obrigatório se o código do pagador não for informado.
especieDocumento Domínios:


0
1
2
3
4
5
6
7
8
9
10

Espécie de documento do título, Obrigatório


Podendo ser:
0 - DUPLICATA MERCANTIL (DM)
1 - DUPLICATA RURAL (DR)
2 - NOTA PROMISSOR IA (NP)
3 - NOTA PROMISSOR IA RURAL (NR)
4 - NOTA DE SEGURO (NS)
5 - RECIBO (RC)
6 - LETRA DE CAMBIO (LC)
7 - NOTA DE DEBITO (ND)
8 - DUPLICATA DE SERVICO (DS)
9 - OUTROS (OS)
10 - BOLETO OFERTA (OFE)

codigoSacador Avalista String Código do sacador avalista. Se não existir, enviar ‘000' Obrigatório
seuNumero String Número de controle interno do beneficiário que referência o pagador. Obrigatório
dataVencimento Data Data de vencimento do boleto Obrigatório
valor Decimal Valor do boleto Obrigatório
tipoDesconto Domínios:


0
1

Tipo de desconto, podendo ser:


0 - VALOR
1 - PERCENTUAL

Obrigatório
valorDesconto 1 Decimal Valor de desconto 1 Opcional. Será obrigatório se o dataDesconto1 for informado.
dataDesconto1 Data Data limite para a concessão de desconto 1 Opcional. Será obrigatório se o valorDesconto1 for informado.
valorDesconto 2 Decimal Valor de desconto 2 Opcional. Será obrigatório se o dataDesconto2 for informado.
dataDesconto2 Data Data limite para a concessão de desconto 2 Opcional. Será obrigatório se o valorDesconto2 for informado.
valorDesconto 3 Decimal Valor de desconto 3 Opcional. Será obrigatório se o dataDesconto3 for informado.
dataDesconto3 String Data limite para a concessão de desconto 3 Opcional. Será obrigatório se o valorDesconto3 for informado.
tipoJuros Domínios:


0
1

Tipo de Juros, podendo ser:


0 - VALOR
1 - PERCENTUAL

Obrigatório
juros Decimal Valor de juros a cobrar por dia Opcional
multas Decimal Valor de multas a cobrar Opcional
descontoAntecipado Decimal Valor de desconto antecipado a cobrar Opcional. Deve ser menor que o valor.
Informativo String Texto do Informativo Obrigatório
mensagem String Texto da linha da mensagem. Obrigatório
codigoMensagem String Código da mensagem Opcional

Entendendo as propriedades de retorno

NomePagador Tipo Descrição
linhaDigitavel String Linhadigitável
codigoBanco String Códigodo Banco
nomeBeneficiario String Nome do Beneficiário
enderecoBeneficiario String Endereço do Beneficiário
cpfCnpjBeneficiario String CPF e/ou CNPJ do Beneficiário
cooperativaBeneficiario String Código da Cooperativa do Beneficiário
postoBeneficiario String Código da UA do Beneficiário
codigoBeneficiario String Códigodo Beneficiário
dataDocumento Data Data do Documento
seuNumero String Seu Número
especieDocumento String Espécie de Documento
aceite String Aceite
dataProcessamento Date Data do Processamento (do dia)
nossoNumero Decimal Nosso Numero
especie String Espécie: Real (Fixo)
valorDocumento Decimal Valordo Documento
dataVencimento Date Data de Vencimento
nomePagador String Nome do Pagador
cpfCnpjPagador String CPF e/ou CNPJ Pagador
enderecoPagador String Endereço do Pagador
dataLimiteDesconto Date Data Limite para Desconto
valorDesconto Decimal Valor do Desconto/Abatimento
jurosMulta Decimal Juros/multa

Caso de Sucesso

Endpoint https://erpnet.online/api/eboleto/emitir
Método POST
Body
(JSON)		 
{
  "Boleto": {
    "Agencia": "0726",
    "Posto": "28",
    "CodigoCedente": "89733",
    "nossoNumero": "",
    "codigoPagador": "",
    "tipoPessoa": "0",
    "cpfCnpj": "02664340026",
    "NomePagador": "teste",
    "EnderecoPagador": "dolores alcaras",
    "cidade": "portoalegre",
    "uf": "rs",
    "cep": "91760110",
    "telefone": "5188888888",
    "email": "[email protected]",
    "especieDocumento": "B",
    "codigoSacadorAvalista": "000",
    "seuNumero": "1234567891",
    "dataVencimento": "26/08/2016",
    "valor": 10,
    "tipoDesconto": "B",
    "valorDesconto1": null,
    "dataDesconto1": null,
    "valorDesconto2": null,
    "dataDesconto2": null,
    "valorDesconto3": null,
    "dataDesconto3": null,
    "tipoJuros": "A",
    "juros": null,
    "multas": null,
    "descontoAntecipado": null,
    "informativo": "teste1",
    "mensagem": "teste",
    "codigoMensagem": ""
  },
  "CodigoBanco": 748
}
O código do banco utilizado é o 748, pois apenas o Sicredi é aceito até o momento.
Retorno
(DATA)		 
{
    "Data": {
        "Aceite": "N",
        "Arquivo": null,
        "CodigoBanco": 748,
        "CodigoBeneficiario": "94914",
        "CpfCnpjBeneficiario": "06117473000150",
        "CpfCnpjPagador": "02664340026",
        "DataDocumento": "2018-05-15T00:00:00",
        "DataEmissao": null,
        "DataLimiteDesconto": null,
        "DataLiquidacao": null,
        "DataProcessamento": "2018-05-15T00:00:00",
        "DataVencimento": "0001-01-01T00:00:00",
        "EnderecoBeneficiario": "R. ANTONIO FELIPE, 1500",
        "EnderecoPagador": "DOLORES ALCARAS",
        "Especie": "REAL",
        "EspecieDocumento": "B",
        "JurosMulta": 0,
        "LinhaDigitavel": "74891118100002420718513949141074886950000001000",
        "NomeBeneficiario": "UNIMAKE SOLUCOES CORPORATIVAS",
        "NomePagador": "TESTE",
        "NossoNumero": "181000242",
        "OoperativaBeneficiario": null,
        "PostoBeneficiario": "13",
        "SeuNumero": "1234567891",
        "Situacao": null,
        "Valor": 0,
        "ValorDesconto": 0,
        "ValorDocumento": 10,
        "ValorLiquidado": null,
        "Codigo": null,
        "Mensagem": null,
        "Success": true
    },
    "Message": null,
    "Success": true,
    "StatusCode": 200
}

É retornado o boleto emitido em caso de sucesso. Propriedade Success = true.

Caso seja retornado Success = false verifique a mensagem de erro em Message

Caso de falha

Endpoint https://erpnet.online/api/eboleto/emitir
Método POST
Body
(JSON)		 
{
  "Boleto": {
    "NossoNumero": "",
    "CodigoPagador": "",
    "TipoPessoa": 1,
    "CpfCnpj": "02664340026",
    "Nome": "teste",
    "EnderecoPagador": "dolores alcaras",
    "Cidade": "portoalegre",
    "UF": "rs",
    "CEP": "91760110",
    "Telefone": "5188888888",
    "Email": "[email protected]",
    "EspecieDocumento": "B",
    "CodigoSacadorAvalista": "000",
    "SeuNumero": "1234567891",
    "DataVencimento": "26/08/2016",
    "Valor": 10,
    "TipoDesconto": 1,
    "TipoJuros": 1,
    "Informativo": "teste1",
    "Mensagem": "teste",
    "CodigoMensagem": ""
  },
  "CodigoBanco": 748
}
O código do banco utilizado é o 748, pois apenas o Sicredi é aceito até o momento.
Retorno
(DATA)		 
{
    "Data": {
        "Aceite": null,
        "Arquivo": null,
        "CodigoBanco": 0,
        "CodigoBeneficiario": null,
        "CpfCnpjBeneficiario": null,
        "CpfCnpjPagador": null,
        "DataDocumento": null,
        "DataEmissao": null,
        "DataLimiteDesconto": null,
        "DataLiquidacao": null,
        "DataProcessamento": null,
        "DataVencimento": null,
        "EnderecoBeneficiario": null,
        "EnderecoPagador": null,
        "Especie": null,
        "EspecieDocumento": null,
        "JurosMulta": null,
        "LinhaDigitavel": null,
        "NomeBeneficiario": null,
        "NomePagador": null,
        "NossoNumero": null,
        "OoperativaBeneficiario": null,
        "PostoBeneficiario": null,
        "SeuNumero": null,
        "Situacao": null,
        "Valor": 0,
        "ValorDesconto": null,
        "ValorDocumento": null,
        "ValorLiquidado": null,
        "Codigo": "E0010",
        "Mensagem": "Campo obrigatorio em branco.",
        "Success": false
    },
    "Message": "Campo obrigatorio em branco.",
    "Success": false,
    "StatusCode": 500
}

Perceba que não colocamos os campos Agencia, Posto e Cedente na requisição. O retorno foi Success = false com a propriedade Message preenchida com o erro.

A propriedade Data possui o resultado original do banco em questão. Pode variar de banco para banco.

Realizando a consulta de vários boletos emitidos

Caso de Sucesso

Endpoint https://erpnet.online/api/eboleto/consultar?Agencia=NÚMERO DA AGÊNCIA&Cedente=CÓDIGO DO CEDENTE&Posto=NÚMERO DO POSTO&NossoNumero=NÚMERO DO BOLETO NO BANCO&CodigoBanco=CÓDIGO DO BANCO
Método GET
QUERYSTRING 
Todos os parâmetros são opcionais, caso seja informado no ERP.Net.
Caso contrário, são obrigatórios serem informados os parâmetros Agencia, Cedente, Posto e CodigoBanco.
  • Agencia: Informar o número de sua agência para pesquisa de boletos;
  • Cedente: Informar o código do Cedente vinculado ao boleto;
  • Posto: Informar o código do posto de seu banco;
  • NossoNumero: Se informado, realiza a pesquisa apenas do boleto em questão;
  • CodigoBanco: Se configurado no ERP.Net, não é necessário passar este parâmetro.
Retorno
(DATA)		 
{
  "Data": [
    {
      "DataEmissao": "2018-03-23T00:00:00",
      "DataLiquidacao": null,
      "DataVencimento": "2016-08-26T00:00:00",
      "NomePagador": "TESTE",
      "NossoNumero": "181000013",
      "Parametro": null,
      "SeuNumero": "1234567891",
      "Situacao": "BAIXADO POR SOLICITACAO",
      "Valor": 10.5,
      "ValorLiquidado": 0,
      "Codigo": null,
      "Mensagem": null,
      "Success": true
    },
    {
      "DataEmissao": "2018-03-23T00:00:00",
      "DataLiquidacao": null,
      "DataVencimento": "2016-08-26T00:00:00",
      "NomePagador": "TESTE",
      "NossoNumero": "181000021",
      "Parametro": null,
      "SeuNumero": "1234567891",
      "Situacao": "BAIXADO POR SOLICITACAO",
      "Valor": 10.5,
      "ValorLiquidado": 0,
      "Codigo": null,
      "Mensagem": null,
      "Success": true
    },
    {
      "DataEmissao": "2018-05-15T00:00:00",
      "DataLiquidacao": null,
      "DataVencimento": "0001-01-01T00:00:00",
      "NomePagador": "TESTE",
      "NossoNumero": "181000242",
      "Parametro": null,
      "SeuNumero": "1234567891",
      "Situacao": "EM CARTEIRA",
      "Valor": 10,
      "ValorLiquidado": 0,
      "Codigo": null,
      "Mensagem": null,
      "Success": true
    }
  ],
  "Message": null,
  "Success": true,
  "StatusCode": 200
}

Caso de Falha

Para simular a falha, iremos omitir o parâmetro Agencia.

Endpoint https://erpnet.online/api/eboleto/consultar?Agencia=NÚMERO DA AGÊNCIA&Cedente=CÓDIGO DO CEDENTE&Posto=NÚMERO DO POSTO&NossoNumero=NÚMERO DO BOLETO NO BANCO&CodigoBanco=CÓDIGO DO BANCO
Método GET
QUERYSTRING 
Todos os parâmetros são opcionais, caso seja informado no ERP.Net.
Caso contrário, são obrigatórios serem informados os parâmetros Agencia, Cedente, Posto e CodigoBanco.
  • Agencia: Informar o número de sua agência para pesquisa de boletos;
  • Cedente: Informar o código do Cedente vinculado ao boleto;
  • Posto: Informar o código do posto de seu banco;
  • NossoNumero: Se informado, realiza a pesquisa apenas do boleto em questão;
  • CodigoBanco: Se configurado no ERP.Net, não é necessário passar este parâmetro.
Retorno
(DATA)		 
{
    "Data": [
        {
            "DataEmissao": null,
            "DataLiquidacao": null,
            "DataVencimento": null,
            "NomePagador": null,
            "NossoNumero": null,
            "Parametro": "agencia",
            "SeuNumero": null,
            "Situacao": null,
            "Valor": null,
            "ValorLiquidado": null,
            "Codigo": "E0010",
            "Mensagem": "Campo obrigatorio em branco. - Parâmetro: agencia",
            "Success": false
        }
    ],
    "Message": "Campo obrigatorio em branco. - Parâmetro: agencia",
    "Success": false,
    "StatusCode": 500
}

Realizando a consulta de um boleto

Entendendo as propriedades de retorno

Antes de iniciarmos a consulta, vamos entender as propriedades que serão retornadas.

Nome Tipo Descição
seuNumero String Seu Número
nossoNumero String Nosso número
nomePagador String Nome do Pagador
valor Decimal Valor do documento
valorLiquidado Decimal Valor liquidado
dataEmissao Date Data da emissão
dataVencimento Date Data de vencimento
dataLiquidacao Date Data da liquidação
situacao String

0. EM CARTEIRA
1. LIQUIDADO
2. BAIXADO POR SOLICITACAO
3. BAIXADO POR PROTESTO
4. EM CARTORIO
5. AGUARDANDO ENTRADA EM CARTORIO
6. AGUARDANDO SUSTACAO DE CARTORIO
7. REJEITADO
8. OUTROS

Caso de Sucesso

Pegue um NossoNumero válido para utilizar neste teste, caso contrário será retornado uma falha, como no exemplo do teste com falha.

Endpoint https://erpnet.online/api/eboleto/consultar?Agencia=NÚMERO DA AGÊNCIA&Cedente=CÓDIGO DO CEDENTE&Posto=NÚMERO DO POSTO&NossoNumero=NÚMERO DO BOLETO NO BANCO&CodigoBanco=CÓDIGO DO BANCO
Método GET
QUERYSTRING 
Com exceção do parâmetro NossoNumero os demais parâmetros são opcionais, caso sejam informados no ERP.Net.
Caso contrário, são obrigatórios serem informados os parâmetros Agencia, Cedente, Posto e CodigoBanco.
  • Agencia: Informar o número de sua agência para pesquisa de boletos;
  • Cedente: Informar o código do Cedente vinculado ao boleto;
  • Posto: Informar o código do posto de seu banco;
  • CodigoBanco: Se configurado no ERP.Net, não é necessário passar este parâmetro.
Parâmetro Obrigatório
  • NossoNumero: Realiza a pesquisa apenas do boleto em questão;
Retorno
(DATA)		 
{
    "Data": [
        {
            "DataEmissao": "2018-05-15T00:00:00Z",
            "DataLiquidacao": null,
            "DataVencimento": "0001-01-01T00:00:00Z",
            "NomePagador": "TESTE",
            "NossoNumero": "181000242",
            "Parametro": "",
            "SeuNumero": "1234567891",
            "Situacao": "BAIXADO POR SOLICITACAO",
            "Valor": 10,
            "ValorLiquidado": 0,
            "Codigo": "",
            "Mensagem": "",
            "Success": true
        }
    ],
    "Message": "",
    "Success": true,
    "StatusCode": 200
}

Caso de Falha

Para simular a falha, iremos passar um NossoNumero incorreto.

Endpoint https://erpnet.online/api/eboleto/consultar?Agencia=NÚMERO DA AGÊNCIA&Cedente=CÓDIGO DO CEDENTE&Posto=NÚMERO DO POSTO&NossoNumero=NÚMERO INCORRETO DO BOLETO NO BANCO&CodigoBanco=CÓDIGO DO BANCO
Método GET
QUERYSTRING 
Todos os parâmetros são opcionais, caso seja informado no ERP.Net.
Caso contrário, são obrigatórios serem informados os parâmetros Agencia, Cedente, Posto e CodigoBanco.
  • Agencia: Informar o número de sua agência para pesquisa de boletos;
  • Cedente: Informar o código do Cedente vinculado ao boleto;
  • Posto: Informar o código do posto de seu banco;
  • NossoNumero: Se informado, realiza a pesquisa apenas do boleto em questão;
  • CodigoBanco: Se configurado no ERP.Net, não é necessário passar este parâmetro.
Retorno
(DATA)		 
{
    "Data": [
        {
            "DataEmissao": null,
            "DataLiquidacao": null,
            "DataVencimento": null,
            "NomePagador": "",
            "NossoNumero": "",
            "Parametro": "",
            "SeuNumero": "",
            "Situacao": "",
            "Valor": null,
            "ValorLiquidado": null,
            "Codigo": "E0024",
            "Mensagem": "Nao foram encontrados resultados para os filtros de consulta informados. - Parâmetro: ",
            "Success": false
        }
    ],
    "Message": "Nao foram encontrados resultados para os filtros de consulta informados. - Parâmetro: ",
    "Success": false,
    "StatusCode": 500
}

Realizando uma ação no boleto

Este tópico demonstra como realizar uma ação em um boleto emitido pelo ERP.Net

Endpoint https://erpnet.online/api/eboleto/executarcomando
Método POST
Body
(JSON)		 Localize abaixo os possíveis comandos que podem ser executados. O código do banco utilizado é o 748, pois apenas o Sicredi é aceito até o momento.
Retorno
(JSON)		 
{
    "Message": "",
    "StatusCode": 200,
    "Success": true
}


Caso não consiga executar algum comando, a propriedade "Message" retornará o erro em questão e a propriedade "Success" será falso (false).

Possíveis comandos para execução

Segue o corpo dos JSON's dos possíveis comandos que pode ser executados:

  • Alteração de Vencimento
{
	"codigoBanco": "748",
	"agencia": "0100",
	"posto": "02",
	"cedente": "00248",
	"nossoNumero": "181000352",
	"acaoComando": "AlteracaoDeVencimento",
	"novoValor": "30/06/2018"
}
  • Alteração do seu número
{
	"codigoBanco": "748",
	"agencia": "0100",
	"posto": "02",
	"cedente": "00248",
	"nossoNumero": "181000360",
	"acaoComando": "AlteracaoSeuNumero",
	"novoValor": "1234"
}
  • Pedido de Baixa
{
	"codigoBanco": "748",
	"agencia": "0100",
	"posto": "02",
	"cedente": "00248",
	"nossoNumero": "181000352",
	"acaoComando": "PedidoDeBaixa"
}
  • Concessão de Abatimento
{
	"codigoBanco": "748",
	"agencia": "0100",
	"posto": "02",
	"cedente": "00248",
	"nossoNumero": "181000360",
	"acaoComando": "ConcessaoDeAbatimento",
	"novoValor": 3
}
  • Cancelamento de abatimento concedido
{
	"codigoBanco": "748",
	"agencia": "0100",
	"posto": "02",
	"cedente": "00248",
	"nossoNumero": "181000360",
	"acaoComando": "CancelamentoDeAbatimentoConcedido"
}
  • Alteração da data limite para desconto

Altera somente a data, o valor não. Caso o boleto emitido esteja somente com uma data de desconto cadastrada, irá alterar somente a data cadastrada. Se o boleto foi emitido sem nenhuma data de desconto, nada será alterado. 

{
	"codigoBanco": "748",
	"agencia": "0100",
	"posto": "02",
	"cedente": "00248",
	"nossoNumero": "181000360",
	"acaoComando": "AlteracaoOutrosDados",
	"acaoComandoComplementar": "DataLimiteConcessaoDesconto",
	"novoValor": "10/05/2018"
}
  • Alteração de desconto
{
	"codigoBanco": "748",
	"agencia": "0100",
	"posto": "02",
	"cedente": "00248",
	"nossoNumero": "181000360",
	"acaoComando": "AlteracaoOutrosDados",
	"acaoComandoComplementar": "Desconto",
	"novoValor": 1
}
  • Alteração de juros por dia

Muda somente o valor do juros por dia. 

{
	"codigoBanco": "748",
	"agencia": "0100",
	"posto": "02",
	"cedente": "00248",
	"nossoNumero": "181000360",
	"acaoComando": "AlteracaoOutrosDados",
	"acaoComandoComplementar": "JurosDia",
	"novoValor": 2.5
}
  • Desconto por dia de antecipação
{
	"codigoBanco": "748",
	"agencia": "0100",
	"posto": "02",
	"cedente": "00248",
	"nossoNumero": "181000379",
	"acaoComando": "AlteracaoOutrosDados",
	"acaoComandoComplementar": "DescontoDiaAntecipacao",
	"novoValor": 1.5
}
  • Pedido de Protesto

Somente em título vencido. 

{
	"codigoBanco": "748",
	"agencia": "0100",
	"posto": "02",
	"cedente": "00248",
	"nossoNumero": "181000360",
	"acaoComando": "PedidoDeProtesto"
}
  • Sustar o processo por baixa
{
	"codigoBanco": "748",
	"agencia": "0100",
	"posto": "02",
	"cedente": "00248",
	"nossoNumero": "181000360",
	"acaoComando": "SustarProtestoEBaixarTitulo"
}
  • Sustar protesto e manter a carteira
{
	"codigoBanco": "748",
	"agencia": "0100",
	"posto": "02",
	"cedente": "00248",
	"nossoNumero": "181000360",
	"acaoComando": "SustarProtestoEManterCarteira"
}
Disponível em "http://wiki.unimake.com.br/index.php?title=Manuais:ERP.Net/API/EBoleto&oldid=733"