Quickstart

Stamp your first SAT CFDI 4.0 in four requests — in test mode, against the hosted API.

Everything here runs in test mode against https://api.newinvoice.dev. A sk_test_ key stamps against the PAC’s test environment — no real CFDI is issued and nothing touches your live records — so you can build the whole flow before going live.

1. Get your API key

   Sign up at 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.

2. Register a fiscal profile — upload the CSD files

   No base64 needed: upload your .cer/.key directly with the private-key password. The RFC, serial, and validity window are read from the certificate. Keys are 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')
   

   Prefer JSON? Send csd: { cer_base64, key_base64, password } as application/json.

   Test mode accepts expired and SAT test CSDs, so you can onboard with a free SAT test certificate; live mode requires a current one.

   The profile comes back on hold — status: "requires_action" with a sign_manifest action under next_actions — and cannot stamp until its carta manifiesto is signed.

3. Sign the carta manifiesto

   The SAT requires a signed carta manifiesto per RFC to authorize timbrado. This API signs it for you (no browser portal), and the gate applies in test mode too. The manifiesto is signed with the taxpayer’s FIEL (e.firma). The profile then flips to status: "active".

   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'
   

   Skip this and the next stamp returns 409 fiscal_profile.manifest_required.
4. Create + stamp an invoice

   The issuer is taken from the profile; you send the customer and line items.

   curl -s -X POST https://api.newinvoice.dev/v1/invoices \
     -H "authorization: Bearer $API_KEY" -H 'content-type: application/json' \
     -H "idempotency-key: quickstart-1" \
     -d "{\"fiscal_profile_id\":\"$FP_ID\",\"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
   

   The response has status: "stamped", the fiscal uuid, and xml_url / pdf_url.

Next steps

Stamping in depth

Taxes, discounts, tax-included pricing, credit notes, and complemento de pago.

Go multi-tenant

Hold many clients under one platform key with the Invoice-Account header.

Webhooks

Receive signed events and verify them (JS + Python snippets).

Going live

Live keys, a real CSD, the carta manifiesto, and the production checklist.