Registrar una representación

Registra la representación que permite a Factuarea remitir tus registros VeriFactu a la AEAT con su propio certificado.

Envía multipart/form-data con kind (social_collaboration_annex_i o aeat_power_of_attorney), signer_name, signer_tax_id, granted_on y la evidencia: el anexo I firmado como document (PDF, hasta 5 MB, validado por magic bytes) para la colaboración social, y el justificante del apoderamiento como document o su referencia en power_of_attorney_reference para un apoderamiento.
El documento se custodia cifrado y cuenta para tu cuota de almacenamiento (402 storage_quota_exceeded).
Si ya había una representación vigente, se revoca y se conserva en el historial, y la nueva pasa a ser la vigente.
El opcional valid_until fija el último día de vigencia (no antes de granted_on, como máximo 5 años después); sin él, la representación no caduca, y una vez pasado ese día deja de habilitar la remisión por tercero (se te avisa 30 y 7 días antes y al caducar).
Si tu empresa ya remite por un modo de tercero, registrar una representación del OTRO tipo mueve el modo al que ese tipo pide (anexo I → social_collaborator, apoderamiento → power_of_attorney), o de vuelta a own_certificate cuando ese modo no se puede usar, porque esta instancia no ofrece el colaborador social o la nueva representación ya está caducada, y se reactivan los registros que estaban bloqueados esperándola.
Con own_certificate no cambia nada: cambia de modo explícitamente con PUT /v1/verifactu/settings, que exige esta representación.
Devuelve 201 con data (la nueva representación) y remission_mode, el modo de remisión resultante, más una cabecera Location; una carga inválida devuelve 422 (param nombra el campo; la evidencia ausente o que no es un PDF válido es business_rule_violation / invalid_representation).

Clave opaca generada por el cliente (hasta 255 caracteres; se recomienda UUID v7) que permite reintentos seguros: la primera respuesta se almacena y se reproduce en las repeticiones sin volver a ejecutar la mutación. Reutilizar una clave con un cuerpo distinto devuelve 409 idempotency_key_reused. Consulta la guía de idempotencia. Obligatoria en esta operación: repetirla produce un efecto irreversible (un email enviado, un archivo generado, una llamada a un tercero o un cargo), por lo que una petición sin esta cabecera se rechaza con 422 idempotency_key_required antes de ejecutar lógica de negocio.

Longitud1 <= length <= 255

Factuarea-Version?string

Fija la versión de la API (YYYY-MM-DD, versionado por fecha estilo Stripe) para esta petición; omítelo para usar la versión fijada de la clave, o la última si no hay ninguna. Versión no soportada → 400 unsupported_api_version; malformada → 400 parameter_invalid_format. La versión efectiva se refleja en la cabecera de respuesta Factuarea-Version. Consulta la guía de Versioning.

Formatodate

X-Active-Profile?string

Opera en nombre de una empresa hija (API key maestra de gestoría): pasa su id público (UUID v7) y la petición se ejecuta contra los datos de esa hija sin cambiar el scope, el tier ni el environment de la clave (omítelo para usar la propia empresa de la clave). UUID inválido → 400 parameter_invalid_uuid; id desconocido o no propio → 404 profile_not_found. Consulta la guía de Acting on behalf.

Formatouuid

Cuerpo de la petición

multipart/form-data

Definiciones de TypeScript

Usa el tipo request body en TypeScript.

kind*RepresentationKind

Tipo de representación: social_collaboration_annex_i (colaboración social, con el anexo I firmado de la Resolución de 18-12-2024) o aeat_power_of_attorney (un apoderamiento inscrito en la AEAT).

Valor en"social_collaboration_annex_i" | "aeat_power_of_attorney"

signer_name*string

Nombre de la persona que firmó la autorización.

Longitud2 <= length <= 255

signer_tax_id*string

NIF de quien firma.

Longitudlength <= 20

granted_on*string

Fecha en que se otorgó la autorización (YYYY-MM-DD). No puede ser futura.

Formatodate

valid_until?|

Último día de vigencia de la representación (YYYY-MM-DD), opcional: sin él, la representación no caduca. No puede ser anterior a granted_on ni superior a 5 años desde esa fecha (apoderamiento inscrito en el registro de la AEAT, art. 6.4 de la Ley 39/2015); si no, 422 con param=valid_until. Una vez pasado ese día, la representación se informa con is_expired: true y deja de habilitar la remisión por tercero.

Formatodate

power_of_attorney_reference?|

Referencia del apoderamiento en el registro de la AEAT. Para un apoderamiento, envía esta o el document.

Longitudlength <= 255

document?|

Evidencia firmada en PDF (hasta 5 MB, validada por magic bytes): obligatoria para el anexo I, y para un apoderamiento cuando no se envía power_of_attorney_reference. Se custodia cifrada, cuenta para tu cuota de almacenamiento y nunca se devuelve.

Formatobinary

Cuerpo de la respuesta

`application/json`

Ejemplo de petición

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const form = new FormData();form.append("kind", "social_collaboration_annex_i");form.append("signer_name", "María López García");form.append("signer_tax_id", "12345678Z");form.append("granted_on", "2026-03-15");const response = await fetch("https://api.factuarea.com/v1/verifactu/representation", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Idempotency-Key":"erp-2026-public-api-v1-verifactu-representation-register"} },  body: form,});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Ejemplo de respuesta

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a16",
    "object": "verifactu_representation",
    "kind": "aeat_power_of_attorney",
    "signer_name": "Marta Gil Soler",
    "signer_tax_id": "12345678Z",
    "granted_on": "2026-09-15",
    "has_document": true,
    "power_of_attorney_reference": "APO-2026-004512",
    "valid_until": "2029-09-15",
    "is_expired": false,
    "is_active": true,
    "revoked_at": null,
    "revocation_reason": null,
    "created_at": "2026-09-15T11:20:00+02:00"
  },
  "remission_mode": "power_of_attorney"
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Falta header Authorization o X-API-Key.",
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_0d6a8c33ecda476b4347ce2b9d"
  }
}

{
  "error": {
    "type": "payment_required_error",
    "code": "storage_quota_exceeded",
    "message": "El documento no cabe en el espacio de almacenamiento de tu plan. Libera espacio o pasa a un plan con más almacenamiento.",
    "doc_url": "https://docs.factuarea.com/guides/errors#storage_quota_exceeded",
    "request_id": "req_6d2f90c1a7e3458b9a0c1d2e3f"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'verifactu:write'. Tu API key solo tiene los scopes: ninguno.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_c279b961c9ebbfb4271642a920"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "Esa `Idempotency-Key` ya se usó con un payload distinto. La clave identifica una operación concreta, así que reutilizarla para otra vaciaría de sentido el replay.",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_98197f28a07db961c86f3e0579"
  }
}

POST /v1/verifactu/representation · 422 invalid_representation

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "message": "El anexo I firmado es obligatorio para la colaboración social.",
    "subcode": "invalid_representation",
    "param": "document",
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_6d2f90c1a7e3458b9a0c1d2e3f"
  }
}

POST /v1/verifactu/representation · 422 invalid_param_value (valid_until)

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "La fecha de fin de vigencia no puede superar los 5 años desde la fecha de otorgamiento.",
    "param": "valid_until",
    "errors": [
      {
        "param": "valid_until",
        "code": "parameter_invalid_value",
        "message": "La fecha de fin de vigencia no puede superar los 5 años desde la fecha de otorgamiento."
      }
    ],
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_2b7f41d8c06e93a15d4e7c0a39"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el límite de requests permitido. Reintenta más tarde.",
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_393587e6ef94de6b2f0e623685"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.",
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_2e37f673038c91e6fc6787ae0b"
  }
}

Registrar una representación

Authorization

Headers

Cuerpo de la petición

Cuerpo de la respuesta

201application/json

401application/json

402application/json

403application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`