Provar comptes gestionats amb clau fact_test_

Pots assajar tot l'aprovisionament de comptes de clients amb una clau fact_test_ abans de tocar un client real. No es cobra res, no surt cap val ni cap correu, no hi intervé cap empresa real i res no arriba a VeriFactu. Aquesta guia recorre el camí en cinc passos, des de llegir el teu propi compte fins a llegir els esdeveniments d'un compte de proves, i acaba amb el que el camí no et deixa fer, perquè sàpigues què provar amb una clau de producció.

Dona per fet que aprovisiones comptes per als teus clients com descriu comptes gestionats. Com es comporta una clau de proves a la resta de l'API és a mode de prova i sandbox.

Què és un compte de proves

Un compte de proves és un compte gestionat creat amb una clau fact_test_. És un compte gestionat normal a l'entorn test, amb aquestes diferències:

Abans de començar

Necessites tres coses:

• El privilegi de proveïdor. accounts:read i accounts:write són scopes privilegiats que concedim compte per compte, també per als comptes de proves: consulta scopes privilegiats. Un compte al seu trial pot crear comptes de proves, i només aquests.
• Una clau de proves. Crea-la a Configuració → Desenvolupadors → API Keys triant l'entorn de proves, o amb una clau de producció mitjançant POST /v1/accounts/{account}/api-keys amb environment a test. Dona-li accounts:read i accounts:write, i a més webhooks:read per al pas 5: és l'únic scope de webhooks que pot portar una clau de proves.
• Una Idempotency-Key a les escriptures irreversibles. Aprovisionar, aplicar una importació, canviar el pla i acabar la gestió la necessiten també amb una clau de proves, i una crida sense ella respon 422 idempotency_key_required.

El camí en una taula

1. Llegeix el teu propi compte

Una clau fact_test_ pertany al teu compte real, així que el llegeix com ho fa una clau de producció. Comença preguntant què és la clau. GET /v1/me no necessita cap scope:

curl https://api.factuarea.com/v1/me \
  -H "Authorization: Bearer $FACTUAREA_TEST_KEY"

{
  "data": {
    "object": "me",
    "account": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00",
      "name": "Asesoría Martínez",
      "environment": "live",
      "is_provider": true,
      "privileged_scopes": [
        "accounts:read",
        "accounts:write"
      ]
    },
    "api_key": {
      "name": "Pruebas de integración",
      "prefix": "fact_test_1OSf9KdP",
      "scopes": [
        "accounts:read",
        "accounts:write",
        "webhooks:read"
      ],
      "environment": "test"
    },
    "client_accounts": [],
    "client_accounts_visible": true,
    "client_accounts_has_more": false
  }
}

La resposta està abreujada. Llegeix-la així:

• La clau és de proves, el compte és real. api_key.environment és test i account.environment és live. El scope de la resposta, que aquí no es mostra, llista l'empresa sandbox a la qual arriba la clau, i només aquesta.
• is_provider i privileged_scopes et diuen si tens el privilegi de proveïdor. Sense ell, l'aprovisionament del pas 2 respon 403 privileged_scope_required.
• client_accounts llista només els teus comptes de proves. Necessita accounts:read en vigor a la clau, o torna buit amb client_accounts_visible a false. L'exemple és buit perquè encara no existeix cap compte de proves, i després del pas 2 llista el nou. Els teus comptes de producció no hi surten: els llisten les claus de producció.

Les altres lectures del teu propi compte responen amb una clau de proves com amb una de producció, cadascuna amb l'scope de la seva operació i amb les dades reals del teu compte: provisioning-usage, la cartera de NIF, els membres i el consum. Els webhooks i els registres de peticions del compte responen amb els del teu entorn de proves.

2. Aprovisiona un compte de proves

Aprovisiona amb POST /v1/accounts i una clau de proves. És la mateixa crida que en producció, amb el mateix cos, i l'entorn és el de la clau: mai no va al cos. Necessita accounts:write i una Idempotency-Key.

curl -X POST https://api.factuarea.com/v1/accounts \
  -H "Authorization: Bearer $FACTUAREA_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_ref": "test-0001",
    "plan": "empresario",
    "access_level": "operate",
    "tax_id": "B12345674",
    "legal_name": "Talleres García SL"
  }'

{
  "data": {
    "id": "0199b2a0-3e44-7c31-8d10-4b1a2c3d4e01",
    "object": "managed_account",
    "external_ref": "test-0001",
    "status": "provisioned",
    "environment": "test",
    "plan": "empresario",
    "pending_plan": null,
    "billing_interval": "monthly",
    "access_level": "operate",
    "display_name": "Talleres García SL",
    "language": "es",
    "companies": [
      {
        "id": "0199b2a0-3e44-7c31-8d10-4b1a2c3d4e02",
        "tax_id": "B12345674",
        "name": "Talleres García SL"
      }
    ],
    "claimed": false,
    "claimed_at": null,
    "management": {
      "status": "active",
      "ended_at": null
    },
    "paid_by_provider": true,
    "created_at": "2026-09-30T10:00:00+00:00",
    "claim_token": null,
    "claim_url": null,
    "claim_expires_at": null
  }
}

La resposta és 201 Created amb Location: /v1/accounts/{id}. Què esperar, en comparació amb un compte de producció:

• Sense val. claim_token, claim_url i claim_expires_at són null, i no surt cap correu. No enviïs send_email: un compte de proves no té cap val que lliurar.
• owner_email és opcional. Un compte de proves no té titular a qui convidar.
• El NIF es valida com en producció. Necessita un NIF, CIF o NIE vàlid amb el seu caràcter de control.
• No compta per al teu topall. provisioning-usage el compta a managed_accounts.test, i limit i remaining no es mouen. Les comprovacions de trial, de topall i de mètode de pagament d'un compte de producció no s'executen, així que un proveïdor al seu trial pot aprovisionar comptes de proves.
• La crida és idempotent per external_ref. Repetir-la respon 200 amb el mateix compte i no crea res.

Els errors que hi pots trobar són els d'aprovisionar un compte de producció que no depenen d'un cobrament:

3. Importa un fitxer de prova

La importació massiva funciona amb una clau de proves en dues crides: una previsualització sense efectes i l'aplicació. L'entorn és, una altra vegada, el de la clau. Prova-la amb un fitxer de tres files, separat per punt i coma i amb les columnes de la plantilla:

mode;external_ref;plan;tax_id;legal_name;owner_email
managed_account;test-0002;emprendedor;A58818501;Bodega Sol SL;
managed_account;test-0003;empresario;B28013829;Horno Mar SL;hugo@hornomar.example
own_nif;;;B76543214;Delegación Este SL;

Previsualitza-la primer. La previsualització és un POST perquè puja el fitxer, no escriu res i no necessita Idempotency-Key:

curl -X POST https://api.factuarea.com/v1/accounts/imports/preview \
  -H "Authorization: Bearer $FACTUAREA_TEST_KEY" \
  -F "accounts_file=@clients.csv"

{
  "data": {
    "object": "managed_account_import_preview",
    "rows": [
      {
        "line": 2,
        "mode": "managed_account",
        "external_ref": "test-0002",
        "tax_id": "A58818501",
        "status": "VALID",
        "code": null,
        "errors": {},
        "plan": "emprendedor",
        "monthly_amount_cents": 0,
        "proration_amount_cents": 0
      },
      {
        "line": 3,
        "mode": "managed_account",
        "external_ref": "test-0003",
        "tax_id": "B28013829",
        "status": "VALID",
        "code": null,
        "errors": {},
        "plan": "empresario",
        "monthly_amount_cents": 0,
        "proration_amount_cents": 0
      },
      {
        "line": 4,
        "mode": "own_nif",
        "external_ref": null,
        "tax_id": "B76543214",
        "status": "ERROR",
        "code": "live_credential_required",
        "errors": {},
        "plan": null,
        "monthly_amount_cents": 0,
        "proration_amount_cents": 0
      }
    ],
    "totals": {
      "total_rows": 3,
      "valid": 2,
      "warning": 0,
      "already_exists": 0,
      "blocked": 0,
      "error": 1
    },
    "cost": {
      "currency": "EUR",
      "total": {
        "monthly_amount_cents": 0,
        "proration_amount_cents": 0
      }
    },
    "own_company_customers": null
  }
}

La resposta està abreujada: les files porten més camps i cost també es desglossa per modalitat. Amb una clau de proves:

• Les files managed_account són VALID i crearien comptes de proves, sense val.
• La fila own_nif és ERROR amb code live_credential_required: un NIF del teu propi compte es dona d'alta només amb una clau de producció. La fila d'opcions de la importació, la que aplica els clients a la teva pròpia empresa, surt igual.
• El cost és 0. El total no compta ni la quota mensual ni el prorrateig, i cap crida no arriba al proveïdor de pagament.

Aplica el mateix fitxer amb POST /v1/accounts/imports. Necessita una Idempotency-Key:

curl -X POST https://api.factuarea.com/v1/accounts/imports \
  -H "Authorization: Bearer $FACTUAREA_TEST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "accounts_file=@clients.csv"

La resposta és 201 Created amb el resultat de l'execució, abreujat aquí:

{
  "data": {
    "id": "0199b2a0-5f60-7d40-9e20-6d3c4e5f6a05",
    "object": "managed_account_import",
    "status": "completed",
    "stats": {
      "total_rows": 3,
      "valid": 2,
      "warning": 0,
      "already_exists": 0,
      "blocked": 0,
      "error": 1,
      "created": 2,
      "reconciled": 0,
      "customers_queued": 0,
      "monthly_amount_cents": 0,
      "proration_amount_cents": 0
    },
    "rows": [
      {
        "line": 2,
        "mode": "managed_account",
        "external_ref": "test-0002",
        "status": "VALID",
        "account_id": "0199b2a0-5f66-7d42-9e21-5c2b3d4e5f03",
        "claim_token": null,
        "claim_url": null
      }
    ],
    "own_company_customers": null
  }
}

Es creen dos comptes i la fila own_nif no crea res. Cap fila porta un val. Aplica el mateix fitxer una altra vegada per veure la reconciliació: els dos comptes surten ALREADY_EXISTS i no es crea res dues vegades. Les columnes, els límits i els estats de fila són els de la importació massiva.

4. Opera el compte de proves

Les operacions d'aprovisionament anomenen el compte de proves pel seu id al segment {account}. Amb una clau de proves, el teu compte arriba als comptes de proves que va aprovisionar i a cap altre.

• Llegeix-lo. GET /v1/accounts/{account} respon 200 amb el compte com al pas 2, i companies[] en llista el NIF. GET /v1/accounts llista només comptes de proves amb una clau de proves. Una clau de producció respon 404 account_not_found amb l'id d'un compte de proves.
• Canvia el teu nivell. PATCH /v1/accounts/{account}/access-level amb level respon 200 amb el nou access_level. Un compte de proves no es reclama mai, així que pots pujar i baixar el nivell tantes vegades com vulguis.
• Canvia el pla. GET /v1/accounts/{account}/plan/preview amb plan mostra els dos imports a 0, i PATCH /v1/accounts/{account}/plan canvia el pla a l'acte i sense cobrament. Les dues demanen el nivell operate, i el canvi necessita una Idempotency-Key. El preu dels comptes gestionats explica el flux de producció.
• Acaba la gestió. DELETE /v1/accounts/{account}/management respon 200 amb management.status a ended, i des de la teva propera petició el compte respon 404, com un de producció: consulta acaba la gestió.

curl -X PATCH https://api.factuarea.com/v1/accounts/0199b2a0-3e44-7c31-8d10-4b1a2c3d4e01/access-level \
  -H "Authorization: Bearer $FACTUAREA_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "level": "view" }'

5. Llegeix-ne els esdeveniments en un endpoint de proves

Els esdeveniments d'un compte de proves no arriben mai a un endpoint de producció, i un endpoint de l'entorn test no rep mai els esdeveniments d'un compte de producció. Per seguir el camí necessites un endpoint de proves del teu compte, i una clau de proves no el pot crear: el crees a l'aplicació web.

1. Passa l'aplicació web a Mode de proves amb l'interruptor de mode de proves de la capçalera. Has de ser titular o administrador del compte.
2. Obre Configuració → Desenvolupadors → Webhooks i tria Compte al selector Empresa | Compte.
3. Tria Nou endpoint de compte. Escriu una URL HTTPS, deixa Comptes dels quals rep esdeveniments a Tots, i tria els esdeveniments que vulguis a Esdeveniments subscrits: account.managed_account_provisioned per al pas 2, account.import_completed per al pas 3, i account.access_level_changed i account.management_ended per al pas 4. El secret de signatura es mostra una sola vegada.

L'endpoint pren l'entorn de la sessió: és test, no canvia mai i és invisible des de producció. El nombre d'endpoints depèn del pla i es compta per compte i entorn. Quan el pla no en té cap, o arribes al límit, l'aplicació rebutja l'endpoint amb addon_required o account_webhook_endpoint_limit_reached: consulta webhooks de compte.

Ara repeteix els passos 2 a 4 amb la teva clau de proves i llegeix què ha passat. Amb webhooks:read, una clau de proves llegeix els endpoints i els lliuraments de l'entorn de proves:

curl https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/webhooks \
  -H "Authorization: Bearer $FACTUAREA_TEST_KEY"

La resposta llista els teus endpoints de proves, i només aquests. Agafa l'id del teu i llista'n els lliuraments amb GET /v1/accounts/{account}/webhooks/{webhook}/deliveries, on {account} és el teu propi account.id:

{
  "data": [
    {
      "id": "0199b2a0-3e80-7c55-8d41-8f5e6a7b8c07",
      "object": "account_webhook_delivery",
      "event_id": "0199b2a0-3e7a-7c50-8d40-9a6f7b8c9d08",
      "event_type": "account.managed_account_provisioned",
      "event_source": "account",
      "company_id": null,
      "account_relationship": "own",
      "environment": "test",
      "status": "pending",
      "attempt": 0,
      "manual_retry_count": 0,
      "next_retry_at": null,
      "response_status": null,
      "response_body": null,
      "duration_ms": null,
      "payload": {
        "id": "0199b2a0-3e7a-7c50-8d40-9a6f7b8c9d08",
        "type": "account.managed_account_provisioned",
        "livemode": false,
        "account": {
          "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00"
        },
        "account_relationship": "own",
        "company_id": null,
        "data": {
          "type": "account.managed_account_provisioned",
          "object": {
            "object": "account_relation",
            "id": "0199b2a0-3e46-7c33-8d12-0b7a8c9dae09",
            "origin": "provisioned",
            "level": "operate",
            "previous_level": null,
            "grantor_account_id": "0199b2a0-3e44-7c31-8d10-4b1a2c3d4e01",
            "grantee_account_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00",
            "status": "active",
            "managed_account_id": "0199b2a0-3e44-7c31-8d10-4b1a2c3d4e01",
            "external_ref": "test-0001"
          }
        }
      },
      "created_at": "2026-09-30T10:00:01+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

El lliurament està abreujat. El seu payload és el sobre que rebria un endpoint de producció, amb livemode a false. Què fa diferent un endpoint de proves:

• No s'envia res a la teva URL. El lliurament d'un endpoint de proves es registra i no surt mai de Factuarea, així que queda pending amb attempt a 0. El llegeixes aquí, o al detall de l'endpoint de l'aplicació web, i no hi ha cap petició que verificar.
• Només arriben els esdeveniments d'un compte de proves. L'entorn d'un esdeveniment account.* és el del compte al qual es refereix. Els esdeveniments d'un compte de producció no arriben mai a aquest endpoint, i un endpoint de producció no rep mai els esdeveniments dels teus comptes de proves.

Llegeix un sol lliurament amb GET …/deliveries/{delivery}, que el retorna amb el mateix payload. Les lectures dels webhooks de compte conserven les seves guardes amb una clau de proves: la persona que va emetre la clau ha de ser avui titular o administradora del compte, com explica webhooks de compte.

El que el camí no permet

Passar a producció

Un compte de proves i un compte de producció són independents, i res del que has creat amb la clau de proves passa a producció. Per passar a producció:

• Aprovisiona els comptes de producció amb una clau fact_live_. Un compte de producció necessita owner_email, un mètode de pagament al teu compte i marge sota el teu topall, i es cobra prorratejat a l'acte: consulta preu i pagador.
• Dona a cadascun un external_ref nou. El d'un compte de proves respon 409 des del costat de producció.
• Crea un endpoint de producció per als esdeveniments de producció. L'endpoint de proves no els rep mai. Crea'l amb una clau de producció o a l'aplicació web en mode Producció.

Relacionat