Faturamento (CFDI) e a API
O faturamento está exposto na API pública v1. Uma fatura é um recurso próprio: você pode criá-la, emiti-la, enviá-la, registrar pagamentos nela e cancelá-la sem passar por um orçamento.
O ciclo de vida de uma fatura
Uma fatura tem dois eixos que não se misturam: seu status comercial (draft, open, paid, void, uncollectible) e seu status fiscal (pending, issued, cancelled, error). “Timbrada no SAT” e “paga pelo cliente” são fatos diferentes.
- Rascunho —
POST /api/v1/facturascomcliente_ideitems. Não consome número nem timbragem. - Emitir —
POST /api/v1/facturas/{id}com{ "action": "finalize" }. Aqui se reserva o número sequencial e se faz a timbragem: CFDI 4.0 no SAT no México (com o CSD da sua organização), fatura comercial com numeração própria no resto do mundo. - Enviar —
{ "action": "send" }envia a fatura para o e-mail do cliente com o PDF e o link para a página de pagamento dela. - Receber — o cliente paga com cartão por esse link, ou você registra um pagamento manual com
{ "action": "payment", "monto": 1000, "moneda": "MXN" }. Nos dois casos o saldo diminui; ao chegar a zero, a fatura passa apaid. - Cancelar ou creditar —
{ "action": "void" }cancela no SAT. Se a fatura já tiver pagamentos aplicados, a resposta é409comcode: "credit_note_required": o documento correto é uma nota de crédito,{ "action": "credit_note" }.
Endpoints
| Método | Caminho | Escopo |
|---|---|---|
GET |
/api/v1/facturas?estado=&cliente=&q=&desde=&hasta=&cursor= |
read |
POST |
/api/v1/facturas |
write |
GET |
/api/v1/facturas/{id} |
read |
POST |
/api/v1/facturas/{id} (finalize, send, payment, void, credit_note) |
write |
A listagem pagina por cursor: se a resposta trouxer meta.next_cursor, repita a chamada com ?cursor=.
A partir de um orçamento
Se a negociação já estava no Cord, tudo continua igual: você marca o orçamento como faturado e o Cord emite o documento herdando cliente, itens e moeda. Os dois caminhos produzem a mesma fatura, com o mesmo ciclo de vida.
Para que o CFDI saia em nome de um RFC específico, informe o regime fiscal, código postal e uso do CFDI do cliente na ficha dele. Sem esses dados, o comprovante é emitido como “público em geral”.
Webhooks
Cada mudança de status dispara um evento com payload de fatura (número, folio fiscal, saldo, vencimento), não de orçamento:
invoice.finalized, invoice.sent, invoice.paid, invoice.payment_failed, invoice.voided, invoice.marked_uncollectible, invoice.overdue.
MCP
O servidor MCP do Cord expõe listar_facturas, detalle_factura e crear_factura_borrador. A escrita vai somente até o rascunho de propósito: a timbragem é irreversível e custa dinheiro real, então é feita pelo app ou pela API com uma chave de escrita.