Mode de prova i sandbox

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

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.

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 llevat dels dels mòduls que el mode de prova no ofereix (per exemple webhooks:write), 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.

També en pots emetre una amb una clau live, amb POST /v1/accounts/{account}/api-keys i environment a test. Una clau de proves no emet mai claus: consulta l'eix de compte.

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/companies/{company}/contacts \
  -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 — amb les excepcions que descriuen l'eix de compte i els endpoints de webhook.

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:

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

L'eix de compte amb una clau de proves

Una clau fact_test_ pertany al teu compte real, així que arriba a l'eix de compte: GET /v1/me i les operacions sota /v1/accounts/{account}/…. La regla és curta: llegeix, i no escriu en un compte de producció.

Comptes gestionats de proves

Si aprovisiones comptes per als teus clients, ho pots assajar amb una clau de proves. POST /v1/accounts amb una clau fact_test_ crea un compte de proves: un compte gestionat de l'entorn test, amb una empresa sandbox com a NIF i cap empresa real al darrere. No es cobra, no té val de reclamació (claim_token i claim_url són null) i ningú no el reclama, no compta per a max_managed_accounts, i res no arriba a VeriFactu ni a un destinatari real. Només hi arriben les teves claus fact_test_ i l'app en Mode de proves: una clau live respon 404 account_not_found. Un compte de proves no passa mai a ser de producció, i el seu external_ref és únic entre els dos entorns: repetir-lo amb una clau live respon 409 managed_account_external_ref_in_other_environment.

Dues coses difereixen del que podries esperar:

• La importació massiva. Amb una clau de proves, les files managed_account creen o concilien comptes de proves. Les files own_nif i la fila d'opcions surten ERROR amb code live_credential_required, no creen res i sumen 0 als totals.
• Les dades del seu NIF. Una clau de proves arriba només a l'empresa sandbox del teu propi compte, així que /v1/companies/{company}/… amb l'id d'un NIF d'un compte de proves respon 404 profile_not_found. Per treballar amb aquestes dades, passa l'app a Mode de proves: els teus comptes de proves apareixen entre els teus comptes de clients, i en triar-ne un, la seva empresa sandbox passa a ser l'activa.

Provar comptes gestionats amb clau fact_test_ recorre tot el camí, des de llegir el teu compte fins a llegir els esdeveniments d'un compte de proves.

Endpoints de webhook de compte en test

Un endpoint de webhook de compte pertany a un entorn, live o test, que es fixa en crear-lo i no canvia mai. Un endpoint de l'entorn test rep només els esdeveniments de l'entorn de proves, i un endpoint live no els rep mai. No fa mai una petició sortint: cada lliurament es registra amb el seu sobre i queda pending, amb attempt a 0. Així que «rebre» un esdeveniment és llegir-lo, amb GET /v1/accounts/{account}/webhooks/{webhook}/deliveries.

Una clau de proves no pot crear un endpoint de proves. L'entorn d'un endpoint el fixa la credencial o la sessió que el crea, i un environment al cos s'ignora. Una clau fact_test_ llegeix els endpoints i els lliuraments de l'entorn de proves amb webhooks:read, però no pot crear, editar, rotar, provar, reintentar ni esborrar un endpoint de compte. L'endpoint de proves el crees a l'aplicació web, amb el Mode de proves activat, des de Configuració → Desenvolupadors → Webhooks, triant Compte: comptes gestionats de proves mostra els passos.

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"

use Factuarea\Sdk\Custom\FactuareaClient;

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

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 «Mode de proves» 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.

El Mode de proves és també on crees els endpoints test dels teus webhooks de compte, i on treballes amb les dades dels NIF dels teus comptes gestionats de proves, que una clau de proves no abasta.

De test a producció

Quan la teva integració funcioni contra fact_test_:

1. Crea una clau fact_live_ al dashboard (els mateixos scopes que vas validar en test).
2. Canvia la clau que fa servir el teu client (variable d'entorn / gestor de secrets).
3. 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.

Res del que has creat en test passa a producció. Un compte gestionat de proves no es promou mai: aprovisiona els de producció amb una clau fact_live_ i un external_ref diferent. Crea els endpoints de webhook de compte de producció amb una clau live o a l'app en mode producció, perquè un endpoint test no rep mai esdeveniments de producció.

Entorn de la botiga i lliurament

L’environment d’una botiga és diferent de l’entorn seleccionat pel prefix de l’API key. Les botigues noves fan servir test, amb facturació i enviament automàtics desactivats. Els esdeveniments de prova es poden descartar com a store_environment_test; el sandbox aïllat també suprimeix el correu real i el lliurament de webhooks públics. Canviar la botiga no converteix una credencial de test en live. Consulta botigues i el trigger de n8n.