Crear envíos en Shalom Pro

Última actualización: 2026-11-04 · 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 (8 dígitos) o carnet de extranjería (CE) del destinatario. Si no está registrado en tu cuenta Shalom Pro, la API lo crea con name, firstname, lastname y phone.
name*	Nombres del destinatario.
firstname*	Primer apellido del destinatario.
lastname*	Segundo apellido del destinatario.
phone*	Teléfono del destinatario (integer).
content	Nombre del producto (SOBRE, PAQUETE XXS/XS/S/M/L u OTRA MEDIDA). Automatiza tipo y costo; para OTRA MEDIDA envía además peso, alto, largo y ancho.
cantidad	Cantidad de bultos (integer).
ancho	Ancho en metros (máx. 1.5). Obligatorio con content "OTRA MEDIDA", junto con alto, largo y peso.
alto	Alto en metros (máx. 1.5). Obligatorio con content "OTRA MEDIDA".
largo	Largo en metros (máx. 1.5). Obligatorio con content "OTRA MEDIDA".
peso	Peso en kg (máx. 500). Obligatorio con content "OTRA MEDIDA".
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).
deseo_garantia	boolean — activa la garantía (seguro de mercancía).
garantia_monto	Valor declarado a asegurar (máx. 40,000). Obligatorio si deseo_garantia = true; el costo de la garantía se calcula automáticamente (0.5% o S/ 5 fijo según producto).
cobro_seguro	boolean — activa el cobro seguro (cobro contra entrega). Requiere la autorización de cobranza aprobada en Shalom Pro.
monto_cobro_seguro	Monto a cobrar al destinatario. Obligatorio si cobro_seguro = true.

{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc",
  "origen": 7,
  "destino": "052",
  "content": "PAQUETE XS",
  "cantidad": 1,
  "documento": "12345678",
  "name": "JUAN CARLOS",
  "firstname": "PEREZ",
  "lastname": "GOMEZ",
  "phone": 987654321,
  "clave": "2580",
  "declaracion_jurada": "Ropa",
  "deseo_garantia": true,
  "garantia_monto": 800,
  "cobro_seguro": true,
  "monto_cobro_seguro": 150
}

Respuesta (ejemplo)

{
  "success": true,
  "message": "Orden de envío creada con exito!",
  "data": {
    "guia": 103149077,
    "codigo": "HC7N",
    "serie": "V207",
    "ose_id": 106620694,
    "precio": 8
  }
}

Nota: guia y codigo son el número de orden y el código de seguridad para POST /track; ose_id sirve para el rótulo, el ticket y para anular. La clave de recojo es de 4 dígitos y no puede ser consecutiva (1234, 4321): Shalom la rechaza y la API responde 400 con { success: false, message }. El destinatario puede identificarse con DNI o carnet de extranjería. tipo_pago se fija a REMITENTE por defecto; remitente/remitente_id se obtienen del perfil. Garantía: garantia_monto es el valor declarado (máx. 40,000) y el costo (0.5%, mínimo S/ 5 en productos fijos) lo calcula la API. Cobro seguro: monto_cobro_seguro es lo que se cobra al destinatario. Para content "OTRA MEDIDA" (producto id 4) envía peso, alto, largo y ancho (máx. 1.5 m por lado y 500 kg); el precio se calcula por volumen.

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 (DNI o carnet de extranjería), recipientPhone, origin, destination, content.
securityCode	Clave de recojo de 4 dígitos. No puede ser consecutiva (1234, 4321) responde 400.

{
  "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": "0.10",
      "width": "0.20",
      "length": "0.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, deseo_garantia + garantia_monto y cobro_seguro + monto_cobro_seguro. content es enum de productos permitidos por Shalom (solo mayúsculas); con "OTRA MEDIDA" el ítem debe traer height, width y length en metros (máx. 1.5 por lado) y weight en kg (máx. 500).

GET/account/products

Lista de productos

Catálogo de productos que acepta el campo content al registrar un envío, con el productId interno de Shalom y las medidas de cada caja. No consume cuota ni requiere instanceId.

curl -X GET "https://api.shalom-api.lat/account/products" \
  -H "x-api-key: TU_API_KEY"

Respuesta (ejemplo)

{
  "success": true,
  "total": 7,
  "data": [
    { "content": "SOBRE", "productId": 3, "name": "Sobre", "detail": "Documentos simples en sobre manila / Tamaño A4" },
    { "content": "PAQUETE XS", "productId": 1090, "name": "Caja Paquete XS", "detail": "15 x 20 x 12" },
    { "content": "OTRA MEDIDA", "productId": 4, "name": "Otra Medida", "detail": "Medidas personalizadas (ancho x alto x largo)" }
  ],
  "allowedContents": ["SOBRE", "PAQUETE XXS", "PAQUETE XS", "PAQUETE S", "PAQUETE M", "PAQUETE L", "CAJA", "BULTO", "OTRA MEDIDA"]
}

Nota: Usa `content` tal cual en /account/register o /account/register-bulk; la API resuelve el tipo de producto y el costo. Para "OTRA MEDIDA" (productId 4) hay que enviar ancho, alto, largo y peso (máx. 1.5 m por lado y 500 kg) y el precio se calcula por volumen. GET /account/products no consume cuota.

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)

{
  "id": 1252462,
  "name": "Juan Carlos Perez",
  "email": "[email protected]",
  "status": 1,
  "has_selfmanagement_history": true,
  "sender": {
    "type": "person",
    "id": 2692645,
    "name": "JUAN CARLOS PEREZ GOMEZ",
    "document": "12345678",
    "document_type": "dni",
    "email": null,
    "phone": 987654321
  }
}

Nota: Resultado cacheado en Redis 24 h por instancia.

POST/account/person/searchShalom Pro

Resolver documento a persona registrada (DNI/RUC/CE)

Busca en las personas y empresas registradas en la cuenta Shalom Pro y devuelve nombre, apellidos, teléfono, correo y dirección para autocompletar formularios. Si no se envía type_document se infiere por longitud: 8 = DNI, 11 = RUC, otro = CE.

Parámetro	Descripción
instanceId*	ID de la instancia (en el body).
document*	DNI (8 dígitos), RUC (11) o CE (6 a 12 dígitos), solo números.
type_document	DNI \| RUC \| CE (opcional; se infiere por la longitud del documento).

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

Respuesta (ejemplo)

{
  "success": true,
  "message": "Entidad encontrada",
  "data": {
    "type_document": "DNI",
    "document": "12345678",
    "name": "JUAN",
    "lastname": "PEREZ",
    "surname": "GOMEZ",
    "full_name": "JUAN PEREZ GOMEZ",
    "phone": "999999999",
    "email": "[email protected]",
    "address": "",
    "id": 123456
  }
}

Nota: Devuelve las personas/empresas ya registradas en esa cuenta Shalom Pro (no consulta RENIEC). 404 si no existe; 409 si la instancia perdió la sesión. Úsalo antes del submit para pre-cargar el formulario.

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), destination no usa el prefijo 0 para aéreo, o Shalom rechazó el registro (por ejemplo, clave de recojo consecutiva como 1234); el cuerpo trae { success: false, message }.
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 60 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

Pendientes, historial y comprobantes 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