Rechnungsstellung (CFDI) und die API
Die Rechnungsstellung ist in der öffentlichen API v1 verfügbar. Eine Rechnung ist eine eigene Ressource: Sie können sie erstellen, ausstellen, versenden, Zahlungen darauf erfassen und sie stornieren, ohne den Umweg über ein Angebot.
Der Lebenszyklus einer Rechnung
Eine Rechnung hat zwei Achsen, die nie vermischt werden: ihren kaufmännischen Status (draft, open, paid, void, uncollectible) und ihren steuerlichen Status (pending, issued, cancelled, error). „Beim SAT gestempelt“ und „vom Kunden bezahlt“ sind unterschiedliche Tatsachen.
- Entwurf –
POST /api/v1/facturasmitcliente_idunditems. Verbraucht weder eine Nummer noch eine Stempelung. - Ausstellen –
POST /api/v1/facturas/{id}mit{ "action": "finalize" }. Hier wird die fortlaufende Nummer reserviert und das Dokument gestempelt: CFDI 4.0 beim SAT in Mexiko (mit dem CSD Ihrer Organisation), eine Handelsrechnung mit eigener Nummerierung im Rest der Welt. - Senden –
{ "action": "send" }sendet die Rechnung mit PDF und dem Link zu ihrer eigenen Zahlungsseite an die E-Mail-Adresse des Kunden. - Zahlung einziehen – Der Kunde zahlt per Karte über diesen Link, oder Sie erfassen eine manuelle Zahlung mit
{ "action": "payment", "monto": 1000, "moneda": "MXN" }. In beiden Fällen sinkt der offene Betrag; bei null wechselt die Rechnung zupaid. - Stornieren oder gutschreiben –
{ "action": "void" }storniert beim SAT. Sind auf die Rechnung bereits Zahlungen verbucht, lautet die Antwort409mitcode: "credit_note_required": Das richtige Dokument ist dann eine Gutschrift,{ "action": "credit_note" }.
Endpoints
| Methode | Pfad | Scope |
|---|---|---|
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 |
Die Liste wird per Cursor paginiert: Enthält die Antwort meta.next_cursor, wiederholen Sie den Aufruf mit ?cursor=.
Aus einem Angebot
Wenn der Deal bereits in Cord lief, funktioniert alles wie gewohnt: Sie markieren das Angebot als Abgerechnet, und Cord stellt das Dokument aus und übernimmt dabei Kunde, Positionen und Währung. Beide Wege erzeugen dieselbe Rechnung mit demselben Lebenszyklus.
Damit der CFDI auf einen bestimmten RFC ausgestellt wird, erfassen Sie im Kundenprofil Steuerregime, Postleitzahl und CFDI-Verwendung des Kunden. Ohne diese Angaben wird der Beleg an „público en general“ (die allgemeine Öffentlichkeit) ausgestellt.
Webhooks
Jede Statusänderung löst ein Ereignis mit dem Payload einer Rechnung aus (Nummer, Folio fiscal, offener Betrag, Fälligkeit), nicht mit dem eines Angebots:
invoice.finalized, invoice.sent, invoice.paid, invoice.payment_failed, invoice.voided, invoice.marked_uncollectible, invoice.overdue.
MCP
Der MCP-Server von Cord stellt listar_facturas, detalle_factura und crear_factura_borrador bereit. Schreibzugriff reicht bewusst nur bis zum Entwurf: Die Stempelung ist unwiderruflich und kostet echtes Geld, deshalb erfolgt sie in der App oder über die API mit einem Schlüssel mit Schreibberechtigung.