Passar para o conteúdo principal

Gerando, consultando ou cancelando um Pix via API

Neste artigo, descubra como utilizar as APIs do Omie para realizar operações com Pix.

Luis Felipe avatar
Escrito por Luis Felipe
Atualizado há mais de 3 semanas

As APIs do Omie oferecem possibilitam integrações com diversos sistemas, permitindo maximizar a eficiência e o potencial do seu ERP.
​
Neste artigo, vamos aprofundar o uso das APIs para realizar operações Pix de maneira ágil e segura, demonstrando como essas integrações podem otimizar suas transações financeiras. 🚀

📣 Importante

Os métodos GerarPix e GerarQrCodePix devem ser utilizados exclusivamente com a Omie.CASH.
​
Sendo que o método GerarQrCodePix está disponível apenas para a Omie.CASH Conta Completa.

Tópicos do Artigo:

Informações importantes

Antes de iniciar seus testes com a nossa API, é fundamental conhecer alguns processos básicos:

  • ✅ Acessando a documentação: consulte nossa documentação oficial para entender os endpoints disponíveis e seus respectivos parâmetros.

  • ⚙️ Características e Recomendações: fique por dentro das melhores práticas para otimizar sua experiência com a API da Omie.
    ​

  • 🔐 Login no Portal: para testar suas requisições no Portal do Desenvolvedor é necessário fazer login na plataforma com o mesmo e-mail e senha que você já usa no ERP. Fácil, né? 😉
    ​

  • 🧪 Aplicativo Teste: aprenda a criar um Aplicativo Teste gratuito e descubra, na prática, como utilizar nossas APIs e aproveitar ao máximo os nossos recursos.

💡 Dica Omie: Você pode testar nossas APIs diretamente no nosso Portal do Desenvolvedor. Além disso, ferramentas como Postman, Insomnia e ThunderClient (extensão do VS Code) também são ótimas opções para realizar testes.

Gerando o Pix

Quando falamos em geração de PIX, podemos trabalhar com dois métodos: GerarPix e GerarQrCodePix.
​

ℹ Para expandir a informação, basta clicar na seta em cima da descrição do campo de interesse.

GerarPix

⚠️ Importante

Este método é específico para utilização com a Omie.CASH Conta Simplificada e Omie.CASH Conta Completa.

1) Com esse método, é possível gerar o Pix para uma Conta a Receber já existente, ou, se nenhum dado do Cliente ou da Conta a Receber for informado, uma nova Conta a Receber será criada.

Neste exemplo, vamos gerar um Pix vinculando a Conta a Receber já existente no Omie:

{
    "call": "GerarPix",
    "app_key": "XXXXXXXXXXXXX",
    "app_secret": "XXXXXXXXXXXXXXXXX",
    "param": [
        {
            "cCodIntPix": "1670867357",
            "nCodTitulo": 1262961171
        }
    ]
}

💡 ao informar tag "nCodTitulo", não é necessário adicionar outra tag de valor ou dados do cliente, pois a requisição utilizará todas as informações da Conta a Receber.

2) A response retornará todos os dados do Pix: 

{
    "nIdPix": 1262964224,
    "cCodIntPix": "1670867357",
    "cUrlPix": "XXXXXXXXXXXXXXXXXX",
    "cQrCode": "XXXXXXXXXXXX",
    "cCopiaCola": "XXXXXXXXXXXXXXXXXX",
    "cCodStatus": "0",
    "cDescStatus": "PIX gerado com sucesso!"
}

💡 Dica

No método GerarPix, é possível enviar uma URL de Callback no parâmetro 'cUrlNotif'.

Com isso, quando o Pix for pago, enviaremos uma notificação para esta URL com o seguinte formato:
​

"cCodIntPix": 12345
"cStatus": "LIQUIDADO"
"nIdPix": XXXXXX
"vValor": 1.00

GerarQrCodePix

⚠️ Importante

Este método é específico para utilização com a Omie.CASH Conta Completa.

1) Nesse método, não é possível vincular uma Conta a Receber existente.

Ou seja, ele deve ser usado quando for necessário emitir uma cobrança por QR Code, mas, sem um cliente ou outro dado definido que não seja o valor.

Veja um exemplo de requisição:

{
    "call": "GerarQrCodePix",
    "app_key": "XXXXXXXXXXXXXXXX",
    "app_secret": "XXXXXXXXXXXXXXXXXXXX",
    "param": [
        {
            "vValor": 1.74
        }
    ]
}

📣 Lembrando que quando a tag "nIdConta" não é preenchida, o sistema assumirá de forma automática que a conta a ser utilizada será a Omie.CASH.

2) Esse método não cadastra a Conta a Receber. Por isso, quando o cliente pagar o QR Code, será registrado automaticamente um lançamento direto no Extrato da Conta Corrente, já conciliado:

📣 Dicas Importantes

  • Quando a tag "cCodStatus" apresenta '0', significa que a solicitação foi executada com sucesso.
    ​
    Do contrário, se ocorrer algum erro durante o processamento da solicitação, será descrito na tag 'cDesStatus'.
    ​

  • Caso queira gerar um Pix cadastrando uma nova Conta a Receber, pode-se usar esse exemplo de requisição: 

{
    "call": "GerarPix",
    "app_key": "XXXXXXXXXXXXX",
    "app_secret": "XXXXXXXXXXXXX",
    "param": [
        {
            "cCodIntPix": "1670867357",
            "vValor": 10.0,
            "nIdConta": 23124,
            "nIdCliente" OU "cCnpjCpf": 1201934
        }
    ]
}

Lembrando: quando as tags 'cIdCliente' e cCnpjCpf' não são informadas, o sistema assumirá que o PIX foi realizado para um cliente consumidor padrão.

Caso não exista um cliente consumidor cadastrado, o mesmo será cadastrado automaticamente.

Listando Pix

Para listar os dados de vários Pix ao mesmo tempo, podemos trabalhar com os seguintes métodos: ListarPix e ListarStatusPix.

Ambos utilizam a mesma estrutura na requisição, porém, os retornos serão diferentes:

 {
    "call": "ListarStatusPix",
    "app_key": "XXXXXXXXXX",
    "app_secret": "XXXXXXXXXXXXX",
    "param": [
        {
            "nPagina": 1,
            "nRegPorPagina": 200
        }
    ]
}

ℹ Para expandir a informação, basta clicar na seta em cima da descrição do campo de interesse.

ListarPix

Traz um retorno detalhado da listagem de PIX, com o link de acesso na tag "cUrlPix" e código para pagamento na tag "cCopiaCola".

Além disso, traz as datas de vencimento e emissão:

{
            "cCodIntPix": "",
            "cCopiaCola": "XXXXXXXXXX",
            "cStatus": "",
            "cUrlPix": "XXXXXXXXXX",
            "dEmissao": "10/02/2023",
            "dVencimento": "11/02/2023",
            "nIdPix": 548097326,
            "vValor": 10
        }

ListarStatusPix

Neste método, o retorno é simplificado, pois, o objetivo é exibir o status atual de um Pix gerado:

{
            "cCodIntPix": "",
            "cStatus": "REGISTRADO",
            "nIdPix": 1171377772,
            "vValor": 10
        }

Obtendo dados de um Pix

Para obter os detalhes de um Pix específico, podemos trabalhar com os seguintes métodos: ObterPix e ObterStatusPix.

Ambos utilizam a mesma estrutura na requisição, porém, os retornos serão diferentes:

{
    "call": "",
    "app_key": "XXXXXXXXXX",
    "app_secret": "XXXXXXXXXX",
    "param": [
        {
            "nIdPix": 1171362012
        }
    ]
}

ℹ Para expandir a informação, basta clicar na seta em cima da descrição do campo de interesse.

ObterPix

Neste método, são retornados os dados completos do Pix cadastrado:

{
    "nIdPix": 1175969877,
    "cCodIntPix": "",
    "vValor": 5.5,
    "dEmissao": "24/11/2022",
    "dVencimento": "25/11/2022",
    "cUrlPix": "XXXXXXXXXXXXXXXXX",
    "cQrCode": "XXXXXXXXXXXXXXXXX",
    "cCopiaCola": "XXXXXXXXXXXXXXXXX",
    "cStatus": "REGISTRADO",
    "cInfo": null
}

ObterStatusPix

Este método possibilita visualizar de forma simplificada, o status atual de um Pix gerado:

{
    "nIdPix": 1175969877,
    "cCodIntPix": "",
    "vValor": 5.5,
    "cStatus": "REGISTRADO"
}

​

Cancelando um Pix

⚠️ Importante

Ao enviar a requisição para cancelar o Pix, por padrão, a Conta a Receber também será excluída.
​
Caso não queira que isso aconteça, é necessário enviar a tag "lDel", conforme o exemplo a seguir.

Se você precisa cancelar um Pix gerado anteriormente, também é possível fazer através de nossas APIs. Para isso, utilizaremos o método CancelarPix.

ℹ Para expandir a informação, basta clicar na seta em cima da descrição do campo de interesse.

Caso queira excluir também a Conta a Receber

Não é necessário o envio da tag "lDel", pois o valor dela por padrão é "True"

{
    "call": "CancelarPix",
    "app_key": "XXXXXXXXXXXX",
    "app_secret": "XXXXXXXXXXXX",
    "param": [
        {
            "nIdPix": 1240017623
        }
    ]
}

Caso não queira excluir a Conta a Receber

Deve ser enviada a tag "lDel" com o valor False, conforme exemplo abaixo:

{
    "call": "CancelarPix",
    "app_key": "XXXXXXXXXXXX",
    "app_secret": "XXXXXXXXXXXX",
    "param": [
        {
            "nIdPix": 1240017623, 
            "lDel": "F"
        }
    ]
}

📚 Artigos Relacionados

Respondeu à sua pergunta?