# Invoice API

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

- [Invoice API](https://docs.newinvoice.dev/index.md): A Stripe-quality REST API for Mexican electronic invoicing (CFDI 4.0).
- [Quickstart](https://docs.newinvoice.dev/quickstart.md): Stamp your first SAT CFDI 4.0 in four requests — in test mode, against the hosted API.
- [Stamping your first invoice](https://docs.newinvoice.dev/guides/stamping-your-first-invoice.md): This walks through the full path from nothing to a SAT-stamped CFDI 4.0 against the hosted API at https://api.newinvoice.dev.
- [Cancellation](https://docs.newinvoice.dev/guides/cancellation.md): Cancelling a CFDI is not a delete — it is a SAT-mediated request that may require the receptor's acceptance and always produces an *acuse de cancelación*.
- [SAT sync — every CFDI the SAT has on file](https://docs.newinvoice.dev/guides/sat-sync.md): Register a taxpayer's RFC once. We backfill their CFDI history from the SAT — up to the full 71-month window — and then keep it current, automatically.
- [SAT credentials — access with the taxpayer's RFC and CIEC](https://docs.newinvoice.dev/guides/sat-credentials.md): Save a taxpayer's SAT password (the CIEC, or *contraseña*) on a fiscal profile, and we can fetch SAT documents for that RFC without a FIEL.
- [Constancia de situación fiscal](https://docs.newinvoice.dev/guides/constancia.md): Get a taxpayer's constancia de situación fiscal as a PDF, using only their RFC and a saved CIEC.
- [Massive download](https://docs.newinvoice.dev/guides/massive-download.md): Download the CFDIs (Mexican electronic invoices) an RFC issued or received in a date range, as a ZIP of XML files.
- [Webhooks](https://docs.newinvoice.dev/guides/webhooks.md): The API POSTs a signed JSON event to your endpoint whenever something happens (an invoice is stamped, a cancellation resolves, a download is ready…).
- [Connect — one platform, many tenants](https://docs.newinvoice.dev/guides/connect.md): Built for accounting apps, ERPs, and platforms that manage invoicing for many businesses under a single integration.
- [API keys](https://docs.newinvoice.dev/guides/api-keys.md): Every /v1 request authenticates with an API key: Authorization: Bearer sk_test_...
- [Testing](https://docs.newinvoice.dev/guides/testing.md): Build and rehearse your whole integration in test mode before you touch live SAT data.
- [Going live](https://docs.newinvoice.dev/guides/going-live.md): Everything up to now ran in test mode. To stamp CFDIs that are real at the SAT you switch your keys from test to live and register real fiscal material.
- [SAT catalogs](https://docs.newinvoice.dev/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.
- [Conventions](https://docs.newinvoice.dev/concepts/conventions.md): Auth, test vs live, money, pagination, idempotency, metadata, versioning, rate limits, and Request-Id — the rules every endpoint follows.
- [Versioning & changelog](https://docs.newinvoice.dev/concepts/versioning.md): Dated API versions, what changed in each, how to pin one, and the deprecation policy.
- [Error reference](https://docs.newinvoice.dev/concepts/errors.md): {/* GENERATED by pnpm openapi (scripts/generate-openapi.ts).
- [Get ](https://docs.newinvoice.dev/api-reference/get-.md)
- [Get healthz](https://docs.newinvoice.dev/api-reference/get-healthz.md)
- [Get health](https://docs.newinvoice.dev/api-reference/get-health.md)
- [Get openapijson](https://docs.newinvoice.dev/api-reference/get-openapijson.md)
- [Get llmstxt](https://docs.newinvoice.dev/api-reference/get-llmstxt.md)
- [Get llms fulltxt](https://docs.newinvoice.dev/api-reference/get-llms-fulltxt.md)
- [Get docserrors](https://docs.newinvoice.dev/api-reference/get-docserrors.md)
- [Serve a how-to guide as markdown.](https://docs.newinvoice.dev/api-reference/docs/serve-a-how-to-guide-as-markdown.md)
- [List API keys](https://docs.newinvoice.dev/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.
- [Create an API key](https://docs.newinvoice.dev/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.
- [Revoke an API key](https://docs.newinvoice.dev/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://docs.newinvoice.dev/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.
- [List connected accounts](https://docs.newinvoice.dev/api-reference/accounts/list-connected-accounts.md): List the connected accounts your platform organization owns, newest first, with cursor pagination.
- [Create a connected account](https://docs.newinvoice.dev/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.
- [Retrieve a connected account](https://docs.newinvoice.dev/api-reference/accounts/retrieve-a-connected-account.md): Fetch one connected account owned by your platform organization by id.
- [Offboard a connected account](https://docs.newinvoice.dev/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.
- [Update a connected account](https://docs.newinvoice.dev/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.
- [List fiscal profiles](https://docs.newinvoice.dev/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. The default test-mode sandbox issuer is not listed.
- [Create a fiscal profile](https://docs.newinvoice.dev/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…
- [Retrieve a fiscal profile](https://docs.newinvoice.dev/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.
- [Delete a fiscal profile](https://docs.newinvoice.dev/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.
- [Update a fiscal profile](https://docs.newinvoice.dev/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.
- [Sign the carta manifiesto](https://docs.newinvoice.dev/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 live fiscal profile is created on hold (status "requires_action") and cannot stamp invoices until this is signed — do it once per profile. Test-mode profiles do not need it, and this is a real authorization…
- [Enable automatic SAT synchronization](https://docs.newinvoice.dev/api-reference/fiscal_profiles/enable-automatic-sat-synchronization.md): Register this profile's RFC for automatic SAT synchronization. We backfill the taxpayer's CFDI history (up to the SAT's 71-month limit) and then keep it current, mirroring both issued and received CFDIs. Authorizes with the FIEL (e.firma), not the CSD. Idempotent: re-enabling an already-registered R…
- [Disable automatic SAT synchronization](https://docs.newinvoice.dev/api-reference/fiscal_profiles/disable-automatic-sat-synchronization.md): Stop syncing this RFC. Already-mirrored documents are retained; no new ones are pulled.
- [Read a SAT credential status](https://docs.newinvoice.dev/api-reference/fiscal_profiles/read-a-sat-credential-status.md): Read the saved credential's verification status and expiry. Never returns the password. 404 when no credential is saved.
- [Save a SAT credential (CIEC or FIEL)](https://docs.newinvoice.dev/api-reference/fiscal_profiles/save-a-sat-credential-ciec-or-fiel.md): Save the taxpayer's SAT password (CIEC), or their FIEL (e.firma), for this profile's RFC. Send either `password` or `fiel`. The credential is checked against SAT asynchronously, so a live response starts as `pending`; wait for the `fiscal_profile.sat_credential_verified` webhook or poll GET before r…
- [Revoke a SAT credential](https://docs.newinvoice.dev/api-reference/fiscal_profiles/revoke-a-sat-credential.md): Remove and revoke the saved credential. Takes effect here immediately; the revocation is retried in the background if it cannot complete right away.
- [List invoices](https://docs.newinvoice.dev/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.
- [Create an invoice](https://docs.newinvoice.dev/api-reference/invoices/create-an-invoice.md): Build and stamp a CFDI 4.0 from friendly JSON. The issuer comes from `fiscal_profile_id`, which is required in live mode. In test mode you may omit it while your organization has no test fiscal profile of its own: the invoice is issued from a default sandbox issuer (the SAT test RFC EKU9003173C9) wi…
- [Stamp a draft invoice](https://docs.newinvoice.dev/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.
- [Retrieve an invoice](https://docs.newinvoice.dev/api-reference/invoices/retrieve-an-invoice.md): Fetch one invoice by id. Pass `expand=fiscal_profile` to inline the issuer profile.
- [Download the CFDI XML](https://docs.newinvoice.dev/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.
- [Download the CFDI PDF](https://docs.newinvoice.dev/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.
- [Cancel an invoice](https://docs.newinvoice.dev/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.
- [Validate a CFDI](https://docs.newinvoice.dev/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.
- [Retrieve a validation](https://docs.newinvoice.dev/api-reference/validations/retrieve-a-validation.md): Fetch a previously run validation result by id.
- [List ticket invoices](https://docs.newinvoice.dev/api-reference/ticket_invoices/list-ticket-invoices.md): List ticket invoices newest-first with cursor pagination. Filter by status (extracting, processing, needs_review, completed, failed).
- [Self-invoice a ticket from a photo](https://docs.newinvoice.dev/api-reference/ticket_invoices/self-invoice-a-ticket-from-a-photo.md): Turn a merchant ticket (gas station, restaurant, retail) into a CFDI by uploading a photo. The simplest way is multipart — `curl -F photo=@ticket.jpg -F fiscal_profile_id=fp_... -F uso_cfdi=G03`; a JSON body with `photo_base64` also works. Processing is asynchronous: the response comes back `status:…
- [Retrieve a ticket invoice](https://docs.newinvoice.dev/api-reference/ticket_invoices/retrieve-a-ticket-invoice.md): Fetch one ticket invoice by id, including its current lifecycle status.
- [Download the CFDI XML](https://docs.newinvoice.dev/api-reference/ticket_invoices/download-the-cfdi-xml.md): Return the CFDI 4.0 XML the merchant portal emitted. Available only once the ticket invoice is `completed` — otherwise 409 ticket_invoice.xml_unavailable.
- [List learned portal recipes](https://docs.newinvoice.dev/api-reference/ticket_invoices/list-learned-portal-recipes.md): List the merchant self-invoice portals this organization has learned to navigate. Each recipe is replayed deterministically on the next ticket from the same portal; `confidence` and `times_used` grow with successful reuse.
- [List massive downloads](https://docs.newinvoice.dev/api-reference/downloads/list-massive-downloads.md): List your descarga masiva requests newest-first with cursor pagination.
- [Request a massive download](https://docs.newinvoice.dev/api-reference/downloads/request-a-massive-download.md): Download the CFDIs a taxpayer issued or received in a date range. A profile with a verified saved SAT password is served that way automatically (full XML only, at most 366 days and 2,000 invoices per download); otherwise the profile needs a FIEL. See the massive download guide for limits and partial…
- [Retrieve a massive download](https://docs.newinvoice.dev/api-reference/downloads/retrieve-a-massive-download.md): Fetch one descarga masiva request by id to check its status and package count.
- [List download packages](https://docs.newinvoice.dev/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.
- [Download the delivery report](https://docs.newinvoice.dev/api-reference/downloads/download-the-delivery-report.md): CSV listing each invoice in the download and its outcome, including the ones that were not delivered and why. Available when `result.report_url` is set.
- [Download a package](https://docs.newinvoice.dev/api-reference/downloads/download-a-package.md): Stream one descarga masiva package as a ZIP (application/zip) by its sequence number.
- [List CFDIs the SAT has on file](https://docs.newinvoice.dev/api-reference/sat_documents/list-cfdis-the-sat-has-on-file.md): Every CFDI the SAT holds for your synced RFCs — issued and received — newest first. Includes documents you never stamped through this API (a supplier invoicing you, or invoices issued before you integrated). Requires SAT sync enabled on at least one fiscal profile.
- [List fiscal documents](https://docs.newinvoice.dev/api-reference/fiscal_documents/list-fiscal-documents.md): List your fiscal documents newest-first with cursor pagination.
- [Request a constancia](https://docs.newinvoice.dev/api-reference/fiscal_documents/request-a-constancia.md): Request the taxpayer's constancia de situación fiscal as a PDF, using the SAT credential saved on the fiscal profile. Requires a `verified`, unexpired credential. Answers immediately with a `pending` resource; wait for the `fiscal_document.ready` webhook or poll GET. If a request for this profile is…
- [Retrieve a fiscal document](https://docs.newinvoice.dev/api-reference/fiscal_documents/retrieve-a-fiscal-document.md): Fetch one fiscal document by id to check its status.
- [Download the PDF](https://docs.newinvoice.dev/api-reference/fiscal_documents/download-the-pdf.md): Download the stored PDF (application/pdf). 409 `fiscal_document.not_ready` until the status is `ready`; 410 `fiscal_document.expired` after the retention period.
- [List webhook endpoints](https://docs.newinvoice.dev/api-reference/webhook_endpoints/list-webhook-endpoints.md): List your webhook endpoints newest-first with cursor pagination. Signing secrets are never included.
- [Create a webhook endpoint](https://docs.newinvoice.dev/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.
- [List webhook deliveries](https://docs.newinvoice.dev/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.
- [Retrieve a webhook endpoint](https://docs.newinvoice.dev/api-reference/webhook_endpoints/retrieve-a-webhook-endpoint.md): Fetch one webhook endpoint by id. The signing secret is never returned.
- [Delete a webhook endpoint](https://docs.newinvoice.dev/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.
- [Update a webhook endpoint](https://docs.newinvoice.dev/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.
- [List events](https://docs.newinvoice.dev/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.
- [Retrieve an event](https://docs.newinvoice.dev/api-reference/events/retrieve-an-event.md): Fetch one stored event by id, including the exact resource snapshot it delivered.
- [Resend an event](https://docs.newinvoice.dev/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 the stamping balance](https://docs.newinvoice.dev/api-reference/balance/retrieve-the-stamping-balance.md): Return the number of stamping transactions (timbres) remaining on your account for the current mode.
- [Get subscription and usage state](https://docs.newinvoice.dev/api-reference/billing/get-subscription-and-usage-state.md): The organization plan, subscription status, quota, live stamps consumed this calendar month, and SAT downloads billed this month with their prices. Test mode is always free.
- [Start a subscription checkout](https://docs.newinvoice.dev/api-reference/billing/start-a-subscription-checkout.md): Creates a hosted checkout session for a paid plan (starter, growth, scale) and returns its URL — send the browser there to pay. On completion the webhook activates the plan. An organization with an active subscription changes plans through the billing portal instead.
- [Open the billing portal](https://docs.newinvoice.dev/api-reference/billing/open-the-billing-portal.md): Creates a hosted billing-portal session (change plan, payment method, invoices, cancel) and returns its URL. Requires a billing account — i.e. at least one completed checkout.
- [List usage records](https://docs.newinvoice.dev/api-reference/usage/list-usage-records.md): List metered consumption newest-first with cursor pagination, plus the SAT downloads billed this month and their prices. Filter by kind and created_at date range to reconcile billing.
- [List SAT catalogs](https://docs.newinvoice.dev/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://docs.newinvoice.dev/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…
- [List every dated API version and how to pin one (public, no auth).](https://docs.newinvoice.dev/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.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


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