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

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