---
title: "Sandbox and testing"
description: "Run the full CFDI lifecycle against isolated test data, then rehearse retries and stamping rejections before you go to production."
language: en
canonical_url: "https://exac.mx/docs/en/sandbox"
md_url: "https://exac.mx/docs/en/sandbox.md"
---

# 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

- [Get organization](/docs/en/api/workspace/organization/get-organization): `GET /v1/organization`. Idempotency-Key: Not required.

### Issuers

- [List issuers](/docs/en/api/workspace/issuers/list-issuers): `GET /v1/issuers`. Idempotency-Key: Not required.

- [Create issuer](/docs/en/api/workspace/issuers/create-issuer): `POST /v1/issuers`. Idempotency-Key: Required.

- [Get issuer](/docs/en/api/workspace/issuers/get-issuer): `GET /v1/issuers/{rfc}`. Idempotency-Key: Not required.

- [Delete issuer](/docs/en/api/workspace/issuers/delete-issuer): `DELETE /v1/issuers/{rfc}`. Idempotency-Key: Required.

### Credentials

- [List webhook endpoints](/docs/en/api/workspace/credentials/list-webhook-endpoints): `GET /v1/organization/webhook-endpoints`. Idempotency-Key: Not required.

- [Create webhook endpoint](/docs/en/api/workspace/credentials/create-webhook-endpoint): `POST /v1/organization/webhook-endpoints`. Idempotency-Key: Required.

- [Get webhook endpoint](/docs/en/api/workspace/credentials/get-webhook-endpoint): `GET /v1/organization/webhook-endpoints/{endpointId}`. Idempotency-Key: Not required.

- [Update webhook endpoint](/docs/en/api/workspace/credentials/update-webhook-endpoint): `PATCH /v1/organization/webhook-endpoints/{endpointId}`. Idempotency-Key: Required.

- [Delete webhook endpoint](/docs/en/api/workspace/credentials/delete-webhook-endpoint): `DELETE /v1/organization/webhook-endpoints/{endpointId}`. Idempotency-Key: Required.

- [Rotate webhook signing secret](/docs/en/api/workspace/credentials/rotate-webhook-endpoint-secret): `POST /v1/organization/webhook-endpoints/{endpointId}/rotate-secret`. Idempotency-Key: Required.

- [List webhook deliveries](/docs/en/api/workspace/credentials/list-webhook-deliveries): `GET /v1/organization/webhook-endpoints/{endpointId}/deliveries`. Idempotency-Key: Not required.

- [Replay webhook delivery](/docs/en/api/workspace/credentials/replay-webhook-delivery): `POST /v1/organization/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/replay`. Idempotency-Key: Required.

- [Send test webhook event](/docs/en/api/workspace/credentials/test-webhook-endpoint): `POST /v1/organization/webhook-endpoints/{endpointId}/test`. Idempotency-Key: Required.

### Developer activity

- [List programmatic requests](/docs/en/api/workspace/developer-activity/list-programmatic-requests): `GET /v1/organization/activity`. Idempotency-Key: Not required.

- [Get programmatic request](/docs/en/api/workspace/developer-activity/get-programmatic-request): `GET /v1/organization/activity/{requestId}`. Idempotency-Key: Not required.

### Fiscal setup

- [Upload certificate](/docs/en/api/workspace/fiscal-setup/upload-certificate): `PUT /v1/organization/certificates/{kind}`. Idempotency-Key: Required. kind: `csd`.

- [Delete certificate](/docs/en/api/workspace/fiscal-setup/delete-certificate): `DELETE /v1/organization/certificates/{kind}`. Idempotency-Key: Required. kind: `csd`.

### Contacts

- [List contacts](/docs/en/api/catalog/contacts/list-contacts): `GET /v1/contacts`. Idempotency-Key: Not required.

- [Get contact](/docs/en/api/catalog/contacts/get-contact): `GET /v1/contacts/{contactId}`. Idempotency-Key: Not required.

- [Create contact](/docs/en/api/catalog/contacts/create-contact): `POST /v1/contacts`. Idempotency-Key: Required.

- [Update contact](/docs/en/api/catalog/contacts/update-contact): `PATCH /v1/contacts/{contactId}`. Idempotency-Key: Required.

- [Delete contact](/docs/en/api/catalog/contacts/delete-contact): `DELETE /v1/contacts/{contactId}`. Idempotency-Key: Required.

### SAT

- [Search SAT products](/docs/en/api/catalog/sat/search-sat-product-catalog): `GET /v1/reference/sat-products`. Idempotency-Key: Not required.

### Products

- [List products](/docs/en/api/catalog/products/list-products): `GET /v1/products`. Idempotency-Key: Not required.

- [Get product](/docs/en/api/catalog/products/get-product): `GET /v1/products/{productId}`. Idempotency-Key: Not required.

- [Create product](/docs/en/api/catalog/products/create-product): `POST /v1/products`. Idempotency-Key: Required.

- [Update product](/docs/en/api/catalog/products/update-product): `PATCH /v1/products/{productId}`. Idempotency-Key: Required.

- [Delete product](/docs/en/api/catalog/products/delete-product): `DELETE /v1/products/{productId}`. Idempotency-Key: Required.

- [List inventory movements](/docs/en/api/catalog/products/list-inventory-movements): `GET /v1/inventory-movements`. Idempotency-Key: Not required.

- [List inventory operations](/docs/en/api/catalog/products/list-inventory-movement-operations): `GET /v1/inventory-movement-operations`. Idempotency-Key: Not required.

- [List operation movements](/docs/en/api/catalog/products/list-inventory-operation-movements): `GET /v1/inventory-movement-operations/{operationId}/movements`. Idempotency-Key: Not required.

- [List inventory by location](/docs/en/api/catalog/products/list-product-inventory-levels): `GET /v1/products/{productId}/inventory-levels`. Idempotency-Key: Not required.

- [List product suppliers](/docs/en/api/catalog/products/list-product-suppliers): `GET /v1/products/{productId}/suppliers`. Idempotency-Key: Not required.

- [Update inventory](/docs/en/api/catalog/products/update-product-inventory): `POST /v1/products/{productId}/inventory`. Idempotency-Key: Required.

- [Receive supplier inventory](/docs/en/api/catalog/products/create-inventory-receipt): `POST /v1/inventory-receipts`. Idempotency-Key: Required.

### Employees

- [List employees](/docs/en/api/catalog/employees/list-employees): `GET /v1/employees`. Idempotency-Key: Not required.

- [Get employee](/docs/en/api/catalog/employees/get-employee): `GET /v1/employees/{employeeId}`. Idempotency-Key: Not required.

- [Create employee](/docs/en/api/catalog/employees/create-employee): `POST /v1/employees`. Idempotency-Key: Required.

- [Update employee](/docs/en/api/catalog/employees/update-employee): `PATCH /v1/employees/{employeeId}`. Idempotency-Key: Required.

- [Delete employee](/docs/en/api/catalog/employees/delete-employee): `DELETE /v1/employees/{employeeId}`. Idempotency-Key: Required.

### Locations

- [List locations](/docs/en/api/catalog/locations/list-locations): `GET /v1/settings/locations`. Idempotency-Key: Not required.

- [Get location](/docs/en/api/catalog/locations/get-location): `GET /v1/settings/locations/{locationId}`. Idempotency-Key: Not required.

- [Create location](/docs/en/api/catalog/locations/create-location): `POST /v1/settings/locations`. Idempotency-Key: Required.

- [Update location](/docs/en/api/catalog/locations/update-location): `PATCH /v1/settings/locations/{locationId}`. Idempotency-Key: Required.

- [Delete location](/docs/en/api/catalog/locations/delete-location): `DELETE /v1/settings/locations/{locationId}`. Idempotency-Key: Required.

### Settings

- [List sales receipt fields](/docs/en/api/catalog/settings/list-sales-receipt-fields): `GET /v1/settings/receipt-fields`. Idempotency-Key: Not required.

- [Get sales receipt field](/docs/en/api/catalog/settings/get-sales-receipt-field): `GET /v1/settings/receipt-fields/{fieldId}`. Idempotency-Key: Not required.

- [Create sales receipt field](/docs/en/api/catalog/settings/create-sales-receipt-field): `POST /v1/settings/receipt-fields`. Idempotency-Key: Required.

- [Update sales receipt field](/docs/en/api/catalog/settings/update-sales-receipt-field): `PATCH /v1/settings/receipt-fields/{fieldId}`. Idempotency-Key: Required.

- [Delete sales receipt field](/docs/en/api/catalog/settings/delete-sales-receipt-field): `DELETE /v1/settings/receipt-fields/{fieldId}`. Idempotency-Key: Required.

- [List sales receipt field values](/docs/en/api/catalog/settings/list-sales-receipt-field-values): `GET /v1/settings/receipt-fields/{fieldId}/values`. Idempotency-Key: Not required.

- [Get fiscal series](/docs/en/api/catalog/settings/get-fiscal-series): `GET /v1/settings/fiscal-series`. Idempotency-Key: Not required.

- [Update fiscal series](/docs/en/api/catalog/settings/update-fiscal-series): `PATCH /v1/settings/fiscal-series/{seriesId}`. Idempotency-Key: Required.

### Pricing

- [List customer prices](/docs/en/api/catalog/pricing/list-customer-prices): `GET /v1/pricing/customers/{customerId}`. Idempotency-Key: Not required.

- [Set customer price](/docs/en/api/catalog/pricing/set-customer-price): `PUT /v1/pricing/customers/{customerId}/products/{productId}`. Idempotency-Key: Required.

- [Delete customer price](/docs/en/api/catalog/pricing/delete-customer-price): `DELETE /v1/pricing/customers/{customerId}/products/{productId}`. Idempotency-Key: Required.

- [List location prices](/docs/en/api/catalog/pricing/list-location-prices): `GET /v1/pricing/locations/{locationId}`. Idempotency-Key: Not required.

- [Set location price](/docs/en/api/catalog/pricing/set-location-price): `PUT /v1/pricing/locations/{locationId}/products/{productId}`. Idempotency-Key: Required.

- [Delete location price](/docs/en/api/catalog/pricing/delete-location-price): `DELETE /v1/pricing/locations/{locationId}/products/{productId}`. Idempotency-Key: Required.

### Invoices

- [List invoices](/docs/en/api/documents/invoices/list-invoices): `GET /v1/invoices`. Idempotency-Key: Not required.

- [Get invoice](/docs/en/api/documents/invoices/get-invoice): `GET /v1/invoices/{documentRef}`. Idempotency-Key: Not required.

- [Create invoice draft](/docs/en/api/documents/invoices/create-invoice-draft): `POST /v1/invoices`. Idempotency-Key: Required.

- [Create invoice draft from sales receipts](/docs/en/api/documents/invoices/create-invoice-draft-from-sales-receipts): `POST /v1/invoices/from-sales-receipts`. Idempotency-Key: Required.

- [Update invoice draft](/docs/en/api/documents/invoices/update-invoice-draft): `PUT /v1/invoices/{documentRef}`. Idempotency-Key: Required.

- [Stamp invoice](/docs/en/api/documents/invoices/stamp-invoice): `POST /v1/invoices/{documentRef}/stamp`. Idempotency-Key: Required.

- [Cancel invoice](/docs/en/api/documents/invoices/cancel-invoice): `POST /v1/invoices/{documentRef}/cancel`. Idempotency-Key: Required.

- [Archive invoice](/docs/en/api/documents/invoices/archive-invoice): `PUT /v1/invoices/{documentRef}/archive`. Idempotency-Key: Required.

### Withholding documents

- [List withholdings](/docs/en/api/documents/withholding-documents/list-withholdings): `GET /v1/withholdings`. Idempotency-Key: Not required.

- [Get withholding](/docs/en/api/documents/withholding-documents/get-withholding): `GET /v1/withholdings/{documentRef}`. Idempotency-Key: Not required.

- [Cancel withholding](/docs/en/api/documents/withholding-documents/cancel-withholding): `POST /v1/withholdings/{documentRef}/cancel`. Idempotency-Key: Required.

- [Archive withholding](/docs/en/api/documents/withholding-documents/archive-withholding): `PUT /v1/withholdings/{documentRef}/archive`. Idempotency-Key: Required.

- [Create withholding](/docs/en/api/documents/withholding-documents/create-withholding): `POST /v1/withholdings`. Idempotency-Key: Required.

### Sales receipts

- [List sales receipts](/docs/en/api/documents/sales-receipts/list-sales-receipts): `GET /v1/sales-receipts`. Idempotency-Key: Not required.

- [Get sales receipt](/docs/en/api/documents/sales-receipts/get-sales-receipt): `GET /v1/sales-receipts/{documentRef}`. Idempotency-Key: Not required.

- [List sales receipt refunds](/docs/en/api/documents/sales-receipts/list-sales-receipt-refunds): `GET /v1/sales-receipt-refunds`. Idempotency-Key: Not required.

- [Get sales receipt refund](/docs/en/api/documents/sales-receipts/get-sales-receipt-refund): `GET /v1/sales-receipt-refunds/{documentRef}`. Idempotency-Key: Not required.

- [Create sales receipt](/docs/en/api/documents/sales-receipts/create-sales-receipt): `POST /v1/sales-receipts`. Idempotency-Key: Required.

- [Cancel sales receipt](/docs/en/api/documents/sales-receipts/cancel-sales-receipt): `POST /v1/sales-receipts/{documentRef}/cancel`. Idempotency-Key: Required.

- [Refund sales receipt](/docs/en/api/documents/sales-receipts/create-sales-receipt-refund): `POST /v1/sales-receipts/{documentRef}/refunds`. Idempotency-Key: Required.

### Files and delivery

- [Download document file](/docs/en/api/documents/files-and-delivery/download-document-file): `GET /v1/documents/{documentRef}/files/{file}`. Idempotency-Key: Not required. Sandbox document categories: `invoice`, `withholding`, `sales_receipt`.

### Payroll

- [Get payroll settings](/docs/en/api/documents/payroll/get-payroll-settings): `GET /v1/payroll/settings`. Idempotency-Key: Not required.

- [Update payroll settings](/docs/en/api/documents/payroll/update-payroll-settings): `PUT /v1/payroll/settings`. Idempotency-Key: Required.

- [List payroll runs](/docs/en/api/documents/payroll/list-payroll-runs): `GET /v1/payroll/runs`. Idempotency-Key: Not required.

- [Prepare payroll run](/docs/en/api/documents/payroll/prepare-payroll-run): `POST /v1/payroll/runs`. Idempotency-Key: Required.

- [Get payroll run](/docs/en/api/documents/payroll/get-payroll-run): `GET /v1/payroll/runs/{runId}`. Idempotency-Key: Not required.

- [Change payroll payment date](/docs/en/api/documents/payroll/update-payroll-run): `PATCH /v1/payroll/runs/{runId}`. Idempotency-Key: Required.

- [Recalculate payroll run](/docs/en/api/documents/payroll/recalculate-payroll-run): `POST /v1/payroll/runs/{runId}/recalculate`. Idempotency-Key: Required.

- [Stamp payroll receipts](/docs/en/api/documents/payroll/stamp-payroll-run): `POST /v1/payroll/runs/{runId}/stamp`. Idempotency-Key: Required.

- [Discard payroll run](/docs/en/api/documents/payroll/discard-payroll-run): `DELETE /v1/payroll/runs/{runId}`. Idempotency-Key: Required.

- [List payroll receipts](/docs/en/api/documents/payroll/list-payroll-rows): `GET /v1/payroll/runs/{runId}/rows`. Idempotency-Key: Not required.

- [Get payroll receipt](/docs/en/api/documents/payroll/get-payroll-row): `GET /v1/payroll/rows/{rowId}`. Idempotency-Key: Not required.

- [Update payroll receipt](/docs/en/api/documents/payroll/update-payroll-row): `PATCH /v1/payroll/rows/{rowId}`. Idempotency-Key: Required.

- [Prepare canceled receipt again](/docs/en/api/documents/payroll/prepare-payroll-row-again): `POST /v1/payroll/rows/{rowId}/prepare-again`. Idempotency-Key: Required.

- [Restamp rejected receipt](/docs/en/api/documents/payroll/restamp-payroll-row): `POST /v1/payroll/rows/{rowId}/restamp`. Idempotency-Key: Required.

### Accounts

- [List receivable accounts](/docs/en/api/accounts-payments/accounts/list-receivable-accounts): `GET /v1/accounts/receivables`. Idempotency-Key: Not required.

- [Get receivable account](/docs/en/api/accounts-payments/accounts/get-receivable-account): `GET /v1/accounts/receivables/{customerId}`. Idempotency-Key: Not required.

- [Archive or restore receivable invoice](/docs/en/api/accounts-payments/accounts/set-receivable-archived): `POST /v1/accounts/receivables/{customerId}/invoices/{documentRef}/archive`. Idempotency-Key: Required.

- [Plan sent invoice collections](/docs/en/api/accounts-payments/accounts/set-receivable-payment-plan): `PUT /v1/accounts/receivables/{customerId}/invoices/{documentRef}/plan`. Idempotency-Key: Required.

- [List payable accounts](/docs/en/api/accounts-payments/accounts/list-payable-accounts): `GET /v1/accounts/payables`. Idempotency-Key: Not required.

- [Get payable account](/docs/en/api/accounts-payments/accounts/get-payable-account): `GET /v1/accounts/payables/{supplierId}`. Idempotency-Key: Not required.

- [Archive or restore payable invoice](/docs/en/api/accounts-payments/accounts/set-payable-archived): `POST /v1/accounts/payables/{supplierId}/invoices/{documentRef}/archive`. Idempotency-Key: Required.

- [Plan received invoice payments](/docs/en/api/accounts-payments/accounts/set-payable-payment-plan): `PUT /v1/accounts/payables/{supplierId}/invoices/{documentRef}/plan`. Idempotency-Key: Required.

### Reports

- [Get income and expenses report](/docs/en/api/tax-reports/reports/get-income-expenses-report): `GET /v1/reports/income-expenses`. Idempotency-Key: Not required.

- [Get sales report](/docs/en/api/tax-reports/reports/get-sales-report): `GET /v1/reports/sales`. Idempotency-Key: Not required.

- [Get invoicing report](/docs/en/api/tax-reports/reports/get-invoicing-report): `GET /v1/reports/invoicing`. Idempotency-Key: Not required.

- [Get payroll report](/docs/en/api/tax-reports/reports/get-payroll-report): `GET /v1/reports/payroll`. Idempotency-Key: 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.

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](/docs/en/quickstart#sandbox-cfdi-lifecycle)

## 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.

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

- `CFDI40139`: Reserved value `RAZON SOCIAL NO REGISTRADA`. Set it in: The issuer legal name: legalName in POST /v1/issuers. Create the issuer, upload its CSD, and stamp with the Exac-Issuer header. Reported at: `issuer.legalName`. Correct it by: The API cannot rename an issuer. Delete it with DELETE /v1/issuers/{rfc} and create it again with the real legal name.

- `CFDI40148`: Reserved value `00148`. Set it in: The customer contact's address.postalCode, with address.country MEX, in POST /v1/contacts. Create the draft with that customerId. Reported at: `receiver.postalCode`. Correct it by: 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`: Reserved value `XNOM010101009`. Set it in: 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. Reported at: `employee.rfc`. Correct it by: 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

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](/docs/en/mcp)

## 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.

Complete documentation: https://exac.mx/docs/en.md
Agent documentation index: https://exac.mx/docs/en/llms.txt
