{ "openapi": "3.1.0", "info": { "title": "MiPlato — API de Integración", "version": "1.0.4", "description": "API REST para que sistemas de gestión (ERP) publiquen el catálogo, reciban los pedidos y actualicen su estado en MiPlato. Documentación completa: /docs/api.", "contact": { "name": "MiPlato", "url": "https://miplato.com.py/docs/api" } }, "servers": [ { "url": "https://app.miplato.com.py/api/v1", "description": "Entorno actual" }, { "url": "https://sandbox.miplato.com.py/api/v1", "description": "Ambiente de homologación (tokens mpk_test_)" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Integración" }, { "name": "Catálogo" }, { "name": "Pedidos" }, { "name": "Eventos" }, { "name": "Webhooks" }, { "name": "Entregas" } ], "paths": { "/me": { "get": { "operationId": "getMe", "summary": "Contexto de la credencial", "tags": [ "Integración" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Me" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Confirma el vínculo. La primera llamada válida activa la integración." } }, "/store": { "get": { "operationId": "getStore", "summary": "Datos operativos del comercio", "tags": [ "Integración" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Store" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "store:read", "description": "Permiso necesario: `store:read`." }, "patch": { "operationId": "patchStore", "summary": "Abrir o pausar la recepción de pedidos", "tags": [ "Integración" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Store" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "store:write", "description": "Permiso necesario: `store:write`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePatch" } } } } } }, "/catalog/categories": { "get": { "operationId": "listCategories", "summary": "Listar categorías", "tags": [ "Catálogo" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "catalog:read", "description": "Permiso necesario: `catalog:read`.", "parameters": [ { "$ref": "#/components/parameters/UpdatedSince" } ] } }, "/catalog/categories/{external_id}": { "parameters": [ { "$ref": "#/components/parameters/ExternalId" } ], "put": { "operationId": "putCategory", "summary": "Crear o actualizar categoría", "tags": [ "Catálogo" ], "responses": { "200": { "description": "Actualizado, sin cambios o ignorado por antiguo", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UpsertResult" } } } } } }, "201": { "description": "Creado", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UpsertResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "catalog:write", "description": "Permiso necesario: `catalog:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryInput" } } } } }, "delete": { "operationId": "deleteCategory", "summary": "Desactivar categoría", "tags": [ "Catálogo" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UpsertResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "catalog:write", "description": "Permiso necesario: `catalog:write`." } }, "/catalog/products": { "get": { "operationId": "listProducts", "summary": "Listar productos", "tags": [ "Catálogo" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "catalog:read", "description": "Permiso necesario: `catalog:read`.", "parameters": [ { "name": "category_external_id", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." } }, { "name": "active", "in": "query", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ] } }, "/catalog/products/{external_id}": { "parameters": [ { "$ref": "#/components/parameters/ExternalId" } ], "put": { "operationId": "putProduct", "summary": "Crear o actualizar producto", "tags": [ "Catálogo" ], "responses": { "200": { "description": "Actualizado, sin cambios o ignorado por antiguo", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UpsertResult" } } } } } }, "201": { "description": "Creado", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UpsertResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Reemplazo completo de los campos gestionados. Requiere catalog_mode = erp_managed.\n\nPermiso necesario: `catalog:write`.", "x-miplato-scope": "catalog:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } } } }, "patch": { "operationId": "patchProduct", "summary": "Cambiar precio o disponibilidad", "tags": [ "Catálogo" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UpsertResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "catalog:write", "description": "Permiso necesario: `catalog:write`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPatch" } } } } }, "delete": { "operationId": "deleteProduct", "summary": "Desactivar producto", "tags": [ "Catálogo" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UpsertResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "catalog:write", "description": "Permiso necesario: `catalog:write`." } }, "/catalog/options/{external_id}": { "parameters": [ { "$ref": "#/components/parameters/ExternalId" } ], "patch": { "operationId": "patchOption", "summary": "Cambiar precio o disponibilidad de un adicional", "tags": [ "Catálogo" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UpsertResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "catalog:write", "description": "Permiso necesario: `catalog:write`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptionPatch" } } } } } }, "/catalog/batch": { "post": { "operationId": "catalogBatch", "summary": "Lote de operaciones de catálogo", "tags": [ "Catálogo" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BatchResponse" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Hasta 500 operaciones; cada una con su resultado. Con full_snapshot aplica missing_items_policy.\n\nPermiso necesario: `catalog:write`.", "x-miplato-scope": "catalog:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } } } } }, "/orders": { "get": { "operationId": "listOrders", "summary": "Listar pedidos", "tags": [ "Pedidos" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "orders:read", "description": "Permiso necesario: `orders:read`.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Estados separados por coma." }, { "name": "ack_status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "acknowledged", "failed" ] } }, { "name": "created_since", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." } }, { "$ref": "#/components/parameters/UpdatedSince" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ] } }, "/orders/by-external-id/{external_id}": { "get": { "operationId": "getOrderByExternalId", "summary": "Buscar pedido por el código del sistema externo", "tags": [ "Pedidos" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Order" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "orders:read", "description": "Permiso necesario: `orders:read`.", "parameters": [ { "$ref": "#/components/parameters/ExternalId" } ] } }, "/orders/{order_id}": { "get": { "operationId": "getOrder", "summary": "Consultar pedido", "tags": [ "Pedidos" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Order" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "orders:read", "description": "Permiso necesario: `orders:read`.", "parameters": [ { "$ref": "#/components/parameters/OrderId" } ] } }, "/orders/{order_id}/ack": { "post": { "operationId": "ackOrder", "summary": "Confirmar importación", "tags": [ "Pedidos" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Order" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "orders:write", "description": "Permiso necesario: `orders:write`.", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AckInput" } } } } } }, "/orders/{order_id}/import-failure": { "post": { "operationId": "orderImportFailure", "summary": "Informar falla de importación", "tags": [ "Pedidos" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Order" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "orders:write", "description": "Permiso necesario: `orders:write`.", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportFailureInput" } } } } } }, "/orders/{order_id}/status": { "post": { "operationId": "changeOrderStatus", "summary": "Cambiar estado", "tags": [ "Pedidos" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Order" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Requiere order_status_authority = erp o both.\n\nPermiso necesario: `orders:write`.", "x-miplato-scope": "orders:write", "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusInput" } } } } } }, "/events": { "get": { "operationId": "listEvents", "summary": "Feed de eventos", "tags": [ "Eventos" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor", "has_more", "cursor_expired" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" }, "cursor_expired": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "orders:read", "description": "Permiso necesario: `orders:read`.", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "types", "in": "query", "schema": { "type": "string" }, "description": "Tipos separados por coma." } ] } }, "/webhook": { "get": { "operationId": "getWebhook", "summary": "Configuración del webhook", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "webhooks:manage", "description": "Permiso necesario: `webhooks:manage`." }, "put": { "operationId": "putWebhook", "summary": "Crear o actualizar el webhook", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Actualizado", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "201": { "description": "Creado (incluye signing_secret)", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "webhooks:manage", "description": "Permiso necesario: `webhooks:manage`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } } } }, "/webhook/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotar el secreto de firma", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "signing_secret": { "type": "string" }, "previous_valid_hours": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "webhooks:manage", "description": "Permiso necesario: `webhooks:manage`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/webhook/test": { "post": { "operationId": "testWebhook", "summary": "Enviar evento de prueba", "tags": [ "Webhooks" ], "responses": { "202": { "description": "En cola", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "queued": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "webhooks:manage", "description": "Permiso necesario: `webhooks:manage`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/webhook/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "Entregas del webhook", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Validation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "webhooks:manage", "description": "Permiso necesario: `webhooks:manage`.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "delivering", "succeeded", "failed" ] } }, { "$ref": "#/components/parameters/Limit" } ] } }, "/webhook/deliveries/{delivery_id}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Reenviar una entrega", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Delivery" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-miplato-scope": "webhooks:manage", "description": "Permiso necesario: `webhooks:manage`.", "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^dlv_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/entregas": { "post": { "operationId": "requestDelivery", "summary": "Llamar repartidor del grupo o favorito", "tags": [ "Entregas" ], "x-miplato-scope": "orders:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryRequest" } } } }, "responses": { "201": { "description": "Entrega logística; cuenta informativa separada del pago del pedido.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Delivery" } } } } } }, "400": { "description": "Falta Idempotency-Key o JSON inválido" }, "403": { "description": "Credencial, comercio o permiso no habilitado" }, "409": { "description": "Cotización cambió" }, "422": { "description": "Validación: cobertura, transferencia o favorito no habilitados" } } } }, "/entregas/{id}": { "get": { "operationId": "getDelivery", "summary": "Consultar entrega de este comercio", "tags": [ "Entregas" ], "x-miplato-scope": "orders:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ent_[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "Entrega logística; cuenta informativa separada del pago del pedido.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Delivery" } } } } } }, "404": { "description": "Entrega inexistente o de otro comercio" } } } }, "/entregas/{id}/{action}": { "post": { "operationId": "deliveryAction", "summary": "Confirmar retiro, complementar envío, cancelar o confirmar devolución", "tags": [ "Entregas" ], "x-miplato-scope": "orders:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ent_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "pickup", "raise_fee", "cancel", "returned" ] } }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "settlement_confirmed": { "type": "boolean" }, "amount": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000 }, { "type": "string", "pattern": "^\\d{1,10}(\\.00)?$" } ], "description": "PYG enteros, sin separadores." }, "reason": { "type": "string", "maxLength": 500 }, "goods_received": { "type": "boolean" }, "refund_confirmed": { "type": "boolean" }, "return_fee": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000 }, { "type": "string", "pattern": "^\\d{1,10}(\\.00)?$" } ], "description": "PYG enteros, sin separadores." } } } } } }, "responses": { "200": { "description": "Entrega logística; cuenta informativa separada del pago del pedido.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Delivery" } } } } } }, "404": { "description": "Entrega o acción inexistente" }, "409": { "description": "Estado incompatible" }, "422": { "description": "Falta confirmación humana o importe inválido" } } } } }, "webhooks": { "evento": { "post": { "summary": "Evento enviado al webhook configurado", "description": "Firma: X-MiPlato-Signature = v1=hex(HMAC_SHA256(signing_secret, X-MiPlato-Timestamp + \".\" + cuerpo)). Responder 2xx en hasta 10 s.", "parameters": [ { "name": "X-MiPlato-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-MiPlato-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-MiPlato-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-MiPlato-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-MiPlato-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Recibido" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer . (credencial generada por el comercio en Panel → Integraciones)." } }, "parameters": { "ExternalId": { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." } }, "OrderId": { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ord_[0-9A-HJKMNP-TV-Z]{26}$" } }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "UpdatedSince": { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:\\-]{8,100}$" } }, "IdempotencyKeyRequired": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:\\-]{8,100}$" } } }, "responses": { "BadRequest": { "description": "JSON inválido, Idempotency-Key ausente o inválida, cursor inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Credencial ausente, inválida, vencida o revocada (unauthenticated).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "insufficient_scope, integration_suspended, store_suspended, status_authority_denied o field_not_managed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "El recurso no existe o pertenece a otro comercio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Conflicto (idempotency_conflict, request_in_progress, invalid_status_transition, external_id_conflict, etc.).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooLarge": { "description": "Cuerpo mayor al permitido o lote con más de 500 operaciones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Validation": { "description": "validation_failed: details trae cada campo inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Límite de solicitudes superado. Ver Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Money": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "ExternalId": { "type": "string", "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Código estable para el tratamiento automático.", "examples": [ "validation_failed" ] }, "message": { "type": "string", "description": "Mensaje en español." }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "request_id": { "type": "string", "examples": [ "req_01JA2B3C4D5E6F7G8H9J0KMNPQ" ] } } } } }, "Settings": { "type": "object", "properties": { "catalog_mode": { "type": "string", "enum": [ "manual", "erp_managed" ] }, "order_status_authority": { "type": "string", "enum": [ "miplato", "erp", "both" ] }, "missing_items_policy": { "type": "string", "enum": [ "keep", "deactivate" ] }, "ack_alert_minutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "ack_expected": { "type": "string", "enum": [ "on_receipt", "after_acceptance" ] } } }, "Me": { "type": "object", "properties": { "integration": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "int_01JA2B3C4D5E6F7G8H9J0KMNPQ" ] }, "system": { "type": "string", "examples": [ "custom" ] }, "status": { "type": "string", "enum": [ "pending", "active", "suspended", "revoked" ] }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "settings": { "$ref": "#/components/schemas/Settings" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "credential": { "type": "object", "properties": { "key_id": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." } } } } }, "store": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" } } }, "api_version": { "type": "string", "examples": [ "1.0" ] } } }, "Scope": { "type": "string", "enum": [ "store:read", "store:write", "catalog:read", "catalog:write", "orders:read", "orders:write", "webhooks:manage" ] }, "Store": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "timezone": { "type": "string", "examples": [ "America/Asuncion" ] }, "currency": { "type": "string", "examples": [ "PYG" ] }, "accepting_orders": { "type": "boolean" }, "fulfillment_types": { "type": "array", "items": { "type": "string", "enum": [ "delivery", "pickup" ] } }, "payment_methods": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "cash" ] }, "name": { "type": "string" } } } } } }, "StorePatch": { "type": "object", "additionalProperties": false, "required": [ "accepting_orders" ], "properties": { "accepting_orders": { "type": "boolean" } } }, "CategoryInput": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120 }, "position": { "type": "integer", "minimum": 0, "maximum": 100000 }, "active": { "type": "boolean", "default": true }, "source_updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." } } }, "OptionInput": { "type": "object", "additionalProperties": false, "required": [ "external_id", "name" ], "properties": { "external_id": { "type": "string", "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "name": { "type": "string", "maxLength": 120 }, "price": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ], "default": "0" }, "available": { "type": "boolean", "default": true } } }, "OptionGroupInput": { "type": "object", "additionalProperties": false, "required": [ "external_id", "name" ], "properties": { "external_id": { "type": "string", "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "name": { "type": "string", "maxLength": 120 }, "min_select": { "type": "integer", "minimum": 0, "maximum": 50, "default": 0 }, "max_select": { "type": "integer", "minimum": 1, "maximum": 50, "default": 1 }, "options": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/OptionInput" } } } }, "ProductInput": { "type": "object", "additionalProperties": false, "required": [ "name", "category_external_id", "price" ], "properties": { "name": { "type": "string", "maxLength": 150 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "sku": { "type": [ "string", "null" ], "maxLength": 64 }, "category_external_id": { "type": "string", "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "price": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "active": { "type": "boolean", "default": true }, "available": { "type": "boolean", "default": true }, "position": { "type": "integer", "minimum": 0, "maximum": 100000 }, "image_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 500 }, "image_mode": { "type": "string", "enum": [ "replace", "if_empty" ], "default": "replace" }, "option_groups": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/OptionGroupInput" }, "description": "Reemplazo completo de los adicionales. Si se omite, no se modifican." }, "source_updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." } } }, "ProductPatch": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "price": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "available": { "type": "boolean" }, "active": { "type": "boolean" }, "source_updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." } } }, "OptionPatch": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "price": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "available": { "type": "boolean" } } }, "UpsertResult": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": "string", "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "result": { "type": "string", "enum": [ "created", "updated", "unchanged", "ignored_stale" ] } } }, "Category": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "name": { "type": "string" }, "position": { "type": "integer" }, "active": { "type": "boolean" } } }, "Option": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "name": { "type": "string" }, "price": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "available": { "type": "boolean" } } }, "OptionGroup": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "name": { "type": "string" }, "min_select": { "type": "integer" }, "max_select": { "type": "integer" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/Option" } } } }, "Product": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "category_id": { "type": "string" }, "category_external_id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "price": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "active": { "type": "boolean" }, "available": { "type": "boolean" }, "position": { "type": "integer" }, "image": { "type": [ "string", "null" ], "format": "uri" }, "option_groups": { "type": "array", "items": { "$ref": "#/components/schemas/OptionGroup" } } } }, "BatchOperation": { "type": "object", "additionalProperties": false, "required": [ "op", "external_id" ], "properties": { "op": { "type": "string", "enum": [ "upsert_category", "deactivate_category", "upsert_product", "patch_product", "deactivate_product", "patch_option" ] }, "external_id": { "type": "string", "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "data": { "type": "object", "description": "Mismo cuerpo que el endpoint individual." }, "link_to_id": { "type": "string", "description": "Sólo en upsert_product: vincula un producto ya existente (prd_…)." } } }, "BatchRequest": { "type": "object", "additionalProperties": false, "required": [ "operations" ], "properties": { "operations": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/BatchOperation" } }, "full_snapshot": { "type": "boolean", "default": false }, "snapshot_id": { "type": "string", "pattern": "^[A-Za-z0-9._:\\-]{1,64}$" }, "snapshot_part": { "type": "integer", "minimum": 1, "maximum": 10000 }, "snapshot_last": { "type": "boolean" } } }, "BatchResponse": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "external_id": { "type": "string" }, "id": { "type": "string" }, "result": { "type": "string", "enum": [ "created", "updated", "unchanged", "ignored_stale", "error" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "sync_run_id": { "type": "string" }, "snapshot": { "type": "object", "properties": { "applied": { "type": "boolean" }, "open": { "type": "boolean" }, "parts_received": { "type": "integer" }, "failed_operations": { "type": "integer" }, "reason": { "type": "string" }, "deactivated": { "type": "object", "properties": { "products": { "type": "integer" }, "categories": { "type": "integer" } } } } } } }, "OrderStatus": { "type": "string", "enum": [ "pending", "accepted", "preparing", "ready", "out_for_delivery", "completed", "rejected", "cancelled" ] }, "Order": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "ord_01JA2B3C4D5E6F7G8H9J0KMNPQ" ] }, "number": { "type": "integer" }, "store_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "status_reason": { "type": [ "string", "null" ] }, "fulfillment_type": { "type": "string", "enum": [ "delivery", "pickup" ] }, "estimated_minutes": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." }, "scheduled_for": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "billing": { "type": [ "object", "null" ], "properties": { "document_type": { "type": "string", "enum": [ "ruc", "ci" ] }, "document": { "type": "string" }, "business_name": { "type": [ "string", "null" ] } } } } }, "delivery_address": { "type": [ "object", "null" ], "properties": { "street": { "type": "string" }, "number": { "type": [ "string", "null" ] }, "neighborhood": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] } } }, "payment": { "type": "object", "properties": { "method_code": { "type": "string" }, "method_name": { "type": "string" }, "change_for": { "type": [ "string", "null" ], "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "status": { "type": "string", "enum": [ "unpaid", "paid" ] } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer" }, "product": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "sku": { "type": [ "string", "null" ] } } }, "name": { "type": "string" }, "unit_price": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "quantity": { "type": "integer", "minimum": 1 }, "options": { "type": "array", "items": { "type": "object", "properties": { "group_name": { "type": "string" }, "group_external_id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "option": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." } } }, "name": { "type": "string" }, "unit_price": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "quantity": { "type": "integer" } } } }, "notes": { "type": [ "string", "null" ] }, "line_total": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] } } } }, "notes": { "type": [ "string", "null" ] }, "totals": { "type": "object", "properties": { "subtotal": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "delivery_fee": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "discount": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "total": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$", "description": "Monto decimal en texto, sin separador de miles.", "examples": [ "35000" ] }, "currency": { "type": "string", "const": "PYG" } } }, "integration": { "type": [ "object", "null" ], "properties": { "external_id": { "type": [ "string", "null" ] }, "external_number": { "type": [ "string", "null" ] }, "ack_status": { "type": "string", "enum": [ "pending", "acknowledged", "failed" ] }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." }, "last_import_error": { "type": [ "object", "null" ], "additionalProperties": true } } }, "status_history": { "type": "array", "items": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/OrderStatus" }, "at": { "type": "string", "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." }, "by": { "type": "string", "enum": [ "customer", "store_user", "integration", "system" ] }, "reason": { "type": [ "string", "null" ] } } } } } }, "AckInput": { "type": "object", "additionalProperties": false, "required": [ "external_id" ], "properties": { "external_id": { "type": "string", "pattern": "^[A-Za-z0-9._:\\-]{1,64}$", "description": "Código del sistema externo (sensible a mayúsculas)." }, "external_number": { "type": [ "string", "null" ], "maxLength": 64 } } }, "ImportFailureInput": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unmapped_product", "invalid_customer", "register_closed", "validation_error", "other" ] }, "message": { "type": "string", "maxLength": 500 }, "retryable": { "type": "boolean", "default": false } } }, "StatusInput": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/OrderStatus" }, "reason": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 255, "description": "Obligatorio para rejected y cancelled." }, "estimated_minutes": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 600, "description": "Sólo con accepted." }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." } } }, "EventType": { "type": "string", "enum": [ "order.created", "order.status_changed", "order.updated", "store.updated", "integration.updated", "webhook.test" ] }, "Event": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "data" ], "properties": { "id": { "type": "string", "examples": [ "evt_01JA2B3C4D5E6F7G8H9J0KMNPQ" ] }, "type": { "$ref": "#/components/schemas/EventType" }, "api_version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 con desplazamiento, p. ej. 2026-10-12T21:30:00-03:00." }, "store_id": { "type": "string" }, "integration_id": { "type": "string" }, "data": { "type": "object", "description": "Eventos de pedido: {order, previous_status?, changed_by?}. store.updated: {store}.", "additionalProperties": true } } }, "WebhookInput": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500, "description": "HTTPS pública." }, "events": { "type": "array", "items": { "type": "string" }, "default": [ "*" ], "description": "Tipos de evento o [\"*\"]." }, "active": { "type": "boolean", "default": true } } }, "Webhook": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "paused": { "type": "boolean" }, "paused_reason": { "type": [ "string", "null" ] }, "signing_secret": { "type": "string", "description": "Sólo en la respuesta de creación (201)." } } }, "Delivery": { "type": "object", "required": [ "id", "state", "version", "customer_total", "courier_fee", "balance" ], "properties": { "id": { "type": "string", "pattern": "^ent_" }, "state": { "type": "string", "enum": [ "offered", "accepted", "en_route", "delivered_review", "delivered", "failed", "returned", "cancelled" ] }, "label": { "type": "string" }, "version": { "type": "integer" }, "store": { "type": "string" }, "courier": { "type": [ "object", "null" ] }, "customer_total": { "type": "integer" }, "products_amount": { "type": "integer" }, "customer_fee": { "type": "integer" }, "courier_fee": { "type": "integer" }, "balance": { "type": "integer", "description": "Positivo: repartidor paga al comercio. Negativo: comercio paga al repartidor." }, "collect": { "type": "integer" }, "change": { "type": "integer" }, "refund_due": { "type": "integer" }, "return_fee": { "type": [ "integer", "null" ] }, "order_id": { "type": [ "string", "null" ] }, "tracking_url": { "type": "string", "description": "Enlace secreto para enviar exclusivamente al cliente." }, "code": { "type": [ "string", "null" ], "description": "Código privado del cliente. Nunca enviar al repartidor." }, "customer_name": { "type": "string" }, "customer_phone": { "type": "string" }, "destination_address": { "type": "string" }, "destination_reference": { "type": "string" }, "neighborhood": { "type": "string" }, "destination_lat": { "type": "string" }, "destination_lng": { "type": "string" }, "pickup_address": { "type": "string" }, "pickup_lat": { "type": "string" }, "pickup_lng": { "type": "string" }, "distance_meters": { "type": "integer" }, "payment_method": { "type": "string" }, "change_for": { "type": [ "integer", "null" ] }, "store_phone": { "type": [ "string", "null" ] }, "code_locked": { "type": "boolean" }, "recipient_name": { "type": [ "string", "null" ] }, "evidence": { "type": "boolean" }, "attention": { "type": "boolean" }, "failure_notified_at": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "created_by": { "type": "string" } } }, "DeliveryRequest": { "type": "object", "additionalProperties": false, "required": [ "request_key" ], "properties": { "request_key": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,64}$" }, "order_id": { "type": "string", "description": "ord_ del pedido aceptado con cotización guardada. Omita para entrega manual." }, "customer_name": { "type": "string", "maxLength": 120 }, "customer_phone": { "type": "string" }, "destination_address": { "type": "string", "maxLength": 255 }, "destination_reference": { "type": "string", "maxLength": 255 }, "neighborhood": { "type": "string", "maxLength": 120 }, "destination_lat": { "type": [ "number", "string" ] }, "destination_lng": { "type": [ "number", "string" ] }, "products_amount": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000 }, { "type": "string", "pattern": "^\\d{1,10}(\\.00)?$" } ], "description": "PYG enteros, sin separadores." }, "payment_method": { "type": "string", "enum": [ "cash", "bank_transfer" ] }, "transfer_confirmed": { "type": "boolean", "description": "Declaración explícita del comercio; no marca pagado un pedido." }, "change_for": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000 }, { "type": "string", "pattern": "^\\d{1,10}(\\.00)?$" } ], "description": "PYG enteros, sin separadores." }, "courier_id": { "type": "string", "description": "rdr_ favorito, o vacío para grupo." }, "fee_extra": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000 }, { "type": "string", "pattern": "^\\d{1,10}(\\.00)?$" } ], "description": "PYG enteros, sin separadores." }, "expected_fee": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000 }, { "type": "string", "pattern": "^\\d{1,10}(\\.00)?$" } ], "description": "PYG enteros, sin separadores." } } } } } }