Manuais:UniNFe/EnviandoXMLBoleto

Como utilizar o serviço do e-Bank Boleto?

Após realizar a configuração do e-Bank no UniNFe, vamos consumir o serviço do e-Bank Boleto. Bora conferir?

• Observação:
  • Por enquanto, está implementado apenas o registro de boletos. Nas próximas semanas, serão integrados os serviços de cancelamento, prorrogação, instruções, etc e de acordo com o que o banco fornece de operações.

Registrando o boleto pelo UniNFe

Para conseguir fazer o registro de boleto, você deve gerar o XML conforme exemplo em nosso site na pasta de envio com o nome e formato a seguir:

0000000000000-BoletoRegistrar.xml

0000000000000	Conteúdo livre
-BoletoRegistrar.xml	Conteúdo fixo. Sempre será "-BoletoRegistrar.xml"

O nome do arquivo de retorno é o mesmo do envio, mudando somente a extensão (final) do mesmo, conforme abaixo:

0000000000000-ret-BoletoRegistrar.xml (se tudo ocorreu bem)

ou

0000000000000-ret-BoletoRegistrar.err (se houve algum erro)

---

Estrutura do XML de envio

Para ficar mais fácil o entendimento da estrutura, vamos separar por tópicos.

• Observação:
  • As tags escritas em vermelho na legenda, indica que são tags obrigatórias.

Informações iniciais

<?xml version="1.0" encoding="utf-8"?>
<BoletoRegistrar versao="1.00">
    <ConfigurationId>ZCKWGQ55LTDXKYYC</ConfigurationId>
    <Aceite>true</Aceite>
    <AgenciaColetora>N</AgenciaColetora>
    <Avalista>
        <Nome>string</Nome>
	<TipoInscricao>0</TipoInscricao>
	<Inscricao>string</Inscricao>
	<Endereco>
	    <Logradouro>Rua</Logradouro>
	    <Numero>11</Numero>
	    <Complemento>string</Complemento>
	    <Bairro>Bairro</Bairro>
	    <Cidade>Brasília</Cidade>
	    <UF>DF</UF>
	    <CEP>11111-111</CEP>
	</Endereco>
    </Avalista>
    <Carteira>string</Carteira>
    <CodigoBarraNumerico>string</CodigoBarraNumerico>
    <Desconto>
        <Data>2025-03-12</Data>
	<Tipo>0</Tipo>
	<Valor>0</Valor>
    </Desconto>
    <DiasParaBaixaOuDevolucao>0</DiasParaBaixaOuDevolucao>
    <DigitoVerificadorNumeroNoBanco>string</DigitoVerificadorNumeroNoBanco>
    <Emissao>2025-03-12</Emissao>
    <Especie>0</Especie>
    ....
    ....
    ....

• Legenda das tags:
  • A tag <ConfigurationId> é uma informação fornecida pela Unimake Software;
  • A tag <Aceite> é um campo true ou false para o aceite do boleto;
  • A tag <AgenciaColetora> indica se a agência é encarregada da cobrança.
  • O grupo <Avalista> indica as informações da pessoa que garante o pagamento da dívida;
  • A tag <Carteira> é o código da carteira do boleto;
  • A tag <CodigoBarraNumerico> indica o código de barras do boleto;
  • O grupo <Desconto> indica os descontos do boleto caso houver:
    • A tag <Tipo> pode ser preenchida com uma das informações abaixo:

Valores do tipo de desconto

• • A tag <DiasParaBaixaOuDevolucao> indica a quantidade de dias para o boleto ser baixado ou devolvido;
  • A tag <DigitoVerificadorNumeroNoBanco> é o campo para informar o dígito verificar do número do boleto no banco;
  • A tag <Emissao> indica a tag de emissão do boleto;
  • A tag <Especie> pode ser informada conforme abaixo:

Informações intermediárias

    ....
    ....
    ....
    <FichaAceiteConfig>
	<FichaAceite>true</FichaAceite>
	<Merge>true</Merge>
	<AceiteDetails>
		<Aceite>true</Aceite>
		<AgenciaCodigoBeneficiario>string</AgenciaCodigoBeneficiario>
		<Beneficiario>string</Beneficiario>
		<Carteira>string</Carteira>
		<CodigoBanco>0</CodigoBanco>
		<DataDocumento>2025-03-12</DataDocumento>
		<DataProcessamento>2025-03-12</DataProcessamento>
		<Descontos>0</Descontos>
		<Especie>string</Especie>
		<Instrucoes>
			<Instrucao>string</Instrucao>
		</Instrucoes>
		<LogoBanco>string</LogoBanco>
		<MoraMulta>0</MoraMulta>
		<NossoNumero>string</NossoNumero>
		<NumeroDocumento>string</NumeroDocumento>
		<OutrasDeducoes>0</OutrasDeducoes>
		<OutrosAcrescimos>0</OutrosAcrescimos>
		<Pagador>string</Pagador>
		<RodapeDireito>
			<CodigoBarras>string</CodigoBarras>
			<TextoLivre>string</TextoLivre>
		</RodapeDireito>
		<RodapeEsquerdo>
			<CodigoBarras>string</CodigoBarras>
			<TextoLivre>string</TextoLivre>
		</RodapeEsquerdo>
		<Testing>true</Testing>
		<ValorCobrado>0</ValorCobrado>
		<ValorDocumento>0</ValorDocumento>
		<Vencimento>2025-03-12</Vencimento>
	</AceiteDetails>
    </FichaAceiteConfig>
    <IdentificacaoDistribuicao>0</IdentificacaoDistribuicao>
    <IdentificacaoEmissao>0</IdentificacaoEmissao>
    <Juros>
    	<Data>2025-03-12</Data>
	<Tipo>0</Tipo>
	<Valor>0</Valor>
    </Juros>
    <LinhaDigitavel>string</LinhaDigitavel>
    <Mensagens>
	<Mensagem>string</Mensagem>
	<Mensagem>string</Mensagem>
	<Mensagem>string</Mensagem>
	<Mensagem>string</Mensagem>
    </Mensagens>
    <MensagensRecibo>
	<Mensagem>string</Mensagem>
    </MensagensRecibo>
    <Multa>
	<Data>2025-03-12</Data>
	<Tipo>0</Tipo>
	<Valor>0</Valor>
    </Multa>
    <NumeroDiasLimiteRecebimento>0</NumeroDiasLimiteRecebimento>
    <NumeroNaEmpresa>string</NumeroNaEmpresa>
    <NumeroNoBanco>string</NumeroNoBanco>
    <NumeroParcela>0</NumeroParcela>
    <NumeroVariacaoCarteira>0</NumeroVariacaoCarteira>
    ....
    ....
    ....

• Legenda das tags:
  • O grupo <FichaAceitaConfig> indica as configurações da ficha de aceite. Veja mais em configurando a ficha de aceite;
  • A tag <IdentificacaoDistribuicao> indica quem está distribuindo o boleto se é o cliente igual a 0 ou banco igual a 1;
  • A tag <IdentificacaoEmissao> indica quem está emitindo o boleto se é o cliente igual a 0 ou banco igual a 1;
  • O grupo <Juros> descreve os juros que serão aplicados ao título caso seja necessário:
    • A tag Data é a data inicial para ser aplicado os juros;
    • A tag <Tipo> deve ser um dos conteúdos abaixo:

Valores do tipo de juros

• • A tag <Valor> é o valor dos juros. Você pode informar como porcentagem ou valor de acordo com o tipo configurado anteriormente;
  • A tag <LinhaDigitavel> informa qual é a linha digitável do boleto em questão;
  • O grupo <Mensagens> auxilia na demonstração da mensagem de instrução para o pagador ou caixa sobre os juros, mora, entre outras informações importantes do boleto;
  • O grupo <MensagensRecibo> auxilia na demonstração da mensagem para o pagador no recibo do boleto;
  • O grupo <Multa> descreve informações sobre a multa que pode ser aplicada no título caso seja necessário:
    • A tag Data é a data inicial para ser aplicado a multa;
    • A tag <Tipo> deve ser um dos conteúdos abaixo:

Valores do tipo de multa

• • A tag <Valor> é o valor da multa. Você pode informar como porcentagem ou valor de acordo com o tipo configurado anteriormente;
  • A tag <NumeroDiasLimiteRecebimento> indica o limite de dias que o boleto pode ser recebido;
  • A tag <NumeroNaEmpresa> é a identificação do título na empresa (seu número);
  • A tag <NumeroNoBanco> é o número do documento no banco (nosso número):
    • Validação:
      • Itaú (314): -- Tamanho: 8 caracteres (sem informar o dígito verificador) -- Obrigatório: Sim
      • Banco do Brasil: -- Tamanho: 10 caracteres (sem informar o dígito verificador) -- Obrigatório: Sim
      • Caixa Econômica Federal: -- Tamanho: 17 caracteres -- Obrigatório: Não
      • Bradesco: -- Tamanho: 11 caracteres -- Obrigatório: Não
      • Santander: -- Tamanho: 12 caracteres (informando o dígito verificador) -- Obrigatório: Não
  • A tag <NumeroParcela> é o campo para informar o número da parcela;
  • A tag <NumeroVariacaoCarteira> indica o número de variação da carteira do boleto.

Informações finais

    ....
    ....
    ....
    <Pagador>
	<Nome>Pagador Fictício</Nome>
	<Inscricao>26994558000123</Inscricao>
	<TipoInscricao>0</TipoInscricao>
	<Codigo>string</Codigo>
	<Email>pagador@ficticio.com.br</Email>
	<Telefone>string</Telefone>
	<Endereco>
        	<Logradouro>Rua</Logradouro>
		<Numero>11</Numero>
		<Complemento>string</Complemento>
		<Bairro>Bairro</Bairro>
		<Cidade>Brasília</Cidade>
		<UF>DF</UF>
		<CEP>11111-111</CEP>
	</Endereco>
    </Pagador>
    <PDFConfig>
    	<Password>string</Password>
	<PermitAnnotations>true</PermitAnnotations>
	<PermitAssembleDocument>true</PermitAssembleDocument>
	<PermitExtractContent>true</PermitExtractContent>
	<PermitFormsFill>true</PermitFormsFill>
	<PermitFullQualityPrint>true</PermitFullQualityPrint>
	<PermitModifyDocument>true</PermitModifyDocument>
	<PermitPrint>true</PermitPrint>
	<SignPDF>true</SignPDF>
	<TryGeneratePDF>true</TryGeneratePDF>
    </PDFConfig>
    <PermiteRecebimentoParcial>N</PermiteRecebimentoParcial>
    <PixConfig>
	<Chave>string</Chave>
	<QrCodeConfig>
		<Height>0</Height>
		<ImageFormat>1</ImageFormat>
		<Quality>0</Quality>
		<Width>0</Width>
	</QrCodeConfig>
	<RegistrarPIX>true</RegistrarPIX>
    </PixConfig>
    <Protesto>
	<Tipo>1</Tipo>
	<Valor>0</Valor>
    </Protesto>
    <Testing>true</Testing>
    <TipoBaixaDevolucao>1</TipoBaixaDevolucao>
    <ValorAbatimento>0</ValorAbatimento>
    <ValorIOF>0</ValorIOF>
    <ValorNominal>45.88</ValorNominal>
    <Vencimento>2021-05-13</Vencimento>
    <UseHomologServer>true</UseHomologServer>	
</BoletoRegistrar>

• Legenda das tags:
  • O grupo <Pagador> são as informações do pagador do boleto;
  • O grupo <PDFConfig> indica as configurações do PDF. Veja mais em configurando o PDF do boleto;
  • A tag <PermiteRecebimentoParcial> é um campo N (false) ou S (true) que indica se permite recebimento parcial do boleto;
  • O grupo <PixConfig> indica as configurações do PIX quando o banco aceitar boleto híbrido. Veja mais em configurando o PIX do boleto híbrido;
  • O grupo <Protesto> informa o protesto que poderá ser aplicado ao título caso seja necessário:
    • A tag <Tipo> deve ser um dos conteúdos abaixo:

Valores do tipo de protesto

• • • A tag <Valor> é o número de dias para protesto ou negativação conforme tipo configurado anteriormente;
  • A tag <Testing> define o tipo de ambiente para emissão do boleto. Se true, será usado o ambiente de teste;
  • A tag <TipoBaixaDevolucao> indica o tipo de baixa ou devolução conforme conteúdo abaixo:

Valores do tipo de baixa ou devolução

• • A tag <ValorAbatimento> é o valor do abatimento do boleto;
  • A tag <ValorIOF> é o valor do IOF a ser recolhido;
  • A tag <ValorNominal> é o valor nominal do boleto em questão;
  • A tag <Vencimento> é a data de vencimento do boleto;
  • A tag <UseHomologServer> não é obrigatória, o valor dela por padrão é false. Só utilize quando é necessário fazer testes para possibilitar DEBUG do lado do eBank, naturalmente isso só pode ocorrer se um desenvolvedor do eBank solicitar esta tag no XML para facilitar depuração de código.

---

Estrutura mínima para utilizar o serviço

<?xml version="1.0" encoding="UTF-8"?>
<BoletoRegistrar versao="1.00">
    <ConfigurationId>ZCKWGQ55LTDXKYYC</ConfigurationId>
	<Aceite>true</Aceite>	
	<Emissao>2025-03-18</Emissao>
	<Especie>2</Especie>
	<NumeroParcela>0</NumeroParcela>
	<Pagador>
		<Nome>Pagador Fictício</Nome>
		<Inscricao>26994558000123</Inscricao>
		<TipoInscricao>0</TipoInscricao>
		<Endereco>
			<Logradouro>Rua</Logradouro>
			<Numero>11</Numero>
			<Complemento>string</Complemento>
			<Bairro>Bairro</Bairro>
			<Cidade>Brasília</Cidade>
			<UF>DF</UF>
			<CEP>11111-111</CEP>
		</Endereco>
	</Pagador>
	<PDFConfig>
		<TryGeneratePDF>true</TryGeneratePDF>
	</PDFConfig>	
	<Testing>true</Testing>
	<ValorNominal>45.88</ValorNominal>
	<Vencimento>2025-03-25</Vencimento>
	<UseHomologServer>true</UseHomologServer>	
</BoletoRegistrar>

---

XML de retorno do envio: O que fazer?

Para verificar se o boleto foi registrado, deve analisar o XML de retorno que será gerado na pasta de retorno com o nome a seguir:

0000000000000-ret-BoletoRegistrar.xml

E sua estrutura é a seguinte:

<?xml version="1.0" encoding="utf-8"?>
<BoletoRegistrarResponse>
	<Status>0</Status>
	<Motivo>Boleto registrado</Motivo>
	<CodigoBarraNumerico>73796162838172194122054272866843292534256573</CodigoBarraNumerico>
	<NumeroNoBanco>-2147483648</NumeroNoBanco>
	<LinhaDigitavel>53527298768113385317506126802226533485564252978</LinhaDigitavel>
	<PdfContentSuccess>True</PdfContentSuccess>
	<PdfContentMessage/>
	<PdfContentBase64>BASE_64_DO_PDF_BOLETO</PdfContentBase64>
	<PdfPath>d:\testenfe\Retorno\0000000000000-ret-BoletoRegistrar.pdf</PdfPath>
	<UniNFeVersao>5.1.0.136 | 25-03-2025 - 10:41:11</UniNFeVersao>
</BoletoRegistrarResponse>

• Legenda das tags:
  • A tag <Status> indica o status da requisição;
  • A tag <Motivo> é a descrição do status do boleto;
  • A tag <CodigoBarraNumerico> é o campo com o código de barras do boleto registrado;
  • A tag <NumeroNoBanco> é o campo com o número do boleto no banco;
  • A tag <LinhaDigitavel> é o campo com a linha digitável do boleto;
  • A tag <PdfContentSuccess> indica se o PDF do boleto retornou com sucesso;
  • A tag <PdfContentBase64> é o campo em base64 do boleto registrado;
  • A tag <PdfPath> é o caminho onde está o PDF do boleto;
  • A tag <UniNFeVersao> indica a versão do UniNFe que foi utilizada.

Veja também

• Como configurar o UniNFe para utilizar o e-Bank?
• Como utilizar o serviço do e-Bank PIX?