# Morsis API: guía para agentes y asistentes de desarrollo > Integrar sistemas externos con comercios que usan Morsis. Leer esta guía para entender los conceptos y consultar OpenAPI antes de construir solicitudes. ## Fuentes y alcance - El contrato exacto está en [OpenAPI](https://api.morsis.dev/v1/openapi.yaml): métodos, parámetros, scopes, cuerpos, respuestas, ejemplos y eventos. - La [documentación interactiva](https://api.morsis.dev/docs) explica el producto y permite probar llamadas reales. - La URL base de este entorno es `https://api.morsis.dev/v1`. Producción: `https://api.morsis.com/v1`. Staging: `https://api.morsis.dev/v1`. Confirmar el entorno antes de ejecutar operaciones. - `/v1` es la versión mayor de la API. `info.version` es la versión de la especificación. - Si esta guía y un esquema difieren, prevalece OpenAPI. No deducir endpoints, valores de enums ni campos de escritura a partir de un ejemplo o una respuesta de lectura. - Los recursos publicados sirven como documentación. No son un servidor MCP ni conceden permiso para operar sobre datos del comercio. ## Conceptos de Morsis Morsis gestiona productos, pedidos, cobros y otras operaciones de un negocio. La API pública expone solo las capacidades incluidas en OpenAPI. - **Comercio / merchant:** negocio de la organización a la que pertenece la clave. `/merchant` devuelve su perfil público, no un directorio de todos los clientes de Morsis. `/merchant/legal` devuelve la información fiscal publicada. - **Sucursal / branch:** local o punto de operación del comercio. `/branches` devuelve las sucursales accesibles. Su `id` se usa como `branchId` y `catalogId` identifica el catálogo asignado, cuando existe. - **Catálogo / catalog:** carta o lista organizada de productos. Puede compartirse entre sucursales. Una sección agrupa productos, por ejemplo «Cafés». Para consultar precios y disponibilidad usar el contexto de sucursal y modalidad que admita el método. - **Producto / product:** artículo vendible, con `productId`, precio y posibles opciones. Validar las selecciones requeridas y límites de cada grupo. Consultar un producto no equivale a reservar stock. - **Modalidad / serviceMode:** cómo se entrega una compra, por ejemplo `takeaway` o `delivery`. Usar solo los valores habilitados y documentados. - **Carrito / cart:** selección de productos de una compra online en preparación. Morsis calcula el precio. Una sesión de pago devuelve `checkoutUrl`; crear el carrito o la sesión no implica un pago aprobado. - **Pedido / order:** productos, totales y estado de una venta. Las lecturas de `/orders` incluyen pedidos con o sin cupón de pago. Las escrituras siguen limitadas a pedidos con cupón elegibles. - **Cupón de pago / payment coupon:** código de barras de nueve dígitos que identifica un pedido ya armado. No es un descuento. Enviar el código como texto con ceros iniciales y la sucursal. - **Método de pago / payment method:** cómo cobró la empresa externa. `/payment-methods` devuelve IDs para `payments[].methodId`; no son IDs de cuentas bancarias ni cajas de Morsis. - **Contenido del sitio:** textos e imágenes publicados por el comercio, consultados por `siteId`. El ID se obtiene durante la configuración; no hay endpoint público para listar sitios. - **Envíos:** cotizaciones para un paquete, según proveedor, sucursal de origen, destino, peso y dimensiones. No crean envíos, reservan tarifas ni aplican automáticamente el costo al checkout. Todo envío a domicilio sale de una sola **sucursal de despacho** (puede ser un depósito), que publica `GET /shipping/policies` como `dispatchBranchId`; los locales de retiro son `pickupLocations`. - **Stock por local:** el stock es por sucursal. Se informa como estado (`available`, `low_stock`, `out_of_stock`, `unavailable`), nunca como cantidad, y no se reserva: el checkout vuelve a validar al elegir dónde retirar. - **Arrepentimientos:** solicitudes de cancelación de compras online y consulta de su estado. Registrar una solicitud no ejecuta un reembolso. - **Webhooks:** notificaciones salientes de Morsis al servidor de la integración. Implementar el receptor y la verificación de firma documentados. No tratar los eventos como rutas de la API a las que enviar solicitudes. Ejemplo: «Café del Centro» es el comercio; «Centro» y «Norte» son sucursales; la carta es un catálogo; «Cafés» es una sección y «Café con leche» es un producto. Estos nombres ilustran conceptos y no son IDs utilizables. ## Autenticación y permisos Los endpoints de negocio requieren `Authorization: Bearer mk_live_...`. La persona que administra el comercio crea la clave en Integraciones y habilita el módulo API pública. La clave fija la organización y puede limitar sucursales. No se selecciona otro comercio enviando `organizationId`. Mantener la clave en el servidor de la integración, en una variable de entorno o almacén de secretos; nunca incluirla en código del navegador, ejemplos compartidos ni mensajes al asistente. Pedir los nombres de variables y la configuración necesaria, no el secreto. No incluir credenciales reales en el código generado. - `branches:read`: sucursales. - `catalog:read`: catálogos, secciones, productos y sugerencias. - `/merchant` y `/merchant/legal`: cualquiera de los dos scopes anteriores. - `cart:write`: carritos, sesiones de pago y cotizaciones de envío. - `site_content:read`: contenido publicado de sitios. - `withdrawals:write` o `cart:write`: solicitudes de arrepentimiento. - `orders:read`: listar y leer pedidos, con o sin cupón de pago. - `orders:write`: modificar los productos de pedidos elegibles. - `orders:complete_external`: registrar cobro, factura externa y cierre. - `orders:refund_external`: registrar reembolsos y anulaciones con la nota de crédito externa. - `payment_methods:read`: consultar IDs de métodos de cobro externo. Los scopes no reemplazan los permisos de dominio ni el acceso a sucursales. Los cambios de pedidos también validan al operador. Documentación, OpenAPI y `/health` se consultan sin clave. La clave no debe utilizarse para una operación que el usuario no haya solicitado. ## Recorrido: clientes y usuarios - Clientes y usuarios son recursos distintos. `/customers` contiene clientes de la organización; `/team/members` contiene quienes tienen acceso a Morsis. - Clientes: `customers:read` permite listar, buscar y consultar; `customers:write` permite crear y actualizar. Requiere el módulo Clientes. `POST /customers` acepta nombre, correo, teléfono, documento y tipo de cliente. Una persona necesita correo o teléfono; una empresa necesita nombre. - Listados: usar `query`, `limit` (1 a 100) y `cursor`. Conservar la búsqueda al avanzar con `meta.cursor` mientras `meta.hasMore` sea verdadero. - Un alta de cliente puede encontrar un contacto existente: devuelve 200 y `meta.matchedExisting: true`; un alta nueva devuelve 201. No reemplaza datos ya existentes. Para modificar, usar `PATCH /customers/{customerId}` con los campos que cambian. Los datos de contacto pertenecen a la identidad del cliente y pueden compartirse entre organizaciones vinculadas a esa misma identidad. - Usuarios: `team:read` permite consultar miembros, invitaciones pendientes y roles asignables. `id` es el ID de membresía que se usa en `/team/members/{memberId}`; `userId` identifica a la persona. - Para invitar, consultar `GET /team/roles` y enviar `POST /team/invitations` con correo y `role` (el `slug`). Requiere `team:invite`. La persona recibe una invitación por correo y debe aceptarla. Los tokens de aceptación no se exponen. Una invitación pendiente repetida devuelve 409. - `team:write` permite cambiar puesto y sucursales con `PATCH /team/members/{memberId}`. No permite cambiar roles, nombre o correo, administrar definiciones de roles ni eliminar miembros. - Las claves nuevas con `team:invite` o `team:write` heredan la jerarquía de quien las crea, con máximo 999, inferior a propietario. Solo pueden editar usuarios de menor jerarquía y, al invitar, asignar roles de su nivel o inferiores. Las claves de consulta conservan jerarquía 200, por lo que su lista de roles asignables es menor. - No se permite asignar propietario, editar propietarios ni cuentas técnicas. Las sucursales no pueden exceder las de la clave. Una clave limitada a sucursales solo ve miembros e invitaciones cuya asignación completa está dentro de ese alcance. Omitir sucursales al invitar hereda las de la clave. - `PATCH` conserva los campos omitidos. No hay control de versión ni replay por `Idempotency-Key` en estas operaciones; ante una respuesta perdida, consultar el estado antes de reintentar. No hay bajas en esta versión. ## Recorrido: consultar productos 1. `GET /merchant`: perfil público del comercio. 2. `GET /branches`: elegir una sucursal accesible y conservar su `id` y `catalogId`. 3. `GET /catalogs/{catalogId}/sections`: organización del catálogo. 4. `GET /catalogs/{catalogId}/products?branchId={branchId}&serviceMode={serviceMode}`: productos en el contexto elegido. Seguir `meta.cursor` mientras `meta.hasMore` indique más páginas. Con `branchId`, cada producto trae `inStock`; agregar `inStock=true` lista solo lo que esa sucursal puede vender. 5. Sugerencias: `GET /catalogs/{catalogId}/products/{productId}/suggestions?branchId={branchId}&serviceMode={serviceMode}` junto a un producto, y `POST /catalogs/{catalogId}/suggestions` con `{ branchId, serviceMode, items: [{ productId, quantity }] }` antes de pagar (es una consulta: no modifica el carrito). `limit` va de 1 a 10 (6 por defecto). Cada entrada de `data` trae `product`, `source` y `rank`; solo incluyen productos que se pueden vender en ese momento. Una falla devuelve 200 con `data` vacío: mostrar la página sin sugerencias, no reintentar en bucle. Al agregar una sugerencia, enviar en `POST /carts/{cartId}/items` el campo `suggestion: { decisionId: meta.decisionId, source, rank, placement }` con `placement` `product_detail` o `pre_payment`. No inventar IDs cuando falten datos; obtenerlos de respuestas o solicitar la configuración de la integración. ## Recorrido: tienda online 1. Consultar sucursal y catálogo. 2. `POST /carts` con `branchId` y `serviceMode`. 3. `POST /carts/{cartId}/items` con productos, cantidades y opciones permitidas por el esquema. Morsis calcula precios y totales. 4. Para Correo Argentino, la elección de domicilio o sucursal y Clásico/Expreso se hace directamente en el checkout de Morsis. La tienda solo redirige a `checkoutUrl`; no implementa selectores ni envía códigos de sucursal. La cuenta MiCorreo debe estar conectada y habilitada en la política de envíos. 5. Si corresponde, cotizar el paquete con `POST /shipping/quotes`. Consultar sus requisitos: una cotización no altera el carrito ni el checkout. 6. `POST /carts/{cartId}/checkout-sessions` y redirigir al comprador al `checkoutUrl`. 7. Confirmar el resultado por el estado del carrito o por una notificación de pago verificada. Una redirección de éxito por sí sola no prueba un cobro. ## Recorrido: stock por local y retiro Para una tienda con varios locales que muestra dónde se puede retirar cada producto. Requiere `catalog:read` y `branches:read`. 1. `GET /shipping/policies`: conservar `dispatchBranchId` (de dónde salen los envíos a domicilio) y `pickupLocations` (locales de retiro, con dirección y horarios). Si `dispatchBranchId` es `null`, no hay envío a domicilio para esta clave. 2. Stock para envío a domicilio: leer el catálogo con `branchId={dispatchBranchId}` y usar `inStock` de cada producto. 3. Ficha de producto: `GET /catalogs/{catalogId}/products/{productId}/pickup-availability` devuelve cada local de retiro con `status`: - `available`: 3 unidades o más, o un producto sin control de stock. - `low_stock`: 1 o 2 unidades («Pocas unidades»). - `out_of_stock`: sin unidades en ese local. - `unavailable`: ese local no vende el producto para retiro. 4. Productos con talle, color u otras variantes: pasar las opciones elegidas en `optionIds` (separadas por comas, los mismos IDs que acepta el carrito). Con todas las variantes elegidas, el estado es el de esa combinación; sin elegir, es el de la combinación con más stock. Volver a consultar al cambiar la selección. 5. Filtro «Disponible para retirar en…»: listar con `branchId={local}&inStock=true`. Filtra antes de paginar, así que `meta.total` y el cursor siguen el resultado filtrado. `inStock` sin `branchId` responde 400. 6. Al comprar, crear el carrito y la sesión de pago como en el recorrido anterior. El checkout lista primero los locales que pueden entregar todo el pedido y marca los demás con «Sin stock para este pedido». El estado es informativo y puede cambiar entre la consulta y la compra: nada se reserva hasta completar el pedido. Un local que vende sin control de stock acepta el retiro aunque informe `out_of_stock`; uno con control rechaza el carrito con 409 `INSUFFICIENT_STOCK`. Mostrar estados, no cantidades. ## Recorrido: listar pedidos por estado - `GET /orders` devuelve resúmenes de los pedidos accesibles, más recientes primero. `GET /orders/{orderId}` devuelve el detalle completo y la versión necesaria para comandos. - Filtros opcionales: `branchId`, `preparationStatus`, `fulfillmentStatus`, `paymentStatus` y `hasPaymentCoupon`. Combinar filtros exige cumplir todos; separar estados con comas admite cualquiera de ellos. `fulfillmentStatus=none` busca pedidos sin estado de entrega. - Cupones pendientes de pago: `GET /orders?hasPaymentCoupon=true&paymentStatus=unpaid`. Un cupón es un atributo del pedido, no un estado de pago; puede seguir presente tras el cobro o la cancelación. Para excluir cancelados, agregar un filtro de preparación con los estados deseados. - Sin cupón: `GET /orders?hasPaymentCoupon=false`. Sin ese filtro se incluyen ambos grupos. - Usar `limit` de 1 a 100 (50 por defecto) y continuar con `meta.cursor` mientras `meta.hasMore` sea verdadero, conservando los filtros. `meta.total` cuenta todos los resultados accesibles antes del cursor; los datos pueden cambiar entre páginas. - La búsqueda exacta con `paymentCouponCode` requiere `branchId` y conserva la respuesta completa de cero o un pedido. ## Recorrido: cupón cobrado por otra empresa La empresa externa cobra y factura con su propio CUIT. Morsis registra esa operación ya realizada; no ejecuta el cobro ni emite la factura. La liquidación posterior al comercio queda pendiente y requiere un circuito separado. 1. `GET /orders?paymentCouponCode={code}&branchId={branchId}`. La lista trae cero o un pedido. Conservar `id` y la `version` opaca exacta. 2. `GET /payment-methods` para obtener los IDs y referencias requeridas. 3. Si hace falta editar: `POST /orders/{orderId}/items`, `PATCH /orders/{orderId}/items/{lineItemId}` o `POST /orders/{orderId}/item-removals`. La remoción lleva `lineItemId` en el JSON. Enviar `actorUserId`, `externalDeviceId`, `expectedVersion` e `Idempotency-Key`. 4. Tras el cobro y la factura externa, `POST /orders/{orderId}/external-completion` con pagos, factura y datos de auditoría. `Idempotency-Key` debe coincidir con `externalOperationId`. La suma de pagos, el total de factura y el total esperado deben coincidir con el total actual del pedido, en ARS. 5. Si la empresa devuelve dinero después del cierre: `POST /orders/{orderId}/external-refunds` con `payments` (`paymentId` de `payments[].id` y monto), `items` si hubo productos devueltos y `creditNote` por la suma. Para anular la venta entera: `POST /orders/{orderId}/external-cancellation` con `reason` y `creditNote` por el total. Ambos requieren `orders:refund_external`, la misma clave que registró el cierre y un operador con `orders:void`. La nota de crédito debe tener el mismo CUIT emisor, la letra que corresponde a la factura y una fecha igual o posterior. Una venta con reembolsos se revierte reembolsando el resto, no anulándola. `actorUserId` es el UUID del usuario activo de Morsis creado para el operador, con acceso a la sucursal y permiso de edición; no es el nombre de usuario externo. `externalDeviceId` es el ID de la caja del sistema externo y no da de alta un dispositivo enrolado. `lineItemId` identifica una línea del pedido. `items[].totalCents` es el total de la línea y `taxBreakdown` desglosa el IVA incluido en el total del pedido. Para tarjetas, usar `debit_card` o `credit_card`; las cuotas (`installments`) solo aplican a crédito. Solo pedidos elegibles, abiertos y sin pago pueden editarse o cerrarse. Hay límites para combos, líneas enviadas a cocina y ajustes especiales; consultar las restricciones del método. La factura externa se guarda como informada, sin validarla contra ARCA. No enviar números completos de tarjeta ni códigos de seguridad. ## Convenciones, conflictos y reintentos - Paths por recurso; campos JSON y filtros en `camelCase`. - Dinero en centavos enteros, nunca decimales. Usar la moneda y las restricciones del esquema. El servidor calcula los totales. - IDs y códigos son cadenas. Fechas como `issuedOn` son `YYYY-MM-DD`; instantes como `occurredAt` incluyen zona horaria. No reformatear `version`: es un token opaco. - Usar `branchId`, `serviceMode`, `sectionId` y `tagId`. Los aliases anteriores siguen disponibles por compatibilidad, pero no usarlos en integraciones nuevas. - Respuestas de negocio: `{ data }`; las listas paginadas (productos, pedidos) agregan `meta`. Los campos con valores conocidos pueden sumar valores nuevos: tratar un valor desconocido como desconocido, no como error. Health conserva `{ status: "ok" }`. - Omitir un campo PATCH conserva su valor. Enviar `null` solo si el esquema lo admite. - Cada cambio de pedido usa la versión leída. Tras un cambio exitoso, conservar la nueva versión de la respuesta. - Ante una interrupción, repetir la misma operación con idéntico cuerpo e idéntica clave de idempotencia. No generar una nueva clave para reintentar un cobro externo ya registrado. - Las ediciones retienen el resultado idempotente durante 24 horas; los cierres confirmados no expiran. La integración externa debe coordinar sus propias cajas: esta API no reserva el cupón ni evita cargos duplicados realizados fuera de Morsis. - `401`: revisar autenticación y vigencia de la clave. `403`: revisar permisos, módulos y acceso. No eludir denegaciones cambiando arbitrariamente IDs. - `409 ORDER_VERSION_CONFLICT`: releer y conciliar antes de enviar un cambio nuevo; no sobrescribir una modificación de otro operador. - `409 IDEMPOTENCY_CONFLICT`: la clave se reutilizó con otro cuerpo. Revisar la operación original antes de actuar. - `429`: respetar `Retry-After`. Los límites exactos están en OpenAPI. - Los errores incluyen `error.code` y `error.message`, y pueden incluir `error.details`. Usar el código, con fallback por estado HTTP, no comparar el texto. Conservar `X-Request-Id` para diagnóstico. ## Antes de generar o ejecutar una integración Identificar el recorrido, entorno, scopes y sucursal. Leer los esquemas de entrada y las respuestas de error de cada método. Separar código de ejemplo de datos reales. Usar mocks o staging para validar primero y no ejecutar cambios, cierres o pagos reales sin una solicitud explícita del usuario. No proponer liquidaciones o remesas del cobro externo como si esta API ya las implementara. ## Especificación OpenAPI completa ```yaml openapi: 3.1.0 info: title: Morsis Public API version: 2.12.0 description: > Public API for discovering branches, accessing catalog data, managing ecommerce carts and subscriptions, reading and completing orders collected by external partners, and managing customers and team members from Morsis-powered businesses. ## Authentication Business endpoints require a valid API key passed via the `Authorization` header. Health, documentation and OpenAPI downloads are public: ``` Authorization: Bearer mk_live_... ``` API keys are created from the Morsis admin panel under **Integrations > API Keys**. The `public_api` module must be enabled for the organization. ## Scopes - `catalog:read` — read catalogs, products, sections - `branches:read` — read public branch details and ordering availability - `cart:write` — create/manage ecommerce carts and request shipping quotes (also authorizes withdrawal-request intake/status) - `withdrawals:write` — submit and query consumer withdrawal requests without cart access (optional, for intake-only keys) - `site_content:read` — read the published content of the organization's sites (`/sites/{siteId}/content`) The merchant profile and legal endpoints (`/merchant`, `/merchant/legal`) accept either read scope (`catalog:read` or `branches:read`). - `orders:read` — list and read orders, with or without a payment coupon - `orders:write` — edit the items of unpaid orders - `orders:complete_external` — record an external collection, invoice and completion - `orders:refund_external` — record refunds and cancellations of an external collection, with the partner's credit note - `payment_methods:read` — list external payment method IDs - `subscriptions:read` — plans, contracts, periods, documents, entitlement, payment status, events, and previews (no effects) - `subscriptions:write` — buyers, contracts, cycles, plan changes, cancellations, pauses and payment intents - `subscriptions:portal` — representatives and buyer portal sessions - `subscriptions:webhooks` — register, change, rotate and remove subscription webhook endpoints (never granted to existing keys; the key must reach every branch) - `customers:read` — list, search and read customers - `customers:write` — create and update customers - `team:read` — read members, pending invitations and assignable roles - `team:invite` — invite members - `team:write` — edit member job title and branch assignment Interactive documentation: `/docs`. All monetary values are integer cents. Order commands require Idempotency-Key, operator, terminal and expectedVersion. Subscription scopes are re-validated on every call by the receiving service, together with the `subscriptions` module (money operations also need `customer_credit_accounts`). ## Subscriptions portal `/portal/*` endpoints are authenticated by a short-lived portal session (`Authorization: Bearer mps_…`), never by an API key. Your backend opens one with `POST /subscriptions/portal-sessions` for its logged-in user (with a role and the acting person, no representative needed), or the buyer uses the Morsis-hosted standalone access (`/portal/login/*`). ## Idempotency Every subscriptions/portal mutation requires `Idempotency-Key`. The same key and request replays the stored result (`Idempotent-Replayed: true`); the same key with another request answers `409 SUBSCRIPTION_IDEMPOTENCY_CONFLICT`. ## Errors All errors follow the same envelope: ```json { "error": { "code": "NOT_FOUND", "message": "Catalog not found" } } ``` ## Rate Limits Requests are rate limited **per API key**, in three buckets: | Bucket | Endpoints | Limit | | --- | --- | --- | | Reads | `GET` catalog, branch, merchant profile/legal, site content, cart, order, payment-method, subscription and portal endpoints, and `POST /catalogs/{catalogId}/suggestions` | 300 requests / 60 seconds | | Cart operations | `POST`/`PATCH`/`DELETE` cart and checkout-session endpoints, `POST /shipping/quotes`, order commands, and subscription and portal mutations | 120 requests / 60 seconds | | Withdrawal requests | `POST /withdrawal-requests`, `GET /withdrawal-requests/{code}` and `POST /portal/login/*` | 10 requests / 60 seconds | Portal endpoints carry no API key: they are rate limited per client IP. When a bucket is exhausted, the API responds `429` with the standard error envelope (`code: RATE_LIMITED`) and a `Retry-After: 60` header. Limits are approximate. Unauthenticated requests (`401`) do not consume quota. ## Webhooks Morsis can POST a signed `catalog.changed` to a store when what it sells may have changed, so it can rebuild its pages without waiting for its next poll. The endpoint is set from the Morsis admin panel under **Integrations > Webhook** (owners and admins, with the `public_api` module enabled). See the `webhooks` section. A site whose copy and images the merchant edits in Morsis (site content) gets its own signed `site.content_published` after each publish, at `POST {site url}/api/webhooks/site-content`, signed with that site's secret. ## Contract conventions - The base URL is /v1. Paths use English resource names in kebab-case; JSON fields and query parameters use camelCase. - Money uses integer cents (amountCents, totalCents) and currency codes (ARS). Never send decimal monetary amounts. - IDs and coupon barcodes are strings. Preserve leading zeros. A lineItemId identifies an order or cart line. - Response fields with a fixed set of values document their known values; new values can be added. Treat an unknown value as unknown, never as an error. Ignore unknown response fields. - Timestamps use RFC 3339 with an explicit timezone. New date-only fields end in On (issuedOn); timestamps end in At (occurredAt). - Success bodies use { data }, with { meta: { cursor, hasMore, total } } for paginated lists (products, orders). Health retains its existing { status } shape. - Optimistic concurrency uses an opaque version token: send the version from the last read or command as expectedVersion. A stale token returns 409 ORDER_VERSION_CONFLICT. - PATCH changes only supplied fields. Null is accepted only where the schema explicitly permits it. Unknown fields are rejected on strict write schemas. - Error codes are stable and extensible; handle unknown codes by HTTP status. Validation errors can include error.details with field paths. Do not match message text. - Every response includes X-Request-Id. 401 includes WWW-Authenticate; 405 includes Allow; 429 includes Retry-After. Authenticated JSON is not cached. - Catalog filters use branchId, serviceMode, sectionId and tagId. Legacy branch_id, service_mode, section and tag remain accepted but deprecated. Conflicting aliases return 400. - Canonical paths omit the trailing slash. The existing unversioned paths and trailing-slash variants remain compatible. Unsupported versions do not fall back to v1. - Existing cart scopes and response fields remain compatible. Order line removal uses POST /orders/{orderId}/item-removals with a JSON command, avoiding a DELETE request body. - Backward-compatible additions stay in v1. Removing or changing an existing field's meaning requires a new major URL version. The info.version above versions this document, not the URL. servers: - url: https://api.morsis.com/v1 description: Production - url: https://api.morsis.dev/v1 description: Staging security: - apiKey: [] paths: /merchant: get: operationId: getMerchant summary: Get the public merchant profile description: | Public name and slug of the API-key organization, public contact fields, visible custom links from its enabled links page (including social and WhatsApp links), and a published B2B storefront URL or null. Requires `branches:read` or `catalog:read`, exactly like `/merchant/legal`. This is organization-wide data, independent of a key's branch allowlist. B2B uses the network profile slug (not the organization slug), and is exposed only while `b2b_sales` is enabled and the profile is active. The B2B profile WhatsApp, when configured, is returned only in b2b.whatsapp, never as a general merchant contact. A storefront requiring buyer approval/login is still published; its access policy remains enforced there. In isolated previews without a configured B2B origin, b2b is null. No new scopes, internal IDs, private metadata, credentials or staff contact data are exposed. tags: - Merchant responses: '200': description: Public merchant profile content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Merchant' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Organization not found or deleted content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /merchant/legal: get: operationId: getMerchantLegalData summary: Merchant legal data (Data Fiscal F.960/D) description: | Returns the legal identity and Data Fiscal (F.960/D) publication a storefront must render on its main page: razón social, CUIT, fiscal and commercial addresses, declared site URL, and the **official ARCA-provided F.960/D hyperlink and logo**, exactly as configured by the merchant. The link is stored verbatim as ARCA generated it — it is never derived from the CUIT and is unrelated to the per-voucher invoice QR. No credentials or customer PII are ever included. Pass `branchId` to prefer a branch-specific publication when the merchant configured one; otherwise the organization-wide publication is returned. Requires `branches:read` or `catalog:read` scope. tags: - Merchant parameters: - name: branchId in: query required: false schema: type: string format: uuid responses: '200': description: Merchant legal data content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/MerchantLegalData' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Merchant legal data is not configured (`NOT_CONFIGURED`) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /branches: get: operationId: listBranches summary: List active branches description: | Returns the active branches for the authenticated organization, including their public address, opening hours, active catalog, ecommerce service modes, active public ordering/booking channels with absolute URLs, and visible custom contact/social links. Inactive and deleted branches are excluded. `selfService` is null when hidden, unavailable, menu-only, without an active catalog, or without enabled public self-service modes. `reservations` is null when its module is disabled or online booking is off/paused after merging organization defaults and branch overrides. Unset self-service toggles default to on, matching the customer app. URLs use configured customer origins, not the API host. These are configured capabilities, not a guarantee of current opening hours, stock, delivery eligibility or bookable slots; those are checked by the destination. Requires `branches:read` scope. Free-form internal address notes and the rest of the branch settings are never exposed. tags: - Branches responses: '200': description: Active branches sorted by name content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Branch' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /branches/{branchId}: get: operationId: getBranch summary: Get an active branch description: | Returns one active branch belonging to the authenticated organization. Inactive, unknown, and cross-organization IDs all return `404`. Includes the same channel/public-links projection as the branch list. Requires `branches:read` scope and respects the API key branch allowlist. tags: - Branches parameters: - $ref: '#/components/parameters/branchId' responses: '200': description: Branch details content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Branch' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/BranchNotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /catalogs: get: operationId: listCatalogs summary: List catalogs description: | Returns all active catalogs for the authenticated organization, followed by the active catalogs another organization shares with it that its branches run (read-only). Each group is ordered by name. tags: - Catalogs responses: '200': description: List of catalog summaries content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/CatalogSummary' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /catalogs/{catalogId}: get: operationId: getCatalog summary: Get a catalog description: | Returns a full catalog with all products, sections, tags, and option groups. This is a heavy response — use the list/filter endpoints for lighter reads. tags: - Catalogs parameters: - $ref: '#/components/parameters/catalogId' - $ref: '#/components/parameters/catalogBranchId' - $ref: '#/components/parameters/legacyCatalogBranchId' - name: serviceMode in: query description: Resolve the product media configured for this service mode. Prices in the full catalog retain their channel values; use product list/detail for mode-specific prices. schema: type: string - name: service_mode in: query deprecated: true description: Compatibility alias for serviceMode. schema: type: string responses: '200': description: Full catalog content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Catalog' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: Invalid pagination or conflicting query parameter values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /catalogs/{catalogId}/products: get: operationId: listProducts summary: List products in a catalog description: | Returns a paginated list of products. Supports filtering by section, tag, search text, and service mode. Uses cursor-based pagination. tags: - Products parameters: - $ref: '#/components/parameters/catalogId' - $ref: '#/components/parameters/catalogBranchId' - name: sectionId in: query description: Filter by section ID schema: &a1 type: string format: uuid - name: tagId in: query description: Filter by tag ID schema: &a2 type: string format: uuid - name: search in: query description: Case-insensitive text search on name, description, and short description schema: type: string - name: serviceMode in: query description: | Exclude products unavailable for this service mode and price each product for it (e.g. `pickup`, `delivery`, `dine_in`). The catalog is always the online store channel's: its own prices and visibility apply, then this mode's exceptions. Without `serviceMode`, products carry the online store's modality-less price and full gallery. Send the same mode the cart uses so the listed price matches the charged one. Resolution: if the product has a non-empty `serviceModeConfig`, it is included unless that mode's entry is present with `enabled: false` (a mode with no entry is available). Otherwise the legacy `serviceModeAvailability` is used: if any mode is explicitly `true` it acts as an allow-list (only those modes are available); otherwise it acts as a deny-list (only modes explicitly set to `false` are excluded). Products with no config and no availability restrictions are always included. schema: &a3 type: string - name: inStock in: query description: | Requires `branchId`. `true` keeps the products the branch has stock for, plus untracked products (`inStock: null`, they sell freely); `false` keeps only out-of-stock ones. Applied before pagination, so `meta.total` and the cursor follow the filtered list. Use it for a «Disponible para retirar en [local]» filter, reading the catalog at the shopper's chosen store. schema: type: boolean - name: limit in: query description: 'Maximum number of products to return (1–100, default: 50)' schema: type: integer minimum: 1 maximum: 100 default: 50 - name: cursor in: query description: Product ID to start after (from `meta.cursor` in previous response) schema: type: string format: uuid - $ref: '#/components/parameters/legacyCatalogBranchId' - name: section in: query description: Compatibility alias for sectionId. Prefer sectionId. Conflicting aliases return 400. schema: *a1 deprecated: true - name: tag in: query description: Compatibility alias for tagId. Prefer tagId. Conflicting aliases return 400. schema: *a2 deprecated: true - name: service_mode in: query description: Compatibility alias for serviceMode. Prefer serviceMode. Conflicting aliases return 400. schema: *a3 deprecated: true responses: '200': description: Paginated product list content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/Product' meta: $ref: '#/components/schemas/CursorPagination' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: Invalid pagination or conflicting query parameter values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /catalogs/{catalogId}/products/{productId}: get: operationId: getProduct summary: Get a product with option groups description: | Returns a single product with its full option groups expanded inline (instead of just IDs). Use this endpoint to render a product detail page or build an "add to cart" form. tags: - Products parameters: - $ref: '#/components/parameters/catalogId' - $ref: '#/components/parameters/catalogBranchId' - name: productId in: path required: true schema: type: string format: uuid - $ref: '#/components/parameters/legacyCatalogBranchId' - name: serviceMode in: query description: Resolve the product price and media for this service mode. schema: type: string - name: service_mode in: query deprecated: true description: Compatibility alias for serviceMode. schema: type: string responses: '200': description: Product with option groups content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ProductDetail' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: Invalid pagination or conflicting query parameter values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /catalogs/{catalogId}/products/{productId}/pickup-availability: get: operationId: getProductPickupAvailability summary: Where a product can be picked up description: | Requires catalog:read and branches:read. For every store the shopper can pick up from at checkout (the pickup locations of /shipping/policies, limited to the key's branch access), reports whether that store sells the product and how much stock it has, as a status rather than a unit count. Use it on the product page for a «Ver disponibilidad en locales» list, passing the picked size or color in `optionIds`. Stock is read live, is not reserved, and does not count add-on option stock. A store that sells without stock control can still accept the pickup when it reports `out_of_stock`; checkout enforces the store's own rule. Empty when delivery options are not configured. tags: - Products parameters: - $ref: '#/components/parameters/catalogId' - name: productId in: path required: true schema: type: string format: uuid - name: optionIds in: query description: | Comma-separated option ids the shopper picked, the same ids the cart takes. Once they cover every variant axis of the product (size, color…), each store reports the stock of that combination instead of the product's best one, and a store that does not sell a picked option reports `unavailable`. Options outside the variant axes are ignored. schema: type: string responses: '200': description: Pickup availability per location content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/PickupAvailability' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /catalogs/{catalogId}/products/{productId}/suggestions: get: operationId: getProductSuggestions summary: Suggestions next to a product description: | Requires `catalog:read`. Returns what to suggest next to the product a shopper is viewing, for example a carousel on the product page. The list is ranked by Morsis: the merchant's recommendations first, then what the store's customers buy together, then the branch best sellers. Every entry is a product of the online store channel that can be sold right now: available, priced for `serviceMode`, and never a tracked product without stock. The viewed product is never suggested. Send the same `branchId` and `serviceMode` the cart uses. Without `branchId` the store's best sellers are not used and stock is not checked. The product, the catalog and the branch return the same `404` as `GET /catalogs/{catalogId}/products/{productId}` (also when the product is not offered in `serviceMode`). If suggestions cannot be computed the response is still `200` with an empty `data`: the page must work without them. When the shopper adds a suggested product, echo `meta.decisionId`, the entry's `source` and `rank` and `placement: product_detail` in the cart item's `suggestion`. tags: - Products parameters: - $ref: '#/components/parameters/catalogId' - name: productId in: path required: true description: The product being viewed (the anchor of the suggestions). schema: type: string format: uuid - $ref: '#/components/parameters/catalogBranchId' - name: serviceMode in: query description: | Suggest only products offered in this service mode, priced for it, with its gallery. Same resolution as `listProducts`. schema: type: string - name: limit in: query description: 'Maximum number of suggestions to return (1–10, default: 6)' schema: type: integer minimum: 1 maximum: 10 default: 6 - $ref: '#/components/parameters/legacyCatalogBranchId' - name: service_mode in: query deprecated: true description: Compatibility alias for serviceMode. schema: type: string responses: '200': description: Ranked suggestions (possibly empty) content: application/json: schema: $ref: '#/components/schemas/ProductSuggestionList' example: data: - product: id: 0c6f2d8e-5b1a-4f3e-9d27-8a4c1e6b3f90 name: Medialuna sku: MED-01 priceCents: 90000 originalPriceCents: null currency: ARS imageUrl: null imageCropData: null shortDescription: null description: null sectionId: 6a1d4c2b-3e5f-4a7b-8c9d-0e1f2a3b4c5d isAvailable: true inStock: true isFeatured: false hasOptions: false optionGroupIds: [] tags: [] sortOrder: 3 createdAt: '2026-09-01T12:00:00.000Z' media: null productType: simple serviceModeAvailability: null serviceModeConfig: null source: affinity rank: 0 reasonProductId: 7f3c2a1e-0b4d-4c8e-9a51-2d6f8e0c4b19 meta: decisionId: 3b9d6f1a-2c4e-4a8b-9f07-5d1e3c2b6a48 stamp: 9a4f2c7e1b3d5f60 headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: Invalid `limit` or conflicting query parameter values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /catalogs/{catalogId}/suggestions: post: operationId: suggestForCart summary: Suggestions before paying a cart description: | Requires `catalog:read`. Returns what to suggest before the shopper pays, for example a last step before checkout, for the products already in the cart. A read: it does not modify any cart, and the request body only carries the cart lines. It counts against the reads rate limit bucket. Same ranking and rules as `getProductSuggestions`: merchant recommendations, then what customers buy together, then the branch best sellers; only products of the online store channel that can be sold right now. Products already in `items` are never suggested; cart products the channel does not show are ignored. `quantity` weighs each line (default 1). The catalog and `branchId` return the same `404` as the product routes; a malformed body returns `400`. If suggestions cannot be computed the response is still `200` with an empty `data`. When the shopper adds a suggested product, echo `meta.decisionId`, the entry's `source` and `rank` and `placement: pre_payment` in the cart item's `suggestion`. tags: - Products parameters: - $ref: '#/components/parameters/catalogId' requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [items] properties: branchId: type: string format: uuid description: | The cart's branch. Must be inside the API key's branch scope; unknown, foreign and unauthorized IDs return `404 Branch not found`. Enables the branch's stock check and best sellers. serviceMode: type: string minLength: 1 maxLength: 80 description: The cart's service mode. Suggests only products offered and priced for it. items: type: array minItems: 1 maxItems: 50 description: The cart lines, in cart order. items: type: object additionalProperties: false required: [productId] properties: productId: type: string format: uuid quantity: type: integer minimum: 1 maximum: 199 default: 1 limit: type: integer minimum: 1 maximum: 10 default: 6 description: Maximum number of suggestions to return. example: branchId: 22222222-2222-4222-8222-222222222222 serviceMode: pickup items: - productId: 7f3c2a1e-0b4d-4c8e-9a51-2d6f8e0c4b19 quantity: 2 limit: 4 responses: '200': description: Ranked suggestions (possibly empty) content: application/json: schema: $ref: '#/components/schemas/ProductSuggestionList' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: Malformed body (`VALIDATION_ERROR`, with `details`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: VALIDATION_ERROR message: 'items: Too small: expected array to have >=1 items' details: - path: items message: 'Too small: expected array to have >=1 items' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /catalogs/{catalogId}/sections: get: operationId: listSections summary: List sections in a catalog description: Returns all active sections (categories) for the catalog, sorted by display order. tags: - Catalogs parameters: - $ref: '#/components/parameters/catalogId' - $ref: '#/components/parameters/catalogBranchId' - $ref: '#/components/parameters/legacyCatalogBranchId' responses: '200': description: List of sections content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Section' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: Invalid pagination or conflicting query parameter values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /sites/{siteId}/content: get: operationId: getSiteContent summary: Get the published content of a site description: | The values of the site's last **published** version, never the draft: only the slots the merchant changed, by key. A slot with no value uses the default the site declares in its manifest; values whose key the site no longer declares are still returned and the site ignores them. A site never published answers `version: 0`, `publishedAt: null` and `values: {}`. `version` grows by one on every publish, rollbacks included. Requires `site_content:read`, and the site must belong to the API key's organization; any other site answers `404`. Counts against the key's read budget. tags: - Site content parameters: - $ref: '#/components/parameters/siteId' responses: '200': description: The published content content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/SiteContent' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: No such site in the API key's organization content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Site not found headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /carts: post: operationId: createCart summary: Create a new cart description: | Creates an ecommerce cart for a specific branch and service mode. The cart starts empty with a total of 0. An order number is assigned immediately at creation. When the cart's branch does not sell without stock, the product's units across the whole cart cannot exceed its stock at that branch; a write past it fails with `409 INSUFFICIENT_STOCK` and leaves the cart as it was. Products that do not track inventory are never limited. Requires `cart:write` scope. tags: - Carts parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - branchId - serviceMode properties: branchId: type: string format: uuid description: Branch where the order will be placed serviceMode: type: string description: 'Service mode (e.g. `pickup`, `delivery`, `dine_in`). Must be one of the branch `serviceModes` returned by `GET /branches`: enabled at the branch and offered by the online store there. Any other value (including the removed `ecommerce` mode) is rejected with `SERVICE_MODE_NOT_ALLOWED`.' metadata: type: object description: Arbitrary key-value metadata attached to the cart additionalProperties: true responses: '201': description: Cart created content: application/json: schema: type: object required: - data properties: data: type: object required: - cartId - orderNumber properties: cartId: type: string format: uuid orderNumber: type: string description: Human-readable order number (e.g. "A-001") headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: Validation error (missing fields, service mode not enabled) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Branch not found or does not belong to organization content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BRANCH_NOT_AVAILABLE message: Branch not found or does not belong to this organization headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/IdempotencyConflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /carts/{cartId}: get: operationId: getCart summary: Get cart with items and totals description: | Returns the full cart including line items (with resolved product names, prices, and options) and the calculated total. Items are grouped by `lineItemId` — each line item represents one product with its quantity and selected options. Requires `cart:write` scope. tags: - Carts parameters: - $ref: '#/components/parameters/cartId' responses: '200': description: Cart details content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Cart' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/CartNotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' delete: operationId: deleteCart summary: Delete a cart description: | Permanently deletes a cart and all its items. Only pending (non-checked-out) carts can be deleted. Requires `cart:write` scope. tags: - Carts parameters: - $ref: '#/components/parameters/cartId' responses: '200': description: Cart deleted content: application/json: schema: type: object required: - data properties: data: type: object required: - deleted properties: deleted: type: boolean enum: - true headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/CartNotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /carts/{cartId}/checkout-sessions: post: operationId: createCheckoutSession summary: Create a hosted checkout session description: | Creates a Morsis-hosted checkout session for an open ecommerce cart. The returned `checkoutUrl` is the URL the ecommerce should redirect or embed for the customer to pay with the branch's configured payment providers. The cart remains a draft order until payment is approved. Once paid, Morsis submits and advances the order through the same operational flow as self-service payments. For delivery carts, this endpoint can store delivery metadata and a delivery fee, but it does not create delivery assignments yet. With the `talo` provider (shown to the customer as «Transferencia») the customer gets a one-time CVU/alias and transfers from their bank app. Morsis confirms the money on its own, which can take a few minutes after the transfer; `checkout.session.paid` is the signal. The CVU accepts money for 120 minutes and the session expires 5 minutes after it. A transfer that lands after `checkout.session.expired` while the order is still unpaid is applied anyway, so `checkout.session.expired` can be followed by `checkout.session.paid` for the same session. Talo sequences with a different amount (no extra event types): - More than the total: the order is covered and `checkout.session.paid` is emitted; the store handles the excess. - Less than the total: the session stays `payment_started`, with no event, while the customer can complete the difference (Morsis tells them by email or WhatsApp). It does not expire while that partial payment is open, even past the CVU's 120 minutes. - The customer completes it: `checkout.session.paid`. - The store refunds the partial payment instead: the session becomes `cancelled` and `checkout.session.failed` is emitted. - No money and the CVU expires: the session becomes `expired` (`checkout.session.expired`); a transfer that lands later can still turn it into `paid` (`checkout.session.paid`). Requires `cart:write` scope. tags: - Carts parameters: - $ref: '#/components/parameters/cartId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutSessionRequest' responses: '201': description: Checkout session created content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/CheckoutSession' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: Validation error or empty cart content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/CartNotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: Checkout is unavailable, already paid, or idempotency key conflicts content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /carts/{cartId}/items: post: operationId: addCartItem summary: Add an item to the cart description: | Adds a product to the cart. Pricing is 100% server-side — the client sends `productId` + `optionIds[]` and the API resolves actual prices from the catalog database. The cart total is recalculated automatically. Requires `cart:write` scope. tags: - Carts parameters: - $ref: '#/components/parameters/cartId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - productId - quantity properties: productId: type: string format: uuid description: Catalog product ID quantity: type: integer minimum: 1 maximum: 199 description: Number of units optionIds: type: array maxItems: 50 items: type: string format: uuid description: > Selected option IDs from the product's option groups. Repeat an option ID to express quantity in `selectionType: quantity` groups. The request must stay within the cart row expansion budget. notes: type: string description: Special instructions for this item suggestion: $ref: '#/components/schemas/CartItemSuggestion' responses: '201': description: Item added content: application/json: schema: type: object required: - data properties: data: type: object required: - itemId properties: itemId: type: string description: Line item ID (use this to update or remove the item) headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: Validation error or invalid option content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Cart not found or product unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/CartWriteConflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /carts/{cartId}/items/{itemId}: patch: operationId: updateCartItem summary: Update a cart item description: | Partially updates a line item in the cart. Any combination of `quantity`, `optionIds`, and `notes` may be sent (at least one is required); omitted fields keep their current value. Updating `quantity` or `optionIds` re-validates the line against the branch catalog and re-resolves pricing server-side, exactly as when the item was added — a product or option that is no longer available makes the update fail. `quantity` must be at least 1; use DELETE to remove the item. The cart total is recalculated automatically. The new quantity is checked against the branch's stock like `addCartItem` (`409 INSUFFICIENT_STOCK`); the line's current units are not counted twice. Requires `cart:write` scope. tags: - Carts parameters: - $ref: '#/components/parameters/cartId' - $ref: '#/components/parameters/itemId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object minProperties: 1 properties: quantity: type: integer minimum: 1 maximum: 199 description: New number of units for this line item optionIds: type: array maxItems: 50 items: type: string format: uuid description: > Replacement set of selected option IDs for this line item — same semantics as when adding an item. Repeat an option ID to express quantity in `selectionType: quantity` groups. Send an empty array to clear all options (if the product's option groups allow it). The request must stay within the cart row expansion budget. notes: type: string description: Special instructions for this item responses: '200': description: Item updated content: application/json: schema: type: object required: - data properties: data: type: object required: - success properties: success: type: boolean enum: - true headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: Validation error or invalid option content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Cart or item not found, or product unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/CartWriteConflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' delete: operationId: removeCartItem summary: Remove an item from the cart description: | Removes a line item and all its associated option rows from the cart. The cart total is recalculated automatically. Requires `cart:write` scope. tags: - Carts parameters: - $ref: '#/components/parameters/cartId' - $ref: '#/components/parameters/itemId' - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: Item removed content: application/json: schema: type: object required: - data properties: data: type: object required: - deleted properties: deleted: type: boolean enum: - true headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: Item not found in cart content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/CartNotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/IdempotencyConflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /shipping/policies: get: operationId: getShippingPolicies summary: Read merchant shipping policies and free pickup locations tags: - Shipping description: | Requires branches:read and an active public_api module. Returns enabled delivery policies, the branch every home delivery ships from (`dispatchBranchId`) and active retail stores with online pickup enabled, limited to the key's branch access; warehouses, offices and inactive locations are never pickup locations. Pickup is always free. Charges use integer ARS cents, and percentageBps uses basis points (100 = 1%). Minimum applies before the inclusive freeFromCents threshold, which uses merchandise after discounts and excludes shipping. Empty postalCodes means unrestricted postal coverage; carrier quotes can still reject a destination. Disconnected automatic-carrier policies are omitted; fixed and percentage policies do not require an integration. Use this projection for storefront messaging, including free-shipping banners. Final delivery selection and pricing are validated by hosted checkout, not by a client-supplied fee. No carrier credentials or private settings are returned. For connected Correo Argentino, hosted checkout also offers agency pickup and Classic/Express selection. Storefronts only redirect to the existing checkoutUrl; they do not send agency codes or product types. pickupLocations lists merchant stores, not Correo agencies. See https://docs.morsis.com/admin/online-store-shipping. responses: '200': description: Public shipping configuration content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/ShippingPolicies' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '503': description: Shipping service unavailable /shipping/quotes: post: operationId: quoteShipping summary: Quote a packed parcel with MiCorreo or Andreani tags: - Shipping description: | Requires `cart:write`, an active `public_api` module and an API key with a service principal authorized for the origin branch. The orders module and online-store delivery modality must be enabled for that branch. Use from the storefront backend; never expose the secret API key in a browser. Read-only quotation: does not create a cart or shipment, reserve a rate, charge a label or change a checkout total. Returns all available home-delivery rates from the selected provider; an empty array means no rates were offered. Request again when the postal code, parcel or provider changes and before checkout. The storefront backend may pass its selected shipping charge through the existing checkout-session fulfillment.deliveryFeeCents. There is no stored quote ID or automatic checkout application. Idempotency-Key does not freeze a quote. The package must include packaging in its total weight and outer dimensions. Automatic packing from catalog products, multiple parcels and branch pickup are not part of this public endpoint. Hosted checkout separately supports Correo agency pickup and Classic/Express selection with server-side validation; those session-bound routes are internal to checkout, not API-key integration endpoints. Destination address/phone are not needed to quote. A successful quote does not certify address validity or delivery coverage at a door. MiCorreo uses the selected Morsis branch's saved postal code, not the integration's fallback postal code. Andreani prices by the merchant's contract; the selected branch must have the same numeric origin postal code as the configured Andreani origin. This is a Morsis branch ID, not an Andreani agency code. Missing/unsupported origins fail explicitly. No carrier credentials or contract IDs are returned. MiCorreo shipment import still uses the merchant account sender. Prices are integer ARS cents (Andreani uses tarifaConIva.total). declaredValueCents is the parcel's insured value; for Andreani it must exclude tax. MiCorreo does not use it for quotation. It is not the shipping charge. Andreani's real API acceptance remains pending merchant QA credentials. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ShippingQuoteRequest' example: provider: correo_argentino originBranchId: 22222222-2222-4222-8222-222222222222 destinationPostalCode: '1704' parcel: weightGrams: 1000 lengthCm: 30 widthCm: 20 heightCm: 10 declaredValueCents: 650000 responses: '200': description: Available rates for one parcel (may be empty) content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ShippingQuote' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: VALIDATION_ERROR or SERVICE_MODE_NOT_ALLOWED content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: BRANCH_NOT_AVAILABLE (foreign, inactive, unauthorized or orders disabled) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: PROVIDER_NOT_CONNECTED or PROVIDER_CONFIGURATION_INVALID content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '422': description: ORIGIN_NOT_CONFIGURED, ORIGIN_NOT_SUPPORTED, CURRENCY_NOT_SUPPORTED or QUOTE_REJECTED content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '502': description: PROVIDER_UNAVAILABLE; provider bodies are never disclosed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '503': description: SERVICE_UNAVAILABLE (internal API transport) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid /withdrawal-requests: post: operationId: createWithdrawalRequest summary: Submit a consumer withdrawal request (botón de arrepentimiento) description: | Creates a withdrawal request for a distance sale (Disposition 954/2025 + 3/2026). The consumer does not log in and does not provide a reason. **Verification** (exactly one path): - `checkoutSessionToken` — the hosted-checkout session token from the buyer's receipt/confirmation. Possession is the proof (preferred). - `orderId` + `contactEmail` and/or `contactPhone` — the contact must match the one captured at checkout. The response returns the **acknowledgment code immediately** — do not wait for the legal 24-hour ceiling. A request is a case for the merchant to review: submitting one does **not** cancel the order or trigger a refund. **Idempotency**: send an `Idempotency-Key` header to make retries safe; independently, a repeat submission for an order with an open request returns the same request/code. **Anti-enumeration**: every unverifiable submission (unknown order, contact mismatch) returns the same neutral `VERIFICATION_FAILED` error. The endpoint never confirms whether an arbitrary order exists. Requires `cart:write` or `withdrawals:write` scope. Note: this endpoint shares the strictest rate-limit bucket with the status query (10 requests / 60 seconds per API key — see Rate Limits above). tags: - Withdrawals parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 requestBody: required: true content: application/json: schema: type: object properties: checkoutSessionToken: type: string description: Hosted-checkout session token (receipt proof) orderId: type: string format: uuid description: Order id, when no session token is available contactEmail: type: string format: email description: Must match the checkout contact (fallback path) contactPhone: type: string description: Must match the checkout contact (fallback path) contactName: type: string maxLength: 200 scope: type: string enum: - full_order - items default: full_order scopeItems: type: array maxItems: 100 description: Required when `scope` is `items` items: type: object properties: orderItemId: type: string format: uuid description: type: string maxLength: 500 quantity: type: integer minimum: 1 responses: '201': description: Request received — acknowledgment code issued immediately content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/WithdrawalRequestAcknowledgment' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '400': description: Invalid request body (`VALIDATION_ERROR`) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '405': $ref: '#/components/responses/MethodNotAllowed' '422': description: | Neutral verification failure (`VERIFICATION_FAILED`) — returned identically whether the order does not exist, belongs to another merchant, or the contact does not match. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /withdrawal-requests/{code}: get: operationId: getWithdrawalRequestStatus summary: Query a withdrawal request by acknowledgment code description: | Returns the status of a withdrawal request. The acknowledgment code is the credential — unknown codes return a neutral 404 with no further detail. Requires `cart:write` or `withdrawals:write` scope. tags: - Withdrawals parameters: - name: code in: path required: true schema: type: string pattern: ^[A-Za-z0-9-]{4,32}$ responses: '200': description: Withdrawal request status content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/WithdrawalRequestStatus' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Unknown acknowledgment code (neutral) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /orders: get: operationId: listOrders tags: - Orders summary: Find orders description: >- Requires `orders:read`. The key must also have its corresponding domain permission and branch access. Without `paymentCouponCode`, returns OrderSummary entries for all accessible orders, with or without a coupon. Read `/orders/{orderId}` for full details. Filters combine with AND; comma-separated states within a filter combine with OR. With `paymentCouponCode`, `branchId` is required and the result preserves the original zero-or-one full Order lookup. Preserve leading zeros in the code. Results are ordered by createdAt descending, then ID descending. Use `limit` (default 50, maximum 100) and pass `meta.cursor` unchanged with the same filters for the next page. `meta.total` counts all matching accessible orders, before the cursor. Pages are live, not a frozen snapshot. `hasPaymentCoupon=true` means a code was issued, including paid and cancelled orders; combine with `paymentStatus=unpaid` for unpaid coupons. Open orders requiring gift-card or accepted-pricing workflows return `409 UNSUPPORTED_ORDER` before exposing collectible totals. Completed history remains readable. parameters: - name: paymentCouponCode in: query required: false description: Scanned payment coupon barcode, as a string. schema: type: string pattern: ^[0-9]+$ maxLength: 32 - name: branchId in: query required: false description: Filter by branch. Required when paymentCouponCode is supplied. schema: type: string format: uuid - name: hasPaymentCoupon in: query description: Omit for all orders, true for orders with a code, false for orders without one. schema: type: boolean - name: preparationStatus in: query description: Preparation states, including terminal states. Multiple values are comma-separated. style: form explode: false schema: type: array minItems: 1 items: type: string enum: [pending, confirmed, preparing, ready, completed, cancelled, in_table] - name: fulfillmentStatus in: query description: Delivery/service states. Use none for orders without a fulfillment state. Multiple values are comma-separated. style: form explode: false schema: type: array minItems: 1 items: type: string enum: [waiting, picked_up, served, driver_assigned, in_transit, delivered, none] - name: paymentStatus in: query description: Payment states, independently of preparation and coupon issuance. Multiple values are comma-separated. style: form explode: false schema: type: array minItems: 1 items: type: string enum: [unpaid, paid, refunded] - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 - name: cursor in: query description: Opaque next-page token from meta.cursor. Preserve the same filters. schema: type: string maxLength: 512 responses: '200': $ref: '#/components/responses/OrderList' '400': $ref: '#/components/responses/OrderBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/OrderConflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /orders/{orderId}: get: operationId: getOrder tags: - Orders summary: Read an order description: Requires `orders:read`. The key must also have its corresponding domain permission and branch access. Orders with and without payment coupons are readable. An order from another organization or outside the key's branches returns 404. Completed and cancelled orders remain readable, including their payments and invoices. Write commands remain restricted to eligible coupon orders. Open orders requiring gift-card or accepted-pricing workflows return `409 UNSUPPORTED_ORDER`; they cannot be collected through this channel. parameters: - $ref: '#/components/parameters/orderId' responses: '200': $ref: '#/components/responses/Order' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/OrderNotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/OrderConflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /orders/{orderId}/items: post: operationId: addOrderItem tags: - Orders summary: Add an item to an order description: Requires `orders:write`. The key must also have its corresponding domain permission and branch access. Prices and option selections are resolved server-side from the branch's local catalog. Only open unpaid sale orders without a live payment, fiscal operation or split plan can be edited. Bundles are not accepted by this endpoint. Replaying the same key and body returns the original response (24-hour retention). parameters: - $ref: '#/components/parameters/orderId' - $ref: '#/components/parameters/orderIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddOrderItemRequest' example: actorUserId: 09af74bb-63d8-47f2-8849-d66fe2b98f37 externalDeviceId: CAJA-7 expectedVersion: MjAyNi0xMC0xNCAxMzowMDowMC4xMjM0NTY productId: 2b0b3fe2-471f-41ad-8b9d-204425456055 quantity: 2 optionIds: [] notes: Sin sal responses: '201': $ref: '#/components/responses/Order' '400': $ref: '#/components/responses/OrderBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/OrderNotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/OrderConflict' '413': $ref: '#/components/responses/OrderPayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /orders/{orderId}/items/{lineItemId}: patch: operationId: updateOrderItem tags: - Orders summary: Edit an order item description: Requires `orders:write`. The key must also have its corresponding domain permission and branch access. lineItemId is the line identifier returned in items. Omitted fields are preserved. Quantity or option changes resolve current catalog prices; notes-only edits preserve prices. Fired kitchen lines, bundles and reward lines require their dedicated workflow; weighted, custom or price-adjusted lines accept notes only. A positive quantity is required; use POST /orders/{orderId}/item-removals to remove a line. Replays are retained for 24 hours. parameters: - $ref: '#/components/parameters/orderId' - $ref: '#/components/parameters/lineItemId' - $ref: '#/components/parameters/orderIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateOrderItemRequest' example: actorUserId: 09af74bb-63d8-47f2-8849-d66fe2b98f37 externalDeviceId: CAJA-7 expectedVersion: MjAyNi0xMC0xNCAxMzowMDowMC4xMjM0NTY quantity: 3 responses: '200': $ref: '#/components/responses/Order' '400': $ref: '#/components/responses/OrderBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/OrderNotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/OrderConflict' '413': $ref: '#/components/responses/OrderPayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /orders/{orderId}/item-removals: post: operationId: removeOrderItem tags: - Orders summary: Remove an order item description: Requires `orders:write`. The key must also have its corresponding domain permission and branch access. Removes the whole line with its options. Send lineItemId, actorUserId, externalDeviceId and expectedVersion in the JSON body. Same editability rules as PATCH. Replays are retained for 24 hours. parameters: - $ref: '#/components/parameters/orderId' - $ref: '#/components/parameters/orderIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RemoveOrderItemRequest' example: actorUserId: 09af74bb-63d8-47f2-8849-d66fe2b98f37 externalDeviceId: CAJA-7 expectedVersion: MjAyNi0xMC0xNCAxMzowMDowMC4xMjM0NTY lineItemId: 22222222-2222-4222-8222-222222222222 responses: '200': $ref: '#/components/responses/Order' '400': $ref: '#/components/responses/OrderBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/OrderNotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/OrderConflict' '413': $ref: '#/components/responses/OrderPayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /orders/{orderId}/external-completion: post: operationId: completeOrderExternally tags: - Orders summary: Record an external payment, invoice and completion description: Requires `orders:complete_external`. The key must also have its corresponding domain permission and branch access. The partner invoices under its own tax ID and collects into its own accounts. This records an already completed sale; it does not charge a provider or issue an invoice. Payment amounts, invoice total and expectedTotalCents must exactly equal the current order total. Currency is ARS. The response lists the reported payments with collectedBy=external (settlementStatus=pending while the merchant tracks third-party collections, null otherwise), and the invoice with issuedBy=external. externalDeviceId is the partner register ID, scoped by the API key; the originating Morsis device is preserved. actorUserId must identify an active non-service member with orders:edit and branch access. When the merchant has third-party collections enabled and has linked the API key to a collector company, invoice.issuerTaxId must be one of that company's tax IDs, otherwise the completion is rejected with 409 ISSUER_TAX_ID_NOT_ALLOWED; a key without a company accepts any issuer tax ID. Idempotency-Key must equal externalOperationId. Successful completion receipts do not expire. Reusing the key with a different payload is a 409. Refunds and cancellations have their own endpoints. A replayed completion returns the stored response unchanged; read GET /orders/{orderId} for the current settlementStatus and settledOn once the merchant records the partner's settlement. parameters: - $ref: '#/components/parameters/orderId' - $ref: '#/components/parameters/orderIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExternalCompletionRequest' example: actorUserId: 09af74bb-63d8-47f2-8849-d66fe2b98f37 externalDeviceId: CAJA-7 expectedVersion: MjAyNi0xMC0xNCAxMzowMDowMC4xMjM0NTY externalOperationId: venta-8421 occurredAt: 2026-10-14T10:05:00-03:00 expectedTotalCents: 250000 currency: ARS payments: - methodId: credit_card amountCents: 250000 reference: transaccion-912 cardLastFour: '1234' cardBrand: visa installments: 3 invoice: issuerTaxId: '30712345678' issuerName: Empresa externa typeCode: 6 pointOfSale: 1 number: 8421 issuedOn: 2026-10-14 totalCents: 250000 currency: ARS responses: '200': $ref: '#/components/responses/Order' '400': $ref: '#/components/responses/OrderBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/OrderNotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/OrderConflict' '413': $ref: '#/components/responses/OrderPayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /orders/{orderId}/external-refunds: post: operationId: refundOrderExternally tags: - Orders summary: Record an external refund and its credit note description: >- Requires `orders:refund_external`. The key must also have its corresponding domain permission and branch access, and must be the key that recorded the external completion or, with third-party collections enabled, a key the merchant linked to the active collector company that owns the invoice issuer tax ID (403 otherwise). Records money the partner already returned to the buyer, with the credit note it issued: Morsis moves no money and issues no fiscal document. List how much of each collected payment (payments[].id) was refunded; their sum must equal the credit note total. Send items when goods were returned: the lines are priced from the sale and must add up to the refunded amount. The sale stays completed. When the refunds reach the whole collection the order becomes paymentStatus=refunded and its accounting is reversed. actorUserId must hold orders:void. The credit note must come from the invoice issuer, with the matching letter (Factura B 6 → Nota de crédito B 8) and not predate the invoice. A credit note already recorded on the sale, by externalOperationId or by typeCode, pointOfSale and number, is rejected with 409 CREDIT_NOTE_ALREADY_RECORDED, also when it arrives through another key of the same company. Idempotency-Key must equal externalOperationId; receipts do not expire. parameters: - $ref: '#/components/parameters/orderId' - $ref: '#/components/parameters/orderIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExternalRefundRequest' example: actorUserId: 09af74bb-63d8-47f2-8849-d66fe2b98f37 externalDeviceId: CAJA-7 expectedVersion: MjAyNi0xMC0xNCAxMzowMDowMC4xMjM0NTY externalOperationId: devolucion-8421-1 occurredAt: 2026-10-15T11:20:00-03:00 reason: Producto devuelto payments: - paymentId: 77777777-7777-4777-8777-777777777777 amountCents: 115000 items: - lineItemId: 22222222-2222-4222-8222-222222222222 quantity: 1 creditNote: issuerTaxId: '30712345678' issuerName: Empresa externa typeCode: 8 pointOfSale: 1 number: 310 issuedOn: 2026-10-15 totalCents: 115000 currency: ARS responses: '200': $ref: '#/components/responses/Order' '400': $ref: '#/components/responses/OrderBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/OrderNotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/OrderConflict' '413': $ref: '#/components/responses/OrderPayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /orders/{orderId}/external-cancellation: post: operationId: cancelOrderExternally tags: - Orders summary: Record the cancellation of an externally collected sale description: >- Requires `orders:refund_external`. The key must also have its corresponding domain permission and branch access, and must be the key that recorded the external completion or, with third-party collections enabled, a key the merchant linked to the active collector company that owns the invoice issuer tax ID (403 otherwise). Records that the partner voided the whole sale, refunded the buyer and issued a credit note for the order total. Morsis cancels the order, returns its stock and reverses its accounting and loyalty effects, without moving money or issuing a fiscal document. A sale that already has refunds is reversed by refunding the rest (409 ORDER_HAS_REFUNDS). actorUserId must hold orders:void. A credit note already recorded on the sale is rejected with 409 CREDIT_NOTE_ALREADY_RECORDED. Idempotency-Key must equal externalOperationId; receipts do not expire. parameters: - $ref: '#/components/parameters/orderId' - $ref: '#/components/parameters/orderIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExternalCancellationRequest' example: actorUserId: 09af74bb-63d8-47f2-8849-d66fe2b98f37 externalDeviceId: CAJA-7 expectedVersion: MjAyNi0xMC0xNCAxMzowMDowMC4xMjM0NTY externalOperationId: anulacion-8421 occurredAt: 2026-10-15T11:20:00-03:00 reason: El comprador desistió de la compra creditNote: issuerTaxId: '30712345678' issuerName: Empresa externa typeCode: 8 pointOfSale: 1 number: 311 issuedOn: 2026-10-15 totalCents: 250000 currency: ARS responses: '200': $ref: '#/components/responses/Order' '400': $ref: '#/components/responses/OrderBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/OrderNotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/OrderConflict' '413': $ref: '#/components/responses/OrderPayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /payment-methods: get: operationId: listExternalPaymentMethods tags: - Payment methods summary: List external collection methods description: Requires `payment_methods:read` and the payment_accounts:view domain permission. These stable method IDs describe how the partner collected the money; they are not local payment-account IDs. New methods can be added; treat an unknown ID as a method you do not support. responses: '200': description: Supported methods content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/ExternalPaymentMethod' example: data: - id: cash name: Efectivo requiredFields: [reference] - id: debit_card name: Tarjeta de débito requiredFields: [reference] - id: credit_card name: Tarjeta de crédito requiredFields: [reference] - id: bank_transfer name: Transferencia bancaria requiredFields: [reference] - id: qr name: QR requiredFields: [reference] - id: payment_link name: Enlace de pago requiredFields: [reference] headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /health: get: operationId: healthCheck summary: Health check description: 'Returns `{ "status": "ok" }`. No authentication required.' tags: - System security: [] responses: '200': description: Service is healthy content: application/json: schema: type: object required: - status properties: status: type: string enum: - ok headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/InternalError' /openapi.yaml: get: operationId: getOpenApiSpec summary: Get the OpenAPI spec description: Returns this document. No authentication required. tags: - System security: [] responses: '200': description: The OpenAPI 3.1 document content: application/yaml: schema: type: string headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/InternalError' /customers: get: tags: - Customers summary: list Customers operationId: listCustomers description: Requires `customers:read`. Requires the customers module and public_api. Only customers linked to the key organization are visible. Contact reads are organization-wide, as in Admin. Responses exclude account balances, face identity, custom fields and internal metadata. parameters: - name: query in: query schema: type: string maxLength: 200 description: 'Case-insensitive search. Customers: name/email/phone; members: name/email; invitations: email.' - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 - name: cursor in: query schema: type: string format: uuid description: Cursor returned by the previous page. Lists are ordered by ID. responses: '200': description: Success content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/PublicCustomer' meta: $ref: '#/components/schemas/PeoplePageMeta' '400': description: Invalid input or unknown fields content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': description: Missing scope, module, live permission, branch access or grantable role content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource outside the organization or visible branch assignment, or missing resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: Conflicting contact, membership or pending invitation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' post: tags: - Customers summary: create Customer operationId: createCustomer description: Requires `customers:write`. Requires the customers module and public_api. Only customers linked to the key organization are visible. Contact reads are organization-wide, as in Admin. Responses exclude account balances, face identity, custom fields and internal metadata. Returns 201 for a new customer or 200 and meta.matchedExisting=true for a contact match. This is contact matching, not general request idempotency. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicCustomerCreate' responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/PublicCustomer' meta: type: object required: - matchedExisting properties: matchedExisting: type: boolean '201': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/PublicCustomer' meta: type: object required: - matchedExisting properties: matchedExisting: type: boolean '400': description: Invalid input or unknown fields content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': description: Missing scope, module, live permission, branch access or grantable role content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource outside the organization or visible branch assignment, or missing resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: Conflicting contact, membership or pending invitation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': $ref: '#/components/responses/OrderPayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /customers/{customerId}: get: tags: - Customers summary: get Customer operationId: getCustomer description: Requires `customers:read`. Requires the customers module and public_api. Only customers linked to the key organization are visible. Contact reads are organization-wide, as in Admin. Responses exclude account balances, face identity, custom fields and internal metadata. parameters: - name: customerId in: path required: true schema: type: string format: uuid responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/PublicCustomer' '400': description: Invalid input or unknown fields content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': description: Missing scope, module, live permission, branch access or grantable role content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource outside the organization or visible branch assignment, or missing resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: Conflicting contact, membership or pending invitation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' patch: tags: - Customers summary: update Customer operationId: updateCustomer description: Requires `customers:write`. Requires the customers module and public_api. Only customers linked to the key organization are visible. Contact reads are organization-wide, as in Admin. Responses exclude account balances, face identity, custom fields and internal metadata. Omitted fields are preserved. Contact data belongs to the shared customer identity; updates also appear wherever that same identity is linked. Concurrent updates use last-write-wins. parameters: - name: customerId in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicCustomerUpdate' responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/PublicCustomer' '400': description: Invalid input or unknown fields content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': description: Missing scope, module, live permission, branch access or grantable role content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource outside the organization or visible branch assignment, or missing resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: Conflicting contact, membership or pending invitation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': $ref: '#/components/responses/OrderPayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /team/members: get: tags: - Team summary: list Team Members operationId: listTeamMembers description: Requires `team:read`. Requires team_management and public_api. Technical service accounts are excluded. Restricted keys see only members whose complete branch assignment falls within the key assignment; unrestricted members are hidden from restricted keys. Personal identity fields cannot be edited. parameters: - name: query in: query schema: type: string maxLength: 200 description: 'Case-insensitive search. Customers: name/email/phone; members: name/email; invitations: email.' - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 - name: cursor in: query schema: type: string format: uuid description: Cursor returned by the previous page. Lists are ordered by ID. responses: '200': description: Success content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/PublicTeamMember' meta: $ref: '#/components/schemas/PeoplePageMeta' '400': description: Invalid input or unknown fields content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': description: Missing scope, module, live permission, branch access or grantable role content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource outside the organization or visible branch assignment, or missing resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: Conflicting contact, membership or pending invitation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /team/members/{memberId}: get: tags: - Team summary: get Team Member operationId: getTeamMember description: Requires `team:read`. Requires team_management and public_api. Technical service accounts are excluded. Restricted keys see only members whose complete branch assignment falls within the key assignment; unrestricted members are hidden from restricted keys. Personal identity fields cannot be edited. parameters: - name: memberId in: path required: true schema: type: string format: uuid responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/PublicTeamMember' '400': description: Invalid input or unknown fields content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': description: Missing scope, module, live permission, branch access or grantable role content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource outside the organization or visible branch assignment, or missing resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: Conflicting contact, membership or pending invitation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' patch: tags: - Team summary: update Team Member operationId: updateTeamMember description: Requires `team:write`. Requires team_management and public_api. Technical service accounts are excluded. Restricted keys see only members whose complete branch assignment falls within the key assignment; unrestricted members are hidden from restricted keys. Personal identity fields and existing roles cannot be edited. Only jobTitle and branchIds are accepted; role or roleId causes a 400 with no changes. New keys with team:invite or team:write inherit the issuing actor hierarchy, capped at 999 (below owner); other keys retain hierarchy 200. Existing members must have a strictly lower hierarchy. Owners and technical principals cannot be edited. Branch assignments cannot exceed the key scope or name another organization. Existing keys gain no capabilities. Omitted fields are preserved; no role-definition or permission-override changes are exposed. parameters: - name: memberId in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicMemberUpdate' responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/PublicTeamMember' '400': description: Invalid input or unknown fields content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': description: Missing scope, module, live permission, branch access or grantable role content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource outside the organization or visible branch assignment, or missing resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: Conflicting contact, membership or pending invitation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': $ref: '#/components/responses/OrderPayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /team/invitations: get: tags: - Team summary: list Team Invitations operationId: listTeamInvitations description: Requires `team:read`. Requires team_management and public_api. Technical service accounts are excluded. Restricted keys see only members whose complete branch assignment falls within the key assignment; unrestricted members are hidden from restricted keys. Personal identity fields cannot be edited. Lists pending invitations, excluding their tokens and acceptance URLs. parameters: - name: query in: query schema: type: string maxLength: 200 description: 'Case-insensitive search. Customers: name/email/phone; members: name/email; invitations: email.' - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 - name: cursor in: query schema: type: string format: uuid description: Cursor returned by the previous page. Lists are ordered by ID. responses: '200': description: Success content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/PublicTeamInvitation' meta: $ref: '#/components/schemas/PeoplePageMeta' '400': description: Invalid input or unknown fields content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': description: Missing scope, module, live permission, branch access or grantable role content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource outside the organization or visible branch assignment, or missing resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: Conflicting contact, membership or pending invitation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' post: tags: - Team summary: invite Team Member operationId: inviteTeamMember description: Requires `team:invite`. New keys with team:invite or team:write inherit the issuing actor hierarchy, capped at 999 (below owner); other keys retain hierarchy 200. Only roles at or below the key hierarchy may be assigned. Existing members must have a strictly lower hierarchy. Owners and technical principals cannot be edited. Branch assignments cannot exceed the key scope or name another organization. Existing keys gain no capabilities. Creates a pending invitation and attempts email delivery. The recipient must accept it; this does not create an authenticated user. Acceptance tokens are never returned. Duplicate pending invitations or existing members return 409, not an idempotent replay. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicInvitationCreate' responses: '201': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/PublicTeamInvitation' '400': description: Invalid input or unknown fields content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': description: Missing scope, module, live permission, branch access or grantable role content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource outside the organization or visible branch assignment, or missing resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: Conflicting contact, membership or pending invitation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': $ref: '#/components/responses/OrderPayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /team/roles: get: tags: - Team summary: list Team Roles operationId: listTeamRoles description: Requires `team:read`. Lists all role slugs assignable at the current key hierarchy, excluding owner and technical roles. A read-only key retains hierarchy 200. This read does not itself authorize invitations or edits. responses: '200': description: Assignable roles content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/PublicTeamRole' '400': description: Invalid input or unknown fields content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': description: Missing scope, module, live permission, branch access or grantable role content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource outside the organization or visible branch assignment, or missing resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: Conflicting contact, membership or pending invitation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' /subscriptions/plans: get: operationId: listSubscriptionPlans summary: List enabled plans with their latest price tags: [Subscriptions] description: | Every enabled plan the seller can contract with this key, principal plans (`kind: base`) and add-ons (`kind: addon`), including per-unit, tiered and setup-fee prices. Filter by `kind` before offering plans to a buyer; the buyer portal (`GET /portal/plans`) lists only self-service plans. Requires `subscriptions:read` scope. responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionPlanList' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/plans/{planId}/prices: get: operationId: listSubscriptionPlanPrices summary: List published price versions of a plan (newest first) tags: [Subscriptions] description: | Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionPlanId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionPriceList' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/buyers: post: operationId: createSubscriptionBuyer summary: Create a buyer ficha (person or company) tags: [Subscriptions] description: | A person needs an email or a phone. `externalCustomerRef` binds your own customer id so every endpoint can address the buyer by it. The ficha and its reference are created in one transaction. Retrying with the same `externalCustomerRef` (even with a new Idempotency-Key) answers the buyer that reference already names, with `matchedExisting: true`, and creates nothing. A reference that names a buyer of another `kind`, or another buyer than `companyMatchChoice.use`, is `409 SUBSCRIPTION_BUYER_REFERENCE_CONFLICT`. Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionBuyerCreate' responses: '201': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/buyers/{buyerId}/reference: post: operationId: setSubscriptionBuyerReference summary: Bind your customer reference to a buyer tags: [Subscriptions] description: | Sets the reference only while the buyer has none. One reference per buyer and one buyer per reference. Repeating the same binding is a no-op; another value is `409 SUBSCRIPTION_BUYER_REFERENCE_CONFLICT` (use `PUT` to re-point). Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/SubscriptionBuyerId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionBuyerReference' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' put: operationId: replaceSubscriptionBuyerReference summary: Set or re-point the reference of a buyer tags: [Subscriptions] description: | The reference decides which buyer your sessions and reads reach, so a change is audited (your key, its service user, the `actor` you state and the `reason`) and revokes every open portal session of the buyer, of any channel, in the same transaction. Sending the value already in place changes nothing (`changed: false`). A value that names another buyer is `409 SUBSCRIPTION_BUYER_REFERENCE_CONFLICT`. Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/SubscriptionBuyerId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionBuyerReferenceReplace' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionBuyerReferenceChange' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' delete: operationId: removeSubscriptionBuyerReference summary: Remove the reference of a buyer tags: [Subscriptions] description: | Audited like `PUT`, and revokes every open portal session of the buyer. A buyer without a reference answers `changed: false`. The reason and the actor travel in the query string, Stripe style: `?reason=Baja%20del%20CRM&actor[id]=user_42&actor[name]=Ana%20P%C3%A9rez`. Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/SubscriptionBuyerId' - name: reason in: query required: true schema: { type: string, minLength: 1, maxLength: 500 } - name: actor[id] in: query required: false description: Required with any other `actor[...]` field. schema: { type: string, minLength: 1, maxLength: 200 } - name: actor[name] in: query required: false schema: { type: string, minLength: 1, maxLength: 160 } - name: actor[email] in: query required: false schema: { type: string, format: email } - name: actor[impersonatorId] in: query required: false schema: { type: string, minLength: 1, maxLength: 200 } responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionBuyerReferenceChange' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/buyers/{buyerId}/representatives: get: operationId: listSubscriptionRepresentatives summary: List representatives of a buyer tags: [Subscriptions] description: | Standalone portal only (Morsis-hosted email login); sessions your backend opens take a `role` and an `actor` instead. Representatives are the ONLY delegation of standalone portal access. Being a contact of the company, knowing its id or its email grants nothing. Add `includeRevoked=true` for the audit list. Requires `subscriptions:portal` scope. parameters: - $ref: '#/components/parameters/SubscriptionBuyerId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionRepresentativeList' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' post: operationId: createSubscriptionRepresentative summary: Add a representative with view/pay/manage rights tags: [Subscriptions] description: | Standalone portal only (Morsis-hosted email login); sessions your backend opens take a `role` and an `actor` instead. `email` admits the standalone (Morsis-hosted, email code) login. Paying or managing requires viewing. Requires `subscriptions:portal` scope. parameters: - $ref: '#/components/parameters/SubscriptionBuyerId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionRepresentativeCreate' responses: '201': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionRepresentative' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/representatives/{representativeId}: patch: operationId: updateSubscriptionRepresentative summary: Change a representative rights tags: [Subscriptions] description: | Standalone portal only (Morsis-hosted email login); sessions your backend opens take a `role` and an `actor` instead. Applies to sessions already open on their next call. Requires `subscriptions:portal` scope. parameters: - $ref: '#/components/parameters/SubscriptionRepresentativeId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionRepresentativeUpdate' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionRepresentative' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/representatives/{representativeId}/revoke: post: operationId: revokeSubscriptionRepresentative summary: Revoke a representative tags: [Subscriptions] description: | Standalone portal only (Morsis-hosted email login); sessions your backend opens take a `role` and an `actor` instead. Every later call of its open sessions answers 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID`. Requires `subscriptions:portal` scope. parameters: - $ref: '#/components/parameters/SubscriptionRepresentativeId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionExpectedRevision' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionRepresentative' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/customers: get: operationId: listSubscriptionCustomers summary: List customer summaries tags: [Subscriptions] description: | Every buyer with a reference or with an accepted contract, by name. Each item rolls up its contracts: `status` is the worst state (`overdue` > `active` > `none`), `cancelled` only when every contract is cancelled or ended, `none` without contracts. `buyerId` answers a one-item page (empty when the buyer is not yours). Page with `limit`/`offset` until `hasMore` is false. Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionBuyerIdQuery' - name: linked in: query required: false description: '`true`: only buyers with a reference. `false`: only buyers without one.' schema: { type: string, enum: ['true', 'false'] } - name: search in: query required: false description: Accent- and case-insensitive match on the name or the reference. schema: { type: string, minLength: 1, maxLength: 160 } - $ref: '#/components/parameters/SubscriptionLimit' - $ref: '#/components/parameters/SubscriptionOffset' responses: '200': description: OK content: application/json: schema: type: object required: [data, hasMore] properties: data: type: array items: { $ref: '#/components/schemas/SubscriptionCustomerSummary' } hasMore: { type: boolean } '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/customers/{externalCustomerRef}: get: operationId: getSubscriptionCustomer summary: Read a customer summary by your reference tags: [Subscriptions] description: | URL-encode the reference. Only the reference is accepted here; by id, use `GET /subscriptions/customers?buyerId=`. Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionCustomerRef' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionCustomerSummary' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/customers/{externalCustomerRef}/payment-reports: post: operationId: createSubscriptionPaymentReport summary: Report a transfer the customer says it made tags: [Subscriptions] description: | A pending report: it moves no balance until the seller confirms it in Admin («Pagos informados»), which records one collection per subscription. One report per customer may name cuotas and one-off charges (`oneOffChargeIds`) of several of its subscriptions, all posted, unpaid and in one currency. `paymentAccountId` must be one of the payment instructions' `methods` offered for every subscription it pays (the seller's transfer accounts turned on for subscriptions at that branch, or the branch's cash). Without partial payments on any involved subscription, `amountMinor` cannot be below what the named cuotas owe. Refusals: 400 `SUBSCRIPTION_PAYMENT_REPORT_INVALID`. Emits `payment.reported`. Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/SubscriptionCustomerRef' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionPaymentReportCreate' responses: '201': description: Created content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionPaymentReport' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/payment-reports: get: operationId: listSubscriptionPaymentReports summary: List reported payments tags: [Subscriptions] description: | Newest first. A receipt is described by its metadata only; the file is readable by the customer's portal session and by the seller in Admin, never through a permanent URL. Needs a key with access to every branch. Requires `subscriptions:read` scope. parameters: - { name: status, in: query, required: false, schema: { type: string, enum: [pending, confirmed, rejected] }, } - $ref: '#/components/parameters/SubscriptionBuyerIdQuery' - $ref: '#/components/parameters/SubscriptionLimit' - $ref: '#/components/parameters/SubscriptionOffset' responses: '200': description: OK content: application/json: schema: type: object required: [data, hasMore] properties: data: type: array items: { $ref: '#/components/schemas/SubscriptionPaymentReport' } hasMore: { type: boolean } '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts: get: operationId: listSubscriptionContracts summary: List the contracts of one buyer tags: [Subscriptions] description: | Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionBuyerIdQuery' - $ref: '#/components/parameters/SubscriptionExternalRefQuery' - $ref: '#/components/parameters/SubscriptionLimit' - $ref: '#/components/parameters/SubscriptionOffset' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionContractList' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' post: operationId: createSubscriptionContract summary: Create a contract draft and prepare its first cycle tags: [Subscriptions] description: | A draft creates no debt, coverage or invoice. Accept it with `POST /subscriptions/drafts/{draftId}/accept`. The body names its lines, discounts and agreed prices by line key (`SubscriptionContractCreate`). Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionContractCreate' responses: '201': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/drafts/{draftId}: get: operationId: getSubscriptionDraft summary: Read a contract draft and its prepared cycles tags: [Subscriptions] description: | Returns the draft's `lines` (see `SubscriptionLine`) and its prepared cycles with their `pricingBreakdown`. Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionDraftId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/drafts/{draftId}/units: get: operationId: getSubscriptionUnitDetails summary: Read optional unit details for a draft or accepted subscription tags: [Subscriptions] description: Requires subscriptions:read. Use the draftId throughout the subscription lifecycle. parameters: - $ref: '#/components/parameters/SubscriptionDraftId' responses: '200': description: Every line of the subscription with its units and descriptive revision. content: application/json: schema: type: object properties: data: type: object properties: lines: type: array items: allOf: - $ref: '#/components/schemas/SubscriptionUnitLine' - type: object required: [lineId] properties: lineId: { type: string, format: uuid } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } put: operationId: updateSubscriptionUnitDetails summary: Replace the optional descriptions of one subscription line tags: [Subscriptions] description: | Requires subscriptions:write and Idempotency-Key. `lineId` names the line (see `GET .../units` or the contract's `lines`). This replaces ONLY that line's descriptions: send all units to retain; [] clears them. Omitted unit ids reuse the existing identity at the same position. Read the response to obtain generated ids. expectedRevision is the unit-details revision, independent of billing revisions. Names and metadata never change quantities, charges, permissions or entitlement. A quantity reduction preserves descriptions outside the new quantity until explicitly cleared. Works on a draft and on an accepted contract's draft (descriptions never reprice). `actor` is accepted like on the other writes; unit edits keep no audit trail yet, so it is not stored. parameters: - $ref: '#/components/parameters/SubscriptionDraftId' - name: Idempotency-Key in: header required: true schema: { type: string, maxLength: 160 } requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [lineId, expectedRevision, units] properties: lineId: { type: string, format: uuid } expectedRevision: { type: integer, minimum: 0 } units: type: array maxItems: 1000 items: { $ref: '#/components/schemas/SubscriptionUnitDetails' } actor: { $ref: '#/components/schemas/SubscriptionActor' } responses: '200': description: Saved units and their new descriptive revision content: application/json: schema: type: object properties: data: { $ref: '#/components/schemas/SubscriptionUnitLine' } '400': { $ref: '#/components/responses/SubscriptionValidation' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } '409': { $ref: '#/components/responses/SubscriptionConflict' } /subscriptions/drafts/{draftId}/accept: post: operationId: acceptSubscriptionContract summary: Accept a draft (activate the contract) tags: [Subscriptions] description: | Uses the buyer receivable account in the contract currency. Without one, send `book.creditLimitMinor` to open it (`"0"` = no credit ceiling, an explicit decision); otherwise 409 `SUBSCRIPTION_BOOK_REQUIRED`. A draft with a setup fee on any line is accepted from Admin, where the signup charges it: here it answers 409 `SUBSCRIPTION_CONTRACT_CONFLICT` and opens no account. Requires the `customer_credit_accounts` module. Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/SubscriptionDraftId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionContractAccept' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}: get: operationId: getSubscriptionContract summary: Read a contract tags: [Subscriptions] description: | Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionContract' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/entitlement: get: operationId: getSubscriptionEntitlement summary: Evaluate service entitlement now tags: [Subscriptions] description: | Derived from persisted facts at the current time; no sweep is needed. It never grants administration of another organization. Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionEntitlement' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/periods: get: operationId: listSubscriptionPeriods summary: List generated cycles with outstanding debt and pause boundaries tags: [Subscriptions] description: | Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' post: operationId: generateSubscriptionPeriod summary: Generate the next cycle tags: [Subscriptions] description: | Accrual posts the charge; prepaid creates a payable offer (not debt). Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionGeneratePeriod' responses: '201': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionPeriod' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/documents: get: operationId: listSubscriptionDocuments summary: List invoices, credit notes and non-fiscal documents tags: [Subscriptions] description: | Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionDocumentList' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/documents/{documentId}/pdf: get: operationId: downloadSubscriptionDocument summary: Download an issued document as PDF tags: [Subscriptions] description: | Requires the `orders` module. Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/SubscriptionDocumentId' responses: '200': description: OK content: application/pdf: schema: type: string format: binary '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/plan-change/preview: post: operationId: previewSubscriptionPlanChange summary: Preview a plan change (no effects) tags: [Subscriptions] description: | Body: `{ lineId?, priceVersionId, expectedRevision, timing?: "immediate" | "next_period", pricingExchangeRate? }`. Changes the plan of one line. `lineId` may be omitted while one principal plan is in force; with more, the call answers 409 `SUBSCRIPTION_LINE_REQUIRED`. Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/plan-change: post: operationId: confirmSubscriptionPlanChange summary: Confirm a reviewed plan change tags: [Subscriptions] description: | The preview body plus, for `timing: "immediate"`, `expectedEffectiveDate`, `expectedNetMinor`, `reason`; for `"next_period"`, `expectedEffectiveDate`, `expectedAmountMinor`, `reason`. A stale preview answers 409. Without `lineId` while several principal plans are in force: 409 `SUBSCRIPTION_LINE_REQUIRED`. A plan change never charges a setup fee. Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/lines: post: operationId: addSubscriptionLine summary: Add a principal plan or an add-on tags: [Subscriptions] description: | A principal plan (`role: principal`) or an add-on under the principal line `parentLineId`. It must match the subscription's frequency, renewal mode and currency, and an add-on must be offered for its principal plan. `next_period` starts it at the next cycle; `now` also bills the rest of the current cycle (409 `SUBSCRIPTION_PRICING_INVALID` with `data.reason` `proration_unavailable` when the current cycle cannot be prorated). The line's setup fee, if any, is posted now (`setupFeeOneOffId`). Requires `subscriptions:write` scope and the `customer_credit_accounts` module. parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [role, priceVersionId, expectedRevision] properties: role: { type: string, enum: [principal, addon] } parentLineId: { type: string, format: uuid, description: 'Add-ons: their principal line' } priceVersionId: { type: string, format: uuid } quantity: { type: integer, minimum: 1, maximum: 1000000 } timing: { type: string, enum: [next_period, now], default: next_period } expectedRevision: { type: integer, minimum: 1 } responses: '201': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionLineChange' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/lines/{lineId}/removal: post: operationId: removeSubscriptionLine summary: Remove a line tags: [Subscriptions] description: | A principal line leaves with its add-ons (`removedLineIds`). The last principal plan cannot be removed: cancel the subscription instead. `now` credits the unused part of the current cycle in one entry; a setup fee is never refunded. Requires `subscriptions:write` scope and the `customer_credit_accounts` module. parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/SubscriptionLineId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [expectedRevision] properties: timing: { type: string, enum: [next_period, now], default: next_period } expectedRevision: { type: integer, minimum: 1 } responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionLineChange' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/lines/{lineId}/quantity: post: operationId: setSubscriptionLineQuantity summary: Change the quantity of a line tags: [Subscriptions] description: | From the next cycle (`next_period`), or also for the rest of the current one (`now`). Requires `subscriptions:write` scope and the `customer_credit_accounts` module. parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/SubscriptionLineId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [quantity, expectedRevision] properties: quantity: { type: integer, minimum: 1, maximum: 1000000 } timing: { type: string, enum: [next_period, now], default: next_period } expectedRevision: { type: integer, minimum: 1 } responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionLineChange' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/cancellation/preview: post: operationId: previewSubscriptionCancellation summary: Preview both cancellation modes (no effects) tags: [Subscriptions] description: | Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/cancellation: post: operationId: cancelSubscriptionContract summary: Cancel at period end or immediately tags: [Subscriptions] description: | Body: `{ expectedRevision, mode, expectedEndsOn, expectedCreditMinor, unusedCredit?, reason? }` from the preview. Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/pause: post: operationId: changeSubscriptionPause summary: Pause at the period boundary, cancel a scheduled pause or resume at a boundary tags: [Subscriptions] description: | Body: `{ action: "pause" | "cancel_pause" | "resume", expectedRevision, expectedEffectiveDate, reason? }`; the boundaries come from `GET .../periods` (`pause`). Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/resume/preview: post: operationId: previewSubscriptionResume summary: Preview resuming today (no effects) tags: [Subscriptions] description: | Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionExpectedRevision' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/contracts/{contractId}/resume: post: operationId: resumeSubscriptionNow summary: Resume today with a proportional first cycle tags: [Subscriptions] description: | Body: `{ expectedRevision, expectedEffectiveDate, expectedAmountMinor, calendar?, reason? }` from the preview. Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/payment-intents/preview: post: operationId: previewSubscriptionPaymentIntent summary: Preview the amount of an online payment (no effects) tags: [Subscriptions] description: | Requires `subscriptions:read` scope. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/payment-intents: post: operationId: createSubscriptionPaymentIntent summary: Start an online payment for selected debts tags: [Subscriptions] description: | `amountMinor` (optional) is in the DEBT currency; the amount in `payCurrency` is computed by Morsis. The checkout return is never proof of payment: poll the intent or listen to `payment.received`. Requires `subscriptions:write` scope. parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionPaymentStartApi' responses: '201': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/payment-intents/{intentId}: get: operationId: getSubscriptionPaymentIntent summary: Read a payment intent and its confirmed status tags: [Subscriptions] description: | Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionIntentId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/events: get: operationId: listSubscriptionEvents summary: Pull subscription events (webhook fallback) tags: [Subscriptions] description: | Ordered by creation; pass the last `id` as `after`. Delivery order of webhooks is not guaranteed: re-read the resource when in doubt. Requires `subscriptions:read` scope. parameters: - $ref: '#/components/parameters/SubscriptionAfter' - $ref: '#/components/parameters/SubscriptionEventsLimit' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionEventPage' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/webhook-endpoints: get: operationId: listSubscriptionWebhookEndpoints summary: List subscription webhook endpoints tags: [Subscriptions] description: | Endpoints registered from Admin or through this API. The signing secret is never listed. Requires `subscriptions:webhooks` scope and a key that reaches every branch. responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: type: array items: { $ref: '#/components/schemas/SubscriptionWebhookEndpoint' } '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' post: operationId: createSubscriptionWebhookEndpoint summary: Register a subscription webhook endpoint tags: [Subscriptions] description: | Only public `https` URLs (`400 SUBSCRIPTION_WEBHOOK_URL_INVALID` otherwise). The response carries the signing secret (`whsec_…`) once: store it, it is never shown again (rotate to get a new one). The endpoint records the key that registered it. No Idempotency-Key replay: retrying registers another endpoint. Events are POSTed with the headers `Morsis-Event`, `Morsis-Event-Id`, `Morsis-Idempotency-Key`, `Morsis-Schema-Version` and `Morsis-Signature`, and retried with backoff (up to 8 attempts). Delivery order is not guaranteed: dedupe by event id and compare `aggregateVersion`. Requires `subscriptions:webhooks` scope and a key that reaches every branch. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionWebhookEndpointCreate' responses: '201': description: OK content: application/json: schema: type: object required: [data] properties: data: type: object required: [endpoint, secret] properties: endpoint: { $ref: '#/components/schemas/SubscriptionWebhookEndpoint' } secret: { type: string, description: 'Signing secret, shown only here' } '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/webhook-endpoints/{endpointId}: patch: operationId: updateSubscriptionWebhookEndpoint summary: Change a subscription webhook endpoint tags: [Subscriptions] description: | Send only the fields to change. `enabled: false` pauses deliveries. Requires `subscriptions:webhooks` scope and a key that reaches every branch. parameters: - $ref: '#/components/parameters/SubscriptionWebhookEndpointId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionWebhookEndpointUpdate' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionWebhookEndpoint' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' delete: operationId: deleteSubscriptionWebhookEndpoint summary: Remove a subscription webhook endpoint tags: [Subscriptions] description: | Removes the endpoint and its delivery history. Requires `subscriptions:webhooks` scope and a key that reaches every branch. parameters: - $ref: '#/components/parameters/SubscriptionWebhookEndpointId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: type: object required: [ok] properties: ok: { type: boolean, const: true } '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/webhook-endpoints/{endpointId}/rotate-secret: post: operationId: rotateSubscriptionWebhookSecret summary: Rotate the signing secret of an endpoint tags: [Subscriptions] description: | The old secret stops signing at once. The new one is returned here only. Requires `subscriptions:webhooks` scope and a key that reaches every branch. parameters: - $ref: '#/components/parameters/SubscriptionWebhookEndpointId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: type: object required: [secret] properties: secret: { type: string, description: 'New signing secret, shown only here' } '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/portal-sessions: post: operationId: createSubscriptionPortalSession summary: Open a buyer portal session for your logged-in user tags: [Subscriptions] description: | Server-to-server only: never call it from a browser. Like a Stripe billing portal session: you decide who the user is (`actor`, recorded on every portal action, not verified by Morsis) and what they may do (`role`: `viewer` views; `billing` also pays; `admin` also changes plan, pauses, resumes, cancels and subscribes). The seller portal policy still narrows the role. No representative is needed. Hand `token` to the embedded SDK (section or modal) or redirect to `portalUrl` (carries only a one-time `code`, valid 2 minutes). Sessions last 10 minutes and die with the API key; a session bound to `origin` refuses requests without an `Origin` header. Idempotency keys of portal actions are scoped to this key, the buyer and `actor.id`. Requires `subscriptions:portal` scope. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionPortalSessionCreate' responses: '201': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionPortalSession' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /subscriptions/portal-sessions/revoke: post: operationId: revokeSubscriptionPortalSessions summary: Revoke sessions this key opened (e.g. on logout) tags: [Subscriptions] description: | Either `sessionIds`, or a buyer (exactly one of `buyerId` or `externalCustomerRef`) with an optional `actorId`: revokes every open session this key opened for that buyer (and actor). Sessions opened by another key are never touched. Requires `subscriptions:portal` scope. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionPortalSessionRevoke' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: type: object required: [revoked] properties: revoked: { type: integer, description: 'Sessions revoked by this call' } '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/login/code: post: operationId: requestPortalLoginCode summary: 'Standalone access: email a login code' tags: [Subscriptions portal] description: | No authentication. The answer is identical whether or not the email holds a delegation (no code is sent without one). security: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PortalLoginCode' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/login/verify: post: operationId: verifyPortalLoginCode summary: 'Standalone access: verify the code and open sessions' tags: [Subscriptions portal] description: | Returns one session per delegation the email holds at this seller (explicit representatives, plus a person buyer whose verified Morsis identity is this email). security: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PortalLoginVerify' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/sessions/exchange: post: operationId: exchangePortalCode summary: Swap a one-time code for a session token tags: [Subscriptions portal] description: | The code dies on first use and the session token rotates. security: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PortalExchange' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/me: get: operationId: getPortalOverview summary: Session, buyer, rights and every contract with status and allowed actions tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/logout: post: operationId: portalLogout summary: End this session tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/plans: get: operationId: listPortalPlans summary: Plans the buyer may subscribe or change to tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/contracts/{contractId}: get: operationId: getPortalContract summary: 'Contract detail: periods, one-off charges, debt, pause boundaries, entitlement' tags: [Subscriptions portal] description: | `oneOffCharges` lists the posted one-off charges (equipment, setup) with `outstandingMinor`, `dueDate` (the cuota it was billed with, else the day it was charged) and `paymentDueStatus`, like the periods. `discountEnds` says until when each discount of a cuota's `pricingBreakdown` applies, by `discountId`: `lastCuota` is the last cuota it reaches (`startDate`, `endDate` exclusive), `null` when it has no end. Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionContractId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/contracts/{contractId}/documents: get: operationId: listPortalDocuments summary: Invoices, credit notes and non-fiscal documents tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionContractId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionDocumentList' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/contracts/{contractId}/payments/preview: post: operationId: previewPortalPayment summary: Preview a payment (pay right) tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionContractId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionPaymentStart' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/contracts/{contractId}/payments: post: operationId: startPortalPayment summary: Start a payment (pay right) tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionPaymentStart' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/payments/{intentId}: get: operationId: getPortalPayment summary: Payment status (confirmed only by the backend) tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionIntentId' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/contracts/{contractId}/plan-change/preview: post: operationId: previewPortalPlanChange summary: Preview a plan change (manage right + seller policy) tags: [Subscriptions portal] description: | Body: `{ lineId?, priceVersionId, expectedRevision, timing? }`. One line changes; without `lineId` while several principal plans are in force, 409 `SUBSCRIPTION_LINE_REQUIRED`. Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionContractId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/contracts/{contractId}/plan-change: post: operationId: confirmPortalPlanChange summary: Confirm a plan change tags: [Subscriptions portal] description: | The preview body plus `expectedEffectiveDate` and `expectedAmountMinor`. The buyer changes the plan of a line but never adds or removes a principal plan. Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/contracts/{contractId}/cancellation/preview: post: operationId: previewPortalCancellation summary: Preview cancellation tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionContractId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionExpectedRevision' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/contracts/{contractId}/cancellation: post: operationId: confirmPortalCancellation summary: Cancel with the accepted rule tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/contracts/{contractId}/pause: post: operationId: changePortalPause summary: Pause, cancel a scheduled pause or resume at a boundary tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/contracts/{contractId}/resume/preview: post: operationId: previewPortalResume summary: Preview resuming today tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionContractId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionExpectedRevision' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/contracts/{contractId}/resume: post: operationId: resumePortalNow summary: Resume today tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/payment-instructions: get: operationId: getPortalPaymentInstructions summary: Ways to pay besides Mercado Pago and the cuotas that can be reported tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID`, 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (the session is not Pagos or more, or the seller does not allow «Informar pago»). security: [{ portalSession: [] }] responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionPaymentInstructions' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/payment-reports: get: operationId: listPortalPaymentReports summary: The customer's reported payments tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). A rejected report carries the seller's `rejectionReason`. security: [{ portalSession: [] }] responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: type: array items: { $ref: '#/components/schemas/SubscriptionPaymentReport' } '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' post: operationId: createPortalPaymentReport summary: Report a transfer («Informar pago») tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID`, 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (the session is not Pagos or more, or the seller does not allow «Informar pago»). Same rules as `POST /subscriptions/customers/{externalCustomerRef}/payment-reports`; the receipt is the `fileKey` of `POST /portal/payment-reports/receipt-upload`. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionPaymentReportBody' responses: '201': description: Created content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionPaymentReport' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/payment-reports/receipt-upload: post: operationId: createPortalReceiptUpload summary: Get a presigned upload for a transfer receipt tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID`, 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (the session is not Pagos or more, or the seller does not allow «Informar pago»). Returns a short-lived presigned URL: `PUT` the file bytes there directly (not through this API) with the returned `headers`. Image (JPG, PNG, WEBP) or PDF, at most 10 MB. 503 `SUBSCRIPTION_PAYMENT_RECEIPT_UPLOAD_UNAVAILABLE` when the environment cannot sign uploads. security: [{ portalSession: [] }] requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [contentType, sizeBytes] properties: contentType: { type: string, enum: [application/pdf, image/jpeg, image/png, image/webp] } sizeBytes: { type: integer, minimum: 1, maximum: 10485760 } responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: type: object required: [uploadUrl, fileKey, headers, expiresAt] properties: uploadUrl: { type: string, format: uri } fileKey: { type: string } headers: { type: object, additionalProperties: { type: string } } expiresAt: { type: string, format: date-time } '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/payment-reports/{reportId}/receipt: get: operationId: downloadPortalPaymentReceipt summary: Download the receipt of one of the customer's reports tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). 404 for a report of another customer or without a receipt. security: [{ portalSession: [] }] parameters: - { name: reportId, in: path, required: true, schema: { type: string, format: uuid } } responses: '200': description: OK content: application/pdf: schema: { type: string, format: binary } image/*: schema: { type: string, format: binary } '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/subscriptions: post: operationId: portalSubscribe summary: Subscribe to a plan (seller allows it) tags: [Subscriptions portal] description: | Authenticated by `Authorization: Bearer mps_…` (portal session). Denials: 401 `SUBSCRIPTION_PORTAL_SESSION_INVALID` (expired/revoked, representative or API key gone), 403 `SUBSCRIPTION_PORTAL_FORBIDDEN` (right or seller rule, or an origin-bound session called without that `Origin`), 404 for any contract of another buyer. security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionAnyBody' responses: '200': description: OK content: application/json: schema: type: object required: [data] properties: data: $ref: '#/components/schemas/SubscriptionData' '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' /portal/contracts/{contractId}/documents/{documentId}/pdf: get: operationId: downloadPortalDocument summary: Download an issued document tags: [Subscriptions portal] description: | security: [{ portalSession: [] }] parameters: - $ref: '#/components/parameters/SubscriptionContractId' - $ref: '#/components/parameters/SubscriptionDocumentId' responses: '200': description: OK content: application/pdf: schema: type: string format: binary '400': $ref: '#/components/responses/SubscriptionValidation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/SubscriptionConflict' '429': $ref: '#/components/responses/RateLimited' webhooks: catalog.changed: post: operationId: catalogChangedWebhook summary: What the online store sells may have changed description: | Sent after a write that may change what `GET /catalogs/{catalogId}` returns for a branch: a catalog edit or publish, a branch's availability, a branch activated, deactivated or switched to another catalog, or the organization's conflict policy. The event carries no catalog data. Read the catalog again and compare it with what the store last built before acting: an event can arrive for a change that leaves the response as it was. Delivery is best effort: each event is sent once and retried once after a second, with a 5 second timeout and no redirects followed. Changes made through imports or tools outside the admin panel and the POS send no event. A store that must not miss a change also compares the catalog on a schedule. **Verifying the signature.** `Morsis-Signature` is `t=,v1=`, where `v1` is the HMAC-SHA256 of `.` keyed with the signing secret (the whole `whsec_…` string, shown once when the webhook is set up or its secret rotated). Compute it over the raw bytes received, before parsing the JSON, and compare in constant time. tags: [Webhooks] security: [] parameters: - $ref: '#/components/parameters/WebhookEventHeader' - $ref: '#/components/parameters/WebhookIdempotencyKeyHeader' - $ref: '#/components/parameters/WebhookSignatureHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CatalogChangedEvent' responses: '2XX': description: Event received. Answer quickly and do the rebuild asynchronously. site.content_published: post: operationId: siteContentPublishedWebhook summary: A new version of a site's content may be out description: | Sent to `POST {site url}/api/webhooks/site-content` after each publish of a site's content, rollbacks included. Compare `data.version` with the version the live pages were built from and rebuild only when it differs, reading `GET /sites/{siteId}/content`. Same delivery and signature as `catalog.changed` (sent once and retried once after a second, 5 second timeout, no redirects followed), keyed with the **site's** secret (`whsec_…`, shown once when the site is created or its secret rotated). Answer `204` to a valid signature and `401` to an invalid one or one older than five minutes. tags: [Webhooks] security: [] parameters: - $ref: '#/components/parameters/WebhookEventHeader' - $ref: '#/components/parameters/WebhookIdempotencyKeyHeader' - $ref: '#/components/parameters/WebhookSignatureHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SiteContentPublishedEvent' responses: '2XX': description: Event received. Answer quickly and rebuild asynchronously. webhook.test: post: operationId: webhookTestEvent summary: Test event sent from the admin panel description: | Sent once, with the same headers and signature as `catalog.changed`, when "Send test event" is used for the Public API webhook in the admin panel, with the `organizationId`. tags: [Webhooks] security: [] parameters: - $ref: '#/components/parameters/WebhookEventHeader' - $ref: '#/components/parameters/WebhookIdempotencyKeyHeader' - $ref: '#/components/parameters/WebhookSignatureHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookTestEvent' responses: '2XX': description: Event received. components: securitySchemes: apiKey: type: http scheme: bearer description: 'API key with `mk_live_` prefix' portalSession: type: http scheme: bearer description: 'Buyer portal session with `mps_` prefix (30 minutes). Never a seller API key.' parameters: siteId: name: siteId in: path required: true schema: type: string format: uuid branchId: name: branchId in: path required: true schema: type: string format: uuid catalogId: name: catalogId in: path required: true schema: type: string format: uuid catalogBranchId: name: branchId in: query required: false description: | Resolve the catalog using this branch's published local overrides and branch-local entities. The branch must be inside the authenticated API key's branch scope. Unknown, foreign, and unauthorized IDs all return the same `404 Branch not found` response. Omit this parameter for the organization-wide master catalog. Stock is per branch, so only a branch-scoped read reports `inStock`. When the branch does not sell without stock, out-of-stock products come back with `isAvailable: false` and out-of-stock options are left out of their groups. schema: type: string format: uuid cartId: name: cartId in: path required: true schema: type: string format: uuid itemId: name: itemId in: path required: true description: Line item ID returned when adding the item schema: type: string IdempotencyKey: name: Idempotency-Key in: header required: false description: | Optional idempotency key for safe retries of cart mutations (create cart, add/update/remove item, create checkout session). Retrying with the same key replays the original response without repeating the effect. Reusing a key with a different request payload (or, for checkout sessions, a different cart) is rejected with a 409 `IDEMPOTENCY_CONFLICT`. schema: type: string minLength: 1 maxLength: 160 WebhookEventHeader: name: Morsis-Event in: header required: true description: The event type, the same as the body's `type`. schema: type: string enum: [catalog.changed, site.content_published, webhook.test] WebhookIdempotencyKeyHeader: name: Morsis-Idempotency-Key in: header required: true description: The event id, the same as the body's `id`. The retry repeats it. schema: type: string example: evt_5f0c2a9e8b1d4c6f9a3e7b2d1c0f4a8e WebhookSignatureHeader: name: Morsis-Signature in: header required: true description: | `t=,v1=.">`, keyed with the signing secret. schema: type: string example: t=1791230400,v1=3f8a1c0e9b7d6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f legacyCatalogBranchId: name: branch_id in: query required: false description: Compatibility alias for branchId. Prefer branchId. If both are sent, values must match. schema: type: string format: uuid deprecated: true orderId: name: orderId in: path required: true schema: type: string format: uuid orderIdempotencyKey: name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 120 description: Required for every order command. Reuse the same key and identical payload for retries. On external completion this must equal externalOperationId. lineItemId: name: lineItemId in: path required: true schema: type: string format: uuid description: Line identifier from items[].lineItemId. SubscriptionPlanId: { name: planId, in: path, required: true, schema: { type: string, format: uuid } } SubscriptionBuyerId: { name: buyerId, in: path, required: true, schema: { type: string, format: uuid } } SubscriptionRepresentativeId: { name: representativeId, in: path, required: true, schema: { type: string, format: uuid } } SubscriptionDraftId: { name: draftId, in: path, required: true, schema: { type: string, format: uuid } } SubscriptionLineId: { name: lineId, in: path, required: true, schema: { type: string, format: uuid } } SubscriptionContractId: { name: contractId, in: path, required: true, schema: { type: string, format: uuid } } SubscriptionDocumentId: { name: documentId, in: path, required: true, schema: { type: string, format: uuid } } SubscriptionIntentId: { name: intentId, in: path, required: true, schema: { type: string, format: uuid } } SubscriptionWebhookEndpointId: { name: endpointId, in: path, required: true, schema: { type: string, format: uuid } } SubscriptionCustomerRef: { name: externalCustomerRef, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 160 }, } SubscriptionBuyerIdQuery: { name: buyerId, in: query, required: false, schema: { type: string, format: uuid } } SubscriptionExternalRefQuery: { name: externalCustomerRef, in: query, required: false, schema: { type: string } } SubscriptionLimit: { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 100, default: 25 }, } SubscriptionOffset: { name: offset, in: query, required: false, schema: { type: integer, minimum: 0, default: 0 }, } SubscriptionAfter: { name: after, in: query, required: false, schema: { type: string, format: uuid } } SubscriptionEventsLimit: { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 200, default: 50 }, } responses: Unauthorized: description: Missing, invalid, revoked, or expired API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHORIZED message: Invalid, revoked, or expired API key headers: WWW-Authenticate: schema: type: string example: Bearer realm="Morsis API" Forbidden: description: API key does not have the required scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: FORBIDDEN message: API key does not have cart:write scope NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Catalog not found BranchNotFound: description: Branch not found, inactive, or outside the authenticated organization content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Branch not found CartNotFound: description: Cart not found, expired, or already checked out content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: CART_EXPIRED message: Cart not found, expired, or already checked out RateLimited: description: Rate limit exceeded for this API key's bucket (see Rate Limits) headers: Retry-After: description: Seconds to wait before retrying schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: RATE_LIMITED message: Rate limit exceeded. Retry after 60 seconds. IdempotencyConflict: description: The idempotency key was already used with a different request payload content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: IDEMPOTENCY_CONFLICT message: The idempotency key was already used with a different request payload InternalError: description: Unexpected server failure. Retry only when safe; include X-Request-Id when reporting the failure. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL_ERROR message: The request could not be completed MethodNotAllowed: description: The path exists but does not support this HTTP method. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: METHOD_NOT_ALLOWED message: Method not supported for this endpoint headers: Allow: description: Supported HTTP methods for this path. schema: type: string example: GET, OPTIONS Order: description: The order after the operation content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Order' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid OrderList: description: Matching orders content: application/json: schema: type: object required: - data - meta properties: data: type: array items: anyOf: - $ref: '#/components/schemas/OrderSummary' - $ref: '#/components/schemas/Order' meta: $ref: '#/components/schemas/CursorPagination' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid OrderBadRequest: description: Invalid parameters, headers or request payload (VALIDATION_ERROR, OPTION_INVALID_FOR_PRODUCT). error.details names each invalid field. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: VALIDATION_ERROR message: 'branchId: Invalid UUID' details: - path: branchId message: Invalid UUID headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid OrderNotFound: description: Order, item or payment not found, or outside the key's branch scope (NOT_FOUND, ITEM_NOT_FOUND, PAYMENT_NOT_FOUND) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Order not found headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid OrderConflict: description: The command cannot apply to the order in its current state. Known codes include ORDER_VERSION_CONFLICT, ORDER_NOT_EDITABLE, ORDER_BUSY, ORDER_CONFLICT, AMOUNT_MISMATCH, UNSUPPORTED_ORDER, UNSUPPORTED_ITEM, BRANCH_NOT_AVAILABLE, PRODUCT_UNAVAILABLE, INSUFFICIENT_STOCK, ORDER_NOT_REVERSIBLE, ORDER_HAS_REFUNDS, CREDIT_NOTE_MISMATCH, CREDIT_NOTE_ALREADY_RECORDED, ITEM_NOT_REFUNDABLE, ISSUER_TAX_ID_NOT_ALLOWED and IDEMPOTENCY_CONFLICT. ISSUER_TAX_ID_NOT_ALLOWED means the API key is linked to a collector company and the invoice issuerTaxId is not one of that company's tax IDs. CREDIT_NOTE_ALREADY_RECORDED means the sale already has a credit note with the same externalOperationId, or with the same typeCode, pointOfSale and number. No writes are committed. Reread the order before sending another command. INSUFFICIENT_STOCK means the branch does not sell without stock and an added or updated item exceeds it. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: ORDER_VERSION_CONFLICT message: Read the order again before changing it headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid OrderPayloadTooLarge: description: Request body exceeds 64 KiB (PAYLOAD_TOO_LARGE) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Server-generated identifier for this request. schema: type: string format: uuid SubscriptionValidation: description: Validation error (`VALIDATION_ERROR`, e.g. missing Idempotency-Key) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' SubscriptionConflict: description: | Stable conflict codes: `SUBSCRIPTION_CONTRACT_CONFLICT` (stale `expectedRevision` or preview), `SUBSCRIPTION_IDEMPOTENCY_CONFLICT` (key reused with another request), `SUBSCRIPTION_IDEMPOTENCY_IN_PROGRESS`, `SUBSCRIPTION_BOOK_REQUIRED`, `SUBSCRIPTION_REPRESENTATIVE_CONFLICT`, `SUBSCRIPTION_BUYER_REFERENCE_CONFLICT` (the reference names another buyer, or the buyer has another one), `SUBSCRIPTION_PLAN_NOT_SELF_SERVICE` (buyer portal only: the plan is an add-on, has a per-unit or tiered price, or a setup fee, so only the seller can contract it), `SUBSCRIPTION_LINE_REQUIRED` (a plan change without `lineId` while several principal plans are in force: send the line), `SUBSCRIPTION_PRICING_INVALID` (a line that does not fit the subscription; `data.reason` tells why). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' CartWriteConflict: description: > The idempotency key was already used with a different request payload (`IDEMPOTENCY_CONFLICT`), or the branch does not have enough stock for the requested quantity (`INSUFFICIENT_STOCK`) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: idempotencyConflict: value: error: code: IDEMPOTENCY_CONFLICT message: The idempotency key was already used with a different request payload insufficientStock: value: error: code: INSUFFICIENT_STOCK message: Not enough stock for product 7f3c2a1e-0b4d-4c8e-9a51-2d6f8e0c4b19 at this branch schemas: PickupLocation: type: object required: [id, name, serviceMode, address, openingHours, feeCents] properties: id: type: string format: uuid name: type: string serviceMode: type: string enum: [pickup, takeaway] description: Actual branch catalog modality used for this pickup location. address: type: [object, 'null'] description: Public pickup address, excluding internal notes and identifiers. properties: street: type: string streetNumber: type: string floor: type: string apartment: type: string unit: type: string city: type: string state: type: string zipCode: type: string country: type: string openingHours: type: [object, 'null'] description: Weekly mon-sun intervals with open/close in HH:mm, optionally with calendar details. feeCents: type: integer const: 0 ProductSuggestionList: type: object required: [data, meta] properties: data: type: array description: Best first. Empty when there is nothing to suggest or suggestions could not be computed. items: $ref: '#/components/schemas/ProductSuggestion' meta: type: object required: [decisionId, stamp] properties: decisionId: type: string maxLength: 64 description: | Identifies this answer. Echo it in the `suggestion` of the cart items added from it, so the sale is attributed to the suggestion. stamp: type: [string, 'null'] description: Version of the learned data behind the ranking; null when suggestions could not be computed. ProductSuggestion: type: object required: [product, source, rank, reasonProductId] properties: product: $ref: '#/components/schemas/Product' source: type: string description: | Why it is suggested. `manual`: a recommendation set by the merchant. `affinity`: customers buy it together with the anchor. `role`: it complements the anchor (for catalogs with few sales). `fallback`: a best seller. Treat unknown values as an automatic suggestion. x-known-values: [manual, affinity, role, fallback] rank: type: integer minimum: 0 description: 0-based position in the ranking. reasonProductId: type: [string, 'null'] format: uuid description: The anchor (viewed or cart product) that contributed most; null for best sellers. CartItemSuggestion: type: object additionalProperties: false description: | The suggestion the item was added from. Copy `decisionId` from the suggestions response `meta`, and `source` and `rank` from the picked entry. Stored with the order line to measure what suggestions sell. required: [decisionId, source, rank, placement] properties: decisionId: type: string minLength: 1 maxLength: 64 source: type: string enum: [manual, affinity, role, fallback] rank: type: integer minimum: 0 maximum: 50 placement: type: string enum: [product_detail, pre_payment] description: '`product_detail` for `getProductSuggestions`, `pre_payment` for `suggestForCart`.' PickupAvailability: type: object required: [productId, locations] properties: productId: type: string format: uuid locations: type: array description: Every pickup location offered to this key, in the same order as /shipping/policies. items: allOf: - $ref: '#/components/schemas/PickupLocation' - type: object required: [status] properties: status: type: string enum: [available, low_stock, out_of_stock, unavailable] description: | `available`: 3 or more units, or the product does not track stock. `low_stock`: 1 or 2 units. `out_of_stock`: none on hand. `unavailable`: the store does not sell this product for pickup (hidden at that branch, not offered in its pickup modality, or the branch sells another catalog). ShippingPolicies: type: object required: [configured, currency, revision, dispatchBranchId, pickupLocations, providers] properties: configured: type: boolean currency: type: string const: ARS revision: type: [string, 'null'] dispatchBranchId: type: [string, 'null'] format: uuid description: | Branch or warehouse every home delivery ships from, whatever branch the cart was created at. Read the catalog with this `branchId` to show stock for home delivery. Null when no home delivery is offered to this key; `providers` is then empty. pickupLocations: type: array items: $ref: '#/components/schemas/PickupLocation' providers: type: array items: type: object required: [ provider, enabled, name, pricing, fixedCents, percentageBps, minimumCents, freeFromCents, postalCodes, deliveryDescription, ] properties: provider: type: string enum: [manual, correo_argentino, andreani, pedidosya_envios] enabled: type: boolean const: true name: type: string pricing: type: string enum: [fixed, order_total, carrier] fixedCents: type: integer minimum: 0 percentageBps: type: integer minimum: 0 maximum: 10000 minimumCents: type: integer minimum: 0 freeFromCents: type: [integer, 'null'] minimum: 0 postalCodes: type: array items: type: string pattern: '^\d{4}$' deliveryDescription: type: string PublicCustomer: type: object required: - id - organizationCustomerId - kind - name - email - phone - documentNumber - documentType - instagram - createdAt properties: id: type: string format: uuid organizationCustomerId: type: string format: uuid kind: type: string description: 'Known values: person, company.' name: type: - string - 'null' email: type: - string - 'null' phone: type: - string - 'null' documentNumber: type: - string - 'null' documentType: type: - string - 'null' instagram: type: - string - 'null' createdAt: type: string format: date-time PublicCustomerCreate: type: object additionalProperties: false description: 'A person requires email or phone. A company requires name. A supplied name must have at least 3 characters. documentType requires a nonempty documentNumber. Existing contacts of the same kind may match by email or phone: creation then fills missing fields without overwriting existing values.' properties: name: type: string maxLength: 200 minLength: 3 email: type: string format: email maxLength: 254 phone: type: string minLength: 1 maxLength: 50 documentNumber: type: string maxLength: 50 documentType: type: string minLength: 1 maxLength: 30 kind: type: string enum: - person - company default: person example: name: Ana Pérez email: ana@example.com phone: '+5491123456789' PublicCustomerUpdate: type: object additionalProperties: false minProperties: 1 description: Only supplied fields change. A supplied name must have at least 3 characters. documentType requires a nonempty documentNumber in the same patch. Empty email/phone/documentNumber/instagram clears that field. A person must keep at least one contact method (or an existing face identity). Null and unknown fields are rejected. Identity data may be shared with other organization links of the same customer. properties: name: type: string maxLength: 200 minLength: 3 email: type: string maxLength: 254 description: Valid email or empty string to clear. phone: type: string maxLength: 50 documentNumber: type: string maxLength: 50 documentType: type: string minLength: 1 maxLength: 30 instagram: type: string maxLength: 100 example: name: Ana Pérez Gómez PublicTeamMember: type: object required: - id - userId - name - email - role - roleId - jobTitle - branchIds - joinedAt properties: id: type: string format: uuid description: Organization membership ID, used as memberId in routes. Distinct from userId. userId: type: string format: uuid name: type: - string - 'null' email: type: string role: type: string roleId: type: string format: uuid jobTitle: type: - string - 'null' branchIds: type: - array - 'null' items: type: string format: uuid description: null grants every branch; an array grants only the listed branches. joinedAt: type: string format: date-time PublicMemberUpdate: type: object additionalProperties: false minProperties: 1 description: Only jobTitle and branchIds can change. role and roleId are rejected with 400, including when combined with valid fields. properties: jobTitle: type: string maxLength: 200 branchIds: type: - array - 'null' items: type: string format: uuid description: null grants every branch; an array grants only the listed branches. maxItems: 100 example: jobTitle: Ventas PublicInvitationCreate: type: object additionalProperties: false required: - email - role properties: email: type: string format: email maxLength: 254 role: type: string minLength: 1 maxLength: 100 jobTitle: type: string maxLength: 200 message: type: string maxLength: 2000 branchIds: type: array items: type: string format: uuid maxItems: 100 description: Omission inherits the API key branch assignment. example: email: integrante@example.com role: staff jobTitle: Ventas PublicTeamInvitation: type: object required: - id - email - role - jobTitle - branchIds - status - createdAt - expiresAt properties: id: type: string format: uuid email: type: string role: type: string jobTitle: type: - string - 'null' branchIds: type: - array - 'null' items: type: string format: uuid description: null grants every branch; an array grants only the listed branches. status: type: string description: 'Known values: pending, accepted, expired, cancelled. The list includes pending records; inspect expiresAt.' createdAt: type: string format: date-time expiresAt: type: string format: date-time PublicTeamRole: type: object required: - id - slug - name - hierarchy - isSystem properties: id: type: string format: uuid slug: type: string name: type: string hierarchy: type: integer isSystem: type: boolean PeoplePageMeta: type: object required: - cursor - hasMore properties: cursor: type: - string - 'null' description: Pass unchanged as cursor on the next request, preserving query. hasMore: type: boolean OrderSummary: type: object description: Bounded collection projection. Use GET /orders/{orderId} for lines, customer, taxes, payments, refunds, invoices and the version needed for commands. required: - id - orderNumber - branchId - paymentCoupon - currency - totalCents - preparationStatus - fulfillmentStatus - paymentStatus - createdAt - completedAt - cancelledAt properties: id: $ref: '#/components/schemas/Order/properties/id' orderNumber: $ref: '#/components/schemas/Order/properties/orderNumber' branchId: $ref: '#/components/schemas/Order/properties/branchId' paymentCoupon: $ref: '#/components/schemas/Order/properties/paymentCoupon' currency: $ref: '#/components/schemas/Order/properties/currency' totalCents: $ref: '#/components/schemas/Order/properties/totalCents' preparationStatus: $ref: '#/components/schemas/Order/properties/preparationStatus' fulfillmentStatus: $ref: '#/components/schemas/Order/properties/fulfillmentStatus' paymentStatus: $ref: '#/components/schemas/Order/properties/paymentStatus' createdAt: $ref: '#/components/schemas/Order/properties/createdAt' completedAt: $ref: '#/components/schemas/Order/properties/completedAt' cancelledAt: $ref: '#/components/schemas/Order/properties/cancelledAt' Order: type: object description: A sale with its lines, totals, payments and fiscal documents. Amounts are integer minor units of `currency`; totalCents = subtotalCents - discountCents + deliveryFeeCents. Fields may be added; ignore unknown fields. required: - id - orderNumber - branchId - paymentCoupon - version - currency - subtotalCents - discountCents - deliveryFeeCents - totalCents - taxBreakdown - preparationStatus - fulfillmentStatus - paymentStatus - serviceMode - createdAt - completedAt - cancelledAt - customer - items - payments - refunds - invoices properties: id: type: string format: uuid orderNumber: type: - string - 'null' branchId: type: string format: uuid paymentCoupon: description: The payment coupon that identifies this order, or null. anyOf: - type: object required: - code properties: code: type: string description: Barcode as a string, including leading zeros. - type: 'null' version: type: string description: Opaque revision token. Send it unchanged as expectedVersion in the next command; do not parse it. currency: type: string description: ISO 4217 code. Currently always ARS. subtotalCents: type: integer description: Sum of items[].totalCents. discountCents: type: integer description: Order-level discount actually applied, after line prices. Negative for a net order-level surcharge. deliveryFeeCents: type: integer minimum: 0 totalCents: type: integer minimum: 0 taxBreakdown: type: array description: Tax included in totalCents, by rate, with the order-level discount prorated and the delivery fee at the default rate. Buckets add up to totalCents. Informational for an external issuer, who applies its own tax rules. items: $ref: '#/components/schemas/TaxBucket' preparationStatus: type: string description: 'Current preparation stage. Known values: pending, confirmed, preparing, ready, completed, cancelled, in_table. Treat new values as unknown states.' fulfillmentStatus: type: - string - 'null' description: 'Delivery/service stage, or null before fulfillment. Known values: waiting, picked_up, served, driver_assigned, in_transit, delivered.' paymentStatus: type: string description: 'Payment state. Known values: unpaid, paid, refunded.' serviceMode: type: - string - 'null' description: 'Known values include dine_in, takeaway and delivery.' createdAt: type: string format: date-time completedAt: type: - string - 'null' format: date-time cancelledAt: type: - string - 'null' format: date-time customer: anyOf: - $ref: '#/components/schemas/OrderCustomer' - type: 'null' items: type: array items: $ref: '#/components/schemas/OrderLineItem' payments: type: array description: Approved payments, collected by the merchant or reported by an external collector. items: $ref: '#/components/schemas/OrderPayment' refunds: type: array description: Refunds of those payments, made by the merchant or reported by the external collector. A payment's refunded amount is the sum of its refunds. items: $ref: '#/components/schemas/OrderRefund' invoices: type: array description: Fiscal documents issued for the order, by the merchant or by an external issuer, including credit notes (documentType). items: $ref: '#/components/schemas/OrderInvoice' example: id: 11111111-1111-4111-8111-111111111111 orderNumber: '1042' branchId: 55555555-5555-4555-8555-555555555555 paymentCoupon: code: '012345678' version: MjAyNi0xMC0xNCAxMzowMDowMC4xMjM0NTY currency: ARS subtotalCents: 2300 discountCents: 0 deliveryFeeCents: 0 totalCents: 2300 taxBreakdown: - rate: 21 netCents: 1901 taxCents: 399 preparationStatus: pending fulfillmentStatus: null paymentStatus: unpaid serviceMode: takeaway createdAt: 2026-10-14T12:58:00.000Z completedAt: null cancelledAt: null customer: null items: - lineItemId: 22222222-2222-4222-8222-222222222222 productId: 33333333-3333-4333-8333-333333333333 sku: CAFE-01 name: Café quantity: 2 priceCents: 1000 totalCents: 2300 taxRate: 21 weightKg: null notes: null options: - optionId: 44444444-4444-4444-8444-444444444444 optionGroupId: 66666666-6666-4666-8666-666666666666 optionGroupName: Leche name: Avena priceCents: 150 modifierType: increase quantity: 1 payments: [] refunds: [] invoices: [] OrderCustomer: type: object description: Commercial customer contact and the purchase's immutable invoice recipient evidence. required: [id, name, email, phone, invoiceRecipient] properties: id: type: string format: uuid name: type: [string, 'null'] email: type: [string, 'null'] phone: type: [string, 'null'] invoiceRecipient: type: [object, 'null'] description: Accepted purchase billing facts. Not a live customer profile or profile collection. required: [taxId, taxIdType, fiscalName, ivaConditionReceptor, fiscalAddress] properties: taxId: type: [string, 'null'] taxIdType: type: [string, 'null'] fiscalName: type: [string, 'null'] ivaConditionReceptor: type: [string, 'null'] fiscalAddress: type: [string, 'null'] OrderLineItem: type: object description: One line of the order, with the same option shape as cart lines. required: - lineItemId - productId - sku - name - quantity - priceCents - totalCents - taxRate - weightKg - notes - options properties: lineItemId: type: - string - 'null' format: uuid description: Use for PATCH and item-removals. Null for legacy lines, which are read-only through this API. productId: type: - string - 'null' format: uuid sku: type: - string - 'null' name: type: string quantity: type: integer minimum: 1 priceCents: type: integer description: Unit price of the product, after line-level adjustments and before option modifiers. totalCents: type: integer description: Line total including options and line-level adjustments, before the order-level discount. Authoritative for the line. taxRate: type: - number - 'null' description: Tax rate (percent) recorded at sale time, or null when the product uses the organization default. weightKg: type: - number - 'null' description: Total weight for products sold by weight; null otherwise. notes: type: - string - 'null' options: type: array items: $ref: '#/components/schemas/OrderLineItemOption' OrderLineItemOption: type: object required: - optionId - optionGroupId - optionGroupName - name - priceCents - modifierType - quantity properties: optionId: type: - string - 'null' format: uuid optionGroupId: type: - string - 'null' format: uuid optionGroupName: type: - string - 'null' name: type: string priceCents: type: integer description: Price modifier in cents, applied as modifierType indicates. modifierType: type: string description: 'How priceCents applies to the product price. Known values: increase, decrease, replace, none.' quantity: type: integer minimum: 1 description: Quantity per product unit. TaxBucket: type: object required: - rate - netCents - taxCents properties: rate: type: number description: Tax rate in percent, for example 21 or 10.5. netCents: type: integer taxCents: type: integer OrderPayment: type: object required: - id - status - collectedBy - methodId - amountCents - currency - reference - authorizationCode - card - bank - occurredAt - externalOperationId - externalDeviceId - settlementStatus - settledOn properties: id: type: string format: uuid status: type: string description: 'Known values: approved.' collectedBy: type: string description: 'Who holds the funds. Known values: merchant, external (a partner that owes them to the merchant).' methodId: type: - string - 'null' description: "Tender type. Known values are the /payment-methods IDs. Null when a merchant payment's tender is not classified." amountCents: type: integer currency: type: string reference: type: - string - 'null' description: Operation reference reported for the payment. authorizationCode: type: - string - 'null' card: anyOf: - type: object required: - type - brand - lastFour - installments properties: type: type: - string - 'null' description: 'Known values: debit, credit.' brand: type: - string - 'null' lastFour: type: - string - 'null' installments: type: - integer - 'null' - type: 'null' bank: type: - string - 'null' occurredAt: type: - string - 'null' format: date-time externalOperationId: type: - string - 'null' description: Partner operation that reported the payment; null for merchant payments. externalDeviceId: type: - string - 'null' description: Partner register that collected; null for merchant payments. settlementStatus: type: - string - 'null' description: 'For external collections, whether the merchant already recorded the partner remitting the funds. Computed at read time. Known values: pending (the collection or one of its refunds is not in an active settlement yet), settled. Null for merchant payments and when the merchant does not track third-party collections.' settledOn: type: - string - 'null' format: date description: Date of the latest active settlement covering the collection or one of its refunds. Null when none covers it, for merchant payments, and when the merchant does not track third-party collections. A pending payment may carry the date of an earlier settlement when a later refund is still pending. OrderInvoice: type: object required: - issuedBy - documentType - issuerTaxId - issuerName - typeCode - pointOfSale - number - issuedOn - totalCents - currency - authorizationCode - authorizationExpiresOn - recipientTaxId - recipientName - documentUrl properties: issuedBy: type: string description: 'Known values: merchant (issued by Morsis), external (reported by a partner and stored without fiscal verification).' documentType: type: string description: 'Known values: invoice, credit_note.' issuerTaxId: type: - string - 'null' issuerName: type: - string - 'null' typeCode: type: - integer - 'null' description: Numeric fiscal document type, for example 6 for Factura B or 8 for a Nota de crédito B. pointOfSale: type: - integer - 'null' number: type: - integer - 'null' issuedOn: type: - string - 'null' format: date totalCents: type: integer currency: type: string authorizationCode: type: - string - 'null' description: Fiscal authorization code (CAE) when known. authorizationExpiresOn: type: - string - 'null' format: date recipientTaxId: type: - string - 'null' recipientName: type: - string - 'null' documentUrl: type: - string - 'null' format: uri ExternalPaymentMethod: type: object required: - id - name - requiredFields properties: id: type: string description: 'Known values: cash, debit_card, credit_card, bank_transfer, qr, payment_link. New IDs can be added.' name: type: string requiredFields: type: array items: type: string OrderCommandContext: type: object description: Sent with every order command to attribute it. required: - actorUserId - externalDeviceId - expectedVersion properties: actorUserId: type: string format: uuid description: Morsis user who operated, created for the partner's operator. externalDeviceId: type: string minLength: 1 maxLength: 160 description: Partner register identifier, scoped by the API key. expectedVersion: type: string minLength: 1 maxLength: 100 description: version from the last order read or command response. AddOrderItemRequest: allOf: - $ref: '#/components/schemas/OrderCommandContext' - type: object required: - productId - quantity properties: productId: type: string format: uuid quantity: type: integer minimum: 1 maximum: 100 optionIds: type: array maxItems: 100 items: type: string format: uuid default: [] description: Repeat an ID to select an option more than once. notes: type: string maxLength: 2000 unevaluatedProperties: false UpdateOrderItemRequest: allOf: - $ref: '#/components/schemas/OrderCommandContext' - type: object anyOf: - required: - quantity - required: - optionIds - required: - notes properties: quantity: type: integer minimum: 1 maximum: 100 optionIds: type: array maxItems: 100 items: type: string format: uuid notes: type: string maxLength: 2000 unevaluatedProperties: false RemoveOrderItemRequest: allOf: - $ref: '#/components/schemas/OrderCommandContext' - type: object required: - lineItemId properties: lineItemId: type: string format: uuid unevaluatedProperties: false ExternalPayment: type: object additionalProperties: false required: - methodId - amountCents - reference properties: methodId: type: string enum: - cash - debit_card - credit_card - bank_transfer - qr - payment_link description: An ID from /payment-methods. amountCents: type: integer minimum: 1 maximum: 999999999999 reference: type: string minLength: 1 maxLength: 160 authorizationCode: type: string minLength: 1 maxLength: 160 cardLastFour: type: string pattern: ^\d{4}$ description: Only for debit_card or credit_card. Never send a full card number or security code. cardBrand: type: string maxLength: 40 description: Only for debit_card or credit_card. installments: type: integer minimum: 1 maximum: 99 description: Only for credit_card. bank: type: string maxLength: 100 ExternalInvoice: type: object additionalProperties: false required: - issuerTaxId - issuerName - typeCode - pointOfSale - number - issuedOn - totalCents - currency properties: issuerTaxId: type: string pattern: ^\d{11}$ issuerName: type: string minLength: 1 maxLength: 200 typeCode: type: integer minimum: 1 maximum: 999 description: Numeric invoice type code reported by the external issuer (for example, 6 for Factura B). Stored without fiscal validation. pointOfSale: type: integer minimum: 1 maximum: 99999 number: type: integer minimum: 1 maximum: 99999999 issuedOn: type: string format: date totalCents: type: integer minimum: 1 maximum: 999999999999 currency: type: string const: ARS authorizationCode: type: string pattern: ^\d{14}$ description: CAE or CAEA, 14 digits. authorizationExpiresOn: type: string format: date recipientTaxId: type: string maxLength: 30 recipientName: type: string maxLength: 200 documentUrl: type: string format: uri pattern: ^https:// maxLength: 2000 OrderRefund: type: object required: - id - paymentId - status - refundedBy - amountCents - currency - occurredAt - externalOperationId - items properties: id: type: string format: uuid paymentId: type: string format: uuid description: The refunded payment (payments[].id). status: type: string description: 'Known values: pending, completed.' refundedBy: type: string description: 'Who returned the money. Known values: merchant, external.' amountCents: type: integer currency: type: string occurredAt: type: string format: date-time externalOperationId: type: - string - 'null' description: Partner operation that reported the refund; null for merchant refunds. items: type: array description: Returned lines, when the refund was for specific goods. items: type: object required: - lineItemId - quantity properties: lineItemId: type: - string - 'null' format: uuid quantity: type: integer minimum: 1 ExternalRefundRequest: allOf: - $ref: '#/components/schemas/OrderCommandContext' - type: object required: - externalOperationId - occurredAt - payments - creditNote properties: externalOperationId: type: string minLength: 1 maxLength: 120 description: Stable partner operation ID. Must equal Idempotency-Key. occurredAt: type: string format: date-time description: When the partner refunded. At most five minutes in the future. reason: type: string minLength: 1 maxLength: 500 payments: type: array minItems: 1 maxItems: 20 items: type: object additionalProperties: false required: - paymentId - amountCents properties: paymentId: type: string format: uuid description: A payment collected by the partner (payments[].id). amountCents: type: integer minimum: 1 description: At most what is left unrefunded of that payment. items: type: array minItems: 1 maxItems: 100 description: Returned goods. Omit for an amount-only refund. items: type: object additionalProperties: false required: - lineItemId - quantity properties: lineItemId: type: string format: uuid quantity: type: integer minimum: 1 maximum: 100 creditNote: $ref: '#/components/schemas/ExternalInvoice' unevaluatedProperties: false ExternalCancellationRequest: allOf: - $ref: '#/components/schemas/OrderCommandContext' - type: object required: - externalOperationId - occurredAt - reason - creditNote properties: externalOperationId: type: string minLength: 1 maxLength: 120 description: Stable partner operation ID. Must equal Idempotency-Key. occurredAt: type: string format: date-time reason: type: string minLength: 1 maxLength: 500 description: Stored as the order's cancellation reason. creditNote: $ref: '#/components/schemas/ExternalInvoice' unevaluatedProperties: false ExternalCompletionRequest: allOf: - $ref: '#/components/schemas/OrderCommandContext' - type: object required: - externalOperationId - occurredAt - expectedTotalCents - currency - payments - invoice properties: externalOperationId: type: string minLength: 1 maxLength: 120 description: Stable partner operation ID. Must equal Idempotency-Key. occurredAt: type: string format: date-time description: When the partner collected. At most five minutes in the future. expectedTotalCents: type: integer minimum: 1 maximum: 999999999999 currency: type: string const: ARS payments: type: array minItems: 1 maxItems: 20 items: $ref: '#/components/schemas/ExternalPayment' invoice: $ref: '#/components/schemas/ExternalInvoice' unevaluatedProperties: false ShippingParcel: type: object additionalProperties: false required: [weightGrams, lengthCm, widthCm, heightCm] properties: weightGrams: type: integer minimum: 1 maximum: 50000 description: Total packed weight. MiCorreo has a lower maximum of 25000 grams. lengthCm: type: integer minimum: 1 maximum: 150 widthCm: type: integer minimum: 1 maximum: 150 heightCm: type: integer minimum: 1 maximum: 150 ShippingQuoteRequest: type: object additionalProperties: false required: [provider, originBranchId, destinationPostalCode, parcel, declaredValueCents] properties: provider: type: string enum: [correo_argentino, andreani] originBranchId: type: string format: uuid destinationPostalCode: type: string pattern: '^(?:[0-9]{4}|[A-Za-z][0-9]{4}[A-Za-z]{3})$' description: Four digits or full Argentine CPA for MiCorreo. Andreani accepts four digits only. Trimmed and uppercased. parcel: $ref: '#/components/schemas/ShippingParcel' declaredValueCents: type: integer minimum: 1 maximum: 999999999 description: Insured value in ARS cents; excluding tax for Andreani. Unused by MiCorreo rates. allOf: - if: properties: provider: { const: correo_argentino } then: properties: parcel: properties: weightGrams: { maximum: 25000 } - if: properties: provider: { const: andreani } then: properties: destinationPostalCode: { pattern: '^[0-9]{4}$' } ShippingQuote: type: object required: [ provider, currency, deliveryType, origin, originPricing, destinationPostalCode, parcel, declaredValueCents, validUntil, rates, ] properties: provider: type: string enum: [correo_argentino, andreani] currency: type: string const: ARS deliveryType: type: string const: home origin: type: object required: [branchId, postalCode] properties: branchId: type: string format: uuid postalCode: type: string originPricing: type: string enum: [postal_code, contract] destinationPostalCode: type: string parcel: $ref: '#/components/schemas/ShippingParcel' declaredValueCents: type: integer validUntil: type: [string, 'null'] description: Provider validity string when supplied (MiCorreo validTo); null for Andreani. Not a reserved price. rates: type: array items: type: object required: [serviceCode, serviceName, priceCents] properties: serviceCode: type: string description: MiCorreo product code, or home_delivery for the configured Andreani contract. serviceName: type: string priceCents: type: integer minimum: 0 maximum: 999999999 ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable machine-readable code. This set is extensible; callers must handle unknown codes using the HTTP status. See operation descriptions for domain conflicts. x-known-values: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - METHOD_NOT_ALLOWED - SERVICE_UNAVAILABLE - VALIDATION_ERROR - BRANCH_NOT_AVAILABLE - PRODUCT_UNAVAILABLE - OPTION_INVALID_FOR_PRODUCT - CART_EXPIRED - CART_ITEM_NOT_FOUND - SERVICE_MODE_NOT_ALLOWED - FULFILLMENT_MODE_MISMATCH - DELIVERY_ADDRESS_REQUIRED - INSUFFICIENT_STOCK - CHECKOUT_SESSION_NOT_FOUND - CHECKOUT_SESSION_EXPIRED - CHECKOUT_ALREADY_PAID - CHECKOUT_CANCELLED - CHECKOUT_PAYMENT_ALREADY_STARTED - CHECKOUT_NOT_AVAILABLE - CHECKOUT_EMPTY_CART - IDEMPOTENCY_CONFLICT - INVALID_PAYMENT_PROVIDER - PAYMENT_PROVIDER_NOT_AVAILABLE - NOT_CONFIGURED - VERIFICATION_FAILED - RATE_LIMITED - PAYLOAD_TOO_LARGE - INTERNAL_ERROR - ORDER_VERSION_CONFLICT - ORDER_NOT_EDITABLE - ORDER_BUSY - AMOUNT_MISMATCH - UNSUPPORTED_ORDER - UNSUPPORTED_ITEM - ITEM_NOT_FOUND - ORDER_CONFLICT - ORDER_NOT_REVERSIBLE - ORDER_HAS_REFUNDS - CREDIT_NOTE_MISMATCH - CREDIT_NOTE_ALREADY_RECORDED - ITEM_NOT_REFUNDABLE - ISSUER_TAX_ID_NOT_ALLOWED - PAYMENT_NOT_FOUND message: type: string details: type: array description: Optional validation failures. path identifies a JSON field or query parameter; (root) indicates the complete payload. items: type: object required: - path - message properties: path: type: string message: type: string MerchantLegalData: type: object required: [legalName, taxId, fiscalAddress, commercialAddress, siteUrl, dataFiscal, scope] properties: legalName: type: string description: Razón social of the publishing legal entity taxId: type: string description: CUIT of the publishing legal entity fiscalAddress: type: string commercialAddress: type: string siteUrl: type: string format: uri description: The storefront site URL declared to ARCA dataFiscal: type: object required: [url] properties: url: type: string format: uri description: Official ARCA-provided F.960/D hyperlink (verbatim) logoUrl: type: [string, 'null'] format: uri description: >- Data Fiscal logo image URL to render. When the merchant did not configure a custom logo, this is the Morsis-hosted copy of the generic F.960/D badge (same image for every merchant). logoMetadata: type: [object, 'null'] properties: width: type: integer height: type: integer altText: type: string scope: type: string enum: [branch, organization] description: Whether a branch-specific or org-wide publication answered WithdrawalRequestAcknowledgment: type: object required: [requestCode, status, receivedAt, acknowledgmentDeadlineAt, scope] properties: requestCode: type: string description: Immutable public acknowledgment code (e.g. `AR-7KQ2M9XWPL`) status: type: string enum: - received - identity_verified - under_review - approved - rejected - refund_pending - completed receivedAt: type: string format: date-time acknowledgmentDeadlineAt: type: string format: date-time description: Legal 24h ceiling for the acknowledgment (already satisfied by this response) scope: type: string enum: [full_order, items] WithdrawalRequestStatus: allOf: - $ref: '#/components/schemas/WithdrawalRequestAcknowledgment' - type: object properties: decidedAt: type: [string, 'null'] format: date-time decisionReason: type: [string, 'null'] description: Merchant decision reason (set on approval/rejection) completedAt: type: [string, 'null'] format: date-time CursorPagination: type: object required: [cursor, hasMore, total] properties: cursor: type: [string, 'null'] description: ID of the last item in the page. Pass as `cursor` query param to get the next page. hasMore: type: boolean description: Whether more items exist after this page total: type: integer description: Total number of items matching the current filters Branch: type: object required: - id - name - displayName - slug - branchType - address - timezone - openingHours - catalogId - serviceModes - availableForOrdering - selfService - reservations - links properties: id: type: string format: uuid name: type: string displayName: type: [string, 'null'] slug: type: string branchType: type: [string, 'null'] address: anyOf: - $ref: '#/components/schemas/BranchAddress' - type: 'null' timezone: type: [string, 'null'] description: IANA timezone configured for the branch openingHours: anyOf: - $ref: '#/components/schemas/WeeklyOpeningHours' - type: 'null' calendar: $ref: '#/components/schemas/BranchCalendar' description: Optional authoritative civil calendar. When present, use its timezone and dated exceptions; openingHours remains a weekday-only compatibility projection. catalogId: type: [string, 'null'] format: uuid description: Active catalog assigned to the branch, or null when none is available serviceModes: type: array description: Modes the online store offers at this branch (enabled at the branch, narrowed by its online store settings; never internal modes), sorted by display order items: $ref: '#/components/schemas/BranchServiceMode' availableForOrdering: type: boolean description: True when the branch has an active catalog and at least one enabled public service mode selfService: description: Active ordering channel; null for hidden, closed or menu-only channels. Its modes are independent of ecommerce serviceModes. Empty self-service mode allowlist means all enabled public modes. anyOf: - $ref: '#/components/schemas/SelfServiceChannel' - type: 'null' reservations: description: Active online booking channel; null when disabled or paused. Does not promise a free slot. anyOf: - $ref: '#/components/schemas/PublicChannel' - type: 'null' links: type: array items: $ref: '#/components/schemas/PublicLink' example: id: 6ec78e84-9363-44e7-a2d2-89149f63e71b name: Centro displayName: Café Centro slug: centro branchType: store address: null timezone: America/Argentina/Buenos_Aires openingHours: null catalogId: 9862a1c2-0f90-4e2d-bf51-4fbccbb6bb84 serviceModes: - key: takeaway name: Para llevar description: null icon: null imageUrl: null sortOrder: 1 availableForOrdering: true selfService: url: https://app.morsis.com/self-service/cafe/centro modes: - key: takeaway url: https://app.morsis.com/self-service/cafe/centro/takeaway reservations: url: https://my.morsis.com/book/6ec78e84-9363-44e7-a2d2-89149f63e71b links: [] PublicChannel: type: object additionalProperties: false required: [url] properties: url: type: string format: uri description: Absolute customer-facing URL using the configured environment origin B2bChannel: type: object additionalProperties: false required: [url, whatsapp] properties: url: type: string format: uri description: Absolute URL of the published B2B storefront whatsapp: type: [string, 'null'] description: Published B2B profile WhatsApp number, not a general merchant contact. Null when no wholesale WhatsApp is configured. SelfServiceChannel: type: object additionalProperties: false required: [url, modes] properties: url: type: string format: uri modes: type: array minItems: 1 items: type: object additionalProperties: false required: [key, url] properties: key: type: string url: type: string format: uri PublicContact: type: object additionalProperties: false required: [phone, email, website] properties: phone: type: [string, 'null'] email: type: [string, 'null'] website: type: [string, 'null'] PublicLink: type: object additionalProperties: false description: Visible custom link from an enabled public links page. Social/WhatsApp links are preserved as configured; auto channel links, link IDs and analytics are excluded. Only absolute HTTP(S), tel and mailto URLs without embedded credentials are allowed. required: [title, url, icon] properties: title: type: string url: type: string format: uri icon: type: [string, 'null'] Merchant: type: object additionalProperties: false required: [slug, name, contact, links, b2b] properties: slug: type: string name: type: string description: Customer-facing organization name, matching the portal; no separate public-name field exists contact: $ref: '#/components/schemas/PublicContact' links: type: array items: $ref: '#/components/schemas/PublicLink' b2b: anyOf: - $ref: '#/components/schemas/B2bChannel' - type: 'null' example: slug: cafe name: Café contact: phone: '+541112345678' email: hola@example.com website: https://example.com links: - title: Instagram url: https://www.instagram.com/cafe icon: null - title: WhatsApp url: https://wa.me/5491112345678 icon: null b2b: url: https://b2b.morsis.com/cafe-negocios whatsapp: '+5491112345678' BranchAddress: type: object required: - street - streetNumber - floor - apartment - unit - city - state - zipCode - country - countryCode - latitude - longitude properties: street: type: [string, 'null'] streetNumber: type: [string, 'null'] floor: type: [string, 'null'] apartment: type: [string, 'null'] unit: type: [string, 'null'] city: type: [string, 'null'] state: type: [string, 'null'] zipCode: type: [string, 'null'] country: type: [string, 'null'] countryCode: type: [string, 'null'] latitude: type: [number, 'null'] longitude: type: [number, 'null'] BranchCalendar: type: object additionalProperties: false required: [timeZone, weekly, exceptions] properties: timeZone: type: string description: IANA timezone for all civil times and dates in this calendar weekly: type: object additionalProperties: false required: [mon, tue, wed, thu, fri, sat, sun] properties: mon: $ref: '#/components/schemas/BranchCalendarDay' tue: $ref: '#/components/schemas/BranchCalendarDay' wed: $ref: '#/components/schemas/BranchCalendarDay' thu: $ref: '#/components/schemas/BranchCalendarDay' fri: $ref: '#/components/schemas/BranchCalendarDay' sat: $ref: '#/components/schemas/BranchCalendarDay' sun: $ref: '#/components/schemas/BranchCalendarDay' exceptions: type: array maxItems: 366 description: Each entry replaces the entire civil date, including hours carried from the previous day items: type: object additionalProperties: false required: [date, day] properties: date: type: string format: date day: $ref: '#/components/schemas/BranchCalendarDay' BranchCalendarDay: oneOf: - type: object additionalProperties: false required: [status] properties: status: type: string enum: [unspecified, closed, open24h] description: Unspecified means no public hours information; it is not equivalent to closed - type: object additionalProperties: false required: [status, intervals] properties: status: type: string const: intervals intervals: type: array minItems: 1 maxItems: 12 items: type: object additionalProperties: false required: [startTime, endTime, endsNextDay] properties: startTime: type: string pattern: '^([01][0-9]|2[0-3]):[0-5][0-9]$' endTime: type: string pattern: '^([01][0-9]|2[0-3]):[0-5][0-9]$' endsNextDay: type: boolean description: End is on the next civil date; interval duration is at most 24 hours WeeklyOpeningHours: type: object description: Local branch hours. Missing day means closed; a day may contain multiple intervals. properties: mon: $ref: '#/components/schemas/OpeningHourIntervals' tue: $ref: '#/components/schemas/OpeningHourIntervals' wed: $ref: '#/components/schemas/OpeningHourIntervals' thu: $ref: '#/components/schemas/OpeningHourIntervals' fri: $ref: '#/components/schemas/OpeningHourIntervals' sat: $ref: '#/components/schemas/OpeningHourIntervals' sun: $ref: '#/components/schemas/OpeningHourIntervals' additionalProperties: false OpeningHourIntervals: type: array items: type: object required: [open, close] properties: open: type: string pattern: '^([01]\\d|2[0-3]):[0-5]\\d$' close: type: string description: Local close time; 24:00 is accepted for midnight pattern: '^(([01]\\d|2[0-3]):[0-5]\\d|24:00)$' BranchServiceMode: type: object required: [key, name, description, icon, imageUrl, sortOrder] properties: key: type: string name: type: string description: type: [string, 'null'] icon: type: [string, 'null'] imageUrl: type: [string, 'null'] sortOrder: type: [integer, 'null'] CatalogSummary: type: object required: [id, name, slug, description, type, status, currency, locale] properties: id: type: string format: uuid name: type: string slug: type: [string, 'null'] description: type: [string, 'null'] type: type: string status: type: string enum: [active] currency: type: string description: 'ISO 4217 currency code (e.g. `ARS`, `USD`)' locale: type: [string, 'null'] Catalog: type: object required: [id, name, products, sections, tags, optionGroups] properties: id: type: string format: uuid name: type: string products: type: array items: $ref: '#/components/schemas/Product' sections: type: array items: $ref: '#/components/schemas/Section' tags: type: array items: $ref: '#/components/schemas/Tag' optionGroups: type: array items: $ref: '#/components/schemas/OptionGroup' Section: type: object required: [id, name, color, icon, imageUrl, sortOrder] properties: id: type: string format: uuid name: type: string color: type: [string, 'null'] description: 'Hex color code (e.g. `#FF5733`)' icon: type: [string, 'null'] description: Icon identifier imageUrl: type: [string, 'null'] sortOrder: type: integer Tag: type: object required: [id, name, icon] properties: id: type: string format: uuid name: type: string icon: type: [string, 'null'] Product: type: object required: - id - name - sku - priceCents - originalPriceCents - currency - imageUrl - imageCropData - shortDescription - description - sectionId - isAvailable - inStock - isFeatured - hasOptions - optionGroupIds - tags - sortOrder - createdAt - media - productType - serviceModeAvailability - serviceModeConfig properties: id: type: string format: uuid name: type: string description: Display name of the product sku: type: string priceCents: type: integer description: Price in the smallest currency unit (e.g. centavos for ARS) originalPriceCents: type: [integer, 'null'] description: Original price before discount. Null if no discount applies. currency: type: string description: 'ISO 4217 currency code inherited from the catalog' imageUrl: type: [string, 'null'] imageCropData: type: [object, 'null'] properties: offsetX: type: number offsetY: type: number zoom: type: number rotation: type: number shortDescription: type: [string, 'null'] description: type: [string, 'null'] sectionId: type: [string, 'null'] format: uuid description: ID of the section this product belongs to isAvailable: type: boolean description: > Whether the product is currently available for ordering. On a branch-scoped read of a branch that does not sell without stock, this is also `false` when the product is out of stock. inStock: type: boolean nullable: true description: > Stock at the requested branch. `true` or `false` for products that track inventory; `null` when the read has no `branch_id`, the product does not track inventory, or it is a bundle. Informational: a branch that sells without stock keeps `isAvailable: true` for an out-of-stock product, so a storefront can still show it (for example, as made to order). isFeatured: type: boolean hasOptions: type: boolean description: Whether this product has customizable option groups optionGroupIds: type: array items: type: string format: uuid description: IDs of option groups. Use GET /products/{id} to get them expanded. tags: type: array items: type: object required: [id, name] properties: id: type: string format: uuid name: type: string sortOrder: type: integer createdAt: type: string format: date-time description: Product creation timestamp (ISO 8601). Useful for sorting by newest. media: type: [array, 'null'] items: $ref: '#/components/schemas/MediaItem' productType: type: string enum: [simple, bundle] bundleGroups: type: array description: | Bundle composition expressed as virtual groups (PR4). Each group is a "step" the customer fills (e.g. "pick your hamburger") and contains a list of candidate child products. Groups may be single-select or multi-select. Single-select groups use either `absorbed` pricing (the selected candidate is included in the bundle price) or `upgrade_from_default` pricing (the default candidate is included and non-default candidates add their configured delta). Non-single groups (`multiple`, `customer_quantity`) use `pricingMode=null`, where each selected candidate contributes according to its configured cost, `absorbed`, where the bundle price already covers the selected candidates and they contribute nothing, or `most_expensive`, where the group contributes the configured cost of its dearest selected candidate, once, whatever the quantities. `upgrade_from_default` is single-select only. A `customer_quantity` group with `fractionalPicks: true` splits one candidate among the units the customer chooses in it: each candidate is its quantity over the total quantity chosen in the group, so two candidates are a half each, three are a third each, and a candidate chosen alone is one whole product. Every candidate of the group has `quantity: 1`. Quantities stay whole numbers; never send a fraction. With `pricingMode=null` such a group contributes the sum of the units' configured costs divided by the total quantity chosen, rounded once to the nearest cent (not per unit): the average of the choices. Options picked on a candidate always add their full modifier, whatever the part. Example, a half-and-half pizza sold at a bundle price of 0: one group with `selectionType: customer_quantity`, `selectionMin: 1`, `selectionMax: 2`, `fractionalPicks: true` and `pricingMode: most_expensive`. One unit of Hawaiian (24000) and one of Mozzarella (15000) costs 24000; Hawaiian alone (one whole pizza) also costs 24000. With `pricingMode: null` the first choice would cost (24000 + 15000) / 2 = 19500, and Hawaiian alone 24000. items: type: object required: - id - selectionType - required - selectionMin - selectionMax - pricingMode - fractionalPicks - defaultChildProductId - defaultEffectiveConfiguredCostCents - sortOrder - candidates properties: id: type: string format: uuid name: type: [string, 'null'] displayName: type: [string, 'null'] selectionType: type: string enum: [single, multiple, customer_quantity] description: | `customer_quantity`: the customer chooses a quantity per candidate (`pricingMode=null` for per-unit pricing, `absorbed` when the bundle price covers them, or `most_expensive` to charge the dearest choice once); the admin may cap each candidate via `customerQuantityMax`. required: type: boolean selectionMin: type: integer selectionMax: type: integer pricingMode: type: [string, 'null'] enum: [absorbed, upgrade_from_default, most_expensive, null] fractionalPicks: type: boolean description: | The units chosen in the group split one candidate. Only `true` on a `customer_quantity` group with `selectionMax` of 2 or more. See the group description for pricing. defaultChildProductId: type: [string, 'null'] format: uuid description: | Pricing baseline product for `upgrade_from_default`. It may be absent from `candidates` when this branch hides it. defaultEffectiveConfiguredCostCents: type: [integer, 'null'] description: | Immutable configured cost of the default candidate used to calculate upgrade deltas without exposing a hidden candidate. sortOrder: type: integer candidates: type: array items: type: object required: - childProductId - childProductName - childProductSku - quantity - sortOrder - optionOverrides - isDefault - isAvailable properties: childProductId: type: string format: uuid childProductName: type: string childProductSku: type: string quantity: type: integer customerQuantityMax: type: [integer, 'null'] description: | Optional per-candidate ceiling for `selectionType=customer_quantity` groups. `null` = no cap; always `null` for single/multiple groups. sortOrder: type: integer optionOverrides: type: object description: | Per-option state on this candidate, keyed by option id. `preset` is applied and locked, `hidden` is not offered, and `included` stays offered and never changes the combo price when the customer picks it. additionalProperties: type: string enum: [preset, hidden, included] isDefault: type: boolean isAvailable: type: boolean description: Branch-effective availability of this candidate. serviceModeAvailability: type: [object, 'null'] description: | Legacy deny/allow-list of service modes, superseded by `serviceModeConfig` when the latter is non-empty. If any mode is explicitly `true` this acts as an allow-list (only those modes are available); otherwise only keys explicitly set to `false` exclude the product from that mode. If null, the product is available in all modes. Example: `{ "delivery": false }` means unavailable for delivery only. additionalProperties: type: boolean serviceModeConfig: type: [object, 'null'] description: | Per-service-mode configuration. Supersedes `serviceModeAvailability` when non-empty. Each key is a service mode (e.g. `dine_in`, `takeaway`, `delivery`, `ecommerce`). A mode with no entry is available; an entry with `enabled: false` excludes the product from that mode. Entries may also override the price for that mode and restrict availability to specific dayparts. If null, no per-mode configuration applies and `serviceModeAvailability` (if any) is used instead. `pricingRule` is intentionally omitted even though older responses could expose it through this object. This compatibility exception prevents callers from deriving internal product cost from the rule percentage and the public price. additionalProperties: type: object required: - enabled properties: enabled: type: boolean description: Whether the product is available in this service mode. priceCents: type: [integer, 'null'] description: | Per-mode price override in cents. Null or absent = use the product's base `priceCents`. daypartIds: type: array items: type: string format: uuid description: | Daypart IDs where the product is available in this mode. Empty or absent = always available within this mode. ProductDetail: description: A product with its option groups expanded inline allOf: - $ref: '#/components/schemas/Product' - type: object required: [optionGroups] properties: optionGroups: type: array items: $ref: '#/components/schemas/OptionGroup' OptionGroup: type: object required: - id - name - selectionType - displayName - isRequired - promptLlm - minSelections - maxSelections - sections - options properties: id: type: string format: uuid name: type: string selectionType: type: string enum: [single, multiple, quantity] displayName: type: [string, 'null'] description: Customer-facing name override isRequired: type: boolean promptLlm: type: boolean description: Whether AI ordering assistants should prompt for this group minSelections: type: integer maxSelections: type: integer description: '999 means unlimited' sections: type: array description: Sub-sections within the option group for visual grouping items: type: object required: [id, name, sortOrder] properties: id: type: string format: uuid name: type: string sortOrder: type: integer options: type: array items: $ref: '#/components/schemas/Option' Option: type: object required: - id - name - description - priceModifierCents - modifierType - isAvailable - isDefault - mediaUrl - sectionId properties: id: type: string format: uuid name: type: string description: type: [string, 'null'] priceModifierCents: type: integer description: Price adjustment in cents modifierType: type: string enum: [increase, decrease, replace, none] description: | How `priceModifierCents` applies to the product price: - `increase`: add to base price - `decrease`: subtract from base price - `replace`: use this as the total price - `none`: no price change isAvailable: type: boolean isDefault: type: boolean description: Whether this option is pre-selected mediaUrl: type: [string, 'null'] sectionId: type: [string, 'null'] format: uuid description: ID of the option group section this option belongs to (for visual grouping) Cart: type: object required: - id - orderNumber - branchId - status - serviceMode - currency - totalCents - items - metadata - createdAt - updatedAt properties: id: type: string format: uuid orderNumber: type: string description: 'Human-readable order number (e.g. "A-001")' branchId: type: string format: uuid status: type: string enum: [open] description: Always "open" for active carts serviceMode: type: [string, 'null'] description: 'Service mode set at creation (e.g. `dine_in`, `takeaway`, `delivery`)' currency: type: string description: 'ISO 4217 currency code (e.g. `ARS`)' totalCents: type: integer description: Cart total in the smallest currency unit, recalculated on every item change items: type: array items: $ref: '#/components/schemas/CartLineItem' metadata: type: [object, 'null'] description: Arbitrary metadata passed at cart creation additionalProperties: true createdAt: type: string format: date-time updatedAt: type: string format: date-time CartLineItem: type: object required: - lineItemId - productId - name - priceCents - quantity - options properties: lineItemId: type: string description: Unique line item ID (use this for update/delete operations) productId: type: [string, 'null'] format: uuid name: type: string description: Product name resolved from catalog at add time priceCents: type: integer description: Unit price in cents (base product price, before option modifiers) quantity: type: integer minimum: 1 notes: type: string description: Special instructions for this item options: type: array items: $ref: '#/components/schemas/CartItemOption' CartItemOption: type: object required: - optionId - optionGroupId - optionGroupName - name - priceCents - modifierType - quantity properties: optionId: type: [string, 'null'] format: uuid optionGroupId: type: [string, 'null'] format: uuid optionGroupName: type: [string, 'null'] name: type: string description: Option name resolved from catalog priceCents: type: integer description: Price modifier in cents modifierType: type: [string, 'null'] enum: [increase, decrease, replace, none, null] description: | How `priceCents` applies to the product price: - `increase`: add to base price - `decrease`: subtract from base price - `replace`: use this as the total price - `none`/`null`: no price change quantity: type: integer minimum: 1 description: Per-product quantity for this selected option CreateCheckoutSessionRequest: type: object additionalProperties: false properties: successUrl: type: string format: uri maxLength: 2048 description: Optional URL to redirect the customer after a successful payment cancelUrl: type: string format: uri maxLength: 2048 description: Optional URL to redirect the customer if they cancel checkout externalReference: type: string minLength: 1 maxLength: 160 description: Ecommerce-side order/cart reference. Unique per organization when present. customer: $ref: '#/components/schemas/CheckoutCustomer' fulfillment: $ref: '#/components/schemas/CheckoutFulfillment' webhook: $ref: '#/components/schemas/CheckoutWebhook' metadata: type: object description: Arbitrary key-value metadata attached to the checkout session additionalProperties: true CheckoutCustomer: type: object additionalProperties: false properties: name: type: string maxLength: 160 phone: type: string maxLength: 80 email: type: string format: email maxLength: 254 CheckoutDeliveryAddress: type: object additionalProperties: false properties: street: type: string maxLength: 160 streetNumber: type: string maxLength: 40 floor: type: string maxLength: 40 apartment: type: string maxLength: 40 city: type: string maxLength: 120 state: type: string maxLength: 120 zipCode: type: string maxLength: 40 country: type: string maxLength: 2 description: ISO 3166-1 alpha-2 country code latitude: type: number longitude: type: number formattedAddress: type: string maxLength: 300 notes: type: string maxLength: 500 CheckoutFulfillment: type: object additionalProperties: false properties: type: type: string minLength: 1 maxLength: 80 description: Optional. When present it must equal the cart's `serviceMode` (`FULFILLMENT_MODE_MISMATCH` otherwise); the cart's mode is the order's modality. A `delivery` cart requires `deliveryAddress` (`DELIVERY_ADDRESS_REQUIRED`). deliveryAddress: $ref: '#/components/schemas/CheckoutDeliveryAddress' deliveryFeeCents: type: integer minimum: 0 maximum: 10000000 description: Delivery fee in the smallest currency unit. Defaults to 0. notes: type: string maxLength: 500 CheckoutWebhook: type: object additionalProperties: false required: [url] properties: url: type: string format: uri maxLength: 2048 description: URL called by Morsis for checkout events secret: type: string minLength: 8 maxLength: 512 description: Optional HMAC secret used for the Morsis-Signature header events: type: array maxItems: 3 items: type: string enum: - checkout.session.paid - checkout.session.failed - checkout.session.expired description: | Events to deliver. With the `talo` provider a late transfer can turn an expired session into a paid one, so `checkout.session.paid` may arrive after `checkout.session.expired`. A partial `talo` transfer emits nothing until the customer completes it (`checkout.session.paid`) or the store refunds it (`checkout.session.failed`, session `cancelled`). CheckoutProvider: type: object required: [provider, label] properties: provider: type: string enum: [mercadopago, modo, nave, talo, bank_transfer, cash] description: When `talo` is offered the manual `bank_transfer` is not; both are the transfer option for the customer. label: type: string CheckoutSession: type: object required: - id - token - checkoutUrl - status - amountCents - currency - expiresAt - customer - fulfillment - providers - order properties: id: type: string format: uuid token: type: string description: Public checkout token used in the hosted checkout URL checkoutUrl: type: string format: uri description: Hosted checkout URL for the customer status: type: string enum: [open, payment_started, paid, failed, expired, cancelled] description: Manual cash and bank transfer checkouts remain payment_started until the merchant confirms collection. A receipt submission is not payment approval. A `talo` checkout stays payment_started while Morsis waits for the transfer (up to 120 minutes, longer when only part of the amount arrived); an `expired` talo session can still become `paid` if the transfer lands late. amountCents: type: integer description: Checkout amount in the smallest currency unit currency: type: string description: ISO 4217 currency code expiresAt: type: string format: date-time transferDetails: type: [object, 'null'] description: Destination of the enabled manual bank transfer account. Receipt submission is handled by the hosted checkout. properties: paymentAccountId: type: string format: uuid version: type: string format: date-time bankName: type: string accountHolder: type: string alias: type: [string, 'null'] cbu: type: [string, 'null'] selectedProvider: type: [string, 'null'] enum: [mercadopago, modo, nave, talo, bank_transfer, cash, null] paymentRequestId: type: [string, 'null'] successUrl: type: [string, 'null'] format: uri cancelUrl: type: [string, 'null'] format: uri customer: anyOf: - $ref: '#/components/schemas/CheckoutCustomer' - type: 'null' fulfillment: anyOf: - $ref: '#/components/schemas/CheckoutFulfillment' - type: 'null' providers: type: array items: $ref: '#/components/schemas/CheckoutProvider' order: $ref: '#/components/schemas/CheckoutOrderSummary' CheckoutOrderSummary: type: object required: - id - orderNumber - totalCents - paymentStatus - serviceMode - serviceModeName - organizationName - branchName - items properties: id: type: string format: uuid orderNumber: type: [string, 'null'] totalCents: type: integer paymentStatus: type: string serviceMode: type: [string, 'null'] serviceModeName: type: [string, 'null'] organizationName: type: string branchName: type: string items: type: array items: $ref: '#/components/schemas/CartLineItem' MediaItem: type: object required: [id, url, type, cropData, sortOrder] properties: id: type: string url: type: string type: type: string enum: [image, video] cropData: type: [object, 'null'] properties: offsetX: type: number offsetY: type: number zoom: type: number rotation: type: number sortOrder: type: integer CatalogChangedEvent: type: object additionalProperties: false required: [id, type, createdAt, data] properties: id: type: string description: Event id (`evt_…`). type: type: string const: catalog.changed createdAt: type: string format: date-time data: type: object additionalProperties: false required: [catalogId, branchIds] properties: catalogId: type: [string, 'null'] format: uuid description: The catalog that changed, or `null` when it may be any catalog of the organization. branchIds: type: [array, 'null'] items: type: string format: uuid description: The branches the change is limited to, or `null` for every branch selling the catalog. WebhookTestEvent: type: object additionalProperties: false required: [id, type, createdAt, data] properties: id: type: string type: type: string const: webhook.test createdAt: type: string format: date-time data: type: object additionalProperties: false required: [organizationId] properties: organizationId: type: string format: uuid SiteContentPublishedEvent: type: object additionalProperties: false required: [id, type, createdAt, data] properties: id: type: string description: Event id (`evt_…`). type: type: string const: site.content_published createdAt: type: string format: date-time data: type: object additionalProperties: false required: [siteId, version] properties: siteId: type: string format: uuid version: type: integer minimum: 1 SiteContent: type: object additionalProperties: false required: [siteId, version, publishedAt, values] properties: siteId: type: string format: uuid version: type: integer minimum: 0 description: The published version; `0` when the site was never published. publishedAt: type: [string, 'null'] format: date-time values: type: object description: | Published values by slot key (`.
.`): a string for a `text` slot (plain text, line breaks as `\n`), a boolean for a `toggle`, a `SiteImage` for an `image`. additionalProperties: oneOf: - type: string - type: boolean - $ref: '#/components/schemas/SiteImage' example: home.hero.title: Smash burgers en Palermo home.hero.photo: url: https://media.morsis.com/site-content/2026/10/12/a1b2.jpg alt: Hamburguesa doble width: 2400 height: 1600 home.reviews.visible: false SiteImage: type: object additionalProperties: false required: [url, alt, width, height] properties: url: type: string format: uri description: Absolute https URL hosted by Morsis; public and stable. alt: type: string maxLength: 200 width: type: integer minimum: 1 description: Real pixel width of the file. height: type: integer minimum: 1 description: Real pixel height of the file. SubscriptionData: description: Operation-specific payload. Amounts are strings in minor units. type: object additionalProperties: true SubscriptionAnyBody: type: object additionalProperties: true SubscriptionExpectedRevision: type: object required: [expectedRevision] properties: expectedRevision: { type: integer, minimum: 1 } SubscriptionPrice: type: object required: [id, planId, revision, amountMinor, currency, interval, renewalMode] properties: id: { type: string, format: uuid } planId: { type: string, format: uuid } revision: { type: integer } amountMinor: { type: string, description: 'Integer in minor units (cents)' } currency: { type: string, enum: [ARS, USD, EUR, BRL] } interval: { type: string, enum: [month, year] } renewalMode: { type: string, enum: [accrual, prepaid, arrears] } pricingModel: { type: string, enum: [flat, per_unit, volume, graduated], description: 'How a quantity becomes an amount. Self-service plans are always `flat`.', } unitLabel: { type: [string, 'null'], description: 'Singular unit name; null for flat' } unitLabelPlural: { type: [string, 'null'] } tiers: type: [array, 'null'] description: 'Volume/graduated tiers; the last `upTo` is null' items: type: object properties: upTo: { type: [integer, 'null'] } unitAmountMinor: { type: string } flatAmountMinor: { type: string } minQuantity: { type: integer } setupFeeMinor: { type: [string, 'null'], description: 'One-off setup fee in minor units of `currency`; null when none', } publishedAt: { type: string, format: date-time } SubscriptionPricingBreakdownV1: type: object description: > Frozen composition of a cycle generated before subscriptions had lines (frozen, never rewritten): base line, add-ons by `addonId`, discounts by `targetAddonId`. Amounts are strings in minor units of `currency`. properties: version: { const: 1 } currency: { type: string, enum: [ARS, USD, EUR, BRL] } lines: type: array items: type: object properties: kind: { type: string, enum: [base, addon] } addonId: { type: [string, 'null'], format: uuid } planId: { type: string, format: uuid } planName: { type: string } priceVersionId: { type: string, format: uuid } pricingModel: { type: string, enum: [flat, per_unit, volume, graduated] } unitLabel: { type: [string, 'null'] } unitLabelPlural: { type: [string, 'null'] } quantity: { type: integer } grossMinor: { type: string } discountMinor: { type: string } netMinor: { type: string } listGrossMinor: type: string description: What the catalog price (same version and quantity) would charge for the line priceOverride: type: [object, 'null'] description: > Agreed price of the line, which replaced the catalog price. For a flat price it is the line's amount; for any other model, the unit price (`grossMinor` = amount × quantity). Null when the line uses the catalog price. properties: overrideId: { type: string, format: uuid } amountMinor: { type: string } discounts: type: array items: type: object properties: discountId: { type: string, format: uuid } label: { type: string, description: 'Generated, e.g. "Descuento 10%"' } amountMinor: { type: string } targetAddonId: { type: [string, 'null'], format: uuid } grossMinor: { type: string } discountMinor: { type: string } netMinor: { type: string } SubscriptionPricingBreakdownV2: type: object description: > Frozen composition of the cycle by line: principal plans by position, each followed by its add-ons. Amounts are strings in minor units of `currency`. properties: version: { const: 2 } currency: { type: string, enum: [ARS, USD, EUR, BRL] } lines: type: array items: type: object properties: lineId: { type: string, format: uuid } role: { type: string, enum: [principal, addon] } parentLineId: { type: [string, 'null'], format: uuid } planId: { type: string, format: uuid } planName: { type: string } priceVersionId: { type: string, format: uuid } pricingModel: { type: string, enum: [flat, per_unit, volume, graduated] } unitLabel: { type: [string, 'null'] } unitLabelPlural: { type: [string, 'null'] } quantity: { type: integer } quantitySegments: type: array description: Dated stretches of the line inside the cycle, before discounts items: type: object properties: startDate: { type: string, format: date } endDate: { type: string, format: date } quantity: { type: integer } days: { type: integer } totalDays: { type: integer } grossMinor: { type: string } grossMinor: { type: string } discountMinor: { type: string } netMinor: { type: string } listGrossMinor: type: string description: What the catalog price (same version and quantity) would charge for the line priceOverride: type: [object, 'null'] description: Agreed price of the line, or null when it uses the catalog price. properties: overrideId: { type: string, format: uuid } amountMinor: { type: string } customerNote: { type: string } discounts: type: array items: type: object properties: discountId: { type: string, format: uuid } label: { type: string, description: 'Generated, e.g. "Descuento 10%"' } amountMinor: { type: string } targetLineId: { type: [string, 'null'], format: uuid, description: 'null = the whole cycle' } grossMinor: { type: string } discountMinor: { type: string } netMinor: { type: string } SubscriptionPricingBreakdown: description: Frozen composition of the cycle, discriminated by `version`. Null only on cycles of the first version without add-ons, discounts or agreed prices. oneOf: - $ref: '#/components/schemas/SubscriptionPricingBreakdownV1' - $ref: '#/components/schemas/SubscriptionPricingBreakdownV2' - type: 'null' SubscriptionPriceList: type: array items: { $ref: '#/components/schemas/SubscriptionPrice' } SubscriptionPlanList: type: array items: type: object required: [id, name, kind, offeredForPlanIds, price] description: > An enabled plan with its latest price. The buyer portal lists only self-service plans: base plans whose latest price is flat with no setup fee. properties: id: { type: string, format: uuid } name: { type: string } description: { type: [string, 'null'] } enabled: { type: boolean } kind: { type: string, enum: [base, addon], description: '`base` is a principal plan; `addon` hangs from a principal line', } offeredForPlanIds: type: array items: { type: string, format: uuid } description: > Add-ons only: the principal plans that offer it. Empty = every principal plan (and always empty for a principal plan). price: { $ref: '#/components/schemas/SubscriptionPrice' } FiscalRecipientSelection: description: Explicit consumer or an organization-local customer profile at its reviewed revision. oneOf: - type: object required: [type] properties: type: { const: consumer } - type: object required: [type, fiscalProfileId, revision] properties: type: { const: profile } fiscalProfileId: { type: string, format: uuid } revision: { type: integer, minimum: 1 } CustomerFiscalProfileInput: type: object properties: taxId: { type: [string, 'null'], maxLength: 40 } taxIdType: { type: [string, 'null'], maxLength: 20 } fiscalName: { type: [string, 'null'], maxLength: 200 } ivaConditionReceptor: { type: [string, 'null'], maxLength: 80 } fiscalAddress: { type: [string, 'null'], maxLength: 500 } SubscriptionBuyerCreate: description: >- Fiscal profiles belong to the seller's customer record. A company document matching existing records returns 409 CUSTOMER_FISCAL_MATCH_CHOICE_REQUIRED with error.details.candidates (organizationCustomerId, customerId, name). Retry with companyMatchChoice action use and the selected organizationCustomerId, or action create. type: object required: [kind, name] properties: kind: { type: string, enum: [person, company] } name: { type: string, maxLength: 160 } email: { type: string, format: email } phone: { type: string } fiscalProfiles: type: array maxItems: 50 items: { $ref: '#/components/schemas/CustomerFiscalProfileInput' } companyMatchChoice: oneOf: - type: object required: [action] properties: action: { const: create } - type: object required: [action, organizationCustomerId] properties: action: { const: use } organizationCustomerId: { type: string, format: uuid } externalCustomerRef: { type: string, maxLength: 160 } SubscriptionBuyerReference: type: object required: [externalCustomerRef] properties: externalCustomerRef: { type: string, maxLength: 160 } SubscriptionActor: type: object additionalProperties: false required: [id, name] description: The person acting, as your backend knows them. Recorded, not verified. properties: id: { type: string, minLength: 1, maxLength: 200, description: 'Your user id' } name: { type: string, minLength: 1, maxLength: 160 } email: { type: string, format: email } impersonatorId: { type: string, minLength: 1, maxLength: 200, description: 'Your support user acting on behalf of `id`, if any', } SubscriptionBuyerReferenceReplace: type: object additionalProperties: false required: [externalCustomerRef, reason] properties: externalCustomerRef: { type: string, minLength: 1, maxLength: 160 } reason: { type: string, minLength: 1, maxLength: 500 } actor: { $ref: '#/components/schemas/SubscriptionActor' } SubscriptionBuyerReferenceChange: type: object required: [buyerId, externalCustomerRef, previousExternalCustomerRef, changed, revokedSessions] properties: buyerId: { type: string, format: uuid } externalCustomerRef: { type: [string, 'null'] } previousExternalCustomerRef: { type: [string, 'null'] } changed: { type: boolean, description: 'false when the value was already in place' } revokedSessions: { type: integer, minimum: 0 } SubscriptionCustomerSummary: type: object required: [ buyerId, externalCustomerRef, name, status, worstDunningLevel, balances, nextDueDate, contracts, ] properties: buyerId: { type: string, format: uuid } externalCustomerRef: { type: [string, 'null'] } name: { type: [string, 'null'] } status: type: string enum: [active, overdue, cancelled, none] description: >- Worst state of the contracts: `overdue` when any has overdue cuotas, `cancelled` only when every contract is cancelled or ended, `none` without contracts, else `active`. worstDunningLevel: allOf: [{ $ref: '#/components/schemas/SubscriptionDunningLevel' }] description: The highest dunning level among the contracts, or null. balances: type: array description: >- Balance of the receivable books the contracts charge, per currency (a book shared with other debts of the customer counts whole; negative = in favour of the customer). items: type: object required: [currency, outstandingMinor] properties: currency: { type: string } outstandingMinor: { type: string } nextDueDate: { type: [string, 'null'], format: date, description: 'Earliest of the live contracts' } contracts: type: array items: type: object required: [ id, draftId, name, planName, legalEntityName, status, currency, overdueMinor, nextDueDate, suspendsOn, oldestDueDate, dunningLevel, lines, ] properties: id: { type: string, format: uuid } draftId: { type: string, format: uuid, description: 'The id `/subscriptions/drafts/{draftId}/units` takes', } name: { type: [string, 'null'] } planName: { type: [string, 'null'], description: 'The principal plans in force at the next cuota («Ecommerce + Sucursal»)', } legalEntityName: { type: [string, 'null'], description: 'Razón social invoiced' } status: type: string enum: [ awaiting_payment, pending, manual_block, suspended, paused, trialing, overdue, active, cancelled, ended, ] currency: { type: [string, 'null'], description: 'Currency of the cached overdue amount' } overdueMinor: { type: [string, 'null'], description: 'Overdue cuotas of the contract at its last refresh (null before it)', } nextDueDate: { type: [string, 'null'], format: date } suspendsOn: { type: [string, 'null'], format: date, description: 'Day a dunning level that suspends access applies to the overdue cuotas (null without overdue debt or without a suspending level)', } oldestDueDate: { type: [string, 'null'], format: date, description: 'Due date of the oldest unpaid cuota: the debt runs from it (null without overdue debt)', } dunningLevel: allOf: [{ $ref: '#/components/schemas/SubscriptionDunningLevel' }] description: The dunning level this contract reached, or null. lines: type: array description: >- The lines not ended before the next cuota, with the plan and quantity in force then and their units (`/subscriptions/drafts/{draftId}/units` edits them by line). items: type: object required: [id, role, parentLineId, plan, quantity, units] properties: id: { type: string, format: uuid } role: { type: string, enum: [principal, addon] } parentLineId: { type: [string, 'null'], format: uuid } plan: type: object properties: { id: { type: string, format: uuid }, name: { type: string } } quantity: { type: integer } units: type: array items: type: object properties: position: { type: integer } name: { type: [string, 'null'] } externalId: { type: [string, 'null'] } SubscriptionPaymentReportBody: type: object additionalProperties: false required: [paymentAccountId, amountMinor, reportedOn, periodIds] properties: paymentAccountId: { type: string, format: uuid, description: 'One of the payment instructions methods, offered for every subscription it pays', } amountMinor: { type: string, pattern: '^[1-9][0-9]{0,15}$' } reportedOn: { type: string, format: date, description: 'Day of the payment' } reference: { type: string, minLength: 1, maxLength: 200 } periodIds: type: array description: 'The cuotas it pays. May be empty when `oneOffChargeIds` names something.' maxItems: 100 uniqueItems: true items: { type: string, format: uuid } oneOffChargeIds: type: array description: 'The one-off charges it pays (equipment, setup). At least one cuota or charge in all.' maxItems: 100 uniqueItems: true items: { type: string, format: uuid } receipt: type: object additionalProperties: false required: [fileKey] properties: fileKey: { type: string, maxLength: 300 } SubscriptionPaymentReportCreate: allOf: - $ref: '#/components/schemas/SubscriptionPaymentReportBody' - type: object properties: actor: { $ref: '#/components/schemas/SubscriptionActor' } SubscriptionPaymentReport: type: object required: [id, status, currency, amountMinor, reportedOn, periodIds, paymentAccount, createdAt] properties: id: { type: string, format: uuid } status: { type: string, enum: [pending, confirmed, rejected] } currency: { type: string, enum: [ARS, USD, EUR, BRL] } amountMinor: { type: string } reportedOn: { type: string, format: date } reference: { type: [string, 'null'] } periodIds: { type: array, items: { type: string, format: uuid } } oneOffChargeIds: { type: array, items: { type: string, format: uuid } } paymentAccount: type: object properties: id: { type: string, format: uuid } method: { type: string, enum: [cash, bank_transfer, qr] } bankName: { type: [string, 'null'] } alias: { type: [string, 'null'] } receipt: type: [object, 'null'] properties: mimeType: { type: string } size: { type: integer } rejectionReason: { type: [string, 'null'] } confirmedAmountMinor: { type: [string, 'null'] } createdAt: { type: string, format: date-time } decidedAt: { type: [string, 'null'], format: date-time } buyerId: { type: string, format: uuid, description: 'API only' } actor: { description: 'API only: who reported it' } confirmation: type: [array, 'null'] description: 'API only: one collection per subscription once confirmed' items: type: object properties: contractId: { type: string, format: uuid } amountMinor: { type: string } receiptIds: { type: array, items: { type: string, format: uuid } } SubscriptionPaymentInstructions: type: object required: [methods, cuotas, charges] properties: methods: type: array description: 'Ways to pay besides Mercado Pago: each transfer account the seller turned on for subscriptions at the subscription branch, then each branch cash. A method pays only the subscriptions in `contractIds`.' items: type: object properties: id: { type: string, format: uuid, description: 'The `paymentAccountId` of a report' } method: { type: string, enum: [cash, bank_transfer, qr] } currency: { type: string } contractIds: { type: array, items: { type: string, format: uuid } } bank: type: [object, 'null'] description: 'Transfer details, when the account has them' properties: bankName: { type: string } accountHolder: { type: string } taxId: { type: [string, 'null'] } alias: { type: [string, 'null'] } cbu: { type: [string, 'null'] } branch: type: [object, 'null'] description: 'Where to pay cash' properties: name: { type: string } address: type: [object, 'null'] properties: street: { type: [string, 'null'] } streetNumber: { type: [string, 'null'] } floor: { type: [string, 'null'] } apartment: { type: [string, 'null'] } unit: { type: [string, 'null'] } city: { type: [string, 'null'] } state: { type: [string, 'null'] } zipCode: { type: [string, 'null'] } cuotas: type: array items: type: object properties: periodId: { type: string, format: uuid } contractId: { type: string, format: uuid } subscriptionName: { type: string } periodIndex: { type: integer } startDate: { type: string, format: date } endDate: { type: string, format: date, description: 'Exclusive' } dueDate: { type: string, format: date } currency: { type: string } amountMinor: { type: string } outstandingMinor: { type: string } allowPartialPayments: { type: boolean } charges: type: array description: 'One-off charges (equipment, setup) still owed, due with the cuota they were billed with, else on the day they were charged' items: type: object properties: oneOffChargeId: { type: string, format: uuid } contractId: { type: string, format: uuid } subscriptionName: { type: string } description: { type: string } quantity: { type: integer } chargedOn: { type: string, format: date } dueDate: { type: string, format: date } currency: { type: string } amountMinor: { type: string } outstandingMinor: { type: string } allowPartialPayments: { type: boolean } SubscriptionEventType: type: string enum: [ contract.activated, contract.changed, contract.paused, contract.resumed, contract.cancelled, period.generated, period.funded, payment.received, payment.refunded, payment.reported, payment.report_rejected, invoice.issued, credit_note.issued, entitlement.changed, ] SubscriptionWebhookEndpoint: type: object properties: id: { type: string, format: uuid } url: { type: string, format: uri } description: { type: string } eventTypes: type: array description: Empty = every event type. items: { $ref: '#/components/schemas/SubscriptionEventType' } enabled: { type: boolean } createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } SubscriptionWebhookEndpointCreate: type: object additionalProperties: false required: [url] properties: url: { type: string, format: uri, maxLength: 2048, description: 'Public https URL' } description: { type: string, maxLength: 200 } eventTypes: type: array description: Empty or omitted = every event type. items: { $ref: '#/components/schemas/SubscriptionEventType' } SubscriptionWebhookEndpointUpdate: type: object additionalProperties: false properties: url: { type: string, format: uri, maxLength: 2048, description: 'Public https URL' } description: { type: string, maxLength: 200 } eventTypes: type: array items: { $ref: '#/components/schemas/SubscriptionEventType' } enabled: { type: boolean } SubscriptionRepresentative: type: object properties: id: { type: string, format: uuid } organizationCustomerId: { type: string, format: uuid } displayName: { type: string } email: { type: string, format: email } canView: { type: boolean } canPay: { type: boolean } canManage: { type: boolean } revision: { type: integer } revokedAt: { type: [string, 'null'], format: date-time } SubscriptionRepresentativeList: type: object properties: buyer: { type: object, additionalProperties: true } representatives: type: array items: { $ref: '#/components/schemas/SubscriptionRepresentative' } SubscriptionRepresentativeCreate: type: object required: [displayName, email] description: A person who signs in to the Morsis-hosted portal with an emailed code. properties: displayName: { type: string, maxLength: 160 } email: { type: string, format: email } canView: { type: boolean, default: true } canPay: { type: boolean, default: false } canManage: { type: boolean, default: false } SubscriptionRepresentativeUpdate: type: object required: [expectedRevision, displayName, canView, canPay, canManage] properties: expectedRevision: { type: integer } displayName: { type: string } canView: { type: boolean } canPay: { type: boolean } canManage: { type: boolean } SubscriptionUnitDetails: type: object additionalProperties: false required: [position] description: | Optional descriptive data for a unit. Position, id and non-empty externalId are unique within a line. Blank units are not stored. Metadata is private seller/integrator data, not automatically exposed to the buyer portal. properties: id: { type: string, format: uuid, description: Stable identity generated when omitted for a new position, } position: { type: integer, minimum: 1, maximum: 1000000 } name: { type: [string, 'null'], maxLength: 160 } externalId: { type: [string, 'null'], maxLength: 200 } metadata: type: object maxProperties: 20 propertyNames: { minLength: 1, maxLength: 80 } additionalProperties: { type: string, maxLength: 500 } SubscriptionUnitLine: type: object required: [units, revision] properties: units: type: array items: { $ref: '#/components/schemas/SubscriptionUnitDetails' } revision: { type: integer, minimum: 0 } SubscriptionContractCreate: type: object additionalProperties: false required: [branchId, anchorDate, lines] description: > Exactly one of `buyerId` or `externalCustomerRef`. The same signup Admin uses, saved as a draft: any plan the seller sells, add-ons and setup fees included. The first principal line sets the frequency, renewal mode and currency; every other line must match them. properties: fiscalRecipient: { $ref: '#/components/schemas/FiscalRecipientSelection' } buyerId: { type: string, format: uuid } externalCustomerRef: { type: string } branchId: { type: string, format: uuid } anchorDate: { type: string, format: date, description: 'Start date of the first cycle' } obligationCurrency: { type: string, enum: [ARS, USD, EUR, BRL], description: "Defaults to the first principal line's price currency", } pricingExchangeRate: { $ref: '#/components/schemas/SubscriptionExchangeRate' } lines: type: array minItems: 1 maxItems: 21 items: { $ref: '#/components/schemas/SubscriptionLineCreate' } discounts: type: array maxItems: 22 items: { $ref: '#/components/schemas/SubscriptionDiscountCreate' } priceOverrides: type: array maxItems: 21 description: At most one per line. items: { $ref: '#/components/schemas/SubscriptionPriceOverrideCreate' } SubscriptionLineCreate: type: object additionalProperties: false required: [key, role, priceVersionId] description: > One line of a new subscription. At least one principal line. Contiguous add-on entries with the same `parentKey` and `priceVersionId` become one line. properties: key: { type: string, minLength: 1, maxLength: 40, description: 'Your name for the line inside this request', } role: { type: string, enum: [principal, addon] } parentKey: { type: string, maxLength: 40, description: 'Add-ons: the key of their principal line' } priceVersionId: { type: string, format: uuid } quantity: { type: integer, minimum: 1, maximum: 1000000, description: "Defaults to the price's minimum quantity", } unitDetails: type: array maxItems: 1000 items: { $ref: '#/components/schemas/SubscriptionUnitDetails' } setupFee: type: object additionalProperties: false required: [amountMinor, reason] description: > Replaces the price's setup fee for this line, in the price currency. `"0"` waives it. properties: amountMinor: { type: string } reason: { type: string, maxLength: 500 } customerNote: { type: string, maxLength: 245 } startDate: { type: string, format: date, description: 'Add-ons: the day it joins' } endDate: { type: string, format: date, description: 'Add-ons: the day it leaves' } SubscriptionDuration: oneOf: - type: object required: [kind] properties: { kind: { const: always } } - type: object required: [kind, periods] properties: kind: { const: count } periods: { type: integer, minimum: 1, maximum: 1200 } - type: object required: [kind, date] properties: kind: { const: until_date } date: { type: string, format: date } SubscriptionDiscountCreate: type: object additionalProperties: false required: [kind, duration, reason] properties: kind: { type: string, enum: [percent, fixed] } percentBps: { type: integer, minimum: 1, maximum: 10000, description: '`percent` only' } amountMinor: { type: string, description: '`fixed` only, in the contract currency' } targetLineKey: { type: string, maxLength: 40, description: 'The line it applies to; absent = whole cuota', } duration: { $ref: '#/components/schemas/SubscriptionDuration' } reason: { type: string, maxLength: 500 } customerNote: { type: string, maxLength: 120 } SubscriptionPriceOverrideCreate: type: object additionalProperties: false required: [lineKey, amountMinor, reason] description: Agreed price of one line, replacing its catalog price. properties: lineKey: { type: string, maxLength: 40 } amountMinor: { type: string } reason: { type: string, maxLength: 500 } customerNote: { type: string, maxLength: 120 } duration: { $ref: '#/components/schemas/SubscriptionDuration' } SubscriptionExchangeRate: type: object required: [baseCurrency, quoteCurrency, quoteUnitsPerBaseUnit] properties: baseCurrency: { type: string, enum: [ARS, USD, EUR, BRL] } quoteCurrency: { type: string, enum: [ARS, USD, EUR, BRL] } quoteUnitsPerBaseUnit: { type: string, description: 'Decimal, e.g. "1200.5"' } SubscriptionContractAccept: type: object properties: fiscalRecipient: { $ref: '#/components/schemas/FiscalRecipientSelection' } firstPeriodIndex: { type: integer, default: 0 } dueDays: { type: integer, default: 0 } trial: type: object required: [startDate, continueAutomatically] properties: startDate: { type: string, format: date } continueAutomatically: { type: boolean } book: type: object required: [creditLimitMinor] properties: creditLimitMinor: { type: string, description: '"0" = no credit ceiling' } pricingExchangeRate: { $ref: '#/components/schemas/SubscriptionExchangeRate' } SubscriptionGeneratePeriod: type: object required: [expectedRevision] properties: expectedRevision: { type: integer } pricingExchangeRate: { $ref: '#/components/schemas/SubscriptionExchangeRate' } SubscriptionContract: type: object properties: fiscalProfileId: { type: [string, 'null'], format: uuid } id: { type: string, format: uuid } draftId: { type: string, format: uuid } buyer: { type: object, properties: { id: { type: string }, name: { type: [string, 'null'] } } } externalCustomerRef: { type: [string, 'null'], description: 'Your reference of the buyer, when bound' } revision: { type: integer, description: 'Send as `expectedRevision` on commands' } planName: { type: [string, 'null'], description: 'The principal plans in force at the next cycle, joined with " + "', } lines: type: array items: { $ref: '#/components/schemas/SubscriptionLine' } obligationCurrency: { type: string } nextPeriodIndex: { type: integer } trial: { type: [object, 'null'] } policy: { type: object, description: "Rules accepted with the contract (frozen): planChange, cancellation, resume and portal. Dunning is not frozen: the seller's current dunning levels apply (see `SubscriptionEntitlement.dunningLevel`).", additionalProperties: true, } SubscriptionLine: type: object required: [id, role, parentLineId, position, plan, price, quantity, fromPeriodIndex, untilPeriodIndex] description: > A line of the subscription not ended before its next cycle: principal plans by position, each followed by its add-ons. Plan, price and quantity are the ones in force at the next cycle, or at the line's first cycle when it starts later. properties: id: { type: string, format: uuid } role: { type: string, enum: [principal, addon] } parentLineId: { type: [string, 'null'], format: uuid } position: { type: integer } plan: { type: object, properties: { id: { type: string }, name: { type: string } } } price: { $ref: '#/components/schemas/SubscriptionPrice' } quantity: { type: integer } fromPeriodIndex: { type: integer } untilPeriodIndex: { type: [integer, 'null'], description: 'First cycle without the line; null = open' } SubscriptionLineChange: type: object description: Result of a line command. `revision` is the contract's new revision. properties: revision: { type: integer } line: oneOf: - $ref: '#/components/schemas/SubscriptionLine' - type: 'null' proration: { $ref: '#/components/schemas/SubscriptionLineProration' } setupFeeOneOffId: { type: [string, 'null'], format: uuid, description: 'Adding a line: the setup fee posted for it', } removedLineIds: type: array items: { type: string, format: uuid } description: 'Removing a line: the line and the add-ons that left with it' SubscriptionLineProration: type: object description: What the command billed (`charge`) or credited for the current cycle; `none` with `next_period`. properties: timing: { type: string, enum: [next_period, now] } kind: { type: string, enum: [charge, credit, none] } amountMinor: { type: string } currency: { type: string } oneOffChargeId: { type: [string, 'null'], format: uuid } remainingDays: { type: [integer, 'null'] } SubscriptionContractList: type: array items: { $ref: '#/components/schemas/SubscriptionContract' } SubscriptionPeriod: type: object properties: id: { type: string, format: uuid } periodIndex: { type: integer } startDate: { type: string, format: date } endDate: { type: string, format: date, description: 'Exclusive' } dueDate: { type: string, format: date } currency: { type: string } amountMinor: { type: string } outstandingMinor: { type: [string, 'null'] } renewalMode: { type: string, enum: [accrual, prepaid, arrears] } pricingBreakdown: { $ref: '#/components/schemas/SubscriptionPricingBreakdown' } SubscriptionEntitlement: type: object properties: contractId: { type: string, format: uuid } status: { type: string, enum: [active, trialing, suspended, paused, cancelled, ended, pending] } entitled: { type: boolean } causes: { type: array, items: { type: string } } coverage: { type: [object, 'null'] } overdue: { type: object } dunningLevel: { $ref: '#/components/schemas/SubscriptionDunningLevel' } planIds: type: array items: { type: string, format: uuid } description: 'The principal plans in force, by position' evaluatedAt: { type: string, format: date-time } contractRevision: { type: integer } SubscriptionDunningLevel: type: [object, 'null'] description: | Dunning level the contract is at, from the seller's current levels (live, not frozen with the contract). Days overdue count from the due date of the oldest unpaid cuota, in the contract's timezone; the level is the one with the greatest `fromDaysOverdue` reached. `null` when no level is reached or the seller has none. A level with `suspendsAccess` also makes the status `suspended` (cause `overdue`); other levels keep the status. required: [id, name, tone, fromDaysOverdue, suspendsAccess, daysOverdue] properties: id: { type: string, format: uuid } name: { type: string } tone: { type: string, enum: [info, warning, destructive] } fromDaysOverdue: { type: integer, minimum: 1, maximum: 365 } suspendsAccess: { type: boolean } daysOverdue: { type: integer, minimum: 0 } SubscriptionDocumentList: type: array description: | Newest first. `non_fiscal` is a comprobante no fiscal still in force; a cuota bonified in full has one at `0`, with no sale (`groupId` null). `concepts` says what each document covers: a cuota by its dates (`endDate` exclusive) or a one-off charge by its text. items: type: object properties: id: { type: string, format: uuid } groupId: { type: [string, 'null'], format: uuid } kind: { type: string, enum: [invoice, credit_note, non_fiscal] } status: { type: string } name: { type: [string, 'null'] } number: { type: [string, 'null'] } amountMinor: { type: [string, 'null'] } currency: { type: string } originDocumentId: { type: [string, 'null'], format: uuid } downloadable: { type: boolean } createdAt: { type: string, format: date-time } concepts: type: array items: type: object required: [kind, startDate, endDate, description] properties: kind: { type: string, enum: [period, one_off] } startDate: { type: [string, 'null'], format: date } endDate: { type: [string, 'null'], format: date } description: { type: [string, 'null'] } SubscriptionPaymentStart: type: object required: [targets, payCurrency, returnUrl] properties: targets: type: array items: type: object required: [kind, id] properties: kind: { type: string, enum: [period, one_off, billing_group] } id: { type: string, format: uuid } amountMinor: { type: string, description: 'Partial amount in the debt currency (portal: only if the seller allows it)', } payCurrency: { type: string, enum: [ARS, USD, EUR, BRL] } returnUrl: { type: string, format: uri } SubscriptionPaymentStartApi: allOf: - $ref: '#/components/schemas/SubscriptionPaymentStart' - type: object required: [contractId] properties: contractId: { type: string, format: uuid } SubscriptionEventPage: type: array items: type: object properties: id: { type: string, format: uuid } type: { $ref: '#/components/schemas/SubscriptionEventType' } schemaVersion: { type: integer } resource: { type: object, properties: { type: { type: string }, id: { type: string } } } aggregateVersion: { type: integer } payload: { type: object, additionalProperties: true, description: '`contract.activated` is emitted once per accepted contract (Admin, API or portal) with `contractDraftId`, `buyerId`, `planIds` (the principal plans), `branchId`, `firstPeriodIndex` and `trialEndDate`. `payment.received` is emitted once per receipt, Mercado Pago or manual (Admin «Registrar cobro»), with `intentId` (null for manual), `contractId`, `currency`, `amountMinor`, `unappliedMinor`, `resolution` and `source` (`mercadopago` or `manual`); `period.funded` follows for each cuota the payment left fully paid. `period.*` payloads include `pricingBreakdown` (see SubscriptionPricingBreakdown). `entitlement.changed` is emitted when the status, the causes, the dunning level or the set of principal plans in force change, and carries `dunningLevel` (see SubscriptionDunningLevel), `planIds` and `externalCustomerRef`: the reference you bound to the buyer (`POST /buyers/{id}/reference`), or null. Read the customer back (`GET /subscriptions/customers/{ref}`) for its current state: deliveries are not ordered. `contract.changed` carries `change`; the line kinds are `line_added` {lineId, planId, priceVersionId, quantity, fromPeriodIndex, timing}, `line_removed` {lineId, removedLineIds, untilPeriodIndex, timing}, `line_plan_changed` {lineId, segmentId, priceVersionId, fromPeriodIndex, timing}, `addon_added` {lineId, parentLineId, planId, priceVersionId, quantity}, `addon_removed` {lineId}, `quantity` {lineId, …}, `price_override` {lineId, planId, …} and `discount_added` {targetLineId, …}. Events written before lines carry `addonId` or `planChangeId`: both are line or segment ids.', } createdAt: { type: string, format: date-time } SubscriptionPortalSessionCreate: type: object additionalProperties: false required: [role, actor] description: Exactly one of `buyerId` or `externalCustomerRef`. properties: buyerId: { type: string, format: uuid } externalCustomerRef: { type: string, maxLength: 160 } role: type: string enum: [viewer, billing, admin] description: '`viewer`: view. `billing`: view and pay. `admin`: view, pay and manage.' actor: type: object additionalProperties: false required: [id, name] description: The person using the portal, as your backend knows them. properties: id: { type: string, minLength: 1, maxLength: 200, description: 'Your user id' } name: { type: string, minLength: 1, maxLength: 160 } email: { type: string, format: email } impersonatorId: { type: string, minLength: 1, maxLength: 200, description: 'Your support user acting on behalf of `id`, if any', } origin: { type: string, format: uri, description: 'Browser origin that will use the token; must be allowed by the seller', } returnUrl: { type: string, format: uri, maxLength: 500, description: 'Where to send the user back; echoed in the response', } SubscriptionPortalSessionRevoke: oneOf: - type: object additionalProperties: false required: [sessionIds] properties: sessionIds: { type: array, minItems: 1, maxItems: 100, items: { type: string, format: uuid } } - type: object additionalProperties: false description: Exactly one of `buyerId` or `externalCustomerRef`. properties: buyerId: { type: string, format: uuid } externalCustomerRef: { type: string, maxLength: 160 } actorId: { type: string, description: 'Only the sessions of this `actor.id`' } SubscriptionPortalSession: type: object properties: sessionId: { type: string, format: uuid } token: { type: string, description: '`mps_…` bearer for the portal SDK' } expiresAt: { type: string, format: date-time } exchangeCode: { type: string } exchangeExpiresAt: { type: string, format: date-time } portalUrl: { type: string, format: uri, description: 'Morsis-hosted portal carrying only the one-time code', } buyerId: { type: string, format: uuid } role: { type: string, enum: [viewer, billing, admin] } returnUrl: { type: [string, 'null'], format: uri } rights: { type: object, properties: { canView: { type: boolean }, canPay: { type: boolean }, canManage: { type: boolean }, }, } PortalLoginCode: type: object required: [organization, email] properties: organization: { type: string, description: 'Seller slug' } email: { type: string, format: email } PortalLoginVerify: type: object required: [organization, otpId, code] properties: organization: { type: string } otpId: { type: string, format: uuid } code: { type: string } PortalExchange: type: object required: [code] properties: code: { type: string } tags: - name: Customers description: Customer contacts linked to the organization. - name: Team description: Organization members, pending invitations and assignable roles. - name: Merchant description: | El negocio al que pertenece la clave de API. Morsis organiza los datos de cada negocio en una organización. Estos métodos devuelven su nombre, contactos públicos y datos de publicación fiscal. No listan otros comercios ni sus usuarios. Por ejemplo, «Café del Centro» es el comercio; cada uno de sus locales es una sucursal. Empezar con `GET /merchant`. Usar `/merchant/legal` para consultar la información fiscal publicada. Requiere `branches:read` o `catalog:read`. - name: Branches description: | Los locales o puntos de operación del comercio. Cada sucursal tiene su dirección, horarios, catálogo y modalidades de venta. Por ejemplo, «Centro» y «Norte» pueden ser dos sucursales del mismo comercio. La clave determina cuáles se pueden consultar. `GET /branches` devuelve los locales disponibles. Conservar el `id` elegido como `branchId` y su `catalogId`, si tiene un catálogo asignado, para las siguientes consultas. Los canales publicados no garantizan disponibilidad de stock ni cupos. Requiere `branches:read`. - name: Catalogs description: | La carta o lista de lo que vende el comercio. Un catálogo organiza productos en secciones, como «Cafés» o «Postres», y puede compartirse entre sucursales. `catalogId` identifica el catálogo; `sectionId` identifica una sección. Las secciones sirven para organizar la navegación de una tienda. Consultar el catálogo asignado a la sucursal y usar `branchId` y `serviceMode` cuando corresponda para obtener precios y disponibilidad en ese contexto. Requiere `catalog:read`. - name: Products description: | Los artículos que se pueden elegir dentro de un catálogo. Cada producto tiene un `productId`, precio y posibles opciones, por ejemplo el tipo de leche de un café. Consultar el detalle antes de construir un selector de opciones: los grupos pueden tener elecciones obligatorias y límites. Estos métodos consultan productos; no los crean ni modifican. La lista admite filtros y paginación: usar `meta.cursor` para la siguiente página mientras `meta.hasMore` sea verdadero. Requiere `catalog:read`. Las sugerencias devuelven qué ofrecer junto a un producto o antes de pagar un carrito: primero las recomendaciones del comercio, después lo que sus clientes compran juntos y, con sucursal, lo más vendido. Solo incluyen productos que se pueden vender en ese momento. - name: Site content description: | Los textos e imágenes publicados para un sitio del comercio. Permite que un sitio externo muestre el contenido que el comercio mantiene en Morsis. `siteId` identifica el sitio configurado para esa organización; obtenerlo durante la configuración de la integración. Esta API no ofrece un listado de sitios. La respuesta contiene contenido publicado, no borradores. No reemplaza las consultas de precios o productos del catálogo. Requiere `site_content:read`. - name: Carts description: | La selección de productos de una compra online en preparación. Crear el carrito con `branchId` y `serviceMode`, agregar productos con cantidades y opciones y usar los totales que calcula Morsis. `cartId` identifica ese carrito. Crear o editar un carrito no implica un cobro aprobado. Una sesión de pago devuelve `checkoutUrl`, donde el comprador puede pagar con los proveedores configurados por la sucursal. Confirmar el pago mediante el estado o una notificación verificada, no solo por el retorno a la URL de éxito. Requiere `cart:write`. - name: Shipping description: | La cotización del envío para una compra. Permite obtener opciones y costos de entrega según los datos enviados y la configuración disponible. Usar el esquema del método para completar sucursal de origen, destino y datos del paquete requeridos. Cotizar no equivale a despachar el pedido ni garantiza una reserva de envío. Requiere `cart:write`. - name: Withdrawals description: | Las solicitudes de arrepentimiento de una compra online. Permite recibir una solicitud del comprador y consultar su estado mediante el código devuelto. «Arrepentimiento» se refiere a la solicitud de cancelar una compra, no a retirar dinero de una cuenta. Registrar una solicitud no ejecuta un reembolso automático. Requiere `withdrawals:write` o `cart:write`. - name: Orders description: | Las ventas de un comercio, con sus productos, totales, pagos y comprobantes. Un pedido reúne los productos, totales y estado de una venta. Esta API permite listar y leer pedidos con o sin cupón de pago. El cupón es un código de barras de nueve dígitos que identifica un pedido ya armado para que otro sistema lo cobre. No es un cupón de descuento. Conservar el código como texto, incluidos sus ceros iniciales. Para listar pedidos, usar `GET /orders` con filtros de preparación, entrega, pago y presencia de cupón. El listado general devuelve resúmenes paginados; `GET /orders/{orderId}` devuelve el detalle. Para encontrar un pedido por cupón, enviar el código escaneado y `branchId` a `GET /orders`; esta búsqueda conserva el detalle completo. Las escrituras siguen limitadas a pedidos con cupón elegibles. Después se puede leer por `orderId`, editar mientras sea elegible y registrar un cobro con factura emitida por otra empresa. Cada comando incluye operador, caja externa, versión e idempotencia. El cierre informa un cobro externo ya realizado: no inicia un cargo ni emite una factura en Morsis. Después del cierre, la empresa que cobró informa los reembolsos parciales y la anulación de la venta con su nota de crédito; Morsis no devuelve dinero ni emite comprobantes. Los permisos de lectura, edición, cierre y reversión se conceden por separado: `orders:read`, `orders:write`, `orders:complete_external` y `orders:refund_external`. - name: Payment methods description: | Cómo pagó el comprador a la empresa externa. Devuelve los IDs admitidos para efectivo, tarjeta de débito, tarjeta de crédito, transferencia y otros métodos. Copiar el `id` de la respuesta en `payments[].methodId` al registrar el cierre externo y completar la referencia requerida por ese método. Estos IDs no representan cajas, proveedores de pago ni cuentas bancarias de Morsis. La caja externa se informa aparte, en `externalDeviceId`. Requiere `payment_methods:read`. - name: Subscriptions description: | Los planes, contratos, períodos y pagos de las suscripciones que vende el comercio. Un comprador se suscribe a un plan con un contrato; cada período del contrato genera su documento y su deuda. Estos métodos crean compradores y contratos, consultan períodos, documentos y derechos vigentes, y aplican cambios de plan, cancelaciones, pausas y pagos. Las vistas previas no tienen efectos. Cada mutación requiere `Idempotency-Key`. Requiere `subscriptions:read`, `subscriptions:write` o `subscriptions:portal` según el método; el servicio vuelve a validar el permiso en cada llamada. - name: Subscriptions portal description: | El portal donde el comprador consulta y gestiona sus suscripciones. Se autentica con una sesión de portal de corta duración (`Authorization: Bearer mps_…`), nunca con una clave de API. El servidor de la integración abre la sesión con `POST /subscriptions/portal-sessions`, o el comprador entra con el acceso propio de Morsis (`/portal/login/*`). Lo que el comprador puede hacer depende de los permisos de su representante y de las reglas del comercio, informadas en `capabilities`. - name: System description: | El estado del servicio y su contrato técnico. `GET /health` permite verificar que la API responde. `/openapi.yaml` publica los métodos, parámetros, esquemas y ejemplos que usa esta consola. Ambos recursos se consultan sin clave y no devuelven datos de ningún comercio. - name: Webhooks description: | Notificaciones que Morsis envía al servidor de una integración. A diferencia de una consulta a la API, aquí Morsis inicia la solicitud cuando ocurre un evento, como un cambio de catálogo o la publicación de contenido. La integración configura una URL receptora y valida la firma según el contrato del evento. Los eventos documentados no son rutas para llamar a Morsis. Las notificaciones de pago se configuran al crear la sesión de pago y se describen en su esquema. ```