> ## Documentation Index
> Fetch the complete documentation index at: https://developers.ipsofactura.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Ambiente de pruebas aislado y sin costo para integrar antes de producción.

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.

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

## 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](https://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.

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

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

## 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):

<Card title="Descargar kit CSD de prueba (.zip)" icon="download" href="/assets/csd-pruebas.zip">
  Contiene `EKU9003173C9.cer` / `.key` (moral), `CACX7605101P8.cer` / `.key` (física) y un
  archivo `LEEME.txt`. Contraseña de las llaves: `12345678a`.
</Card>

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

<Note>
  `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.
</Note>

### Convertir a Base64

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

<CodeGroup>
  ```bash macOS / Linux theme={null}
  CER=$(base64 -i EKU9003173C9.cer | tr -d '\n')
  KEY=$(base64 -i EKU9003173C9.key | tr -d '\n')
  ```

  ```powershell Windows theme={null}
  $CER = [Convert]::ToBase64String([IO.File]::ReadAllBytes("EKU9003173C9.cer"))
  $KEY = [Convert]::ToBase64String([IO.File]::ReadAllBytes("EKU9003173C9.key"))
  ```
</CodeGroup>

### Registrar el CSD

```bash cURL theme={null}
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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Timbra un CFDI">
    Envía tu CFDI como en producción. El sandbox ejecuta las validaciones y devuelve un timbre
    simulado.

    ```bash cURL theme={null}
    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
    ```
  </Step>

  <Step title="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.

    ```json theme={null}
    {
      "uuid": "6128396f-c09b-4ec6-8699-43da5a244971",
      "sello_cfdi": "SANDBOX_sello_cfdi_...",
      "sandbox": true
    }
    ```
  </Step>
</Steps>

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

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

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

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