Manuais:UniNFe/EnviandoXMLPIX

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

Após realizar a configuração do e-Bank no UniNFe, vamos consumir o serviço do e-Bank PIX que consiste em duas etapas. Bora conferir?

1ª etapa: Gerar a sinalização da cobrança no banco

Para conseguir gerar o PIX, você precisa sinalizar para o banco que quer criar essa cobrança e como a comunicação no UniNFe é por transmissão de arquivos, criamos um exemplo em XML de como você pode fazer isso. Para fazer o envio dessa cobrança, basta gerar o arquivo na pasta de envio com o nome e formato a seguir:

0000000000000-PIXCobCreate.xml

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

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

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

ou

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

---

Estrutura do XML de envio

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

Informações iniciais

<?xml version="1.0" encoding="utf-8"?>
<PIXCobrancaCreateRequest versao="1.00">
	<SolicitacaoPagador>Prestação de serviços em software</SolicitacaoPagador>
	<TipoCobranca>0</TipoCobranca>
	<Valor>1.00</Valor>
	<Chave>+5544999999999</Chave>
	<TxId>12345678901234567890123456789012345</TxId>
	<GerarQRCode>true</GerarQRCode>
	......
	......

• Legenda:
  • A tag <SolicitacaoPagador> é um campo livre, que pode ser utilizado para descrever o serviço prestado (tamanho máximo de 140 caracteres);
  • A tag <TipoCobranca> aceita dois valores:
    • 0 = Referente a cobrança sem vencimento, multas ou juros. Cobrança simples;
    • 1 = Referente a cobrança com vencimento, multas e juros. Normalmente utilizada junto com o boleto.
  • A tag <Valor> significa o valor do PIX sendo o ponto final como separador decimal;
  • A tag <Chave> é a chave PIX do recebedor;
  • A tag <TxId> é o identificador do PIX, através dele que será feita a consulta na 2ª etapa do serviço de PIX:
    • Observação: deve ter entre 26 e 35 caracteres contendo apenas letras e números, sem espaço em branco ou caracter especial.
  • A tag <GerarQRCode> quando true, gera um arquivo de imagem contendo o QRCode do PIX. Quando false, não gera o arquivo de imagem.

---

Grupo obrigatório

O grupo Beneficiário é obrigatório no XML, sendo definido após a tag <GerarQRCode>:

<Beneficiario>
	<Inscricao>11222333000122</Inscricao>
	<Nome>Empresa Teste</Nome>
	<Conta>
		<Agencia>1111</Agencia>
		<Numero>1111111</Numero>
		<Banco>756</Banco>
	</Conta>
</Beneficiario>

• Legenda:
  • A tag <Inscricao> é a informação do titular da conta do recebedor do PIX sendo CPF ou CNPJ;
  • A tag <Nome> é o nome do titular da conta do recebedor do PIX;
  • O grupo <Conta> terá as informações da conta que vai receber o PIX:
    • A tag <Agencia> é o número da agência da conta;
    • A tag <Numero> é o número da conta;
    • A tag <Banco> é o código do banco do recebedor: 756 (Sicoob), 748 (Sicredi), 33 (Santander) e assim por diante.
      • Observação: Temos o banco Sicoob, Banco do Brasil e Bradesco implementados para PIX. Para saber mais, entre em contato com a Unimake Software.

---

Grupos opcionais

O grupo de tag <Calendario> é opcional no XML. Quando não informado, receberá valores padrões:

<Calendario>
	<Criacao>2023-05-23T10:42:05</Criacao>
	<Expiracao>600</Expiracao>
</Calendario>

OU

<Calendario>
	<Criacao>2023-05-23T10:42:05</Criacao>
	<DataDeVencimento>2023-05-23T10:42:05</DataDeVencimento>
	<ValidadeAposVencimento>3</ValidadeAposVencimento>
</Calendario>

• Legenda:
  • A tag <Criacao> é a data e hora da criação do PIX. O valor padrão é DATA e HORA atual;
  • A tag <Expiracao> é o tempo em segundos para expirar a cobrança PIX. O valor padrão é 86400 (24 horas);
  • A tag <DataDeVencimento> é a data de vencimento do PIX. Logo você pode escolher se informa o tempo de expiração ou a data de vencimento;
  • A tag <ValidadeAposVencimento> é o número de dias que a cobrança ainda poderá ser paga após o vencimento. Informar apenas se a <DataDeVencimento> existir no XML.

O grupo de tag <QRCodeConfig> é opcional no XML. Quando não informado, receberá valores padrões:

<QRCodeConfig>
	<Width>512</Width>
	<Height>512</Height>
	<Quality>100</Quality>
	<ImageFormat>2</ImageFormat>
</QRCodeConfig>

• Legenda:
  • A tag <Width> é a largura da imagem do QRCode. O valor padrão é 512 mega pixels;
  • A tag <Height> é a altura da imagem do QRCode. O valor padrão é 512 mega pixels;
  • A tag <Quality> é a qualidade da imagem gerada do QRCode (1 a 100). O valor padrão é 100;
  • A tag <ImagemFormat> é o formato da imagem do QRCode. Aceita 4 valores:
    • 0 = GIF;
    • 1 = JPEG;
    • 2 = PNG (valor padrão);
    • 3 = WEBP.

O grupo de tag <Devedor> é opcional no XML. Esse grupo não receberá valores padrões:

<Devedor>
	<Nome>Devedor de teste</Nome>
	<Inscricao>00000000000</Inscricao>
	<CEP>87700000</CEP>
	<Logradouro>Rua sao joao do joao, 111, Jardim teste</Logradouro>
	<Cidade>Paranavaí</Cidade>
	<UF>PR</UF>
</Devedor>

• Legenda:
  • A tag <Inscricao> é o CPF ou CNPJ do devedor;
  • As outras informações não precisam de legenda.

A tag <UseHomologServer> é opcional no XML. 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.

		....
		....
		<Cidade>Paranavaí</Cidade>
		<UF>PR</UF>
	</Devedor>
	<UseHomologServer>true</UseHomologServer>
</PIXCobrancaCreateRequest>

• Legenda:
  • A tag <UseHomologServer> tem o valor padrão false.

---

Estrutura mínima para utilizar o serviço

<?xml version="1.0" encoding="utf-8"?>
<PIXCobrancaCreateRequest versao="1.00">
	<SolicitacaoPagador>Prestação de serviços em software</SolicitacaoPagador>
	<TipoCobranca>0</TipoCobranca>
	<Valor>1.00</Valor>
	<Chave>+5544999999999</Chave>
	<TxId>12345678901234567890123456789012345</TxId>
	<GerarQRCode>true</GerarQRCode>
	<Beneficiario>
		<Inscricao>11222333000122</Inscricao>
		<Nome>Empresa Teste</Nome>
		<Conta>
			<Agencia>1111</Agencia>
			<Numero>1111111</Numero>
			<Banco>756</Banco>
		</Conta>
	</Beneficiario>
</PIXCobrancaCreateRequest>

---

XML de retorno do envio: O que fazer?

Para verificar se o banco ativou a cobrança e ter a chave PIX para pagamento, você deve utilizar as informações no XML de retorno. Esse XML será gerado na pasta de retorno com o nome a seguir:

0000000000000-ret-PIXCobCreate.xml

E sua estrutura é a seguinte:

<?xml version="1.0" encoding="utf-8"?>
<PIXCobrancaCreateResponse>
	<Status>0</Status>
	<Motivo>PIX Ativo (Cobrança gerada)</Motivo>
	<PixCopiaECola>11111111111111111111br.gov.bcb.pix1111pix.xxxxxx.com.br/qr/xxxxxxx/v2/cobv/11111111-1111-1111-1111-1111111111111111111111111111111111111XXXXXXX XX XXXXXXXXXNao_informado22222222***2222222E</PixCopiaECola>
	<ImageQRCode>d:\testenfe\Retorno\20230523T103002-ret-PIXCobCreate.png</ImageQRCode>
</PIXCobrancaCreateResponse>

• Legenda:
  • A tag <Status> é o status do PIX tendo os valores:
    • 0 = Ativo (PIX gerado);
    • 1 = Concluído (Já foi pago);
    • 2 = Removido pelo usuário recebedor;
    • 3 = Removido pelo PSP;
    • 999 = Exceção/Erro.
  • A tag <Motivo> é a descrição do status;
  • A tag <PixCopiaECola> é a string do PIX Copia e Cola para o devedor pagar por este formato;
  • A tag <ImageQRCode> é o caminho onde foi gravado a imagem do QRCode do PIX para o devedor pagar por este formato.

2ª etapa: Consultar a cobrança para verificar o recebimento

Para verificar o recebimento, você deve fazer a consulta do conteúdo da tag <TxId> criada no tópico Informações inicias do XML de envio. Para fazer o envio dessa consulta, basta gerar o arquivo na pasta de envio com o nome e formato a seguir:

0000000000000-PIXGet.xml

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

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

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

ou

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

---

Estrutura do XML de consulta

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

Informações iniciais

<PIXGetRequest versao="1.00">
	<StartDate>2023-05-23T10:42:05</StartDate>
	<EndDate>2023-05-23T10:42:05</EndDate>
	<TxId>12345678901234567890123456anvfrg</TxId>
	.....
	.....

• Legenda:
  • A tag <StarDate> é a data inicial do período da consulta;
  • A tag <EndDate> é a data final do período da consulta;
  • A tag <TxId> é o conteúdo que foi criado no XML de envio. É o identificador do PIX para consultar a situação e ver se foi recebido ou não.

---

Grupo obrigatório

O grupo Beneficiário é obrigatório no XML, sendo definido após a tag <TxId>:

<Beneficiario>
	<Inscricao>11222333000122</Inscricao>
	<Nome>Empresa Teste</Nome>
	<Conta>
		<Agencia>1111</Agencia>
		<Numero>1111111</Numero>
		<Banco>756</Banco>
	</Conta>
</Beneficiario>

• Legenda:
  • A tag <Inscricao> é a informação do titular da conta do recebedor do PIX sendo CPF ou CNPJ;
  • A tag <Nome> é o nome do titular da conta do recebedor do PIX;
  • O grupo <Conta> terá as informações da conta que vai receber o PIX:
    • A tag <Agencia> é o número da agência da conta;
    • A tag <Numero> é o número da conta;
    • A tag <Banco> é o código do banco do recebedor: 756 (Sicoob), 748 (Sicredi), 33 (Santander) e assim por diante.
      • Observação: Temos o banco Sicoob, Banco do Brasil e Bradesco implementados para PIX. Para saber mais, entre em contato com a Unimake Software.

---

A tag <UseHomologServer> é opcional no XML. 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.

			....
			....
			<Numero>1111111</Numero>
			<Banco>756</Banco>
		</Conta>
	</Beneficiario>
	<UseHomologServer>true</UseHomologServer>
</PIXGetRequest>

• Legenda:
  • A tag <UseHomologServer> tem o valor padrão false.

---

Estrutura mínima para utilizar o serviço

<?xml version="1.0" encoding="utf-8"?>
<PIXGetRequest versao="1.00">
	<StartDate>2023-05-23T10:42:05</StartDate>
	<EndDate>2023-05-23T10:42:05</EndDate>
	<TxId>12345678901234567890123456anvfrg</TxId>
	<Beneficiario>
		<Inscricao>37765786000148</Inscricao>
		<Nome>Dream Solutions</Nome>
		<Conta>
			<Agencia>1111</Agencia>
			<Numero>1111111</Numero>
			<Banco>756</Banco>
		</Conta>
	</Beneficiario>
</PIXGetRequest>

---

XML de retorno da consulta: O que fazer?

Para verificar se o devedor pagou ou não a cobrança PIX, você deve utilizar as informações no XML de retorno. Esse XML será gerado na pasta de retorno com o nome a seguir:

0000000000000-ret-PIXGet.xml

E sua estrutura é a seguinte:

<?xml version="1.0" encoding="utf-8"?>
<PIXGetResponse>
	<Status>1</Status>
	<Motivo>Movimento PIX foi localizado.</Motivo>
	<TxId>12345678901234567890123456</TxId>
	<Valor>0.00</Valor>
	<Horario>2023-05-23T10:42:05</Horario>
	<Pagador>
		<Nome>Teste nome pagador</Nome>
		<Inscricao>12345678901234</Inscricao>
	</Pagador>
</PIXGetResponse>

• Legenda:
  • A tag <Status> é o status do PIX podendo conter os valores:
    • 1 = Movimento PIX foi localizado.;
    • 2 = Nenhum Movimento PIX foi localizado.;
    • 999 = Exceção/Erro.
  • A tag <Descricao> é a descrição do status;
  • A tag <TxId> é o identificador do PIX que está sendo consultado;
  • A tag <Valor> é o valor do PIX;
  • A tag <Horario> é a data e hora que o PIX foi processado no PSP;
  • Grupo <Pagador> são as informações do pagador:
    • A tag <Nome> é o nome do pagador;
    • A tag <Inscricao> é o CPF ou CNPJ do pagador.

Veja também

• O que é o e-Bank PIX?
• Como configurar o UniNFe para utilizar o e-Bank PIX?