Factuarea API
VeriFactu (AEAT)

Actualitzar la configuració de VeriFactu

Actualitza la configuració VeriFactu de la teva empresa (p. ex. mode/entorn). Retorna 422 `business_rule_violation` quan una transició està bloquejada pel compliment AEAT (per exemple, un cop activat el mode VeriFactu no es pot desactivar silenciosament).

PUT
/verifactu/settings

Authorization

AuthorizationBearer <token>

A: header

Paràmetres de capçalera

Idempotency-Key?string

Clau única generada pel client per garantir la idempotència en els reintents. Et permet reenviar de manera segura la mateixa petició: la primera resposta es cacheja i es retorna sense tornar a executar la mutació. És una cadena opaca per al servidor; qualsevol valor únic de fins a 64 caràcters és vàlid (UUID v7, UUID v4, ULID, nanoid, etc.). Es recomana UUID v7 per coherència amb els identificadors de l'API. La mateixa clau reutilitzada amb un body diferent retorna 409 idempotency_key_reused.

Longitud1 <= length <= 64

Cos de la petició

application/json

Definicions de TypeScript

Usa el tipus request body a TypeScript.

Cos de la resposta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

{
  "data": {
    "object": "verifactu_config",
    "enabled": true,
    "mode": "verifactu",
    "auto_transmit": true,
    "environment": "production",
    "notification_emails": [
      "avisos@empresa.es"
    ],
    "is_locked_until": "2026-12-31T23:59:59+01:00",
    "has_active_certificate": true,
    "active_certificate_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13",
    "updated_at": "2026-04-15T10:30:00+02:00"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se ha proporcionado una API key válida en el header Authorization.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido para esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "La cabecera `Idempotency-Key` ya se usó con un body distinto. Usa una clave nueva o reenvía exactamente el mismo body.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_01HKQS5NHT9A4U7R2E3F8GZWTJ"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "El campo `name` es obligatorio y no puede estar vacío.",
    "param": "name",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid",
    "request_id": "req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
  }
}

Esmenar (subsanar) un registre VeriFactu rebutjat

Esmena (subsana) un registre VeriFactu rebutjat per l'AEAT: regenera el contingut esmenable a partir de la factura origen conservant la `huella` original, reinicia la ronda de transmissió i torna a encuar la transmissió a l'AEAT (202). Retorna 404 si el registre no existeix, 422 `business_rule_violation` amb subcode `record_not_rejected` si el registre no està en estat rebutjat, o `requires_annulment` quan la correcció afecta camps de l'empremta (en el seu lloc cal anul·lació + nova alta).

Obtenir estadístiques de VeriFactu

KPIs agregats dels teus registres VeriFactu: recompte total, recomptes per estat (pending, submitted, accepted, rejected, error), desglossament per tipus de registre i de factura, i data de l'última transmissió. Accepta els filtres opcionals `date_from`, `date_to` i `environment`. Es retorna com a `{ "data": VeriFactuStats }`.