Verificació censal AEAT

Factuarea pot comprovar que el parell raó social + NIF de la teva empresa està correctament identificat al cens de l'AEAT — la mateixa identificació que fa l'AEAT quan rep els teus registres de facturació VeriFactu. Un parell no censat provoca el rebuig de l'enviament (error AEAT 4104, titular no identificat), així que verificar aviat — just després del registre i cada cop que canviïn les teves dades fiscals — t'estalvia enviaments rebutjats després.

POST /v1/account/census-verification

• Scope: account:read
• Body de la request: cap — la comprovació s'executa sempre contra la raó social i el tax_id persistits del compte autenticat. Mai no accepta un NIF o nom arbitrari al payload.
• Efecte: el resultat es desa com a snapshot a la teva empresa (visible als ajustos de l'app de Factuarea). Canviar la raó social o el tax_id reinicia l'snapshot fins que tornis a verificar.

Cridar l'endpoint

curl -X POST https://api.factuarea.com/v1/account/census-verification \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Idempotency-Key: $(uuidgen)"

Resposta (200):

{
  "data": {
    "object": "census_verification",
    "status": "identified",
    "verified_name": "ACME SOLUTIONS SL",
    "checked_at": "2026-06-10T22:15:04+00:00"
  }
}

verified_name és la raó social que es va contrastar contra el cens (la persistida). checked_at és el moment de la verificació, en ISO 8601.

Amb els SDK oficials:

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

const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });

const result = await factuarea.account.verifyCensus();
// result.data.status → "identified" | "not_identified" | …

<?php

use Factuarea\Sdk\Custom\FactuareaClient;

$factuarea = FactuareaClient::create(getenv('FACTUAREA_API_KEY'));

$response = $factuarea->account->publicApiV1AccountVerifyCensus();

Verifica també els teus clients

L'AEAT executa la mateixa identificació sobre el destinatari de cada registre de facturació VeriFactu: un client el parell nom + NIF del qual no està censat provoca el rebuig de l'enviament amb l'error AEAT 1239 (destinatari no identificat).

Factuarea no valida deliberadament els clients contra el cens en crear-los — i és per disseny, no un descuit: els clients estrangers no tenen entrada al cens espanyol, les empreses acabades de constituir poden trigar dies a aparèixer, les factures simplificades B2C no porten NIF de destinatari, i el mateix servei de l'AEAT pot estar caigut (tota la funcionalitat és fail-open). Bloquejar la creació de clients pel cens trencaria tots aquests fluxos legítims.

El patró recomanat és un altre: verifica el parell nom + NIF just abans d'emetre factures VeriFactu a aquest client amb l'endpoint dedicat:

POST /v1/clients/census-verification

• Scope: clients:read
• Body de la request: tax_id (NIF/CIF/NIE) i name — el parell es comprova conjuntament, exactament igual que ho comprovarà l'AEAT en l'enviament. No cal que correspongui a un client existent: la comprovació és stateless i no persisteix res als teus clients.
• Límit de peticions: 5 verificacions per minut, com l'endpoint del compte.

curl -X POST https://api.factuarea.com/v1/clients/census-verification \
  -H "Authorization: Bearer fact_live_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -d '{"tax_id": "B12345674", "name": "CONSTRUCCIONES PEREZ SL"}'

Resposta (200):

{
  "data": {
    "object": "census_verification",
    "status": "identified",
    "verified_name": "CONSTRUCCIONES PEREZ SL",
    "checked_at": "2026-06-11T09:30:00Z"
  }
}

Els valors de status són els mateixos sis que a la verificació del compte (taula més avall). Com actuar-hi per a un client:

• identified — emet amb normalitat.
• not_identified — un enviament VeriFactu a aquest destinatari té el rebuig 1239 garantit. Demana al client la seva raó social exacta i el seu NIF abans d'emetre.
• not_identified_similar — (persones físiques) fes servir el nom exacte tal com està registrat a l'AEAT.
• unavailable — l'AEAT no va poder respondre; la comprovació és informativa, així que pots emetre igualment i reintentar la verificació més tard.

Estats possibles

status és sempre un d'aquests sis valors:

Ramifica segons status, els valors són un contracte congelat. Tingues en compte que els estats negatius no són errors HTTP: tota verificació completada retorna 200.

Fail-open per disseny

La verificació mai no trenca el teu flux perquè l'AEAT estigui caiguda:

• Timeout de l'AEAT, SOAP fault o resposta no reconeguda → 200 amb status: unavailable. Mai un 5xx per aquesta causa.
• Els resultats es cachegen al servidor durant un període curt, de manera que els reintents immediats del mateix parell no tornen a cridar l'AEAT (unavailable es cacheja només uns segons perquè puguis reintentar aviat).

Errors

L'únic error de negoci és una empresa sense dades fiscals:

{
  "error": {
    "type": "invalid_request_error",
    "code": "census_requires_tax_id",
    "message": "Configura primero los datos fiscales de tu empresa para verificar el censo.",
    "param": "tax_id"
  }
}

Consulta la guia de l'embolcall d'error per al contracte complet d'errors.

Límit de peticions

L'endpoint està limitat a 5 verificacions per minut per compte, independentment del tier global de límit de peticions de la teva clau. Per sobre reps un 429 — espera que la finestra es reiniciï i reintenta.

Mode de prova: NIFs màgics

Amb una clau fact_test_ (mode de prova) la verificació mai no arriba a l'AEAT. El sandbox retorna estats deterministes segons el tax_id de l'empresa sandbox, perquè puguis exercitar totes les branques de la teva integració:

Tots els NIFs màgics porten una lletra de control vàlida, així que passen la validació estàndard de NIF. Configura el tax_id de l'empresa sandbox amb el valor màgic que vulguis provar i crida l'endpoint amb la teva clau fact_test_:

curl -X POST https://api.factuarea.com/v1/account/census-verification \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Idempotency-Key: $(uuidgen)"

{
  "data": {
    "object": "census_verification",
    "status": "identified_revoked",
    "verified_name": "SANDBOX COMPANY SL",
    "checked_at": "2026-06-10T22:15:04+00:00"
  }
}