# Invoice API

> Mexican CFDI 4.0 invoicing API — stamp, cancel, validate, and bulk-download.

## Docs

- [Create a connected account](https://invoiceapi.mintlify.app/api-reference/accounts/create-a-connected-account.md): Create a connected account (tenant) owned by your platform organization. Act on its behalf on any other endpoint by sending your key plus the `Invoice-Account: <id>` header. Connected accounts do not get their own API keys.
- [List connected accounts](https://invoiceapi.mintlify.app/api-reference/accounts/list-connected-accounts.md): List the connected accounts your platform organization owns, newest first, with cursor pagination.
- [Offboard a connected account](https://invoiceapi.mintlify.app/api-reference/accounts/offboard-a-connected-account.md): Disables the connected account so no one can act as it, but retains all of its data. Its CFDIs are fiscal records that the taxpayer and the tax authority may need for years, so they are never hard-deleted; this is a soft offboard.
- [Retrieve a connected account](https://invoiceapi.mintlify.app/api-reference/accounts/retrieve-a-connected-account.md): Fetch one connected account owned by your platform organization by id.
- [Update a connected account](https://invoiceapi.mintlify.app/api-reference/accounts/update-a-connected-account.md): Rename, re-tag (metadata), or disable/re-enable a connected account. At least one field is required.
- [Create an API key](https://invoiceapi.mintlify.app/api-reference/api_keys/create-an-api-key.md): The plaintext `key` is returned exactly once and cannot be retrieved later. `mode` is independent of the key you authenticate with, so a test key may mint a live key.
- [List API keys](https://invoiceapi.mintlify.app/api-reference/api_keys/list-api-keys.md): List your API keys newest-first with cursor pagination. Only the non-secret prefix is returned — never the plaintext key or its hash.
- [Revoke an API key](https://invoiceapi.mintlify.app/api-reference/api_keys/revoke-an-api-key.md): Revocation is immediate: the key fails auth on its very next request. FOOTGUN — you may revoke the key you are authenticating with; that request succeeds but the key is dead afterward, so keep another active key of the same mode. Revoking the last active key of a mode returns a `warning`.
- [Update an API key](https://invoiceapi.mintlify.app/api-reference/api_keys/update-an-api-key.md): Rename an API key or pin it to a dated API version. At least one of name or version is required.
- [Retrieve the stamping balance](https://invoiceapi.mintlify.app/api-reference/balance/retrieve-the-stamping-balance.md): Return the number of stamping transactions (timbres) remaining on your account for the current mode.
- [List SAT catalogs](https://invoiceapi.mintlify.app/api-reference/catalogs/list-sat-catalogs.md): List the SAT reference catalogs you can look up — payment forms, payment methods, uso CFDI, tax regimes, and more — each with its slug and entry count. Fetch one with GET /v1/catalogs/{catalog}. Public — no API key required.
- [Retrieve a SAT catalog](https://invoiceapi.mintlify.app/api-reference/catalogs/retrieve-a-sat-catalog.md): Return every code + description for one SAT catalog — the exact values to send in invoice fields like `payment_form` (c_FormaPago), `payment_method` (c_MetodoPago), `use` (c_UsoCFDI) and `tax_regime` (c_RegimenFiscal). Filter uso_cfdi / tax_regimes by taxpayer type with `?persona=fisica|moral`. Publ…
- [Serve a how-to guide as markdown.](https://invoiceapi.mintlify.app/api-reference/docs/serve-a-how-to-guide-as-markdown.md)
- [Download a package](https://invoiceapi.mintlify.app/api-reference/downloads/download-a-package.md): Stream one descarga masiva package as a ZIP (application/zip) by its sequence number.
- [List download packages](https://invoiceapi.mintlify.app/api-reference/downloads/list-download-packages.md): List the downloadable packages for a completed request. Fetch each one promptly — SAT package URLs expire in ~5 minutes.
- [List massive downloads](https://invoiceapi.mintlify.app/api-reference/downloads/list-massive-downloads.md): List your descarga masiva requests newest-first with cursor pagination.
- [Request a massive download](https://invoiceapi.mintlify.app/api-reference/downloads/request-a-massive-download.md): Start a SAT descarga masiva for issued or received CFDIs over a date range, as full XML or a metadata index. Requires a signed carta manifiesto on the fiscal profile. Note the SAT limits: only 2 identical lifetime requests, 200k XML cap, and package URLs expire in ~5 minutes — fragment wide ranges r…
- [Retrieve a massive download](https://invoiceapi.mintlify.app/api-reference/downloads/retrieve-a-massive-download.md): Fetch one descarga masiva request by id to check its status and package count.
- [List events](https://invoiceapi.mintlify.app/api-reference/events/list-events.md): List events newest-first with cursor pagination, optionally filtered by exact type. Events mirror the bodies delivered to webhooks and can be replayed.
- [Resend an event](https://invoiceapi.mintlify.app/api-reference/events/resend-an-event.md): Re-enqueues webhook delivery for the event. With webhook_endpoint_id, targets that one endpoint (must belong to your org+mode and subscribe to the event type). Without it, fans out to every currently-matching enabled endpoint. A previously failed or exhausted delivery is reset and re-attempted, so a…
- [Retrieve an event](https://invoiceapi.mintlify.app/api-reference/events/retrieve-an-event.md): Fetch one stored event by id, including the exact resource snapshot it delivered.
- [Create a fiscal profile](https://invoiceapi.mintlify.app/api-reference/fiscal_profiles/create-a-fiscal-profile.md): Register an issuer RFC with its CSD (and optionally FIEL). The simplest way is to upload the raw files via multipart/form-data — `curl -F csd_cer=@csd.cer -F csd_key=@csd.key -F csd_password=... -F legal_name=... -F tax_regime=601 -F zip=06000`. Sending base64 in a JSON body is the alternative. Priv…
- [Delete a fiscal profile](https://invoiceapi.mintlify.app/api-reference/fiscal_profiles/delete-a-fiscal-profile.md): Delete a fiscal profile. Profiles referenced by issued invoices are retained (409 fiscal_profile.in_use) — rotate the CSD instead of deleting.
- [List fiscal profiles](https://invoiceapi.mintlify.app/api-reference/fiscal_profiles/list-fiscal-profiles.md): List the fiscal profiles for your organization in the current mode (test/live), newest first, with cursor pagination.
- [Retrieve a fiscal profile](https://invoiceapi.mintlify.app/api-reference/fiscal_profiles/retrieve-a-fiscal-profile.md): Fetch one fiscal profile by id. Returns the CSD public metadata (serial, validity, RFC) and manifest status — never the private key.
- [Sign the carta manifiesto](https://invoiceapi.mintlify.app/api-reference/fiscal_profiles/sign-the-carta-manifiesto.md): Sign the carta manifiesto with the FIEL (e.firma) to AUTHORIZE CFDI stamping for this RFC. A fiscal profile is created on hold (status "requires_action") and cannot stamp invoices until this is signed — do it once per profile. Uses the FIEL stored on the profile, or upload one raw via multipart — `c…
- [Update a fiscal profile](https://invoiceapi.mintlify.app/api-reference/fiscal_profiles/update-a-fiscal-profile.md): Rotate the CSD (upload the new files raw via multipart — `curl -F csd_cer=@new.cer -F csd_key=@new.key -F csd_password=...`; base64 JSON also works), replace the FIEL, set the PDF brand color/logo, edit legal_name/zip, or update metadata. A rotated CSD must belong to the same RFC.
- [Get ](https://invoiceapi.mintlify.app/api-reference/get-.md)
- [Get docserrors](https://invoiceapi.mintlify.app/api-reference/get-docserrors.md)
- [Get health](https://invoiceapi.mintlify.app/api-reference/get-health.md)
- [Get healthz](https://invoiceapi.mintlify.app/api-reference/get-healthz.md)
- [Get llms fulltxt](https://invoiceapi.mintlify.app/api-reference/get-llms-fulltxt.md)
- [Get llmstxt](https://invoiceapi.mintlify.app/api-reference/get-llmstxt.md)
- [Get openapijson](https://invoiceapi.mintlify.app/api-reference/get-openapijson.md)
- [Cancel an invoice](https://invoiceapi.mintlify.app/api-reference/invoices/cancel-an-invoice.md): Request SAT cancellation of a stamped CFDI with a motivo (01-04). Reason "01" requires substitute_invoice_id. Cancellation may be asynchronous — the invoice `cancellation.status` moves to cancel_pending while the receptor/SAT window resolves; poll or watch webhooks for the final state.
- [Create an invoice](https://invoiceapi.mintlify.app/api-reference/invoices/create-an-invoice.md): Build and stamp a CFDI 4.0 from friendly JSON. The issuer comes from `fiscal_profile_id` (the only body field the schema hard-requires); every other field is validated in the service, which returns a precise error with remediation if something is missing or wrong. Required for type I (ingreso) and E…
- [Download the CFDI PDF](https://invoiceapi.mintlify.app/api-reference/invoices/download-the-cfdi-pdf.md): Return the CFDI representación impresa as a PDF, rendered on demand and then cached. Uses the fiscal profile brand color/logo when set.
- [Download the CFDI XML](https://invoiceapi.mintlify.app/api-reference/invoices/download-the-cfdi-xml.md): Return the stamped CFDI 4.0 XML (with the TimbreFiscalDigital). Only available once stamped — a draft/stamp_failed invoice returns 409 invoice.xml_requires_stamp.
- [List invoices](https://invoiceapi.mintlify.app/api-reference/invoices/list-invoices.md): List invoices newest-first with cursor pagination. Filter by status, customer_rfc, and created_at date range. Pass `expand=fiscal_profile` to inline the issuer on each row.
- [Retrieve an invoice](https://invoiceapi.mintlify.app/api-reference/invoices/retrieve-an-invoice.md): Fetch one invoice by id. Pass `expand=fiscal_profile` to inline the issuer profile.
- [Stamp a draft invoice](https://invoiceapi.mintlify.app/api-reference/invoices/stamp-a-draft-invoice.md): Stamp a previously created draft, turning it into a fiscal CFDI with a SAT UUID. Re-signs with a fresh Fecha if the draft is near the SAT 72-hour window. No-op-safe: an already-stamped invoice returns 409 invoice.already_stamped.
- [Create an organization](https://invoiceapi.mintlify.app/api-reference/organizations/create-an-organization.md): Bootstrap a new organization and mint its first test and live API keys. Dev-gated: only available when ALLOW_ORG_BOOTSTRAP is enabled; requires no API key. The returned secret keys are shown once — store them immediately.
- [List usage records](https://invoiceapi.mintlify.app/api-reference/usage/list-usage-records.md): List metered consumption (today: CFDI stamps) newest-first with cursor pagination. Filter by kind and created_at date range to reconcile billing.
- [Retrieve a validation](https://invoiceapi.mintlify.app/api-reference/validations/retrieve-a-validation.md): Fetch a previously run validation result by id.
- [Validate a CFDI](https://invoiceapi.mintlify.app/api-reference/validations/validate-a-cfdi.md): Validate a CFDI 4.0 XML: structure, arithmetic, the digital seal (sello), and — when already stamped — live SAT status. Send either JSON `{ "xml_base64": "..." }` or a raw CFDI XML body with Content-Type application/xml.
- [List every dated API version and how to pin one (public, no auth).](https://invoiceapi.mintlify.app/api-reference/versions/list-every-dated-api-version-and-how-to-pin-one-public-no-auth.md): Discovery endpoint for dated versioning. Returns every supported version with a human- and agent-readable changelog, the current version, and how to pin one via the `Invoice-Version` header. Requires no API key.
- [Create a webhook endpoint](https://invoiceapi.mintlify.app/api-reference/webhook_endpoints/create-a-webhook-endpoint.md): Register an HTTPS URL to receive event notifications. Subscribe to specific event types, wildcards, or all ("*"). The signing secret used to verify deliveries is returned exactly once here.
- [Delete a webhook endpoint](https://invoiceapi.mintlify.app/api-reference/webhook_endpoints/delete-a-webhook-endpoint.md): Permanently delete a webhook endpoint. Its delivery history is retained but no further events are sent.
- [List webhook deliveries](https://invoiceapi.mintlify.app/api-reference/webhook_endpoints/list-webhook-deliveries.md): Each row is the current state of one (event, endpoint) delivery — status, attempt count, last response/error, and the next scheduled retry. Use it to see why deliveries failed and to confirm a resent event was re-delivered.
- [List webhook endpoints](https://invoiceapi.mintlify.app/api-reference/webhook_endpoints/list-webhook-endpoints.md): List your webhook endpoints newest-first with cursor pagination. Signing secrets are never included.
- [Retrieve a webhook endpoint](https://invoiceapi.mintlify.app/api-reference/webhook_endpoints/retrieve-a-webhook-endpoint.md): Fetch one webhook endpoint by id. The signing secret is never returned.
- [Update a webhook endpoint](https://invoiceapi.mintlify.app/api-reference/webhook_endpoints/update-a-webhook-endpoint.md): Change the delivery URL, replace the subscribed event types, pause/resume delivery, or update metadata. At least one field is required.
- [Conventions](https://invoiceapi.mintlify.app/concepts/conventions.md): Auth, test vs live, money, pagination, idempotency, metadata, versioning, rate limits, and Request-Id — the rules every endpoint follows.
- [Error reference](https://invoiceapi.mintlify.app/concepts/errors.md): {/* GENERATED by pnpm openapi (scripts/generate-openapi.ts). Do not edit by hand. */}
- [Versioning & changelog](https://invoiceapi.mintlify.app/concepts/versioning.md): Dated API versions, what changed in each, how to pin one, and the deprecation policy.
- [API keys](https://invoiceapi.mintlify.app/guides/api-keys.md): Every /v1 request authenticates with an API key: Authorization: Bearer sk_test_... (test) or
- [Cancellation](https://invoiceapi.mintlify.app/guides/cancellation.md): Cancelling a CFDI is not a delete — it is a SAT-mediated request that may require the receptor's
- [SAT catalogs](https://invoiceapi.mintlify.app/guides/catalogs.md): Look up the exact coded values the SAT requires — payment forms, payment methods, uso CFDI, tax regimes, and more — instead of guessing four-digit enums.
- [Connect — one platform, many tenants](https://invoiceapi.mintlify.app/guides/connect.md): Built for accounting apps, ERPs, and platforms that manage invoicing for many businesses under
- [Going live](https://invoiceapi.mintlify.app/guides/going-live.md): Everything up to now ran on the simulated PAC with zero credentials. To stamp CFDIs that are real
- [Massive download (SAT descarga masiva)](https://invoiceapi.mintlify.app/guides/massive-download.md): Bulk-retrieve the CFDIs (or their metadata) that an RFC issued or received in a date range,
- [Stamping your first invoice](https://invoiceapi.mintlify.app/guides/stamping-your-first-invoice.md): This walks through the full path from nothing to a SAT-stamped CFDI 4.0. It runs entirely on the
- [Testing](https://invoiceapi.mintlify.app/guides/testing.md): Everything in this API can be exercised end-to-end with zero credentials. In test mode the
- [Webhooks](https://invoiceapi.mintlify.app/guides/webhooks.md): The API POSTs a signed JSON event to your endpoint whenever something happens (an invoice is
- [Invoice API](https://invoiceapi.mintlify.app/index.md): A Stripe-quality REST API for Mexican electronic invoicing (CFDI 4.0).
- [Quickstart](https://invoiceapi.mintlify.app/quickstart.md): Stamp your first SAT CFDI 4.0 in four requests — zero credentials, running on the simulated PAC.

## OpenAPI Specs

- [openapi](https://invoiceapi.mintlify.app/api-reference/openapi.json)