Facturation (CFDI) et l’API
La facturation est bien exposée dans l’API publique v1. Une facture est une ressource à part entière : vous pouvez la créer, l’émettre, l’envoyer, y enregistrer des paiements et l’annuler sans passer par un devis.
Le cycle de vie d’une facture
Une facture possède deux axes qui ne se mélangent jamais : son statut commercial (draft, open, paid, void, uncollectible) et son statut fiscal (pending, issued, cancelled, error). « Timbrée auprès du SAT » et « payée par le client » sont deux faits distincts.
- Brouillon —
POST /api/v1/facturasaveccliente_idetitems. Ne consomme ni numéro ni timbre. - Émettre —
POST /api/v1/facturas/{id}avec{ "action": "finalize" }. C’est à ce moment que le numéro séquentiel suivant est réservé et que le document est timbré : CFDI 4.0 auprès du SAT au Mexique (avec le CSD de votre organisation), facture commerciale avec votre propre numérotation partout ailleurs. - Envoyer —
{ "action": "send" }envoie la facture à l’e-mail du client avec son PDF et le lien vers sa propre page de paiement. - Encaisser — le client paie par carte depuis ce lien, ou vous enregistrez un paiement manuel avec
{ "action": "payment", "monto": 1000, "moneda": "MXN" }. Dans les deux cas, le solde diminue ; lorsqu’il atteint zéro, la facture passe àpaid. - Annuler ou émettre un avoir —
{ "action": "void" }annule auprès du SAT. Si des paiements ont déjà été imputés à la facture, la réponse est409aveccode: "credit_note_required": le document approprié est alors un avoir,{ "action": "credit_note" }.
Endpoints
| Méthode | Chemin | Portée |
|---|---|---|
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 |
La liste est paginée par curseur : si la réponse contient meta.next_cursor, répétez l’appel avec ?cursor=.
À partir d’un devis
Si l’affaire existait déjà dans Cord, rien ne change : vous marquez le devis comme facturé et Cord émet le document en reprenant le client, les lignes et la devise. Les deux voies produisent la même facture, avec le même cycle de vie.
Pour que le CFDI soit émis au nom d’un RFC précis, saisissez le régime fiscal, le code postal et l’usage du CFDI du client dans sa fiche. Sans ces informations, le document est émis au nom du « público en general » (grand public).
Webhooks
Chaque changement de statut déclenche un événement avec une charge utile de facture (numéro, Folio fiscal, solde, échéance), et non de devis :
invoice.finalized, invoice.sent, invoice.paid, invoice.payment_failed, invoice.voided, invoice.marked_uncollectible, invoice.overdue.
MCP
Le serveur MCP de Cord expose listar_facturas, detalle_factura et crear_factura_borrador. L’écriture s’arrête volontairement au brouillon : le timbrage est irréversible et coûte de l’argent réel, il se fait donc depuis l’application ou depuis l’API avec une clé en écriture.