Mercado --- checkout por correo (integradores)

Última actualización: Aug 31, 2026Sección: Integraciones

Mailoo no aloja tu tienda. La integración Market te ofrece una API de catálogo, APIs opcionales de pedido para un flujo simple de "snapshot del carrito → pedido por correo" y APIs del panel de control para que el propietario del proyecto liste pedidos y cambie estados.

Relacionado: lectura de catálogo y atributos --- market-catalog-csv{.interpreted-text role="doc"} / market-catalog-external-api{.interpreted-text role="doc"}. OpenAPI --- https://api.mailoo.app/docs/v1.

Arquitectura

  • Carrito / caché de catálogo: Mantén el estado del carrito en el sitio del integrador (p. ej. localStorage o un store del cliente). Actualiza precios usando ``GET /api/v1/market/.../effective-price?kind=...`` con la clave del tipo de precio (o las mismas reglas de resolución) antes de enviar para que los totales coincidan con el servidor. Consulta market-catalog-external-api{.interpreted-text role="doc"} (Tipos de precio y precio efectivo).
  • Secretos: Todas las llamadas con ``X-API-Key`` se ejecutan desde tu servidor o BFF, nunca desde paquetes públicos del navegador.
  • Enviar pedido: Tu BFF hace ``POST`` a Mailoo con ``market.order.submit``; Mailoo almacena un snapshot de líneas y precios resueltos, envía un correo de confirmación al comprador cuando esa integración Market tiene SMTP saliente configurado (panel de control Conexión y ajustes → Correo saliente (SMTP) --- mismo outboundMail que las integraciones FORM/CONTACT), y devuelve un ``accessToken`` de un solo uso para consulta de solo lectura. El SMTP global de la plataforma (GLOBAL_SMTP_*) no se usa para este correo.
  • Después del envío: El comprador (o tu SPA) puede llamar a ``GET /api/v1/market/public/orders/{orderId}?token=`` sin clave API hasta que el token expire. Si el token se pierde, el comprador solo tiene el correo y el id de pedido que muestres en la UI.
  • Back office: El propietario del proyecto usa rutas Bearer bajo ``/api/v1/projects/{uid}/integrations/{id}/market/orders/...`` para listar pedidos, ver detalle y actualizar estado.

Crear pedido (BFF)

  • ``POST {baseUrl}/api/v1/market/{projectUid}/integrations/{integrationId}/orders``
  • Cabeceras: ``X-API-Key`` con ``market.order.submit`` (o FULL)
  • Cuerpo (JSON):
  • ``customerEmail`` (obligatorio) --- dirección del comprador (normalizada a minúsculas)
  • ``items`` (obligatorio, no vacío) --- cada elemento:
  • ``productId`` --- debe estar ``PUBLISHED`` en esta integración
  • ``priceKindId`` o ``priceKindKey`` (exactamente uno) --- el tipo de precio. Prefiere ``priceKindKey`` (p. ej. base) para configuración del integrador; ``priceKindId`` es el CUID interno si ya lo tienes (p. ej. de líneas de ``GET .../price-lists/...``).
  • ``quantity`` --- string decimal positivo (p. ej. "2", "1.5")
  • ``variantId`` --- obligatorio si el producto tiene variantes, omitido (o null) si no tiene
  • ``measurementUnitId`` --- opcional; por defecto usa la unidad predeterminada del producto + reglas de resolución de effective-price
  • ``note``, ``metadata`` --- opcionales (definidos por el integrador)

Respuesta (201): ``data.id``, ``data.status`` (comienza como NEW), ``data.accessToken`` (almacenar solo en la sesión del comprador / devolver al cliente para UX), ``data.accessExpiresAt``, ``data.totalAmount``, ``data.currency`` y ``data.emailToCustomer`` (si el outboundMail de la integración pudo enviar: SENT / FAILED / NOT_CONFIGURED).

Lectura pública (comprador)

  • ``GET {baseUrl}/api/v1/market/public/orders/{orderId}?token={accessToken}``
  • O ``X-Market-Order-Token: {accessToken}``
  • Sin ``X-API-Key``. Token inválido/faltante devuelve 404 (igual que pedido desconocido) para evitar filtrar la existencia.

TTL del token por defecto es 72 horas; la API puede establecer ``MARKET_ORDER_ACCESS_TOKEN_TTL_HOURS`` (1--720) en el host de Mailoo.

Panel del propietario (JWT)

Rutas autenticadas (resumen):

  • ``GET .../market/orders`` --- lista (consulta ``limit`` opcional, máx. 100)
  • ``GET .../market/orders/{orderId}`` --- snapshot completo + ``attributesSnapshot`` de línea
  • ``PATCH .../market/orders/{orderId}`` --- ``{ "status": "...", "note"?: "..." }`` (transiciones de estado: los estados terminales ``REJECTED``, ``FULFILLED``, ``CANCELLED`` no pueden moverse a un estado diferente)
  • ``GET .../market/orders/{orderId}/status-events`` --- historial de auditoría

Estados: ``NEW``, ``PROCESSING``, ``CONFIRMED``, ``REJECTED``, ``FULFILLED``, ``CANCELLED``.

Alcances de las claves API

  • ``market.external-read`` --- solo ``GET`` del catálogo; usar en un BFF que obtiene páginas de producto.
  • ``market.order.submit`` --- solo ``POST .../orders``; puede ser una clave restringida diferente en el BFF de checkout.
  • Puedes usar una clave FULL solo en backends confiables; para mínimo privilegio, separa lectura vs envío como arriba.

:::: note ::: title Note :::

El panel de control de Mailoo es la consola de administración; el checkout orientado al cliente se ejecuta en tu sitio y llama a la API pública de Mailoo de la misma forma que lo haría cualquier tercero. ::::

📚