Misma API v5
Mismos endpoints, mismos campos y mismas respuestas que en producción. Solo cambian la URL base y la llave.
Prueba todo, sin romper nada.
El sandbox es un ambiente de pruebas gratuito con la misma API v5 que producción. Timbra con un PAC de pruebas, así que los CFDI que generes no tienen validez fiscal. Cuando tu integración funcione, cambias la URL base y la llave.
Factura Digital · API v5Sandbox
POST
https://sandbox-app.facturadigital.com.mx/api/v5/invoice/create
application/x-www-form-urlencoded
json={"Version": "4.0","Serie": "A","Folio": "AUTO","Fecha": "AUTO","Receptor": {"Rfc": "XIA190128J61","Nombre": "XENON INDUSTRIAL ARTICLES","UsoCFDI": "G03"},"Conceptos": [ ... ],...}
Respuesta200 OK
{"message": "The document was generated successfully","code": 200,"cfdi": {"UUID": "6FA90F39-2D7A-4F1C-9C4D-AC2B11D9F6E0","FechaTimbrado": "2026-09-23T10:15:30","XmlBase64": "PD94bWwgdmVyc2lvbj0i...","PDF": "https://sandbox-app.facturadigital.com.mx/docs/pdf/6FA90F39-2D7A-4F1C-9C4D-AC2B11D9F6E0","XML": "https://sandbox-app.facturadigital.com.mx/docs/xml/..."}}
Interfaz de muestra con llamadas reales de la API v5 contra el sandbox; los valores son de ejemplo. La referencia completa está en docs.facturadigital.com.mx.
La misma API, con timbrado de prueba
Lo que funciona igual que en producción y lo que cambia en el sandbox.
PAC de pruebas
El sandbox siempre timbra con un PAC de pruebas. Los CFDI que generes ahí no tienen validez fiscal.
PDF marcado como prueba
El PDF de cada CFDI de prueba lleva la marca «Timbrado de prueba» y «Sin validez fiscal».
Correos que no salen
Si pides el envío por correo (enviar_mail), el mensaje no llega al destinatario real: fuera de producción se desvía a un buzón de pruebas.
Una llave por ambiente
Tu llave de sandbox no sirve en producción ni al revés. Si las cruzas, el error te dice qué ambiente respondió.
Cuenta aparte
Tu cuenta de sandbox es independiente de la de producción: sus CFDI, llaves y plantillas de PDF no se mezclan.
Errores que puedes provocar a propósito
Los errores responden con HTTP 400 y un code interno en el cuerpo. Estos los reproduces en el sandbox para probar cómo reacciona tu sistema.
Llave inválida o de otro ambiente
code 501El mensaje termina con el ambiente que respondió, por ejemplo [Environment: SANDBOX].
Llama sin el header X-Api-Key o con tu llave de producciónSin CSD cargado
code 602Para sellar el XML, la cuenta necesita un Certificado de Sello Digital activo.
POST /invoice/create antes de subir tu CSDSin créditos
code 601Cada CFDI timbrado usa 1 crédito; sin saldo, no se timbra.
Timbra cuando GET /account/balance devuelve 0JSON faltante
code 400La respuesta indica que no recibió el JSON: «Invalid or non received json in headers or body.»
POST /invoice/create sin el campo jsonNo cumple el esquema del SAT
code 702Responde con errorType cfdi_schema_validation y el detalle de cada error en el campo errors.
Envía un CFDI que no cumple el Anexo 20Cancelación sin UUID
code 400La cancelación recibe sus parámetros (UUID, MOTIVO) como headers, no en el body.
POST /invoice/cancel sin el header UUIDLos mismos endpoints que en producción
Lo que integras en el sandbox funciona igual en producción.
Timbrar por JSON
POST /invoice/create: envías el CFDI en JSON y la API arma el XML, lo sella con tu CSD y lo timbra.
Timbrar XML sellado
POST /invoice/stampxml (Base64) y /invoice/stampxmlfile (archivo) para XML que ya sellaste con tu CSD.
Cancelar
POST /invoice/cancel con motivos 01 a 04, o /invoice/cancelwithcsd enviando el CSD en la petición.
Consultar
GET /invoice/list, listextended, listpayments, listreceived, listbydaterange y listwithfilters.
Cuenta
GET /account/authorize para obtener tu llave y GET /account/balance para consultar tus créditos.
Mismas respuestas
Éxito con HTTP 200 y code 200; los errores de validación, llave, saldo o certificado, con HTTP 400 y un code interno (501, 601, 602, 702…).
Paso a producción
Tu código no cambia: solo la URL base y la llave.
- 01
Integras contra el sandbox
https://sandbox-app.facturadigital.com.mx/api/v5 - 02
Subes tu CSD en tu cuenta de producción
Configuración → Certificados - 03
Cambias la llave
X-Api-Key: <llave de producción> - 04
Cambias la URL base
https://app.facturadigital.com.mx/api/v5
El mismo código timbra en producción con tus folios, que no caducan.
También en la API v5
WebhooksNuevo
Avisos a tu sistema cuando se timbra o se cancela un CFDI, o cuando se registra un pago.
SDKs oficialesNuevo
Librerías para Node.js, PHP y Python que llaman a la misma API v5.
Servidor MCPNuevo
Conecta Claude, ChatGPT o Gemini a tu cuenta. El asistente prepara la factura y tú confirmas.
Preguntas frecuentes
¿Cuesta usar el sandbox?
No. El sandbox es gratis. Es un ambiente aparte, así que lo que timbres ahí no usa los folios de tu cuenta de producción.
¿Los CFDI del sandbox tienen validez fiscal?
No. El sandbox siempre timbra con un PAC de pruebas: los CFDI no tienen validez fiscal y el PDF lo indica con la marca «Timbrado de prueba» y «Sin validez fiscal».
¿Cómo distingo sandbox de producción en mi código?
Por la URL base (https://sandbox-app.facturadigital.com.mx/api/v5 contra https://app.facturadigital.com.mx/api/v5) y por la llave: cada ambiente tiene la suya. Si usas la llave de un ambiente en el otro, la API responde con code 501 y el mensaje termina con el ambiente que respondió, por ejemplo [Environment: SANDBOX].
¿Cómo obtengo mi llave de sandbox?
Igual que en producción, pero en tu cuenta de sandbox: la copias de Configuración → Datos de facturación o la obtienes con GET /account/authorize enviando tu usuario y contraseña en los headers API-USUARIO y API-PASSWORD. Va en el header X-Api-Key, codificada en Base64.
¿Se envían correos desde el sandbox?
No a tus clientes. Fuera de producción, los correos (por ejemplo, con enviar_mail) se desvían a un buzón de pruebas.
¿Puedo probar con los SDKs oficiales?
Sí. Los SDKs llaman a la misma API v5; para el sandbox usas la URL base y la llave de pruebas.
¿Qué errores del PAC debo manejar?
Dos: code 5037 significa que no se pudo conectar con el PAC; no se envió nada y puedes reintentar. Code 5034 significa que el PAC no respondió; el CFDI pudo haberse timbrado, así que revisa en el SAT antes de reintentar. La respuesta trae la Serie y el Folio que se usaron.
Cuando todo pase en sandbox, ya estás listo para producción.
El sandbox es gratis y la API viene incluida: en producción pagas folios que no caducan.