{ "openapi": "3.1.0", "info": { "title": "API de Chainlink", "version": "1.0.0", "x-release-date": "2026-10-06", "summary": "API REST del WMS Chainlink para integrar ERP, tiendas en línea y sistemas propios.", "description": "API REST para leer y escribir catálogo, existencias, documentos de entrada y salida, órdenes de\ntransferencia, olas y webhooks de una instancia de Chainlink.\n\nCada empresa tiene su propia instancia y su propia API: `https://{instancia}.chainlink.mx/api/v1`.\nLos datos de una instancia no se comparten con otra.\n", "contact": { "name": "Soporte de Chainlink", "url": "https://chainlink.mx/contacto-ventas" }, "license": { "name": "Uso sujeto al contrato de servicio de Chainlink", "url": "https://chainlink.mx/legal/terminos" } }, "servers": [ { "url": "https://{instancia}.chainlink.mx/api/v1", "description": "Instancia de la empresa", "variables": { "instancia": { "default": "empresa", "description": "Subdominio de la empresa en Chainlink. Con dominio propio, se usa ese dominio." } } } ], "security": [ { "clientCredentials": [] }, { "userToken": [] } ], "tags": [ { "name": "productos", "x-displayName": "Productos", "description": "Catálogo de productos y sus categorías. El código (`item_code`) identifica al producto en documentos y existencias." }, { "name": "existencias", "x-displayName": "Existencias", "description": "Existencias por ubicación, lote y serie, y niveles por producto (a la mano y disponible)." }, { "name": "almacenes", "x-displayName": "Almacenes y ubicaciones", "description": "Almacenes, sus ubicaciones y el mapa publicado." }, { "name": "documentos", "x-displayName": "Documentos de entrada y salida", "description": "Lo que el ERP manda a recibir (órdenes de compra, entradas) o a surtir (pedidos, remisiones). Cada documento\nlleva la referencia externa del sistema de origen (`external_ref`): mandar dos veces la misma referencia no crea un duplicado.\n" }, { "name": "operacion", "x-displayName": "Recepciones, surtidos y traspasos", "description": "El trabajo que el almacén hizo sobre los documentos, con su operador, sus tiempos y sus líneas." }, { "name": "ordenes-de-transferencia", "x-displayName": "Órdenes de transferencia", "description": "Traslados de mercancía entre almacenes, de la creación a la recepción en destino." }, { "name": "olas", "x-displayName": "Olas", "description": "Grupos de pedidos que se surten juntos. Requiere el módulo de olas." }, { "name": "carga-masiva", "x-displayName": "Carga masiva", "description": "Archivos de Excel o CSV con productos o documentos, validados antes de aplicarse." }, { "name": "socios", "x-displayName": "Clientes y proveedores", "description": "Los socios de negocio de las salidas (clientes) y de las entradas (proveedores)." }, { "name": "webhooks", "x-displayName": "Suscripciones a webhooks", "description": "Avisos HTTP firmados cuando algo cambia en el almacén. Requiere el plan Professional o Enterprise." } ], "x-tagGroups": [ { "name": "Catálogo e inventario", "tags": [ "productos", "existencias", "almacenes" ] }, { "name": "Documentos y operación", "tags": [ "documentos", "operacion", "ordenes-de-transferencia", "olas", "carga-masiva" ] }, { "name": "Socios de negocio", "tags": [ "socios" ] }, { "name": "Webhooks", "tags": [ "webhooks" ] } ], "x-chainlink-errors": [ { "code": "bad_request", "status": 400, "title": "Solicitud no válida", "description": "La solicitud no se pudo interpretar (por ejemplo, JSON mal formado).", "action": "Revise el cuerpo y las cabeceras de la solicitud." }, { "code": "idempotency_key_required", "status": 400, "title": "Falta Idempotency-Key", "description": "La ruta exige la cabecera `Idempotency-Key` (documentos de entrada y salida).", "action": "Envíe un UUID v4 por cada operación de negocio y repítalo en los reintentos." }, { "code": "unauthenticated", "status": 401, "title": "Sin autenticación", "description": "Falta el token, venció, se revocó o el cliente de integración está revocado.", "action": "Solicite un token nuevo en `/oauth/token` y envíelo como `Authorization: Bearer `." }, { "code": "feature_not_in_plan", "status": 402, "title": "Función fuera del plan", "description": "El plan de la empresa no incluye la función (por ejemplo, `api.public.enabled` o `webhooks.enabled`). `error.feature` dice cuál.", "action": "Cambie de plan desde el portal de cuenta (`error.upgrade_url`) o contacte a ventas." }, { "code": "limit_reached", "status": 402, "title": "Límite del plan alcanzado", "description": "Se alcanzó un límite facturable del plan, como el número de clientes de integración.", "action": "Libere capacidad o amplíe el plan; `error.offer` describe la opción disponible." }, { "code": "tenant_suspended", "status": 402, "title": "Cuenta suspendida", "description": "La cuenta de la empresa está suspendida por facturación.", "action": "Regulariza el pago en el portal de cuenta; la API responde de nuevo al reactivarse." }, { "code": "tenant_cancelled", "status": 402, "title": "Cuenta cancelada", "description": "La cuenta de la empresa está cancelada.", "action": "Contacta a ventas para reactivarla." }, { "code": "forbidden", "status": 403, "title": "Sin permiso", "description": "El usuario dueño del token no tiene el permiso que pide la ruta (por ejemplo, `inventory.manage`).", "action": "Asigne al usuario un rol con ese permiso o use un cliente de integración con el alcance correcto." }, { "code": "missing_scope", "status": 403, "title": "Falta un alcance", "description": "El token del cliente de integración no incluye el alcance que pide la ruta. `error.scope` dice cuál.", "action": "Solicite un token nuevo que incluya ese alcance en el parámetro `scope`." }, { "code": "client_not_allowed", "status": 403, "title": "Token sin acceso a la API pública", "description": "El token es de la aplicación móvil (cliente «Chainlink Mobile») o de un usuario con verificación en dos pasos, emitido con el grant `password`, que no pide el segundo factor. Solo llega a la búsqueda del catálogo (`GET /products`).", "action": "Use un cliente de integración con el grant `client_credentials` (Configuración › Clientes API)." }, { "code": "not_found", "status": 404, "title": "No existe", "description": "El recurso o la ruta no existe en esta instancia.", "action": "Revise el identificador y la URL base de la instancia." }, { "code": "transfer_orders_disabled", "status": 404, "title": "Módulo de transferencias apagado", "description": "La empresa no tiene activas las órdenes de transferencia.", "action": "Actívalas en Configuración › Operación (requiere al menos dos almacenes)." }, { "code": "bulk_import_disabled", "status": 404, "title": "Carga masiva apagada", "description": "La empresa no tiene activa la carga masiva.", "action": "Actívala en Configuración › Operación." }, { "code": "method_not_allowed", "status": 405, "title": "Método no permitido", "description": "La ruta existe pero no admite ese método HTTP.", "action": "Consulte en la referencia los métodos de la ruta." }, { "code": "conflict", "status": 409, "title": "Conflicto", "description": "La solicitud choca con el estado actual del recurso.", "action": "Vuelva a leer el recurso y decida si reintentar." }, { "code": "duplicate_in_flight", "status": 409, "title": "Solicitud en proceso", "description": "Llegó otra solicitud con la misma `Idempotency-Key` mientras la primera sigue en proceso.", "action": "Reintente tras unos segundos con la misma llave; la respuesta será la de la primera solicitud." }, { "code": "approval_required", "status": 409, "title": "Requiere aprobación", "description": "Una regla de negocio pide la aprobación de un supervisor antes de continuar.", "action": "Un supervisor aprueba en la web; después, repita la operación." }, { "code": "order_in_wave", "status": 409, "title": "Pedido ya en otra ola", "description": "Uno de los surtidos ya pertenece a otra ola activa.", "action": "Quita ese surtido de la lista o cancela la otra ola." }, { "code": "stale_state", "status": 409, "title": "Estado desactualizado", "description": "El recurso cambió de estado antes de aplicar la operación (por ejemplo, la transferencia ya se liberó).", "action": "Vuelva a leer el recurso y decida con su estado actual." }, { "code": "import_refused", "status": 422, "title": "Carga rechazada", "description": "El archivo no se puede procesar (formato, tamaño) o la carga ya no se puede confirmar. Puede llegar con 409, 413 o 422.", "action": "Corrija lo que indica el mensaje y vuelva a subir el archivo." }, { "code": "tenant_moved", "status": 410, "title": "Instancia trasladada", "description": "La empresa opera ahora en su propio servidor.", "action": "Use la URL de la instalación propia de la empresa." }, { "code": "gone", "status": 410, "title": "Ya no disponible", "description": "El recurso existió pero ya no está disponible.", "action": "Deje de usar ese recurso; consulte el registro de cambios si fue retirado." }, { "code": "payload_too_large", "status": 413, "title": "Solicitud demasiado grande", "description": "El cuerpo o el archivo excede el tamaño permitido (5 MB en carga masiva).", "action": "Divide la carga en partes más pequeñas." }, { "code": "validation_failed", "status": 422, "title": "Datos no válidos", "description": "Uno o más campos no pasan la validación. `errors[]` lista cada campo con su mensaje y `error.field` señala el primero.", "action": "Corrija los campos indicados y reenvíe la solicitud." }, { "code": "idempotency_key_reused", "status": 422, "title": "Llave de idempotencia reutilizada", "description": "La `Idempotency-Key` ya se usó con otra ruta, otro método u otro cuerpo.", "action": "Genera una llave nueva para cada operación distinta." }, { "code": "rule_blocked", "status": 422, "title": "Bloqueado por una regla", "description": "Una regla de negocio de la empresa bloquea la operación. `error.rule` identifica la regla.", "action": "Revise la regla en Configuración › Reglas de negocio." }, { "code": "transfer_refused", "status": 422, "title": "Transferencia rechazada", "description": "La orden de transferencia no es válida (producto inexistente, cantidad, almacenes).", "action": "Corrija lo que indica el mensaje." }, { "code": "transfer_requires_two_warehouses", "status": 422, "title": "Se necesitan dos almacenes", "description": "Las transferencias entre almacenes requieren al menos dos almacenes activos.", "action": "Da de alta el segundo almacén." }, { "code": "no_candidates", "status": 422, "title": "Sin pedidos para la ola", "description": "Los filtros no encontraron surtidos pendientes para planear la ola.", "action": "Amplíe los filtros o envíe `picking_ids`." }, { "code": "wave_refused", "status": 422, "title": "Ola rechazada", "description": "La ola no se puede planear con esos datos.", "action": "Corrija lo que indica el mensaje." }, { "code": "installation_restricted", "status": 423, "title": "Instalación en modo restringido", "description": "La instalación propia de la empresa está en modo de solo lectura por su licencia.", "action": "Renueva la licencia de la instalación." }, { "code": "locked", "status": 423, "title": "Bloqueado", "description": "El recurso está bloqueado por otra operación.", "action": "Reintente en unos segundos." }, { "code": "rate_limited", "status": 429, "title": "Límite de solicitudes", "description": "Se superó el límite de solicitudes por minuto de la empresa (60 en Essentials, 300 en Professional).", "action": "Espere los segundos que indica `Retry-After` y reintente. Distribuya las llamadas en el tiempo." }, { "code": "server_error", "status": 500, "title": "Error interno", "description": "Ocurrió un error inesperado en Chainlink. El equipo recibe el aviso.", "action": "Reintente con espera exponencial; si persiste, envíe `error.request_id` a soporte." }, { "code": "tenant_moving", "status": 503, "title": "Instancia en migración", "description": "La empresa se está trasladando de servidor.", "action": "Reintente en unos minutos." }, { "code": "service_unavailable", "status": 503, "title": "Servicio no disponible", "description": "El servicio no está disponible por el momento.", "action": "Reintente con espera exponencial." } ], "x-header-sets": { "success": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "created": { "Location": { "$ref": "#/components/headers/Location" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "write": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "paths": { "/products": { "get": { "operationId": "listProducts", "tags": [ "productos" ], "summary": "Listar productos", "description": "Devuelve el catálogo paginado. `search` busca por parte del código, del nombre o del código de barras.\nPara sincronizar solo lo que cambió, envíe en `updated_since` la fecha de la última lectura.\n", "security": [ { "clientCredentials": [ "products:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "name", "-name", "item_code", "-item_code", "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "name" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "search", "in": "query", "description": "Texto a buscar en código, nombre o código de barras. `q` es un alias.", "schema": { "type": "string", "maxLength": 100 }, "example": "aceite" }, { "name": "item_code", "in": "query", "description": "Código exacto del producto.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "barcode", "in": "query", "description": "Código de barras exacto.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "type", "in": "query", "description": "Tipo de producto.", "schema": { "type": "string", "maxLength": 50 } } ], "responses": { "200": { "description": "Página de productos.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" }, "example": { "data": [ { "id": 101, "item_code": "P-1001", "sku": "P-1001", "name": "Aceite comestible 1 L", "barcode": "7501234567890", "type": "I", "image_url": null, "man_btch_num": true, "man_ser_num": false, "sales_unit": "PZA", "purchase_unit": "CJA", "inventory_item": true, "created_at": "2026-09-14T15:02:11.000000Z", "updated_at": "2026-10-05T18:40:03.000000Z" } ], "links": { "first": "https://demo.chainlink.mx/api/v1/products?page=1", "last": "https://demo.chainlink.mx/api/v1/products?page=4", "prev": null, "next": "https://demo.chainlink.mx/api/v1/products?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 4, "links": [], "path": "https://demo.chainlink.mx/api/v1/products", "per_page": 25, "to": 25, "total": 87 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createProduct", "tags": [ "productos" ], "summary": "Crear un producto", "description": "Da de alta un producto. El código (`item_code`, o `sku`) debe ser único en la instancia.", "security": [ { "clientCredentials": [ "products:write" ] }, { "userToken": [] } ], "x-permission": "inventory.manage", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" }, "example": { "item_code": "P-1004", "name": "Frijol negro 900 g", "barcode": "7501234567904", "man_btch_num": true, "sales_unit": "PZA" } } } }, "responses": { "201": { "description": "Producto creado. `Location` apunta al nuevo recurso.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductItem" }, "example": { "data": { "id": 104, "item_code": "P-1004", "sku": "P-1004", "name": "Frijol negro 900 g", "barcode": "7501234567904", "type": null, "image_url": null, "man_btch_num": true, "man_ser_num": false, "sales_unit": "PZA", "purchase_unit": null, "inventory_item": false, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/products/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getProduct", "tags": [ "productos" ], "summary": "Consultar un producto", "security": [ { "clientCredentials": [ "products:read" ] }, { "userToken": [] } ], "responses": { "200": { "description": "El producto.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductItem" }, "example": { "data": { "id": 101, "item_code": "P-1001", "sku": "P-1001", "name": "Aceite comestible 1 L", "barcode": "7501234567890", "type": "I", "image_url": null, "man_btch_num": true, "man_ser_num": false, "sales_unit": "PZA", "purchase_unit": "CJA", "inventory_item": true, "created_at": "2026-09-14T15:02:11.000000Z", "updated_at": "2026-10-05T18:40:03.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "updateProduct", "tags": [ "productos" ], "summary": "Actualizar un producto", "description": "Cambia solo los campos enviados.", "security": [ { "clientCredentials": [ "products:write" ] }, { "userToken": [] } ], "x-permission": "inventory.manage", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdate" }, "example": { "name": "Aceite comestible 1 L (caja 12)", "barcode": "7501234567891" } } } }, "responses": { "200": { "description": "El producto actualizado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductItem" }, "example": { "data": { "id": 101, "item_code": "P-1001", "sku": "P-1001", "name": "Aceite comestible 1 L (caja 12)", "barcode": "7501234567891", "type": "I", "image_url": null, "man_btch_num": true, "man_ser_num": false, "sales_unit": "PZA", "purchase_unit": "CJA", "inventory_item": true, "created_at": "2026-09-14T15:02:11.000000Z", "updated_at": "2026-10-06T16:31:40.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "operationId": "replaceProduct", "tags": [ "productos" ], "summary": "Actualizar un producto (PUT)", "description": "Igual que `PATCH`; se conserva por compatibilidad. Cambia solo los campos enviados.", "security": [ { "clientCredentials": [ "products:write" ] }, { "userToken": [] } ], "x-permission": "inventory.manage", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdate" }, "example": { "name": "Aceite comestible 1 L" } } } }, "responses": { "200": { "description": "El producto actualizado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductItem" }, "example": { "data": { "id": 1, "item_code": "P-1001", "sku": "P-1001", "name": "Aceite comestible 1 L", "barcode": "7501234567890", "type": null, "image_url": null, "man_btch_num": true, "man_ser_num": false, "sales_unit": null, "purchase_unit": null, "inventory_item": true, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteProduct", "tags": [ "productos" ], "summary": "Eliminar un producto", "description": "Da de baja el producto. Su historial (recepciones, surtidos, existencias) se conserva.", "security": [ { "clientCredentials": [ "products:write" ] }, { "userToken": [] } ], "x-permission": "inventory.manage", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Eliminado; sin cuerpo.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/product-categories": { "get": { "operationId": "listProductCategories", "tags": [ "productos" ], "summary": "Listar categorías", "security": [ { "clientCredentials": [ "products:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "name", "-name", "updated_at", "-updated_at" ], "default": "name" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/Search" } ], "responses": { "200": { "description": "Página de categorías.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCategoryList" }, "example": { "data": [ { "id": 3, "name": "Abarrotes", "description": "Básicos de despensa", "created_at": "2026-09-14T15:00:00.000000Z", "updated_at": "2026-09-14T15:00:00.000000Z" } ], "links": { "first": "https://demo.chainlink.mx/api/v1/product-categories?page=1", "last": "https://demo.chainlink.mx/api/v1/product-categories?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://demo.chainlink.mx/api/v1/product-categories", "per_page": 25, "to": 1, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/product-categories/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getProductCategory", "tags": [ "productos" ], "summary": "Consultar una categoría", "security": [ { "clientCredentials": [ "products:read" ] }, { "userToken": [] } ], "responses": { "200": { "description": "La categoría.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProductCategory" } } }, "example": { "data": { "id": 3, "name": "Abarrotes", "description": "Autem totam labore non quibusdam quod qui.", "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/stocks": { "get": { "operationId": "listStocks", "tags": [ "existencias" ], "summary": "Listar existencias", "description": "Una fila por producto, ubicación, lote y serie. Filtra por producto (`product_id` o `item_code`), almacén\n(`warehouse_id` o `warehouse`), ubicación, lote, serie y estado. Para totales por producto se usa\n[niveles de existencia](#operation/listStockLevels).\n", "security": [ { "clientCredentials": [ "stocks:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "id", "-id", "qty", "-qty", "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "id" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "product_id", "in": "query", "description": "Id del producto.", "schema": { "type": "integer" } }, { "name": "item_code", "in": "query", "description": "Código del producto.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "warehouse_id", "in": "query", "description": "Id del almacén.", "schema": { "type": "integer" } }, { "name": "warehouse", "in": "query", "description": "Código del almacén (`whs_code`).", "schema": { "type": "string", "maxLength": 20 }, "example": "CEDIS-GDL" }, { "name": "bin_code", "in": "query", "description": "Código de la ubicación.", "schema": { "type": "string", "maxLength": 50 } }, { "name": "batch", "in": "query", "description": "Lote.", "schema": { "type": "string", "maxLength": 50 } }, { "name": "serial", "in": "query", "description": "Número de serie.", "schema": { "type": "string", "maxLength": 191 } }, { "name": "status", "in": "query", "description": "Estado de la fila: `in` (en almacén) u `out` (salió).", "schema": { "type": "string", "maxLength": 20 } } ], "responses": { "200": { "description": "Página de existencias.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockList" }, "example": { "data": [ { "id": 5012, "product_id": 101, "product_name": "Aceite comestible 1 L", "item_code": "P-1001", "qty": 48, "status": "in", "serial_number": null, "batch_num": "L2609", "position": { "id": 210, "bin_code": "A-01-01-1", "whs_code": "CEDIS-GDL", "warehouse_id": 1, "warehouse_name": "CEDIS Guadalajara" }, "expiry_date": "2027-03-31", "inventory_status": "available", "created_at": "2026-09-20T14:10:00.000000Z", "updated_at": "2026-10-06T15:58:21.000000Z" } ], "links": { "first": "https://demo.chainlink.mx/api/v1/stocks?page=1", "last": "https://demo.chainlink.mx/api/v1/stocks?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://demo.chainlink.mx/api/v1/stocks", "per_page": 25, "to": 1, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/stocks/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getStock", "tags": [ "existencias" ], "summary": "Consultar una fila de existencia", "security": [ { "clientCredentials": [ "stocks:read" ] }, { "userToken": [] } ], "responses": { "200": { "description": "La fila de existencia.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Stock" } } }, "example": { "data": { "id": 1, "product_id": 1, "product_name": "Aceite comestible 1 L", "item_code": "P-1001", "qty": 48, "status": "in", "serial_number": null, "batch_num": "L2610", "position": { "id": 1, "bin_code": "A-01-01-1", "whs_code": "CEDIS-GDL", "warehouse_id": 1, "warehouse_name": "CEDIS Guadalajara" }, "expiry_date": "2027-04-04", "inventory_status": "available", "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/stock-levels": { "get": { "operationId": "listStockLevels", "tags": [ "existencias" ], "summary": "Niveles de existencia por producto", "description": "Para cada producto, lo que hay **a la mano** (`on_hand`: todo lo que está en almacén) y lo **disponible**\n(`available`: en estado disponible, sin retenciones y descontando lo que reservan los pedidos abiertos). Son\nlas mismas cifras del evento `stock.updated`. Con `warehouse`, solo las de ese almacén.\n\n`updated_since` aquí significa «productos cuyas existencias se movieron desde esa fecha».\n", "security": [ { "clientCredentials": [ "stocks:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "item_code", "-item_code", "name", "-name" ], "default": "item_code" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "item_code", "in": "query", "description": "Uno o varios códigos separados por comas (hasta 100).", "schema": { "type": "string", "maxLength": 2000 }, "example": "P-1001,P-1002" }, { "name": "product_id", "in": "query", "description": "Id del producto.", "schema": { "type": "integer" } }, { "name": "warehouse", "in": "query", "description": "Código del almacén; sin él, el total de la empresa.", "schema": { "type": "string", "maxLength": 20 }, "example": "CEDIS-GDL" } ], "responses": { "200": { "description": "Página de niveles por producto.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockLevelList" }, "example": { "data": [ { "product_id": 101, "item_code": "P-1001", "name": "Aceite comestible 1 L", "warehouse": "CEDIS-GDL", "on_hand": 48, "available": 46 }, { "product_id": 102, "item_code": "P-1002", "name": "Arroz grano largo 1 kg", "warehouse": "CEDIS-GDL", "on_hand": 120, "available": 120 } ], "links": { "first": "https://demo.chainlink.mx/api/v1/stock-levels?warehouse=CEDIS-GDL&page=1", "last": "https://demo.chainlink.mx/api/v1/stock-levels?warehouse=CEDIS-GDL&page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://demo.chainlink.mx/api/v1/stock-levels", "per_page": 25, "to": 2, "total": 2 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/warehouses": { "get": { "operationId": "listWarehouses", "tags": [ "almacenes" ], "summary": "Listar almacenes", "security": [ { "clientCredentials": [ "warehouses:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "name", "-name", "whs_code", "-whs_code", "updated_at", "-updated_at" ], "default": "name" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "search", "in": "query", "description": "Parte del nombre o del código.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "whs_code", "in": "query", "description": "Código exacto del almacén.", "schema": { "type": "string", "maxLength": 20 } } ], "responses": { "200": { "description": "Página de almacenes, con el número de ubicaciones de cada uno.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseList" }, "example": { "data": [ { "id": 1, "whs_code": "CEDIS-GDL", "name": "CEDIS Guadalajara", "site_code": "GDL", "is_virtual": false, "timezone": "America/Mexico_City", "street": "Av. Vallarta 1200", "block": null, "city": "Guadalajara", "state": "Jalisco", "zip_code": "44100", "country": "MX", "positions_count": 412, "created_at": "2026-09-14T15:00:00.000000Z", "updated_at": "2026-09-30T12:00:00.000000Z" } ], "links": { "first": "https://demo.chainlink.mx/api/v1/warehouses?page=1", "last": "https://demo.chainlink.mx/api/v1/warehouses?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://demo.chainlink.mx/api/v1/warehouses", "per_page": 25, "to": 1, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/warehouses/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getWarehouse", "tags": [ "almacenes" ], "summary": "Consultar un almacén", "description": "El almacén con todas sus ubicaciones. Para almacenes grandes conviene paginar con `GET /warehouse-positions?warehouse_id=`.", "security": [ { "clientCredentials": [ "warehouses:read" ] }, { "userToken": [] } ], "responses": { "200": { "description": "El almacén con sus ubicaciones.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Warehouse" } } }, "example": { "data": { "id": 1, "whs_code": "CEDIS-GDL", "name": "CEDIS Guadalajara", "site_code": null, "is_virtual": false, "timezone": null, "street": null, "block": null, "city": null, "state": null, "zip_code": null, "country": null, "positions_count": 20, "positions": [ { "id": 1, "warehouse_id": 1, "whs_code": "CEDIS-GDL", "bin_code": "A-01-01-1", "description": null, "type": "pick_face", "zone_id": 1, "aisle": "01", "rack": "01", "level": "1", "slot": null, "pick_sequence": 1, "is_pickable": true, "is_blocked": false, "is_crossdock": false, "disabled": false, "capacity_units": null, "capacity_weight_kg": null, "capacity_volume_m3": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" }, { "id": 2, "warehouse_id": 1, "whs_code": "CEDIS-GDL", "bin_code": "A-01-01-2", "description": null, "type": "pick_face", "zone_id": 1, "aisle": "01", "rack": "01", "level": "2", "slot": null, "pick_sequence": 2, "is_pickable": true, "is_blocked": false, "is_crossdock": false, "disabled": false, "capacity_units": null, "capacity_weight_kg": null, "capacity_volume_m3": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } ], "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/warehouses/{id}/layout": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getWarehouseLayout", "tags": [ "almacenes" ], "summary": "Mapa publicado del almacén", "description": "El mapa vigente del almacén (pasillos, racks y ubicaciones con sus coordenadas). Responde `ETag` con la\nversión: con `If-None-Match` y ese valor, la respuesta es `304` sin cuerpo si no cambió. Requiere el módulo\nde mapas; un almacén sin mapa publicado responde `404`.\n", "security": [ { "clientCredentials": [ "warehouses:read" ] }, { "userToken": [] } ], "x-gates": [ "feature:modules.layout" ], "parameters": [ { "name": "If-None-Match", "in": "header", "description": "El `ETag` de la última lectura.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "El mapa publicado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WarehouseLayout" } } }, "example": { "data": { "warehouse_code": "CEDIS-MAPA", "version": 1, "published_at": "2026-10-06T10:20:11-06:00", "width_m": 30, "depth_m": 22, "grid_m": 0.5, "naming_mask": "{Z}-{A:2}-{B:2}-{L}", "slots_per_level": 1, "depot": { "x": 0, "y": 0 }, "zones": [ { "code": "A", "type": "storage", "polygon": [ [ 0, 0 ], [ 25, 0 ], [ 25, 17 ], [ 0, 17 ] ], "color": "#3B82F6", "temperature_class": null, "naming_mask": "{Z}-{A:2}-{B:2}-{L}" } ], "aisles": [ { "number": 1, "x1": 4, "y1": 0, "x2": 4, "y2": 14, "width_m": 3, "one_way": false, "kind": "standard", "zone": null }, { "number": 2, "x1": 8, "y1": 0, "x2": 8, "y2": 14, "width_m": 3, "one_way": false, "kind": "standard", "zone": null } ], "bays": [ { "side": "L", "number": 1, "x": 2, "y": 1.5, "w": 2.7, "d": 1, "rotation": 90, "rack_type": "selective", "aisle": 1, "aisle_zone": null, "levels": [ { "level_no": 1, "z_from_m": 0, "height_m": 1.5, "max_weight_kg": null, "golden": false }, { "level_no": 2, "z_from_m": 1.5, "height_m": 1.5, "max_weight_kg": null, "golden": true } ] }, { "side": "L", "number": 2, "x": 2, "y": 4.3, "w": 2.7, "d": 1, "rotation": 90, "rack_type": "selective", "aisle": 1, "aisle_zone": null, "levels": [ { "level_no": 1, "z_from_m": 0, "height_m": 1.5, "max_weight_kg": null, "golden": false }, { "level_no": 2, "z_from_m": 1.5, "height_m": 1.5, "max_weight_kg": null, "golden": true } ] } ], "points": [] } } } } }, "304": { "description": "El mapa no cambió desde el `ETag` enviado; sin cuerpo.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/warehouse-positions": { "get": { "operationId": "listWarehousePositions", "tags": [ "almacenes" ], "summary": "Listar ubicaciones", "security": [ { "clientCredentials": [ "warehouses:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "bin_code", "-bin_code", "pick_sequence", "-pick_sequence", "updated_at", "-updated_at" ], "default": "bin_code" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "warehouse_id", "in": "query", "description": "Id del almacén.", "schema": { "type": "integer" } }, { "name": "warehouse", "in": "query", "description": "Código del almacén.", "schema": { "type": "string", "maxLength": 20 } }, { "name": "bin_code", "in": "query", "description": "Código exacto de la ubicación.", "schema": { "type": "string", "maxLength": 50 } }, { "name": "search", "in": "query", "description": "Parte del código de la ubicación.", "schema": { "type": "string", "maxLength": 50 } } ], "responses": { "200": { "description": "Página de ubicaciones.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PositionList" }, "example": { "data": [ { "id": 210, "warehouse_id": 1, "whs_code": "CEDIS-GDL", "bin_code": "A-01-01-1", "description": null, "type": "pick_face", "zone_id": 1, "aisle": "01", "rack": "01", "level": "1", "slot": null, "pick_sequence": 1, "is_pickable": true, "is_blocked": false, "is_crossdock": false, "disabled": false, "capacity_units": null, "capacity_weight_kg": null, "capacity_volume_m3": null, "warehouse": { "id": 1, "whs_code": "CEDIS-GDL", "name": "CEDIS Guadalajara" }, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } ], "links": { "first": "https://demo.chainlink.mx/api/v1/warehouse-positions?page=1", "last": "https://demo.chainlink.mx/api/v1/warehouse-positions?page=17", "prev": null, "next": "https://demo.chainlink.mx/api/v1/warehouse-positions?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 17, "links": [], "path": "https://demo.chainlink.mx/api/v1/warehouse-positions", "per_page": 25, "to": 25, "total": 412 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/warehouse-positions/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getWarehousePosition", "tags": [ "almacenes" ], "summary": "Consultar una ubicación", "security": [ { "clientCredentials": [ "warehouses:read" ] }, { "userToken": [] } ], "responses": { "200": { "description": "La ubicación.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Position" } } }, "example": { "data": { "id": 1, "warehouse_id": 1, "whs_code": "CEDIS-GDL", "bin_code": "A-01-01-1", "description": null, "type": "pick_face", "zone_id": 1, "aisle": "01", "rack": "01", "level": "1", "slot": null, "pick_sequence": 1, "is_pickable": true, "is_blocked": false, "is_crossdock": false, "disabled": false, "capacity_units": null, "capacity_weight_kg": null, "capacity_volume_m3": null, "warehouse": { "id": 1, "whs_code": "CEDIS-GDL", "name": "CEDIS Guadalajara" }, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/entry-documents": { "get": { "operationId": "listEntryDocuments", "tags": [ "documentos" ], "summary": "Listar documentos de entrada", "description": "Los documentos de entrada con su avance por línea (`open_qty`, `received_qty`). Un documento se busca por la\nreferencia del sistema de origen con `external_ref`.\n", "security": [ { "clientCredentials": [ "receipts:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "doc_date", "-doc_date" ], "default": "-created_at" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "external_ref", "in": "query", "description": "Referencia externa del documento.", "schema": { "type": "string", "maxLength": 100 }, "example": "OC-2026-0042" }, { "name": "type", "in": "query", "description": "Tipo interno (`purchase_order`, `goods_receipt`, `delivery_good`).", "schema": { "type": "string", "maxLength": 40 } }, { "name": "card_code", "in": "query", "description": "Código del proveedor.", "schema": { "type": "string", "maxLength": 50 } }, { "name": "status", "in": "query", "description": "Estado del documento (`open`, `assigned`, `partial-complete`, `completed`, `closed`).", "schema": { "type": "string", "maxLength": 30 } }, { "name": "source", "in": "query", "description": "Origen (`api`, `import`, `web`, `sap`).", "schema": { "type": "string", "maxLength": 20 } } ], "responses": { "200": { "description": "Página de documentos de entrada.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryDocumentList" }, "example": { "data": [ { "id": 1, "doc_num": "OC-000001", "type": "purchase_order", "external_ref": "OC-2026-0042", "source": "api", "status": "open", "card_code": "PRV-001", "card_name": null, "doc_date": "2026-10-06", "due_date": "2026-10-06", "comments": null, "lines": [ { "line_num": 0, "item_code": "P-1001", "qty": 48, "open_qty": 48, "received_qty": 0, "whs_code": "CEDIS-GDL", "status": "open" }, { "line_num": 1, "item_code": "P-1002", "qty": 120, "open_qty": 120, "received_qty": 0, "whs_code": "CEDIS-GDL", "status": "open" } ], "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } ], "links": { "first": "https://empresa.chainlink.mx/api/v1/entry-documents?external_ref=OC-2026-0042&page=1", "last": "https://empresa.chainlink.mx/api/v1/entry-documents?external_ref=OC-2026-0042&page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://empresa.chainlink.mx/api/v1/entry-documents", "per_page": 25, "to": 1, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createEntryDocument", "tags": [ "documentos" ], "summary": "Crear un documento de entrada", "description": "Manda a recibir mercancía (orden de compra, entrada). Se valida con las mismas reglas que la plantilla de carga\nmasiva: productos, almacén, ubicación destino, lotes y series. La cabecera `Idempotency-Key` es obligatoria.\n\nSi ya existe un documento del mismo `type` con ese `external_ref`, responde `200` con ese documento en lugar de\ncrear otro; uno nuevo responde `201`.\n", "security": [ { "clientCredentials": [ "receipts:write" ] }, { "userToken": [] } ], "x-permission": "entries.manage", "x-idempotency": "required", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryDocumentInput" }, "example": { "external_ref": "OC-2026-0042", "type": "Orden de Compra", "doc_date": "2026-10-06", "due_date": "2026-10-09", "partner_code": "PRV-001", "partner_name": "Distribuidora del Bajío", "warehouse_code": "CEDIS-GDL", "lines": [ { "item_code": "P-1001", "qty": 48, "batch": "L2610", "expiry_date": "2027-04-30", "destination_bin": "A-01-01-1" }, { "item_code": "P-1002", "qty": 120 } ] } } } }, "responses": { "200": { "description": "Ya existía un documento con ese `type` y `external_ref`; se devuelve ese.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryDocumentItem" }, "example": { "data": { "id": 1, "doc_num": "OC-000001", "type": "purchase_order", "external_ref": "OC-2026-0042", "source": "api", "status": "open", "card_code": "PRV-001", "card_name": null, "doc_date": "2026-10-06", "due_date": "2026-10-06", "comments": null, "lines": [ { "line_num": 0, "item_code": "P-1001", "qty": 48, "open_qty": 48, "received_qty": 0, "whs_code": "CEDIS-GDL", "status": "open" }, { "line_num": 1, "item_code": "P-1002", "qty": 120, "open_qty": 120, "received_qty": 0, "whs_code": "CEDIS-GDL", "status": "open" } ], "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "201": { "description": "Documento creado. `Location` apunta al nuevo recurso.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryDocumentItem" }, "example": { "data": { "id": 318, "doc_num": "OC-000318", "type": "purchase_order", "external_ref": "OC-2026-0042", "source": "api", "status": "open", "card_code": "PRV-001", "card_name": "Distribuidora del Bajío", "doc_date": "2026-10-06", "due_date": "2026-10-09", "comments": null, "lines": [ { "line_num": 0, "item_code": "P-1001", "qty": 48, "open_qty": 48, "received_qty": 0, "whs_code": "CEDIS-GDL", "status": "open" }, { "line_num": 1, "item_code": "P-1002", "qty": 120, "open_qty": 120, "received_qty": 0, "whs_code": "CEDIS-GDL", "status": "open" } ], "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "400": { "$ref": "#/components/responses/IdempotencyKeyRequired" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/entry-documents/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getEntryDocument", "tags": [ "documentos" ], "summary": "Consultar un documento de entrada", "security": [ { "clientCredentials": [ "receipts:read" ] }, { "userToken": [] } ], "responses": { "200": { "description": "El documento con su avance por línea.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryDocumentItem" }, "example": { "data": { "id": 1, "doc_num": "OC-000001", "type": "purchase_order", "external_ref": "OC-2026-0042", "source": "api", "status": "open", "card_code": "PRV-001", "card_name": null, "doc_date": "2026-10-06", "due_date": "2026-10-06", "comments": null, "lines": [ { "line_num": 0, "item_code": "P-1001", "qty": 48, "open_qty": 48, "received_qty": 0, "whs_code": "CEDIS-GDL", "status": "open" }, { "line_num": 1, "item_code": "P-1002", "qty": 120, "open_qty": 120, "received_qty": 0, "whs_code": "CEDIS-GDL", "status": "open" } ], "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/exit-documents": { "get": { "operationId": "listExitDocuments", "tags": [ "documentos" ], "summary": "Listar documentos de salida", "description": "Los documentos de salida con su avance por línea (`open_qty`, `picked_qty`).", "security": [ { "clientCredentials": [ "pickings:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "doc_date", "-doc_date" ], "default": "-created_at" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "external_ref", "in": "query", "description": "Referencia externa del documento.", "schema": { "type": "string", "maxLength": 100 }, "example": "PED-88121" }, { "name": "type", "in": "query", "description": "Tipo interno (`sale_order`, `delivery_note`, `goods_issue`, `dispatch_good`).", "schema": { "type": "string", "maxLength": 40 } }, { "name": "card_code", "in": "query", "description": "Código del cliente.", "schema": { "type": "string", "maxLength": 50 } }, { "name": "status", "in": "query", "description": "Estado del documento.", "schema": { "type": "string", "maxLength": 30 } }, { "name": "source", "in": "query", "description": "Origen (`api`, `import`, `web`, `sap`).", "schema": { "type": "string", "maxLength": 20 } } ], "responses": { "200": { "description": "Página de documentos de salida.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExitDocumentList" }, "example": { "data": [ { "id": 1, "doc_num": "OV-000001", "type": "sale_order", "external_ref": "PED-88121", "source": "api", "status": "open", "card_code": "CLI-001", "card_name": null, "doc_date": "2026-10-06", "due_date": "2026-10-06", "comments": null, "priority": 50, "ship_to": null, "lines": [ { "line_num": 0, "item_code": "P-1001", "qty": 6, "open_qty": 6, "picked_qty": 0, "whs_code": "CEDIS-GDL", "status": "open" } ], "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } ], "links": { "first": "https://empresa.chainlink.mx/api/v1/exit-documents?external_ref=PED-88121&page=1", "last": "https://empresa.chainlink.mx/api/v1/exit-documents?external_ref=PED-88121&page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://empresa.chainlink.mx/api/v1/exit-documents", "per_page": 25, "to": 1, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createExitDocument", "tags": [ "documentos" ], "summary": "Crear un documento de salida", "description": "Manda a surtir un pedido (orden de venta, remisión, salida). Mismas reglas que la plantilla de carga masiva;\n`Idempotency-Key` obligatoria. Un `type` con un `external_ref` que ya existe responde `200` con ese documento.\n", "security": [ { "clientCredentials": [ "pickings:write" ] }, { "userToken": [] } ], "x-permission": "exits.manage", "x-idempotency": "required", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExitDocumentInput" }, "example": { "external_ref": "PED-88121", "type": "Orden de Venta", "doc_date": "2026-10-06", "due_date": "2026-10-07", "partner_code": "CLI-001", "partner_name": "Abarrotes del Norte", "warehouse_code": "CEDIS-GDL", "priority": "Alta", "ship_to": "Av. Vallarta 1200, Guadalajara", "lines": [ { "item_code": "P-1001", "qty": 6 } ] } } } }, "responses": { "200": { "description": "Ya existía un documento con ese `type` y `external_ref`; se devuelve ese.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExitDocumentItem" }, "example": { "data": { "id": 1, "doc_num": "OV-000001", "type": "sale_order", "external_ref": "PED-88121", "source": "api", "status": "open", "card_code": "CLI-001", "card_name": null, "doc_date": "2026-10-06", "due_date": "2026-10-06", "comments": null, "priority": 50, "ship_to": null, "lines": [ { "line_num": 0, "item_code": "P-1001", "qty": 6, "open_qty": 6, "picked_qty": 0, "whs_code": "CEDIS-GDL", "status": "open" } ], "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "201": { "description": "Documento creado. `Location` apunta al nuevo recurso.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExitDocumentItem" }, "example": { "data": { "id": 977, "doc_num": "OV-000977", "type": "sale_order", "external_ref": "PED-88121", "source": "api", "status": "open", "card_code": "CLI-001", "card_name": "Abarrotes del Norte", "doc_date": "2026-10-06", "due_date": "2026-10-07", "comments": null, "priority": 80, "ship_to": "Av. Vallarta 1200, Guadalajara", "lines": [ { "line_num": 0, "item_code": "P-1001", "qty": 6, "open_qty": 6, "picked_qty": 0, "whs_code": "CEDIS-GDL", "status": "open" } ], "created_at": "2026-10-06T16:22:40.000000Z", "updated_at": "2026-10-06T16:22:40.000000Z" } } } } }, "400": { "$ref": "#/components/responses/IdempotencyKeyRequired" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/exit-documents/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getExitDocument", "tags": [ "documentos" ], "summary": "Consultar un documento de salida", "security": [ { "clientCredentials": [ "pickings:read" ] }, { "userToken": [] } ], "responses": { "200": { "description": "El documento con su avance por línea.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExitDocumentItem" }, "example": { "data": { "id": 1, "doc_num": "OV-000001", "type": "sale_order", "external_ref": "PED-88121", "source": "api", "status": "open", "card_code": "CLI-001", "card_name": null, "doc_date": "2026-10-06", "due_date": "2026-10-06", "comments": null, "priority": 50, "ship_to": null, "lines": [ { "line_num": 0, "item_code": "P-1001", "qty": 6, "open_qty": 6, "picked_qty": 0, "whs_code": "CEDIS-GDL", "status": "open" } ], "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/receipts": { "get": { "operationId": "listReceipts", "tags": [ "operacion" ], "summary": "Listar recepciones", "description": "Las recepciones (el trabajo de recibir un documento de entrada), de la más reciente a la más antigua.", "security": [ { "clientCredentials": [ "receipts:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "finalized_at", "-finalized_at" ], "default": "-created_at" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "status", "in": "query", "description": "Estado de la recepción.", "schema": { "$ref": "#/components/schemas/WorkStatus" } }, { "name": "from", "in": "query", "description": "Creadas desde esta fecha (AAAA-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Creadas hasta esta fecha (AAAA-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "external_ref", "in": "query", "description": "La referencia externa del documento de entrada.", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Página de recepciones.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptList" }, "example": { "data": [ { "id": 1, "uuid": "6c1f0b8e-3d2a-4f5b-9e7c-2a4d8b1c0f93", "concept": "delivery_good", "status": "finalized", "comments": null, "user_id": 2, "operator": { "id": 2, "name": "Juan Pérez" }, "document": { "id": 2, "type": "delivery_good", "doc_num": "ED-740259", "card_code": null, "external_ref": null }, "started_at": null, "finalized_at": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } ], "links": { "first": "https://empresa.chainlink.mx/api/v1/receipts?page=1", "last": "https://empresa.chainlink.mx/api/v1/receipts?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://empresa.chainlink.mx/api/v1/receipts", "per_page": 25, "to": 1, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/receipts/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getReceipt", "tags": [ "operacion" ], "summary": "Consultar una recepción", "description": "La recepción con sus líneas recibidas (producto, cantidad, lote y series).", "security": [ { "clientCredentials": [ "receipts:read" ] }, { "userToken": [] } ], "responses": { "200": { "description": "La recepción con sus líneas.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReceiptDetail" } } }, "example": { "data": { "id": 5531, "uuid": "0f8e0c1e-6a7b-4b1e-9a51-3d0b7f2b8c11", "concept": "purchase_order", "status": "finalized", "comments": null, "user_id": 12, "operator": { "id": 12, "name": "Juan Pérez" }, "document": { "id": 318, "type": "purchase_order", "doc_num": "OC-000318", "card_code": "PRV-001", "external_ref": "OC-2026-0042" }, "started_at": "2026-10-06T17:01:00.000000Z", "finalized_at": "2026-10-06T17:12:44.000000Z", "created_at": "2026-10-06T16:20:12.000000Z", "updated_at": "2026-10-06T17:12:44.000000Z", "lines": [ { "product_id": 101, "item_code": "P-1001", "qty": 48, "batch_num": "L2610", "serials": [] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pickings": { "get": { "operationId": "listPickings", "tags": [ "operacion" ], "summary": "Listar surtidos", "description": "Los surtidos (el trabajo de surtir un documento de salida), del más reciente al más antiguo.", "security": [ { "clientCredentials": [ "pickings:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "finalized_at", "-finalized_at", "priority", "-priority" ], "default": "-created_at" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "status", "in": "query", "description": "Estado del surtido.", "schema": { "$ref": "#/components/schemas/WorkStatus" } }, { "name": "from", "in": "query", "description": "Creados desde esta fecha (AAAA-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Creados hasta esta fecha (AAAA-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "external_ref", "in": "query", "description": "La referencia externa del documento de salida.", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Página de surtidos.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickingList" }, "example": { "data": [ { "id": 5, "code": "PKG-5", "uuid": "6c1f0b8e-3d2a-4f5b-9e7c-2a4d8b1c0f93", "concept": "dispatch_good", "status": "pending", "priority": 50, "has_shortage": false, "comments": null, "user_id": 2, "operator": { "id": 2, "name": "Juan Pérez" }, "document": { "id": 6, "type": "dispatch_good", "doc_num": "SD-627227", "card_code": null, "external_ref": null }, "started_at": null, "finalized_at": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } ], "links": { "first": "https://empresa.chainlink.mx/api/v1/pickings?page=1", "last": "https://empresa.chainlink.mx/api/v1/pickings?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://empresa.chainlink.mx/api/v1/pickings", "per_page": 25, "to": 5, "total": 5 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/pickings/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getPicking", "tags": [ "operacion" ], "summary": "Consultar un surtido", "description": "El surtido con sus líneas surtidas.", "security": [ { "clientCredentials": [ "pickings:read" ] }, { "userToken": [] } ], "responses": { "200": { "description": "El surtido con sus líneas.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PickingDetail" } } }, "example": { "data": { "id": 5, "code": "PKG-5", "uuid": "6c1f0b8e-3d2a-4f5b-9e7c-2a4d8b1c0f93", "concept": "dispatch_good", "status": "pending", "priority": 50, "has_shortage": false, "comments": null, "user_id": 2, "operator": { "id": 2, "name": "Juan Pérez" }, "document": { "id": 6, "type": "dispatch_good", "doc_num": "SD-627227", "card_code": null, "external_ref": null }, "started_at": null, "finalized_at": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z", "lines": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/transfers": { "get": { "operationId": "listTransfers", "tags": [ "operacion" ], "summary": "Listar traspasos", "description": "Movimientos de mercancía entre ubicaciones o almacenes registrados en la operación.", "security": [ { "clientCredentials": [ "transfers:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "-created_at" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "status", "in": "query", "description": "Estado (`pending`, `transferred`, `error`).", "schema": { "type": "string", "enum": [ "pending", "transferred", "error" ] } }, { "name": "from", "in": "query", "description": "Creados desde esta fecha (AAAA-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Creados hasta esta fecha (AAAA-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "from_warehouse", "in": "query", "description": "Código del almacén de origen.", "schema": { "type": "string", "maxLength": 20 } }, { "name": "to_warehouse", "in": "query", "description": "Código del almacén de destino.", "schema": { "type": "string", "maxLength": 20 } } ], "responses": { "200": { "description": "Página de traspasos.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferList" }, "example": { "data": [ { "id": 1, "status": "pending", "wms_status": "pending", "sap_status": "pending", "from_whs_code": "CEDIS-GDL", "to_whs_code": "TDA-MTY", "doc_entry": null, "message": null, "user_id": 2, "operator": { "id": 2, "name": "Juan Pérez" }, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } ], "links": { "first": "https://empresa.chainlink.mx/api/v1/transfers?page=1", "last": "https://empresa.chainlink.mx/api/v1/transfers?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://empresa.chainlink.mx/api/v1/transfers", "per_page": 25, "to": 1, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/transfers/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getTransfer", "tags": [ "operacion" ], "summary": "Consultar un traspaso", "security": [ { "clientCredentials": [ "transfers:read" ] }, { "userToken": [] } ], "responses": { "200": { "description": "El traspaso con sus líneas.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TransferDetail" } } }, "example": { "data": { "id": 1, "status": "pending", "wms_status": "pending", "sap_status": "pending", "from_whs_code": "CEDIS-GDL", "to_whs_code": "TDA-MTY", "doc_entry": null, "message": null, "user_id": 2, "operator": { "id": 2, "name": "Juan Pérez" }, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z", "lines": [ { "product_id": 1, "item_code": "P-1001", "qty": 12, "from_position": "R-10-01-1", "to_position": "MTY-A-01", "batch": "L2610", "serial": null, "status": "pending" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/transfer-orders": { "get": { "operationId": "listTransferOrders", "tags": [ "ordenes-de-transferencia" ], "summary": "Listar órdenes de transferencia", "description": "Requiere el módulo de órdenes de transferencia; apagado, responde `404 transfer_orders_disabled`.", "security": [ { "clientCredentials": [ "transfers:read" ] }, { "userToken": [] } ], "x-gates": [ "ops.module:transfer_orders" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "id", "-id", "created_at", "-created_at", "updated_at", "-updated_at", "due_at", "-due_at", "priority", "-priority" ], "default": "-id" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "status", "in": "query", "description": "Estado de la orden.", "schema": { "$ref": "#/components/schemas/TransferOrderStatus" } }, { "name": "from_warehouse", "in": "query", "description": "Código del almacén de origen.", "schema": { "type": "string", "maxLength": 20 } }, { "name": "to_warehouse", "in": "query", "description": "Código del almacén de destino.", "schema": { "type": "string", "maxLength": 20 } }, { "name": "external_ref", "in": "query", "description": "Referencia externa de la orden.", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Página de órdenes (sin líneas; el detalle de cada orden las incluye).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferOrderList" }, "example": { "data": [ { "object": "transfer_order", "id": 1, "code": "TR-000001", "status": "draft", "status_label": "Borrador", "headline": "TR-000001 · De CEDIS-GDL a TDA-MTY · Borrador", "has_discrepancy": false, "from": { "id": 1, "code": "CEDIS-GDL", "name": "CEDIS Guadalajara" }, "to": { "id": 2, "code": "TDA-MTY", "name": "Tienda Monterrey" }, "priority": 0, "reason": null, "due_at": null, "lines_count": 1, "units": { "requested": 24, "picked": 0, "dispatched": 0, "received": 0 }, "dispatched_at": null, "received_at": null, "closed_at": null, "seal_number": null, "vehicle_plate": null, "carrier_id": null, "external_ref": "TR-2026-0107", "source": "api", "picking_id": null, "receipt_id": null, "sap": { "dispatch": null, "receipt": null }, "lines": null } ], "links": { "first": "https://empresa.chainlink.mx/api/v1/transfer-orders?page=1", "last": "https://empresa.chainlink.mx/api/v1/transfer-orders?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://empresa.chainlink.mx/api/v1/transfer-orders", "per_page": 25, "to": 1, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/ModuleDisabled" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createTransferOrder", "tags": [ "ordenes-de-transferencia" ], "summary": "Crear una orden de transferencia", "description": "Crea una orden en borrador o, con `release: true`, la libera para surtido de inmediato. Con un cliente de\nintegración, liberar exige `picker_id` (el surtidor). Un `external_ref` que ya existe responde `200` con esa orden.\n", "security": [ { "clientCredentials": [ "transfers:write" ] }, { "userToken": [] } ], "x-permission": "transfer-orders.manage", "x-idempotency": "optional", "x-gates": [ "ops.module:transfer_orders" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferOrderInput" }, "example": { "from_warehouse": "CEDIS-GDL", "to_warehouse": "TDA-MTY", "priority": 50, "reason": "Reabasto semanal", "due_at": "2026-10-08T18:00:00-06:00", "external_ref": "TR-2026-0107", "lines": [ { "item_code": "P-1001", "qty": 24 } ] } } } }, "responses": { "200": { "description": "Ya existía una orden con ese `external_ref`; se devuelve esa.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferOrderItem" }, "example": { "data": { "object": "transfer_order", "id": 1, "code": "TR-000001", "status": "draft", "status_label": "Borrador", "headline": "TR-000001 · De CEDIS-GDL a TDA-MTY · Borrador", "has_discrepancy": false, "from": { "id": 1, "code": "CEDIS-GDL", "name": "CEDIS Guadalajara" }, "to": { "id": 2, "code": "TDA-MTY", "name": "Tienda Monterrey" }, "priority": 0, "reason": null, "due_at": null, "lines_count": 1, "units": { "requested": 24, "picked": 0, "dispatched": 0, "received": 0 }, "dispatched_at": null, "received_at": null, "closed_at": null, "seal_number": null, "vehicle_plate": null, "carrier_id": null, "external_ref": "TR-2026-0107", "source": "api", "picking_id": null, "receipt_id": null, "sap": { "dispatch": null, "receipt": null }, "lines": [ { "id": 1, "line_num": 1, "product_id": 1, "item_code": "P-1001", "qty": 24, "picked_qty": 0, "dispatched_qty": 0, "received_qty": 0, "batch_num": null, "serial_numbers": [], "status": "open" } ] } } } } }, "201": { "description": "Orden creada. `Location` apunta al nuevo recurso.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferOrderItem" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/ModuleDisabled" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/transfer-orders/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getTransferOrder", "tags": [ "ordenes-de-transferencia" ], "summary": "Consultar una orden de transferencia", "security": [ { "clientCredentials": [ "transfers:read" ] }, { "userToken": [] } ], "x-gates": [ "ops.module:transfer_orders" ], "responses": { "200": { "description": "La orden con sus líneas y unidades pedidas, surtidas, despachadas y recibidas.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferOrderItem" }, "example": { "data": { "object": "transfer_order", "id": 41, "code": "TR-000041", "status": "in_transit", "status_label": "En tránsito", "headline": "CEDIS-GDL → TDA-MTY", "has_discrepancy": false, "from": { "id": 1, "code": "CEDIS-GDL", "name": "CEDIS Guadalajara" }, "to": { "id": 2, "code": "TDA-MTY", "name": "Tienda Monterrey" }, "priority": 50, "reason": "Reabasto semanal", "due_at": "2026-10-08T18:00:00-06:00", "lines_count": 1, "units": { "requested": 24, "picked": 24, "dispatched": 24, "received": 0 }, "dispatched_at": "2026-10-07T09:30:00-06:00", "received_at": null, "closed_at": null, "seal_number": "S-99812", "vehicle_plate": "JAL-123-A", "carrier_id": 3, "external_ref": "TR-2026-0107", "source": "api", "picking_id": 6120, "receipt_id": null, "sap": { "dispatch": null, "receipt": null }, "lines": [ { "id": 77, "line_num": 0, "product_id": 101, "item_code": "P-1001", "qty": 24, "picked_qty": 24, "dispatched_qty": 24, "received_qty": 0, "batch_num": null, "serial_numbers": [], "status": "dispatched" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/waves": { "get": { "operationId": "listWaves", "tags": [ "olas" ], "summary": "Listar olas", "description": "Requiere el módulo de olas y el permiso `exits.manage` (o el alcance `pickings:read`).", "security": [ { "clientCredentials": [ "pickings:read" ] }, { "userToken": [] } ], "x-permission": "exits.manage", "x-gates": [ "feature:modules.waves" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "id", "-id", "created_at", "-created_at", "updated_at", "-updated_at", "due_at", "-due_at" ], "default": "-id" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "status", "in": "query", "description": "Estado de la ola.", "schema": { "$ref": "#/components/schemas/WaveStatus" } }, { "name": "warehouse", "in": "query", "description": "Código del almacén.", "schema": { "type": "string", "maxLength": 20 } }, { "name": "from", "in": "query", "description": "Creadas desde esta fecha.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Creadas hasta esta fecha.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Página de olas.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaveList" }, "example": { "data": [ { "id": 1, "code": "W-0001", "warehouse_code": "CEDIS-GDL", "strategy": "cluster", "status": "planned", "carrier_code": null, "cutoff_at": null, "released_at": null, "metrics": { "lines": 2, "trips": 0, "units": 3, "orders": 2, "standard_minutes": 1 }, "created_at": "2026-10-06T10:20:11-06:00", "updated_at": "2026-10-06T10:20:11-06:00" } ], "links": { "first": "https://empresa.chainlink.mx/api/v1/waves?page=1", "last": "https://empresa.chainlink.mx/api/v1/waves?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://empresa.chainlink.mx/api/v1/waves", "per_page": 25, "to": 1, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createWave", "tags": [ "olas" ], "summary": "Planear una ola", "description": "Planea una ola con una lista de surtidos (`picking_ids`) o con los filtros del planeador (`filters`). La ola\nqueda planeada; liberarla es decisión de un supervisor en la web.\n", "security": [ { "clientCredentials": [ "pickings:write" ] }, { "userToken": [] } ], "x-permission": "exits.manage", "x-idempotency": "optional", "x-gates": [ "feature:modules.waves" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaveInput" }, "example": { "warehouse": "CEDIS-GDL", "strategy": "batch", "filters": { "customer": "CLI-001", "due_by": "2026-10-07" } } } } }, "responses": { "201": { "description": "Ola planeada. `Location` apunta al nuevo recurso.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaveItem" }, "example": { "data": { "id": 9, "code": "OLA-000009", "warehouse_code": "CEDIS-GDL", "strategy": "batch", "status": "planned", "carrier_code": null, "cutoff_at": null, "released_at": null, "metrics": { "lines": 3, "trips": 0, "units": 18, "orders": 2, "standard_minutes": 1.1 }, "created_at": "2026-10-06T10:20:11-06:00", "updated_at": "2026-10-06T10:20:11-06:00", "orders": [ { "picking_id": 6120, "status": "planned" }, { "picking_id": 6121, "status": "planned" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/waves/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getWave", "tags": [ "olas" ], "summary": "Consultar una ola", "security": [ { "clientCredentials": [ "pickings:read" ] }, { "userToken": [] } ], "x-permission": "exits.manage", "x-gates": [ "feature:modules.waves" ], "responses": { "200": { "description": "La ola con sus pedidos.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaveItem" }, "example": { "data": { "id": 1, "code": "W-0001", "warehouse_code": "CEDIS-GDL", "strategy": "cluster", "status": "planned", "carrier_code": null, "cutoff_at": null, "released_at": null, "metrics": { "lines": 2, "trips": 0, "units": 3, "orders": 2, "standard_minutes": 1 }, "created_at": "2026-10-06T10:20:11-06:00", "updated_at": "2026-10-06T10:20:11-06:00", "orders": [ { "picking_id": 1, "status": "allocated" }, { "picking_id": 2, "status": "allocated" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/imports": { "post": { "operationId": "createImport", "tags": [ "carga-masiva" ], "summary": "Subir un archivo de carga masiva", "description": "Sube un archivo `.xlsx` o `.csv` (máximo 5 MB) con la plantilla de la web y lo valida sin aplicar nada. Responde\n`202` con el resultado de la validación; el estado se consulta y la carga se confirma con\n[confirmar carga](#operation/commitImport). Los límites de filas dependen del plan (2,000 en Essentials,\n10,000 en Professional, 100,000 en Enterprise).\n", "security": [ { "clientCredentials": [ "products:write" ] }, { "userToken": [] } ], "x-permission": "imports.run", "x-idempotency": "optional", "x-gates": [ "ops.module:bulk_import" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImportInput" } } } }, "responses": { "202": { "description": "Archivo recibido y validado. `Location` apunta a la carga.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportItem" }, "example": { "data": { "id": 14, "kind": "products", "status": "validated", "file": "catalogo-octubre.xlsx", "rows": { "total": 250, "valid": 248, "error": 2 }, "documents": { "total": 0, "valid": 0, "committed": 0 }, "structure_errors": [], "error_report_url": "https://demo.chainlink.mx/imports/14/errors.xlsx", "committed_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/ModuleDisabled" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/imports/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getImport", "tags": [ "carga-masiva" ], "summary": "Consultar una carga", "security": [ { "clientCredentials": [ "products:read" ] }, { "userToken": [] } ], "x-permission": "imports.run", "x-gates": [ "ops.module:bulk_import" ], "responses": { "200": { "description": "Estado, conteos y enlace al reporte de errores.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportItem" }, "example": { "data": { "id": 1, "kind": "products", "status": "validated", "file": "catalogo.csv", "rows": { "total": 1, "valid": 1, "error": 0 }, "documents": { "total": 1, "valid": 1, "committed": 0 }, "structure_errors": [], "error_report_url": null, "committed_at": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/imports/{id}/commit": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "commitImport", "tags": [ "carga-masiva" ], "summary": "Confirmar una carga", "description": "Aplica las filas válidas de la carga. Si la carga no tiene nada por confirmar o ya se está confirmando, responde `409 import_refused`.", "security": [ { "clientCredentials": [ "products:write" ] }, { "userToken": [] } ], "x-permission": "imports.run", "x-idempotency": "optional", "x-gates": [ "ops.module:bulk_import" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Carga aplicada o en proceso.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportItem" }, "example": { "data": { "id": 1, "kind": "products", "status": "committed", "file": "catalogo.csv", "rows": { "total": 1, "valid": 1, "error": 0 }, "documents": { "total": 1, "valid": 1, "committed": 1 }, "structure_errors": [], "error_report_url": null, "committed_at": "2026-10-06T10:20:11-06:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/clients": { "get": { "operationId": "listClients", "tags": [ "socios" ], "summary": "Listar clientes", "security": [ { "clientCredentials": [ "clients:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "name" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "search", "in": "query", "description": "Parte del nombre.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "document_id", "in": "query", "description": "Número de documento fiscal exacto.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Página de clientes.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientList" }, "example": { "data": [ { "id": 1, "name": "Comercial del Pacífico", "document_type": "V", "document_id": 5022331, "email": null, "phone": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } ], "links": { "first": "https://empresa.chainlink.mx/api/v1/clients?page=1", "last": "https://empresa.chainlink.mx/api/v1/clients?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://empresa.chainlink.mx/api/v1/clients", "per_page": 25, "to": 1, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createClient", "tags": [ "socios" ], "summary": "Crear un cliente", "security": [ { "clientCredentials": [ "clients:write" ] }, { "userToken": [] } ], "x-permission": "exits.manage", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientInput" }, "example": { "name": "Abarrotes del Norte", "document_type": "R", "document_id": 4011220, "email": "compras@abarrotesnorte.mx", "phone": "81 5555 0101" } } } }, "responses": { "201": { "description": "Creado. `Location` apunta al nuevo recurso.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientItem" }, "example": { "data": { "id": 7, "name": "Abarrotes del Norte", "document_type": "R", "document_id": 4011220, "email": "compras@abarrotesnorte.mx", "phone": "81 5555 0101", "created_at": "2026-09-20T15:00:00.000000Z", "updated_at": "2026-09-20T15:00:00.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/clients/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getClient", "tags": [ "socios" ], "summary": "Consultar un cliente", "security": [ { "clientCredentials": [ "clients:read" ] }, { "userToken": [] } ], "responses": { "200": { "description": "El cliente.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientItem" }, "example": { "data": { "id": 7, "name": "Abarrotes del Norte", "document_type": "R", "document_id": 4011220, "email": "compras@abarrotesnorte.mx", "phone": "81 5555 0101", "created_at": "2026-09-20T15:00:00.000000Z", "updated_at": "2026-09-20T15:00:00.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "updateClient", "tags": [ "socios" ], "summary": "Actualizar un cliente", "description": "Cambia solo los campos enviados.", "security": [ { "clientCredentials": [ "clients:write" ] }, { "userToken": [] } ], "x-permission": "exits.manage", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientUpdate" }, "example": { "phone": "33 1234 5678" } } } }, "responses": { "200": { "description": "El cliente actualizado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientItem" }, "example": { "data": { "id": 1, "name": "Comercial del Pacífico", "document_type": "V", "document_id": 5022331, "email": null, "phone": "33 1234 5678", "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "operationId": "replaceClient", "tags": [ "socios" ], "summary": "Actualizar un cliente (PUT)", "description": "Igual que `PATCH`; se conserva por compatibilidad.", "security": [ { "clientCredentials": [ "clients:write" ] }, { "userToken": [] } ], "x-permission": "exits.manage", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientUpdate" }, "example": { "phone": "33 1234 5679" } } } }, "responses": { "200": { "description": "El cliente actualizado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientItem" }, "example": { "data": { "id": 1, "name": "Comercial del Pacífico", "document_type": "V", "document_id": 5022331, "email": null, "phone": "33 1234 5679", "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteClient", "tags": [ "socios" ], "summary": "Eliminar un cliente", "description": "Da de baja el cliente; sus documentos anteriores se conservan.", "security": [ { "clientCredentials": [ "clients:write" ] }, { "userToken": [] } ], "x-permission": "exits.manage", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Eliminado; sin cuerpo.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/providers": { "get": { "operationId": "listProviders", "tags": [ "socios" ], "summary": "Listar proveedores", "security": [ { "clientCredentials": [ "providers:read" ] }, { "userToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "sort", "in": "query", "description": "Campo de orden; antepón `-` para descendente.", "schema": { "type": "string", "enum": [ "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "name" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "name": "search", "in": "query", "description": "Parte del nombre.", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Página de proveedores.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderList" }, "example": { "data": [ { "id": 1, "name": "Aceites del Centro", "email": null, "phone": null, "description": null, "paymentinfo": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } ], "links": { "first": "https://empresa.chainlink.mx/api/v1/providers?page=1", "last": "https://empresa.chainlink.mx/api/v1/providers?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [], "path": "https://empresa.chainlink.mx/api/v1/providers", "per_page": 25, "to": 1, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createProvider", "tags": [ "socios" ], "summary": "Crear un proveedor", "security": [ { "clientCredentials": [ "providers:write" ] }, { "userToken": [] } ], "x-permission": "entries.manage", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInput" }, "example": { "name": "Distribuidora del Bajío", "email": "ventas@dbajio.mx", "phone": "477 555 0199", "description": "Abarrotes y aceites" } } } }, "responses": { "201": { "description": "Creado. `Location` apunta al nuevo recurso.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderItem" }, "example": { "data": { "id": 4, "name": "Distribuidora del Bajío", "email": "ventas@dbajio.mx", "phone": "477 555 0199", "description": "Abarrotes y aceites", "paymentinfo": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/providers/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getProvider", "tags": [ "socios" ], "summary": "Consultar un proveedor", "security": [ { "clientCredentials": [ "providers:read" ] }, { "userToken": [] } ], "responses": { "200": { "description": "El proveedor.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderItem" }, "example": { "data": { "id": 4, "name": "Distribuidora del Bajío", "email": "ventas@dbajio.mx", "phone": "477 555 0199", "description": null, "paymentinfo": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "updateProvider", "tags": [ "socios" ], "summary": "Actualizar un proveedor", "description": "Cambia solo los campos enviados.", "security": [ { "clientCredentials": [ "providers:write" ] }, { "userToken": [] } ], "x-permission": "entries.manage", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderUpdate" }, "example": { "phone": "33 1234 5678" } } } }, "responses": { "200": { "description": "El proveedor actualizado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderItem" }, "example": { "data": { "id": 1, "name": "Aceites del Centro", "email": null, "phone": "33 1234 5678", "description": null, "paymentinfo": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "operationId": "replaceProvider", "tags": [ "socios" ], "summary": "Actualizar un proveedor (PUT)", "description": "Igual que `PATCH`; se conserva por compatibilidad.", "security": [ { "clientCredentials": [ "providers:write" ] }, { "userToken": [] } ], "x-permission": "entries.manage", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderUpdate" }, "example": { "phone": "33 1234 5679" } } } }, "responses": { "200": { "description": "El proveedor actualizado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderItem" }, "example": { "data": { "id": 1, "name": "Aceites del Centro", "email": null, "phone": "33 1234 5679", "description": null, "paymentinfo": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteProvider", "tags": [ "socios" ], "summary": "Eliminar un proveedor", "description": "Da de baja el proveedor; sus documentos anteriores se conservan.", "security": [ { "clientCredentials": [ "providers:write" ] }, { "userToken": [] } ], "x-permission": "entries.manage", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Eliminado; sin cuerpo.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "webhooks" ], "summary": "Listar suscripciones", "description": "Todas las suscripciones de la empresa, sin el secreto de firma. Requiere el plan Professional o Enterprise (`webhooks.enabled`).", "security": [ { "clientCredentials": [ "webhooks:manage" ] }, { "userToken": [] } ], "x-gates": [ "feature:webhooks.enabled" ], "responses": { "200": { "description": "Las suscripciones (lista sin paginar).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "example": { "data": [ { "id": 3, "url": "https://erp.example.com/chainlink/webhooks", "events": [ "receipt.completed", "stock.updated" ], "is_active": true, "failure_count": 0, "last_triggered_at": "2026-10-06T17:12:46.000000Z", "created_at": "2026-10-01T12:00:00.000000Z", "updated_at": "2026-10-06T17:12:46.000000Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createWebhook", "tags": [ "webhooks" ], "summary": "Crear una suscripción", "description": "Registra una URL para recibir los eventos indicados. La respuesta trae el secreto de firma (`secret`)\n**una sola vez**: debe guardarse para verificar `X-Chainlink-Signature`. Si no se envía `secret`, Chainlink genera uno.\n\nLa URL debe usar `https://` y apuntar a una dirección pública de internet: se rechazan con `422` las\ndirecciones privadas, locales, de enlace local, CGNAT, multicast, reservadas y de metadatos de la nube, en IPv4\ne IPv6, también cuando el dominio resuelve a una de ellas. La comprobación se repite en cada entrega.\n", "security": [ { "clientCredentials": [ "webhooks:manage" ] }, { "userToken": [] } ], "x-permission": "users.manage", "x-idempotency": "optional", "x-gates": [ "feature:webhooks.enabled" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionInput" }, "example": { "url": "https://erp.example.com/chainlink/webhooks", "events": [ "receipt.completed", "picking.completed", "stock.updated" ] } } } }, "responses": { "201": { "description": "Suscripción creada, con su secreto. `Location` apunta al nuevo recurso.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/WebhookSubscription" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "Secreto de firma. Solo aparece en esta respuesta." } } } ] } } }, "example": { "data": { "id": 3, "url": "https://erp.example.com/chainlink/webhooks", "events": [ "receipt.completed", "picking.completed", "stock.updated" ], "is_active": true, "failure_count": 0, "last_triggered_at": null, "created_at": "2026-10-06T16:40:00.000000Z", "updated_at": "2026-10-06T16:40:00.000000Z", "secret": "9f2c1d7e0a5b4c3d8e6f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getWebhook", "tags": [ "webhooks" ], "summary": "Consultar una suscripción", "security": [ { "clientCredentials": [ "webhooks:manage" ] }, { "userToken": [] } ], "x-gates": [ "feature:webhooks.enabled" ], "responses": { "200": { "description": "La suscripción, sin el secreto.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionItem" }, "example": { "data": { "id": 1, "url": "https://erp.example.com/chainlink/webhooks", "events": [ "receipt.completed" ], "is_active": true, "failure_count": 0, "last_triggered_at": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "updateWebhook", "tags": [ "webhooks" ], "summary": "Cambiar una suscripción", "description": "Cambia la URL, los eventos o el estado. Tras 10 entregas fallidas seguidas la suscripción se desactiva sola;\n`is_active: true` la reactiva y reinicia el contador de fallas.\n", "security": [ { "clientCredentials": [ "webhooks:manage" ] }, { "userToken": [] } ], "x-permission": "users.manage", "x-idempotency": "optional", "x-gates": [ "feature:webhooks.enabled" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdate" }, "example": { "is_active": true } } } }, "responses": { "200": { "description": "La suscripción actualizada.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionItem" }, "example": { "data": { "id": 1, "url": "https://erp.example.com/chainlink/webhooks", "events": [ "receipt.completed" ], "is_active": true, "failure_count": 0, "last_triggered_at": null, "created_at": "2026-10-06T16:20:11.000000Z", "updated_at": "2026-10-06T16:20:11.000000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteWebhook", "tags": [ "webhooks" ], "summary": "Eliminar una suscripción", "security": [ { "clientCredentials": [ "webhooks:manage" ] }, { "userToken": [] } ], "x-permission": "users.manage", "x-idempotency": "optional", "x-gates": [ "feature:webhooks.enabled" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Eliminada; sin cuerpo.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "webhooks": { "receipt.created": { "post": { "operationId": "onReceiptCreated", "summary": "Recepción creada", "description": "Se creó una recepción para un documento de entrada.", "x-group": "Recepciones", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "receipt.created" }, "data": { "$ref": "#/components/schemas/ReceiptEvent" } } } ] }, "example": { "event": "receipt.created", "version": 1, "data": { "id": 5531, "concept": "purchase_order", "status": "pending", "document": { "type": "App\\Models\\DeliveryGood", "doc_num": "OC-000318" }, "operator": { "id": 12, "name": "Juan Pérez" }, "started_at": null, "finalized_at": null, "lines": [] }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "receipt.completed": { "post": { "operationId": "onReceiptCompleted", "summary": "Recepción finalizada", "description": "El operador finalizó la recepción; `lines` trae lo recibido.", "x-group": "Recepciones", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "receipt.completed" }, "data": { "$ref": "#/components/schemas/ReceiptEvent" } } } ] }, "example": { "event": "receipt.completed", "version": 1, "data": { "id": 5531, "concept": "purchase_order", "status": "finalized", "document": { "type": "App\\Models\\DeliveryGood", "doc_num": "OC-000318" }, "operator": { "id": 12, "name": "Juan Pérez" }, "started_at": "2026-10-06T11:01:00-06:00", "finalized_at": "2026-10-06T11:12:44-06:00", "lines": [ { "item_code": "P-1001", "qty": 48, "batch": "L2610", "serials": [] } ] }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "picking.created": { "post": { "operationId": "onPickingCreated", "summary": "Surtido creado", "description": "Se creó un surtido para un documento de salida.", "x-group": "Surtidos", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "picking.created" }, "data": { "$ref": "#/components/schemas/PickingEvent" } } } ] }, "example": { "event": "picking.created", "version": 1, "data": { "id": 6120, "code": "PKG-6120", "concept": "sale_order", "status": "pending", "document": { "type": "App\\Models\\DispatchGood", "doc_num": "OV-000977" }, "operator": null, "started_at": null, "finalized_at": null, "lines": [] }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "picking.completed": { "post": { "operationId": "onPickingCompleted", "summary": "Surtido finalizado", "description": "El surtido terminó; `lines` trae lo surtido con lotes y series.", "x-group": "Surtidos", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "picking.completed" }, "data": { "$ref": "#/components/schemas/PickingEvent" } } } ] }, "example": { "event": "picking.completed", "version": 1, "data": { "id": 6120, "code": "PKG-6120", "concept": "sale_order", "status": "finalized", "document": { "type": "App\\Models\\DispatchGood", "doc_num": "OV-000977" }, "operator": { "id": 14, "name": "Ana Ruiz" }, "started_at": "2026-10-06T12:00:00-06:00", "finalized_at": "2026-10-06T12:09:30-06:00", "lines": [ { "item_code": "P-1001", "qty": 6, "batch": "L2610", "serials": [] } ] }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "transfer.created": { "post": { "operationId": "onTransferCreated", "summary": "Traspaso creado", "description": "Se registró un movimiento entre ubicaciones o almacenes.", "x-group": "Traspasos", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "transfer.created" }, "data": { "$ref": "#/components/schemas/TransferEvent" } } } ] }, "example": { "event": "transfer.created", "version": 1, "data": { "id": 880, "status": "pending", "from_whs_code": "CEDIS-GDL", "to_whs_code": "CEDIS-GDL", "operator": { "id": 12, "name": "Juan Pérez" }, "lines": [ { "item_code": "P-1001", "qty": 12, "from_position": "RECEPCION", "to_position": "A-01-01-1", "batch": "L2610", "serial": null } ] }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "transfer.completed": { "post": { "operationId": "onTransferCompleted", "summary": "Traspaso aplicado", "description": "El movimiento se aplicó a las existencias.", "x-group": "Traspasos", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "transfer.completed" }, "data": { "$ref": "#/components/schemas/TransferEvent" } } } ] }, "example": { "event": "transfer.completed", "version": 1, "data": { "id": 880, "status": "transferred", "from_whs_code": "CEDIS-GDL", "to_whs_code": "CEDIS-GDL", "operator": { "id": 12, "name": "Juan Pérez" }, "lines": [ { "item_code": "P-1001", "qty": 12, "from_position": "RECEPCION", "to_position": "A-01-01-1", "batch": "L2610", "serial": null } ] }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "transfer.dispatched": { "post": { "operationId": "onTransferDispatched", "summary": "Orden de transferencia despachada", "description": "La mercancía salió del almacén de origen.", "x-group": "Órdenes de transferencia", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "transfer.dispatched" }, "data": { "$ref": "#/components/schemas/TransferOrder" } } } ] }, "example": { "event": "transfer.dispatched", "version": 1, "data": { "object": "transfer_order", "id": 41, "code": "TR-000041", "status": "in_transit", "status_label": "En tránsito", "headline": "CEDIS-GDL → TDA-MTY", "has_discrepancy": false, "from": { "id": 1, "code": "CEDIS-GDL", "name": "CEDIS Guadalajara" }, "to": { "id": 2, "code": "TDA-MTY", "name": "Tienda Monterrey" }, "priority": 50, "reason": "Reabasto semanal", "due_at": "2026-10-08T18:00:00-06:00", "lines_count": 1, "units": { "requested": 24, "picked": 24, "dispatched": 24, "received": 0 }, "dispatched_at": "2026-10-07T09:30:00-06:00", "received_at": null, "closed_at": null, "seal_number": "S-99812", "vehicle_plate": "JAL-123-A", "carrier_id": 3, "external_ref": "TR-2026-0107", "source": "api", "picking_id": 6120, "receipt_id": null, "sap": null, "lines": [ { "id": 77, "line_num": 0, "product_id": 101, "item_code": "P-1001", "qty": 24, "picked_qty": 24, "dispatched_qty": 24, "received_qty": 0, "batch_num": null, "serial_numbers": [], "status": "dispatched" } ] }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "transfer.received": { "post": { "operationId": "onTransferReceived", "summary": "Orden de transferencia recibida", "description": "El almacén de destino recibió la mercancía; `has_discrepancy` indica diferencias.", "x-group": "Órdenes de transferencia", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "transfer.received" }, "data": { "$ref": "#/components/schemas/TransferOrder" } } } ] }, "example": { "event": "transfer.received", "version": 1, "data": { "object": "transfer_order", "id": 41, "code": "TR-000041", "status": "received", "status_label": "En tránsito", "headline": "CEDIS-GDL → TDA-MTY", "has_discrepancy": false, "from": { "id": 1, "code": "CEDIS-GDL", "name": "CEDIS Guadalajara" }, "to": { "id": 2, "code": "TDA-MTY", "name": "Tienda Monterrey" }, "priority": 50, "reason": "Reabasto semanal", "due_at": "2026-10-08T18:00:00-06:00", "lines_count": 1, "units": { "requested": 24, "picked": 24, "dispatched": 24, "received": 0 }, "dispatched_at": "2026-10-07T09:30:00-06:00", "received_at": null, "closed_at": null, "seal_number": "S-99812", "vehicle_plate": "JAL-123-A", "carrier_id": 3, "external_ref": "TR-2026-0107", "source": "api", "picking_id": 6120, "receipt_id": null, "sap": null, "lines": [ { "id": 77, "line_num": 0, "product_id": 101, "item_code": "P-1001", "qty": 24, "picked_qty": 24, "dispatched_qty": 24, "received_qty": 0, "batch_num": null, "serial_numbers": [], "status": "dispatched" } ] }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "shipment.dispatched": { "post": { "operationId": "onShipmentDispatched", "summary": "Embarque despachado", "description": "Un embarque salió del andén con su transportista, sello y paquetes.", "x-group": "Embarques", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "shipment.dispatched" }, "data": { "$ref": "#/components/schemas/ShipmentEvent" } } } ] }, "example": { "event": "shipment.dispatched", "version": 1, "data": { "object": "shipment", "id": 31, "code": "EMB-000031", "status": "dispatched", "status_label": "Despachado", "warehouse": { "id": 1, "code": "CEDIS-GDL", "name": "CEDIS Guadalajara" }, "carrier": { "id": 3, "code": "DHL", "name": "DHL Express" }, "vehicle_plate": "JAL-123-A", "seal_numbers": [ "S-99812" ], "dispatched_at": "2026-10-06T18:00:00-06:00" }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "return.received": { "post": { "operationId": "onReturnReceived", "summary": "Devolución recibida", "description": "Llegó mercancía devuelta por un cliente.", "x-group": "Devoluciones", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "return.received" }, "data": { "$ref": "#/components/schemas/ReturnEvent" } } } ] }, "example": { "event": "return.received", "version": 1, "data": { "object": "return_order", "id": 12, "code": "DEV-000012", "type": "customer", "status": "received", "status_label": "Recibida", "card_code": "CLI-001", "card_name": "Abarrotes del Norte", "rma_number": "RMA-5521", "units": { "expected": 6, "received": 6, "inspected": 0 } }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "return.dispositioned": { "post": { "operationId": "onReturnDispositioned", "summary": "Devolución con destino", "description": "Se decidió el destino de la mercancía devuelta (reacomodo, merma, proveedor).", "x-group": "Devoluciones", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "return.dispositioned" }, "data": { "$ref": "#/components/schemas/ReturnEvent" } } } ] }, "example": { "event": "return.dispositioned", "version": 1, "data": { "object": "return_order", "id": 12, "code": "DEV-000012", "type": "customer", "status": "dispositioned", "status_label": "Con destino", "card_code": "CLI-001", "card_name": "Abarrotes del Norte", "rma_number": "RMA-5521", "units": { "expected": 6, "received": 6, "inspected": 6 } }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "packing_order.transitioned": { "post": { "operationId": "onPackingOrderTransitioned", "summary": "Orden de empaque cambió de estado", "description": "Una orden de empaque pasó de un estado a otro (`from`, `to`).", "x-group": "Empaque", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "packing_order.transitioned" }, "data": { "$ref": "#/components/schemas/PackingOrderEvent" } } } ] }, "example": { "event": "packing_order.transitioned", "version": 1, "data": { "object": "packing_order", "id": 55, "code": "EMP-000055", "status": "packed", "step": "label", "doc_num": "OV-000977", "card_code": "CLI-001", "units_count": 6, "weight_kg": 7.2, "from": "packing", "to": "packed" }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "rfid_validation.completed": { "post": { "operationId": "onRfidValidationCompleted", "summary": "Validación RFID terminada", "description": "Terminó una lectura RFID contra un documento, con sus conteos.", "x-group": "RFID", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "rfid_validation.completed" }, "data": { "$ref": "#/components/schemas/RfidValidationEvent" } } } ] }, "example": { "event": "rfid_validation.completed", "version": 1, "data": { "object": "rfid_session", "code": "RFID-000201", "mode": "validation", "context": { "type": "picking", "code": "PKG-6120" }, "result": "matched", "counts": { "expected": 6, "matched": 6, "missing": 0, "unexpected": 0, "foreign": 0, "unknown": 0 }, "closed_at": "2026-10-06T12:10:02-06:00" }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "product.created": { "post": { "operationId": "onProductCreated", "summary": "Producto creado", "description": "Se dio de alta un producto (por la web, la API o una carga).", "x-group": "Catálogo", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "product.created" }, "data": { "$ref": "#/components/schemas/ProductEvent" } } } ] }, "example": { "event": "product.created", "version": 1, "data": { "id": 101, "item_code": "P-1001", "name": "Aceite comestible 1 L", "barcode": "7501234567890", "tracks_serials": false, "tracks_lots": true, "updated_at": "2026-10-06T10:20:11-06:00" }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "product.updated": { "post": { "operationId": "onProductUpdated", "summary": "Producto actualizado", "description": "Cambió un dato del producto.", "x-group": "Catálogo", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "product.updated" }, "data": { "$ref": "#/components/schemas/ProductEvent" } } } ] }, "example": { "event": "product.updated", "version": 1, "data": { "id": 101, "item_code": "P-1001", "name": "Aceite comestible 1 L (caja 12)", "barcode": "7501234567891", "tracks_serials": false, "tracks_lots": true, "updated_at": "2026-10-06T10:31:40-06:00" }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "stock.updated": { "post": { "operationId": "onStockUpdated", "summary": "Existencias actualizadas", "description": "Una transacción movió existencias. Llega un evento por transacción con los productos que tocó, con lo disponible y lo que hay a la mano en ese momento.", "x-group": "Existencias", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "stock.updated" }, "data": { "$ref": "#/components/schemas/StockEvent" } } } ] }, "example": { "event": "stock.updated", "version": 1, "data": { "products": [ { "id": 101, "item_code": "P-1001", "available": 46, "on_hand": 48 } ] }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "layout.published": { "post": { "operationId": "onLayoutPublished", "summary": "Mapa publicado", "description": "Se publicó una versión nueva del mapa de un almacén.", "x-group": "Mapas", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "layout.published" }, "data": { "$ref": "#/components/schemas/LayoutEvent" } } } ] }, "example": { "event": "layout.published", "version": 1, "data": { "warehouse_code": "CEDIS-GDL", "layout_version": 4, "published_at": "2026-10-06T09:00:00-06:00", "summary": { "added": 12, "relocated": 3, "removed": 0 } }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "wave.planned": { "post": { "operationId": "onWavePlanned", "summary": "Ola planeada", "description": "Se planeó una ola.", "x-group": "Olas", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "wave.planned" }, "data": { "$ref": "#/components/schemas/Wave" } } } ] }, "example": { "event": "wave.planned", "version": 1, "data": { "id": 9, "code": "OLA-000009", "warehouse_code": "CEDIS-GDL", "strategy": "batch", "status": "planned", "carrier_code": null, "cutoff_at": null, "released_at": null, "metrics": { "orders": 2, "lines": 3, "units": 18 }, "created_at": "2026-10-06T10:20:11-06:00", "updated_at": "2026-10-06T11:00:00-06:00" }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "wave.released": { "post": { "operationId": "onWaveReleased", "summary": "Ola liberada", "description": "Un supervisor liberó la ola al piso.", "x-group": "Olas", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "wave.released" }, "data": { "$ref": "#/components/schemas/Wave" } } } ] }, "example": { "event": "wave.released", "version": 1, "data": { "id": 9, "code": "OLA-000009", "warehouse_code": "CEDIS-GDL", "strategy": "batch", "status": "released", "carrier_code": null, "cutoff_at": null, "released_at": "2026-10-06T11:00:00-06:00", "metrics": { "orders": 2, "lines": 3, "units": 18 }, "created_at": "2026-10-06T10:20:11-06:00", "updated_at": "2026-10-06T11:00:00-06:00" }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "wave.completed": { "post": { "operationId": "onWaveCompleted", "summary": "Ola completada", "description": "Todos los pedidos de la ola se surtieron.", "x-group": "Olas", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "wave.completed" }, "data": { "$ref": "#/components/schemas/Wave" } } } ] }, "example": { "event": "wave.completed", "version": 1, "data": { "id": 9, "code": "OLA-000009", "warehouse_code": "CEDIS-GDL", "strategy": "batch", "status": "completed", "carrier_code": null, "cutoff_at": null, "released_at": "2026-10-06T11:00:00-06:00", "metrics": { "orders": 2, "lines": 3, "units": 18 }, "created_at": "2026-10-06T10:20:11-06:00", "updated_at": "2026-10-06T11:00:00-06:00" }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } }, "wave.cancelled": { "post": { "operationId": "onWaveCancelled", "summary": "Ola cancelada", "description": "La ola se canceló.", "x-group": "Olas", "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookDelivery" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "wave.cancelled" }, "data": { "$ref": "#/components/schemas/Wave" } } } ] }, "example": { "event": "wave.cancelled", "version": 1, "data": { "id": 9, "code": "OLA-000009", "warehouse_code": "CEDIS-GDL", "strategy": "batch", "status": "cancelled", "carrier_code": null, "cutoff_at": null, "released_at": null, "metrics": { "orders": 2, "lines": 3, "units": 18 }, "created_at": "2026-10-06T10:20:11-06:00", "updated_at": "2026-10-06T11:00:00-06:00" }, "timestamp": 1791302400 } } } }, "responses": { "200": { "description": "Recibido. Cualquier respuesta 2xx en menos de 15 segundos cuenta como entregado." } } } } }, "components": { "securitySchemes": { "clientCredentials": { "type": "oauth2", "description": "Cliente de integración (recomendado). Se crea en Configuración › Clientes API; el secreto se muestra una sola\nvez. Al solicitar el token se indican los alcances requeridos (`scope`, separados por espacios). El token\nactúa por la empresa, no por una persona: lo juzgan sus alcances.\n", "flows": { "clientCredentials": { "tokenUrl": "/oauth/token", "scopes": { "products:read": "Leer productos, categorías y cargas masivas.", "products:write": "Crear, cambiar y eliminar productos; subir y confirmar cargas masivas.", "stocks:read": "Leer existencias y niveles de existencia.", "warehouses:read": "Leer almacenes, ubicaciones y mapas.", "receipts:read": "Leer recepciones y documentos de entrada.", "receipts:write": "Crear documentos de entrada.", "pickings:read": "Leer surtidos, documentos de salida y olas.", "pickings:write": "Crear documentos de salida y planear olas.", "transfers:read": "Leer traspasos y órdenes de transferencia.", "transfers:write": "Crear órdenes de transferencia.", "clients:read": "Leer clientes.", "clients:write": "Crear, cambiar y eliminar clientes.", "providers:read": "Leer proveedores.", "providers:write": "Crear, cambiar y eliminar proveedores.", "webhooks:manage": "Administrar suscripciones a webhooks." } } } }, "userToken": { "type": "oauth2", "description": "Token de un usuario (grant `password`) emitido por un cliente OAuth de la empresa. La integración actúa como\nese usuario y hereda los permisos de su rol; las escrituras piden el permiso indicado en cada operación.\nSi el usuario tiene la verificación en dos pasos activa, el token solo llega a `GET /products`; las demás rutas\nresponden `403 client_not_allowed`. Lo mismo aplica a todo token de la aplicación móvil.\n", "flows": { "password": { "tokenUrl": "/oauth/token", "scopes": [] } } } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "description": "Identificador numérico del recurso.", "schema": { "type": "integer", "minimum": 1 }, "example": 101 }, "Page": { "name": "page", "in": "query", "description": "Número de página, desde 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPage": { "name": "per_page", "in": "query", "description": "Elementos por página, de 1 a 100. Un valor mayor se toma como 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "UpdatedSince": { "name": "updated_since", "in": "query", "description": "Solo lo que cambió desde esta fecha (ISO 8601), para sincronización incremental.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-06T00:00:00-06:00" }, "Search": { "name": "search", "in": "query", "description": "Parte del nombre.", "schema": { "type": "string", "maxLength": 100 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "Llave única por operación (se recomienda un UUID v4). Reenviar la misma solicitud con la misma llave en las\nsiguientes 24 horas devuelve la respuesta original sin repetir la operación.\n", "schema": { "type": "string", "maxLength": 255 }, "example": "6f1c7f1e-2b8a-4f43-9a0e-3c2f9b8f1d2a" }, "IdempotencyKeyRequired": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Obligatoria en esta ruta. Llave única por operación (UUID v4); los reintentos repiten la misma.", "schema": { "type": "string", "maxLength": 255 }, "example": "6f1c7f1e-2b8a-4f43-9a0e-3c2f9b8f1d2a" }, "WebhookSignature": { "name": "X-Chainlink-Signature", "in": "header", "required": true, "description": "`t=,v1=`: HMAC-SHA256 de `\".\"` con el secreto de la suscripción.", "schema": { "type": "string" }, "example": "t=1791302400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, "WebhookEvent": { "name": "X-Chainlink-Event", "in": "header", "required": true, "description": "El nombre del evento, igual a `event` en el cuerpo.", "schema": { "type": "string" }, "example": "receipt.completed" }, "WebhookDelivery": { "name": "X-Chainlink-Delivery", "in": "header", "required": true, "description": "Identificador de la entrega; se repite en cada reintento y permite descartar duplicados.", "schema": { "type": "string" }, "example": "48211" } }, "headers": { "RequestId": { "description": "Identificador de la solicitud. Inclúyelo al reportar un problema a soporte.", "schema": { "type": "string", "pattern": "^req_[0-9a-z]{26}$" }, "example": "req_01j9x2m4k7q8r5t6v3w0y1z2a3" }, "RateLimitLimit": { "description": "Solicitudes permitidas por minuto para la empresa.", "schema": { "type": "integer" }, "example": 300 }, "RateLimitRemaining": { "description": "Solicitudes que quedan en el minuto en curso.", "schema": { "type": "integer" }, "example": 297 }, "RetryAfter": { "description": "Segundos que hay que esperar antes de reintentar.", "schema": { "type": "integer" }, "example": 23 }, "Location": { "description": "URL del recurso creado.", "schema": { "type": "string", "format": "uri" }, "example": "https://demo.chainlink.mx/api/v1/products/101" }, "IdempotencyReplayed": { "description": "`true` cuando la respuesta es la guardada de una solicitud anterior con la misma `Idempotency-Key`.", "schema": { "type": "string", "enum": [ "true" ] } }, "ETag": { "description": "Versión del recurso; con `If-None-Match` la respuesta es `304` si no cambió.", "schema": { "type": "string" }, "example": "\"layout-1-v4\"" } }, "responses": { "Unauthorized": { "description": "Falta el token o no es válido.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthenticated", "message": "Falta el token de acceso o ya no es válido.", "doc_url": "https://chainlink.mx/developers/errores#unauthenticated", "request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3" }, "errors": [], "message": "Falta el token de acceso o ya no es válido." } } } }, "PaymentRequired": { "description": "La función no está en el plan de la empresa, o la cuenta está suspendida o cancelada.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "feature_not_in_plan", "message": "Función no disponible en tu plan actual.", "feature": "webhooks.enabled", "upgrade_url": "/billing/plans", "doc_url": "https://chainlink.mx/developers/errores#feature_not_in_plan", "request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3" }, "errors": [], "message": "Función no disponible en tu plan actual." } } } }, "Forbidden": { "description": "Al cliente le falta el alcance (`missing_scope`), al usuario el permiso (`forbidden`), o el token de usuario no\ntiene acceso a la ruta (`client_not_allowed`: aplicación móvil o usuario con verificación en dos pasos).\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "El cliente no tiene el alcance products:write.", "scope": "products:write", "doc_url": "https://chainlink.mx/developers/errores#missing_scope", "request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3" }, "errors": [], "message": "El cliente no tiene el alcance products:write." } } } }, "NotFound": { "description": "El recurso no existe.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "El recurso no existe.", "doc_url": "https://chainlink.mx/developers/errores#not_found", "request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3" }, "errors": [], "message": "El recurso no existe." } } } }, "ModuleDisabled": { "description": "El módulo no está activo en la empresa.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "transfer_orders_disabled", "message": "Las órdenes de transferencia no están activas en tu empresa.", "doc_url": "https://chainlink.mx/developers/errores#transfer_orders_disabled", "request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3" }, "errors": [], "message": "Las órdenes de transferencia no están activas en tu empresa." } } } }, "IdempotencyKeyRequired": { "description": "Falta la cabecera `Idempotency-Key`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "idempotency_key_required", "message": "Envía la cabecera Idempotency-Key.", "doc_url": "https://chainlink.mx/developers/errores#idempotency_key_required", "request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3" }, "errors": [], "message": "Envía la cabecera Idempotency-Key." } } } }, "IdempotencyConflict": { "description": "Otra solicitud con la misma `Idempotency-Key` sigue en proceso.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "duplicate_in_flight", "message": "Esta solicitud ya se está procesando.", "doc_url": "https://chainlink.mx/developers/errores#duplicate_in_flight", "request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3" }, "errors": [], "message": "Esta solicitud ya se está procesando." } } } }, "Conflict": { "description": "La solicitud choca con el estado actual (por ejemplo, un pedido ya está en otra ola).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "order_in_wave", "message": "El pedido OV-000977 ya está en la ola OLA-000008.", "doc_url": "https://chainlink.mx/developers/errores#order_in_wave", "request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3" }, "errors": [], "message": "El pedido OV-000977 ya está en la ola OLA-000008." } } } }, "PayloadTooLarge": { "description": "El archivo excede 5 MB.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationFailed": { "description": "Datos no válidos (`validation_failed`), una llave de idempotencia reutilizada con otra solicitud\n(`idempotency_key_reused`) o una regla de negocio que bloquea la operación (`rule_blocked`).\n", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "El campo name es obligatorio.", "field": "name", "doc_url": "https://chainlink.mx/developers/errores#validation_failed", "request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3" }, "errors": [ { "field": "name", "message": "El campo name es obligatorio." } ], "message": "El campo name es obligatorio." } } } }, "TooManyRequests": { "description": "Se superó el límite por minuto. Reintente después de los segundos de `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Superaste el límite de solicitudes por minuto. Espera los segundos que indica Retry-After.", "doc_url": "https://chainlink.mx/developers/errores#rate_limited", "request_id": "req_01j9x2m4k7q8r5t6v3w0y1z2a3" }, "errors": [], "message": "Superaste el límite de solicitudes por minuto. Espera los segundos que indica Retry-After." } } } } }, "schemas": { "ErrorCode": { "type": "string", "description": "Código estable del error. El catálogo completo está en /developers/errores.", "enum": [ "bad_request", "idempotency_key_required", "unauthenticated", "feature_not_in_plan", "limit_reached", "tenant_suspended", "tenant_cancelled", "forbidden", "missing_scope", "client_not_allowed", "not_found", "transfer_orders_disabled", "bulk_import_disabled", "method_not_allowed", "conflict", "duplicate_in_flight", "approval_required", "order_in_wave", "stale_state", "import_refused", "tenant_moved", "gone", "payload_too_large", "validation_failed", "idempotency_key_reused", "rule_blocked", "transfer_refused", "transfer_requires_two_warehouses", "no_candidates", "wave_refused", "installation_restricted", "locked", "rate_limited", "server_error", "tenant_moving", "service_unavailable" ] }, "Error": { "type": "object", "description": "El sobre de todo error de la API pública.", "required": [ "error", "errors", "message" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "doc_url", "request_id" ], "additionalProperties": true, "description": "El error principal. Según el código puede traer detalles: `scope` (missing_scope), `feature` y\n`upgrade_url` (feature_not_in_plan), `offer` (limit_reached), `rule` (rule_blocked) o `approval`\n(approval_required).\n", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", "description": "Mensaje en español para mostrar o registrar." }, "field": { "type": "string", "description": "El primer campo con error, en notación de puntos (`lines.0.qty`)." }, "doc_url": { "type": "string", "format": "uri", "description": "Enlace a la explicación del código." }, "request_id": { "type": "string", "pattern": "^req_[0-9a-z]{26}$", "description": "Igual a la cabecera `X-Request-Id`." } } }, "errors": { "type": "array", "description": "Un elemento por campo con error (vacío si el error no es de validación).", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": [ "string", "null" ] }, "message": { "type": "string" } } } }, "message": { "type": "string", "description": "Igual a `error.message`; se conserva por compatibilidad." } } }, "PaginationLinks": { "type": "object", "required": [ "first", "last", "prev", "next" ], "properties": { "first": { "type": [ "string", "null" ], "format": "uri" }, "last": { "type": [ "string", "null" ], "format": "uri" }, "prev": { "type": [ "string", "null" ], "format": "uri", "description": "Página anterior; `null` en la primera." }, "next": { "type": [ "string", "null" ], "format": "uri", "description": "Página siguiente; `null` en la última." } } }, "PaginationMeta": { "type": "object", "required": [ "current_page", "last_page", "per_page", "total" ], "properties": { "current_page": { "type": "integer" }, "from": { "type": [ "integer", "null" ], "description": "Posición del primer elemento de la página." }, "last_page": { "type": "integer" }, "links": { "type": "array", "description": "Enlaces de página para interfaces; no hace falta leerlos.", "items": { "type": "object" } }, "path": { "type": "string", "format": "uri" }, "per_page": { "type": "integer" }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "integer", "description": "Total de elementos con los filtros aplicados." } } }, "Timestamps": { "type": "object", "properties": { "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Operator": { "type": [ "object", "null" ], "description": "La persona que hizo el trabajo.", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "SourceDocument": { "type": [ "object", "null" ], "description": "El documento sobre el que se trabajó.", "required": [ "id", "type", "doc_num" ], "properties": { "id": { "type": "integer" }, "type": { "type": "string", "description": "Tipo interno del documento (`purchase_order`, `sale_order`, `transfer_order`…)." }, "doc_num": { "type": [ "string", "integer", "null" ] }, "card_code": { "type": [ "string", "null" ], "description": "Código del proveedor o del cliente." }, "external_ref": { "type": [ "string", "null" ], "description": "La referencia externa que envió el sistema de origen." } } }, "Product": { "title": "Producto", "type": "object", "required": [ "id", "item_code", "sku", "name" ], "properties": { "id": { "type": "integer" }, "item_code": { "type": "string", "description": "Código del producto en la instancia." }, "sku": { "type": "string", "description": "Igual a `item_code`." }, "name": { "type": "string" }, "barcode": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "man_btch_num": { "type": "boolean", "description": "Se maneja por lotes." }, "man_ser_num": { "type": "boolean", "description": "Se maneja por números de serie." }, "sales_unit": { "type": [ "string", "null" ] }, "purchase_unit": { "type": [ "string", "null" ] }, "inventory_item": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProductInput": { "type": "object", "required": [ "name" ], "description": "Requiere `item_code` (o su alias `sku`).", "properties": { "item_code": { "type": "string", "maxLength": 100 }, "sku": { "type": "string", "maxLength": 100, "description": "Alias de `item_code`." }, "name": { "type": "string", "maxLength": 255 }, "barcode": { "type": [ "string", "null" ], "maxLength": 255 }, "type": { "type": [ "string", "null" ], "maxLength": 50 }, "man_ser_num": { "type": [ "boolean", "null" ] }, "man_btch_num": { "type": [ "boolean", "null" ] }, "sales_unit": { "type": [ "string", "null" ], "maxLength": 20 }, "purchase_unit": { "type": [ "string", "null" ], "maxLength": 20 }, "inventory_item": { "type": [ "boolean", "null" ] } } }, "ProductUpdate": { "type": "object", "description": "Cualquier campo de `ProductInput`; ninguno es obligatorio.", "properties": { "item_code": { "type": "string", "maxLength": 100 }, "sku": { "type": "string", "maxLength": 100 }, "name": { "type": "string", "maxLength": 255 }, "barcode": { "type": [ "string", "null" ], "maxLength": 255 }, "type": { "type": [ "string", "null" ], "maxLength": 50 }, "man_ser_num": { "type": [ "boolean", "null" ] }, "man_btch_num": { "type": [ "boolean", "null" ] }, "sales_unit": { "type": [ "string", "null" ], "maxLength": 20 }, "purchase_unit": { "type": [ "string", "null" ], "maxLength": 20 }, "inventory_item": { "type": [ "boolean", "null" ] } } }, "ProductItem": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Product" } } }, "ProductList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "ProductCategory": { "title": "Categoría", "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProductCategoryList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCategory" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "Stock": { "title": "Fila de existencia", "type": "object", "required": [ "id", "product_id", "qty", "status" ], "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "product_name": { "type": [ "string", "null" ] }, "item_code": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "status": { "type": "string", "description": "`in` (en almacén) u `out` (salió)." }, "serial_number": { "type": [ "string", "null" ] }, "batch_num": { "type": [ "string", "null" ] }, "position": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "bin_code": { "type": [ "string", "null" ] }, "whs_code": { "type": [ "string", "null" ] }, "warehouse_id": { "type": [ "integer", "null" ] }, "warehouse_name": { "type": [ "string", "null" ] } } }, "expiry_date": { "type": [ "string", "null" ], "format": "date" }, "inventory_status": { "type": [ "string", "null" ], "enum": [ "available", "quarantine", "in_transit", "staged", "damaged", "blocked", null ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "StockList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Stock" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "StockLevel": { "title": "Nivel de existencia", "type": "object", "required": [ "product_id", "item_code", "on_hand", "available" ], "properties": { "product_id": { "type": "integer" }, "item_code": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "warehouse": { "type": [ "string", "null" ], "description": "El almacén pedido; `null` para el total de la empresa." }, "on_hand": { "type": "number", "description": "Todo lo que está en almacén." }, "available": { "type": "number", "description": "Lo que se puede prometer o surtir." } } }, "StockLevelList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StockLevel" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "Warehouse": { "title": "Almacén", "type": "object", "required": [ "id", "whs_code", "name" ], "properties": { "id": { "type": "integer" }, "whs_code": { "type": "string", "description": "Código del almacén; así lo nombran documentos, órdenes y olas." }, "name": { "type": "string" }, "site_code": { "type": [ "string", "null" ] }, "is_virtual": { "type": "boolean" }, "timezone": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "block": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "positions_count": { "type": "integer" }, "positions": { "type": "array", "description": "Solo en el detalle.", "items": { "$ref": "#/components/schemas/Position" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WarehouseList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Warehouse" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "WarehouseLayout": { "title": "Mapa del almacén", "type": "object", "required": [ "warehouse_code", "version" ], "additionalProperties": true, "description": "El mapa vigente; además de estos campos trae la geometría de pasillos, racks y ubicaciones.", "properties": { "warehouse_code": { "type": [ "string", "null" ] }, "version": { "type": "integer" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Position": { "title": "Ubicación", "type": "object", "required": [ "id", "warehouse_id", "bin_code" ], "properties": { "id": { "type": "integer" }, "warehouse_id": { "type": "integer" }, "whs_code": { "type": [ "string", "null" ] }, "bin_code": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "description": "Uso de la ubicación (`storage`, `pick_face`, `reserve`, `receiving`, `staging_out`, `dock`…)." }, "zone_id": { "type": [ "integer", "null" ] }, "aisle": { "type": [ "string", "null" ] }, "rack": { "type": [ "string", "null" ] }, "level": { "type": [ "string", "null" ] }, "slot": { "type": [ "string", "null" ] }, "pick_sequence": { "type": [ "integer", "null" ] }, "is_pickable": { "type": "boolean" }, "is_blocked": { "type": "boolean" }, "is_crossdock": { "type": "boolean" }, "disabled": { "type": "boolean" }, "capacity_units": { "type": [ "number", "null" ] }, "capacity_weight_kg": { "type": [ "number", "null" ] }, "capacity_volume_m3": { "type": [ "number", "null" ] }, "warehouse": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "whs_code": { "type": "string" }, "name": { "type": "string" } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PositionList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "WorkStatus": { "type": "string", "enum": [ "pending", "started", "finalized", "synchronized", "cancelled", "reverted" ], "description": "`pending` (por iniciar), `started`, `finalized` (terminado en el almacén), `synchronized` (enviado al ERP), `cancelled`, `reverted`." }, "WorkLine": { "type": "object", "required": [ "product_id", "item_code", "qty" ], "properties": { "product_id": { "type": "integer" }, "item_code": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "batch_num": { "type": [ "string", "null" ] }, "serials": { "type": "array", "items": { "type": "string" } } } }, "Receipt": { "title": "Recepción", "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "integer" }, "uuid": { "type": [ "string", "null" ] }, "concept": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/WorkStatus" }, "comments": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "operator": { "$ref": "#/components/schemas/Operator" }, "document": { "$ref": "#/components/schemas/SourceDocument" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finalized_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ReceiptDetail": { "allOf": [ { "$ref": "#/components/schemas/Receipt" }, { "type": "object", "required": [ "lines" ], "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/WorkLine" } } } } ] }, "ReceiptList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Receipt" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "Picking": { "title": "Surtido", "type": "object", "required": [ "id", "code", "status" ], "properties": { "id": { "type": "integer" }, "code": { "type": "string", "description": "`PKG-{id}`." }, "uuid": { "type": [ "string", "null" ] }, "concept": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/WorkStatus" }, "priority": { "type": [ "integer", "null" ] }, "has_shortage": { "type": "boolean", "description": "Se surtió con faltante." }, "comments": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "operator": { "$ref": "#/components/schemas/Operator" }, "document": { "$ref": "#/components/schemas/SourceDocument" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finalized_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PickingDetail": { "allOf": [ { "$ref": "#/components/schemas/Picking" }, { "type": "object", "required": [ "lines" ], "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/WorkLine" } } } } ] }, "PickingList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Picking" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "Transfer": { "title": "Traspaso", "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "transferred", "error" ], "description": "Igual a `wms_status`." }, "wms_status": { "type": "string" }, "sap_status": { "type": [ "string", "null" ], "description": "Estado del envío al ERP." }, "from_whs_code": { "type": [ "string", "null" ] }, "to_whs_code": { "type": [ "string", "null" ] }, "doc_entry": { "type": [ "integer", "string", "null" ], "description": "Número del documento en el ERP." }, "message": { "type": [ "string", "null" ], "description": "Respuesta del ERP cuando hubo error." }, "user_id": { "type": [ "integer", "null" ] }, "operator": { "$ref": "#/components/schemas/Operator" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TransferDetail": { "allOf": [ { "$ref": "#/components/schemas/Transfer" }, { "type": "object", "required": [ "lines" ], "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": [ "integer", "null" ] }, "item_code": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "from_position": { "type": [ "string", "null" ] }, "to_position": { "type": [ "string", "null" ] }, "batch": { "type": [ "string", "null" ] }, "serial": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } } } } } ] }, "TransferList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transfer" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "DocumentInputBase": { "type": "object", "required": [ "external_ref", "type", "doc_date", "partner_code", "warehouse_code", "lines" ], "properties": { "external_ref": { "type": "string", "maxLength": 100, "description": "Referencia externa (folio del ERP). Con el mismo `type`, no se crea dos veces." }, "type": { "type": "string", "maxLength": 40, "description": "Tipo de documento: la clave (`purchase_order`) o su nombre (`Orden de Compra`)." }, "doc_date": { "type": "string", "maxLength": 20, "description": "Fecha del documento: `AAAA-MM-DD` o `dd/mm/aaaa`." }, "due_date": { "type": [ "string", "null" ], "maxLength": 20 }, "partner_code": { "type": "string", "maxLength": 50, "description": "Código del proveedor o del cliente." }, "partner_name": { "type": [ "string", "null" ], "maxLength": 255 }, "warehouse_code": { "type": "string", "maxLength": 20 }, "comments": { "type": [ "string", "null" ], "maxLength": 2000 }, "lines": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "item_code", "qty" ], "properties": { "item_code": { "type": "string", "maxLength": 50 }, "qty": { "type": "number" }, "batch": { "type": [ "string", "null" ], "maxLength": 50, "description": "Lote (obligatorio si el producto se maneja por lotes al recibir)." }, "expiry_date": { "type": [ "string", "null" ], "maxLength": 20 }, "serials": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 191 } }, "destination_bin": { "type": [ "string", "null" ], "maxLength": 50, "description": "Ubicación destino (solo entradas)." } } } } } }, "EntryDocumentInput": { "allOf": [ { "$ref": "#/components/schemas/DocumentInputBase" } ] }, "ExitDocumentInput": { "allOf": [ { "$ref": "#/components/schemas/DocumentInputBase" }, { "type": "object", "properties": { "priority": { "type": [ "string", "null" ], "enum": [ "Alta", "Normal", "Baja", "alta", "normal", "baja", null ] }, "ship_to": { "type": [ "string", "null" ], "maxLength": 255 } } } ] }, "DocumentBase": { "type": "object", "required": [ "id", "doc_num", "type", "status", "lines" ], "properties": { "id": { "type": "integer" }, "doc_num": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "external_ref": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ], "description": "`api`, `import`, `web` o `sap`." }, "status": { "type": [ "string", "null" ] }, "card_code": { "type": [ "string", "null" ] }, "card_name": { "type": [ "string", "null" ] }, "doc_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "comments": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "EntryDocument": { "title": "Documento de entrada", "allOf": [ { "$ref": "#/components/schemas/DocumentBase" }, { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "required": [ "item_code", "qty", "open_qty", "received_qty" ], "properties": { "line_num": { "type": [ "integer", "null" ] }, "item_code": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "open_qty": { "type": "number", "description": "Lo que falta por recibir." }, "received_qty": { "type": "number" }, "whs_code": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } } } } } ] }, "ExitDocument": { "title": "Documento de salida", "allOf": [ { "$ref": "#/components/schemas/DocumentBase" }, { "type": "object", "properties": { "priority": { "type": [ "integer", "null" ] }, "ship_to": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "required": [ "item_code", "qty", "open_qty", "picked_qty" ], "properties": { "line_num": { "type": [ "integer", "null" ] }, "item_code": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "open_qty": { "type": "number", "description": "Lo que falta por surtir." }, "picked_qty": { "type": "number" }, "whs_code": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } } } } } ] }, "EntryDocumentItem": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EntryDocument" } } }, "ExitDocumentItem": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ExitDocument" } } }, "EntryDocumentList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntryDocument" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "ExitDocumentList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExitDocument" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "TransferOrderStatus": { "type": "string", "enum": [ "draft", "released", "picking", "picked", "in_transit", "receiving", "received", "closed", "cancelled" ] }, "WarehouseRef": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "TransferOrder": { "title": "Orden de transferencia", "type": "object", "required": [ "object", "id", "code", "status", "from", "to", "units" ], "properties": { "object": { "const": "transfer_order" }, "id": { "type": "integer" }, "code": { "type": "string" }, "status": { "$ref": "#/components/schemas/TransferOrderStatus" }, "status_label": { "type": "string" }, "headline": { "type": [ "string", "null" ] }, "has_discrepancy": { "type": "boolean", "description": "Lo recibido no coincide con lo despachado." }, "from": { "$ref": "#/components/schemas/WarehouseRef" }, "to": { "$ref": "#/components/schemas/WarehouseRef" }, "priority": { "type": "integer" }, "reason": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "lines_count": { "type": "integer" }, "units": { "type": "object", "properties": { "requested": { "type": "number" }, "picked": { "type": "number" }, "dispatched": { "type": "number" }, "received": { "type": "number" } } }, "dispatched_at": { "type": [ "string", "null" ], "format": "date-time" }, "received_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "seal_number": { "type": [ "string", "null" ] }, "vehicle_plate": { "type": [ "string", "null" ] }, "carrier_id": { "type": [ "integer", "null" ] }, "external_ref": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "web", "api", "import", "sap" ] }, "picking_id": { "type": [ "integer", "null" ] }, "receipt_id": { "type": [ "integer", "null" ] }, "sap": { "type": [ "object", "null" ], "description": "Estado del envío al ERP cuando aplica." }, "lines": { "type": [ "array", "null" ], "description": "`null` en el listado; en el detalle, las líneas.", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "line_num": { "type": "integer" }, "product_id": { "type": [ "integer", "null" ] }, "item_code": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "picked_qty": { "type": "number" }, "dispatched_qty": { "type": "number" }, "received_qty": { "type": "number" }, "batch_num": { "type": [ "string", "null" ] }, "serial_numbers": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } } } } } }, "TransferOrderInput": { "type": "object", "required": [ "from_warehouse", "to_warehouse", "lines" ], "properties": { "from_warehouse": { "type": "string", "maxLength": 20, "description": "Código del almacén de origen." }, "to_warehouse": { "type": "string", "maxLength": 20, "description": "Código del almacén de destino." }, "priority": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "reason": { "type": [ "string", "null" ], "maxLength": 255 }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_ref": { "type": [ "string", "null" ], "maxLength": 100, "description": "Referencia externa; no se crea dos veces." }, "release": { "type": [ "boolean", "null" ], "description": "`true` libera la orden para surtido al crearla." }, "picker_id": { "type": [ "integer", "null" ], "description": "El surtidor al liberar. Obligatorio con `release` y un cliente de integración." }, "lines": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "item_code", "qty" ], "properties": { "item_code": { "type": "string", "maxLength": 50 }, "qty": { "type": "number", "exclusiveMinimum": 0 }, "batch_num": { "type": [ "string", "null" ], "maxLength": 50 }, "expected_series": { "type": [ "array", "null" ], "items": { "type": "string" } }, "expected_batches": { "type": [ "array", "null" ], "items": { "type": "string" } } } } } } }, "TransferOrderItem": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TransferOrder" } } }, "TransferOrderList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransferOrder" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "WaveStatus": { "type": "string", "enum": [ "draft", "planned", "released", "in_progress", "picked", "completed", "closed", "cancelled" ] }, "Wave": { "title": "Ola", "type": "object", "required": [ "id", "code", "strategy", "status" ], "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "warehouse_code": { "type": [ "string", "null" ] }, "strategy": { "type": "string", "enum": [ "discrete", "by_customer", "batch", "cluster", "zone", "pick_and_pass" ] }, "status": { "$ref": "#/components/schemas/WaveStatus" }, "carrier_code": { "type": [ "string", "null" ] }, "cutoff_at": { "type": [ "string", "null" ], "format": "date-time" }, "released_at": { "type": [ "string", "null" ], "format": "date-time" }, "metrics": { "type": "object", "additionalProperties": true, "description": "Pedidos, líneas, unidades y avance de la ola." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "orders": { "type": "array", "description": "Solo en el detalle.", "items": { "type": "object", "required": [ "picking_id", "status" ], "properties": { "picking_id": { "type": "integer" }, "status": { "type": "string" } } } } } }, "WaveInput": { "type": "object", "required": [ "warehouse", "strategy" ], "description": "Requiere `picking_ids` o `filters`.", "properties": { "warehouse": { "type": "string", "maxLength": 20 }, "strategy": { "type": "string", "enum": [ "discrete", "by_customer", "batch", "cluster", "zone", "pick_and_pass" ] }, "picking_ids": { "type": "array", "maxItems": 2000, "items": { "type": "integer" } }, "filters": { "type": "object", "properties": { "carrier": { "type": [ "string", "null" ], "maxLength": 20 }, "customer": { "type": [ "string", "null" ], "maxLength": 50 }, "route": { "type": [ "string", "null" ], "maxLength": 50 }, "zone_id": { "type": [ "integer", "null" ] }, "min_priority": { "type": [ "integer", "null" ] }, "due_by": { "type": [ "string", "null" ], "format": "date" } } }, "cutoff_id": { "type": [ "integer", "null" ] }, "template_id": { "type": [ "integer", "null" ] } } }, "WaveItem": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Wave" } } }, "WaveList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wave" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "ImportInput": { "type": "object", "required": [ "kind", "file" ], "properties": { "kind": { "type": "string", "enum": [ "entry_documents", "exit_documents", "transfer_orders", "pick_faces", "products" ] }, "file": { "type": "string", "contentMediaType": "application/octet-stream", "description": "El archivo `.xlsx` o `.csv` con la plantilla de la web." }, "options[on_duplicate]": { "type": "string", "enum": [ "skip", "fail" ], "description": "Qué hacer con un documento que ya existe." }, "options[auto_allocate]": { "type": "boolean" } } }, "Import": { "title": "Carga masiva", "type": "object", "required": [ "id", "kind", "status", "rows", "documents" ], "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "status": { "type": "string", "enum": [ "uploaded", "validating", "validated", "invalid", "committing", "committed", "failed", "cancelled" ] }, "file": { "type": [ "string", "null" ] }, "rows": { "type": "object", "properties": { "total": { "type": [ "integer", "null" ] }, "valid": { "type": [ "integer", "null" ] }, "error": { "type": [ "integer", "null" ] } } }, "documents": { "type": "object", "properties": { "total": { "type": [ "integer", "null" ] }, "valid": { "type": [ "integer", "null" ] }, "committed": { "type": [ "integer", "null" ] } } }, "structure_errors": { "type": "array", "items": [] }, "error_report_url": { "type": [ "string", "null" ], "format": "uri", "description": "Excel con cada fila rechazada y su motivo." }, "committed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ImportItem": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Import" }, "warning": { "type": "string", "description": "Aviso cuando el mismo archivo ya se había subido." } } }, "Client": { "title": "Cliente", "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document_type": { "type": [ "string", "null" ], "description": "Tipo de documento fiscal (una letra)." }, "document_id": { "type": [ "integer", "null" ], "description": "Número de documento fiscal; único." }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ClientInput": { "type": "object", "required": [ "name", "document_id" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "document_type": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1 }, "document_id": { "type": "integer" }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 50 } } }, "ClientUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "document_type": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1 }, "document_id": { "type": "integer" }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 50 } } }, "ClientItem": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Client" } } }, "ClientList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "Provider": { "title": "Proveedor", "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "paymentinfo": { "type": [ "string", "null" ], "description": "Condiciones o datos de pago." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProviderInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 50 }, "paymentinfo": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "ProviderUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 50 }, "paymentinfo": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "ProviderItem": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Provider" } } }, "ProviderList": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "WebhookSubscription": { "title": "Suscripción a webhooks", "type": "object", "required": [ "id", "url", "events", "is_active", "failure_count" ], "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventName" } }, "is_active": { "type": "boolean", "description": "Se desactiva sola tras 10 entregas fallidas seguidas." }, "failure_count": { "type": "integer" }, "last_triggered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookSubscriptionItem": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } }, "WebhookSubscriptionInput": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500, "pattern": "^https://", "description": "URL pública con https:// que recibirá los eventos. Se rechazan direcciones privadas, locales, de enlace local, CGNAT, multicast y de metadatos de la nube (IPv4 e IPv6), también si el dominio resuelve a ellas." }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEventName" } }, "secret": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 255, "description": "Secreto de firma propio; si no se envía, se genera uno." } } }, "WebhookSubscriptionUpdate": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500, "pattern": "^https://", "description": "Las mismas reglas que al crear." }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEventName" } }, "is_active": { "type": "boolean" } } }, "WebhookEventName": { "type": "string", "enum": [ "receipt.created", "receipt.completed", "picking.created", "picking.completed", "transfer.created", "transfer.completed", "transfer.dispatched", "transfer.received", "shipment.dispatched", "return.received", "return.dispositioned", "packing_order.transitioned", "rfid_validation.completed", "product.created", "product.updated", "stock.updated", "layout.published", "wave.planned", "wave.released", "wave.completed", "wave.cancelled" ] }, "WebhookEnvelope": { "type": "object", "required": [ "event", "version", "data", "timestamp" ], "description": "El cuerpo de toda entrega de webhook.", "properties": { "event": { "$ref": "#/components/schemas/WebhookEventName" }, "version": { "type": "integer", "const": 1, "description": "Versión de la carga. Agregar campos es compatible; cambiar o quitar uno es versión 2." }, "data": { "type": "object", "description": "El recurso del evento." }, "timestamp": { "type": "integer", "description": "Momento del intento de entrega (Unix); es el `t` de la firma." } } }, "ReceiptEvent": { "type": "object", "required": [ "id", "status", "lines" ], "properties": { "id": { "type": "integer" }, "concept": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "document": { "type": [ "object", "null" ], "properties": { "type": { "type": [ "string", "null" ] }, "doc_num": { "type": [ "string", "integer", "null" ] } } }, "operator": { "$ref": "#/components/schemas/Operator" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finalized_at": { "type": [ "string", "null" ], "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "item_code": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "batch": { "type": [ "string", "null" ] }, "serials": { "type": "array", "items": { "type": "string" } } } } } } }, "PickingEvent": { "allOf": [ { "$ref": "#/components/schemas/ReceiptEvent" }, { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } } ] }, "TransferEvent": { "type": "object", "required": [ "id", "status", "lines" ], "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "from_whs_code": { "type": [ "string", "null" ] }, "to_whs_code": { "type": [ "string", "null" ] }, "operator": { "$ref": "#/components/schemas/Operator" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "item_code": { "type": [ "string", "null" ] }, "qty": { "type": "number" }, "from_position": { "type": [ "string", "null" ] }, "to_position": { "type": [ "string", "null" ] }, "batch": { "type": [ "string", "null" ] }, "serial": { "type": [ "string", "null" ] } } } } } }, "ShipmentEvent": { "type": "object", "required": [ "object", "id", "code", "status" ], "additionalProperties": true, "description": "El embarque con su almacén, andén, transportista, vehículo, sellos, paquetes y documentos.", "properties": { "object": { "const": "shipment" }, "id": { "type": "integer" }, "code": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "warehouse": { "$ref": "#/components/schemas/WarehouseRef" }, "carrier": { "type": [ "object", "null" ] }, "vehicle_plate": { "type": [ "string", "null" ] }, "seal_numbers": { "type": [ "array", "null" ], "items": { "type": "string" } }, "dispatched_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ReturnEvent": { "type": "object", "required": [ "object", "id", "code", "status" ], "additionalProperties": true, "description": "La devolución con su cliente, documento de origen, unidades, líneas e inspecciones.", "properties": { "object": { "const": "return_order" }, "id": { "type": "integer" }, "code": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "status_label": { "type": "string" }, "card_code": { "type": [ "string", "null" ] }, "card_name": { "type": [ "string", "null" ] }, "rma_number": { "type": [ "string", "null" ] }, "units": { "type": "object", "additionalProperties": { "type": "number" } } } }, "PackingOrderEvent": { "type": "object", "required": [ "object", "id", "code", "status", "from", "to" ], "additionalProperties": true, "description": "La orden de empaque con su estado anterior (`from`) y el nuevo (`to`).", "properties": { "object": { "const": "packing_order" }, "id": { "type": "integer" }, "code": { "type": "string" }, "status": { "type": "string" }, "step": { "type": [ "string", "null" ] }, "doc_num": { "type": [ "string", "null" ] }, "card_code": { "type": [ "string", "null" ] }, "units_count": { "type": [ "integer", "null" ] }, "weight_kg": { "type": [ "number", "null" ] }, "from": { "type": [ "string", "null" ] }, "to": { "type": "string" } } }, "RfidValidationEvent": { "type": "object", "required": [ "object", "code", "mode", "counts" ], "properties": { "object": { "const": "rfid_session" }, "code": { "type": "string" }, "mode": { "type": "string" }, "context": { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] } } }, "result": { "type": [ "string", "null" ] }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ProductEvent": { "type": "object", "required": [ "id", "item_code", "name" ], "properties": { "id": { "type": "integer" }, "item_code": { "type": "string" }, "name": { "type": "string" }, "barcode": { "type": [ "string", "null" ] }, "tracks_serials": { "type": "boolean" }, "tracks_lots": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "StockEvent": { "type": "object", "required": [ "products" ], "properties": { "products": { "type": "array", "items": { "type": "object", "required": [ "id", "item_code", "available", "on_hand" ], "properties": { "id": { "type": "integer" }, "item_code": { "type": "string" }, "available": { "type": "number" }, "on_hand": { "type": "number" } } } } } }, "LayoutEvent": { "type": "object", "required": [ "warehouse_code", "layout_version" ], "properties": { "warehouse_code": { "type": [ "string", "null" ] }, "layout_version": { "type": "integer" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "summary": { "type": "object", "properties": { "added": { "type": "integer" }, "relocated": { "type": "integer" }, "removed": { "type": "integer" } } } } } } } }