# 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.
