Listar escaneos de compras

Lista los documentos recibidos por el escáner de compras (subida, API o buzón), con su estado, incidencias de extracción y available_actions.

Utiliza filter[status], filter[source] y los filtros de fecha e intervalo documentados; paginación mediante cursor.

Authorization

AuthorizationBearer <token>

En: header

Parámetros de consulta

limit?integer

Rango1 <= value <= 100

starting_after?|

Formatouuid

ending_before?|

Formatouuid

search?string

Longitudlength <= 200

sort?string

Valor en"received_at" | "-received_at" | "issue_date" | "-issue_date" | "total" | "-total" | "status" | "-status"

filter[status]?string

Valor en"received" | "queued" | "processing" | "needs_review" | "duplicate" | "failed" | "auto_created" | "created" | "archived"

filter[source][]?array<>

Valor en"upload" | "email" | "api"

filter[supplier_id][]?array<>

Formatouuid

filter[document_kind][]?array<>

Valor en"invoice" | "simplified_qualified" | "ticket" | "delivery_note" | "other" | "undetermined"

filter[file_kind][]?array<>

Valor en"pdf" | "image"

filter[supplier_link_state][]?array<>

Valor en"linked" | "pending_link" | "unidentified"

filter[has_issues]?boolean

filter[sender]?string

Longitudlength <= 254

filter[source]?string

Lista separada por comas de orígenes del escaneo. Valores permitidos: upload, email, api.

filter[document_kind]?string

Lista separada por comas de tipos de documento. Valores permitidos: invoice, simplified_qualified, ticket, delivery_note, other, undetermined.

filter[file_kind]?string

Lista separada por comas de tipos de archivo. Valores permitidos: pdf, image.

filter[supplier_link_state]?string

Lista separada por comas de estados de vínculo con el proveedor. Valores permitidos: linked, pending_link, unidentified.

filter[supplier_id]?string

Lista separada por comas de ids de proveedor (hasta 20).

Formatouuid

filter[created][eq]?string

Formatodate

filter[created][gt]?string

Formatodate

filter[created][gte]?string

Formatodate

filter[created][lt]?string

Formatodate

filter[created][lte]?string

Formatodate

filter[issued_on][eq]?string

Formatodate

filter[issued_on][gt]?string

Formatodate

filter[issued_on][gte]?string

Formatodate

filter[issued_on][lt]?string

Formatodate

filter[issued_on][lte]?string

Formatodate

filter[total][eq]?string

Coincidencia^-?(?:0|[1-9]\d*)(?:\.\d{1,4})?$

filter[total][gt]?string

Coincidencia^-?(?:0|[1-9]\d*)(?:\.\d{1,4})?$

filter[total][gte]?string

Coincidencia^-?(?:0|[1-9]\d*)(?:\.\d{1,4})?$

filter[total][lt]?string

Coincidencia^-?(?:0|[1-9]\d*)(?:\.\d{1,4})?$

filter[total][lte]?string

Coincidencia^-?(?:0|[1-9]\d*)(?:\.\d{1,4})?$

Headers

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 respuesta

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Ejemplo de petición

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/purchase_scans?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());

Ejemplo de respuesta

{
  "data": [
    {
      "id": "019e0000-0000-7000-8000-000000000042",
      "version": 3,
      "source": "api",
      "status": "needs_review",
      "original_filename": "factura-proveedor.pdf",
      "mime_type": "application/pdf",
      "page_count": 1,
      "received_at": "2026-09-12T10:30:00Z",
      "uploaded_by": {
        "name": "Administración"
      },
      "supplier_id": "019e0000-0000-7000-8000-000000000010",
      "supplier_name": "Suministros Ejemplo SL",
      "document_number": "PROV-2026-0042",
      "issue_date": "2026-09-12",
      "currency": "EUR",
      "total": "121",
      "issue_count": 0,
      "available_actions": [
        "save_review",
        "convert",
        "archive",
        "download_source"
      ],
      "purchase_invoice_id": null,
      "last_error": null,
      "deferred_until": null,
      "deferred_reason": null,
      "document_kind": "invoice",
      "file_kind": "pdf",
      "supplier_link_state": "linked"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "message": "La consulta incluye un parámetro no admitido.",
    "doc_url": "https://docs.factuarea.com/errors/parameter_unknown",
    "request_id": "req_scanner_example",
    "param": "filter[unknown]"
  }
}

Falta la 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"
  }
}

Formato de API key no válido

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

La API key carece del scope requerido

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

Se requiere mejorar el plan

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

Plan sin acceso a la 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"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "El valor del parámetro de consulta no es válido.",
    "doc_url": "https://docs.factuarea.com/errors/invalid_param_value",
    "request_id": "req_scanner_example",
    "param": "filter[status]"
  }
}

Límite de peticiones superado

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

Demasiados fallos de autenticación (bloqueo 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"
  }
}

Too many concurrent uploads in flight

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

Company-wide rate limit exceeded (all keys combined)

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

Company-wide monthly quota exhausted (all keys combined)

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

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