Documentación REST API
Conectar con Morsis.
Una API para conectar un sitio, una tienda online o un sistema de cobro con un negocio que usa Morsis. Esta guía explica los conceptos, el acceso y las llamadas de cada integración.
Entender los conceptoscurl --request GET https://api.morsis.com/v1/healthConsultar el estado de la API. No requiere una clave.
Entender el modelo
Un comercio, sus sucursales y lo que vende
Morsis es una plataforma para gestionar la operación de un negocio: productos, pedidos y cobros, entre otras funciones. Esta API conecta sistemas externos con una parte de esa información. Los datos disponibles dependen del comercio al que pertenece la clave y de los permisos habilitados.
«Café del Centro» es el comercio. «Centro» y «Norte» son sus sucursales. La carta es un catálogo; «Cafés» es una sección y «Café con leche» es un producto. Antes de consultar precios o tomar un pedido, se elige la sucursal que lo atenderá.
- ComercioCafé del Centro
- SucursalLocal Centro
- CatálogoCarta de la sucursal
- ProductoCafé con leche
Varias sucursales pueden compartir un catálogo. Los precios y la disponibilidad deben consultarse para la sucursal y la modalidad de entrega correspondientes.
- Comercio
merchant - Es el negocio que usa Morsis. Su organización agrupa sucursales, configuración y usuarios. La clave de API identifica esa organización:
/merchantdevuelve su perfil público, no una lista de todos los negocios que usan Morsis. Consultar el comercio. - Sucursal
branch - Es un local o punto de operación del comercio, con dirección, horarios y configuración de venta. Su
idse usa comobranchIden otras solicitudes. La clave puede tener acceso a todas o solo a algunas sucursales. Obtener sucursales. - Catálogo, sección y producto
- El catálogo organiza lo que se vende. Las secciones agrupan productos, por ejemplo «Cafés»; cada producto tiene su identidad, precio y opciones.
catalogIdidentifica el catálogo yproductIdel producto. Una opción puede ser «Leche de almendras». Explorar catálogos. - Carrito y sesión de pago
- El carrito es una selección de productos para una compra online, todavía en preparación. Morsis calcula los totales. Una sesión de pago permite obtener un
checkoutUrly llevar al comprador a la página de pago. Crear un carrito no significa que la compra esté pagada. Crear un carrito. - Pedido y cupón de pago
- El pedido reúne los productos, totales y estado de una venta. Un cupón permite encontrar un pedido ya armado mediante un código de barras de nueve dígitos. No es un cupón de descuento. Las lecturas de
/ordersincluyen pedidos con o sin cupón. El listado permite combinar estados de preparación, entrega y pago, filtrar por sucursal y usar paginación.hasPaymentCoupon=true&paymentStatus=unpaidbusca cupones pendientes de pago. Las escrituras siguen limitadas a pedidos con cupón elegibles. Listar pedidos y consultar filtros. - Método de pago y cobro externo
- El método describe cómo pagó el comprador: efectivo, tarjeta de débito, tarjeta de crédito o transferencia, por ejemplo. En la integración de cupones, otra empresa cobra y factura con su propio CUIT; Morsis registra lo informado.
methodIdno identifica una caja ni una cuenta bancaria de Morsis. Consultar métodos de pago.
Modalidad de entrega: serviceMode indica cómo se entrega la compra, por ejemplo retiro (takeaway) o envío (delivery). Usar las modalidades habilitadas para la sucursal. Los identificadores se obtienen de las respuestas de la API; los nombres del ejemplo no son IDs.
Elegir un recorrido
¿Qué necesita hacer la integración?
No todas las integraciones necesitan todos los recursos. Estos recorridos muestran el orden de las primeras llamadas; cada enlace abre el método con sus parámetros y ejemplos.
Mostrar productos en un sitio o aplicación
Consultar qué ofrece el comercio, sin crear una venta.
- Consultar el comercio para mostrar su nombre y datos públicos.
- Listar sucursales y conservar el
idde la elegida y sucatalogId, si tiene un catálogo asignado. - Listar productos del catálogo con
branchIdyserviceModepara consultar el contexto de venta correspondiente. Consultar secciones para organizar la navegación. - Consultar sugerencias junto a un producto y, antes de pagar, sugerencias para el carrito, con la misma sucursal y modalidad. Solo incluyen productos que se pueden vender en ese momento. Si no hay sugerencias,
datallega vacío y la página se muestra sin ellas. Al agregar una sugerencia al carrito, enviarmeta.decisionId,sourceyrankensuggestion.
Vender desde una tienda online
Continuar desde el catálogo para armar la compra y llevar al comprador al pago.
- Crear un carrito con la sucursal y la modalidad de entrega.
- Agregar productos con sus IDs, cantidades y opciones. Usar los totales devueltos por Morsis.
- Crear una sesión de pago y abrir el
checkoutUrl. Consultar el estado del carrito o procesar la notificación de pago configurada; volver a una URL de éxito no es prueba suficiente de cobro.
Mostrar stock por local y retiro
Para una tienda con varios locales: dónde se puede retirar cada producto y qué hay para envío a domicilio.
- Consultar las políticas de envío y conservar
dispatchBranchId(de dónde salen los envíos) ypickupLocations(locales de retiro). - Consultar la disponibilidad de retiro de un producto: cada local devuelve
available,low_stock,out_of_stockounavailable. Para talle o color, enviar las opciones elegidas enoptionIds. - Listar productos con
branchIdeinStock=truepara un filtro «Disponible para retirar en…». ConbranchId={dispatchBranchId},inStockindica el stock para envío a domicilio.
Sincronizar clientes
- Buscar clientes por nombre, correo o teléfono. Recorrer las páginas con
meta.cursor. - Crear un cliente con correo o teléfono, o una empresa con nombre. Si ya existe un contacto coincidente, la respuesta indica
matchedExisting. - Actualizar sus datos enviando solamente los campos que cambian. Los datos de contacto pueden compartirse entre organizaciones vinculadas a la misma identidad.
Invitar y administrar usuarios
- Consultar los usuarios y los roles asignables. El ID del miembro es distinto del ID de la persona.
- Enviar una invitación con correo y rol. La persona debe aceptar el correo; los tokens no se devuelven por API.
- Modificar puesto o sucursales. El rol no se puede cambiar por API. Nombre y correo se administran desde el perfil personal.
Cobrar un cupón desde el sistema de otra empresa
El pedido ya existe en Morsis. La empresa externa lo cobra y emite su propia factura.
- Buscar el pedido por código de cupón y sucursal. Conservar el ID del pedido y su versión.
- Editar una línea si hace falta. Informar el usuario de Morsis que operó, la caja externa, la versión y una clave de idempotencia.
- Consultar métodos de pago y, después del cobro y la facturación externa, registrar el cierre.
Para asistentes de desarrollo
Integrar con IA, con el contrato a mano
Un asistente necesita conocer los conceptos y las reglas de la API antes de escribir código. Estos recursos se pueden leer sin JavaScript ni una clave de API.
- llms.txt
- Índice breve con enlaces para encontrar la documentación relevante.
- Guía en Markdown
- Conceptos, permisos, secuencias de llamadas y reglas de reintentos para orientar la integración.
- OpenAPI
- Contrato exacto de los métodos, campos, ejemplos y respuestas. Es la referencia para generar código.
- Contexto completo
- Guía y OpenAPI en un archivo para herramientas que admiten contextos grandes.
Leer /llms.txt y /docs/agents.md, y consultar /v1/openapi.yaml antes de generar una integración con Morsis. Identificar el recorrido, el entorno y los permisos necesarios. Usar placeholders para credenciales e IDs. No ejecutar operaciones reales sin una solicitud explícita.Agregar al mensaje qué integración se necesita construir. No incluir claves ni datos de clientes.
Compartir los enlaces permite al asistente consultar estas fuentes. No todas las herramientas descubren llms.txt automáticamente. Los enlaces a localhost requieren una herramienta con acceso al entorno local; para un asistente remoto, usar la documentación desplegada o adjuntar los archivos.
Preparar la primera llamada
Crear una clave
Desde Integraciones, crear una clave con los permisos necesarios. El módulo API pública debe estar habilitado.
Elegir el entorno
La consola inicia en este entorno. Seleccionar el servidor y usar una clave de la organización que corresponda.
Probar una llamada
Ingresar la clave en «Authorize» y abrir un método. «Try it out» permite enviar parámetros y consultar la respuesta.
Claves, permisos e identificadores
Una clave de API identifica a una integración dentro de una organización de Morsis. Un scope es un permiso de esa clave, por ejemplo catalog:read para consultar catálogos. Los scopes requeridos aparecen en la descripción de cada método.
La persona que administra el comercio debe habilitar el módulo API pública y crear la clave desde Integraciones. El sistema externo envía esa clave desde su servidor en el encabezado Authorization: Bearer CLAVE_DE_API. No se envía un organizationId para elegir otro comercio.
curl 'https://api.morsis.com/v1/branches' \
--header 'Authorization: Bearer CLAVE_DE_API'Reemplazar CLAVE_DE_API por una clave con branches:read. La respuesta contiene data, una lista de sucursales; el id de cada una es el branchId que se utiliza en las siguientes llamadas. Para pruebas en staging, usar https://api.morsis.dev/v1 y una clave de ese entorno.
La clave debe conservarse en el servidor de la integración. El recorrido habitual es: navegador o aplicación del comprador → servidor de la integración → API de Morsis. El comprador no recibe la clave.
401: falta una clave válida.403: revisar scopes, módulo habilitado y acceso a la sucursal. En los cambios de pedidos también se verifican permisos del operador.409: en cambios de pedidos, revisar conflictos de versión o de idempotencia segúnerror.code.429: esperar el tiempo indicado porRetry-Afterantes de reintentar.
En la consola de esta página, «Authorize» permite ingresar la clave y «Try it out» habilita una llamada. Los valores entre llaves, como {branchId}, son parámetros que se reemplazan por IDs reales. GET consulta, POST crea o ejecuta una operación, PATCH modifica y DELETE elimina.
Convenciones de la API
- Rutas por recurso bajo
/v1. Campos JSON y filtros encamelCase. - Montos enteros en centavos y moneda explícita. Identificadores y códigos de cupón como texto, conservando los ceros iniciales.
- Fechas en
YYYY-MM-DDe instantes con zona horaria.issuedOnidentifica la fecha de la factura;occurredAt, el instante del cobro. - Respuestas con
datay errores conerror.codeyerror.message. Las validaciones pueden incluirerror.details. Cada respuesta tiene unX-Request-Id. - Filtros de catálogo:
branchId,serviceMode,sectionIdytagId. Los nombres anteriores siguen disponibles por compatibilidad. - Los métodos existentes mantienen su contrato. Los cambios incompatibles requieren una nueva versión de la API.
Integración de cupones y cobros externos
Antes de integrar, crear los usuarios operadores en Morsis y darles acceso a la sucursal y permiso para editar pedidos. actorUserId es el UUID de ese usuario en Morsis, no su nombre en el sistema externo. externalDeviceId es el ID de caja del sistema externo y se guarda para auditoría; no requiere dar de alta un dispositivo de Morsis.
- Buscar el pedido con
GET /orders, el código de nueve dígitos del cupón y la sucursal. Conservaridyversion. - Consultar
GET /payment-methods. Sus identificadores describen cómo cobra la otra empresa; no representan cajas propias. Las tarjetas se informan comodebit_cardocredit_card, con cuotas solo en crédito. - Usar
items[].lineItemIdpara editar una línea. Cada línea trae cantidad, opciones, total e IVA;taxBreakdowndesglosa el IVA del pedido. Para quitarla, usarPOST /orders/{orderId}/item-removals. Editar con el operador de Morsis, el ID de caja externa,expectedVersiony unIdempotency-Keypor operación. Usar la nueva versión de cada respuesta. - Informar el cierre con los pagos y la factura externa.
externalOperationIdyIdempotency-Keydeben coincidir. Los montos deben sumar exactamente el total del pedido. - Si después la empresa devuelve dinero, informar
POST /orders/{orderId}/external-refundscon el monto de cada pago (payments[].id), los productos devueltos si corresponde y su nota de crédito. Para anular la venta completa, usarPOST /orders/{orderId}/external-cancellationcon la nota de crédito por el total. - Ante una interrupción, repetir la misma solicitud con la misma clave. Un cierre confirmado no vuelve a cobrar ni a emitir una factura.
El cierre registra un cobro y una factura que ya existen en el sistema externo: no ejecuta un nuevo cargo ni emite una factura en Morsis. El cobro queda pendiente de liquidación por el tercero. La integración debe coordinar sus cajas para evitar cobrar dos veces el mismo cupón: la idempotencia evita duplicar el registro en Morsis, no los cobros realizados por fuera. Los reembolsos y las anulaciones se informan desde el sistema de la empresa que cobró: Morsis no devuelve dinero ni emite la nota de crédito, pero repone el stock y revierte la venta en sus registros. La liquidación posterior requiere un circuito específico.
Las llamadas de la consola son reales, incluidas las que modifican datos. La clave se mantiene en memoria y se elimina al recargar esta página. En una integración, usarla desde el servidor.
Referencia de la API
Elegir un método desde el índice para consultar sus parámetros, ejemplos y respuestas.