Passar para o conteúdo principal
Todas as coleçõesAPIs e WebhooksExemplos de API
Gerando, Consultando ou Cancelando um Pix via API
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 2 meses

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. 🚀

Tópicos do Artigo:


Gerando o Pix

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

Abaixo, vamos mostrar em detalhes cada um deles, basta clicar no botão "▶️" para expandir a visualização.

GerarPix

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
}
]
}

Como informamos a tag "nCodTitulo" não é necessário informar nenhuma outra tag de valor ou dados do cliente, pois ele vai puxar todas as informações da conta a receber!

A response, virá com 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

Nesse método, não é possível vincular uma Conta a Receber existente. Ou seja, ele deve ser usado quando for necessário cobrar por QR Code, mas, sem um cliente ou outro dado definido que não seja o valor.

Um exemplo de requisição que pode ser enviado é:

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

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

Esse método em específico não cria a Conta a Receber! Por isso, quando o cliente pagar o QR Code, será criado automaticamente um lançamento direto no Extrato da Conta Corrente, já conciliado:

📣 Dicas Importantes

  • A tag "cCodStatus" quando 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 criando 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á criado 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 visualizar o exemplo de resposta de API para cada um dos métodos, clique no botão "▶️" sobre a opção 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
}
]
}

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

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.

⚠️ Importante

Ao enviarmos 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.

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?