API: contas a pagar

Endpoints REST para listar e criar contas a pagar. Requer módulo Financeiro habilitado (beta).

Módulo em beta

Disponível para empresas com a feature module.financial habilitada. Sem ela, a API responde 403 Finance module not enabled.

Autenticação

Todos os endpoints exigem o header X-API-Key com sua API key. Gere a sua em Integrações → API Keys. Veja Autenticação.

GET/api/public/v1/finance/payablesAuth: API key

Lista as contas a pagar da empresa autenticada, ordenadas por vencimento ascendente. Escopo de API key necessário: read.

Query params

Campo	Tipo	Descrição
limit	integer	Máximo de registros (1–200). Default: 50.
status	enum(aberto,parcial,pago,vencido,cancelado)	Filtra por status.
date_from	ISO date	Vencimento >= data (YYYY-MM-DD).
date_to	ISO date	Vencimento <= data (YYYY-MM-DD).

bash

curl "https://freteflow.log.br/api/public/v1/finance/payables?status=aberto&limit=50" \
  -H "X-API-Key: ff_live_..."

Resposta

json

{
  "data": [
    {
      "id": "8d3...",
      "numero": "NF-1234",
      "descricao": "Combustível semana 23",
      "supplier_partner_id": "p_...",
      "supplier_name_snapshot": "Posto Estrada Ltda",
      "valor_centavos": 250000,
      "saldo_centavos": 250000,
      "pago_centavos": 0,
      "emissao_at": "2026-06-01",
      "vencimento_at": "2026-06-15",
      "pago_em": null,
      "parcela_num": 1,
      "parcela_total": 1,
      "status": "aberto",
      "created_at": "2026-06-01T13:45:00Z"
    }
  ]
}

POST/api/public/v1/finance/payablesAuth: API key

Cria um título no contas a pagar. Quando parcela_total > 1, gera N títulos com vencimento mensal a partir de vencimento_at. Escopo necessário: write.

Body

Campo	Tipo	Descrição
descricaoreq	string	Descrição do título (1–500 caracteres).
numero	string	Número do documento.
serie	string	Série do documento.
valor_centavosreq	integer	Valor total em centavos. Em parcelamento, é dividido por parcela_total.
emissao_at	ISO date	Data de emissão. Default: hoje.
vencimento_atreq	ISO date	Vencimento da 1ª parcela (YYYY-MM-DD).
parcela_total	integer	Quantidade de parcelas (1–120). Default: 1.
supplier_partner_id	uuid	ID do parceiro fornecedor.
supplier_cpf_cnpj	string	Alternativa ao partner_id — CPF/CNPJ (apenas dígitos ou formatado).
account_code	string	Code da conta contábil (plano de contas).
cost_center_code	string	Code do centro de custo.
freight_id	uuid	Vincula a um frete existente.
vehicle_id	uuid	Vincula a um veículo.
notes	string	Observações livres (até 2000 caracteres).

bash

curl -X POST https://freteflow.log.br/api/public/v1/finance/payables \
  -H "X-API-Key: ff_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "descricao": "Manutenção Scania ABC1D23",
    "supplier_cpf_cnpj": "12345678000199",
    "valor_centavos": 360000,
    "vencimento_at": "2026-07-10",
    "parcela_total": 3,
    "account_code": "4.02.01",
    "cost_center_code": "VEIC-ABC1D23"
  }'

Resposta

json

{ "ids": ["8d3...", "8d4...", "8d5..."] }

Códigos de erro específicos

Campo	Tipo	Descrição
400	Invalid body	Payload não passou na validação Zod.
401	Unauthorized	API key ausente ou inválida.
403	Finance module not enabled	Empresa não tem o módulo Financeiro habilitado.
413	Body too large	Corpo da requisição excede o limite.