Docs

Sandbox

Sandbox and testing

Run the full CFDI lifecycle against isolated test data, then rehearse retries and stamping rejections before you go to production.

What the sandbox is

The sandbox is a separate deployment of the same REST contract. Nothing you do there touches production data, and nothing it produces is sent to SAT.

Base URL

https://api.sandbox.exac.mx

Production uses a different origin; see the API reference servers.

Credentials

Organization API keys created for the Test environment, which carry the api:sandbox permission. OAuth access tokens are not accepted. A sandbox key is rejected by production and a production key is rejected by the sandbox.

Documents

Stamping is simulated by Exac with no PAC call. Test CFDIs are not submitted to SAT, cannot be verified there, and have no fiscal validity.

Data

The sandbox organization, its contacts, drafts, and documents are isolated from your production organization. Sandbox certification is free.

Operations available in sandbox

Only the operations below exist on the sandbox server. This list is generated from the same operation contract as the runtime and the OpenAPI document, so it changes when the contract does.

Operations that are not listed are production-only and do not exist on the sandbox server.

Organization

OperationSummaryIdempotency-Key
GET /v1/organizationGet organizationNot required

Issuers

OperationSummaryIdempotency-Key
GET /v1/issuersList issuersNot required
POST /v1/issuersCreate issuerRequired
GET /v1/issuers/{rfc}Get issuerNot required
DELETE /v1/issuers/{rfc}Delete issuerRequired

Credentials

OperationSummaryIdempotency-Key
GET /v1/organization/webhook-endpointsList webhook endpointsNot required
POST /v1/organization/webhook-endpointsCreate webhook endpointRequired
GET /v1/organization/webhook-endpoints/{endpointId}Get webhook endpointNot required
PATCH /v1/organization/webhook-endpoints/{endpointId}Update webhook endpointRequired
DELETE /v1/organization/webhook-endpoints/{endpointId}Delete webhook endpointRequired
POST /v1/organization/webhook-endpoints/{endpointId}/rotate-secretRotate webhook signing secretRequired
GET /v1/organization/webhook-endpoints/{endpointId}/deliveriesList webhook deliveriesNot required
POST /v1/organization/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/replayReplay webhook deliveryRequired
POST /v1/organization/webhook-endpoints/{endpointId}/testSend test webhook eventRequired

Developer activity

OperationSummaryIdempotency-Key
GET /v1/organization/activityList programmatic requestsNot required
GET /v1/organization/activity/{requestId}Get programmatic requestNot required

Fiscal setup

OperationSummaryIdempotency-Key
PUT /v1/organization/certificates/{kind}Upload certificate

kind: csd

Required
DELETE /v1/organization/certificates/{kind}Delete certificate

kind: csd

Required

Contacts

OperationSummaryIdempotency-Key
GET /v1/contactsList contactsNot required
GET /v1/contacts/{contactId}Get contactNot required
POST /v1/contactsCreate contactRequired
PATCH /v1/contacts/{contactId}Update contactRequired
DELETE /v1/contacts/{contactId}Delete contactRequired

SAT

OperationSummaryIdempotency-Key
GET /v1/reference/sat-productsSearch SAT productsNot required

Products

OperationSummaryIdempotency-Key
GET /v1/productsList productsNot required
GET /v1/products/{productId}Get productNot required
POST /v1/productsCreate productRequired
PATCH /v1/products/{productId}Update productRequired
DELETE /v1/products/{productId}Delete productRequired
GET /v1/inventory-movementsList inventory movementsNot required
GET /v1/inventory-movement-operationsList inventory operationsNot required
GET /v1/inventory-movement-operations/{operationId}/movementsList operation movementsNot required
GET /v1/products/{productId}/inventory-levelsList inventory by locationNot required
GET /v1/products/{productId}/suppliersList product suppliersNot required
POST /v1/products/{productId}/inventoryUpdate inventoryRequired
POST /v1/inventory-receiptsReceive supplier inventoryRequired

Employees

OperationSummaryIdempotency-Key
GET /v1/employeesList employeesNot required
GET /v1/employees/{employeeId}Get employeeNot required
POST /v1/employeesCreate employeeRequired
PATCH /v1/employees/{employeeId}Update employeeRequired
DELETE /v1/employees/{employeeId}Delete employeeRequired

Locations

OperationSummaryIdempotency-Key
GET /v1/settings/locationsList locationsNot required
GET /v1/settings/locations/{locationId}Get locationNot required
POST /v1/settings/locationsCreate locationRequired
PATCH /v1/settings/locations/{locationId}Update locationRequired
DELETE /v1/settings/locations/{locationId}Delete locationRequired

Settings

OperationSummaryIdempotency-Key
GET /v1/settings/receipt-fieldsList sales receipt fieldsNot required
GET /v1/settings/receipt-fields/{fieldId}Get sales receipt fieldNot required
POST /v1/settings/receipt-fieldsCreate sales receipt fieldRequired
PATCH /v1/settings/receipt-fields/{fieldId}Update sales receipt fieldRequired
DELETE /v1/settings/receipt-fields/{fieldId}Delete sales receipt fieldRequired
GET /v1/settings/receipt-fields/{fieldId}/valuesList sales receipt field valuesNot required
GET /v1/settings/fiscal-seriesGet fiscal seriesNot required
PATCH /v1/settings/fiscal-series/{seriesId}Update fiscal seriesRequired

Pricing

OperationSummaryIdempotency-Key
GET /v1/pricing/customers/{customerId}List customer pricesNot required
PUT /v1/pricing/customers/{customerId}/products/{productId}Set customer priceRequired
DELETE /v1/pricing/customers/{customerId}/products/{productId}Delete customer priceRequired
GET /v1/pricing/locations/{locationId}List location pricesNot required
PUT /v1/pricing/locations/{locationId}/products/{productId}Set location priceRequired
DELETE /v1/pricing/locations/{locationId}/products/{productId}Delete location priceRequired

Invoices

OperationSummaryIdempotency-Key
GET /v1/invoicesList invoicesNot required
GET /v1/invoices/{documentRef}Get invoiceNot required
POST /v1/invoicesCreate invoice draftRequired
POST /v1/invoices/from-sales-receiptsCreate invoice draft from sales receiptsRequired
PUT /v1/invoices/{documentRef}Update invoice draftRequired
POST /v1/invoices/{documentRef}/stampStamp invoiceRequired
POST /v1/invoices/{documentRef}/cancelCancel invoiceRequired
PUT /v1/invoices/{documentRef}/archiveArchive invoiceRequired

Withholding documents

OperationSummaryIdempotency-Key
GET /v1/withholdingsList withholdingsNot required
GET /v1/withholdings/{documentRef}Get withholdingNot required
POST /v1/withholdings/{documentRef}/cancelCancel withholdingRequired
PUT /v1/withholdings/{documentRef}/archiveArchive withholdingRequired
POST /v1/withholdingsCreate withholdingRequired

Sales receipts

OperationSummaryIdempotency-Key
GET /v1/sales-receiptsList sales receiptsNot required
GET /v1/sales-receipts/{documentRef}Get sales receiptNot required
GET /v1/sales-receipt-refundsList sales receipt refundsNot required
GET /v1/sales-receipt-refunds/{documentRef}Get sales receipt refundNot required
POST /v1/sales-receiptsCreate sales receiptRequired
POST /v1/sales-receipts/{documentRef}/cancelCancel sales receiptRequired
POST /v1/sales-receipts/{documentRef}/refundsRefund sales receiptRequired

Files and delivery

OperationSummaryIdempotency-Key
GET /v1/documents/{documentRef}/files/{file}Download document file

Sandbox document categories: invoice, withholding, sales_receipt

Not required

Payroll

OperationSummaryIdempotency-Key
GET /v1/payroll/settingsGet payroll settingsNot required
PUT /v1/payroll/settingsUpdate payroll settingsRequired
GET /v1/payroll/runsList payroll runsNot required
POST /v1/payroll/runsPrepare payroll runRequired
GET /v1/payroll/runs/{runId}Get payroll runNot required
PATCH /v1/payroll/runs/{runId}Change payroll payment dateRequired
POST /v1/payroll/runs/{runId}/recalculateRecalculate payroll runRequired
POST /v1/payroll/runs/{runId}/stampStamp payroll receiptsRequired
DELETE /v1/payroll/runs/{runId}Discard payroll runRequired
GET /v1/payroll/runs/{runId}/rowsList payroll receiptsNot required
GET /v1/payroll/rows/{rowId}Get payroll receiptNot required
PATCH /v1/payroll/rows/{rowId}Update payroll receiptRequired
POST /v1/payroll/rows/{rowId}/prepare-againPrepare canceled receipt againRequired
POST /v1/payroll/rows/{rowId}/restampRestamp rejected receiptRequired

Accounts

OperationSummaryIdempotency-Key
GET /v1/accounts/receivablesList receivable accountsNot required
GET /v1/accounts/receivables/{customerId}Get receivable accountNot required
POST /v1/accounts/receivables/{customerId}/invoices/{documentRef}/archiveArchive or restore receivable invoiceRequired
PUT /v1/accounts/receivables/{customerId}/invoices/{documentRef}/planPlan sent invoice collectionsRequired
GET /v1/accounts/payablesList payable accountsNot required
GET /v1/accounts/payables/{supplierId}Get payable accountNot required
POST /v1/accounts/payables/{supplierId}/invoices/{documentRef}/archiveArchive or restore payable invoiceRequired
PUT /v1/accounts/payables/{supplierId}/invoices/{documentRef}/planPlan received invoice paymentsRequired

Reports

OperationSummaryIdempotency-Key
GET /v1/reports/income-expensesGet income and expenses reportNot required
GET /v1/reports/salesGet sales reportNot required
GET /v1/reports/invoicingGet invoicing reportNot required
GET /v1/reports/payrollGet payroll reportNot required

Run the full CFDI lifecycle

The sandbox CFDI lifecycle workflow creates a customer and a draft, stamps it, downloads the PDF, and cancels it. Its request bodies and per-step retry guidance live in the Quickstart workflows.

  1. Verify the organization GET /v1/organization
  2. Create a test customer POST /v1/contacts
  3. Create a CFDI draft POST /v1/invoices
  4. Create a test stamp POST /v1/invoices/invoice:invoice-example/stamp
  5. Download the test PDF GET /v1/documents/invoice:invoice-example/files/pdf
  6. Cancel the test CFDI POST /v1/invoices/invoice:invoice-example/cancel

Open the sandbox lifecycle workflow

Test retries and failures

Every write requires an Idempotency-Key. Rehearse these cases against the stamp operation before you rely on them in production.

Idempotent replay

Keys are kept for 7 days and scoped to the organization and calling identity. To simulate a timeout, send the stamp request, drop the connection before reading the response, and repeat the identical request.

You sendYou get
The same key, path, and body againThe original result is replayed and the document is not stamped a second time. Confirm with a read of the document.
The same key with a different body or operationidempotency_conflict. The request is refused. Use a new key for a changed request.
The same key while the first attempt is still runningoperation_in_progress. Wait for the Retry-After header, then repeat the exact request.
The same key after 7 daysDeduplication no longer applies. Read the document before submitting another write.

Simulate a stamping rejection

Sandbox has reserved values that stamp as the PAC rejection production would return. They cannot belong to a real taxpayer. The reported path is where the error points, not a field of the draft body: a draft does not accept an issuer or receiver object. Store the value in the record the draft is built from, create the draft from that record, then call the stamp operation.

SAT codeReserved valueSet it inReported atCorrect it by
CFDI40139RAZON SOCIAL NO REGISTRADAThe issuer legal name: legalName in POST /v1/issuers. Create the issuer, upload its CSD, and stamp with the Exac-Issuer header.issuer.legalNameThe API cannot rename an issuer. Delete it with DELETE /v1/issuers/{rfc} and create it again with the real legal name.
CFDI4014800148The customer contact's address.postalCode, with address.country MEX, in POST /v1/contacts. Create the draft with that customerId.receiver.postalCodePATCH /v1/contacts/{contactId} with a real postal code, replace the draft with PUT /v1/invoices/{documentRef} so it reads the contact again, then stamp.
NOM9XNOM010101009The employee rfc in POST /v1/employees. Prepare a payroll run that includes the employee, then stamp it with POST /v1/payroll/runs/{runId}/stamp.employee.rfcAn employee RFC cannot be changed: PATCH /v1/employees/{employeeId} rejects rfc as an unrecognized key. Create a replacement employee with POST /v1/employees and the real RFC, omit the rejected receipt with PATCH /v1/payroll/rows/{rowId} and excluded true, recalculate the run with POST /v1/payroll/runs/{runId}/recalculate, then stamp the run again with the expectedCount and expectedNet you read from the run. Each of these is a new request with a fresh Idempotency-Key.

A rejected CFDI stamp returns validation_error (HTTP 400) with details.retryable = false and the SAT code in details.issues[].code. The draft stays unstamped.

A rejected payroll receipt does not fail the request: it reads state rejected with rejectionCode set to the SAT code.

A synchronous CFDI rejection does not complete the operation, so after you correct the source record and the draft you can repeat the stamp request with the same key. Payroll differs: stamping a run or restamping a receipt completes its idempotent operation once the work is queued, so repeating the same key returns the stored result and stamps nothing. Recover a rejected receipt with the separate operations in the table, each with a fresh Idempotency-Key.

After an uncertain outcome

If a stamp ends with recovery_required, do not retry automatically and do not change the key. Read the document with the get-invoice operation, using details.document.documentRef from the error when present, and check its status.

The status refresh operation is production-only. In sandbox, the document read is the way to check the outcome.

What sandbox does not simulate

There is no switch to force provider_unavailable, a timeout, or another transient failure. Rehearse those paths with the dropped-connection replay above and with the reserved rejection values.

MCP in sandbox

The sandbox has its own MCP server, with the same tools minus the production-only ones. It takes sandbox API keys only. Create a draft, stamp it and cancel it over MCP the same way as over REST; stamps are simulated. MCP server

Before you go to production

  • Switch the base URL and replace the sandbox API key with a production key.
  • Run the lifecycle, a replayed stamp, and each rejection case above end to end.
  • Store the Idempotency-Key and the documentRef with every write, and branch on error.code rather than on the message.
  • Handle recovery_required by reading the document, never by changing the key.
  • Fund the prepaid wallet: production certification is billed from the first timbre.
  • Remember that operations missing from the sandbox list, and the MCP tools marked production only, are tested only in production.