API: faturamento

Envie documentos para faturamento e gere faturas automaticamente. Disponível para empresas com o módulo Faturamento habilitado (beta).

Módulo em beta

O módulo de Faturamento está em testes restritos. Caso receba 403 Billing module not enabled, peça à equipe FreteFlow a habilitação para sua empresa.

Autenticação

Todos os endpoints exigem cabeçalho x-freteflow-key com sua API key. Quando o HMAC estiver ativo, envie também x-freteflow-timestamp (Unix epoch em ms) e x-freteflow-signature (HMAC-SHA256 do corpo bruto, em hex). Veja Autenticação.

POST/api/public/v1/billing/documentsAuth: API key

Cria um documento na caixa de entrada do faturamento. Útil para sistemas que emitem CT-e/NF-e externos.

Body

Campo	Tipo	Descrição
kind	enum(cte,nfe,pdf,xlsx,outro)	Tipo do documento. Default: outro.
customer_cpf_cnpj	string	CNPJ/CPF do cliente (apenas dígitos ou formatado). Resolve para um parceiro cadastrado.
customer_partner_id	uuid	Alternativa ao CNPJ — id direto do parceiro.
freight_id	uuid	Opcional — vincula a um frete existente.
chave	string	Chave do documento (44 dígitos para CT-e/NF-e).
numero	string	Número do documento.
serie	string	Série do documento.
valor_centavos	integer	Valor em centavos. Ex.: R$ 1.234,56 = 123456.
emissao_at	ISO date	Data de emissão (YYYY-MM-DD).
storage_path	string	Caminho no storage (ex.: bucket onde já subiu o XML/PDF).
notes	string	Observações livres.
metadata	object	Dados adicionais arbitrários (chave/valor).

bash

curl -X POST https://freteflow.log.br/api/public/v1/billing/documents \
  -H "x-freteflow-key: ff_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "cte",
    "customer_cpf_cnpj": "12345678000199",
    "chave": "35240612345678000199570010000012341234567890",
    "numero": "1234",
    "serie": "1",
    "valor_centavos": 250000,
    "emissao_at": "2026-05-28"
  }'

GET/api/public/v1/billing/documentsAuth: API key

Lista os documentos da empresa autenticada. Aceita query ?status=pendente|vinculado|faturado|descartado e ?limit= (máx 200).

POST/api/public/v1/billing/invoicesAuth: API key

Gera uma fatura a partir de N documentos pendentes do mesmo cliente. Se emit=true, a fatura já sai emitida e cria automaticamente o título em contas a receber.

Body

Campo	Tipo	Descrição
customer_cpf_cnpj	string	CNPJ/CPF do cliente.
customer_partner_id	uuid	Alternativa ao CNPJ.
document_idsreq	uuid[]	IDs dos documentos a consolidar (1–200). Todos devem estar pendente e pertencer ao mesmo cliente.
vencimento_at	ISO date	Vencimento. Default: hoje + prazo padrão configurado em /faturamento/configuracoes.
condicao_pagamento	string	Condição. Default: condição padrão da empresa.
observacoes	string	Observações que vão para o PDF.
emit	boolean	Se true, emite imediatamente e gera o título a receber. Default: false (rascunho).

bash

curl -X POST https://freteflow.log.br/api/public/v1/billing/invoices \
  -H "x-freteflow-key: ff_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_cpf_cnpj": "12345678000199",
    "document_ids": ["c0a8...","c0a8..."],
    "emit": true
  }'

Resposta

json

{
  "data": {
    "id": "8d3...",
    "numero": "FAT-000123",
    "valor_centavos": 500000,
    "vencimento_at": "2026-06-27",
    "status": "emitida",
    "items_count": 2
  }
}

GET/api/public/v1/billing/invoices/{id}/pdfAuth: API key

Retorna o PDF binário (application/pdf) da fatura. Disponível apenas para faturas emitida, encerrada ou cancelada. O layout respeita a configuração de PDF da empresa e, quando existir, o override do cliente (cores, logo, textos institucionais, colunas visíveis e blocos opcionais). Veja Configuração do PDF da fatura. A configuração é feita exclusivamente pela UI — não há endpoint público para editá-la.

Códigos de erro específicos

Campo	Tipo	Descrição
401	Unauthorized	API key ausente, inválida ou HMAC incorreto.
403	Billing module not enabled	Empresa não tem o módulo Faturamento habilitado.
404	Customer not found	CNPJ/CPF ou partner_id não pertence à empresa.
422	Validation	Documentos não pertencem ao mesmo cliente, não estão pendentes, ou IDs inexistentes.