{ "openapi": "3.0.3", "info": { "title": "Istmo Commerce — API de integración", "version": "1.6.0", "description": "API Commerce para POS local y cloud-pos. Gateway saliente con cola durable, catálogo, solicitudes, cotizaciones y reservas. ACH/transferencia opt-in: instrucciones de pago y conciliación administrativa, emisión idempotente por el motor documental y registro de devoluciones ya realizadas para pagos sin factura. Sin cobros automáticos, tarjeta ni Yappy web. Las API keys de tienda nunca autorizan conciliación o emisión. Documentación no activa conectividad ni migra instalaciones. Administración operativa ACH desde Tienda online, búsqueda de receptor y preparación/retiro auditados. Estado fulfillment disponible mediante status en POS/gateway. Webhooks firmados con outbox local y cola durable en gateway. Consulta/reintento sólo en gateway." }, "servers": [ { "url": "http://127.0.0.1:4000/api/v1/commerce", "description": "Desarrollo/QA local solamente. No accesible desde Vercel." }, { "url": "https://{posHost}/api/v1/commerce", "description": "Servidor operativo cloud-pos o gateway Commerce configurado con HTTPS. /admin sólo existe en POS; gateway sirve catálogo y pedidos. Sustituir dominio de ejemplo.", "variables": { "posHost": { "default": "pos.example.com" } } } ], "tags": [ { "name": "Tienda", "description": "Servidor de la tienda con credencial dedicada; nunca el navegador." }, { "name": "Administración", "description": "Usuario administrativo autenticado, permiso vigente admin.configuracion y pertenencia a la sucursal." } ], "paths": { "/catalog": { "get": { "operationId": "getCatalog", "summary": "Consultar catálogo autorizado", "tags": [ "Tienda" ], "description": "Catálogo publicado de referencia. Cotizar y reservar mediante checkout-commands; disponibilidad y precios deben confirmarse en POS.", "security": [ { "CommerceKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/after" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Operación correcta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Catalog" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Petición inválida o producto no publicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credencial ausente, inválida, revocada o expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permisos/scopes/licencia/contexto insuficientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso no encontrado en el contexto autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referencia reutilizada con otro contenido o estado incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite por IP/proceso excedido (240 solicitudes/minuto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno; al reintentar un pedido conservar externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Gateway sin catálogo sincronizado, servicio pausado o temporalmente no disponible." } }, "x-required-scope": "catalog:read" } }, "/orders": { "post": { "operationId": "createOrderRequest", "summary": "Registrar solicitud de pedido", "tags": [ "Tienda" ], "description": "externalId es la clave idempotente por integración y se conserva mientras exista el pedido. Mismo contenido devuelve el mismo ID; contenido diferente devuelve 409. Cantidades decimales equivalentes y orden de líneas no cambian la identidad. No acepta precios, totales ni afirmaciones de pago. No reserva inventario, cobra o factura. Los reintentos consultan el estado actual, incluso si fue rechazado.", "security": [ { "CommerceKey": [] } ], "parameters": [], "responses": { "202": { "description": "Solicitud persistida pendiente de confirmación. No es una venta ni autorización de cobro.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OrderReceipt" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Petición inválida o producto no publicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credencial ausente, inválida, revocada o expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permisos/scopes/licencia/contexto insuficientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso no encontrado en el contexto autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referencia reutilizada con otro contenido o estado incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite por IP/proceso excedido (240 solicitudes/minuto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno; al reintentar un pedido conservar externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Gateway sin catálogo sincronizado, servicio pausado o temporalmente no disponible." } }, "x-required-scope": "orders:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderInput" } } } } } }, "/orders/{externalId}": { "get": { "operationId": "getOrderRequest", "summary": "Consultar estado de una solicitud", "tags": [ "Tienda" ], "description": "Sólo solicitudes de la integración autenticada. No exponer esta consulta públicamente sin comprobar propiedad del comprador en el backend de la tienda.", "security": [ { "CommerceKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/externalId" } ], "responses": { "200": { "description": "Operación correcta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OrderReceipt" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Petición inválida o producto no publicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credencial ausente, inválida, revocada o expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permisos/scopes/licencia/contexto insuficientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso no encontrado en el contexto autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referencia reutilizada con otro contenido o estado incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite por IP/proceso excedido (240 solicitudes/minuto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno; al reintentar un pedido conservar externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Gateway sin catálogo sincronizado, servicio pausado o temporalmente no disponible." } }, "x-required-scope": "orders:read" } }, "/admin/integrations": { "post": { "operationId": "createIntegration", "summary": "Crear conexión de tienda", "tags": [ "Administración" ], "description": "Empresa y sucursal se derivan del JWT y permisos vigentes de BD. No se aceptan desde el body. Requiere admin.configuracion o rol superadmin vigente, licencia POS/facturación y almacén autorizado. La creación no es idempotente: ante respuesta perdida listar antes de repetir; una clave perdida se rota.", "security": [ { "AdminBearer": [] } ], "parameters": [], "responses": { "201": { "description": "Operación correcta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/IntegrationCreated" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Petición inválida o producto no publicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credencial ausente, inválida, revocada o expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permisos/scopes/licencia/contexto insuficientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso no encontrado en el contexto autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referencia reutilizada con otro contenido o estado incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite por IP/proceso excedido (240 solicitudes/minuto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno; al reintentar un pedido conservar externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationInput" } } } } }, "get": { "operationId": "listIntegrations", "summary": "Listar conexiones de la sucursal", "tags": [ "Administración" ], "description": "", "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/after" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Operación correcta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/IntegrationsPage" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Petición inválida o producto no publicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credencial ausente, inválida, revocada o expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permisos/scopes/licencia/contexto insuficientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso no encontrado en el contexto autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referencia reutilizada con otro contenido o estado incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite por IP/proceso excedido (240 solicitudes/minuto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno; al reintentar un pedido conservar externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/integrations/{id}/rotate": { "post": { "operationId": "rotateIntegrationCredential", "summary": "Rotar credencial", "tags": [ "Administración" ], "description": "Invalida la anterior. Devuelve el secreto una sola vez; si se pierde la respuesta volver a rotar. No reactiva integraciones revocadas.", "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Operación correcta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Credential" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Petición inválida o producto no publicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credencial ausente, inválida, revocada o expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permisos/scopes/licencia/contexto insuficientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso no encontrado en el contexto autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referencia reutilizada con otro contenido o estado incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite por IP/proceso excedido (240 solicitudes/minuto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno; al reintentar un pedido conservar externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/integrations/{id}": { "delete": { "operationId": "revokeIntegration", "summary": "Revocar conexión", "tags": [ "Administración" ], "description": "Revocación lógica irreversible, idempotente. Preserva pedidos e historial. Operaciones que ya adquirieron el bloqueo pueden terminar antes de la revocación.", "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Operación correcta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Revoked" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Petición inválida o producto no publicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credencial ausente, inválida, revocada o expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permisos/scopes/licencia/contexto insuficientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso no encontrado en el contexto autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referencia reutilizada con otro contenido o estado incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite por IP/proceso excedido (240 solicitudes/minuto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno; al reintentar un pedido conservar externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/integrations/{id}/products": { "put": { "operationId": "replacePublishedProducts", "summary": "Reemplazar productos publicados", "tags": [ "Administración" ], "description": "Selección atómica por integración, máximo 200 productos simples activos. No cambia productos ni precios del POS. No publica automáticamente todo el inventario.", "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Operación correcta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PublicationResult" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Petición inválida o producto no publicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credencial ausente, inválida, revocada o expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permisos/scopes/licencia/contexto insuficientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso no encontrado en el contexto autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referencia reutilizada con otro contenido o estado incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite por IP/proceso excedido (240 solicitudes/minuto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno; al reintentar un pedido conservar externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationInput" } } } } }, "get": { "operationId": "searchCommerceProducts", "summary": "Buscar productos elegibles para publicar", "tags": [ "Administración" ], "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 100, "default": "" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operación completada; guardar no confirma conectividad.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CommerceProducts" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada inválida" }, "403": { "description": "Permisos insuficientes" }, "404": { "description": "Integración no encontrada" }, "409": { "description": "Vínculo inmutable o administrado por entorno" }, "503": { "description": "Cifrado no disponible" } } } }, "/admin/integrations/{id}/orders": { "get": { "operationId": "listOrderRequests", "summary": "Consultar bandeja de solicitudes", "tags": [ "Administración" ], "description": "Incluye datos personales y snapshot; acceso administrativo, no usar desde Vue público.", "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/after" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Operación correcta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OrdersPage" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Petición inválida o producto no publicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credencial ausente, inválida, revocada o expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permisos/scopes/licencia/contexto insuficientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso no encontrado en el contexto autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referencia reutilizada con otro contenido o estado incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite por IP/proceso excedido (240 solicitudes/minuto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno; al reintentar un pedido conservar externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/integrations/{id}/orders/{orderId}/reject": { "post": { "operationId": "rejectOrderRequest", "summary": "Rechazar solicitud con motivo", "tags": [ "Administración" ], "description": "Mismo motivo es idempotente; otro motivo después del rechazo devuelve 409. No anula documentos fiscales ni devuelve dinero.", "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/orderId" } ], "responses": { "200": { "description": "Operación correcta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/OrderReceipt" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Petición inválida o producto no publicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credencial ausente, inválida, revocada o expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permisos/scopes/licencia/contexto insuficientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso no encontrado en el contexto autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referencia reutilizada con otro contenido o estado incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite por IP/proceso excedido (240 solicitudes/minuto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error interno; al reintentar un pedido conservar externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectInput" } } } } } }, "/admin/options": { "get": { "operationId": "getCommerceOptions", "summary": "Consultar almacenes y requisitos del puente", "tags": [ "Administración" ], "security": [ { "AdminBearer": [] } ], "parameters": [], "responses": { "200": { "description": "Operación completada; guardar no confirma conectividad.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CommerceOptions" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada inválida" }, "403": { "description": "Permisos insuficientes" }, "404": { "description": "Integración no encontrada" }, "409": { "description": "Vínculo inmutable o administrado por entorno" }, "503": { "description": "Cifrado no disponible" } } } }, "/admin/integrations/{id}/settings": { "get": { "operationId": "getCommerceSettings", "summary": "Consultar publicación y diagnóstico sin secretos", "tags": [ "Administración" ], "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Operación completada; guardar no confirma conectividad.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CommerceSettings" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada inválida" }, "403": { "description": "Permisos insuficientes" }, "404": { "description": "Integración no encontrada" }, "409": { "description": "Vínculo inmutable o administrado por entorno" }, "503": { "description": "Cifrado no disponible" } } } }, "/admin/integrations/{id}/bridge": { "put": { "operationId": "saveCommerceBridge", "summary": "Guardar y activar vínculo cifrado", "tags": [ "Administración" ], "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Operación completada; guardar no confirma conectividad.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CommerceBridgeResult" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada inválida" }, "403": { "description": "Permisos insuficientes" }, "404": { "description": "Integración no encontrada" }, "409": { "description": "Vínculo inmutable o administrado por entorno" }, "503": { "description": "Cifrado no disponible" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceBridgeInput" } } } } }, "delete": { "operationId": "pauseCommerceBridge", "summary": "Solicitar pausa del puente", "tags": [ "Administración" ], "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "Operación completada; guardar no confirma conectividad.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CommerceBridgeResult" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada inválida" }, "403": { "description": "Permisos insuficientes" }, "404": { "description": "Integración no encontrada" }, "409": { "description": "Vínculo inmutable o administrado por entorno" }, "503": { "description": "Cifrado no disponible" } } } }, "/checkout-commands": { "post": { "operationId": "submitCheckoutCommand", "summary": "Cotizar, reservar, solicitar transferencia, consultar o cancelar", "tags": [ "Tienda" ], "security": [ { "CommerceKey": [] } ], "parameters": [], "description": "quote/payment/cancel requieren orders:write; status requiere orders:read. quote/payment nuevos requieren gateway sincronizado en últimos 45s y llegada al POS antes de 60s. payment requiere configuración ACH y reserva vigente; reintentos recuperan la intención original. Las API keys de tienda no confirman pagos ni facturas. cancel rechaza pagos conciliados: resolución administrativa. Reserva de 5 minutos.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCommand" } } } }, "responses": { "202": { "description": "Recibo de operación; no confirma venta ni pago.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CheckoutCommandResult" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada inválida" }, "401": { "description": "Credencial inválida" }, "403": { "description": "Scope o licencia" }, "404": { "description": "Operación no encontrada" }, "409": { "description": "commandId reutilizado con contenido diferente" }, "503": { "description": "POS desconectado o servicio no disponible" } } } }, "/checkout-commands/{commandId}": { "get": { "operationId": "getCheckoutCommandResult", "summary": "Recuperar recibo histórico de operación", "tags": [ "Tienda" ], "security": [ { "CommerceKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/commandId" } ], "responses": { "200": { "description": "Recibo de operación; no confirma venta ni pago.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CheckoutCommandResult" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada inválida" }, "401": { "description": "Credencial inválida" }, "403": { "description": "Scope o licencia" }, "404": { "description": "Operación no encontrada" }, "409": { "description": "commandId reutilizado con contenido diferente" }, "503": { "description": "POS desconectado o servicio no disponible" } } } }, "/admin/integrations/{id}/payment-settings": { "put": { "operationId": "configureTransfer", "summary": "Configurar ACH/transferencia", "tags": [ "Administración" ], "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" } ], "description": "Requiere admin.configuracion vigente. Opt-in por integración. Instrumento ACH/TRANSFERENCIA activo USD. instructions se publica al solicitar payment; nunca incluir credenciales bancarias. Consultar configuración en GET settings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferSettings" } } } }, "responses": { "200": { "description": "Resultado persistido en el POS; consulte estado actual ante respuesta incierta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TransferSettings" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada o configuración incompatible" }, "401": { "description": "Sesión requerida" }, "403": { "description": "Permiso o licencia" }, "404": { "description": "Fuera del ámbito autorizado" }, "409": { "description": "Conflicto de importe, referencia, stock, conciliación o emisión" } } } }, "/admin/integrations/{id}/checkouts": { "get": { "operationId": "listCheckouts", "summary": "Listar cotizaciones y pagos", "tags": [ "Administración" ], "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "description": "Requiere admin.configuracion. Paginación limit 1–100 y after UUID. Sólo esta empresa/sucursal. confirmed sin invoice significa pago recibido pendiente de resolver, nunca pedir otro cobro.", "responses": { "200": { "description": "Resultado persistido en el POS; consulte estado actual ante respuesta incierta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AdminCheckouts" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada o configuración incompatible" }, "401": { "description": "Sesión requerida" }, "403": { "description": "Permiso o licencia" }, "404": { "description": "Fuera del ámbito autorizado" }, "409": { "description": "Conflicto de importe, referencia, stock, conciliación o emisión" } } } }, "/admin/integrations/{id}/checkouts/{checkoutId}/confirm-transfer": { "post": { "operationId": "confirmTransfer", "summary": "Conciliar transferencia recibida", "tags": [ "Administración" ], "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/checkoutId" } ], "description": "Requiere admin.configuracion + admin.bancos vigentes. El administrador verifica el banco antes de enviar. Monto exacto, referencia normalizada a mayúsculas única por empresa dentro de Commerce y motivo auditado. Idempotente con mismo cuerpo; no registra abono bancario contable ni emite factura. No aceptar esta declaración del comprador.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferConfirmation" } } } }, "responses": { "200": { "description": "Resultado persistido en el POS; consulte estado actual ante respuesta incierta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TransferResult" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada o configuración incompatible" }, "401": { "description": "Sesión requerida" }, "403": { "description": "Permiso o licencia" }, "404": { "description": "Fuera del ámbito autorizado" }, "409": { "description": "Conflicto de importe, referencia, stock, conciliación o emisión" } } } }, "/admin/integrations/{id}/checkouts/{checkoutId}/invoice": { "post": { "operationId": "invoiceTransfer", "summary": "Emitir venta desde pago conciliado", "tags": [ "Administración" ], "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/checkoutId" } ], "description": "Requiere admin.configuracion + pos.documentos, licencia y capacidad de facturación. Consumidor final 02 existente. Reutiliza motor documental, precios/permisos y FE. Stock/reserva/factura/pago atómicos, sin estación/turno. Si reserva expiró, comprueba stock disponible; falta de stock o cambio de precio conserva pago confirmado sin factura. Repetir devuelve factura original; no vuelve a cobrar. No garantiza aceptación PAC: revisar fiscalStatus y flujo fiscal administrativo.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferInvoiceInput" } } } }, "responses": { "201": { "description": "Resultado persistido en el POS; consulte estado actual ante respuesta incierta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TransferResult" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada o configuración incompatible" }, "401": { "description": "Sesión requerida" }, "403": { "description": "Permiso o licencia" }, "404": { "description": "Fuera del ámbito autorizado" }, "409": { "description": "Conflicto de importe, referencia, stock, conciliación o emisión" } } } }, "/admin/integrations/{id}/checkouts/{checkoutId}/record-refund": { "post": { "operationId": "recordTransferRefund", "summary": "Registrar devolución bancaria realizada", "tags": [ "Administración" ], "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/checkoutId" } ], "description": "Requiere admin.configuracion + admin.bancos. Sólo pago confirmado sin factura. Registra importe completo, referencia de devolución y motivo verificados; no mueve dinero ni emite nota de crédito. Repetir mismo cuerpo es idempotente; bloquea emisión posterior y libera reserva. Si existe factura usar flujo documental de anulación/nota de crédito.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferConfirmation" } } } }, "responses": { "200": { "description": "Resultado persistido en el POS; consulte estado actual ante respuesta incierta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TransferResult" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada o configuración incompatible" }, "401": { "description": "Sesión requerida" }, "403": { "description": "Permiso o licencia" }, "404": { "description": "Fuera del ámbito autorizado" }, "409": { "description": "Conflicto de importe, referencia, stock, conciliación o emisión" } } } }, "/admin/integrations/{id}/customers": { "get": { "operationId": "searchCommerceCustomers", "summary": "Buscar cliente para emitir factura", "tags": [ "Administración" ], "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 100, "default": "" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "description": "Requiere admin.configuracion. Hasta 50 clientes activos consumidor final 02 de la empresa, por nombre/código/RUC. nextCursor permite continuar; no crea clientes ni elige automáticamente al comprador.", "responses": { "200": { "description": "Resultado de la operación.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CommerceCustomers" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada inválida" }, "401": { "description": "Sesión requerida" }, "403": { "description": "Permiso vigente o licencia" }, "404": { "description": "Fuera del ámbito autorizado" }, "409": { "description": "Factura requerida/anulada, comprobante fiscal pendiente, comando reutilizado o transición incompatible" } } } }, "/admin/integrations/{id}/checkouts/{checkoutId}/fulfillment": { "post": { "operationId": "updateCommerceFulfillment", "summary": "Avanzar preparación y retiro", "tags": [ "Administración" ], "security": [ { "AdminBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/checkoutId" } ], "description": "Requiere admin.configuracion y pos.documentos vigentes. Sólo pago aplicado y factura no anulada. Secuencia pendiente → preparando → listo → entregado, sin saltos ni retrocesos. commandId UUID estable por transición: mismo cuerpo devuelve recibo histórico y otro cuerpo genera 409. entregado requiere receivedBy y comprobante fiscal disponible si FE está activa (mismo criterio del recibo fiscal, incluida contingencia firmada). Actor/nota/receptor se auditan localmente; no se publican. Para estado actual, comando status nuevo vía POS o gateway.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentInput" } } } }, "responses": { "200": { "description": "Resultado de la operación.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CommerceFulfillment" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Entrada inválida" }, "401": { "description": "Sesión requerida" }, "403": { "description": "Permiso vigente o licencia" }, "404": { "description": "Fuera del ámbito autorizado" }, "409": { "description": "Factura requerida/anulada, comprobante fiscal pendiente, comando reutilizado o transición incompatible" } } } }, "/webhook-deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "Consultar entregas webhook (gateway)", "tags": [ "Tienda" ], "description": "Sólo gateway, no POS directo. Paginación UUID para inspección, no cursor incremental. Evento sin PII: consultar estado actual con un nuevo comando status. No devuelve destino ni secreto.", "x-availability": "gateway", "x-required-scope": "orders:read", "security": [ { "CommerceKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/after" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Operación correcta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "items", "nextCursor" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Petición inválida o producto no publicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credencial ausente, inválida, revocada o expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permisos/scopes/licencia/contexto insuficientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso no encontrado en el contexto autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referencia reutilizada con otro contenido o estado incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite gateway: 600 solicitudes/minuto por IP/proceso." }, "500": { "description": "Error interno; al reintentar un pedido conservar externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Gateway sin catálogo sincronizado, servicio pausado o temporalmente no disponible." } } } }, "/webhook-deliveries/{eventId}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Reintentar entrega fallida (gateway)", "tags": [ "Tienda" ], "description": "Sólo gateway. Reactiva failed/disabled con destino actualmente configurado y contador cero. Pending/retry/processing no se duplican; La respuesta conserva el estado actual de trabajos activos. Delivered devuelve 409. Requiere webhook habilitado. Sin body.", "x-availability": "gateway", "x-required-scope": "orders:write", "security": [ { "CommerceKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/eventId" } ], "responses": { "200": { "description": "Operación correcta.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "retry", "processing" ] } }, "required": [ "id", "status" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Petición inválida o producto no publicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Credencial ausente, inválida, revocada o expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permisos/scopes/licencia/contexto insuficientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso no encontrado en el contexto autorizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referencia reutilizada con otro contenido o estado incompatible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Límite gateway: 600 solicitudes/minuto por IP/proceso." }, "500": { "description": "Error interno; al reintentar un pedido conservar externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Gateway sin catálogo sincronizado, servicio pausado o temporalmente no disponible." } } } } }, "components": { "securitySchemes": { "CommerceKey": { "type": "apiKey", "in": "header", "name": "x-istmo-commerce-key", "description": "Secreto del backend. Permisos definidos al crear la integración." }, "AdminBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "parameters": { "id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." }, "orderId": { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "externalId": { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,99}$", "description": "Referencia estable única por integración. Conservar exactamente en reintentos, incluso tras un timeout." } }, "after": { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "nextCursor previo. Orden UUID ascendente; no es un cursor de sincronización incremental." }, "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "commandId": { "name": "commandId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "checkoutId": { "name": "checkoutId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID POS del checkout, distinto de la referencia externa usada en los comandos." }, "eventId": { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "schemas": { "Error": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, "IntegrationInput": { "type": "object", "additionalProperties": false, "properties": { "nombre": { "type": "string", "minLength": 1, "maxLength": 100 }, "sitioUrl": { "type": "string", "format": "uri", "maxLength": 500, "pattern": "^https://", "description": "URL HTTPS sin credenciales, query ni fragmento. Informativa; no se usa para autenticación ni llamadas salientes." }, "almacenId": { "type": "string", "format": "uuid" }, "numeroLista": { "type": "integer", "minimum": 1, "maximum": 3, "default": 1 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "catalog:read", "orders:write", "orders:read" ] }, "minItems": 1, "maxItems": 3, "uniqueItems": true } }, "required": [ "nombre", "sitioUrl", "almacenId", "scopes" ] }, "Integration": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "empresaId": { "type": "string", "format": "uuid" }, "sucursalId": { "type": "string", "format": "uuid" }, "almacenId": { "type": "string", "format": "uuid" }, "nombre": { "type": "string" }, "sitioUrl": { "type": "string", "format": "uri" }, "numeroLista": { "type": "integer" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "catalog:read", "orders:write", "orders:read" ] }, "minItems": 1, "maxItems": 3, "uniqueItems": true }, "activo": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "empresaId", "sucursalId", "almacenId", "nombre", "sitioUrl", "numeroLista", "scopes", "activo", "createdAt", "updatedAt" ] }, "PublicationInput": { "type": "object", "additionalProperties": false, "properties": { "productoIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 200, "uniqueItems": true, "description": "Reemplaza toda la selección. [] despublica todo. Sólo productos simples activos con precio USD." } }, "required": [ "productoIds" ] }, "PublicationResult": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "productoIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "id", "productoIds" ] }, "Credential": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "credential": { "type": "string", "pattern": "^istmo_com_[a-f0-9]{64}$", "description": "Se entrega una sola vez. Guardar exclusivamente como secreto del backend." } }, "required": [ "id", "credential" ] }, "Revoked": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "activo": { "type": "boolean", "enum": [ false ] } }, "required": [ "id", "activo" ] }, "Product": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "unitPriceReference": { "type": "string", "pattern": "^\\d+\\.\\d{4}$", "description": "Precio de la lista; referencia, no cotización fiscal ni total a cobrar. No calcular impuestos o confirmar cobros a partir de este campo." }, "currency": { "type": "string", "enum": [ "USD" ] }, "availableReference": { "type": "string", "pattern": "^\\d+\\.\\d{4}$", "description": "max(0, existencia-reservada) del almacén autorizado. No garantiza disponibilidad ni reserva." }, "stockUpdatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "sku", "name", "description", "unitPriceReference", "currency", "availableReference", "stockUpdatedAt" ] }, "OrderInput": { "type": "object", "additionalProperties": false, "properties": { "externalId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,99}$", "description": "Referencia estable única por integración. Conservar exactamente en reintentos, incluso tras un timeout." }, "customer": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 150 }, "email": { "type": "string", "format": "email", "maxLength": 150 }, "phone": { "type": "string", "minLength": 5, "maxLength": 40 } }, "required": [ "name", "email", "phone" ] }, "fulfillment": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "method": { "type": "string", "enum": [ "pickup" ] } }, "required": [ "method" ] }, { "type": "object", "additionalProperties": false, "properties": { "method": { "type": "string", "enum": [ "delivery" ] }, "address": { "type": "string", "minLength": 5, "maxLength": 500 } }, "required": [ "method", "address" ] } ], "discriminator": { "propertyName": "method" } }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "productId": { "type": "string", "format": "uuid" }, "quantity": { "type": "string", "pattern": "^(?:0|[1-9]\\d{0,5})(?:\\.\\d{1,4})?$", "description": "Decimal como texto > 0, hasta 999999.9999. No repetir productId." } }, "required": [ "productId", "quantity" ] }, "minItems": 1, "maxItems": 100 }, "note": { "type": "string", "maxLength": 500, "default": "" } }, "required": [ "externalId", "customer", "fulfillment", "lines" ] }, "OrderReceipt": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "externalId": { "type": "string" }, "status": { "type": "string", "enum": [ "recibido_gateway", "pendiente_confirmacion", "rechazado" ] }, "reason": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "paymentStatus": { "type": "string", "enum": [ "not_requested" ] }, "stockReserved": { "type": "boolean", "enum": [ false ] }, "invoiced": { "type": "boolean", "enum": [ false ] }, "posOrderId": { "type": "string", "format": "uuid", "nullable": true, "description": "Sólo gateway. Recibo local, o null mientras no existe. El id principal del gateway permanece estable." } }, "required": [ "id", "externalId", "status", "reason", "createdAt", "updatedAt", "paymentStatus", "stockReserved", "invoiced" ] }, "RejectInput": { "type": "object", "additionalProperties": false, "properties": { "motivo": { "type": "string", "minLength": 5, "maxLength": 500 } }, "required": [ "motivo" ] }, "Snapshot": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "checkoutEnabled": { "type": "boolean", "enum": [ false ] } }, "required": [ "currency", "products", "checkoutEnabled" ] }, "IntegrationCreated": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "empresaId": { "type": "string", "format": "uuid" }, "sucursalId": { "type": "string", "format": "uuid" }, "almacenId": { "type": "string", "format": "uuid" }, "nombre": { "type": "string" }, "sitioUrl": { "type": "string", "format": "uri" }, "numeroLista": { "type": "integer" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "catalog:read", "orders:write", "orders:read" ] }, "minItems": 1, "maxItems": 3, "uniqueItems": true }, "activo": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "credential": { "type": "string", "pattern": "^istmo_com_[a-f0-9]{64}$", "description": "Se entrega una sola vez. Guardar exclusivamente como secreto del backend." } }, "required": [ "id", "empresaId", "sucursalId", "almacenId", "nombre", "sitioUrl", "numeroLista", "scopes", "activo", "createdAt", "updatedAt", "credential" ] }, "OrderAdmin": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "externalId": { "type": "string" }, "status": { "type": "string", "enum": [ "pendiente_confirmacion", "rechazado" ] }, "reason": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "paymentStatus": { "type": "string", "enum": [ "not_requested" ] }, "stockReserved": { "type": "boolean", "enum": [ false ] }, "invoiced": { "type": "boolean", "enum": [ false ] }, "request": { "$ref": "#/components/schemas/OrderInput" }, "snapshot": { "$ref": "#/components/schemas/Snapshot" } }, "required": [ "id", "externalId", "status", "reason", "createdAt", "updatedAt", "paymentStatus", "stockReserved", "invoiced", "request", "snapshot" ] }, "IntegrationsPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "items", "nextCursor" ] }, "OrdersPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderAdmin" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "items", "nextCursor" ] }, "Catalog": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true }, "integrationId": { "type": "string", "format": "uuid" }, "observedAt": { "type": "string", "format": "date-time" }, "availabilityGuaranteed": { "type": "boolean", "enum": [ false ] }, "checkoutEnabled": { "type": "boolean", "enum": [ false ] }, "mode": { "type": "string", "enum": [ "request_only" ] }, "lastSyncAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Sólo gateway: última publicación recibida. El catálogo puede estar desactualizado durante desconexión." } }, "required": [ "items", "nextCursor", "integrationId", "observedAt", "availabilityGuaranteed", "checkoutEnabled", "mode" ] }, "CommerceOptions": { "type": "object", "additionalProperties": false, "properties": { "warehouses": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "nombre": { "type": "string" } }, "required": [ "id", "nombre" ] } }, "allowedGateways": { "type": "array", "items": { "type": "string" } }, "encryptionReady": { "type": "boolean" }, "paymentInstruments": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "nombre": { "type": "string" } }, "required": [ "id", "nombre" ] } }, "permissions": { "type": "object", "additionalProperties": false, "properties": { "reconcile": { "type": "boolean" }, "invoice": { "type": "boolean" }, "fulfill": { "type": "boolean" } }, "required": [ "reconcile", "invoice", "fulfill" ] } }, "required": [ "warehouses", "allowedGateways", "encryptionReady", "paymentInstruments", "permissions" ] }, "CommerceSettings": { "type": "object", "additionalProperties": false, "properties": { "selected": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "sku", "name" ] } }, "bridge": { "type": "object", "additionalProperties": false, "properties": { "source": { "type": "string", "enum": [ "environment", "database" ] }, "gatewayUrl": { "type": "string" }, "binding": { "type": "object", "additionalProperties": false, "properties": { "installationId": { "type": "string", "format": "uuid" }, "integrationId": { "type": "string", "format": "uuid" } }, "required": [ "installationId", "integrationId" ] }, "enabled": { "type": "boolean" }, "status": { "type": "object", "additionalProperties": false, "properties": { "attemptAt": { "type": "string", "nullable": true }, "successAt": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true }, "paused": { "type": "boolean" } }, "required": [ "attemptAt", "successAt", "errorCode", "paused" ] } }, "required": [ "source", "gatewayUrl", "binding", "enabled", "status" ], "nullable": true }, "paymentSettings": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "instrumentoId": { "type": "string", "format": "uuid" }, "instructions": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "enabled", "instrumentoId", "instructions" ], "nullable": true } }, "required": [ "selected", "bridge", "paymentSettings" ] }, "CommerceProducts": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "sku", "name" ] } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "items", "nextCursor" ] }, "CommerceBridgeInput": { "type": "object", "additionalProperties": false, "properties": { "gatewayUrl": { "type": "string", "format": "uri", "description": "Origen HTTPS incluido en la lista del operador. Inmutable después de guardar." }, "installationId": { "type": "string", "format": "uuid" }, "connectorKey": { "type": "string", "pattern": "^istmo_bridge_[a-f0-9]{64}$", "writeOnly": true }, "localKey": { "type": "string", "pattern": "^istmo_com_[a-f0-9]{64}$", "writeOnly": true } }, "required": [ "gatewayUrl", "installationId", "connectorKey", "localKey" ] }, "CommerceBridgeResult": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" } }, "required": [ "id", "enabled" ] }, "CheckoutCommand": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "commandId": { "type": "string", "format": "uuid" }, "checkoutId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,99}$" }, "action": { "type": "string", "enum": [ "quote" ] }, "order": { "$ref": "#/components/schemas/OrderInput" } }, "required": [ "commandId", "checkoutId", "action", "order" ] }, { "type": "object", "additionalProperties": false, "properties": { "commandId": { "type": "string", "format": "uuid" }, "checkoutId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,99}$" }, "action": { "type": "string", "enum": [ "status" ] } }, "required": [ "commandId", "checkoutId", "action" ] }, { "type": "object", "additionalProperties": false, "properties": { "commandId": { "type": "string", "format": "uuid" }, "checkoutId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,99}$" }, "action": { "type": "string", "enum": [ "cancel" ] } }, "required": [ "commandId", "checkoutId", "action" ] }, { "type": "object", "additionalProperties": false, "properties": { "commandId": { "type": "string", "format": "uuid" }, "checkoutId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,99}$" }, "action": { "type": "string", "enum": [ "payment" ] } }, "required": [ "commandId", "checkoutId", "action" ] } ], "description": "commandId estable por operación. quote requiere order y checkoutId=externalId. payment solicita instrucciones ACH en una reserva vigente, sin confirmar cobro. status con UUID nuevo consulta estado actual; GET devuelve recibo histórico." }, "CheckoutQuote": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "fulfillment": { "type": "string", "enum": [ "pickup" ] }, "pricingPolicy": { "type": "string", "enum": [ "published_list_no_discounts" ] }, "subtotal": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "tax": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "total": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "productId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "quantity": { "type": "string" }, "unitPrice": { "type": "string" }, "taxRate": { "type": "string" }, "subtotal": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "tax": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "total": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" } }, "required": [ "productId", "name", "quantity", "unitPrice", "taxRate", "subtotal", "tax", "total" ] } } }, "required": [ "currency", "fulfillment", "pricingPolicy", "subtotal", "tax", "total", "lines" ] }, "CheckoutResult": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "externalId": { "type": "string" }, "status": { "type": "string", "enum": [ "reservado", "expirado", "cancelado", "vendido" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "observedAt": { "type": "string", "format": "date-time" }, "stockReserved": { "type": "boolean" }, "checkoutEnabled": { "type": "boolean", "enum": [ false ] }, "paymentStatus": { "type": "string", "enum": [ "not_requested", "pending", "confirmed", "applied", "refunded" ] }, "invoiced": { "type": "boolean" }, "quote": { "$ref": "#/components/schemas/CheckoutQuote" }, "payment": { "$ref": "#/components/schemas/TransferPayment" }, "invoice": { "$ref": "#/components/schemas/TransferInvoice" }, "fulfillment": { "$ref": "#/components/schemas/CommerceFulfillment" } }, "required": [ "id", "externalId", "status", "expiresAt", "observedAt", "stockReserved", "checkoutEnabled", "paymentStatus", "invoiced", "quote" ] }, "CheckoutCommandResult": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "commandId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "pending" ] }, "checkoutEnabled": { "type": "boolean", "enum": [ false ] } }, "required": [ "commandId", "state", "checkoutEnabled" ] }, { "type": "object", "additionalProperties": false, "properties": { "commandId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "completed" ] }, "result": { "$ref": "#/components/schemas/CheckoutResult" } }, "required": [ "commandId", "state", "result" ] }, { "type": "object", "additionalProperties": false, "properties": { "commandId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "failed" ] }, "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "commandId", "state", "error" ] } ], "description": "pending en gateway sólo confirma persistencia. completed/failed son recibos históricos: para consultar pago/factura actuales enviar status con nuevo commandId. checkoutEnabled=false significa que no hay cobro automático. ACH requiere confirmación administrativa." }, "TransferSettings": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "instrumentoId": { "type": "string", "format": "uuid" }, "instructions": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "enabled", "instrumentoId", "instructions" ] }, "TransferConfirmation": { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^(?:0|[1-9]\\d{0,11})\\.\\d{2}$" }, "reference": { "type": "string", "minLength": 3, "maxLength": 120 }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "amount", "reference", "reason" ] }, "TransferInvoiceInput": { "type": "object", "additionalProperties": false, "properties": { "terceroId": { "type": "string", "format": "uuid" } }, "required": [ "terceroId" ] }, "TransferPayment": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "method": { "type": "string", "enum": [ "bank_transfer" ] }, "status": { "type": "string", "enum": [ "pending", "confirmed", "applied", "refunded" ] }, "amount": { "type": "string", "pattern": "^(?:0|[1-9]\\d{0,11})\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "USD" ] }, "instructions": { "type": "string" }, "reference": { "type": "string", "nullable": true } }, "required": [ "id", "method", "status", "amount", "currency", "instructions", "reference" ], "nullable": true }, "TransferInvoice": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string", "nullable": true }, "fiscalStatus": { "type": "integer", "nullable": true } }, "required": [ "id", "number", "status", "fiscalStatus" ], "nullable": true }, "TransferResult": { "type": "object", "additionalProperties": false, "properties": { "paymentStatus": { "type": "string", "enum": [ "not_requested", "pending", "confirmed", "applied", "refunded" ] }, "invoiced": { "type": "boolean" }, "payment": { "$ref": "#/components/schemas/TransferPayment" }, "invoice": { "$ref": "#/components/schemas/TransferInvoice" }, "fulfillment": { "$ref": "#/components/schemas/CommerceFulfillment" } }, "required": [ "paymentStatus", "invoiced", "payment", "invoice", "fulfillment" ] }, "AdminCheckouts": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "externalId": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "customer": { "$ref": "#/components/schemas/OrderInput" }, "quote": { "$ref": "#/components/schemas/CheckoutQuote" }, "paymentStatus": { "type": "string", "enum": [ "not_requested", "pending", "confirmed", "applied", "refunded" ] }, "invoiced": { "type": "boolean" }, "payment": { "$ref": "#/components/schemas/TransferPayment" }, "invoice": { "$ref": "#/components/schemas/TransferInvoice" }, "fulfillment": { "$ref": "#/components/schemas/CommerceFulfillment" } }, "required": [ "id", "externalId", "status", "expiresAt", "customer", "quote", "paymentStatus", "invoiced", "payment", "invoice", "fulfillment" ] } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "items", "nextCursor" ] }, "CommerceFulfillment": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pendiente", "preparando", "listo", "entregado" ] }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "status", "updatedAt" ] }, "CommerceCustomers": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "nombre": { "type": "string" }, "codigo": { "type": "string" }, "ruc": { "type": "string", "nullable": true } }, "required": [ "id", "nombre", "codigo", "ruc" ] } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "items", "nextCursor" ] }, "FulfillmentInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "commandId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "preparando" ] }, "note": { "type": "string", "maxLength": 500, "default": "" } }, "required": [ "commandId", "status" ] }, { "type": "object", "additionalProperties": false, "properties": { "commandId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "listo" ] }, "note": { "type": "string", "maxLength": 500, "default": "" } }, "required": [ "commandId", "status" ] }, { "type": "object", "additionalProperties": false, "properties": { "commandId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "entregado" ] }, "note": { "type": "string", "maxLength": 500, "default": "" }, "receivedBy": { "type": "string", "minLength": 3, "maxLength": 150 } }, "required": [ "commandId", "status", "receivedBy" ] } ] }, "WebhookEvent": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "string", "enum": [ "1" ] }, "integrationId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "checkout.reserved", "checkout.expirado", "checkout.cancelado", "checkout.vendido", "checkout.invoiced", "checkout.fulfillment", "transfer.requested", "transfer.confirmed", "transfer.refund_recorded", "invoice.updated" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": false, "properties": { "checkoutId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,99}$" } }, "required": [ "checkoutId" ] } }, "required": [ "id", "version", "integrationId", "type", "occurredAt", "data" ] }, "WebhookDelivery": { "type": "object", "additionalProperties": false, "properties": { "event": { "$ref": "#/components/schemas/WebhookEvent" }, "status": { "type": "string", "enum": [ "pending", "retry", "processing", "delivered", "failed", "disabled" ] }, "attempts": { "type": "integer", "minimum": 0 }, "httpStatus": { "type": "integer", "nullable": true }, "nextAttemptAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "event", "status", "attempts", "httpStatus", "nextAttemptAt", "deliveredAt" ] } } } }