API · products

Catálogo de productos del negocio (F3-145).

GET /products

Buscar productos del negocio

Scope products:read. Tenant desde credencial. Importes en unidad menor ({PYG:0, CLP:0, resto:2}); no price_cents de servicios. Owner/manager gestionan; staff lee activos ofrecidos por service_id. Archivar = PATCH active=false; no hay DELETE. Importación y exportación CSV: /products/import/* y /products/export.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:read

Parâmetros

Respostas

POST /products

Crear producto del negocio

Scope products:write. Tenant desde credencial. Importes en unidad menor ({PYG:0, CLP:0, resto:2}); no price_cents de servicios. Owner/manager gestionan; staff lee activos ofrecidos por service_id. Archivar = PATCH active=false; no hay DELETE. Importación y exportación CSV: /products/import/* y /products/export.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write

Corpo da solicitação (obrigatório)

• application/json: ProductIn

Respostas

GET /products/{id}

Ver producto del negocio

Scope products:read. Tenant desde credencial. Importes en unidad menor ({PYG:0, CLP:0, resto:2}); no price_cents de servicios. Owner/manager gestionan; staff lee activos ofrecidos por service_id. Pausar = PATCH active=false; eliminar = DELETE (borra sin historial, archiva con historial; FIU-485). Importación y exportación CSV: /products/import/* y /products/export.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:read

Parâmetros

Respostas

PATCH /products/{id}

Editar o archivar producto del negocio

Scope products:write. Tenant desde credencial. Importes en unidad menor ({PYG:0, CLP:0, resto:2}); no price_cents de servicios. Owner/manager gestionan; staff lee activos ofrecidos por service_id. Pausar = PATCH active=false; eliminar = DELETE (borra sin historial, archiva con historial; FIU-485). Importación y exportación CSV: /products/import/* y /products/export.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write

Parâmetros

Corpo da solicitação (obrigatório)

• application/json: ProductPatch

Respostas

DELETE /products/{id}

Eliminar producto (borra sin historial, archiva con historial)

mode=remove (por defecto) borra si ninguna tarea ni regla lo usa y archiva si hay historial; archive archiva siempre; delete borra o responde 409 catalog_item_has_history.

• Autenticação: Chave de API ou sessão do painel
• Escopos: Nenhum

Parâmetros

Respostas

GET /products/{id}/removal

Qué pasa al eliminar el producto (borra o archiva; tareas futuras)

• Autenticação: Chave de API ou sessão do painel
• Escopos: Nenhum

Parâmetros

Respostas

POST /products/{id}/restore

Restaurar el producto archivado (vuelve pausado; se reactiva a propósito)

• Autenticação: Chave de API ou sessão do painel
• Escopos: Nenhum

Parâmetros

Respostas

GET /products/categories

Categorías del catálogo

Gestión del catálogo (permiso products:manage_read, owner/manager). Con API key exige el scope products:write; una key de solo products:read recibe 403. Tenant desde credencial.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write, products:read

Respostas

GET /products/export

Exportación o plantilla CSV

Gestión del catálogo (permiso products:manage_read, owner/manager). Con API key exige el scope products:write. Devuelve el CSV (name,short_name,unit,price,category,synonyms,sku,active,featured,sort_order) con price en unidad mayor, punto decimal y sin miles; las celdas que empiezan con = + - @, tab o salto van con apóstrofo contra inyección de fórmulas. template=true devuelve solo el encabezado.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write

Parâmetros

Respostas

POST /products/import/{id}/confirm

Confirmar la importación de una vista previa

Scope products:write. Confirmar el mismo id es idempotente (devuelve el mismo resultado, que se conserva 7 días; luego 404). 409 products.preview_stale si cambió el catálogo, la moneda o la vista previa caducó; 404 si es de otro negocio. Todo o nada, bajo un solo bloqueo del catálogo.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write

Parâmetros

Respostas

POST /products/import/{id}/undo

Deshacer una importación confirmada

Scope products:write. Borra los productos que creó la importación (o los archiva si ya tienen historial) y devuelve los actualizados a su valor anterior. Solo mientras el catálogo no cambió desde la confirmación: si no, 409 products.import_undo_stale. Repetirlo devuelve el mismo resultado; 404 si la importación no existe, no se confirmó, venció (7 días) o es de otro negocio.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write

Parâmetros

Respostas

POST /products/import/preview

Validar un CSV (vista previa, no importa nada)

Scope products:write. FIU-525: exactamente uno de csv, xlsx (Excel en base64, hasta 1 MiB; primera hoja o sheet) o rows (hasta 2000 objetos que leyó una IA de un Excel, PDF o foto); con xlsx o rows, columns mapea encabezado → columna (name, unit, price, …) y la respuesta devuelve columns e ignored_columns. CSV UTF-8 de hasta 1 MiB y 2000 filas (, o ;, BOM aceptado); un texto con U+FFFD (Windows-1252 leído como UTF-8) se rechaza con 422 products.csv_encoding. El precio sigue la regla única de montos (docs/api/productos.md): «15.000» en PYG/CLP = 15000, «1,500» en BRL/COP se rechaza como ambiguo. Celdas en blanco en active, featured, sort_order y sku, y columnas omitidas, no cambian nada. Nada se importa hasta confirmar; la vista previa válida dura 30 minutos y queda ligada al negocio, la moneda y los valores del catálogo.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write

Corpo da solicitação (obrigatório)

• application/json: ProductCsvInput

Respostas

GET /products/stats

Ventas por producto en el período (unidades, tareas y facturación)

F3-315. Ventas por producto del período para la lista del catálogo, en una sola consulta agrupada (nunca una llamada por fila). Permiso products:manage_read (owner/manager); con API key, scope bookings:read (las ventas salen de las tareas). Cuenta las líneas del pedido (qty entregado, nunca lo pedido) de tareas completadas, sin pruebas, atribuidas al día local de inicio/vencimiento, igual que GET /v1/services/stats. revenue_minor = unidades por precio copiado en la línea (unidad menor) y currency solo con permiso finance:analyze (rol de la matriz o scope de la key); si no, null. Solo devuelve productos con ventas; ids (hasta 100) limita a los de la página visible. Máximo 366 días. Tenant desde la credencial, RLS.

• Autenticação: Chave de API ou sessão do painel
• Escopos: bookings:read

Parâmetros

Respostas

GET /products/store-search

Ver la búsqueda en la tienda externa

404 store_search_not_configured si el proyecto no tiene una. F4-55. Scope products:write (owner y manager por sesión; escrituras con CSRF). Una fuente por proyecto: URL HTTPS plantilla con {q} (obligatorio) y {limit} solo como valores completos del query; host y ruta fijos. Encabezados con credenciales cifrados y de escritura únicamente (se devuelven solo sus nombres); secretos en el query (?token=, ?api_key=…) se rechazan. Mapeo declarativo de F2-48 (items_path, rutas a.b[0].c) con nombre y precio obligatorios y moneda, URL, imagen, stock e id opcionales. service_id es el servicio de pedidos por chat con carrito al que entran los productos.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write

Respostas

PUT /products/store-search

Crear o editar la búsqueda en la tienda externa

Crea la fuente (sin expected_version) o la edita (con la versión vigente; 409 store_search_version_conflict si cambió). Al editar, los encabezados guardados se conservan salvo replace_headers: true; cambiar el host de la URL con credenciales guardadas exige reemplazarlas (422 credentials_origin_changed). Valida forma, HTTPS y DNS público de la URL (422 store_search_invalid con reason unsafe_url) y que el servicio exista, esté activo, acepte pedidos por chat y tenga carrito (service_not_orderable). Auditado sin URL completa ni credenciales. F4-55. Scope products:write (owner y manager por sesión; escrituras con CSRF). Una fuente por proyecto: URL HTTPS plantilla con {q} (obligatorio) y {limit} solo como valores completos del query; host y ruta fijos. Encabezados con credenciales cifrados y de escritura únicamente (se devuelven solo sus nombres); secretos en el query (?token=, ?api_key=…) se rechazan. Mapeo declarativo de F2-48 (items_path, rutas a.b[0].c) con nombre y precio obligatorios y moneda, URL, imagen, stock e id opcionales. service_id es el servicio de pedidos por chat con carrito al que entran los productos.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write

Corpo da solicitação (obrigatório)

• application/json: StoreSearchIn

Respostas

DELETE /products/store-search

Desactivar la búsqueda en la tienda externa

La desactiva (conserva la configuración y sube la versión): el bot deja de ofrecerla y los productos de la tienda que estaban en carritos abiertos ya no se pueden sumar. F4-55. Scope products:write (owner y manager por sesión; escrituras con CSRF). Una fuente por proyecto: URL HTTPS plantilla con {q} (obligatorio) y {limit} solo como valores completos del query; host y ruta fijos. Encabezados con credenciales cifrados y de escritura únicamente (se devuelven solo sus nombres); secretos en el query (?token=, ?api_key=…) se rechazan. Mapeo declarativo de F2-48 (items_path, rutas a.b[0].c) con nombre y precio obligatorios y moneda, URL, imagen, stock e id opcionales. service_id es el servicio de pedidos por chat con carrito al que entran los productos.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write

Respostas

GET /products/store-search/presets

Plantillas listas de búsqueda en tienda

Plantillas para Tiendanube/Nuvemshop, WooCommerce, Shopify, Make, n8n y una URL propia: URL de ejemplo (reemplazar el dominio o el id de la tienda), nombres de los encabezados de credenciales, mapeo y escala del precio. No consulta ninguna tienda. F4-55. Scope products:write (owner y manager por sesión; escrituras con CSRF). Una fuente por proyecto: URL HTTPS plantilla con {q} (obligatorio) y {limit} solo como valores completos del query; host y ruta fijos. Encabezados con credenciales cifrados y de escritura únicamente (se devuelven solo sus nombres); secretos en el query (?token=, ?api_key=…) se rechazan. Mapeo declarativo de F2-48 (items_path, rutas a.b[0].c) con nombre y precio obligatorios y moneda, URL, imagen, stock e id opcionales. service_id es el servicio de pedidos por chat con carrito al que entran los productos.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write

Respostas

POST /products/store-search/test

Probar la búsqueda en la tienda externa

«Probar búsqueda»: hace la misma consulta que el bot con la configuración guardada (aunque esté desactivada) y devuelve los resultados mapeados, con el precio ya en la unidad menor de la moneda del negocio, y los descartados por motivo (invalid_price, currency_mismatch, missing_name, duplicate). No guarda instantáneas. Traída segura: solo HTTPS a IPs públicas validadas en cada salto y fijadas al socket, 3 s en total, 512 KiB descomprimidos, caché por consulta y circuito tras fallos. Una tienda lenta, caída o con respuesta inválida o enorme responde 200 con ok: false y un status corto, nunca el cuerpo ni el error crudo. 10 pruebas por minuto por proyecto (429 store_search_rate_limited). F4-55. Scope products:write (owner y manager por sesión; escrituras con CSRF). Una fuente por proyecto: URL HTTPS plantilla con {q} (obligatorio) y {limit} solo como valores completos del query; host y ruta fijos. Encabezados con credenciales cifrados y de escritura únicamente (se devuelven solo sus nombres); secretos en el query (?token=, ?api_key=…) se rechazan. Mapeo declarativo de F2-48 (items_path, rutas a.b[0].c) con nombre y precio obligatorios y moneda, URL, imagen, stock e id opcionales. service_id es el servicio de pedidos por chat con carrito al que entran los productos.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write

Corpo da solicitação (obrigatório)

• application/json: StoreSearchTest

Respostas

GET /products/suggestions

Sugerencias de formularios existentes

Gestión del catálogo (permiso products:manage_read, owner/manager). Con API key exige el scope products:write; una key de solo products:read recibe 403. Tenant desde credencial.

• Autenticação: Chave de API ou sessão do painel
• Escopos: products:write, products:read

Respostas