Factuarea API
Productes

Llistar tots els productes

Llista els productes del teu catàleg amb paginació per cursor.

GET
/products

Authorization

AuthorizationBearer <token>

A: header

Paràmetres de consulta

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
sku?string

SKU del producte. Coincidència exacta en sku.

sku[in]?string

SKU del producte. Llista separada per comes. Coincideix qualsevol dels valors.

name?string

Nom del producte. Coincidència exacta en name.

is_active?boolean

Filtra per productes actius / inactius. Coincidència exacta en is_active.

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
price[gte]?number

Preu unitari. Major o igual que el valor donat.

price[lte]?number

Preu unitari. Menor o igual que el valor donat.

price[gt]?number

Preu unitari. Estrictament major que el valor donat.

price[lt]?number

Preu unitari. Estrictament menor que el valor donat.

in_stock?boolean

Filtra per productes amb stock disponible (true → stock > 0) o sense stock (false → stock = 0). Coincidència exacta en in_stock.

low_stock?boolean

Filtra per productes amb stock baix (true → 0 < stock ≤ llindar configurat) o amb stock ampli (false → stock > llindar). Coincidència exacta en low_stock.

tag?string

Filtra per etiqueta de classificació. Admet múltiples valors amb tag[in]. Coincidència exacta en tag.

tag[in]?string

Filtra per etiqueta de classificació. Admet múltiples valors amb tag[in]. Llista separada per comes. Coincideix qualsevol dels valors.

Cos de la resposta

application/json

application/json

application/json

application/json

application/json

application/json

{
  "data": [
    {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09",
      "object": "product",
      "name": "Teclado mecánico RGB",
      "sku": "KEY-RGB-01",
      "price": "1234.56",
      "currency": "EUR",
      "tax_rate": {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f",
        "rate": 21
      },
      "stock": 120,
      "gallery": [
        {
          "index": 0,
          "url": "https://files.factuarea.com/products/key-rgb-01-front.jpg",
          "content_type": "image/jpeg"
        }
      ],
      "video": {
        "url": "https://files.factuarea.com/products/key-rgb-01-demo.mp4",
        "content_type": "video/mp4"
      },
      "is_active": true,
      "description": "Teclat mecànic retroil·luminat RGB amb switches Cherry MX Red i carcassa d'alumini.",
      "tags": [
        "periféricos",
        "gaming"
      ],
      "low_stock_threshold": 10,
      "is_low_stock": false,
      "is_in_stock": true,
      "specifications": {
        "switch": "Cherry MX Red",
        "layout": "ES",
        "conexion": "USB-C"
      },
      "metadata": {
        "erp_code": "IVA-GEN",
        "ledger_account": "477000"
      },
      "external_id": "SHOP-42",
      "created_at": "2026-01-02T08:30:00Z",
      "updated_at": "2026-01-02T08:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"
}

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

Puja una imatge de galeria a un producte

Adjunta una imatge (jpeg, png, jpg, gif o webp; fins a 3 MB) a la galeria del producte. Retorna el producte actualitzat. Falla amb 422 si se supera el límit de la galeria.

Llista els productes per sota del llindar d'stock

Retorna els productes el stock actual dels quals està per sota del seu llindar de stock baix configurat. Útil per a alertes d'inventari.