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:
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.
🔑 Chaves de Integração da API: Saiba como obter e utilizar suas credenciais de acesso para autenticar as requisições.
⚙️ 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
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
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 expandir a informação, basta clicar na seta em cima da descrição do campo de interesse.
ListarPix
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
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
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
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 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.
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
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
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
