Ingestion API — v1

Overview

The flow: 1) your system POSTs a payment → 2) you deliver the returned portal_url to your client through your own channel → 3) the client claims the record with their RFC and stamps → 4) you poll and reconcile the stamped CFDI. Records arrive without receptor data by design — the client owns their fiscal identity.

Authentication

Every request carries a bearer key issued by the platform admin. Keys are environment-scoped: a worker refuses a key minted for the other environment. The secret is shown once at issuance; revocation is immediate.

Authorization: Bearer mk_live_…   # production
Authorization: Bearer mk_test_…   # staging

401 = missing/unknown/wrong-environment key · 403 key_revoked. Store the key as a secret; rotate by revoking in the admin panel and minting a new one.

Amounts

subtotal = quantity × unit_price     (rounded to 2 decimals per line)
iva      = subtotal × rate           (0.16 · 0.08 · 0 · 0 for exento)
total    = subtotal + iva            ← the CFDI total

unit_price: 15000, quantity: 1, iva: "16"     →  subtotal 15000.00 + IVA 2400.00 = total 17400.00
unit_price: 15000, quantity: 1, iva: "8"      →  subtotal 15000.00 + IVA 1200.00 = total 16200.00
unit_price: 15000, quantity: 1, iva: "exento" →  subtotal 15000.00 + IVA    0.00 = total 15000.00

If your system records the amount actually charged with IVA included, divide by 1 + rate before POSTing: a $17,400.00 charge at 16% is unit_price: 15000.00, and so is a $16,200.00 charge at 8%. The invoice object returned by this API carries the stamped CFDI's subtotal, iva, total, iva_rate and expedition_zip — reconcile against those, never against your own math.

Tasa de IVA and lugar de expedición

Every record carries an effective tasa de IVA (iva: "16" · "8" · "0" · "exento") and, optionally, a lugar de expedición (expedition_zip, the 5-digit CP the CFDI is issued from — LugarExpedicion). When you are silent, both resolve from the emisor's settings (the tenant configures them in Ajustes › Facturación) and the response names every default it applied:

// 201 — a silent payload on an emisor configured 16 → 06700, 8 → 22010
{
  "result": "created",
  "record": { "…": "…", "iva": "16", "expedition_zip": "06700" },
  "portal_url": "https://…",
  "warnings": [
    { "path": "iva", "code": "iva_defaulted", "message": "iva defaulted to \"16\" (the issuer default)" },
    { "path": "expedition_zip", "code": "expedition_zip_defaulted", "message": "expedition_zip defaulted to \"06700\" (the issuer CP for this rate)" }
  ]
}

• warnings is additive and only present when something defaulted — send both fields and it never appears. Codes: iva_defaulted · expedition_zip_defaulted.
• 8% is the estímulo región fronteriza: the PAC accepts it only from a CP with the border mark, for an RFC registered in the padrón, on eligible product keys. micfdi does not pre-validate those; it only refuses iva: "8" when neither you nor the emisor provide a CP for 8 (422 validation_failed, field expedition_zip). A PAC rejection burns no timbre.
• Once the record is invoiced both fields are frozen — a differing re-send is the usual 409.

Match fields (self-service search)

When your tenant has a claim configuration (ask us to set one up), every record must carry the configured ownership fields inside match_fields. Your clients then find their payments — without the portal link — at your public search page (factura.micfdi.mx/f/<your-slug> or <your-slug>.micfdi.mx) by typing exactly those values.

"match_fields": {
  "policy_number": "POL-00123",     // string — trimmed, UPPERCASED before matching
  "contract_start": "2026-06-01",   // date   — strict ISO yyyy-mm-dd
  "total": "10,440.00"              // amount — "$", "MXN", commas stripped; stored "10440.00"
}

Create or update a record

One endpoint, convergent by external_ref: POST the payment as your system knows it, as often as you like. A new ref creates the record; an existing one makes the record converge onto your payload — your system is authoritative, so a re-send with different facts edits the record in place (field-level audit trail on our side). The response's result tells you which happened.

curl -X POST https://micfdi-api-prod.tbrneto.workers.dev/v1/records \
  -H "Authorization: Bearer mk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "pay-8841",
    "description": "Póliza jurídica junio",
    "payment_form": "03",
    "unit_price": "15000.00",
    "iva": "16",
    "client": { "name": "Ernesto Huerta", "email": "cliente@ejemplo.mx" }
  }'

payment_method is fixed to PUE for now (PPD + Complemento de Pago is on the roadmap).

Fetch one record

Returns the record, including invoice once your client self-stamped. Poll this (or the list) to reconcile — outbound webhooks are a later slice. 404 if the id is not yours.

curl https://micfdi-api-prod.tbrneto.workers.dev/v1/records/018f… -H "Authorization: Bearer mk_live_…"

{
  "record": {
    "id": "018f…", "external_ref": "pay-8841", "status": "invoiced", "claimed": true,
    …
    "invoice": { "uuid": "18604FDA-…", "folio": "106", "subtotal": 15000, "iva": 2400, "total": 17400 }
  }
}

List records

Newest first. status ∈ registered | validated | invoiced | rejected; limit ≤ 100 (default 20); cursor = the previous response's next_cursor (opaque). next_cursor: null = last page.

curl "https://micfdi-api-prod.tbrneto.workers.dev/v1/records?status=invoiced&limit=50" \
  -H "Authorization: Bearer mk_live_…"

The record object

Errors

{
  "error": {
    "code": "validation_failed",
    "message": "invalid fields",
    "fields": [
      { "path": "payment_form", "message": "is not a SAT c_FormaPago code (e.g. \"03\" transferencia)" },
      { "path": "match_fields.contract_start", "message": "must be an ISO date (yyyy-mm-dd)" }
    ]
  }
}

Codes are stable and safe to branch on; messages are human-oriented and may change.

Integration checklist

1. Get an API key from the platform admin; store it as a secret.
2. On each payment (and on each correction): POST /v1/records with your payment id as external_ref and the IVA-exclusive unit_price. Re-send freely — the server decides create vs update, and result tells you which happened.
3. Treat 409 record_rejected as terminal for that ref: surface it to your operations team — re-sending will not fix it (the tenant must restore the record).
4. On any 4xx, log the full error body — especially error.fields (see Errors).
5. Self-service search enabled? Include match_fields with the values as printed on the client's receipt (see Match fields).
6. Deliver portal_url to your client through your own channel (WhatsApp, email, your app).
7. Poll GET /v1/records?status=invoiced (or by id) and reconcile against invoice.total.
8. Key compromised? Revoke in the admin panel, mint a new one, redeploy your secret.