Verificación censal AEAT

Factuarea puede comprobar que el par razón social + NIF de tu empresa está correctamente identificado en el censo de la AEAT — la misma identificación que realiza la AEAT cuando recibe tus registros de facturación VeriFactu. Un par no censado provoca el rechazo del envío (error AEAT 4104, titular no identificado), así que verificar pronto — justo después del registro y cada vez que cambien tus datos fiscales — te ahorra envíos rechazados después.

POST /v1/account/census-verification

• Scope: account:read
• Body de la request: ninguno — la comprobación se ejecuta siempre contra la razón social y el tax_id persistidos de la cuenta autenticada. Nunca acepta un NIF o nombre arbitrario en el payload.
• Efecto: el resultado se guarda como snapshot en tu empresa (visible en los ajustes de la app de Factuarea). Cambiar la razón social o el tax_id resetea el snapshot hasta que vuelvas a verificar.

Llamar al endpoint

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

Respuesta (200):

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

verified_name es la razón social que se contrastó contra el censo (la persistida). checked_at es el momento de la verificación, en ISO 8601.

Con los SDK oficiales:

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 también a tus clientes

La AEAT ejecuta la misma identificación sobre el destinatario de cada registro de facturación VeriFactu: un cliente cuyo par nombre + NIF no está censado provoca el rechazo del envío con el error AEAT 1239 (destinatario no identificado).

Factuarea no valida deliberadamente a los clientes contra el censo al crearlos — y es por diseño, no un descuido: los clientes extranjeros no tienen entrada en el censo español, las empresas recién constituidas pueden tardar días en aparecer, las facturas simplificadas B2C no llevan NIF de destinatario, y el propio servicio de la AEAT puede estar caído (toda la funcionalidad es fail-open). Bloquear la creación de clientes por el censo rompería todos esos flujos legítimos.

El patrón recomendado es otro: verifica el par nombre + NIF justo antes de emitir facturas VeriFactu a ese cliente con el endpoint dedicado:

POST /v1/clients/census-verification

• Scope: clients:read
• Body de la request: tax_id (NIF/CIF/NIE) y name — el par se comprueba conjuntamente, exactamente igual que lo comprobará la AEAT en el envío. No necesita corresponder a un cliente existente: la comprobación es stateless y no persiste nada en tus clientes.
• Límite de peticiones: 5 verificaciones por minuto, como el endpoint de la cuenta.

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"}'

Respuesta (200):

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

Los valores de status son los mismos seis que en la verificación de la cuenta (tabla más abajo). Cómo actuar con ellos para un cliente:

• identified — emite con normalidad.
• not_identified — un envío VeriFactu a este destinatario tiene el rechazo 1239 garantizado. Pide al cliente su razón social exacta y su NIF antes de emitir.
• not_identified_similar — (personas físicas) usa el nombre exacto tal como está registrado en la AEAT.
• unavailable — la AEAT no pudo responder; la comprobación es informativa, así que puedes emitir igualmente y reintentar la verificación más tarde.

Estados posibles

status es siempre uno de estos seis valores:

Ramifica según status, los valores son un contrato congelado. Ten en cuenta que los estados negativos no son errores HTTP: toda verificación completada devuelve 200.

Fail-open por diseño

La verificación nunca rompe tu flujo porque la AEAT esté caída:

• Timeout de la AEAT, SOAP fault o respuesta no reconocida → 200 con status: unavailable. Nunca un 5xx por esta causa.
• Los resultados se cachean en el servidor durante un periodo corto, de modo que los reintentos inmediatos del mismo par no vuelven a llamar a la AEAT (unavailable se cachea solo unos segundos para que puedas reintentar pronto).

Errores

El único error de negocio es una empresa sin datos fiscales:

{
  "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 guía del envoltorio de error para el contrato completo de errores.

Límite de peticiones

El endpoint está limitado a 5 verificaciones por minuto por cuenta, independientemente del tier global de límite de peticiones de tu clave. Por encima recibes un 429 — espera a que la ventana se reinicie y reintenta.

Modo de prueba: NIFs mágicos

Con una clave fact_test_ (modo de prueba) la verificación nunca llega a la AEAT. El sandbox devuelve estados deterministas según el tax_id de la empresa sandbox, para que puedas ejercitar todas las ramas de tu integración:

Todos los NIFs mágicos llevan una letra de control válida, así que pasan la validación estándar de NIF. Configura el tax_id de la empresa sandbox con el valor mágico que quieras probar y llama al endpoint con tu clave 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"
  }
}