Colecciones

Las colecciones agrupan productos para fines comerciales — vitrinas, promociones, curaduría editorial — de forma independiente a la categorización taxonómica (Categorías). Soportan jerarquía (una colección puede tener colecciones hijas vía parentId) y orden manual de sus productos.

Base path distinto de /products

Este dominio vive bajo /collections, un recurso de API Gateway propio (fenicia-collections-{stage}) — no es un sub-recurso de /products. Usa https://api.fenicia.io/collections/... directamente, no /products/collections/....

Autenticación: igual que el resto de la API — Authorization: Bearer fkapi_..., 401 si no se resuelve el tenant, 403 si el tenant está suspendido. Todas las operaciones de escritura y lectura exigen además el permiso collections:* correspondiente.

Listar y consultar colecciones

Lista colecciones con paginación y filtros

pagenumber

Página.

limitnumber

Elementos por página.

searchstring

Búsqueda de texto por nombre.

statusstring

Filtra por estado de la colección.

collectionTypestring

Filtra por tipo de colección.

scopestring

Filtra por alcance de la colección.

purposestring

Filtra por propósito de la colección.

parentIdstring

Filtra por colección padre.

200
{
  "items": [
    {
      "id": "65f5a1b2c4d5e6f7a8b9c1a1",
      "name": { "value": "Novedades verano" },
      "status": "active",
      "collectionType": "manual",
      "parentId": null,
      "sortOrder": 0
    }
  ],
  "total": 1,
  "page": 0,
  "limit": 20
}

Permiso requerido: collections:read

Shape de respuesta no verificado campo a campo

Los parámetros de filtro están confirmados contra el código fuente (son los mismos campos que soporta CollectionsService.search). El envelope exacto de paginación (nombres de las claves) no fue verificado campo por campo — confírmalo contra una respuesta real antes de depender de su forma exacta.

Devuelve el árbol completo de colecciones, o el subárbol de una raíz dada

rootIdstring

ID de la colección raíz del subárbol. Si se omite, devuelve el árbol completo.

200
[
  {
    "id": "65f5a1b2c4d5e6f7a8b9c1a1",
    "name": { "value": "Novedades verano" },
    "parentId": null,
    "children": [
      { "id": "65f5a1b2c4d5e6f7a8b9c1a2", "name": { "value": "Playeras" }, "parentId": "65f5a1b2c4d5e6f7a8b9c1a1", "children": [] }
    ]
  }
]

Permiso requerido: collections:read

Obtiene una colección por ID

idstringrequired

ID de la colección.

200
{
  "id": "65f5a1b2c4d5e6f7a8b9c1a1",
  "name": { "value": "Novedades verano" },
  "status": "active",
  "collectionType": "manual",
  "scope": "storefront",
  "purpose": "merchandising",
  "parentId": null,
  "sortOrder": 0
}
404
{ "code": "not-found", "message": "Collection not found" }

Permiso requerido: collections:read

Lista las colecciones hijas directas de una colección

idstringrequired

ID de la colección padre.

200
[
  { "id": "65f5a1b2c4d5e6f7a8b9c1a2", "name": { "value": "Playeras" }, "parentId": "65f5a1b2c4d5e6f7a8b9c1a1" }
]

Permiso requerido: collections:read

Crear, actualizar y mover colecciones

Crea una colección

nameobjectrequired

{ value: string } — nombre de la colección. Es el único campo confirmado como requerido.

{ "name": { "value": "Novedades verano" } }
201
{
  "id": "65f5a1b2c4d5e6f7a8b9c1a1",
  "name": { "value": "Novedades verano" },
  "status": "active",
  "sortOrder": 0
}
400
{ "code": "bad-request", "message": "Collection name is required" }

Permiso requerido: collections:create

Actualiza una colección (parcial)

idstringrequired

ID de la colección.

{ "name": { "value": "Novedades otoño" }, "status": "active" }
404
{ "code": "not-found", "message": "Collection not found" }
400
{ "code": "bad-request", "message": "Request body is required" }

Permiso requerido: collections:update

Mueve una colección a otro padre y/o reordena su posición entre hermanas

parentIdstringrequired

ID de la nueva colección padre. Acepta `null` explícito para mover la colección a nivel raíz.

sortOrdernumberrequired

Nueva posición entre las colecciones hermanas.

{ "parentId": null, "sortOrder": 2 }
404
{ "code": "not-found", "message": "Collection not found" }
400
{ "code": "bad-request", "message": "Request body is required" }

Permiso requerido: collections:update

Productos dentro de una colección

Agrega productos a una colección

idstringrequired

ID de la colección.

skusarrayrequired

Arreglo de SKUs a agregar.

{ "skus": ["CAM-ROJO-M", "PAN-AZUL-32"] }
200
{ "success": true }
400
{ "code": "bad-request", "message": "skus array is required" }

Permiso requerido: collections:update

Reordena manualmente los productos dentro de una colección

idstringrequired

ID de la colección.

skuOrderarrayrequired

Arreglo de SKUs en el orden deseado.

{ "skuOrder": ["PAN-AZUL-32", "CAM-ROJO-M"] }
200
{ "success": true }
400
{ "code": "bad-request", "message": "skuOrder array is required" }

Permiso requerido: collections:update

Quita productos de una colección

idstringrequired

ID de la colección.

skusarrayrequired

Arreglo de SKUs a quitar.

200
{ "success": true }
400
{ "code": "bad-request", "message": "skus array is required" }

Permiso requerido: collections:update

Eliminar una colección

Elimina una colección

idstringrequired

ID de la colección.

200
{ "success": true }
404
{ "code": "not-found", "message": "Collection not found" }
400
{ "code": "has-children", "message": "Cannot delete collection with children. Delete children first or move them." }

Permiso requerido: collections:delete

No se puede borrar una colección con hijas

Si la colección tiene colecciones hijas (parentId apuntando a ella), el borrado se rechaza con 400 has-children. Mueve o elimina primero las colecciones hijas.

Ejemplo — agregar productos a una colección

curl -X POST https://api.fenicia.io/collections/65f5a1b2c4d5e6f7a8b9c1a1/products \
  -H "Authorization: Bearer fkapi_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "skus": ["CAM-ROJO-M", "PAN-AZUL-32"] }'

Errores

CódigoStatusDescripción
bad-request400Body faltante, name.value faltante al crear, o skus/skuOrder no es un arreglo.
not-found404No existe una colección con ese ID en tu tenant.
has-children400No se puede eliminar una colección que tiene colecciones hijas.
permission-denied403La API key no tiene el permiso requerido. La respuesta incluye requiredPermission con el permiso exacto que faltó.
method-not-allowed405El método HTTP no está soportado para esa ruta.
internal-error500Error no controlado del servidor.
auth:invalid_token401La API key es inválida o fue revocada, o no se pudo resolver el tenant.

Consulta el catálogo completo de errores para el resto de los códigos posibles.

Permisos independientes de productos

collections:* es un grupo de permisos propio (read, create, update, delete), separado de products:*. Un rol con acceso de lectura a productos no necesariamente puede leer colecciones — revisa ambos si tu integración toca los dos dominios.

Siguientes pasos