Saltar al contenido
Shalom APIInicio rápido
Inicio rápido

Tu primera guía en 6 pasos

De la llave al aviso por webhook. Elige tu lenguaje una vez y todos los ejemplos cambian. Base: https://shalom.smartflow.pe/v1.

Crea tu llave

Entra al panel, crea tu cuenta y copia tu llave sk_…. Se ve una sola vez: guárdala como secreto en tu servidor (nunca en el navegador de tus clientes).

En los ejemplos va en la variable de entorno SHALOM_API_KEY. Para probarla:

curl "https://shalom.smartflow.pe/v1/yo" \
  -H "x-api-key: $SHALOM_API_KEY"

Conecta tu cuenta Shalom Pro

Manda el correo y la clave con que entras a pro.shalom.pe. Probamos el inicio de sesión de verdad y guardamos la clave cifrada.

La respuesta trae el id de la cuenta (cta_…): va como cuenta_id en todo lo demás.

curl -X POST "https://shalom.smartflow.pe/v1/cuentas" \
  -H "x-api-key: $SHALOM_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "email": "ventas@mitienda.pe",
    "password": "tu_clave_shalom",
    "nombre": "Principal"
  }'

Cotiza antes de enviar

Con los ids de agencia de origen y destino (búscalos en GET /v1/agencias o, sin llave, en GET /v1/publico/agencias/buscar?q=…). Sin producto te devuelve el precio de cada tamaño.

curl -X POST "https://shalom.smartflow.pe/v1/cotizar" \
  -H "x-api-key: $SHALOM_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "cuenta_id": "cta_123",
    "origen_id": 219,
    "destino_id": 543,
    "producto": "PAQUETE S"
  }'

Registra la guía

referencia es el id del pedido en tu sistema: si la mandas dos veces, la segunda devuelve la misma guía (ya_existia: true) y no se crea otra.

Respuesta 201 con guia, codigo, clave, precio y rastreo_url. Si algo falta, 400 DATOS con la lista completa en errores, sin tocar Shalom.

curl -X POST "https://shalom.smartflow.pe/v1/guias" \
  -H "x-api-key: $SHALOM_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "cuenta_id": "cta_123",
    "referencia": "PED-1001",
    "envio": {
      "documento": "11111111",
      "telefono": "987654321",
      "origen_ter_id": 219,
      "destino_ter_id": 543,
      "producto": "PAQUETE S"
    }
  }'

Rastrea el envío

Estado y movimientos con el número de guía. Para muchas a la vez: POST /v1/rastreo/lote (hasta 50).

curl "https://shalom.smartflow.pe/v1/rastreo/103149001?cuenta_id=cta_123" \
  -H "x-api-key: $SHALOM_API_KEY"

Recibe avisos por webhook

Registra tu URL (la respuesta trae el secreto whsec_… una sola vez) y luego suscribe las guías con POST /v1/suscripciones. Cuando cambie el estado te llega un POST firmado: cómo verificar la firma.

curl -X PUT "https://shalom.smartflow.pe/v1/webhook" \
  -H "x-api-key: $SHALOM_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://mitienda.pe/webhooks/shalom"
  }'

¿Prefieres no programar? Usa los conectores de n8n, Make o Zapier, o pídeselo a tu asistente de IA con el servidor MCP. Todas las rutas y campos: referencia · llms-full.txt.