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://megarepartos.com.ar 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://megarepartos.com.ar/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://megarepartos.com.ar/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://megarepartos.com.ar/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://megarepartos.com.ar/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://megarepartos.com.ar/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://megarepartos.com.ar/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://megarepartos.com.ar/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://megarepartos.com.ar/api/mcp

Con una clave, para vos solo:

claude mcp add --transport http megarepartos https://megarepartos.com.ar/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://megarepartos.com.ar/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 <OWNER>/<REPO>
/plugin install megarepartos@megarepartos

<OWNER>/<REPO> 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://megarepartos.com.ar/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).