Guía Técnica & Estándares de Integración

1. Autenticación con API Keys

Todas las peticiones a la API REST y al servidor MCP requieren autenticación mediante una clave API emitida por sucursal. La clave debe transmitirse en la cabecera HTTP X-API-Key o como token Bearer en Authorization.

curl -X GET https://mau.rest/api/v1/pos/menus/active \
  -H "X-API-Key: mau_live_9f83a21b44c80219" \
  -H "X-Restaurant-Slug: petit-gateau"

import requests

url = "https://mau.rest/api/v1/pos/menus/active"
headers = {
    "X-API-Key": "mau_live_9f83a21b44c80219",
    "X-Restaurant-Slug": "petit-gateau"
}
response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch("https://mau.rest/api/v1/pos/menus/active", {
  headers: {
    "X-API-Key": "mau_live_9f83a21b44c80219",
    "X-Restaurant-Slug": "petit-gateau"
  }
});
const menu = await response.json();
console.log(menu);

2. Multi-tenancy & Contexto RLS

MAURICIO opera bajo una arquitectura multi-tenant estricta gobernada por Row-Level Security (RLS) en PostgreSQL. Cada petición debe especificar el slug de la sucursal activa mediante la cabecera X-Restaurant-Slug.

3. Estándar de Errores (RFC 7807)

Todas las respuestas de error en la API REST y en llamadas JSON-RPC retornan un cuerpo normalizado conforme al RFC 7807 Problem Details:

4. Rate Limiting & Cuotas

Para garantizar la resiliencia en horas pico de servicio (almuerzo y cena), cada sucursal dispone de una cuota de 600 peticiones por minuto por API Key.

• X-RateLimit-Limit: Total de peticiones autorizadas por ventana (60s).
• X-RateLimit-Remaining: Peticiones restantes en la ventana activa.
• X-RateLimit-Reset: Timestamp UNIX en segundos para el reinicio del contador.

5. Webhooks & Verificación de Firmas HMAC SHA-256

Los eventos del restaurante (órdenes enviadas a cocina, reservaciones creadas o mesas cobradas) se envían vía POST a tus endpoints registrados con la firma criptográfica en la cabecera X-Mauricio-Signature.

import hmac, hashlib

def verify_mauricio_webhook(payload_bytes, signature_header, secret):
    expected = hmac.new(secret.encode(), payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

const crypto = require('crypto');

function verifyMauricioWebhook(payloadBuffer, signatureHeader, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const expected = 'sha256=' + hmac.update(payloadBuffer).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

6. Hardware Print Bridge (ESC/POS Edge)

Las impresoras térmicas de tickets y comanderas locales se comunican con MAURICIO a través del servicio Print Bridge mediante un modelo de pull continuo por HTTP continuo o WebSockets.

• No requiere apertura de puertos en el router del restaurante ni IP pública fija.
• Soporta protocolos térmicos nativos ESC/POS y Star Micronics.
• Reclamado de trabajos atómico vía POST /api/print-bridge/v1/jobs/claim para evitar impresiones duplicadas.

7. Model Context Protocol (MCP) & Two-Phase Commit

El servidor MCP de MAURICIO implementa el protocolo oficial (versión 2024-11-05) mediante transporte Streamable HTTP en POST /api/v1/mcp.

Para probar las 18 Macro-Tools canónicas y configurar Cursor o Claude con un solo clic, visita nuestro hub dedicado:

8. Autodescubrimiento para Agentes Autónomos

Frameworks agénticos (LangChain, AutoGen, CrewAI, LlamaIndex) pueden auto-configurar herramientas y esquemas consumiendo nuestros descriptores estándar:

• /.well-known/mcp.json: Server Card oficial para descubrimiento en el dominio.
• /developers/server.json: Manifiesto de publicación en el registro MCP.
• /llms.txt & /llms-full.txt: Contexto condensado y exhaustivo en Markdown sin ruido de maquetación.