Modo de prueba y sandbox

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

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.

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 salvo los de los módulos que el modo de prueba no ofrece (por ejemplo webhooks:write), 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.

También puedes emitir una con una clave live, con POST /v1/accounts/{account}/api-keys y environment en test. Una clave de pruebas nunca emite claves: consulta el eje de cuenta.

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/companies/{company}/contacts \
  -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 — con las excepciones que describen el eje de cuenta y los endpoints de webhook.

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:

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.

El eje de cuenta con una clave de pruebas

Una clave fact_test_ pertenece a tu cuenta real, así que alcanza el eje de cuenta: GET /v1/me y las operaciones bajo /v1/accounts/{account}/…. La regla es corta: lee, y no escribe en una cuenta de producción.

Cuentas gestionadas de pruebas

Si aprovisionas cuentas para tus clientes, puedes ensayarlo con una clave de pruebas. POST /v1/accounts con una clave fact_test_ crea una cuenta de pruebas: una cuenta gestionada del entorno test, con una empresa sandbox como NIF y ninguna empresa real detrás. No se cobra, no tiene vale de reclamación (claim_token y claim_url son null) y nadie la reclama, no cuenta para max_managed_accounts, y nada llega a VeriFactu ni a un destinatario real. Solo la alcanzan tus claves fact_test_ y la app en Modo pruebas: una clave live responde 404 account_not_found. Una cuenta de pruebas nunca pasa a ser de producción, y su external_ref es único entre los dos entornos: repetirlo con una clave live responde 409 managed_account_external_ref_in_other_environment.

Dos cosas difieren de lo que podrías esperar:

• La importación masiva. Con una clave de pruebas, las filas managed_account crean o concilian cuentas de pruebas. Las filas own_nif y la fila de opciones salen ERROR con code live_credential_required, no crean nada y suman 0 a los totales.
• Los datos de su NIF. Una clave de pruebas alcanza solo la empresa sandbox de tu propia cuenta, así que /v1/companies/{company}/… con el id de un NIF de una cuenta de pruebas responde 404 profile_not_found. Para trabajar con esos datos, cambia la app a Modo pruebas: tus cuentas de pruebas aparecen entre tus cuentas de cliente, y al elegir una, su empresa sandbox pasa a ser la activa.

Probar cuentas gestionadas con clave fact_test_ recorre todo el camino, desde leer tu cuenta hasta leer los eventos de una cuenta de pruebas.

Endpoints de webhook de cuenta en test

Un endpoint de webhook de cuenta pertenece a un entorno, live o test, que se fija al crearlo y no cambia nunca. Un endpoint del entorno test recibe solo los eventos del entorno de pruebas, y un endpoint live nunca los recibe. Nunca hace una petición saliente: cada entrega se registra con su sobre y queda pending, con attempt a 0. Así que «recibir» un evento es leerlo, con GET /v1/accounts/{account}/webhooks/{webhook}/deliveries.

Una clave de pruebas no puede crear un endpoint de pruebas. El entorno de un endpoint lo fija la credencial o la sesión que lo crea, y un environment en el cuerpo se ignora. Una clave fact_test_ lee los endpoints y las entregas del entorno de pruebas con webhooks:read, pero no puede crear, editar, rotar, probar, reintentar ni borrar un endpoint de cuenta. El endpoint de pruebas lo creas en la app web, con el Modo pruebas activado, desde Ajustes → Desarrolladores → Webhooks, eligiendo Cuenta: cuentas gestionadas de pruebas muestra los pasos.

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"

use Factuarea\Sdk\Custom\FactuareaClient;

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

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 pruebas» 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.

El Modo pruebas es también donde creas los endpoints test de tus webhooks de cuenta, y donde trabajas con los datos de los NIF de tus cuentas gestionadas de pruebas, que una clave de pruebas no alcanza.

De test a producción

Cuando tu integración funcione contra fact_test_:

1. Crea una clave fact_live_ en el dashboard (los mismos scopes que validaste en test).
2. Cambia la clave que usa tu cliente (variable de entorno / gestor de secretos).
3. 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.

Nada de lo que creaste en test pasa a producción. Una cuenta gestionada de pruebas nunca se promueve: aprovisiona las de producción con una clave fact_live_ y un external_ref distinto. Crea los endpoints de webhook de cuenta de producción con una clave live o en la app en modo producción, porque un endpoint test nunca recibe eventos de producción.

Entorno de la tienda y entrega

El environment de una tienda es distinto del entorno seleccionado por el prefijo de la API key. Las tiendas nuevas usan test, con facturación y envío automáticos desactivados. Sus eventos de prueba pueden descartarse como store_environment_test; el sandbox aislado también suprime el correo real y la entrega de webhooks públicos. Cambiar la tienda no convierte una credencial de test en live. Consulta tiendas y el trigger de n8n.