Stamping your first invoice

This walks through the full path from nothing to a SAT-stamped CFDI 4.0 against the hosted API at https://api.newinvoice.dev.

This walks through the full path from nothing to a SAT-stamped CFDI 4.0 against the hosted API at https://api.newinvoice.dev. Do it all in test mode (an sk_test_... key) — test-mode stamps hit the PAC’s test environment, so nothing here touches SAT production and no real CFDI is issued. When you’re ready for real invoices, swap the test key for a live one (see Going live).

0. Get your API key

Sign up at https://api.newinvoice.dev/signup and open the dashboard. Each organization gets a test key (sk_test_...) and a live key (sk_live_...); copy the test key — it’s shown once.

API_KEY=sk_test_...            # from the dashboard

Every /v1 call needs Authorization: Bearer $API_KEY. The key’s mode scopes all data: a test key never sees live resources and vice-versa, and livemode appears on every resource.

1. Register a fiscal profile (emitter + CSD)

An invoice is issued by a fiscal profile: an RFC plus its CSD (Certificado de Sello Digital). Upload the .cer and .key files directly (multipart) with the private-key password; the RFC, serial and validity window are read from the certificate. The key material is AES-256-GCM encrypted at rest and never returned.

FP_ID=$(curl -s -X POST https://api.newinvoice.dev/v1/fiscal_profiles \
  -H "authorization: Bearer $API_KEY" \
  -F "legal_name=ACCEM SERVICIOS EMPRESARIALES SC" \
  -F "tax_regime=601" -F "zip=26015" -F "csd_password=YOUR_CSD_PASSWORD" \
  -F "csd_cer=@/path/to/your.cer" \
  -F "csd_key=@/path/to/your.key" \
  | jq -r '.id')

Multipart field names: csd_cer, csd_key, csd_password for the CSD, and fiel_cer, fiel_key, fiel_password if you also attach a FIEL. Prefer JSON? Send the same data as application/json with csd: { cer_base64, key_base64, password } — both content types are accepted.

Testing without a production CSD? Test mode tolerates expired and SAT test certificates, so you can onboard with a free SAT test CSD. Live mode rejects expired CSDs (422 fiscal_profile.csd_expired) — use a current CSD to go live.

The profile comes back on hold. A brand-new profile has not yet been authorized to stamp, so its response carries status: "requires_action" and a single next_actions entry telling you exactly what to do next:

{
  "id": "fp_...",
  "rfc": "AAA010101AAA",
  "status": "requires_action",
  "manifest_status": "pending_signature",
  "next_actions": [
    { "type": "sign_manifest",
      "message": "Upload the taxpayer's FIEL (e.firma) and sign the carta manifiesto to authorize CFDI stamping for this RFC.",
      "endpoint": "POST /v1/fiscal_profiles/fp_.../manifest",
      "requires": ["fiel"] }
  ]
}

On retrieve or list the same pending action appears as pending_actions. When the profile is authorized both arrays are [] and status is "active".

2. Sign the carta manifiesto

The PAC requires a signed carta manifiesto per RFC to authorize timbrado (invoice stamping) for that taxpayer — this is the SAT/PAC authorization, not the CSD. This API signs it for you; there is no browser portal to visit. The gate applies in test mode too, so you sign it once here before stamping.

The manifiesto is signed with the taxpayer’s FIEL (e.firma):

curl -s -X POST https://api.newinvoice.dev/v1/fiscal_profiles/$FP_ID/manifest \
  -H "authorization: Bearer $API_KEY" \
  -F "cer=@/path/to/fiel.cer" \
  -F "key=@/path/to/fiel.key" \
  -F "password=YOUR_FIEL_PASSWORD" \
  -F "email=[e-mail]" | jq '.status'

The manifest endpoint accepts the FIEL inline as -F cer= -F key= -F password= (or fiel: { cer_base64, key_base64, password \} in JSON), or reuses a FIEL already stored on the profile. On success the manifiesto is signed once and for all: the profile flips to status: "active" (manifest_status: "signed"), next_actions/pending_actions empty out, and a fiscal_profile.manifest_signed webhook fires. Signing is idempotent — an “already signed” result is treated as success.

Skip this step and the very next stamp attempt returns 409 fiscal_profile.manifest_required (in both test and live), with remediation pointing back to this endpoint. Every stamp call checks the manifiesto, so you only ever sign it once per profile.

3. Create + stamp an invoice

Send friendly JSON. You do not send the issuer — it comes from the profile. Omit taxes and each item defaults to 16% IVA traslado; subtotal/total are computed and rounded to the currency’s decimals.

curl -s -X POST https://api.newinvoice.dev/v1/invoices \
  -H "authorization: Bearer $API_KEY" -H 'content-type: application/json' \
  -H "idempotency-key: first-invoice-1" \
  -d "{
    \"fiscal_profile_id\": \"$FP_ID\",
    \"type\": \"I\",
    \"payment_form\": \"03\",
    \"payment_method\": \"PUE\",
    \"use\": \"G03\",
    \"customer\": { \"rfc\": \"URE180429TM6\", \"name\": \"UNIVERSIDAD ROBOTICA ESPANOLA\", \"zip\": \"65000\", \"tax_regime\": \"601\" },
    \"items\": [ { \"product_key\": \"01010101\", \"unit_key\": \"H87\", \"description\": \"Servicio de consultoría\", \"quantity\": 1, \"unit_price\": \"100.00\" } ]
  }" | jq

You get back status: "stamped", a real uuid (folio fiscal), total: "116.00", serie: "A", folio: "1", the sello_cfd/sello_sat, and xml_url/pdf_url.

Required fields, briefly

Field	Notes
type	I ingreso (default), E egreso/nota de crédito, P pago (complemento 2.0).
payment_form	c_FormaPago (03 transferencia, 01 efectivo…). Required for I/E.
payment_method	PUE (una exhibición) or PPD (parcialidades/diferido). Required for I/E.
use	UsoCFDI (G03 gastos en general…). Set here or on customer.use.
customer	rfc, name, zip, tax_regime — must match the receptor’s Constancia de Situación Fiscal.
items[]	product_key (8-digit ClaveProdServ), unit_key (ClaveUnidad), description, quantity, unit_price.

Common coherence rules the API enforces (returned as 422 cfdi.invalid_input with a path):

• payment_method: "PPD" forces payment_form: "99" (Por definir).
• Type P must not carry items or payment_method; it needs payments.
• Type E should carry relation (type 01 nota de crédito or 03 devolución) + original UUID.
• Receptor XAXX010101000 (público en general) requires global_information.
• Non-MXN currency requires exchange_rate.

4. Draft, then stamp later (optional)

Pass "draft": true to build and sign without stamping; the invoice returns status: "draft". Stamp it when ready:

curl -s -X POST https://api.newinvoice.dev/v1/invoices/$INV_ID/stamp \
  -H "authorization: Bearer $API_KEY" | jq '.status,.uuid'

5. Fetch the artifacts

curl -s https://api.newinvoice.dev/v1/invoices/$INV_ID/xml -H "authorization: Bearer $API_KEY" -o invoice.xml
curl -s https://api.newinvoice.dev/v1/invoices/$INV_ID/pdf -H "authorization: Bearer $API_KEY" -o invoice.pdf

Idempotency

Send Idempotency-Key: <unique> on POSTs. A retry with the same key + identical body replays the stored response (idempotent-replayed: true) instead of stamping twice; a different body under the same key → 409 idempotency.key_reuse. The PAC’s own duplicate code 307 is also resolved as a success-replay of the prior stamp, so double submits never mint two CFDIs.

Next

• Cancellation · Webhooks · Going live
• Full field reference: /openapi.json · error codes: ../errors.md