Modo de prueba y sandbox

Crea tu integración de forma segura con claves fact_test_ — datos de sandbox aislados y AEAT, email y webhooks desactivados.

Cada API key de Factuarea pertenece a uno de dos entornos, distinguidos por su prefijo:

Prefijo	Entorno	Opera sobre	Efectos externos
`fact_live_`	live (producción)	Tu empresa real	Reales: numeración fiscal legal, VeriFactu → AEAT, envíos a FACe, emails a clientes, webhooks salientes
`fact_test_`	test (sandbox)	Una empresa sandbox aislada	Desactivados (ver abajo)

El prefijo es la fuente de verdad del entorno: una clave fact_test_ siempre opera en modo de prueba y una clave fact_live_ siempre en producción. Ningún parámetro de la petición cambia el entorno — lo determina por completo la clave con la que te autenticas.

Crea y prueba siempre tu integración primero con una clave fact_test_. Una vez tu flujo funcione de extremo a extremo, cambia el prefijo a fact_live_ para pasar a producción. La superficie de la API es idéntica en ambos entornos.

Obtener una clave de prueba

Las claves de prueba se crean desde el dashboard de desarrolladores exactamente igual que las claves live, seleccionando el entorno Test (app.factuarea.com/settings/developers/api-keys). El secreto generado tiene este aspecto:

fact_test_<24 alphanumeric characters>

Ejemplo:

fact_test_3pXnR2VbY7TcA9eFmN5z8KqW

Mismo formato y entropía que una clave live (24 caracteres base62), mismos scopes, mismo nivel de rate limit. La única diferencia es el prefijo y aquello a lo que apunta. Igual que con las claves live, el secreto se muestra solo una vez al crearlo — si lo pierdes, tendrás que rotarlo.

Usar una clave de prueba

Envíala en cada petición igual que una clave live, mediante Authorization: Bearer o X-API-Key:

curl https://api.factuarea.com/v1/clients \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW"

Los mismos endpoints y operaciones disponibles en live lo están en test — no se elimina ni se simula nada.

Aislamiento de datos: la empresa sandbox

Una clave fact_test_ opera sobre una empresa sandbox dedicada — un "gemelo" técnico de tu empresa real, aprovisionado automáticamente la primera vez que usas el modo de prueba, que hereda el plan de tu empresa real para que la limitación por funcionalidades sea fiel. Gracias al aislamiento multi-tenant por empresa:

Los recursos creados con una clave fact_test_ no son visibles para una clave fact_live_, y viceversa.
La numeración fiscal de prueba usa las series propias del sandbox y nunca consume ni altera la numeración correlativa de tus series de producción.

Esto es aislamiento estructural, no un filtro: los datos de test y live viven en empresas separadas, así que no hay forma de que se mezclen.

Qué está desactivado en test

Cuando operas con una clave fact_test_ (entorno sandbox), los efectos que alcanzan al mundo exterior están deshabilitados para que puedas ejercitar tu integración sin consecuencias en el mundo real:

Efecto	En `live`	En `test`
VeriFactu	El registro de Alta se crea y se transmite a la AEAT.	El registro de Alta se crea localmente, pero nunca se transmite a la AEAT.
Email	Los emails de documentos se entregan a destinatarios reales.	Los emails de documentos no se entregan a destinatarios reales.
Webhooks	Los eventos suscritos se entregan a tus endpoints HTTP externos.	Los eventos se registran con `livemode: false` (consultables vía `GET /v1/events`) pero no se entregan a tus endpoints.
FACe (FacturaE)	Los envíos se presentan al web service real de FACe.	Todo el flujo se simula — ninguna llamada SOAP sale de Factuarea y el número de registro es sintético (`FACE-SANDBOX-*`). Consulta Facturación FACe.

Todo lo demás se comporta de forma idéntica: validación, totales, máquinas de estado de documentos, idempotencia, paginación, rate limits y envoltorios de error son los mismos que en producción.

Como los webhooks no se entregan en test, no puedes ejercitar tu receptor de webhooks contra datos del sandbox. Prueba la verificación de firma de tu endpoint con el POST /v1/webhook_endpoints/{id}/ping dedicado (que sí se entrega) o contra una clave live en un evento controlado.

Con los SDK oficiales

Los SDK de TypeScript y PHP siguen la misma regla: el prefijo de la clave selecciona el entorno — no hay ningún flag. Crea tu integración con una clave fact_test_ y luego cambia la variable de entorno a fact_live_ para pasar a producción. Sin cambios de código.

import { Factuarea } from "@factuarea/sdk";

const sandbox = new Factuarea({ apiKey: "fact_test_…" });
sandbox.environment; // "test"

const prod = new Factuarea({ apiKey: "fact_live_…" });
prod.environment;    // "live"

El SDK expone el entorno resuelto en .environment, derivado del prefijo — útil para guardas y logging.

use Factuarea\Sdk\Custom\FactuareaClient;

$sandbox = FactuareaClient::create('fact_test_…'); // sandbox
$prod    = FactuareaClient::create('fact_live_…'); // production

Los webhooks siguen sin entregarse en test, incluso a través del SDK. Para ejercitar el verificador del SDK de tu receptor en el sandbox, usa POST /v1/webhook_endpoints/{id}/ping, que sí se entrega.

Cambiar de entorno en la app

Más allá de las API keys, la app web de Factuarea te permite alternar entre live y test en cualquier momento desde la barra superior. Al cambiar a test:

Se reemite tu sesión sin volver a iniciar sesión, apuntándola a la empresa sandbox (aprovisionándola si aún no existe). El token anterior se invalida.
Se muestra un banner persistente "MODO TEST" en toda la interfaz para que el contexto activo sea siempre evidente.
Se rehidrata el estado del cliente para que los listados reflejen los datos del sandbox y nunca muestren datos de producción cacheados.

Volver a live reemite la sesión contra tu empresa real. El sandbox nunca se muestra como una empresa real en el selector de empresas — existe únicamente para dar soporte al entorno de prueba.

De test a producción

Cuando tu integración funcione contra fact_test_:

Crea una clave fact_live_ en el dashboard (los mismos scopes que validaste en test).
Cambia la clave que usa tu cliente (variable de entorno / gestor de secretos).
No hace falta ningún cambio de código — la forma de la petición es idéntica.

A partir de ese momento, los efectos reales (numeración fiscal, VeriFactu → AEAT, emails, webhooks) vuelven a estar activos.