Llistar els lliuraments d'un webhook endpoint de compte

Llista els intents d'entrega d'un webhook endpoint de compte, paginats per cursor amb limit (1-100, 25 per defecte). - ELS MÉS ANTICS PRIMER; filtra per status (pending, delivered, failed, failed_permanently, cancelled) per trobar errors. - Les entregues de l'entorn de prova queden a pending; ending_before retorna 400 parameter_unknown; un endpoint que no veus retorna 404.

Authorization

AuthorizationBearer <token>

La teva API key com a token Bearer: fact_live_… en producció, fact_test_… en sandbox. Consulta la guia d'autenticació.

A: header

Paràmetres de ruta

account*string

Identificador públic (UUID v7) del teu compte. Obtén-lo de GET /v1/me (data.account.id).

Formatuuid

webhook*string

Identificador públic (UUID v7) del webhook endpoint.

Formatuuid

Paràmetres de consulta

status?string

Només els lliuraments en aquest estat: pending, delivered, failed, failed_permanently o cancelled. Qualsevol altre valor retorna 422.

Valor a"pending" | "delivered" | "failed" | "failed_permanently" | "cancelled"

limit?integer

Nombre d'objectes a retornar, entre 1 i 100 (25 per defecte).

Predeterminat25

Rang1 <= value <= 100

starting_after?string

Cursor de paginació cap endavant: passa l'id de l'últim objecte de la pàgina anterior (el next_cursor de la resposta anterior).

Formatuuid

Headers

Factuarea-Version?string

Fixa la versió de l'API (YYYY-MM-DD, versionat per data estil Stripe) per a aquesta petició; omet-lo per usar la versió fixada de la clau, o l'última si no n'hi ha cap. Versió no suportada → 400 unsupported_api_version; mal formada → 400 parameter_invalid_format. La versió efectiva es reflecteix a la capçalera de resposta Factuarea-Version. Consulta la guia de Versioning.

Formatdate

Cos de la resposta

`application/json`

Exemple de petició

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/accounts/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/webhooks/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/deliveries?limit=25", {  method: "GET",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json"} },});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Exemple de resposta

{
  "data": [
    {
      "id": "01933b71-1f0a-7d4b-8e63-5c7f9a2b3d02",
      "object": "account_webhook_delivery",
      "event_id": "01933b70-f2c3-7a15-b8d4-6e9a1b3c4e03",
      "event_type": "account.member_added",
      "event_source": "account",
      "company_id": null,
      "account_relationship": "own",
      "environment": "live",
      "status": "delivered",
      "attempt": 1,
      "manual_retry_count": 0,
      "next_retry_at": null,
      "response_status": 200,
      "response_body": "{\"received\":true}",
      "duration_ms": 142,
      "payload": {
        "id": "01933b70-f2c3-7a15-b8d4-6e9a1b3c4e03",
        "type": "account.member_added",
        "api_version": "2026-10-05",
        "created": 1790590561,
        "livemode": true,
        "test": false,
        "correlation_id": "req_01JQZP8K4M9N2T5V7X0Y3B6D8F",
        "account": {
          "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00"
        },
        "account_relationship": "own",
        "company_id": null,
        "data": {
          "type": "account.member_added",
          "object": {
            "object": "account_member",
            "id": "01933b70-c4d2-7e6a-a1b3-7d8e9f0a1b04",
            "user_id": "01933b70-c4d2-7e6a-a1b3-7d8e9f0a1b05",
            "email": "marta@acme.example",
            "role": "member",
            "previous_role": null
          }
        }
      },
      "payload_api_version": "2026-10-05",
      "cancel_reason": null,
      "delivered_at": "2026-09-28T10:16:02+00:00",
      "failed_at": null,
      "created_at": "2026-09-28T10:16:01+00:00"
    },
    {
      "id": "01933b71-9c2d-7e5f-a674-6d8f0b3c4e06",
      "object": "account_webhook_delivery",
      "event_id": "01933b71-0d5e-7b26-9c15-3f5a7c9e1b07",
      "event_type": "invoice.created",
      "event_source": "company",
      "company_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "account_relationship": "managed",
      "environment": "live",
      "status": "failed",
      "attempt": 3,
      "manual_retry_count": 0,
      "next_retry_at": "2026-09-28T12:20:00+00:00",
      "response_status": 503,
      "response_body": "Service Unavailable",
      "duration_ms": 30012,
      "payload": {
        "id": "01933b71-0d5e-7b26-9c15-3f5a7c9e1b07",
        "type": "invoice.created",
        "api_version": "2026-10-05",
        "created": 1790590561,
        "livemode": true,
        "test": false,
        "correlation_id": "req_01JQZP8K4M9N2T5V7X0Y3B6D8F",
        "account": {
          "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00"
        },
        "account_relationship": "managed",
        "company_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
        "data": {
          "type": "invoice.created",
          "object": {
            "object": "invoice",
            "id": "01933b71-2a6f-7c38-8d25-4e6a8c0f2b08",
            "number": "F-2026-0042",
            "status": "draft"
          }
        }
      },
      "payload_api_version": "2026-10-05",
      "cancel_reason": null,
      "delivered_at": null,
      "failed_at": "2026-09-28T10:20:31+00:00",
      "created_at": "2026-09-28T10:17:01+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /v1/accounts/{account}/webhooks/{webhook}/deliveries · 400 parameter_unknown

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "message": "El parámetro 'ending_before' no es válido para este endpoint.",
    "param": "ending_before",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_unknown",
    "request_id": "req_7b2d8f0bc3a45e7f9d1b2c3a4f"
  }
}

S'ha enviat la capçalera X-Active-Profile retirada

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "subcode": "retired_active_profile_header",
    "message": "La cabecera 'X-Active-Profile' fue retirada de la API v1: la empresa efectiva se indica en el segmento de empresa de la ruta.",
    "param": "X-Active-Profile",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_unknown",
    "request_id": "req_01J8Y3M2Q40000000000000001"
  }
}

Capçalera Factuarea-Version malformada

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid_format",
    "message": "El header 'Factuarea-Version' debe tener formato YYYY-MM-DD.",
    "param": "Factuarea-Version",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid_format",
    "request_id": "req_01J8Y3M2Q40000000000000002"
  }
}

Factuarea-Version no admesa

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_api_version",
    "message": "La versión de API '2020-01-01' no está soportada.",
    "param": "Factuarea-Version",
    "doc_url": "https://docs.factuarea.com/guides/errors#unsupported_api_version",
    "request_id": "req_01J8Y3M2Q40000000000000003"
  }
}

Falta l'API key

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

Format d'API key no vàlid

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La API key no tiene el formato esperado (debe empezar por fact_live_ o fact_test_).",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_api_key",
    "request_id": "req_01HKQS5N9JTQM7HVTQP3FBN5XB"
  }
}

API key revocada

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_revoked",
    "message": "Esta API key ha sido revocada y ya no es válida.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#api_key_revoked",
    "request_id": "req_01HKQS5NA8K7E2V9YDZWMT6RJC"
  }
}

API key caducada

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_expired",
    "message": "Esta API key ha caducado.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#api_key_expired",
    "request_id": "req_01HKQS5NAPIKEYEXPIRED00008"
  }
}

IP de la petició fora de la llista d'accés de l'API key

{
  "error": {
    "type": "authentication_error",
    "code": "ip_not_allowed",
    "message": "La IP 203.0.113.10 no está autorizada para esta API key.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#ip_not_allowed",
    "request_id": "req_01HKQS5NIPNOTALLOWED000009"
  }
}

L'API key no té el scope requerit

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

Cal millorar el pla

{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available_in_plan",
    "message": "Esta funcionalidad requiere el plan empresario o superior. Actualiza tu suscripción para acceder.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#feature_not_available_in_plan",
    "request_id": "req_01HKQS5NCK4V9N2L7Y8X3WPMRE"
  }
}

Pla sense accés a l'API pública

{
  "error": {
    "type": "authorization_error",
    "code": "addon_not_active",
    "message": "Tu plan actual no incluye acceso a la API pública. Contrata o renueva un plan de Factuarea para usar la API.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#addon_not_active",
    "request_id": "req_01HKQS5NDP5W0Q3M8Z9A4BVSNF"
  }
}

Mòdul no disponible amb una clau de prova

{
  "error": {
    "type": "authorization_error",
    "code": "module_not_available_in_sandbox",
    "message": "El módulo \"verifactu\" no está disponible en modo de pruebas. Usa una clave fact_live_ para operar sobre este recurso.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#module_not_available_in_sandbox",
    "request_id": "req_01HKQS5NMODULESANDBOX00010"
  }
}

Privilegi de proveïdor de comptes no concedit

{
  "error": {
    "type": "authorization_error",
    "code": "privileged_scope_required",
    "message": "Esta operación exige el privilegio de proveedor de cuentas (accounts:*) y la persona que emitió la clave debe ser propietaria o administradora de la cuenta",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#privileged_scope_required",
    "request_id": "req_01HKQS5NPRIVILEGEDSCOPE001"
  }
}

Operació del compte propietari sobre un NIF al qual s'arriba per una relació

{
  "error": {
    "type": "authorization_error",
    "code": "forbidden_action",
    "message": "Esta operación solo la puede hacer la cuenta dueña del NIF: con un acceso por relación entre cuentas no está disponible.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#forbidden_action",
    "request_id": "req_01HKQS5NRELATIONNIFOWNER01"
  }
}

Secció retirada a la persona que va emetre la clau

{
  "error": {
    "type": "authorization_error",
    "code": "emitter_capability_restricted",
    "message": "El acceso a la sección «invoices» está restringido para la persona emisora de esta credencial en esta empresa. Pide al administrador de la empresa que lo habilite.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#emitter_capability_restricted",
    "request_id": "req_01J8Y3M2Q40000000000000012"
  }
}

Clau de prova en una escriptura que canvia un compte live

{
  "error": {
    "type": "authorization_error",
    "code": "live_credential_required",
    "message": "Esta operación modifica la cuenta y exige una clave de producción (fact_live_)",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#live_credential_required",
    "request_id": "req_01J8Y3M2Q40000000000000010"
  }
}

Escriptura amb accés de només lectura a l'empresa

{
  "error": {
    "type": "authorization_error",
    "code": "company_read_only",
    "message": "Tu acceso a esta empresa es de solo lectura.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_read_only",
    "request_id": "req_01J8Y3M2Q40000000000000011"
  }
}

GET /v1/accounts/{account}/webhooks/{webhook}/deliveries · 404 webhook_endpoint_not_found

{
  "error": {
    "type": "not_found_error",
    "code": "webhook_endpoint_not_found",
    "message": "Endpoint de webhook de cuenta no encontrado.",
    "doc_url": "https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found",
    "request_id": "req_8c3e9a1cd4b56f8a0e2c3d4b5a"
  }
}

Compte no trobat o no és el compte de l'API key

{
  "error": {
    "type": "not_found_error",
    "code": "account_not_found",
    "message": "La cuenta indicada no existe o no es la de tu credencial.",
    "param": "account",
    "doc_url": "https://docs.factuarea.com/guides/errors#account_not_found",
    "request_id": "req_01J8Y3M2Q40000000000000006"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "El estado indicado no es válido. Valores permitidos: pending, delivered, failed, failed_permanently, cancelled.",
    "param": "status",
    "errors": [
      {
        "param": "status",
        "code": "parameter_invalid_value",
        "message": "El estado indicado no es válido. Valores permitidos: pending, delivered, failed, failed_permanently, cancelled."
      }
    ],
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_9d4f0b2de5c67a9b1f3d4e5c6b"
  }
}

Límit de peticions superat

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

Massa errors d'autenticació (bloqueig temporal)

{
  "error": {
    "type": "authentication_error",
    "code": "too_many_auth_failures",
    "message": "Has alcanzado el número máximo de intentos de autenticación fallidos. La API key queda bloqueada temporalmente. Reintenta tras el tiempo indicado en `Retry-After`.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#too_many_auth_failures",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVM"
  }
}

Massa pujades simultànies en curs

{
  "error": {
    "type": "rate_limit_error",
    "code": "upload_in_flight_budget_exceeded",
    "message": "Tu empresa tiene demasiadas subidas en curso a la vez: este archivo ocupa 10 MB y el margen simultáneo es de 120 MB. Espera a que terminen las subidas en marcha y vuelve a intentarlo dentro de 45 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#upload_in_flight_budget_exceeded",
    "request_id": "req_01HKQS5NUPLOADINFLIGHT005"
  }
}

Límit de peticions de tota l'empresa superat (totes les claus combinades)

{
  "error": {
    "type": "rate_limit_error",
    "code": "company_rate_limit_exceeded",
    "message": "Tu empresa ha superado su límite conjunto de 900 peticiones por minuto, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. Reintenta en 12 segundos, o solicita una ampliación de plan si necesitas más capacidad.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_rate_limit_exceeded",
    "request_id": "req_01HKQS5NCOMPANYRATELIMIT06"
  }
}

Quota mensual de tota l'empresa exhaurida (totes les claus combinades)

{
  "error": {
    "type": "rate_limit_error",
    "code": "company_monthly_quota_exceeded",
    "message": "Tu empresa ha agotado su cuota conjunta de 150000 peticiones de este mes, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. El contador se reinicia el día 1 del mes siguiente; solicita una ampliación de plan si necesitas más volumen antes.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_monthly_quota_exceeded",
    "request_id": "req_01HKQS5NCOMPANYMONTHLY0007"
  }
}

Quota mensual de l'API key esgotada

{
  "error": {
    "type": "rate_limit_error",
    "code": "monthly_quota_exceeded",
    "message": "Has agotado tu cuota mensual de 100000 requests. Mejora tu plan para obtener una cuota superior.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#monthly_quota_exceeded",
    "request_id": "req_01HKQS5NMONTHLYQUOTA000011"
  }
}

Límit de peticions de la cartera superat (tots els NIF del compte junts)

{
  "error": {
    "type": "rate_limit_error",
    "code": "portfolio_rate_limit_exceeded",
    "message": "La cartera de tu cuenta ha superado su límite conjunto de 1800 peticiones por minuto, contando a la vez todos sus NIF. Es un techo de la cartera, así que repartir el tráfico entre NIF no lo eleva. Reintenta en 12 segundos, o solicita una ampliación de plan si necesitas más capacidad.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#portfolio_rate_limit_exceeded",
    "request_id": "req_01HKQS5NPORTFOLIORATE00012"
  }
}

Quota mensual de la cartera esgotada (tots els NIF del compte junts)

{
  "error": {
    "type": "rate_limit_error",
    "code": "portfolio_monthly_quota_exceeded",
    "message": "La cartera de tu cuenta ha agotado su cuota conjunta de 300000 peticiones de este mes, contando a la vez todos sus NIF. Es un techo de la cartera, así que repartir el tráfico entre NIF no lo eleva. El contador se reinicia el día 1 del mes siguiente; solicita una ampliación de plan si necesitas más volumen antes.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#portfolio_monthly_quota_exceeded",
    "request_id": "req_01HKQS5NPORTFOLIOMONTH0013"
  }
}

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

Llistar els lliuraments d'un webhook endpoint de compte

Authorization

Paràmetres de ruta

Paràmetres de consulta

Headers

Cos de la resposta

200application/json

400application/json

401application/json

403application/json

404application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`