Register a representation

Send multipart/form-data with kind (social_collaboration_annex_i or aeat_power_of_attorney), signer_name, signer_tax_id, granted_on and the evidence: the signed annex I as document (PDF, up to 5 MB, validated by magic bytes) for social collaboration, and the proof of the power of attorney as document or its reference in power_of_attorney_reference for a power of attorney.
The document is custodied encrypted and counts against your storage quota (402 storage_quota_exceeded).
If a representation was already active it is revoked and kept in the history, and the new one becomes the active one.
The optional valid_until sets the last day of validity (not before granted_on, at most 5 years after it); without it the representation does not expire, and once the day has passed it stops enabling third-party remission (you are warned 30 and 7 days ahead and when it expires).
If your company already remits through a third-party mode, registering a representation of the OTHER kind moves the mode to the one that kind asks for (annex I → social_collaborator, power of attorney → power_of_attorney) — or back to own_certificate when that mode cannot be used, because this instance does not offer the social collaborator or the new representation is already expired — and the records that were blocked waiting for it are reactivated.
With own_certificate nothing changes: switch explicitly with PUT /v1/verifactu/settings, which requires this representation.
Returns 201 with data (the new representation) and remission_mode, the remission mode that results, plus a Location header; an invalid payload returns 422 (param names the field; the evidence that is missing or not a valid PDF is business_rule_violation / invalid_representation).

Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns 409 idempotency_key_reused. See the Idempotency guide. Required on this operation: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with 422 idempotency_key_required before any business logic runs.

Length1 <= length <= 255

Factuarea-Version?string

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Formatdate

X-Active-Profile?string

Operate on behalf of a child company (gestoría master key): pass its public id (UUID v7) and the request runs against that child's data without changing the key's scope, tier or environment (omit to use the key's own company). Invalid UUID → 400 parameter_invalid_uuid; unknown or non-owned id → 404 profile_not_found. See the Acting on behalf guide.

Formatuuid

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

kind*RepresentationKind

Kind of representation: social_collaboration_annex_i (social collaboration, with the signed annex I of the Resolution of 18-12-2024) or aeat_power_of_attorney (a power of attorney registered with AEAT).

Value in"social_collaboration_annex_i" | "aeat_power_of_attorney"

signer_name*string

Name of the person who signed the authorization.

Length2 <= length <= 255

signer_tax_id*string

Tax ID (NIF) of the signer.

Lengthlength <= 20

granted_on*string

Date on which the authorization was granted (YYYY-MM-DD). It cannot be in the future.

Formatdate

valid_until?|

Last day of validity of the representation (YYYY-MM-DD), optional: without it the representation does not expire. It cannot be earlier than granted_on nor more than 5 years after it (power of attorney registered in the AEAT register, art. 6.4 of Law 39/2015); otherwise 422 with param=valid_until. Once the day has passed the representation is reported with is_expired: true and stops enabling third-party remission.

Formatdate

power_of_attorney_reference?|

Reference of the power of attorney in the AEAT register. For a power of attorney, send this or the document.

Lengthlength <= 255

document?|

Signed evidence as a PDF (up to 5 MB, validated by magic bytes): required for the annex I, and for a power of attorney when no power_of_attorney_reference is sent. It is custodied encrypted, counts against your storage quota and is never returned.

Formatbinary

Response Body

`application/json`

Request example

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());

Response example

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

Register a representation

Authorization

Headers

Request Body

Response Body

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`