# Referencia API Métodos, credenciales y esquemas generados desde OpenAPI 1.6.0 ## Autenticación y API keys Cada tienda usa una API key independiente en la cabecera x-istmo-commerce-key. En el POS se generan 32 bytes aleatorios y sólo se guarda el hash SHA-256; la clave se entrega una vez al crear o rotar. En gateway, el operador aprovisiona una clave de sitio independiente en el gestor de secretos del despliegue. La clave POS fija empresa, sucursal y almacén y revalida contexto y licencia. La clave gateway sólo accede a su tienda y scopes; el conector revalida el POS al sincronizar. Durante desconexión el gateway puede recibir solicitudes con el último catálogo. Las operaciones administrativas requieren JWT de usuario y permisos vigentes; una API key de tienda no los sustituye. Guarda los secretos sólo en el backend, nunca en Vue o variables VITE_. - catalog:read: consultar únicamente el catálogo publicado. - orders:write: enviar solicitudes de pedido; no autoriza cobros ni facturas. - orders:read: consultar solicitudes de esa integración; el backend también debe autorizar al comprador. - Crear: POST /admin/integrations. Guardar data.credential de inmediato; el listado no vuelve a mostrarla. - Rotar: POST /admin/integrations/{id}/rotate. Invalida la clave anterior; si pierdes la respuesta, vuelve a rotar. - Revocar: DELETE /admin/integrations/{id}. Preserva pedidos e historial; una conexión revocada no se reactiva. - Se auditan creación, rotación y revocación. Ante una filtración, revoca o rota y actualiza el secreto del backend. - Las operaciones /admin anteriores se ejecutan en POS. Para gateway, el operador rota siteKey en su configuración; enabled=false y reinicio de todas las réplicas corta recepción inmediatamente. Cambiar sólo la clave POS no garantiza revocación cloud mientras está desconectado. ## GET /catalog Consultar catálogo autorizado Catálogo publicado de referencia. Cotizar y reservar mediante checkout-commands; disponibilidad y precios deben confirmarse en POS. Autenticación: x-istmo-commerce-key · scope catalog:read. ```json { "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "nextCursor previo. Orden UUID ascendente; no es un cursor de sincronización incremental." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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" }, "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" ] } }, "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" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X GET "$ISTMO_COMMERCE_BASE_URL/catalog" \ -H "x-istmo-commerce-key: $ISTMO_COMMERCE_KEY" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/catalog', { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { 'x-istmo-commerce-key': process.env.ISTMO_COMMERCE_KEY } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "items": [ { "id": "11111111-1111-4111-8111-111111111111", "sku": "ARROZ", "name": "Arroz nacional 1 kg", "description": "Arroz nacional 1 kg", "unitPriceReference": "1.2500", "currency": "USD", "availableReference": "8.2500", "stockUpdatedAt": null } ], "nextCursor": null, "integrationId": "11111111-1111-4111-8111-111111111111", "observedAt": "2026-09-17T15:00:00.000Z", "availabilityGuaranteed": false, "checkoutEnabled": false, "mode": "request_only", "lastSyncAt": null } } ``` ## POST /orders Registrar solicitud de pedido 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. Autenticación: x-istmo-commerce-key · scope orders:write. ```json { "requestBody": { "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" ] }, "responseStatus": 202, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X POST "$ISTMO_COMMERCE_BASE_URL/orders" \ -H "x-istmo-commerce-key: $ISTMO_COMMERCE_KEY" \ -H "Content-Type: application/json" \ --data '{ "externalId": "web-7d2f4c9a", "customer": { "name": "María González", "email": "maria@example.com", "phone": "6000-1234" }, "fulfillment": { "method": "pickup" }, "lines": [ { "productId": "11111111-1111-4111-8111-111111111111", "quantity": "2.0000" } ], "note": "" }' ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/orders', { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { 'x-istmo-commerce-key': process.env.ISTMO_COMMERCE_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ "externalId": "web-7d2f4c9a", "customer": { "name": "María González", "email": "maria@example.com", "phone": "6000-1234" }, "fulfillment": { "method": "pickup" }, "lines": [ { "productId": "11111111-1111-4111-8111-111111111111", "quantity": "2.0000" } ], "note": "" }) } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "id": "11111111-1111-4111-8111-111111111111", "externalId": "web-7d2f4c9a", "status": "recibido_gateway", "reason": null, "createdAt": "2026-09-17T15:00:00.000Z", "updatedAt": "2026-09-17T15:00:00.000Z", "paymentStatus": "not_requested", "stockReserved": false, "invoiced": false, "posOrderId": null } } ``` ## GET /orders/{externalId} Consultar estado de una solicitud 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. Autenticación: x-istmo-commerce-key · scope orders:read. ```json { "parameters": [ { "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." } } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X GET "$ISTMO_COMMERCE_BASE_URL/orders/web-7d2f4c9a" \ -H "x-istmo-commerce-key: $ISTMO_COMMERCE_KEY" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/orders/web-7d2f4c9a', { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { 'x-istmo-commerce-key': process.env.ISTMO_COMMERCE_KEY } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "id": "11111111-1111-4111-8111-111111111111", "externalId": "web-7d2f4c9a", "status": "recibido_gateway", "reason": null, "createdAt": "2026-09-17T15:00:00.000Z", "updatedAt": "2026-09-17T15:00:00.000Z", "paymentStatus": "not_requested", "stockReserved": false, "invoiced": false, "posOrderId": null } } ``` ## POST /admin/integrations Crear conexión de tienda 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. Autenticación: JWT administrativo con permisos vigentes. ```json { "requestBody": { "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" ] }, "responseStatus": 201, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X POST "$ISTMO_COMMERCE_BASE_URL/admin/integrations" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ --data '{ "nombre": "Mi tienda", "sitioUrl": "https://tienda.example.com", "almacenId": "11111111-1111-4111-8111-111111111111", "numeroLista": 1, "scopes": [ "catalog:read" ] }' ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations', { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN, 'Content-Type': 'application/json' }, body: JSON.stringify({ "nombre": "Mi tienda", "sitioUrl": "https://tienda.example.com", "almacenId": "11111111-1111-4111-8111-111111111111", "numeroLista": 1, "scopes": [ "catalog:read" ] }) } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "id": "11111111-1111-4111-8111-111111111111", "empresaId": "11111111-1111-4111-8111-111111111111", "sucursalId": "11111111-1111-4111-8111-111111111111", "almacenId": "11111111-1111-4111-8111-111111111111", "nombre": "Mi tienda", "sitioUrl": "https://tienda.example.com", "numeroLista": 1, "scopes": [ "catalog:read" ], "activo": false, "createdAt": "2026-09-17T15:00:00.000Z", "updatedAt": "2026-09-17T15:00:00.000Z", "credential": "CREDENCIAL-SOLO-EN-EL-BACKEND" } } ``` ## GET /admin/integrations Listar conexiones de la sucursal Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "nextCursor previo. Orden UUID ascendente; no es un cursor de sincronización incremental." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "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" ] } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "items", "nextCursor" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X GET "$ISTMO_COMMERCE_BASE_URL/admin/integrations" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations', { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "items": [ { "id": "11111111-1111-4111-8111-111111111111", "empresaId": "11111111-1111-4111-8111-111111111111", "sucursalId": "11111111-1111-4111-8111-111111111111", "almacenId": "11111111-1111-4111-8111-111111111111", "nombre": "Mi tienda", "sitioUrl": "https://tienda.example.com", "numeroLista": 1, "scopes": [ "catalog:read" ], "activo": false, "createdAt": "2026-09-17T15:00:00.000Z", "updatedAt": "2026-09-17T15:00:00.000Z" } ], "nextCursor": null } } ``` ## POST /admin/integrations/{id}/rotate Rotar credencial Invalida la anterior. Devuelve el secreto una sola vez; si se pierde la respuesta volver a rotar. No reactiva integraciones revocadas. Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X POST "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/rotate" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/rotate', { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "id": "11111111-1111-4111-8111-111111111111", "credential": "CREDENCIAL-SOLO-EN-EL-BACKEND" } } ``` ## DELETE /admin/integrations/{id} Revocar conexión Revocación lógica irreversible, idempotente. Preserva pedidos e historial. Operaciones que ya adquirieron el bloqueo pueden terminar antes de la revocación. Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "activo": { "type": "boolean", "enum": [ false ] } }, "required": [ "id", "activo" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X DELETE "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111', { method: 'DELETE', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "id": "11111111-1111-4111-8111-111111111111", "activo": false } } ``` ## PUT /admin/integrations/{id}/products Reemplazar productos publicados 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. Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." } ], "requestBody": { "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" ] }, "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "productoIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "id", "productoIds" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X PUT "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/products" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ --data '{ "productoIds": [ "11111111-1111-4111-8111-111111111111" ] }' ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/products', { method: 'PUT', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN, 'Content-Type': 'application/json' }, body: JSON.stringify({ "productoIds": [ "11111111-1111-4111-8111-111111111111" ] }) } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "id": "11111111-1111-4111-8111-111111111111", "productoIds": [ "11111111-1111-4111-8111-111111111111" ] } } ``` ## GET /admin/integrations/{id}/products Buscar productos elegibles para publicar Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 100, "default": "" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X GET "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/products" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/products', { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "items": [ { "id": "11111111-1111-4111-8111-111111111111", "sku": "ARROZ", "name": "Arroz nacional 1 kg" } ], "nextCursor": null } } ``` ## GET /admin/integrations/{id}/orders Consultar bandeja de solicitudes Incluye datos personales y snapshot; acceso administrativo, no usar desde Vue público. Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "nextCursor previo. Orden UUID ascendente; no es un cursor de sincronización incremental." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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", "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": { "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" ] }, "snapshot": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "products": { "type": "array", "items": { "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" ] } }, "checkoutEnabled": { "type": "boolean", "enum": [ false ] } }, "required": [ "currency", "products", "checkoutEnabled" ] } }, "required": [ "id", "externalId", "status", "reason", "createdAt", "updatedAt", "paymentStatus", "stockReserved", "invoiced", "request", "snapshot" ] } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "items", "nextCursor" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X GET "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/orders" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/orders', { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "items": [ { "id": "11111111-1111-4111-8111-111111111111", "externalId": "web-7d2f4c9a", "status": "pendiente_confirmacion", "reason": null, "createdAt": "2026-09-17T15:00:00.000Z", "updatedAt": "2026-09-17T15:00:00.000Z", "paymentStatus": "not_requested", "stockReserved": false, "invoiced": false, "request": { "externalId": "web-7d2f4c9a", "customer": { "name": "María González", "email": "maria@example.com", "phone": "6000-1234" }, "fulfillment": { "method": "pickup" }, "lines": [ { "productId": "11111111-1111-4111-8111-111111111111", "quantity": "2.0000" } ], "note": "" }, "snapshot": { "currency": "USD", "products": [ { "id": "11111111-1111-4111-8111-111111111111", "sku": "ARROZ", "name": "Arroz nacional 1 kg", "description": "Arroz nacional 1 kg", "unitPriceReference": "1.2500", "currency": "USD", "availableReference": "8.2500", "stockUpdatedAt": null } ], "checkoutEnabled": false } } ], "nextCursor": null } } ``` ## POST /admin/integrations/{id}/orders/{orderId}/reject Rechazar solicitud con motivo Mismo motivo es idempotente; otro motivo después del rechazo devuelve 409. No anula documentos fiscales ni devuelve dinero. Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." }, { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "type": "object", "additionalProperties": false, "properties": { "motivo": { "type": "string", "minLength": 5, "maxLength": 500 } }, "required": [ "motivo" ] }, "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X POST "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/orders/11111111-1111-4111-8111-111111111111/reject" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ --data '{ "motivo": "Producto sin disponibilidad" }' ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/orders/11111111-1111-4111-8111-111111111111/reject', { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN, 'Content-Type': 'application/json' }, body: JSON.stringify({ "motivo": "Producto sin disponibilidad" }) } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "id": "11111111-1111-4111-8111-111111111111", "externalId": "web-7d2f4c9a", "status": "recibido_gateway", "reason": null, "createdAt": "2026-09-17T15:00:00.000Z", "updatedAt": "2026-09-17T15:00:00.000Z", "paymentStatus": "not_requested", "stockReserved": false, "invoiced": false, "posOrderId": null } } ``` ## GET /admin/options Consultar almacenes y requisitos del puente Autenticación: JWT administrativo con permisos vigentes. ```json { "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X GET "$ISTMO_COMMERCE_BASE_URL/admin/options" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/options', { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "warehouses": [ { "id": "11111111-1111-4111-8111-111111111111", "nombre": "Mi tienda" } ], "allowedGateways": [ "Ejemplo" ], "encryptionReady": false, "paymentInstruments": [ { "id": "11111111-1111-4111-8111-111111111111", "nombre": "Mi tienda" } ], "permissions": { "reconcile": false, "invoice": false, "fulfill": false } } } ``` ## GET /admin/integrations/{id}/settings Consultar publicación y diagnóstico sin secretos Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X GET "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/settings" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/settings', { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "selected": [ { "id": "11111111-1111-4111-8111-111111111111", "sku": "ARROZ", "name": "Arroz nacional 1 kg" } ], "bridge": null, "paymentSettings": null } } ``` ## PUT /admin/integrations/{id}/bridge Guardar y activar vínculo cifrado Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." } ], "requestBody": { "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" ] }, "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" } }, "required": [ "id", "enabled" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X PUT "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/bridge" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ --data '{ "gatewayUrl": "https://tienda.example.com", "installationId": "11111111-1111-4111-8111-111111111111", "connectorKey": "Ejemplo", "localKey": "Ejemplo" }' ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/bridge', { method: 'PUT', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN, 'Content-Type': 'application/json' }, body: JSON.stringify({ "gatewayUrl": "https://tienda.example.com", "installationId": "11111111-1111-4111-8111-111111111111", "connectorKey": "Ejemplo", "localKey": "Ejemplo" }) } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "id": "11111111-1111-4111-8111-111111111111", "enabled": false } } ``` ## DELETE /admin/integrations/{id}/bridge Solicitar pausa del puente Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" } }, "required": [ "id", "enabled" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X DELETE "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/bridge" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/bridge', { method: 'DELETE', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "id": "11111111-1111-4111-8111-111111111111", "enabled": false } } ``` ## POST /checkout-commands Cotizar, reservar, solicitar transferencia, consultar o cancelar 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. Autenticación: x-istmo-commerce-key · scope undefined. ```json { "requestBody": { "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": { "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" ] } }, "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." }, "responseStatus": 202, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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": { "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": { "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" ] }, "payment": { "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 }, "invoice": { "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 }, "fulfillment": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pendiente", "preparando", "listo", "entregado" ] }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "status", "updatedAt" ] } }, "required": [ "id", "externalId", "status", "expiresAt", "observedAt", "stockReserved", "checkoutEnabled", "paymentStatus", "invoiced", "quote" ] } }, "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." } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X POST "$ISTMO_COMMERCE_BASE_URL/checkout-commands" \ -H "x-istmo-commerce-key: $ISTMO_COMMERCE_KEY" \ -H "Content-Type: application/json" \ --data '{ "commandId": "11111111-1111-4111-8111-111111111111", "checkoutId": "web-7d2f4c9a", "action": "quote", "order": { "externalId": "web-7d2f4c9a", "customer": { "name": "María González", "email": "maria@example.com", "phone": "6000-1234" }, "fulfillment": { "method": "pickup" }, "lines": [ { "productId": "11111111-1111-4111-8111-111111111111", "quantity": "2.0000" } ], "note": "" } }' ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/checkout-commands', { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { 'x-istmo-commerce-key': process.env.ISTMO_COMMERCE_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ "commandId": "11111111-1111-4111-8111-111111111111", "checkoutId": "web-7d2f4c9a", "action": "quote", "order": { "externalId": "web-7d2f4c9a", "customer": { "name": "María González", "email": "maria@example.com", "phone": "6000-1234" }, "fulfillment": { "method": "pickup" }, "lines": [ { "productId": "11111111-1111-4111-8111-111111111111", "quantity": "2.0000" } ], "note": "" } }) } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "commandId": "11111111-1111-4111-8111-111111111111", "state": "pending", "checkoutEnabled": false } } ``` ## GET /checkout-commands/{commandId} Recuperar recibo histórico de operación Autenticación: x-istmo-commerce-key · scope undefined. ```json { "parameters": [ { "name": "commandId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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": { "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": { "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" ] }, "payment": { "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 }, "invoice": { "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 }, "fulfillment": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pendiente", "preparando", "listo", "entregado" ] }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "status", "updatedAt" ] } }, "required": [ "id", "externalId", "status", "expiresAt", "observedAt", "stockReserved", "checkoutEnabled", "paymentStatus", "invoiced", "quote" ] } }, "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." } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X GET "$ISTMO_COMMERCE_BASE_URL/checkout-commands/11111111-1111-4111-8111-111111111111" \ -H "x-istmo-commerce-key: $ISTMO_COMMERCE_KEY" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/checkout-commands/11111111-1111-4111-8111-111111111111', { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { 'x-istmo-commerce-key': process.env.ISTMO_COMMERCE_KEY } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "commandId": "11111111-1111-4111-8111-111111111111", "state": "pending", "checkoutEnabled": false } } ``` ## PUT /admin/integrations/{id}/payment-settings Configurar ACH/transferencia 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. Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." } ], "requestBody": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "instrumentoId": { "type": "string", "format": "uuid" }, "instructions": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "enabled", "instrumentoId", "instructions" ] }, "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "instrumentoId": { "type": "string", "format": "uuid" }, "instructions": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "enabled", "instrumentoId", "instructions" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X PUT "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/payment-settings" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ --data '{ "enabled": false, "instrumentoId": "11111111-1111-4111-8111-111111111111", "instructions": "Ejemplo" }' ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/payment-settings', { method: 'PUT', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN, 'Content-Type': 'application/json' }, body: JSON.stringify({ "enabled": false, "instrumentoId": "11111111-1111-4111-8111-111111111111", "instructions": "Ejemplo" }) } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "enabled": false, "instrumentoId": "11111111-1111-4111-8111-111111111111", "instructions": "Ejemplo" } } ``` ## GET /admin/integrations/{id}/checkouts Listar cotizaciones y pagos 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. Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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": { "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" ] }, "quote": { "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" ] }, "paymentStatus": { "type": "string", "enum": [ "not_requested", "pending", "confirmed", "applied", "refunded" ] }, "invoiced": { "type": "boolean" }, "payment": { "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 }, "invoice": { "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 }, "fulfillment": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pendiente", "preparando", "listo", "entregado" ] }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "status", "updatedAt" ] } }, "required": [ "id", "externalId", "status", "expiresAt", "customer", "quote", "paymentStatus", "invoiced", "payment", "invoice", "fulfillment" ] } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "items", "nextCursor" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X GET "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/checkouts" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/checkouts', { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "items": [ { "id": "11111111-1111-4111-8111-111111111111", "externalId": "web-7d2f4c9a", "status": "Ejemplo", "expiresAt": "2026-09-17T15:00:00.000Z", "customer": { "externalId": "web-7d2f4c9a", "customer": { "name": "María González", "email": "maria@example.com", "phone": "6000-1234" }, "fulfillment": { "method": "pickup" }, "lines": [ { "productId": "11111111-1111-4111-8111-111111111111", "quantity": "2.0000" } ], "note": "" }, "quote": { "currency": "USD", "fulfillment": "pickup", "pricingPolicy": "published_list_no_discounts", "subtotal": "Ejemplo", "tax": "Ejemplo", "total": "Ejemplo", "lines": [ { "productId": "11111111-1111-4111-8111-111111111111", "name": "María González", "quantity": "2.0000", "unitPrice": "Ejemplo", "taxRate": "Ejemplo", "subtotal": "Ejemplo", "tax": "Ejemplo", "total": "Ejemplo" } ] }, "paymentStatus": "not_requested", "invoiced": false, "payment": null, "invoice": null, "fulfillment": { "status": "pendiente", "updatedAt": null } } ], "nextCursor": null } } ``` ## POST /admin/integrations/{id}/checkouts/{checkoutId}/confirm-transfer Conciliar transferencia recibida 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. Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." }, { "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." } ], "requestBody": { "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" ] }, "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "paymentStatus": { "type": "string", "enum": [ "not_requested", "pending", "confirmed", "applied", "refunded" ] }, "invoiced": { "type": "boolean" }, "payment": { "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 }, "invoice": { "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 }, "fulfillment": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pendiente", "preparando", "listo", "entregado" ] }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "status", "updatedAt" ] } }, "required": [ "paymentStatus", "invoiced", "payment", "invoice", "fulfillment" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X POST "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/checkouts/11111111-1111-4111-8111-111111111111/confirm-transfer" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ --data '{ "amount": "Ejemplo", "reference": "Ejemplo", "reason": "Ejemplo" }' ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/checkouts/11111111-1111-4111-8111-111111111111/confirm-transfer', { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN, 'Content-Type': 'application/json' }, body: JSON.stringify({ "amount": "Ejemplo", "reference": "Ejemplo", "reason": "Ejemplo" }) } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "paymentStatus": "not_requested", "invoiced": false, "payment": null, "invoice": null, "fulfillment": { "status": "pendiente", "updatedAt": null } } } ``` ## POST /admin/integrations/{id}/checkouts/{checkoutId}/invoice Emitir venta desde pago conciliado 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. Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." }, { "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." } ], "requestBody": { "type": "object", "additionalProperties": false, "properties": { "terceroId": { "type": "string", "format": "uuid" } }, "required": [ "terceroId" ] }, "responseStatus": 201, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "paymentStatus": { "type": "string", "enum": [ "not_requested", "pending", "confirmed", "applied", "refunded" ] }, "invoiced": { "type": "boolean" }, "payment": { "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 }, "invoice": { "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 }, "fulfillment": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pendiente", "preparando", "listo", "entregado" ] }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "status", "updatedAt" ] } }, "required": [ "paymentStatus", "invoiced", "payment", "invoice", "fulfillment" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X POST "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/checkouts/11111111-1111-4111-8111-111111111111/invoice" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ --data '{ "terceroId": "11111111-1111-4111-8111-111111111111" }' ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/checkouts/11111111-1111-4111-8111-111111111111/invoice', { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN, 'Content-Type': 'application/json' }, body: JSON.stringify({ "terceroId": "11111111-1111-4111-8111-111111111111" }) } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "paymentStatus": "not_requested", "invoiced": false, "payment": null, "invoice": null, "fulfillment": { "status": "pendiente", "updatedAt": null } } } ``` ## POST /admin/integrations/{id}/checkouts/{checkoutId}/record-refund Registrar devolución bancaria realizada 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. Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." }, { "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." } ], "requestBody": { "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" ] }, "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "paymentStatus": { "type": "string", "enum": [ "not_requested", "pending", "confirmed", "applied", "refunded" ] }, "invoiced": { "type": "boolean" }, "payment": { "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 }, "invoice": { "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 }, "fulfillment": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pendiente", "preparando", "listo", "entregado" ] }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "status", "updatedAt" ] } }, "required": [ "paymentStatus", "invoiced", "payment", "invoice", "fulfillment" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X POST "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/checkouts/11111111-1111-4111-8111-111111111111/record-refund" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ --data '{ "amount": "Ejemplo", "reference": "Ejemplo", "reason": "Ejemplo" }' ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/checkouts/11111111-1111-4111-8111-111111111111/record-refund', { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN, 'Content-Type': 'application/json' }, body: JSON.stringify({ "amount": "Ejemplo", "reference": "Ejemplo", "reason": "Ejemplo" }) } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "paymentStatus": "not_requested", "invoiced": false, "payment": null, "invoice": null, "fulfillment": { "status": "pendiente", "updatedAt": null } } } ``` ## GET /admin/integrations/{id}/customers Buscar cliente para emitir factura 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. Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 100, "default": "" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "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" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X GET "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/customers" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/customers', { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "items": [ { "id": "11111111-1111-4111-8111-111111111111", "nombre": "Mi tienda", "codigo": "Ejemplo", "ruc": null } ], "nextCursor": null } } ``` ## POST /admin/integrations/{id}/checkouts/{checkoutId}/fulfillment Avanzar preparación y retiro 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. Autenticación: JWT administrativo con permisos vigentes. ```json { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID de integración, no ID de empresa." }, { "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." } ], "requestBody": { "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" ] } ] }, "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pendiente", "preparando", "listo", "entregado" ] }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "status", "updatedAt" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X POST "$ISTMO_COMMERCE_BASE_URL/admin/integrations/11111111-1111-4111-8111-111111111111/checkouts/11111111-1111-4111-8111-111111111111/fulfillment" \ -H "Authorization: Bearer $ISTMO_ADMIN_TOKEN" \ -H "Content-Type: application/json" \ --data '{ "commandId": "11111111-1111-4111-8111-111111111111", "status": "preparando", "note": "" }' ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/admin/integrations/11111111-1111-4111-8111-111111111111/checkouts/11111111-1111-4111-8111-111111111111/fulfillment', { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { Authorization: 'Bearer ' + process.env.ISTMO_ADMIN_TOKEN, 'Content-Type': 'application/json' }, body: JSON.stringify({ "commandId": "11111111-1111-4111-8111-111111111111", "status": "preparando", "note": "" }) } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "status": "pendiente", "updatedAt": null } } ``` ## GET /webhook-deliveries Consultar entregas webhook (gateway) 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. Autenticación: x-istmo-commerce-key · scope orders:read. ```json { "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "nextCursor previo. Orden UUID ascendente; no es un cursor de sincronización incremental." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responseStatus": 200, "responseBody": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "event": { "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" ] }, "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" ] } }, "nextCursor": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "items", "nextCursor" ] } }, "required": [ "success", "data" ] } } ``` ### Ejemplo cURL ```bash curl -X GET "$ISTMO_COMMERCE_BASE_URL/webhook-deliveries" \ -H "x-istmo-commerce-key: $ISTMO_COMMERCE_KEY" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/webhook-deliveries', { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { 'x-istmo-commerce-key': process.env.ISTMO_COMMERCE_KEY } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "items": [ { "event": { "id": "11111111-1111-4111-8111-111111111111", "version": "1", "integrationId": "11111111-1111-4111-8111-111111111111", "type": "checkout.reserved", "occurredAt": "2026-09-17T15:00:00.000Z", "data": { "checkoutId": "web-7d2f4c9a" } }, "status": "pending", "attempts": 0, "httpStatus": null, "nextAttemptAt": "2026-09-17T15:00:00.000Z", "deliveredAt": null } ], "nextCursor": null } } ``` ## POST /webhook-deliveries/{eventId}/retry Reintentar entrega fallida (gateway) 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. Autenticación: x-istmo-commerce-key · scope orders:write. ```json { "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responseStatus": 200, "responseBody": { "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" ] } } ``` ### Ejemplo cURL ```bash curl -X POST "$ISTMO_COMMERCE_BASE_URL/webhook-deliveries/{eventId}/retry" \ -H "x-istmo-commerce-key: $ISTMO_COMMERCE_KEY" ``` ### Ejemplo Node.js ```js // Node 20+ · ejecutar sólo en el servidor const response = await fetch( process.env.ISTMO_COMMERCE_BASE_URL + '/webhook-deliveries/{eventId}/retry', { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000), headers: { 'x-istmo-commerce-key': process.env.ISTMO_COMMERCE_KEY } } ); const result = await response.json(); if (!response.ok) throw new Error(result.error?.code); // En un timeout, conservar externalId y consultar su estado. ``` ### Respuesta ilustrativa ```json { "success": true, "data": { "id": "11111111-1111-4111-8111-111111111111", "status": "pending" } } ```