Documentación pública · actualizada el 2026-11-11

Integra Shalom por API en minutos.

Todo lo que necesitas para conectar tu ecommerce o automatización con Shalom: autenticación, rastreo, agencias, creación de guías en Shalom Pro, cotizaciones y webhooks firmados. Cada sección incluye ejemplos reales en cURL, JavaScript, PHP y Python contra https://api.shalom-api.lat.

Qué es la API de Shalom

Shalom API Perú es una API REST que expone la operación de la empresa de encomiendas Shalom: consulta el estado de una guía, entrega el catálogo completo de agencias con coordenadas, devuelve los ubigeos del Perú y permite crear envíos reales en Shalom Pro con las credenciales de tu cliente final. Responde JSON sobre HTTPS y se autentica con la cabecera x-api-key.

La cobertura son 540 agencias en los 25 departamentos, con latitud y longitud listas para pintar en un mapa. El límite es de 60 peticiones por minuto y todas las respuestas de tracking son el espejo del sistema de Shalom.

Por dónde empezar según lo que necesites

Si necesitasEmpieza por
Saber dónde está un pedidoRastrear envíos
Cotizar antes de que el cliente compreCotizar tarifas y consultar DNI
Crear la guía en Shalom ProCrear envíos
Gestionar envíos ya creadosOperaciones de envíos
Conectar la cuenta de tu clienteInstancias de Shalom Pro
Elegir la agencia de destinoAgencias y cobertura
Validar la dirección del clienteUbicaciones (ubigeos)
Enterarte de un cambio de estado sin consultarWebhooks de tracking
Configurar el accesoAutenticación y API keys
Depurar una respuesta con errorErrores y límites
Usarlo desde n8nInstalar el nodo de n8n
Usarlo desde un agente de IAInstalar la skill de IA

Qué hace distinta a esta API

  • ▸Webhooks firmados con HMAC-SHA256: te enteras del cambio de estado sin hacer polling.
  • ▸Demo pública sin API key: GET /public/agencies responde desde el primer minuto, así ves el formato real antes de integrar.
  • ▸540 agencias con latitud y longitud, listas para un mapa o un selector de destino.
  • ▸Nodo oficial de n8n con repositorio público y paquete publicado en npm.
  • ▸Documentación pensada para agentes: llms.txt, la referencia completa en un solo archivo y una skill instalable en Claude Code, Cursor, Codex o VS Code.
  • ▸Cada página se sirve en markdown si la pides con Accept: text/markdown.

Autenticación y API keys

Cómo autenticar tus peticiones a Shalom API Perú con el header x-api-key, validar tu API key, conocer los límites por plan y el rate limit de 60 peticiones por minuto.

Leer guía

Rastrear envíos

Rastrea envíos de Shalom por API: consulta individual con POST /track, seguimiento en lote de hasta 50 guías, descarga del ticket oficial en PDF o imagen y etiquetas de envío.

Leer guía

Agencias y cobertura

Consulta el catálogo completo de agencias de Shalom por API: listado, búsqueda avanzada por departamento, provincia y cercanía con coordenadas, y versión pública sin API key.

Leer guía

Ubicaciones (ubigeos)

Obtén los ubigeos del Perú con cobertura Shalom por API: departamentos, provincias de un departamento y distritos de una provincia, con IDs para crear envíos.

Leer guía

Instancias (sesión Shalom Pro)

Conecta tu cuenta Shalom Pro como instancia: crea, lista y elimina instancias, y gestiona la sesión de Shalom Pro (login, estado y logout) por API.

Leer guía

Crear envíos en Shalom Pro

Crea guías reales en Shalom Pro por API: registro individual con auto-completado de destinatario, envíos masivos en lote, pendientes y perfil del usuario Shalom.

Leer guía

Operaciones de envíos

Gestiona los envíos ya creados en Shalom Pro: lista y anula pendientes, consulta el seguimiento en tránsito, filtra el historial de entregados y obtén los comprobantes con su enlace de descarga.

Leer guía

Cotizar tarifas y consultar DNI

Cotiza el costo de un envío de Shalom entre dos terminales por API con la tarifa de tu cuenta Shalom Pro y valida documentos de identidad (DNI/RENIEC) antes de crear la guía.

Leer guía

Webhooks de tracking

Recibe un POST firmado con HMAC cada vez que un envío de Shalom cambia de estado: registro, consulta y eliminación del webhook, suscripción de guías y verificación de firma.

Leer guía

Autogestiones: gestionar una guía ya creada

Gestiona una guía ya creada en Shalom por API: cambia la clave de recojo, agrega un contacto, cambia el destino, registra una devolución, retiene o libera la carga y pide reparto a domicilio, con verificación por SMS o email.

Leer guía

Errores y límites

Tabla completa de códigos de error de Shalom API Perú: 400, 401, 403, 404, 429 y 500, el rate limit de 60 peticiones por minuto y las buenas prácticas de reintento con backoff.

Leer guía

Instalar la skill de IA

Instala la skill shalom-api en tu agente de IA (Claude Code, Cursor, Codex, OpenCode, VS Code) y enseña a la IA a rastrear envíos, buscar agencias, cotizar y crear guías de Shalom por API.

Leer guía

Instalar el nodo de n8n

Instala el nodo comunitario n8n-nodes-shalom en n8n self-hosted y conecta Shalom API a tus flujos: tracking, agencias, cotizaciones y creación de envíos sin escribir HTTP a mano.

Leer guía

Optimizaciones del tracking

Cómo mantiene Shalom API frescos los estados de envío: solo las guías suscritas se actualizan en segundo plano, pausa nocturna, guías inactivas (DORMANT) y refresco en vivo al consultar /track.

Leer guía

Tu primera petición

Solicita tu API key por WhatsApp y prueba la autenticación en segundos.

cURL
curl "https://api.shalom-api.lat/validate" -H "x-api-key: TU_API_KEY"

Preguntas frecuentes

¿Qué es la API de Shalom?

Una API REST que expone tracking de envíos, el catálogo de agencias, los ubigeos del Perú y la creación de envíos en Shalom Pro. Responde JSON sobre HTTPS y se autentica con la cabecera x-api-key.

¿Necesito una API key para usar la API de Shalom?

Para los endpoints de agencias, tracking, cuentas e instancias sí. Las rutas /public/* responden sin API key, así que puedes ver el formato real de las respuestas antes de solicitar acceso.

¿Puedo crear guías reales o solo consultar?

Las dos cosas. Consultar es inmediato con la API key. Crear guías reales en Shalom Pro requiere una instancia con sesión activa, usando las credenciales de tu cliente final.

¿En qué lenguajes hay ejemplos?

Cada sección incluye ejemplos en cURL, JavaScript, PHP y Python contra https://api.shalom-api.lat.

¿Hay documentación pensada para agentes de IA?

Sí: llms.txt con el índice, llms-full.txt con toda la referencia y una skill instalable en Claude Code, Cursor, Codex, OpenCode y VS Code.