Llistar totes les factures

Llista les teves factures de venda amb paginació per cursor.

Admet filtratge per status[in], client_id, series_id, issued_on[gte|lte] i total[gte|lte].

Paràmetres de consulta

original_invoice_id?|

Formatuuid

verifactu_status?|

Valor a"no_verifactu" | "pending" | "accepted" | "rejected" | null

limit?integer

Nombre d'objectes a retornar. Enter entre 1 i 100. Per defecte 25.

Predeterminat25

Rang1 <= value <= 100

starting_after?string

Cursor per a paginació cap endavant. Fes servir l'uuid de l'últim objecte de la pàgina anterior.

Formatuuid

ending_before?string

Cursor per a paginació cap enrere. Fes servir l'uuid del primer objecte de la pàgina actual.

Formatuuid

status?string

Estat de la factura. Coincidència exacta amb status.

status[in]?string

Estat de la factura. Llista separada per comes. Coincideix qualsevol dels valors.

client_id?string

Client ID (UUID v7). Coincidència exacta amb client_id.

Formatuuid

client_id[in]?string

Client ID (UUID v7). Llista separada per comes. Coincideix qualsevol dels valors.

series_id?string

Series ID (UUID v7). Coincidència exacta amb series_id.

Formatuuid

series_id[in]?string

Series ID (UUID v7). Llista separada per comes. Coincideix qualsevol dels valors.

created[gte]?string

Data de creació (ISO 8601). Major o igual que el valor donat.

Formatdate-time

created[lte]?string

Data de creació (ISO 8601). Menor o igual que el valor donat.

Formatdate-time

created[gt]?string

Data de creació (ISO 8601). Estrictament major que el valor donat.

Formatdate-time

created[lt]?string

Data de creació (ISO 8601). Estrictament menor que el valor donat.

Formatdate-time

due_on[gte]?string

Data de venciment. Més gran o igual que el valor indicat.

Formatdate

due_on[lte]?string

Data de venciment. Més petita o igual que el valor indicat.

Formatdate

due_on[gt]?string

Data de venciment. Estrictament més gran que el valor indicat.

Formatdate

due_on[lt]?string

Data de venciment. Estrictament més petita que el valor indicat.

Formatdate

total[gte]?number

Import total. Major o igual que el valor donat.

total[lte]?number

Import total. Menor o igual que el valor donat.

total[gt]?number

Import total. Estrictament major que el valor donat.

total[lt]?number

Import total. Estrictament menor que el valor donat.

currency?string

Codi de moneda ISO 4217 (p. ex. EUR). Coincidència exacta amb currency.

currency[in]?string

Codi de moneda ISO 4217 (p. ex. EUR). Llista separada per comes. Coincideix qualsevol dels valors.

number?string

Número de factura. Coincidència exacta amb number.

tags?string

Filtrar per tag de classificació (slug en minúscula). Admet múltiples valors amb tags[in]=a,b (JSON_CONTAINS, semàntica OR — coincideix amb les factures que porten QUALSEVOL dels tags). Coincidència exacta sobre tags.

tags[in]?string

sort?string

Ordre dels resultats. Fes servir un camp per a ascendent o un prefix - per a descendent (p. ex. -created). Camps permesos: created, total, number. Combinat amb el cursor, l'ordre es manté determinista (un ordre secundari estable per l'id del cursor, a l'estil Stripe). Si s'omet, els resultats segueixen l'ordre de cursor per defecte (created descendent).

search?string

Cerca de text lliure. LIKE %term% escapat (sense distingir majúscules, màx. 80 caràcters) sobre les columnes de text clau del recurs, combinat amb la resta de filtres (AND) i compatible amb el cursor.

Longitudlength <= 80

metadata?

Filtra per parells clau/valor de metadata usant la sintaxi deepObject metadata[key]=value. Diversos parells es combinen amb AND. Cada clau ha de complir [A-Za-z0-9_.-]{1,64}; es permeten un màxim de 50 parells (més → 422).

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

X-Active-Profile?string

Opera en nom d'una empresa filla (API key mestra de gestoria): passa el seu id públic (UUID v7) i la petició s'executa contra les dades d'aquella filla sense canviar l'scope, el tier ni l'environment de la clau (omet-lo per usar la pròpia empresa de la clau). UUID no vàlid → 400 parameter_invalid_uuid; id desconegut o no propi → 404 profile_not_found. Consulta la guia d'Acting on behalf.

Formatuuid

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/invoices?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": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
      "object": "invoice",
      "number": "FAC-2026-00042",
      "is_number_assigned": true,
      "type": "F1",
      "series": {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02",
        "code": "FAC-2026"
      },
      "client": {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
        "name": "Acme Soluciones SL"
      },
      "status": "paid",
      "price_list_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10",
      "price_list_name": "Tarifa profesional 2026",
      "issued_on": "2026-03-15",
      "due_on": "2026-04-14",
      "subtotal": 1000,
      "taxes_total": 210,
      "total_vat": 210,
      "total_retention": 0,
      "total_surcharge": 0,
      "total": 1210,
      "total_disbursements": 0,
      "total_to_pay": 1210,
      "currency": "EUR",
      "notes": "Servicios profesionales marzo 2026.",
      "external_id": "ERP-2026-0042",
      "lines": [
        {
          "object": "invoice_line",
          "description": "Consultoría técnica (10 h)",
          "additional_description": "Auditoría inicial e informe de mejoras",
          "product": {
            "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03",
            "name": "Consultoría técnica (hora)"
          },
          "quantity": 10,
          "unit_price": 100,
          "tax_rate": 21,
          "retention_rate": 0,
          "surcharge_rate": 0,
          "discount_percent": 0,
          "subtotal": 1000,
          "taxes": 210,
          "total": 1210,
          "indirect_tax_regime": "iva",
          "variant": null,
          "presentation": null,
          "item_kind": "service",
          "commercial_unit_code": "HUR",
          "base_unit_code": "HUR",
          "conversion_factor": "1.000000",
          "base_quantity": "10.0000",
          "price_list_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10",
          "price_list_name": "Tarifa profesional 2026",
          "price_source": "price_list",
          "price_unit_code": "HUR",
          "configuration": null,
          "options": [],
          "price_semantics": "per_commercial_unit",
          "price_adjustment_total": "0.0000",
          "option_adjustments_absorbed": false,
          "regime_key": null,
          "exemption_reason": null,
          "aeat_tax_code": "S1",
          "line_type": "NORMAL",
          "source_invoice_reference": null,
          "source_invoice_ids": null,
          "unit": null,
          "exemption_reason_text": null
        }
      ],
      "metadata": {
        "order_id": "PO-2026-0042"
      },
      "tags": [
        "consultoria",
        "cliente-vip"
      ],
      "custom_fields": [
        {
          "field": "centro_coste",
          "value": "CC-2026-001"
        },
        {
          "field": "numero_pedido",
          "value": "PO-2026-0042"
        }
      ],
      "operation_regime": "general",
      "exemption_reason": null,
      "legal_mentions": [],
      "exclude_347": false,
      "verifactu_status": "accepted",
      "paid_amount": 1210,
      "pending_amount": 0,
      "payments": {
        "detail": [
          {
            "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90",
            "object": "payment",
            "invoice_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
            "amount": 1210,
            "payment_date": "2026-03-20",
            "payment_method": "bank_transfer",
            "payment_method_text": "Transferencia bancaria",
            "reference": "TRF-2026-0042",
            "notes": null,
            "is_reversed": false,
            "reversed_at": null,
            "reversal_reason": null,
            "reversal_reason_text": null,
            "reversal_note": null,
            "created_at": "2026-03-20T10:30:00Z",
            "updated_at": "2026-03-20T10:30:00Z"
          }
        ],
        "total": 1210,
        "pending": 0
      },
      "is_corrective": false,
      "corrective": null,
      "payment": {
        "method": "bank_transfer",
        "reference": "TRF-2026-0042",
        "date": "2026-03-20"
      },
      "public_link": {
        "object": "public_link",
        "url": "https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
        "enabled": true,
        "expires_at": "2026-09-15T23:59:59Z",
        "max_days": 120
      },
      "substituted_by": null,
      "recurring": null,
      "paid_at": "2026-03-20T10:30:00Z",
      "paid_on": "2026-03-20",
      "sent_at": "2026-03-15T11:45:00Z",
      "voided_at": null,
      "void_reason": null,
      "scheduled_for": null,
      "scheduled_action": null,
      "channel": null,
      "source_store_id": null,
      "created_at": "2026-03-15T11:30:00Z",
      "updated_at": "2026-03-20T10:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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

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

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_1abc4910dcb3d1ae1bab11e685"
  }
}

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

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

Llistar totes les factures

Authorization

Paràmetres de consulta

Headers

Cos de la resposta

200application/json

401application/json

403application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`