Sandbox
Sandbox y pruebas
Ejecuta el ciclo completo de un CFDI con datos de prueba aislados y ensaya reintentos y rechazos de timbrado antes de pasar a producción.
Qué es el sandbox
El sandbox es un despliegue independiente del mismo contrato REST. Nada de lo que hagas ahí toca datos de producción y nada de lo que genera se envía al SAT.
URL base
https://api.sandbox.exac.mxProducción usa otro origen; consulta los servidores en la referencia de la API.
Credenciales
API keys de organización creadas para el entorno de prueba, que incluyen el permiso api:sandbox. No se aceptan tokens de acceso OAuth. Producción rechaza una clave de sandbox y el sandbox rechaza una clave de producción.
Documentos
Exac simula el timbrado sin llamar al SAT, no se pueden verificar ahí y no tienen validez fiscal.
Datos
La organización de prueba, sus contactos, borradores y documentos están aislados de tu organización de producción. La certificación en sandbox es gratuita.
Operaciones disponibles en sandbox
Solo las operaciones siguientes existen en el servidor de prueba. La lista se genera desde el mismo contrato de operaciones que usan el runtime y el documento OpenAPI, así que cambia cuando cambia el contrato.
Las operaciones que no aparecen son solo de producción y no existen en el servidor de prueba.
Organización
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/organization | Obtener organización | No requerida |
Emisores
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/issuers | Listar emisores | No requerida |
POST /v1/issuers | Crear emisor | Requerida |
GET /v1/issuers/{rfc} | Obtener emisor | No requerida |
DELETE /v1/issuers/{rfc} | Eliminar emisor | Requerida |
Credenciales
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/organization/webhook-endpoints | Listar endpoints de webhooks | No requerida |
POST /v1/organization/webhook-endpoints | Crear endpoint de webhooks | Requerida |
GET /v1/organization/webhook-endpoints/{endpointId} | Consultar endpoint de webhooks | No requerida |
PATCH /v1/organization/webhook-endpoints/{endpointId} | Actualizar endpoint de webhooks | Requerida |
DELETE /v1/organization/webhook-endpoints/{endpointId} | Eliminar endpoint de webhooks | Requerida |
POST /v1/organization/webhook-endpoints/{endpointId}/rotate-secret | Rotar secreto de firma del webhook | Requerida |
GET /v1/organization/webhook-endpoints/{endpointId}/deliveries | Listar entregas de webhooks | No requerida |
POST /v1/organization/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/replay | Reenviar entrega de webhook | Requerida |
POST /v1/organization/webhook-endpoints/{endpointId}/test | Enviar evento de webhook de prueba | Requerida |
Developer activity
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/organization/activity | Listar solicitudes programáticas | No requerida |
GET /v1/organization/activity/{requestId} | Obtener solicitud programática | No requerida |
Configuración fiscal
| Operación | Resumen | Idempotency-Key |
|---|---|---|
PUT /v1/organization/certificates/{kind} | Cargar certificado kind: | Requerida |
DELETE /v1/organization/certificates/{kind} | Eliminar certificado kind: | Requerida |
Contactos
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/contacts | Listar contactos | No requerida |
GET /v1/contacts/{contactId} | Obtener contacto | No requerida |
POST /v1/contacts | Crear contacto | Requerida |
PATCH /v1/contacts/{contactId} | Actualizar contacto | Requerida |
DELETE /v1/contacts/{contactId} | Eliminar contacto | Requerida |
SAT
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/reference/sat-products | Buscar productos SAT | No requerida |
Productos
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/products | Listar productos | No requerida |
GET /v1/products/{productId} | Obtener producto | No requerida |
POST /v1/products | Crear producto | Requerida |
PATCH /v1/products/{productId} | Actualizar producto | Requerida |
DELETE /v1/products/{productId} | Eliminar producto | Requerida |
GET /v1/inventory-movements | Listar movimientos de inventario | No requerida |
GET /v1/inventory-movement-operations | Listar operaciones de inventario | No requerida |
GET /v1/inventory-movement-operations/{operationId}/movements | Listar movimientos de la operación | No requerida |
GET /v1/products/{productId}/inventory-levels | Listar existencias por sucursal | No requerida |
GET /v1/products/{productId}/suppliers | Listar proveedores del producto | No requerida |
POST /v1/products/{productId}/inventory | Actualizar inventario | Requerida |
POST /v1/inventory-receipts | Registrar entrada de proveedor | Requerida |
Empleados
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/employees | Listar empleados | No requerida |
GET /v1/employees/{employeeId} | Obtener empleado | No requerida |
POST /v1/employees | Crear empleado | Requerida |
PATCH /v1/employees/{employeeId} | Actualizar empleado | Requerida |
DELETE /v1/employees/{employeeId} | Eliminar empleado | Requerida |
Sucursales
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/settings/locations | Listar sucursales | No requerida |
GET /v1/settings/locations/{locationId} | Obtener sucursal | No requerida |
POST /v1/settings/locations | Crear sucursal | Requerida |
PATCH /v1/settings/locations/{locationId} | Actualizar sucursal | Requerida |
DELETE /v1/settings/locations/{locationId} | Eliminar sucursal | Requerida |
Configuración
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/settings/receipt-fields | Listar campos de recibo de venta | No requerida |
GET /v1/settings/receipt-fields/{fieldId} | Obtener campo de recibo de venta | No requerida |
POST /v1/settings/receipt-fields | Crear campo de recibo de venta | Requerida |
PATCH /v1/settings/receipt-fields/{fieldId} | Actualizar campo de recibo de venta | Requerida |
DELETE /v1/settings/receipt-fields/{fieldId} | Eliminar campo de recibo de venta | Requerida |
GET /v1/settings/receipt-fields/{fieldId}/values | Listar valores de campo de recibo | No requerida |
GET /v1/settings/fiscal-series | Obtener series fiscales | No requerida |
PATCH /v1/settings/fiscal-series/{seriesId} | Actualizar series fiscales | Requerida |
Precios
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/pricing/customers/{customerId} | Listar precios de cliente | No requerida |
PUT /v1/pricing/customers/{customerId}/products/{productId} | Definir precio de cliente | Requerida |
DELETE /v1/pricing/customers/{customerId}/products/{productId} | Eliminar precio de cliente | Requerida |
GET /v1/pricing/locations/{locationId} | Listar precios de sucursal | No requerida |
PUT /v1/pricing/locations/{locationId}/products/{productId} | Definir precio de sucursal | Requerida |
DELETE /v1/pricing/locations/{locationId}/products/{productId} | Eliminar precio de sucursal | Requerida |
Facturas
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/invoices | Listar facturas | No requerida |
GET /v1/invoices/{documentRef} | Obtener factura | No requerida |
POST /v1/invoices | Crear borrador de factura | Requerida |
POST /v1/invoices/from-sales-receipts | Crear borrador de factura desde recibos de venta | Requerida |
PUT /v1/invoices/{documentRef} | Actualizar borrador de factura | Requerida |
POST /v1/invoices/{documentRef}/stamp | Timbrar factura | Requerida |
POST /v1/invoices/{documentRef}/cancel | Cancelar factura | Requerida |
PUT /v1/invoices/{documentRef}/archive | Archivar factura | Requerida |
Documentos de retención
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/withholdings | Listar retenciones | No requerida |
GET /v1/withholdings/{documentRef} | Obtener retención | No requerida |
POST /v1/withholdings/{documentRef}/cancel | Cancelar documento de retención | Requerida |
PUT /v1/withholdings/{documentRef}/archive | Archivar documento de retención | Requerida |
POST /v1/withholdings | Crear retención | Requerida |
Recibos de venta
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/sales-receipts | Listar recibos de venta | No requerida |
GET /v1/sales-receipts/{documentRef} | Obtener recibo de venta | No requerida |
GET /v1/sales-receipt-refunds | Listar reembolsos de recibos | No requerida |
GET /v1/sales-receipt-refunds/{documentRef} | Obtener reembolso de recibo | No requerida |
POST /v1/sales-receipts | Crear recibo de venta | Requerida |
POST /v1/sales-receipts/{documentRef}/cancel | Cancelar recibo de venta | Requerida |
POST /v1/sales-receipts/{documentRef}/refunds | Reembolsar recibo de venta | Requerida |
Archivos y entrega
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/documents/{documentRef}/files/{file} | Descargar archivo Categorías de documento en prueba: | No requerida |
Nómina
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/payroll/settings | Obtener ajustes de nómina | No requerida |
PUT /v1/payroll/settings | Actualizar ajustes de nómina | Requerida |
GET /v1/payroll/runs | Listar nóminas | No requerida |
POST /v1/payroll/runs | Preparar nómina | Requerida |
GET /v1/payroll/runs/{runId} | Obtener nómina | No requerida |
PATCH /v1/payroll/runs/{runId} | Cambiar fecha de pago de la nómina | Requerida |
POST /v1/payroll/runs/{runId}/recalculate | Recalcular nómina | Requerida |
POST /v1/payroll/runs/{runId}/stamp | Timbrar recibos de nómina | Requerida |
DELETE /v1/payroll/runs/{runId} | Descartar nómina | Requerida |
GET /v1/payroll/runs/{runId}/rows | Listar recibos de nómina | No requerida |
GET /v1/payroll/rows/{rowId} | Obtener recibo de nómina | No requerida |
PATCH /v1/payroll/rows/{rowId} | Actualizar recibo de nómina | Requerida |
POST /v1/payroll/rows/{rowId}/prepare-again | Preparar de nuevo un recibo cancelado | Requerida |
POST /v1/payroll/rows/{rowId}/restamp | Volver a timbrar un recibo rechazado | Requerida |
Cuentas
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/accounts/receivables | Listar cuentas por cobrar | No requerida |
GET /v1/accounts/receivables/{customerId} | Obtener cuenta por cobrar | No requerida |
POST /v1/accounts/receivables/{customerId}/invoices/{documentRef}/archive | Archivar o restaurar factura por cobrar | Requerida |
PUT /v1/accounts/receivables/{customerId}/invoices/{documentRef}/plan | Planificar cobros de factura emitida | Requerida |
GET /v1/accounts/payables | Listar cuentas por pagar | No requerida |
GET /v1/accounts/payables/{supplierId} | Obtener cuenta por pagar | No requerida |
POST /v1/accounts/payables/{supplierId}/invoices/{documentRef}/archive | Archivar o restaurar factura por pagar | Requerida |
PUT /v1/accounts/payables/{supplierId}/invoices/{documentRef}/plan | Planificar pagos de factura recibida | Requerida |
Reportes
| Operación | Resumen | Idempotency-Key |
|---|---|---|
GET /v1/reports/income-expenses | Obtener reporte de ingresos y gastos | No requerida |
GET /v1/reports/sales | Obtener reporte de ventas | No requerida |
GET /v1/reports/invoicing | Obtener reporte de facturación | No requerida |
GET /v1/reports/payroll | Obtener reporte de nómina | No requerida |
Ejecuta el ciclo completo de un CFDI
El flujo del ciclo de un CFDI en sandbox crea un cliente y un borrador, lo timbra, descarga el PDF y lo cancela. Sus cuerpos de solicitud y la guía de reintentos de cada paso están en los flujos del Inicio rápido.
- Verifica la organización
GET /v1/organization - Crea un cliente de prueba
POST /v1/contacts - Crea un borrador CFDI
POST /v1/invoices - Crea un timbrado de prueba
POST /v1/invoices/invoice:invoice-example/stamp - Descarga el PDF de prueba
GET /v1/documents/invoice:invoice-example/files/pdf - Cancela el CFDI de prueba
POST /v1/invoices/invoice:invoice-example/cancel
Prueba reintentos y fallas
Toda escritura requiere Idempotency-Key. Ensaya estos casos con la operación de timbrado antes de depender de ellos en producción.
Repetición idempotente
Las claves se conservan 7 días y se limitan a la organización y a la identidad que llama. Para simular un timeout, envía la solicitud de timbrado, corta la conexión antes de leer la respuesta y repite la solicitud idéntica.
| Envías | Obtienes |
|---|---|
| La misma clave, ruta y cuerpo otra vez | Se repite el resultado original y el documento no se timbra por segunda vez. Confírmalo leyendo el documento. |
| La misma clave con otro cuerpo u otra operación | idempotency_conflict. La solicitud se rechaza. Usa una clave nueva para una solicitud modificada. |
| La misma clave mientras el primer intento sigue en curso | operation_in_progress. Espera el encabezado Retry-After y repite la solicitud exacta. |
| La misma clave después de 7 días | Ya no hay deduplicación. Lee el documento antes de enviar otra escritura. |
Simula un rechazo de timbrado
El sandbox reserva valores que se timbran como el rechazo del SAT que daría producción. No pueden pertenecer a un contribuyente real. La ruta reportada indica dónde apunta el error, no es un campo del cuerpo del borrador: un borrador no acepta un objeto issuer ni receiver. Guarda el valor en el registro del que se construye el borrador, crea el borrador a partir de ese registro y llama a la operación de timbrado.
| Código SAT | Valor reservado | Dónde ponerlo | Se reporta en | Cómo corregirlo |
|---|---|---|---|---|
CFDI40139 | RAZON SOCIAL NO REGISTRADA | La razón social del emisor: legalName en POST /v1/issuers. Crea el emisor, sube su CSD y timbra con el encabezado Exac-Issuer. | issuer.legalName | La API no permite renombrar un emisor. Elimínalo con DELETE /v1/issuers/{rfc} y créalo de nuevo con la razón social real. |
CFDI40148 | 00148 | El address.postalCode del contacto cliente, con address.country MEX, en POST /v1/contacts. Crea el borrador con ese customerId. | receiver.postalCode | Haz PATCH /v1/contacts/{contactId} con un código postal real, reemplaza el borrador con PUT /v1/invoices/{documentRef} para que lea de nuevo el contacto y timbra. |
NOM9 | XNOM010101009 | El rfc del empleado en POST /v1/employees. Prepara una nómina que incluya al empleado y timbra con POST /v1/payroll/runs/{runId}/stamp. | employee.rfc | El RFC de un empleado no se puede cambiar: PATCH /v1/employees/{employeeId} rechaza rfc como clave no reconocida. Crea un empleado de reemplazo con POST /v1/employees y el RFC real, omite el recibo rechazado con PATCH /v1/payroll/rows/{rowId} y excluded true, recalcula la nómina con POST /v1/payroll/runs/{runId}/recalculate y vuelve a timbrarla con el expectedCount y el expectedNet que leas en la nómina. Cada una es una solicitud nueva con un Idempotency-Key nuevo. |
Un timbrado de CFDI rechazado devuelve validation_error (HTTP 400) con details.retryable = false y el código del SAT en details.issues[].code. El borrador queda sin timbrar.
Un recibo de nómina rechazado no hace fallar la solicitud: se lee con state rejected y rejectionCode con el código del SAT.
Un rechazo síncrono de CFDI no completa la operación, así que después de corregir el registro de origen y el borrador puedes repetir la solicitud de timbrado con la misma clave. La nómina es distinta: timbrar una nómina o volver a timbrar un recibo completa su operación idempotente en cuanto el trabajo queda en cola, así que repetir la misma clave devuelve el resultado guardado y no timbra nada. Recupera un recibo rechazado con las operaciones separadas de la tabla, cada una con un Idempotency-Key nuevo.
Después de un resultado incierto
Si un timbrado termina con recovery_required, no reintentes automáticamente ni cambies la clave. Lee el documento con la operación de consulta de factura, usando details.document.documentRef del error cuando exista, y revisa su estado.
La operación para refrescar el estado es solo de producción. En sandbox, la lectura del documento es la forma de verificar el resultado.
Lo que el sandbox no simula
No hay un interruptor para forzar provider_unavailable, un timeout u otra falla transitoria. Ensaya esas rutas con la repetición tras cortar la conexión y con los valores de rechazo reservados.
MCP en sandbox
Antes de pasar a producción
- Cambia la URL base y reemplaza la API key de sandbox por una de producción.
- Ejecuta de punta a punta el ciclo, un timbrado repetido y cada caso de rechazo anterior.
- Guarda el Idempotency-Key y el documentRef de cada escritura, y decide según error.code, no según el mensaje.
- Atiende recovery_required leyendo el documento, nunca cambiando la clave.
- Fondea el monedero prepagado: la certificación en producción se cobra desde el primer timbre.
- Recuerda que las operaciones ausentes de la lista de sandbox, y las herramientas MCP marcadas solo producción, se prueban únicamente en producción.