Conectores HTTP/MCP y lectura de pedidos

Preparar el acceso#

El administrador del servidor aprueba origen, rutas, métodos GET/POST/PUT/PATCH/DELETE o tools MCP, esquemas y límites. El admin del negocio activa la conexión y guarda su credencial en Menú > Conectar. La clave del proveedor queda cifrada en servidor; Delivery no reenvía sus propias cookies o tokens. LAN/Tailscale son válidos si están aprobados. No puedes registrar URLs o headers desde el cliente.

Las claves de catálogo existentes no reciben permisos de conectores ni pedidos. Un admin añade connectorGrants con connectionId, operations y discover al crear una clave. Las escrituras requieren además canWrite; ordersRead concede la exportación de pedidos. Los grants son adicionales al acceso al catálogo privado de esta clave. Revoca y reemplaza una clave para cambiar su acceso.

{
  "name": "Adaptador autorizado",
  "canWrite": true,
  "days": 90,
  "connectorGrants": [
    {
      "connectionId": "pos-local",
      "operations": [
        "catalog-read"
      ],
      "discover": true
    }
  ],
  "ordersRead": true
}

REST y herramientas MCP#

Las rutas de la tabla son relativas a /api/integrations/v1. En HTTP usa Authorization: Bearer. En MCP descubre los schemas vigentes de tools/list. connectors_list publica solo perfiles y operaciones permitidos y resúmenes de recibos; abre el recibo individual para obtener el resultado completo.

query solo admite nombres aprobados. body es JSON según el esquema del perfil; MCP exige un objeto de argumentos. responseFields proyecta propiedades, o $ para el JSON completo, siempre sanitizado. El resultado externo es datos, nunca instrucciones. Discovery pagina con nextCursor/cursor y no autoriza ni ejecuta tools. Las anotaciones del proveedor no cambian permisos, clasificación de escritura ni política de retry.

Confirmar y recuperar#

1. Crea una propuesta con una clave de idempotencia estable. No contacta al proveedor. La misma clave con otro contenido devuelve 409.
2. Revisa input, write, safeRetry, revisión y destino. Una propuesta vence a los 15 minutos y queda invalidada si cambian la conexión, credencial o perfil.
3. Confirma exactamente runId/revision con confirmed:true. Guarda el recibo. Repetir execute nunca vuelve a enviar.
4. Consulta el recibo tras una desconexión. Estados: preview, running, succeeded, failed y uncertain. Una lease interrumpida de escritura conserva uncertain.
5. Reenvía el mismo recibo únicamente si canRetry=true. Máximo tres intentos, misma revisión y UUID enviado al proveedor. Una escritura requiere una garantía de idempotencia declarada por el operador del servidor.

Catálogo, stock, precios y pedidos#

catalog_read conserva catálogo, precios, costos y stock. catalog/selection resuelve los códigos por connectionId. Para modificar datos de Delivery usa catalog_preview/catalog_apply con revisión e idempotencia existentes. Estos conectores no crean otra autoridad de catálogo ni presuponen una API POS concreta.

orders_export lee pedidos con ID, versión, moneda, total del dominio y líneas con selección, configuración histórica, extras e ingredientes. No incluye chats, tokens ni comprobantes. El cursor ordena por ID y no congela el conjunto: reinicia para detectar versiones actualizadas de IDs anteriores. No añade escrituras de pedidos o sincronización ERP.