Crear envíos en Shalom Pro

Última actualización: 2026-09-21 · Base URL: https://api.shalom-api.lat

Los endpoints de envíos operan sobre una instancia (cuenta Shalom Pro conectada) y requieren su instanceId en el body. El registro individual resuelve destinatario por DNI, tipo de producto y costo automáticamente; el masivo procesa una lista completa con auto-resolución de agencias, RENIEC, tarifa y costo.

POST/account/registerShalom Pro

Registrar un envío individual

Registra un envío individual directamente en la API de Shalom Pro.

Parámetro	Descripción
instanceId*	ID de la instancia.
origen*	ter_id del terminal de origen (integer) o nombre de la agencia.
destino*	ter_id del terminal de destino (integer), string con prefijo "0" para aéreo (ej. "052"), o nombre de la agencia.
documento*	DNI del destinatario (se usa para la creación automática).
name*	Nombres del destinatario.
firstname*	Primer apellido del destinatario.
lastname*	Segundo apellido del destinatario.
phone*	Teléfono del destinatario (integer).
content	Nombre del producto (ej: SOBRE, PAQUETE XS). Automatiza tipo y costo.
cantidad	Cantidad de bultos (integer).
clave	Clave de recojo del envío.
declaracion_jurada	enum: '' \| 'Artículos de uso personal' \| 'Documentos' \| 'Ropa' \| 'Electrodomésticos' — acepción para envío aéreo.
aereo	enum: 0 \| 1 — se autodetecta si destino empieza con 0.
costo	Opcional si se envía content (se calculará automáticamente).

{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc",
  "origen": 7,
  "destino": "052",
  "content": "PAQUETE XS",
  "cantidad": 1,
  "documento": "03891771",
  "name": "RONALD EDGAR",
  "firstname": "RANGEL",
  "lastname": "ANTON",
  "phone": 949916360,
  "clave": "1234",
  "declaracion_jurada": "Ropa"
}

Respuesta (ejemplo)

{
  "...": "espejo de la respuesta de Shalom Pro con los datos de la orden creada"
}

Nota: Ejemplo oficial del Swagger. tipo_pago se fija a REMITENTE por defecto; remitente/remitente_id se obtienen del perfil.

POST/account/register-bulkShalom Pro

Registrar envíos masivos

Registra envíos masivos en Shalom a partir de una lista de shipments. Requiere estar logueado previamente.

Parámetro	Descripción
instanceId*	ID de la instancia.
shipments*	Lista de envíos (mínimo 1). Cada item requiere: recipientDoc, recipientPhone, origin, destination, content.
securityCode	Clave de seguridad de 4 dígitos.

{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc",
  "shipments": [
    {
      "recipientDoc": "72845631",
      "recipientPhone": "987654321",
      "contactDoc": "72845631",
      "contactPhone": "987654321",
      "grr": "GRR-001",
      "origin": "LIMA",
      "destination": "PIURA",
      "content": "PAQUETE XS",
      "height": "10",
      "width": "20",
      "length": "30",
      "weight": "1.5",
      "quantity": "1"
    }
  ],
  "securityCode": "5858"
}

Respuesta (ejemplo)

{
  "...": "espejo de la respuesta de Shalom Pro con el resultado por envío"
}

Nota: Ejemplo oficial del Swagger. Campos opcionales por item: contactDoc, contactPhone, grr, height, width, length, weight, quantity. content es enum de productos permitidos por Shalom (solo mayúsculas).

POST/account/pending-shipmentsShalom Pro

Lista de envíos pendientes

Obtiene el espejo (mirror) de la respuesta de Shalom para los envíos que están en estado PENDIENTE.

Parámetro	Descripción
instanceId*	ID de la instancia (en el body).

{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc"
}

Respuesta (ejemplo)

{
  "...": "espejo de la vista de envíos pendientes de Shalom Pro"
}

POST/account/get-userShalom Pro

Información del usuario autenticado

Obtiene el espejo (mirror) de la respuesta de Shalom para los datos del usuario autenticado en la instancia.

Parámetro	Descripción
instanceId*	ID de la instancia (en el body).

{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc"
}

Respuesta (ejemplo)

{
  "...": "espejo del perfil del usuario Shalom autenticado"
}

Nota: Resultado cacheado en Redis 24 h por instancia.

Antes de crear una guía

Necesitas tres cosas: una instancia de Shalom Pro con sesión activa (esas credenciales son de tu cliente final, no nuestras), el ID de la agencia de destino y los datos del destinatario.

Si la sesión de la instancia expiró, el registro falla aunque todo lo demás esté bien. Comprobar la sesión antes de un lote grande ahorra una tanda entera de errores.

El orden correcto de las llamadas

El flujo que funciona: cotizas con POST /account/quote para saber el costo, resuelves la agencia con GET /agencies/search, y recién entonces creas la guía con POST /account/register.

Crear sin cotizar es posible, pero te deja sin control del precio que le estás cobrando a tu cliente y sin poder comparar contra lo que te cuesta.

Una guía o un lote

Para pedidos individuales usa POST /account/register. Para el cierre del día con decenas de pedidos, POST /account/register-bulk acepta el lote completo en una sola llamada.

En el lote, un registro inválido no debería tumbar el resto: revisa la respuesta elemento por elemento y reintenta solo los fallidos. Reenviar el lote completo duplica las guías que sí se crearon.

Validar al destinatario antes de registrar

Consulta el DNI con GET /account/dni/{dni} antes de armar el registro. Así evitas guías rechazadas por un documento mal escrito y, si tu tienda vende con pago contra entrega, puedes comparar el nombre devuelto con el del pedido.

Qué hacer cuando algo falla

Los fallos más comunes son sesión de instancia expirada, agencia inexistente y datos del destinatario incompletos.

Guarda siempre tu propio identificador de pedido junto al número de orden que devuelve Shalom. Es la única forma de reconciliar cuando la respuesta se pierde por un timeout.

Errores de esta sección

400	Falta un campo requerido (instanceId, origen, destino, documento, name, firstname, lastname, phone) o destination no usa el prefijo 0 para aéreo.
401	La sesión de la instancia expiró y no hay credenciales guardadas para auto-login.

Preguntas frecuentes

¿Puedo crear guías solo con la API key?

No. Crear envíos requiere una instancia de Shalom Pro con sesión activa, usando las credenciales de tu cliente final.

¿Cuántos envíos puedo crear de una sola vez?

POST /account/register-bulk acepta el lote completo en una sola llamada. El límite práctico lo pone el rate limit de 1.000 peticiones por minuto.

¿Cómo calculo el costo antes de crear la guía?

Con POST /account/quote, indicando la agencia de origen y la de destino.

¿Qué hago si se cayó la sesión de Shalom Pro?

Vuelve a iniciarla con POST /instances/login y reintenta. Antes de un lote grande conviene verificar el estado con POST /instances/status.

¿Puedo validar el DNI del destinatario antes de registrar?

Sí, con GET /account/dni/{dni}. Sirve para confirmar que el documento existe y que el nombre coincide con el del pedido.

Continúa con

Conectar tu cuenta Shalom Pro Rastrear la guía creada

¿Aún no tienes API key?

Escríbenos por WhatsApp y la recibes de inmediato para probar todos estos ejemplos.

Solicitar API key