Integração F360 com outras plataformas (Webhooks)

Os Webhooks permitem que sistemas externos enviem notificações via HTTP em tempo real para o F360 Finanças. Exemplos de uso incluem o registro automático de vendas, a entrada de cupons fiscais, entre outros.

Isso elimina a necessidade de inserir informações manualmente, bastando uma chamada de Webhook para registrar os dados e trazer mais agilidade ao processo de integração.

Primeiros Passos

Para começar a integração, você (o parceiro integrador) deve seguir estes passos:

1. Entre em contato com o seu cliente (o usuário da plataforma F360 Finanças).
2. Solicite a ele a URL de Webhook específica para a sua integração.
3. O cliente irá gerar essa URL dentro da plataforma F360 Finanças e fornecê-la a você.

Esse processo é essencial para mantermos a segurança e identificarmos corretamente cada parceiro. O cliente pode consultar as instruções para gerar essa URL em nossa Documentação Técnica interna.

Estrutura do Endpoint

Foi desenvolvido um padrão de endpoint para todos os fornecedores de dados que desejam enviar informações via Webhook. Segue um exemplo de como é a URL do serviço:

https://webhook.f360.com.br/{{identificador-unico-do-servico}}/{{servico-consumido}}

• identificador-unico-do-servico: Um ID exclusivo gerado pelo F360 e fornecido pelo cliente a você (conforme os "Primeiros Passos").
• servico-consumido: O serviço específico para o qual a request será direcionada (ex: f360-cupom-fiscal).

Consulta de disponibilidade de serviço

É possível realizar uma consulta de status para verificar se um serviço de Webhook específico está disponível. Para isso, utilize a URL abaixo (substituindo o identificador):

https://webhook.f360.com.br/{{identificador-unico-do-servico}}/f360-cupom-fiscal

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

A request deve ser enviada via HTTP POST e é obrigatório que o corpo da requisição (body) seja um JSON válido, contendo todos os dados que descrevem o cupom fiscal ou o período de vendas.

Exemplo de request:

curl --location --request POST 'https://webhook.f360.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.4,
          "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.5,
          "Bandeira": "",
          "Autorizacao": "",
          "NSU": "789654",
          "QtdParcelas": "1",
          "Vencimento": "2022-05-27T15:08:26"
        }
      ],
      "Data": "2022-05-26T15:08:26",
      "VendaCancelada": true,
      "ValorFrete": 10.21
    }
  ]
}'

Informações Importantes: 

• Por se tratar de uma requisição assíncrona, a resposta da API (ver seção "Resposta") confirma apenas o recebimento dos dados, e não o seu processamento final. Um status HTTP 200 (Success) não garante que a mensagem foi validada e inserida com sucesso na plataforma. Você deve sempre verificar o resultado na tela de "Upload de Arquivos" do F360 Finanças. O tempo entre o envio da informação e o processamento completo pode levar até 1 hora.
• Caso o sistema não localize o CNPJEmitente cadastrado na plataforma, a mensagem será descartada.
• Apesar de aceitarmos mais de um cupom na mesma request, é fundamental que o CNPJEmitente e o dia das vendas (campo Data) sejam únicos dentro da mesma request. A hora da venda (que complementa o campo Data) pode ser diferente entre os cupons.
• Lançamentos que pertencem ao mesmo cupom fiscal (ex: múltiplos meios de pagamento) devem ser enviados em uma única request, dentro do mesmo objeto de cupom. Enviar o mesmo cupom em requests separadas fará com que sejam interpretados como duplicados, resultando no descarte das vendas subsequentes.

Detalhamento dos Campos (Cupons): 

Campos marcados com * são obrigatórios.

• *NumeroCupom (string): Número do cupom da venda.
• *CNPJEmitente (string): Número do CNPJ da loja (sem pontos ou traços) cadastrado no F360 Finanças.
• Cliente (object): Objeto opcional contendo Nome e Cpf do cliente do cupom.
• *Data (string, formato: "yyyy-MM-ddTHH:mm:ss"): Data e hora em que a venda foi realizada.
• VendaCancelada (bool): Campo booleano (true/false). Se não for preenchido, será considerado false. Se true, o sistema buscará a venda e tentará cancelá-la. Se a venda não for encontrada, nada será feito.
• ValorFrete (double, '0.00'): Campo opcional com o valor do frete relacionado à venda.
• *MeioPagamento (array): Array de objetos detalhando as formas de pagamento do cupom.
  • *FormaPagamento (string): Forma como o pagamento foi efetuado (ex: "Dinheiro", "Cartao Debito").
  • *Valor (double, ‘0.00’): Valor líquido pago nesta forma de pagamento. (Ex: Em pagamentos em dinheiro, este deve ser o valor final, já descontado o troco, se houver).
  • Bandeira (string): Bandeira do cartão utilizado. (Ver ‘Tabela 1’).
  • Autorizacao (string): Código de autorização do pagamento, gerado pela adquirente.
  • NSU (string): Código de rastreio (NSU) do pagamento, gerado pela adquirente.
  • QtdParcelas (string): Quantidade de parcelas. Se omitido, o sistema considerará "1".
  • Vencimento (string, formato: "yyyy-MM-ddTHH:mm:ss"): Data de vencimento do pagamento.
  • Parcelas (array): Objeto opcional para detalhar cada parcela separadamente. Se não for preenchido, o sistema calculará o parcelamento automaticamente com base nos campos Valor, Vencimento e QtdParcelas.
    • DataDeApresentacao (string, formato: "yyyy-MM-dd"): Data de apresentação da parcela.
    • Valor (double, ‘0.00’): Valor da parcela.
    • NumeroDaParcela (string): Número da parcela (ex: "1", "2").
    • Vencimento (string, formato: "yyyy-MM-ddTHH:mm:ss"): Data de vencimento da parcela.

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

A request deve ser enviada via HTTP POST com um JSON válido contendo os dados dos títulos. Este Webhook pode ser usado tanto para Contas a Pagar quanto para Contas a Receber.

Importante: Esta operação pode ser utilizada apenas para inserir novos registros. Não é possível realizar operações de "alteração" ou "exclusão" via Webhook.

Informações como Plano de Contas e Centro de Custo podem ser consultadas em nossa API pública: F360 Finanças

Exemplo de request:

curl --location --globoff 'https://webhook.f360.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",
      "detalhesClienteFornecedor": {
        "nome": "João da Silva",
        "cpfCnpj": "00000000000"
      },
      "emissao": "2025-01-14",
      "valor": 150,
      "tipoDocumento": "boleto",
      "contaBancaria": "nome da conta bancária",
      "meioPagamento": "boleto",
      "historico": "",
      "remessaCnab": false,
      "receitaDeCaixa": false,
      "parcelas": [
        {
          "vencimento": "2025-02-14",
          "valor": 150,
          "numeroParcela": 1,
          "liquidacao": null,
          "codigoDeBarras": null
        }
      ],
      "rateio": [
        {
          "competencia": "02-2025",
          "centroDeCusto": "centro de custo",
          "planoDeContas": "vendas de mercadorias",
          "numeroParcela": 1,
          "valor": 150
        }
      ]
    }
  ]
}'

Detalhamento dos campos

Campos marcados com * são obrigatórios.

Objeto Titulo

• *cnpj (string) : CNPJ da empresa (com formatação).
• *tipoTitulo (string): Deve ser preenchido com uma das opções (exatamente como abaixo):
  • pagar
  • receber
• *numeroTitulo (string) : Número de identificação do título.
• *clienteFornecedor (string) : CPF/CNPJ ou nome do fornecedor (se pagar) ou cliente (se receber). Se a pessoa não existir no sistema, ela será criada usando este campo como chave.
• detalhesClienteFornecedor (object): Objeto opcional. Se preenchido, seus dados serão usados para cadastrar a pessoa (cliente/fornecedor) caso ela não exista. Este método utiliza nome e cpfCnpj em conjunto.
  • nome (string) : Nome do cliente/fornecedor.
  • cpfCnpj (string) : CPF ou CNPJ do cliente/fornecedor.
• *emissao (string, formato "yyyy-MM-dd") : Data de emissão do título.
• *valor (double, formato "0.00") : Valor total do título.
• *tipoDocumento (string) : Deve ser preenchido com uma das opções (exatamente como abaixo):
  • duplicata
  • boleto
  • nota fiscal
  • nota de débito
  • conta de consumo
  • cupom fiscal
  • outros
  • previsão
• *contaBancaria (string) : Nome de uma conta bancária já cadastrada no sistema.
• *meioPagamento (string) : Deve ser preenchido com uma das opções (exatamente como abaixo):
  • boleto
  • dinheiro
  • cheque
  • dda
  • doc/ted
  • depósito em conta
  • transferência bancária
  • débito automático
  • cartão de crédito / débito
  • outros
• historico (string) : Descrição opcional que pode ser adicionada ao título.
• remessaCnab (boolean) : Opcional. Se true, indica que o título foi gerado pelo CNAB. Padrão: false.
• receitaDeCaixa (boolean) : Opcional. Se true, o título será exibido na tela de fechamento de caixa. Padrão: false.
• *parcelas (array de objetos) : Detalhes de cada parcela. (Ver "Objeto Parcela").
• *rateio (array de objetos) : Detalhes do rateio (Centro de Custo / Plano de Contas). (Ver "Objeto Rateio").

Objeto Parcela

• *vencimento (string, formato "yyyy-MM-dd") : Data de vencimento da parcela.
• *valor (double, formato "0.00") : Valor da parcela.
• *numeroParcela (short) : Número da parcela (ex: 1, 2, 3).
• liquidacao (string, formato "yyyy-MM-dd") : Opcional. Se preenchido, a parcela será criada como liquidada nesta data. Se null ou omitido, será considerada "não liquidada".
• codigoDeBarras (string) : Opcional.

Objeto Rateio

• *competencia (string, formato "MM-yyyy") : Mês e ano de competência do rateio (ex: "02-2025").
• centroDeCusto (string) : Nome do centro de custo cadastrado no sistema. Se omitido, será utilizado o centro de custo padrão.
• *planoDeContas (string) : Nome do plano de contas cadastrado no sistema.
• *numeroParcela (short) : O número da parcela (numeroParcela do Objeto Parcela) à qual este rateio se refere.
• *valor (double, formato "0.00") : Valor do rateio.

Informações Importantes:

• Por se tratar de uma requisição assíncrona, a resposta da API (ver seção "Resposta") confirma apenas o recebimento dos dados, e não o seu processamento final. Um status HTTP 200 (Success) não garante que a mensagem foi validada e inserida com sucesso na plataforma. Você deve sempre verificar o resultado na tela de "Upload de Arquivos" do F360 Finanças. O tempo entre o envio da informação e o processamento completo pode levar até 1 hora.
• Todo título deve ter pelo menos uma parcela e um rateio.
• O numeroParcela do rateio deve corresponder a uma parcela existente no mesmo título.
• A soma do valor de todas as parcelas deve ser igual ao valor total do título.
• A soma dos valor dos rateios de uma mesma parcela deve ser igual ao valor total daquela parcela.

Resposta da API

O Webhook opera de forma assíncrona. A resposta da API indica apenas o status do recebimento da mensagem, não o status do processamento.

Exemplo HTTP 200 (Sucesso no Recebimento)

A mensagem foi recebida com sucesso. O rastreioId pode ser usado para consultar o status do processamento (via suporte ou plataforma).

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

Exemplo HTTP 500 (Erro no Recebimento)

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

Tabelas

Gostou desse artigo? Tem alguma dúvida ou sugestão? Por favor, entre em contato com a gente pelo e-mail suporte@f360.com.br e compartilhe suas experiências. Sua opinião é muito importante para nós.

Um grande abraço,

Equipe F360°