# Integrar tu sistema con Megarepartos Megarepartos le escribe a cada cliente fijo de un negocio de reparto a domicilio (agua y soda, garrafas, lácteos, verdulería…) antes del reparto por WhatsApp oficial, una IA anota lo que contesta como pedido y lo dudoso queda en una bandeja para una persona. Esta guía es para conectar eso con otro sistema: el de gestión que usa el negocio, uno propio (hecho a mano o con una IA como Claude Code) o un asistente como Claude. En los ejemplos, `https://` es la dirección de Megarepartos desde donde estás leyendo esto. > Lo que tu sistema puede hacer con la clave lo autoriza el admin del negocio al crearla, y lo puede revocar cuando quiera. Tu sistema nunca habla con Meta ni recibe el acceso de WhatsApp: habla con Megarepartos. ## Si sos una IA que ayuda a integrar un sistema - Usá sólo lo que dice esta guía y la documentación de `https:///api/v1/docs`. No inventes endpoints ni campos. - La clave (`mrk_...`) es un secreto: va en una variable de entorno, nunca en el código ni en el repositorio. - `POST /api/v1/consultas` y la herramienta `mandar_consulta` mandan mensajes reales de WhatsApp que Meta le cobra al negocio. Antes de usarlos, confirmalo con la persona. - Verificá siempre la firma de los avisos (webhooks) antes de confiar en el contenido. ## Paso 1: crear la clave 1. El admin del negocio entra a Megarepartos y va a «Integraciones». 2. Pone para qué sistema es la clave, lee la autorización y la acepta. 3. Copia la clave que aparece. Se muestra una sola vez: si se pierde, se revoca y se crea otra. La clave va en cada pedido, en el header `Authorization: Bearer mrk_...` (o en `X-Api-Key`, si tu sistema no puede mandar Authorization). ``` export MEGAREPARTOS_API_KEY="mrk_..." curl https:///api/v1/zonas -H "Authorization: Bearer $MEGAREPARTOS_API_KEY" ``` ## Paso 2: sincronizar los clientes Cada cliente se identifica por `id_externo`: el código que tiene en tu sistema. `PUT` lo crea o lo actualiza, y mandarlo dos veces no duplica nada. Si ya existe un cliente con el mismo teléfono y sin código (porque lo cargaron a mano), se le asigna el código en vez de crear otro. ``` curl -X PUT https:///api/v1/clientes/C-1001 \ -H "Authorization: Bearer $MEGAREPARTOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "nombre": "Ana Gómez", "telefono": "351 555 1234", "direccion": "San Martín 123", "zona": "Norte", "notas": "Dejar en portería", "frecuencia": "semanal", "habituales": [{"producto": "Bidón 20L", "cantidad": 2}] }' ``` - Responde 201 si lo creó y 200 si lo actualizó. - La zona y los productos van por nombre, como están cargados (`GET /api/v1/zonas` y `GET /api/v1/productos`). Si un nombre no existe, la respuesta dice cuáles hay. - Un campo que no mandás no se toca. `"zona": ""` le saca la zona y `"habituales": []` los vacía. - `DELETE /api/v1/clientes/C-1001` lo da de baja (deja de consultarlo; no se borra su historial). - `GET /api/v1/clientes?id_externo=C-1001` lo busca. Sin filtro lista todos, de a 100 (`limite` y `offset`). ## Paso 3: traer los pedidos Lo que contestaron los clientes, del más viejo al más nuevo: un pedido (`"accion": "confirmo"`, con productos y cantidades) o "esta vez no" (`"accion": "rechazo"`). ``` curl "https:///api/v1/pedidos?desde=2026-11-14T00:00:00-03:00" \ -H "Authorization: Bearer $MEGAREPARTOS_API_KEY" ``` - `desde` es inclusivo. Para no perder ninguno, en la próxima llamada usá el `ultimo` que te devolvió y descartá los `id` que ya tenías. - Sin `desde`, devuelve la última semana. - Si preferís que te avisemos en vez de preguntar cada tanto, usá los avisos (paso 5). ## Paso 4: la bandeja y la consulta - `GET /api/v1/bandeja`: los mensajes que la IA no resolvió sola, con el `motivo`. Los atiende una persona desde Megarepartos. - `POST /api/v1/consultas`: manda por WhatsApp la consulta "¿te llevo lo de siempre?". **Son mensajes reales que Meta le cobra al negocio.** Respeta las bajas, las pausas y el tope diario. ``` curl -X POST https:///api/v1/consultas \ -H "Authorization: Bearer $MEGAREPARTOS_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: reparto-norte-2026-11-14" \ -d '{"zona": "Norte"}' ``` Va exactamente una de estas: `"zona"`, `"clientes"` (lista de `id_externo`) o `"todos": true`. Con el mismo `Idempotency-Key`, repetir el pedido no manda dos veces. ## Paso 5: recibir avisos (webhooks) En «Integraciones», el admin pone la dirección `https` de tu sistema en la clave. Te aparece un secreto de firma (`whsec_...`) una sola vez: guardalo. Con «Probar» te llega un aviso de prueba. Avisos que mandamos, como POST con JSON: - `pedido.anotado`: un cliente contestó y quedó anotado (pedido o "esta vez no"). - `mensaje.para_atender`: llegó algo que tiene que mirar una persona, con el motivo. - `cliente.baja`: un cliente pidió no recibir más mensajes. - `prueba`: el aviso de prueba. ``` POST https://tu-sistema.example.com/megarepartos X-Megarepartos-Evento: pedido.anotado X-Megarepartos-Id: 6f1c... X-Megarepartos-Fecha: 1794691450 X-Megarepartos-Firma: sha256=3a7b... {"id": "6f1c...", "tipo": "pedido.anotado", "fecha": "2026-11-14T21:04:10+00:00", "datos": {"pedido": {"id": "...", "accion": "confirmo", "productos": [{"nombre": "Bidón 20L", "cantidad_llenos": 2, "cantidad_vacios": 2}], "observacion": "dejar en portería", "cliente": {"id": "...", "id_externo": "C-1001", "nombre": "Ana Gómez", "telefono": "+5493515551234"}}, "mensaje": {"id": "...", "tipo": "text", "texto": "sí", "fecha": "..."}}} ``` - **Verificá la firma** antes de usar el contenido: es `sha256=` más el HMAC-SHA256 de `"{X-Megarepartos-Fecha}."` seguido del cuerpo crudo (los bytes tal cual llegaron), con tu secreto `whsec_...`. Compará en tiempo constante. - **Rechazá los avisos viejos:** si `X-Megarepartos-Fecha` (segundos Unix) es de hace más de 5 minutos, descartalo. Así un aviso capturado no se puede reenviar. - Los avisos salen dentro de los 15 minutos de pasar lo que avisan. - Respondé con un 2xx rápido. Si no, reintentamos a los 15 minutos, a los 30 minutos, a las 2 horas y después cada 12 horas; a los 8 intentos dejamos de intentar. - Puede llegar el mismo aviso dos veces: usá `id` para no procesarlo dos veces. - No seguimos redirecciones y sólo mandamos a direcciones públicas de internet. Verificar la firma en Python: ``` import hashlib, hmac, time def firma_valida(cuerpo: bytes, fecha: str, recibida: str, secreto: str) -> bool: if not fecha.isdigit() or abs(time.time() - int(fecha)) > 300: return False # más de 5 minutos: no se acepta mensaje = f"{fecha}.".encode() + cuerpo esperada = "sha256=" + hmac.new(secreto.encode(), mensaje, hashlib.sha256).hexdigest() return hmac.compare_digest(esperada, recibida) ``` En Node: ``` import crypto from "node:crypto"; function firmaValida(cuerpo, fecha, recibida, secreto) { if (!/^\d+$/.test(fecha) || Math.abs(Date.now() / 1000 - Number(fecha)) > 300) return false; const mensaje = Buffer.concat([Buffer.from(`${fecha}.`), cuerpo]); const esperada = "sha256=" + crypto.createHmac("sha256", secreto).update(mensaje).digest("hex"); return recibida.length === esperada.length && crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(recibida)); } ``` ## Errores Siempre con la misma forma, y el mensaje en castellano para mostrarlo tal cual: ``` {"error": {"code": "VALIDACION_SEMANTICA", "message": "No existe la zona «Sur». Las zonas son: Centro, Norte.", "details": {"zonas": ["Centro", "Norte"]}}} ``` - 400: faltan datos o están mal escritos. - 401: falta la clave, no es válida o fue revocada. - 402: se pasa del plan (cupo de clientes o tope diario de mensajes). - 404: no existe (o es de otro negocio). - 422: los datos no cierran (zona o producto que no existe, cliente dado de baja de WhatsApp). - 503: Meta o WhatsApp no respondieron; probá de nuevo más tarde. ## Con Claude (MCP) Megarepartos tiene un servidor MCP en `https:///api/mcp` con estas herramientas: - De lectura: `listar_pedidos`, `ver_bandeja`, `buscar_clientes` y `ver_productos_y_zonas`. - De escritura: `guardar_cliente` y `mandar_consulta`. Claude pide confirmación antes de usarlas; `mandar_consulta` manda mensajes reales que Meta cobra. ### claude.ai, Claude Desktop y el celular Se conecta entrando con tu cuenta de Megarepartos, sin copiar ninguna clave: 1. En claude.ai, abrí «Settings» → «Connectors» → «Add custom connector». 2. Pegá la dirección `https:///api/mcp` y guardá. 3. Tocá «Connect». Se abre Megarepartos: entrá con la cuenta de Google de tu negocio (tiene que ser la de un admin), leé qué va a poder hacer Claude y tocá «Autorizar». Queda disponible en claude.ai, en Claude Desktop y en la app del celular con la misma cuenta. Los planes Free de Claude permiten un solo conector propio. Para desconectarlo, en Megarepartos → «Integraciones» → «Conexiones de Claude» → «Desconectar». ### Claude Code Entrando con tu cuenta (sin clave): agregalo y después, dentro de Claude Code, escribí `/mcp` y elegí autenticarte. ``` claude mcp add --transport http megarepartos https:///api/mcp ``` Con una clave, para vos solo: ``` claude mcp add --transport http megarepartos https:///api/mcp --header "Authorization: Bearer mrk_..." ``` Para un equipo, con la configuración en el repositorio (`.mcp.json`) y la clave en una variable de entorno de cada uno: ``` claude mcp add --transport http --scope project megarepartos https:///api/mcp --header 'Authorization: Bearer ${MEGAREPARTOS_API_KEY}' ``` Usá un nombre de variable propio como `MEGAREPARTOS_API_KEY`: las que empiezan con `ANTHROPIC_` o `AWS_` no se expanden. ### Plugin de Claude Code El plugin trae el servidor MCP ya configurado y una habilidad que le explica a Claude cómo integrar un sistema con la API, los avisos y la firma. La clave va en la variable `MEGAREPARTOS_API_KEY`. ``` export MEGAREPARTOS_API_KEY="mrk_..." /plugin marketplace add / /plugin install megarepartos@megarepartos ``` > `/` es el repositorio público donde se publique el plugin: todavía no está publicado. Mientras tanto se puede probar desde una copia local con `/plugin marketplace add ./integraciones`. ### API de Anthropic (Messages) A probar: Claude puede usar el servidor MCP directo desde la API de mensajes, con el header beta `anthropic-beta: mcp-client-2026-09-15`. ``` curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: mcp-client-2026-09-15" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "¿Qué pedidos entraron hoy?"}], "mcp_servers": [{"type": "url", "url": "https:///api/mcp", "name": "megarepartos", "authorization_token": "mrk_..."}], "tools": [{"type": "mcp_toolset", "mcp_server_name": "megarepartos"}] }' ``` ## Lo que no hace - No da acceso a WhatsApp ni a Meta: tu sistema no puede mandar mensajes libres, sólo la consulta de Megarepartos. - No borra clientes ni pedidos. - No cambia precios, productos ni zonas (eso se hace desde Megarepartos).