Referencia de la API
URL base, autenticación, formato de las respuestas y lista de todos los endpoints de Shalom API.
¿Usas un agente de IA?
Pásale a tu agente docs.shalom-api.lat/llms.txt, que lista cada página de la documentación en Markdown, o agrega .md a la URL de cualquier página para leerla en Markdown.
Shalom API es una API REST con respuestas JSON. Esta página reúne lo común a todos los endpoints y la lista completa; el detalle de cada uno está en su tema.
URL base
https://api.shalom-api.latTodas las peticiones usan HTTPS. Cuando hay cuerpo, envíalo en JSON con Content-Type: application/json.
Autenticación
Envía tu API key en el header x-api-key de cada petición, salvo en las rutas /public/*. La copias en el panel, en API Key. Detalles en Autenticación y API keys.
curl "https://api.shalom-api.lat/validate" \
-H "x-api-key: TU_API_KEY"Límites y errores
- 60 peticiones por minuto por API key. Al superarlo, la API responde
429con el headerretry-after. - Cada plan tiene una cuota mensual de operaciones. Solo consumen cuota las llamadas exitosas de los endpoints marcados con Sí en la tabla de abajo.
- Los errores responden con un código HTTP y un cuerpo JSON con el campo
error. Lista completa en Errores y límites.
Shalom Pro
Los endpoints marcados con Sí en la columna Shalom Pro operan sobre tu cuenta de Shalom Pro: necesitan una instancia con la sesión iniciada y su instanceId. Se llaman con tu misma API key.
Todos los endpoints
| Método | Ruta | Qué hace | Cuota | Shalom Pro |
|---|---|---|---|---|
| POST | /track | Rastrear una guía | Sí | No |
| POST | /track/batch | Rastrear hasta 50 guías | Sí, 1 por llamada | No |
| GET | /track/by-ose | Resolver un ose_id a guía y código | Sí | Opcional |
| GET | /track/voucher | Ticket oficial en PDF o imagen | Sí | Sí |
| GET | /track/label | Rótulo en PDF | Sí | Sí |
| GET | /agencies | Listar agencias | Sí | No |
| GET | /agencies/search | Buscar agencias y ordenar por cercanía | Sí | No |
| GET | /public/agencies | Listado público, sin API key | No | No |
| GET | /public/agencies/search | Búsqueda pública, sin API key | No | No |
| GET | /locations/departments | Departamentos con agencias | Sí | No |
| GET | /locations/departments/{depId}/provinces | Provincias de un departamento | Sí | No |
| GET | /locations/departments/{depId}/provinces/{provId}/districts | Distritos de una provincia | Sí | No |
| POST | /account/quote | Cotizar un envío | Sí | Opcional (recomendado) |
| GET | /account/dni/{dni} | Consultar un DNI | Sí | No |
| GET | /account/products | Catálogo de contenidos | No | No |
| POST | /account/register | Crear una guía | Sí | Sí |
| POST | /account/register-bulk | Crear guías en lote | Sí, 1 por llamada | Sí |
| POST | /account/get-user | Perfil del remitente | Sí | Sí |
| POST | /account/person/search | Buscar una persona registrada | Sí | Sí |
| POST | /account/pending-shipments | Envíos pendientes | Sí | Sí |
| DELETE | /account/pending-shipments | Anular un envío pendiente | Sí | Sí |
| GET | /account/tracking-list | Envíos en tránsito | Sí | Sí |
| GET | /account/history | Historial de entregados | Sí | Sí |
| GET | /account/vouchers | Comprobantes | Sí | Sí |
| POST | /shipments/pickup-code | Cambiar la clave de recojo | Sí | Sí |
| POST | /shipments/self-management | Iniciar una autogestión (envía el código) | No | Sí |
| POST | /shipments/self-management/confirm | Confirmar la autogestión | Sí | Sí |
| GET | /shipments/self-management | Historial de autogestiones | No | Sí |
| GET | /shipments/home-delivery/ubigeo | Ubigeo para reparto a domicilio | No | Sí |
| POST | /instances | Crear una instancia | No | No |
| GET | /instances | Listar instancias | No | No |
| DELETE | /instances | Eliminar una instancia | No | Sí (instanceId) |
| POST | /instances/status | Estado de la sesión | No | Sí |
| POST | /instances/login | Iniciar sesión en Shalom Pro | No | Sí |
| POST | /instances/logout | Cerrar sesión en Shalom Pro | No | Sí |
| PUT | /webhooks | Configurar el webhook | No | No |
| GET | /webhooks | Consultar el webhook | No | No |
| DELETE | /webhooks | Eliminar el webhook | No | No |
| GET | /webhooks/deliveries | Historial de entregas | No | No |
| POST | /tracking/subscriptions | Suscribir una guía | No | No |
| GET | /tracking/subscriptions | Listar suscripciones | No | No |
| DELETE | /tracking/subscriptions | Cancelar una suscripción | No | No |
| GET | /validate | Validar la API key y ver el consumo | No | No |
Por tema
Rastrear envíos
Una guía o hasta 50, ticket oficial y rótulo.
Cotizar y consultar DNI
Tarifas entre agencias y datos de una persona.
Crear envíos
Guías reales en Shalom Pro, una o en lote.
Operaciones de envíos
Pendientes, en tránsito, historial y comprobantes.
Autogestiones
Cambios sobre una guía ya creada.
Agencias y cobertura
Catálogo, búsqueda y agencias cercanas.
Ubicaciones
Departamentos, provincias y distritos.
Instancias
Conecta y gestiona tu sesión de Shalom Pro.
Webhooks
Avisos firmados cuando cambia una guía.