Faturas

O ciclo completo de uma fatura a partir do seu sistema: rascunho, emissão, envio, recebimento e cancelamento.

Visão geral

Uma fatura nasce como rascunho e só se torna definitiva quando você a emite. Emitir é uma ação explícita e irreversível: consome a timbragem do seu plano quando se aplica (CFDI no México) e dá à fatura o seu número. Criar nunca emite por si só.

A API de faturas está disponível em todos os planos, incluindo o Grátis, com faturas comerciais (pró-forma no México e na Espanha). A emissão fiscal integrada (CFDI no México, e Verifactu na Espanha com o certificado da empresa carregado) exige o Starter ou superior: pedir document_mode: "fiscal" sem esse plano responde 400 invalid_request.

Listar faturas

GET /api/v1/facturas com estes filtros opcionais:

Parâmetro	O que faz
`estado`	`draft`, `open`, `paid`, `void`, `uncollectible` ou `overdue` (em aberto com o vencimento já passado).
`cliente`	Id do cliente.
`desde`, `hasta`	Intervalo pela data de criação, `YYYY-MM-DD`, com os dois extremos incluídos.
`q`	Busca por número, folio fiscal, número do orçamento de origem ou nome do cliente.
`limit`	De 1 a 200; por padrão, 50.
`cursor`	O `next_cursor` da página anterior.

A paginação é por cursor, não por deslocamento: uma fatura nova não move a página que você está lendo.

curl "https://cordhq.app/api/v1/facturas?limit=20" \
     -H "Authorization: Bearer sk_live_tU..."

{
  "data": [
    {
      "id": "f3a1c7e9-2b4d-4f6a-8c0e-5d7b9a1c3e24", "numero": "F-0231", "folio_fiscal": "6F1C2A9E-7B4D-4E6A-8C2F-1D5B9E3A7C40", "cliente": "Aceros del Norte",
      "estado": "open", "estado_fiscal": "issued", "pais": "MX", "tipo": "cfdi_40",
      "moneda": "MXN", "total": 184300, "pagado": 0, "saldo": 184300,
      "vence": "2026-10-15", "vencida": false, "cotizacion_id": "2a9d8e4f-6b1c-4d7a-9e3f-5c8b1a2d4e6f", "creada": "15 sep 2026", "language": "es"
    }
  ],
  "meta": { "next_cursor": null }
}

creada chega como data de exibição (15 sep 2026), não como data ISO; vence vem como YYYY-MM-DD.

Campo	Valores
`estado`	`draft` (rascunho), `open` (emitida e a receber), `paid` (paga), `void` (cancelada) ou `uncollectible` (incobrável).
`estado_fiscal`	`pending`, `issued` (registrada perante o provedor fiscal), `cancelled` ou `error`.
`tipo`	`cfdi_40` (CFDI de receita, México), `cfdi_egreso` (nota de crédito CFDI), `proforma` (documento comercial no México, na Espanha e nos países com fatura autorizada), `commercial_invoice` (fatura comercial), `commercial_credit_note` (nota de crédito comercial), `verifactu_invoice` ou `verifactu_credit_note` (Espanha com Verifactu). Com a emissão perante a autoridade ativa: `arca_invoice` (Argentina), `nfse_invoice` e `nfe_invoice` (Brasil), `sii_invoice` (Chile), `dian_invoice` (Colômbia) e `sunat_invoice` (Peru), com as suas notas de crédito `*_credit_note` e, no Chile, `sii_debit_note`.
`language`	Somente leitura. O idioma em que o cliente recebe a fatura, o PDF, o link e os e-mails dela: `es`, `en`, `pt`, `fr` ou `de`. A fatura o recebe ao ser emitida, do cliente ou, se ele não tiver, da sua organização; uma nota de crédito o herda da fatura dela. `null` em um rascunho.

Criar um rascunho

POST /api/v1/facturas cria um rascunho. Exige uma chave com escrita e aceita Idempotency-Key.

Campo	Obrigatório	Detalhe
`cliente_id`	Sim	Um cliente da sua organização.
`items`	Sim	De 1 a 200 itens. Cada um com `descripcion` e `cantidad`; opcionais `precio_unitario`, `precio_negociado`, `producto_id`, `costo_unitario`, `tax_rate`, `exemption_reason` e, no México, `clave_sat` e `clave_unidad_sat`.
`currency`	Não	Moeda da fatura; por padrão, a da sua conta.
`due_date`	Não	Vencimento em `YYYY-MM-DD`.
`notas`	Não	Até 1000 caracteres.
`iva_incluido`	Não	`true` se os preços já incluem o imposto.
`document_mode`	Não	`commercial` ou `fiscal`. Sem ele, o Cord emite fiscal se o seu plano o incluir e o seu país o tiver habilitado, e comercial nos demais casos. `fiscal` sem o plano ou sem o país habilitado responde `400 invalid_request`.
`fx_buffer_pct`	Não	Cobertura em pontos percentuais sobre a taxa de câmbio de referência quando `currency` difere da sua moeda contábil (`2` = +2%, limite de 25). Por padrão, `0`.
`descuento`	Não	Desconto do documento antes de impostos: `{ "tipo": "porcentaje", "valor": 10 }` ou `{ "tipo": "monto", "valor": 2500 }`. O Cord calcula o valor e o distribui entre os itens. Veja Descontos e cupons.
`cupon`	Não	O código de um cupom da sua conta. Prevalece sobre `descuento`. O uso dele é contado ao emitir a fatura.
`service_date`, `service_date_end`	Não	Data ou período de prestação, `YYYY-MM-DD`. O fim exige o início e não pode ser anterior a ele. Sem ela, a fatura indica que coincide com a data de emissão (obrigatória na Alemanha).
`buyer_reference`	Não	Referência do comprador (BT-10 da fatura eletrônica europeia; na Alemanha, o Leitweg-ID da administração pública). Sem ela, vale a do cliente. Se o endereço eletrônico do cliente for um Leitweg-ID, os dígitos verificadores dele são conferidos e um que não passe responde `400`.
`purchase_order`	Não	Número da ordem de compra do cliente (BT-13).

tax_rate é uma fração (0.16, não 16) e é validada com o seu catálogo de impostos: você não pode declarar um item isento em uma venda tributada. 0 significa isento de propósito; omiti-la usa a alíquota da sua conta. clave_sat e clave_unidad_sat prevalecem sobre os códigos do produto; sem nenhum, o CFDI usa 01010101 e H87. Um código com formato inválido responde 400.

curl -X POST "https://cordhq.app/api/v1/facturas" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: invoice-order-8812" \
     -d '{
       "cliente_id": "9b2e4c6a-8d1f-4a3b-b5c7-0e2d4f6a8c91",
       "currency": "USD",
       "due_date": "2026-10-15",
       "items": [{ "descripcion": "Rebar 3/8\"", "cantidad": 120, "precio_unitario": 4.2, "tax_rate": 0.0825 }]
     }'

{ "data": { "id": "f3a1c7e9-2b4d-4f6a-8c0e-5d7b9a1c3e24" } }

Se a fatura estiver em uma moeda diferente da sua moeda contábil e não for possível obter uma taxa de câmbio verificável, ela responde 503 com code: "fx_unavailable": tente de novo mais tarde, o Cord não inventa uma taxa.

Consultar uma fatura

GET /api/v1/facturas/{id} devolve os campos da listagem mais subtotal, impuestos, moneda_contable, tipo_cambio, total_contable, notas, nota_credito_de, emisor, receptor, descuento, conceptos e pagos.

Campo	Detalhe
`descuento`	`null`, ou `{ tipo, valor, cupon, monto, moneda }`: a definição, o cupom de onde ele saiu e o valor antes de impostos. `subtotal` já é líquido.
`conceptos[].precio_unitario`	Preço unitário líquido, depois do desconto do documento, sem imposto.
`conceptos[].subtotal`	Base líquida do item.
`conceptos[].descuento`	A parte do desconto do documento que coube a esse item; `0` se não houver.
`conceptos[].clave_sat`, `conceptos[].clave_unidad_sat`	México: as chaves do SAT com que o item foi timbrado; `null` fora do México.
`pagos`	Cada pagamento com `monto`, `moneda`, `metodo`, `referencia` e `cuando`. Uma cobrança que pagou várias faturas aparece em cada uma com a parte que coube a ela.

Alterar o status

POST /api/v1/facturas/{id} com action:

`action`	O que faz	Campos
`finalize`	Emite a fatura. Irreversível; timbra o CFDI no México quando se aplica.	—
`send`	Envia o e-mail da fatura com o PDF ao cliente, no idioma da fatura (`language`). Exige uma fatura emitida e um cliente com e-mail.	—
`payment`	Registra um pagamento, total ou parcial.	`monto`, `moneda`, `metodo` (por padrão, `manual`), `referencia`
`void`	Cancela a fatura.	`motivo`
`credit_note`	Emite uma nota de crédito sobre a fatura.	`monto` (opcional; sem ele, pelo total), `motivo`

payment responde com o valor pago, o saldo e o status resultante. Um pagamento que quita a fatura dispara o evento invoice.paid.

Se uma fatura já timbrada não puder ser cancelada diretamente, void responde 409 com code: "credit_note_required": emita uma nota de crédito.

No México:

void pede o cancelamento do CFDI com o motivo 02 do SAT. Se o SAT ainda não o confirmou, responde 202 com { "data": { "id": "…", "estado": "open", "cancelacion": "pendiente" } } e a fatura continua válida; invoice.voided não é disparado até a confirmação. A substituição com o motivo 01 e a fatura global só estão disponíveis no app.
payment sobre um CFDI PPD dispara o complemento de pagamento automático desse pagamento.

Erros frequentes

Código	Quando
`invalid_request` (400)	Falta `cliente_id` ou `items`, um item não traz descrição ou quantidade, `due_date` não é `YYYY-MM-DD`, o desconto não tem o formato `{ tipo, valor }` ou um Leitweg-ID não passa nos dígitos verificadores.
`coupon_no_existe` (404)	O cupom não existe na sua conta.
`coupon_inactivo`, `coupon_vencido`, `coupon_aun_no_vigente`, `coupon_agotado`, `coupon_agotado_cliente`, `coupon_moneda`, `coupon_requiere_cliente` (409)	O cupom não se aplica a esta fatura; a mensagem diz por quê.
`invalid_state` (409)	A ação não se aplica ao status atual (por exemplo, enviar um rascunho). Enviar para um cliente sem e-mail responde `400` com este mesmo código.
`credit_note_required` (409)	A fatura já timbrada não pode ser cancelada diretamente: emita uma nota de crédito.
`not_found` (404)	A fatura não existe na sua organização.
`provider_error` (502)	O provedor fiscal rejeitou a emissão; a mensagem diz por quê.
`send_failed` (502)	Não foi possível enviar o e-mail da fatura. Tente `send` de novo.
`fx_unavailable`, `tax_catalog_unavailable` (503)	Não há taxa de câmbio verificável ou não foi possível ler o seu catálogo de impostos. Tente de novo.