Documentación pública · actualizada el 2026-09-21

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 1000 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
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 1000 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 de comprobantes en PNG o PDF 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

Cotizar tarifas y consultar DNI

Cotiza el costo de un envío de Shalom entre dos terminales por API (con API key de usuario, sin instancia) 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

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 1000 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

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.