Manuais:UniNFe/EnviandoXMLPIX

De unimake
Revisão de 14h25min de 26 de junho de 2023 por Wesley (discussão | contribs) (→‎Grupo obrigatório)
Ir para: navegação, pesquisa

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.

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.

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 e Bradesco implementados para PIX. Para solicitar um novo banco, entre em contato com a Unimake.

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>Devedor efetuou o PIX.</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 = Devedor já efetuou o pagamento;
      • 2 = Devedor não efetuou o pagamento;
      • 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

Disponível em "http://wiki.unimake.com.br/index.php?title=Manuais:UniNFe/EnviandoXMLPIX&oldid=5207"