Docs

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

Producció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ónResumenIdempotency-Key
GET /v1/organizationObtener organizaciónNo requerida

Emisores

OperaciónResumenIdempotency-Key
GET /v1/issuersListar emisoresNo requerida
POST /v1/issuersCrear emisorRequerida
GET /v1/issuers/{rfc}Obtener emisorNo requerida
DELETE /v1/issuers/{rfc}Eliminar emisorRequerida

Credenciales

OperaciónResumenIdempotency-Key
GET /v1/organization/webhook-endpointsListar endpoints de webhooksNo requerida
POST /v1/organization/webhook-endpointsCrear endpoint de webhooksRequerida
GET /v1/organization/webhook-endpoints/{endpointId}Consultar endpoint de webhooksNo requerida
PATCH /v1/organization/webhook-endpoints/{endpointId}Actualizar endpoint de webhooksRequerida
DELETE /v1/organization/webhook-endpoints/{endpointId}Eliminar endpoint de webhooksRequerida
POST /v1/organization/webhook-endpoints/{endpointId}/rotate-secretRotar secreto de firma del webhookRequerida
GET /v1/organization/webhook-endpoints/{endpointId}/deliveriesListar entregas de webhooksNo requerida
POST /v1/organization/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/replayReenviar entrega de webhookRequerida
POST /v1/organization/webhook-endpoints/{endpointId}/testEnviar evento de webhook de pruebaRequerida

Developer activity

OperaciónResumenIdempotency-Key
GET /v1/organization/activityListar solicitudes programáticasNo requerida
GET /v1/organization/activity/{requestId}Obtener solicitud programáticaNo requerida

Configuración fiscal

OperaciónResumenIdempotency-Key
PUT /v1/organization/certificates/{kind}Cargar certificado

kind: csd

Requerida
DELETE /v1/organization/certificates/{kind}Eliminar certificado

kind: csd

Requerida

Contactos

OperaciónResumenIdempotency-Key
GET /v1/contactsListar contactosNo requerida
GET /v1/contacts/{contactId}Obtener contactoNo requerida
POST /v1/contactsCrear contactoRequerida
PATCH /v1/contacts/{contactId}Actualizar contactoRequerida
DELETE /v1/contacts/{contactId}Eliminar contactoRequerida

SAT

OperaciónResumenIdempotency-Key
GET /v1/reference/sat-productsBuscar productos SATNo requerida

Productos

OperaciónResumenIdempotency-Key
GET /v1/productsListar productosNo requerida
GET /v1/products/{productId}Obtener productoNo requerida
POST /v1/productsCrear productoRequerida
PATCH /v1/products/{productId}Actualizar productoRequerida
DELETE /v1/products/{productId}Eliminar productoRequerida
GET /v1/inventory-movementsListar movimientos de inventarioNo requerida
GET /v1/inventory-movement-operationsListar operaciones de inventarioNo requerida
GET /v1/inventory-movement-operations/{operationId}/movementsListar movimientos de la operaciónNo requerida
GET /v1/products/{productId}/inventory-levelsListar existencias por sucursalNo requerida
GET /v1/products/{productId}/suppliersListar proveedores del productoNo requerida
POST /v1/products/{productId}/inventoryActualizar inventarioRequerida
POST /v1/inventory-receiptsRegistrar entrada de proveedorRequerida

Empleados

OperaciónResumenIdempotency-Key
GET /v1/employeesListar empleadosNo requerida
GET /v1/employees/{employeeId}Obtener empleadoNo requerida
POST /v1/employeesCrear empleadoRequerida
PATCH /v1/employees/{employeeId}Actualizar empleadoRequerida
DELETE /v1/employees/{employeeId}Eliminar empleadoRequerida

Sucursales

OperaciónResumenIdempotency-Key
GET /v1/settings/locationsListar sucursalesNo requerida
GET /v1/settings/locations/{locationId}Obtener sucursalNo requerida
POST /v1/settings/locationsCrear sucursalRequerida
PATCH /v1/settings/locations/{locationId}Actualizar sucursalRequerida
DELETE /v1/settings/locations/{locationId}Eliminar sucursalRequerida

Configuración

OperaciónResumenIdempotency-Key
GET /v1/settings/receipt-fieldsListar campos de recibo de ventaNo requerida
GET /v1/settings/receipt-fields/{fieldId}Obtener campo de recibo de ventaNo requerida
POST /v1/settings/receipt-fieldsCrear campo de recibo de ventaRequerida
PATCH /v1/settings/receipt-fields/{fieldId}Actualizar campo de recibo de ventaRequerida
DELETE /v1/settings/receipt-fields/{fieldId}Eliminar campo de recibo de ventaRequerida
GET /v1/settings/receipt-fields/{fieldId}/valuesListar valores de campo de reciboNo requerida
GET /v1/settings/fiscal-seriesObtener series fiscalesNo requerida
PATCH /v1/settings/fiscal-series/{seriesId}Actualizar series fiscalesRequerida

Precios

OperaciónResumenIdempotency-Key
GET /v1/pricing/customers/{customerId}Listar precios de clienteNo requerida
PUT /v1/pricing/customers/{customerId}/products/{productId}Definir precio de clienteRequerida
DELETE /v1/pricing/customers/{customerId}/products/{productId}Eliminar precio de clienteRequerida
GET /v1/pricing/locations/{locationId}Listar precios de sucursalNo requerida
PUT /v1/pricing/locations/{locationId}/products/{productId}Definir precio de sucursalRequerida
DELETE /v1/pricing/locations/{locationId}/products/{productId}Eliminar precio de sucursalRequerida

Facturas

OperaciónResumenIdempotency-Key
GET /v1/invoicesListar facturasNo requerida
GET /v1/invoices/{documentRef}Obtener facturaNo requerida
POST /v1/invoicesCrear borrador de facturaRequerida
POST /v1/invoices/from-sales-receiptsCrear borrador de factura desde recibos de ventaRequerida
PUT /v1/invoices/{documentRef}Actualizar borrador de facturaRequerida
POST /v1/invoices/{documentRef}/stampTimbrar facturaRequerida
POST /v1/invoices/{documentRef}/cancelCancelar facturaRequerida
PUT /v1/invoices/{documentRef}/archiveArchivar facturaRequerida

Documentos de retención

OperaciónResumenIdempotency-Key
GET /v1/withholdingsListar retencionesNo requerida
GET /v1/withholdings/{documentRef}Obtener retenciónNo requerida
POST /v1/withholdings/{documentRef}/cancelCancelar documento de retenciónRequerida
PUT /v1/withholdings/{documentRef}/archiveArchivar documento de retenciónRequerida
POST /v1/withholdingsCrear retenciónRequerida

Recibos de venta

OperaciónResumenIdempotency-Key
GET /v1/sales-receiptsListar recibos de ventaNo requerida
GET /v1/sales-receipts/{documentRef}Obtener recibo de ventaNo requerida
GET /v1/sales-receipt-refundsListar reembolsos de recibosNo requerida
GET /v1/sales-receipt-refunds/{documentRef}Obtener reembolso de reciboNo requerida
POST /v1/sales-receiptsCrear recibo de ventaRequerida
POST /v1/sales-receipts/{documentRef}/cancelCancelar recibo de ventaRequerida
POST /v1/sales-receipts/{documentRef}/refundsReembolsar recibo de ventaRequerida

Archivos y entrega

OperaciónResumenIdempotency-Key
GET /v1/documents/{documentRef}/files/{file}Descargar archivo

Categorías de documento en prueba: invoice, withholding, sales_receipt

No requerida

Nómina

OperaciónResumenIdempotency-Key
GET /v1/payroll/settingsObtener ajustes de nóminaNo requerida
PUT /v1/payroll/settingsActualizar ajustes de nóminaRequerida
GET /v1/payroll/runsListar nóminasNo requerida
POST /v1/payroll/runsPreparar nóminaRequerida
GET /v1/payroll/runs/{runId}Obtener nóminaNo requerida
PATCH /v1/payroll/runs/{runId}Cambiar fecha de pago de la nóminaRequerida
POST /v1/payroll/runs/{runId}/recalculateRecalcular nóminaRequerida
POST /v1/payroll/runs/{runId}/stampTimbrar recibos de nóminaRequerida
DELETE /v1/payroll/runs/{runId}Descartar nóminaRequerida
GET /v1/payroll/runs/{runId}/rowsListar recibos de nóminaNo requerida
GET /v1/payroll/rows/{rowId}Obtener recibo de nóminaNo requerida
PATCH /v1/payroll/rows/{rowId}Actualizar recibo de nóminaRequerida
POST /v1/payroll/rows/{rowId}/prepare-againPreparar de nuevo un recibo canceladoRequerida
POST /v1/payroll/rows/{rowId}/restampVolver a timbrar un recibo rechazadoRequerida

Cuentas

OperaciónResumenIdempotency-Key
GET /v1/accounts/receivablesListar cuentas por cobrarNo requerida
GET /v1/accounts/receivables/{customerId}Obtener cuenta por cobrarNo requerida
POST /v1/accounts/receivables/{customerId}/invoices/{documentRef}/archiveArchivar o restaurar factura por cobrarRequerida
PUT /v1/accounts/receivables/{customerId}/invoices/{documentRef}/planPlanificar cobros de factura emitidaRequerida
GET /v1/accounts/payablesListar cuentas por pagarNo requerida
GET /v1/accounts/payables/{supplierId}Obtener cuenta por pagarNo requerida
POST /v1/accounts/payables/{supplierId}/invoices/{documentRef}/archiveArchivar o restaurar factura por pagarRequerida
PUT /v1/accounts/payables/{supplierId}/invoices/{documentRef}/planPlanificar pagos de factura recibidaRequerida

Reportes

OperaciónResumenIdempotency-Key
GET /v1/reports/income-expensesObtener reporte de ingresos y gastosNo requerida
GET /v1/reports/salesObtener reporte de ventasNo requerida
GET /v1/reports/invoicingObtener reporte de facturaciónNo requerida
GET /v1/reports/payrollObtener reporte de nóminaNo 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.

  1. Verifica la organización GET /v1/organization
  2. Crea un cliente de prueba POST /v1/contacts
  3. Crea un borrador CFDI POST /v1/invoices
  4. Crea un timbrado de prueba POST /v1/invoices/invoice:invoice-example/stamp
  5. Descarga el PDF de prueba GET /v1/documents/invoice:invoice-example/files/pdf
  6. Cancela el CFDI de prueba POST /v1/invoices/invoice:invoice-example/cancel

Abrir el flujo del ciclo en sandbox

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íasObtienes
La misma clave, ruta y cuerpo otra vezSe 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ónidempotency_conflict. La solicitud se rechaza. Usa una clave nueva para una solicitud modificada.
La misma clave mientras el primer intento sigue en cursooperation_in_progress. Espera el encabezado Retry-After y repite la solicitud exacta.
La misma clave después de 7 díasYa 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 SATValor reservadoDónde ponerloSe reporta enCómo corregirlo
CFDI40139RAZON SOCIAL NO REGISTRADALa razón social del emisor: legalName en POST /v1/issuers. Crea el emisor, sube su CSD y timbra con el encabezado Exac-Issuer.issuer.legalNameLa API no permite renombrar un emisor. Elimínalo con DELETE /v1/issuers/{rfc} y créalo de nuevo con la razón social real.
CFDI4014800148El address.postalCode del contacto cliente, con address.country MEX, en POST /v1/contacts. Crea el borrador con ese customerId.receiver.postalCodeHaz 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.
NOM9XNOM010101009El 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.rfcEl 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

El sandbox tiene su propio servidor MCP, con las mismas herramientas salvo las exclusivas de producción. Solo acepta claves de API de sandbox. Crea un borrador, timbralo y cancélalo por MCP igual que por REST; los timbrados se simulan. Servidor MCP

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.