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.mxProduction 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
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/organization | Get organization | Not required |
Issuers
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/issuers | List issuers | Not required |
POST /v1/issuers | Create issuer | Required |
GET /v1/issuers/{rfc} | Get issuer | Not required |
DELETE /v1/issuers/{rfc} | Delete issuer | Required |
Credentials
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/organization/webhook-endpoints | List webhook endpoints | Not required |
POST /v1/organization/webhook-endpoints | Create webhook endpoint | Required |
GET /v1/organization/webhook-endpoints/{endpointId} | Get webhook endpoint | Not required |
PATCH /v1/organization/webhook-endpoints/{endpointId} | Update webhook endpoint | Required |
DELETE /v1/organization/webhook-endpoints/{endpointId} | Delete webhook endpoint | Required |
POST /v1/organization/webhook-endpoints/{endpointId}/rotate-secret | Rotate webhook signing secret | Required |
GET /v1/organization/webhook-endpoints/{endpointId}/deliveries | List webhook deliveries | Not required |
POST /v1/organization/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/replay | Replay webhook delivery | Required |
POST /v1/organization/webhook-endpoints/{endpointId}/test | Send test webhook event | Required |
Developer activity
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/organization/activity | List programmatic requests | Not required |
GET /v1/organization/activity/{requestId} | Get programmatic request | Not required |
Fiscal setup
| Operation | Summary | Idempotency-Key |
|---|---|---|
PUT /v1/organization/certificates/{kind} | Upload certificate kind: | Required |
DELETE /v1/organization/certificates/{kind} | Delete certificate kind: | Required |
Contacts
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/contacts | List contacts | Not required |
GET /v1/contacts/{contactId} | Get contact | Not required |
POST /v1/contacts | Create contact | Required |
PATCH /v1/contacts/{contactId} | Update contact | Required |
DELETE /v1/contacts/{contactId} | Delete contact | Required |
SAT
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/reference/sat-products | Search SAT products | Not required |
Products
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/products | List products | Not required |
GET /v1/products/{productId} | Get product | Not required |
POST /v1/products | Create product | Required |
PATCH /v1/products/{productId} | Update product | Required |
DELETE /v1/products/{productId} | Delete product | Required |
GET /v1/inventory-movements | List inventory movements | Not required |
GET /v1/inventory-movement-operations | List inventory operations | Not required |
GET /v1/inventory-movement-operations/{operationId}/movements | List operation movements | Not required |
GET /v1/products/{productId}/inventory-levels | List inventory by location | Not required |
GET /v1/products/{productId}/suppliers | List product suppliers | Not required |
POST /v1/products/{productId}/inventory | Update inventory | Required |
POST /v1/inventory-receipts | Receive supplier inventory | Required |
Employees
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/employees | List employees | Not required |
GET /v1/employees/{employeeId} | Get employee | Not required |
POST /v1/employees | Create employee | Required |
PATCH /v1/employees/{employeeId} | Update employee | Required |
DELETE /v1/employees/{employeeId} | Delete employee | Required |
Locations
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/settings/locations | List locations | Not required |
GET /v1/settings/locations/{locationId} | Get location | Not required |
POST /v1/settings/locations | Create location | Required |
PATCH /v1/settings/locations/{locationId} | Update location | Required |
DELETE /v1/settings/locations/{locationId} | Delete location | Required |
Settings
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/settings/receipt-fields | List sales receipt fields | Not required |
GET /v1/settings/receipt-fields/{fieldId} | Get sales receipt field | Not required |
POST /v1/settings/receipt-fields | Create sales receipt field | Required |
PATCH /v1/settings/receipt-fields/{fieldId} | Update sales receipt field | Required |
DELETE /v1/settings/receipt-fields/{fieldId} | Delete sales receipt field | Required |
GET /v1/settings/receipt-fields/{fieldId}/values | List sales receipt field values | Not required |
GET /v1/settings/fiscal-series | Get fiscal series | Not required |
PATCH /v1/settings/fiscal-series/{seriesId} | Update fiscal series | Required |
Pricing
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/pricing/customers/{customerId} | List customer prices | Not required |
PUT /v1/pricing/customers/{customerId}/products/{productId} | Set customer price | Required |
DELETE /v1/pricing/customers/{customerId}/products/{productId} | Delete customer price | Required |
GET /v1/pricing/locations/{locationId} | List location prices | Not required |
PUT /v1/pricing/locations/{locationId}/products/{productId} | Set location price | Required |
DELETE /v1/pricing/locations/{locationId}/products/{productId} | Delete location price | Required |
Invoices
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/invoices | List invoices | Not required |
GET /v1/invoices/{documentRef} | Get invoice | Not required |
POST /v1/invoices | Create invoice draft | Required |
POST /v1/invoices/from-sales-receipts | Create invoice draft from sales receipts | Required |
PUT /v1/invoices/{documentRef} | Update invoice draft | Required |
POST /v1/invoices/{documentRef}/stamp | Stamp invoice | Required |
POST /v1/invoices/{documentRef}/cancel | Cancel invoice | Required |
PUT /v1/invoices/{documentRef}/archive | Archive invoice | Required |
Withholding documents
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/withholdings | List withholdings | Not required |
GET /v1/withholdings/{documentRef} | Get withholding | Not required |
POST /v1/withholdings/{documentRef}/cancel | Cancel withholding | Required |
PUT /v1/withholdings/{documentRef}/archive | Archive withholding | Required |
POST /v1/withholdings | Create withholding | Required |
Sales receipts
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/sales-receipts | List sales receipts | Not required |
GET /v1/sales-receipts/{documentRef} | Get sales receipt | Not required |
GET /v1/sales-receipt-refunds | List sales receipt refunds | Not required |
GET /v1/sales-receipt-refunds/{documentRef} | Get sales receipt refund | Not required |
POST /v1/sales-receipts | Create sales receipt | Required |
POST /v1/sales-receipts/{documentRef}/cancel | Cancel sales receipt | Required |
POST /v1/sales-receipts/{documentRef}/refunds | Refund sales receipt | Required |
Files and delivery
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/documents/{documentRef}/files/{file} | Download document file Sandbox document categories: | Not required |
Payroll
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/payroll/settings | Get payroll settings | Not required |
PUT /v1/payroll/settings | Update payroll settings | Required |
GET /v1/payroll/runs | List payroll runs | Not required |
POST /v1/payroll/runs | Prepare payroll run | Required |
GET /v1/payroll/runs/{runId} | Get payroll run | Not required |
PATCH /v1/payroll/runs/{runId} | Change payroll payment date | Required |
POST /v1/payroll/runs/{runId}/recalculate | Recalculate payroll run | Required |
POST /v1/payroll/runs/{runId}/stamp | Stamp payroll receipts | Required |
DELETE /v1/payroll/runs/{runId} | Discard payroll run | Required |
GET /v1/payroll/runs/{runId}/rows | List payroll receipts | Not required |
GET /v1/payroll/rows/{rowId} | Get payroll receipt | Not required |
PATCH /v1/payroll/rows/{rowId} | Update payroll receipt | Required |
POST /v1/payroll/rows/{rowId}/prepare-again | Prepare canceled receipt again | Required |
POST /v1/payroll/rows/{rowId}/restamp | Restamp rejected receipt | Required |
Accounts
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/accounts/receivables | List receivable accounts | Not required |
GET /v1/accounts/receivables/{customerId} | Get receivable account | Not required |
POST /v1/accounts/receivables/{customerId}/invoices/{documentRef}/archive | Archive or restore receivable invoice | Required |
PUT /v1/accounts/receivables/{customerId}/invoices/{documentRef}/plan | Plan sent invoice collections | Required |
GET /v1/accounts/payables | List payable accounts | Not required |
GET /v1/accounts/payables/{supplierId} | Get payable account | Not required |
POST /v1/accounts/payables/{supplierId}/invoices/{documentRef}/archive | Archive or restore payable invoice | Required |
PUT /v1/accounts/payables/{supplierId}/invoices/{documentRef}/plan | Plan received invoice payments | Required |
Reports
| Operation | Summary | Idempotency-Key |
|---|---|---|
GET /v1/reports/income-expenses | Get income and expenses report | Not required |
GET /v1/reports/sales | Get sales report | Not required |
GET /v1/reports/invoicing | Get invoicing report | Not required |
GET /v1/reports/payroll | Get payroll report | Not 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.
- Verify the organization
GET /v1/organization - Create a test customer
POST /v1/contacts - Create a CFDI draft
POST /v1/invoices - Create a test stamp
POST /v1/invoices/invoice:invoice-example/stamp - Download the test PDF
GET /v1/documents/invoice:invoice-example/files/pdf - Cancel the test CFDI
POST /v1/invoices/invoice:invoice-example/cancel
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 send | You get |
|---|---|
| The same key, path, and body again | The 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 operation | idempotency_conflict. The request is refused. Use a new key for a changed request. |
| The same key while the first attempt is still running | operation_in_progress. Wait for the Retry-After header, then repeat the exact request. |
| The same key after 7 days | Deduplication 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 code | Reserved value | Set it in | Reported at | Correct it by |
|---|---|---|---|---|
CFDI40139 | RAZON SOCIAL NO REGISTRADA | The issuer legal name: legalName in POST /v1/issuers. Create the issuer, upload its CSD, and stamp with the Exac-Issuer header. | issuer.legalName | The API cannot rename an issuer. Delete it with DELETE /v1/issuers/{rfc} and create it again with the real legal name. |
CFDI40148 | 00148 | The customer contact's address.postalCode, with address.country MEX, in POST /v1/contacts. Create the draft with that customerId. | receiver.postalCode | PATCH /v1/contacts/{contactId} with a real postal code, replace the draft with PUT /v1/invoices/{documentRef} so it reads the contact again, then stamp. |
NOM9 | XNOM010101009 | The 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.rfc | An 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
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.