Invoices: Overview

The API issues and retrieves CFDI 4.0 fiscal documents on behalf of your registered entities. All five comprobante types share one endpoint (POST /v1/issued-invoices); a unified list (GET /v1/invoices) surfaces both house-issued and SAT-downloaded invoices in a single, deduplicated view.

Issuing is synchronous. The stamped XML and PDF come back in the 201 response. No polling required.

Listing is unified. One endpoint, one source field: house (issued via this API) or extraction (downloaded from the SAT).

The XML is the legal document. It carries the SAT's digital seal and UUID (folio fiscal). The PDF is a printable representation regenerated from the XML. A PDF rendering failure never blocks stamping — pdf.available may be false even on a successfully stamped invoice.

Supported CFDI types

Not currently supported: optional complements beyond Carta Porte 3.1 and Complemento de Pago 2.0 (e.g. donatarias, leyendas fiscales, comercio exterior). Self-billing and other CFDI variants are out of scope.

Quickstart

Get from zero to a stamped invoice in four steps.

Step 1 — Upload a CSD

Every invoice must be signed with the entity's Certificado de Sello Digital. See Credentials for the full reference.

curl -X POST https://api.example.com/v1/entities/$ENTITY_ID/credentials \
  -u "$API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "cer":      "'"$(base64 -i certificate.cer | tr -d '\n')"'",
    "key":      "'"$(base64 -i privatekey.key | tr -d '\n')"'",
    "password": "your_key_password"
  }'

A 201 Created response with "status": "active" confirms the CSD is ready.

Step 2 — Issue an invoice

curl -X POST https://api.example.com/v1/issued-invoices \
  -u "$API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id":      "'"$ENTITY_ID"'",
    "type":           "I",
    "series":         "A",
    "folio":          "1024",
    "issuer": { "fiscal_regime": "601", "place_of_issue": "06600" },
    "receiver": {
      "rfc":           "EKU9003173C9",
      "name":          "ESCUELA KEMPER URGATE",
      "postal_code":   "06600",
      "fiscal_regime": "601",
      "cfdi_use":      "G03"
    },
    "payment_form":   "03",
    "payment_method": "PUE",
    "currency":       "MXN",
    "items": [
      {
        "product_code": "81161500",
        "unit_code":    "E48",
        "description":  "Software consulting services",
        "quantity":     10,
        "unit_price":   500.00,
        "tax_object":   "02",
        "taxes": [{ "type": "iva", "factor": "rate", "rate": 0.160000 }]
      }
    ]
  }'

Save the id and uuid from the 201 response.

Step 3 — Download the XML

curl -u "$API_KEY:" \
  https://api.example.com/v1/issued-invoices/$INVOICE_ID/xml \
  -o invoice.xml

Step 4 — Verify it appears in the unified list

curl -u "$API_KEY:" \
  "https://api.example.com/v1/invoices?source=house&type=I"

The invoice appears with "source": "house". Once a SAT extraction runs, confirmed_by_sat flips to true.

Prerequisites

• CSD — required to issue and cancel CFDI 4.0. Upload once per entity via Credentials.
• CIEC — required for SAT extractions (pulling invoices, CSF, compliance opinion). Also managed via Credentials.
• An entity must have exactly one active CSD before any stamping operation will succeed.

Sandbox

A sandbox environment is available for testing the full issuing flow without generating real fiscal documents.

• Point your requests to the sandbox base URL provided in your account dashboard.
• A test CSD is required even in sandbox. Upload it via Credentials using the sandbox base URL and your sandbox API key.
• SAT test RFC pairs published for interoperability testing work as receiver.rfc.
• Invoices issued in sandbox are stamped against the SAT's certification environment and produce real-looking UUIDs that are not valid in production.

Explore the invoicing API