Mode de prova i sandbox

Crea la teva integració de forma segura amb claus fact_test_ — dades de sandbox aïllades i AEAT, email i webhooks desactivats.

Cada API key de Factuarea pertany a un de dos entorns, distingits pel seu prefix:

Prefix	Entorn	Opera sobre	Efectes externs
`fact_live_`	live (producció)	La teva empresa real	Reals: numeració fiscal legal, VeriFactu → AEAT, enviaments a FACe, emails a clients, webhooks sortints
`fact_test_`	test (sandbox)	Una empresa sandbox aïllada	Desactivats (vegeu a sota)

El prefix és la font de veritat de l'entorn: una clau fact_test_ sempre opera en mode de prova i una clau fact_live_ sempre en producció. Cap paràmetre de la petició canvia l'entorn — el determina completament la clau amb què t'autentiques.

Crea i prova sempre la teva integració primer amb una clau fact_test_. Un cop el teu flux funcioni d'extrem a extrem, canvia el prefix a fact_live_ per passar a producció. La superfície de l'API és idèntica en tots dos entorns.

Obtenir una clau de prova

Les claus de prova es creen des del dashboard de desenvolupadors exactament igual que les claus live, seleccionant l'entorn Test (app.factuarea.com/settings/developers/api-keys). El secret generat té aquest aspecte:

fact_test_<24 alphanumeric characters>

Exemple:

fact_test_3pXnR2VbY7TcA9eFmN5z8KqW

Mateix format i entropia que una clau live (24 caràcters base62), mateixos scopes, mateix nivell de rate limit. L'única diferència és el prefix i allò a què apunta. Igual que amb les claus live, el secret es mostra només un cop en crear-lo — si el perds, l'hauràs de rotar.

Utilitzar una clau de prova

Envia-la a cada petició igual que una clau live, mitjançant Authorization: Bearer o X-API-Key:

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

Els mateixos endpoints i operacions disponibles en live ho estan en test — no s'elimina ni se simula res.

Aïllament de dades: l'empresa sandbox

Una clau fact_test_ opera sobre una empresa sandbox dedicada — un "bessó" tècnic de la teva empresa real, aprovisionat automàticament el primer cop que utilitzes el mode de prova, que hereta el pla de la teva empresa real perquè la limitació per funcionalitats sigui fidel. Gràcies a l'aïllament multi-tenant per empresa:

Els recursos creats amb una clau fact_test_ no són visibles per a una clau fact_live_, i viceversa.
La numeració fiscal de prova fa servir les sèries pròpies del sandbox i mai consumeix ni altera la numeració correlativa de les teves sèries de producció.

Això és aïllament estructural, no un filtre: les dades de test i live viuen en empreses separades, així que no hi ha manera que es barregin.

Què està desactivat en test

Quan operes amb una clau fact_test_ (entorn sandbox), els efectes que arriben al món exterior estan deshabilitats perquè puguis exercitar la teva integració sense conseqüències en el món real:

Efecte	En `live`	En `test`
VeriFactu	El registre d'Alta es crea i es transmet a l'AEAT.	El registre d'Alta es crea localment, però mai es transmet a l'AEAT.
Email	Els emails de documents s'entreguen a destinataris reals.	Els emails de documents no s'entreguen a destinataris reals.
Webhooks	Els esdeveniments subscrits s'entreguen als teus endpoints HTTP externs.	Els esdeveniments es registren amb `livemode: false` (consultables via `GET /v1/events`) però no s'entreguen als teus endpoints.
FACe (FacturaE)	Els enviaments es presenten al web service real de FACe.	Tot el flux es simula — cap crida SOAP surt de Factuarea i el número de registre és sintètic (`FACE-SANDBOX-*`). Consulta Facturació FACe.

Tota la resta es comporta de manera idèntica: validació, totals, màquines d'estat de documents, idempotència, paginació, rate limits i embolcalls d'error són els mateixos que en producció.

Com que els webhooks no s'entreguen en test, no pots exercitar el teu receptor de webhooks contra dades del sandbox. Prova la verificació de signatura del teu endpoint amb el POST /v1/webhook_endpoints/{id}/ping dedicat (que sí s'entrega) o contra una clau live en un esdeveniment controlat.

Amb els SDK oficials

Els SDK de TypeScript i PHP segueixen la mateixa regla: el prefix de la clau selecciona l'entorn — no hi ha cap flag. Crea la teva integració amb una clau fact_test_ i després canvia la variable d'entorn a fact_live_ per passar a producció. Sense canvis de codi.

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"

L'SDK exposa l'entorn resolt a .environment, derivat del prefix — útil per a guardes i logging.

use Factuarea\Sdk\Custom\FactuareaClient;

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

Els webhooks segueixen sense entregar-se en test, fins i tot a través de l'SDK. Per exercitar el verificador de l'SDK del teu receptor al sandbox, fes servir POST /v1/webhook_endpoints/{id}/ping, que sí s'entrega.

Canviar d'entorn a l'app

Més enllà de les API keys, l'app web de Factuarea et permet alternar entre live i test en qualsevol moment des de la barra superior. En canviar a test:

Es reemet la teva sessió sense tornar a iniciar sessió, apuntant-la a l'empresa sandbox (aprovisionant-la si encara no existeix). El token anterior s'invalida.
Es mostra un banner persistent "MODO TEST" a tota la interfície perquè el context actiu sigui sempre evident.
Es rehidrata l'estat del client perquè els llistats reflecteixin les dades del sandbox i mai mostrin dades de producció en memòria cau.

Tornar a live reemet la sessió contra la teva empresa real. El sandbox no es mostra mai com una empresa real al selector d'empreses — existeix únicament per donar suport a l'entorn de prova.

De test a producció

Quan la teva integració funcioni contra fact_test_:

Crea una clau fact_live_ al dashboard (els mateixos scopes que vas validar en test).
Canvia la clau que fa servir el teu client (variable d'entorn / gestor de secrets).
No cal cap canvi de codi — la forma de la petició és idèntica.

A partir d'aquest moment, els efectes reals (numeració fiscal, VeriFactu → AEAT, emails, webhooks) tornen a estar actius.