Sandbox

El sandbox es un ambiente aislado donde puedes probar toda tu integración —registrar empresas, subir CSD, timbrar, cancelar, descargar XML/PDF— sin generar CFDIs con validez fiscal y sin costo.

Los CFDIs timbrados en el sandbox son simulados: llevan un UUID y un Timbre Fiscal Digital con estructura completa, pero no tienen validez fiscal ante el SAT y no se reportan a ningún sistema del SAT. No los uses para efectos fiscales reales.

Base URL

El sandbox vive en un host y una base de datos independientes de producción. Tus datos, folios y credenciales de sandbox no se comparten con producción.

Ambiente	Base URL
Producción	`https://api.ipsofactura.com`
Sandbox	`https://sandbox.api.ipsofactura.com`

Para cambiar de ambiente solo cambias la base URL y usas la API key del ambiente correspondiente. Una API key de producción no funciona en el sandbox, y viceversa.

Obtén tus credenciales de sandbox

Solicítalas en ipsofactura.com/contacto. Te entregamos una API key de sandbox dedicada, sin límite de timbrado y sin costo.

¿Qué es un CSD?

El Certificado de Sello Digital (CSD) es la credencial con la que el SAT autoriza a un contribuyente a sellar (firmar) sus CFDIs. Son tres cosas que envías al registrarlo:

Archivo / dato	Campo en la API	Qué es
`.cer`	`certificado_cer_base64`	El certificado público, en Base64.
`.key`	`llave_key_base64`	La llave privada cifrada, en Base64.
contraseña	`password_key`	La contraseña de la llave.

En producción subes el CSD real de tu empresa (el que descargas del SAT con tu e.firma). En el sandbox NO uses tu CSD real.

El sandbox rechaza CSD de producción. Usa un CSD de prueba del SAT (abajo). Además, el RFC de tu empresa emisora debe coincidir con el RFC del CSD que subas.

Como los CSD de prueba del SAT son públicos y compartidos, en el sandbox el mismo número de certificado puede registrarse en varias empresas (la unicidad es por empresa). En producción el número de certificado es único a nivel global.

CSD de prueba (descarga)

El SAT publica CSD de prueba gratuitos para desarrollo. Producen CFDIs simulados, sin validez fiscal. Te dejamos los más usados listos para descargar (contraseña 12345678a en todos):

Descargar kit CSD de prueba (.zip)

Contiene EKU9003173C9.cer / .key (moral), CACX7605101P8.cer / .key (física) y un archivo LEEME.txt. Contraseña de las llaves: 12345678a.

RFC emisor	Tipo	Régimen	`numero_certificado`	`fecha_fin`	Contraseña
`EKU9003173C9`	Moral (ESCUELA KEMPER URGATE)	`601`	`30001000000500003416`	`2027-05-18`	`12345678a`
`CACX7605101P8`	Física	`612`	`30001000000500003316`	`2027-05-09`	`12345678a`

numero_certificado y fecha_fin se leen del propio .cer y se validan contra él. Al capturar la razón social usa el nombre sin el sufijo de régimen de capital (ESCUELA KEMPER URGATE, no ... SA DE CV), tal como lo valida el SAT.

Convertir a Base64

certificado_cer_base64 y llave_key_base64 van en Base64, en una sola línea:

CER=$(base64 -i EKU9003173C9.cer | tr -d '\n')
KEY=$(base64 -i EKU9003173C9.key | tr -d '\n')

$CER = [Convert]::ToBase64String([IO.File]::ReadAllBytes("EKU9003173C9.cer"))
$KEY = [Convert]::ToBase64String([IO.File]::ReadAllBytes("EKU9003173C9.key"))

Registrar el CSD

cURL

curl -X POST https://sandbox.api.ipsofactura.com/empresas/{empresa_id}/certificados \
  -H "x-api: {tu_api_key_sandbox}" \
  -H "Content-Type: application/json" \
  -d "{
    \"certificado_cer_base64\": \"$CER\",
    \"llave_key_base64\": \"$KEY\",
    \"password_key\": \"12345678a\",
    \"numero_certificado\": \"30001000000500003416\",
    \"fecha_fin\": \"2027-05-18T00:00:00Z\"
  }"

Flujo de prueba

Registra el CSD de prueba

Sube el .cer y .key de prueba del SAT a tu empresa de sandbox, igual que en producción pero contra la base URL del sandbox.

Timbra un CFDI

Envía tu CFDI como en producción. El sandbox ejecuta las validaciones y devuelve un timbre simulado.

cURL

curl -X POST https://sandbox.api.ipsofactura.com/cfdi/timbrar \
  -H "x-api: {tu_api_key_sandbox}" \
  -H "Content-Type: application/json" \
  -d @factura.json

Verifica la respuesta

Una respuesta exitosa del sandbox incluye el campo sandbox: true. Este campo no aparece en producción, así que sirve para confirmar contra qué ambiente estás integrando.

{
  "uuid": "6128396f-c09b-4ec6-8699-43da5a244971",
  "sello_cfdi": "SANDBOX_sello_cfdi_...",
  "sandbox": true
}

Validaciones

El sandbox reproduce un subconjunto curado de las validaciones CFDI 4.0 del SAT, para que puedas probar el manejo de errores de tu integración. Entre otras, valida:

Que el UsoCFDI sea aplicable al RegimenFiscal del receptor.
Que el RegimenFiscal del receptor corresponda al tipo de persona (física o moral) según su RFC.
Que un receptor extranjero (XEXX010101000) use UsoCFDI = S01.

Cuando una validación falla, el sandbox responde con el mismo formato de error que producción, incluyendo un código tipo CFDIxxxxx en el mensaje:

{
  "code": "VALIDATION_ERROR",
  "message": "...",
  "pacs": [
    {
      "pac": "ipsofactura",
      "code": "VALIDATION_ERROR",
      "message": "CFDI40161 - El UsoCFDI 'D01' no es aplicable para el RegimenFiscal '601' del receptor."
    }
  ]
}

Las validaciones del sandbox son un subconjunto representativo, no la totalidad de la matriz del SAT. Un CFDI aceptado en sandbox puede aún requerir ajustes ante el SAT real.

RFCs mágicos

Para forzar escenarios de error de forma determinista (al estilo de las tarjetas de prueba de Stripe), usa estos RFC de receptor reservados en el sandbox:

RFC receptor	Resultado forzado
`SBX010101ERR`	Error de validación simulado (`CFDI40197`).
`SBX010101TMO`	Servicio de timbrado no disponible (para probar reintentos).

Cualquier otro RFC válido sigue el flujo normal de validación descrito arriba.

Diferencias con producción

Los CFDIs no tienen validez fiscal y no se reportan al SAT.
Solo se aceptan CSD de prueba del SAT (los de producción se rechazan).
Las respuestas de timbrado incluyen sandbox: true.
Es gratis y sin límite de timbrado.
El UUID del sandbox no se puede verificar en el portal “Verifica tus facturas” del SAT.

Empezar

Referencia

Base URL

Obtén tus credenciales de sandbox

¿Qué es un CSD?

CSD de prueba (descarga)

Descargar kit CSD de prueba (.zip)

Convertir a Base64

Registrar el CSD

Flujo de prueba

Validaciones

RFCs mágicos

Diferencias con producción

​Base URL

​Obtén tus credenciales de sandbox

​¿Qué es un CSD?

​CSD de prueba (descarga)

Descargar kit CSD de prueba (.zip)

​Convertir a Base64

​Registrar el CSD

​Flujo de prueba

​Validaciones

​RFCs mágicos

​Diferencias con producción

Base URL

Obtén tus credenciales de sandbox

¿Qué es un CSD?

CSD de prueba (descarga)

Convertir a Base64

Registrar el CSD

Flujo de prueba

Validaciones

RFCs mágicos

Diferencias con producción