> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newinvoice.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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
with the PAC's `prueba=true` flag — no real CFDI is issued and nothing touches your live records —
so you can build the whole flow before [going live](https://docs.newinvoice.dev/guides/going-live.md). To stamp with no profile
at all, see [Stamp with no setup](https://docs.newinvoice.dev/guides/testing.md#stamp-with-no-setup).

**1. Get your API key**

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

```bash theme={null}
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.

```bash theme={null}
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')
```

> [!TIP]
>
> Prefer JSON? Send `csd: { cer_base64, key_base64, password }` as `application/json`.

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

A test profile can stamp straight away. A live 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 (live mode)**

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

> [!WARNING]
>
> The manifiesto has no test mode. Signing with a real FIEL creates a real authorization
> with the PAC for that RFC, even with a `sk_test_` key. See [Testing](https://docs.newinvoice.dev/guides/testing.md).

```bash theme={null}
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=legal@example.mx" | jq '.status'
```

> [!WARNING]
>
> In live mode, skipping this makes the next stamp return 409 `fiscal_profile.manifest_required`.

**4. Create + stamp an invoice**

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

```bash theme={null}
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

> [card] [Stamping in depth](https://docs.newinvoice.dev/guides/stamping-your-first-invoice.md)
>
> Taxes, discounts, tax-included pricing, credit notes, and complemento de pago.

> [card] [Go multi-tenant](https://docs.newinvoice.dev/guides/connect.md)
>
> Hold many clients under one platform key with the `Invoice-Account` header.

> [card] [Webhooks](https://docs.newinvoice.dev/guides/webhooks.md)
>
> Receive signed events and verify them (JS + Python snippets).

> [card] [Going live](https://docs.newinvoice.dev/guides/going-live.md)
>
> Live keys, a real CSD, the carta manifiesto, and the production checklist.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.