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 × 0.16
total    = subtotal + iva            ← the CFDI total

unit_price: 15000, quantity: 1  →  subtotal 15000.00 + IVA 2400.00 = total 17400.00

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

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",
    "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.