Integraciones y entrada de documentos Opcional

Probar la API en el sandbox

3:30 Tutorial 3.14

El sandbox es un entorno aparte, con clientes y facturas ficticios, para probar una integración sin afectar a datos reales. No remite nada a la AEAT ni envía correos a clientes.

Antes de empezar

  • Plan Starter, Professional o Enterprise: hasta 3 sandboxes, con todos los permisos de la API. El plan Gratuito no incluye sandbox.
  • Rol de titular o de administrador del equipo. El resto de miembros no ve el submenú API y desarrolladores.
  • La pestaña Sandbox aparece solo cuando el servicio está habilitado en el sistema. Si no figura, consultar con soporte.
  • Un sandbox no admite datos personales reales ni certificados digitales. Los topes por sandbox son 25 clientes, 2.000 facturas, 500 documentos y 200 MB.

Paso 1. Abrir la pestaña Sandbox

En el menú lateral, Integraciones > API y desarrolladores > Claves de API, y pulsar la pestaña Sandbox.

  1. El bloque Qué ejercita el sandbox indica el máximo de sandboxes del plan.
  2. La URL base y el prefijo cg_sbx_ de las claves figuran en ese mismo bloque.
Nota. Con un plan sin sandbox la pantalla indica El plan actual no incluye sandbox y remite a Suscripción. Disponible desde Starter.

Paso 2. Crear un sandbox

En el bloque Crear un sandbox:

  1. Nombre: opcional, hasta 120 caracteres. Sirve para distinguir una integración de otra.
  2. Datos de partida: despacho de demostración con 8 clientes, despacho ampliado con 12 o vacía, sin clientes.
  3. Marcar la casilla de confirmación: no se usarán datos personales reales ni certificados digitales.
  4. Pulsar Crear sandbox.
Nota. El bloque solo se pinta si quedan plazas libres en el plan y el servicio responde. Con el máximo alcanzado, eliminar un sandbox antes de crear otro.

Paso 3. Copiar la clave del sandbox

Tras crearlo, aparece el aviso Sandbox creado. Preparando los datos de ejemplo. y el bloque Clave del sandbox. Pulsar Copiar.

Importante. La clave se muestra una sola vez y solo es válida en el sandbox. Si se pierde, crear otra desde el panel del sandbox.
Nota. La tarjeta del sandbox pasa de Preparando datos a Activo cuando los datos de ejemplo están cargados.

Paso 4. Llamar a la API del sandbox

La integración usa la URL base indicada en pantalla y la clave cg_sbx_ en la cabecera Authorization, con el formato Bearer.

  1. Enviar Idempotency-Key en toda escritura y reutilizarla en los reintentos tras un 503 o un error de red.
  2. Probar los errores 400, 401, 403, 404, 409, 422, 429 con Retry-After y 503 con los valores de prueba.
  3. La documentación completa está en el botón Documentación, que abre la sección del sandbox.
Atención. La clave del sandbox solo es válida en el sandbox. Ningún identificador del sandbox debe reutilizarse en producción.

Paso 5. Simular el resultado de la AEAT

La remisión es simulada. El resultado se fija con la cabecera X-CG-Sandbox-Scenario al emitir o con un NIF de receptor de prueba.

  1. aceptada: la AEAT acepta el registro y devuelve un CSV de pruebas.
  2. aceptada_con_errores (NIF 00000001R): registra la factura con errores. No cuenta como éxito.
  3. rechazada (NIF 00000002W): rechazo con el código 4104, el nombre no casa con el censo.
  4. estado_desconocido (NIF 00000003A): se envió sin confirmación y queda pendiente de revisión.
  5. reintentable (NIF 00000004G): fallo del servidor de la AEAT; la remisión se reintenta sola.
  6. duplicada (NIF 00000005M): rechazo porque el registro ya existe.
  7. espera (NIF 00000006Y): la AEAT impone una espera antes de aceptar.
Nota. También hay escenarios de cobro y de plataforma, por ejemplo límite de peticiones o servicio no disponible. Constan en la documentación.

Paso 6. Abrir el panel del sandbox o compartir el acceso

Cada sandbox figura como una tarjeta con su nombre, el prefijo de la clave, la Última actividad y los Reseteos realizados.

  1. Abrir panel del sandbox: abre en otra pestaña el panel con los datos ficticios.
  2. Compartir acceso: genera un enlace de un solo uso, válido 24 horas, que da acceso únicamente al panel del sandbox.
Nota. El enlace compartido aparece en el bloque Enlace de acceso al panel del sandbox, con su botón Copiar.

Paso 7. Resetear, reactivar o eliminar un sandbox

  1. Resetear: tras Sí, resetear, se borran los datos y se recrean los de ejemplo. Claves y destinos de webhook se conservan.
  2. Eliminar: tras Sí, eliminar, se borran el sandbox, sus claves, destinos de webhook y datos.
  3. Reactivar: un sandbox archivado por inactividad vuelve a estar activo.
Atención. Eliminar no se deshace. Resetear devuelve la numeración de la serie SBX a su estado inicial.
Nota. Un sandbox sin actividad se archiva a los 90 días, con aviso a los 60 y 30 días de gracia antes de eliminar los datos.

Paso 8. Repasar la lista de paso a producción

El bloque Paso a producción reúne las comprobaciones previas a la clave real, en tres fases: Integración (en el sandbox), Solicitud y Activación (con datos reales).

Importante. La clave de producción se crea aparte, desde Claves, con los clientes autorizados. Cada cliente final debe registrar su consentimiento antes de que la integración lea sus datos.

Resultado

El sandbox figura como Activo con su clave cg_sbx_ en poder del integrador, clientes y facturas ficticios, y la remisión a la AEAT simulada. Nada de lo que se haga en él afecta a datos reales ni sale al exterior.

Campos del formulario Crear un sandbox

Campo Qué admite Obligatorio Efecto
Nombre Texto, hasta 120 caracteres No Identifica el sandbox en el listado.
Datos de partida Despacho de demostración (8 clientes con casos de prueba) · Despacho ampliado (12 clientes) · Vacía (sin clientes) No (despacho de demostración por defecto) Define los clientes y facturas ficticios con los que arranca.
Confirmación de datos ficticios Casilla Sí Sin marcarla no se crea el sandbox.

Problemas frecuentes

«El plan actual no incluye sandbox.»
El plan Gratuito no tiene sandbox. Contratar Starter o superior desde Suscripción.
«Máximo de sandboxes del plan alcanzado. Eliminar uno para crear otro.»
Ya hay 3 sandboxes. Eliminar uno que no se use y volver a crear.
«Confirmar que no se utilizarán datos personales reales en el sandbox.»
Marcar la casilla de confirmación del formulario antes de pulsar Crear sandbox.
«Máximo de reseteos diarios alcanzado.»
El sandbox admite 10 reseteos al día. Esperar al día siguiente o eliminar el sandbox y crear otro.
«Solo el titular de la cuenta puede gestionar el sandbox.»
Crear, abrir, resetear y eliminar corresponde al titular o al administrador del equipo.
La tarjeta solo muestra Reactivar y Eliminar.
El sandbox está archivado por inactividad. Pulsar Reactivar para recuperarlo durante el periodo de gracia.
Las llamadas de digitalización, modelos fiscales o importación de extractos devuelven 501.
Esas funciones no existen en el sandbox. Las lecturas sí funcionan.

Continuar con

Consejo
Probar en el sandbox los resultados aceptada_con_errores, rechazada y estado_desconocido: la integración debe tratar cada uno de forma distinta antes de pasar a producción.
Anterior Rotar o revocar una clave de API Siguiente Generar el Modelo 303 de un cliente

Prueba CopilotGestoria gratis

30 días gratis. Sube tu primera factura en 2 minutos.

Crear cuenta gratis