Integrações do Cielo Conciliador com outras plataformas via webhooks

Os Webhooks permitem o envio de notificações via HTTP em tempo real para o Cielo Conciliador, como, por exemplo, notificações para registrar vendas, entradas de cupons, entre outros. Isso elimina a necessidade de preenchimento manual de certas informações, bastando apenas a chamada do Webhook para inserção dos registros, trazendo agilidade ao processo de integração.

Primeiros Passos

Inicialmente, você deve entrar em contato com o usuário da plataforma Cielo Conciliador e solicitar a URL para a qual as mensagens serão enviadas. Esse processo é importante para garantir a segurança e identificar corretamente cada parceiro.

Na prática, foi desenvolvido um único endpoint para todos os fornecedores de dados que desejam enviar informações via Webhook, onde será possível transmitir todas as informações necessárias. Por isso, as informações abaixo são de extrema importância.

Como criar uma URL para envio de mensagens

1 - Entre na tela de Webservices do Cielo Conciliador.

2 - Clique no botão Criar localizado no canto inferior esquerdo da tela.

3 - Selecione a opção de mensagens que deseja permitir o recebimento, atualmente temos a seguinte opção:

4 - Clique no botão Salvar e aguarde a confirmação da plataforma.

5 - Agora localize a webservice que você acabou de criar, na coluna ‘Outros’ encontra-se a URL para a qual seu fornecedor deverá enviar as mensagens via webhook.

Modelo de endereço disponibilizado:

webhook.exemplo.com.br/identificador-unico-do-servico/servico-consumido

Consulta de Disponibilidade de Serviço

É possível consultar o status de todos os serviços disponíveis utilizando a URL abaixo:

webhook.exemplo.com.br/IDENTIFICADOR-UNICO-DO-SERVICO/f360-cupom-fiscal

Criação de Cupons Fiscais - Webhook F360 (PDV)

A request deve ser enviada por meio de uma solicitação HTTP POST. É obrigatório que o corpo da requisição seja um JSON válido e contenha todos os dados que descrevem o cupom fiscal ou o período de vendas. Abaixo, detalharemos os campos obrigatórios e opcionais desse corpo.

Exemplo de Requisição:

A request deve ser enviada por meio de uma solicitação HTTP POST. É obrigatório que o corpo da requisição seja um JSON válido e contenha todos os dados que descrevem o cupom fiscal ou o período de vendas. Abaixo, detalharemos os campos obrigatórios e opcionais desse corpo.

curl --location --request POST 'https://webhook.exemplo.com.br/identificador-unico-do-servico/f360-cupom-fiscal' \
--header 'Content-Type: application/json' \
--data-raw '{
    "NomeSistema": "Meu PDV",
    "Values": [
        {
            "NumeroCupom": "123456",
            "CNPJEmitente": "01234567000199",
            "Cliente": {
                "Nome": "João da Silva",
                "Cpf": "123.456.789-10"
            },
            "MeioPagamento": [
                {
                    "FormaPagamento": "Dinheiro",
                    "Valor": 71.12,
                    "Bandeira": "",
                    "Autorizacao": "",
                    "NSU": "",
                    "QtdParcelas": "1",
                    "Vencimento": "2022-05-26T15:08:26"
                }
            ],
            "Data": "2022-05-26T15:08:26"
        },
        {
            "NumeroCupom": "123457",
            "CNPJEmitente": "01234567000199",
            "Cliente": {
                "Nome": "Jorge da Silva",
                "Cpf": "456.807.789-10"
            },
            "MeioPagamento": [
                {
                    "FormaPagamento": "Cartao Parcelado",
                    "Valor": 38.40,
                    "Bandeira": "",
                    "Autorizacao": "A25V87",
                    "NSU": "123456",
                    "QtdParcelas": "2",
                    "Parcelas": [
                        {
                            "DataDeApresentacao": "2022-05-26",
                            "Valor": 19.2,
                            "NumeroDaParcela": "1",
                            "Vencimento": "2022-06-26"
                        },
                        {
                            "DataDeApresentacao": "2022-05-26",
                            "Valor": 19.2,
                            "NumeroDaParcela": "2",
                            "Vencimento": "2022-07-26"
                        }
                    ]
                },
                {
                    "FormaPagamento": "Cartao Debito",
                    "Valor": 21.50,
                    "Bandeira": "",
                    "Autorizacao": "",
                    "NSU": "789654",
                    "QtdParcelas": "1",
                    "Vencimento": "2022-05-27T15:08:26"
                }
            ],
            "Data": "2022-05-26T15:08:26",
            "VendaCancelada": true,
            "ValorFrete": 10.21
        }
    ]
}'

Por se tratar de uma requisição assíncrona, não retornamos o status da operação realizada no Cielo Conciliador. Logo, o processamento da informação enviada na requisição deve ser verificado na própria plataforma do Cielo Conciliador. Caso o sistema não localize a ‘CNPJEmitente’ cadastrado, o sistema irá descartar a mensagem.

Atenção: Apesar de aceitarmos mais de um cupom fiscal no mesmo corpo da request, é importante observar que o ‘CNPJEmitente’ e o dia das datas das vendas devem ser únicos dentro da mesma request. Já a informação da hora da venda (que complementa o campo ‘Data’) pode ser diferente dentre os cupons fiscais.

Lançamentos pertencentes ao mesmo cupom fiscal devem ser enviados em uma única request, para evitar que esses registros sejam interpretados como vendas duplicadas, o que resultaria na não inserção dessas vendas.

Detalhamento dos campos

Campos marcados com * são campos obrigatórios, porém o envio das informações adicionais traz benefícios à conciliação e rastreabilidade dos cupons fiscais.

Criação de Títulos (Contas a pagar/receber) - (Webhook F360 - Títulos)

A request deve ser enviada por meio de solicitação HTTP POST e é obrigatório que o corpo da requisição seja um JSON válido, e contenha todos os dados que descrevem os títulos. Detalharemos mais à frente os campos obrigatórios e opcionais desse corpo.

Tanto contas a pagar quanto a receber são tratados como Títulos no sistema, então este webhook pode ser usado para envio de ambos.

Esta operação pode ser utilizada apenas para inserir novos registros. Não é possível realizar operação de “alteração” ou “exclusão” nesta integração.

Algumas informações cadastradas no sistema, como Plano de Contas e Centro de Custo, podem ser consultadas em nossa API pública, cada uma em seu respectivo endpoint, conforme descrito na documentação, disponível no link a seguir: Visão geral do Cielo Conciliador.

Abaixo há um exemplo de requisição para o webhook de títulos. A URL contém campos que variam para cada cadastro do webhook, realizado na tela de webservice. Os campos variáveis estão envolvidos por {}. A URL completa é obtida na tela de webservices, após a criação do webservice deste webhook.

curl --location 'https://webhook.exemplo.com.br/{identificador-unico-do-servico}/f360-{id}-titulos/' \
--header 'Content-Type: application/json' \
--data '{
    "titulos": [
        {
            "cnpj": "00.000.000/0000-00",
            "tipoTitulo": "receber",
            "numeroTitulo": "123456",
            "clienteFornecedor": "João da Silva",
            "emissao": "2023-02-14",
            "valor": 150,
            "tipoDocumento": "boleto",
            "contaBancaria": "nome da conta bancária",
            "meioPagamento": "boleto",
            "historico": "",
            "remessaCnab": false,
            "receitaDeCaixa": false,
            "parcelas": [{
                "vencimento": "2023-03-14",
                "valor": 150,
                "numeroParcela": 1,
                "liquidacao": null,
                "codigoDeBarras": null
            }],
            "rateio": [{
                "competencia": "03-2022",
                "centroDeCusto": "centro de custo",
                "planoDeContas": "vendas de mercadorias",
                "numeroParcela": 1,
                "valor": 150
            }]
        }
    ]
}'

Detalhamento dos campos

Campos marcados com (*) são de preenchimento obrigatório e caso não sejam preenchidos o registro será ignorado.

Objeto Titulo

Objeto Parcela

Objeto Rateio

Regras de Leitura

Resposta

Caso o envio seja bem-sucedido, o status HTTP 200 será retornado com um ID de rastreio do evento. Este ID poderá ser utilizado para consultar o status do processamento da mensagem. Porém, caso algum problema ocorra ao recebermos a mensagem, o status HTTP 500 será retornado.

Exemplo HTTP 200

{
    "rastreioId": "5737a24e-8eef-4090-9c8d-6c168af2c8a4"
}

Exemplo HTTP 500

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
    "title": "An error occurred while processing your request.",
    "status": 500,
    "traceId": "00-92255f294a1a8995227eac28b180a0a7-91d42cfdc65d5e99-00"
}

Tabela 1 - Bandeiras de Cartão

Documentações e tutoriais

Materiais complementares

Contato
GitHub