Autogestiones: gestionar una guía ya creada

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

Cuando la guía ya está creada todavía se puede gestionar: cambiar la clave de recojo, agregar un contacto autorizado, cambiar el destino, devolver la mercadería, retener o liberar la carga y pedir reparto a domicilio. Todo se apoya en el módulo de autogestión de Shalom Pro: la plataforma resuelve tu envío entre los pendientes, pide el código por SMS o email y recién con el código confirmado aplica el cambio.

POST/shipments/pickup-code

Cambiar la clave de recojo

Actualiza la clave de recojo (4 dígitos) de una guía pendiente. No requiere código de verificación.

Parámetro	Descripción
instanceId*	ID de la instancia conectada.
guia*	Número de guía (6 a 12 dígitos).
clave*	Nueva clave de 4 dígitos.

{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc",
  "guia": "77175223",
  "clave": "2008"
}

Respuesta (ejemplo)

{
  "success": true,
  "tipo": "cambio_clave",
  "guia": "77175223",
  "message": "Clave de recojo actualizada"
}

Nota: Consume 1 operación. La guía debe estar en los envíos pendientes de la cuenta.

POST/shipments/self-management

Iniciar una autogestión (envía el código)

Guarda el cambio que quieres hacer y pide a Shalom el código de verificación por SMS o email. Devuelve un challengeId de un solo uso que dura 10 minutos.

Parámetro	Descripción
instanceId*	ID de la instancia conectada.
guia*	Número de guía (6 a 12 dígitos).
tipo*	cambiar_contacto \| cambio_destino \| devolucion_mercaderia \| retencion_entrega \| liberacion_carga \| reparto_domicilio.
canal	sms (default) o email. Con email el código llega al correo indicado.
telefono*	Teléfono de 9 dígitos que recibe y valida el código.
email	Obligatorio cuando canal = email.
destinatario	Documento del destinatario. Obligatorio en cambiar_contacto; en cambio_destino y devolucion_mercaderia se toma del envío pendiente y, si Shalom no lo tiene, hay que enviarlo.
destino	ter_id o nombre de la agencia destino (tipos cambio_destino y devolucion_mercaderia).
direccion	Dirección de entrega (tipo reparto_domicilio).
dep_id	Departamento de entrega (tipo reparto_domicilio).
prov_id	Provincia de entrega (tipo reparto_domicilio).
dist_id	Distrito de entrega (tipo reparto_domicilio).
rate	Tarifa de reparto cobrada por Shalom (tipo reparto_domicilio).
label_rate	Tarifa de etiqueta (tipo reparto_domicilio).

{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc",
  "guia": "77175223",
  "tipo": "cambio_destino",
  "telefono": "987654321",
  "destino": 582
}

Respuesta (ejemplo)

{
  "success": true,
  "challengeId": "83e9cc9607eb9475e7a96f6be742e0a9",
  "expiresAt": "2026-10-04T09:02:46.299Z",
  "tipo": "cambio_destino",
  "guia": "77175223",
  "canal": "sms"
}

Nota: No consume cuota. Máximo 5 solicitudes de código por instancia cada 10 minutos.

POST/shipments/self-management/confirm

Confirmar la autogestión con el código

Valida el código contra Shalom y aplica el cambio guardado en el challenge. Máximo 5 intentos por código.

Parámetro	Descripción
instanceId*	ID de la instancia conectada.
challengeId*	Identificador devuelto al iniciar la autogestión.
clave*	Código alfanumérico de 4 a 8 caracteres recibido por SMS o email (ej. M9M7NT).

{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc",
  "challengeId": "83e9cc9607eb9475e7a96f6be742e0a9",
  "clave": "4821"
}

Respuesta (ejemplo)

{
  "success": true,
  "tipo": "cambio_destino",
  "guia": "77175223",
  "message": "Destino actualizado en Shalom"
}

Nota: Consume 1 operación: la autogestión completa cuesta lo mismo que una consulta, aunque use dos llamadas.

GET/shipments/self-management

Historial de autogestiones

Lista las autogestiones hechas en la cuenta con filtros por guía, tipo y rango de fechas.

Parámetro	Descripción
instanceId*	ID de la instancia conectada.
guia	Filtrar por número de guía.
tipo	Filtrar por tipo de autogestión.
desde	Fecha inicial (YYYY-MM-DD).
hasta	Fecha final (YYYY-MM-DD).
page	Página (default 1).
per_page	Resultados por página (default 20, máximo 50).

curl -X GET "https://api.shalom-api.lat/shipments/self-management?instanceId={instanceId}&guia={guia}&per_page=5" \
  -H "x-api-key: TU_API_KEY"

Respuesta (ejemplo)

{
  "success": true,
  "data": [
    {
      "id": 47378,
      "fecha_autogestion": "2026-10-04T08:53:17.000000Z",
      "autogestion": "cambio_clave",
      "codigo_guia": "P9JP"
    }
  ],
  "meta": { "current_page": 1, "per_page": 20, "total": 1 }
}

Nota: No consume cuota.

GET/shipments/home-delivery/ubigeo

Ubigeo para reparto a domicilio

Sin parámetros devuelve departamentos; con dep_id, provincias; con dep_id y prov_id, distritos. Se usa para armar el reparto a domicilio.

Parámetro	Descripción
instanceId*	ID de la instancia conectada.
dep_id	ID del departamento.
prov_id	ID de la provincia (requiere dep_id).

curl -X GET "https://api.shalom-api.lat/shipments/home-delivery/ubigeo?instanceId={instanceId}" \
  -H "x-api-key: TU_API_KEY"

Respuesta (ejemplo)

{
  "success": true,
  "nivel": "departamentos",
  "data": [ { "id": 15, "name": "LIMA" } ]
}

Nota: No consume cuota.

Solo aplica a guías pendientes

La autogestión existe mientras Shalom tiene el envío en su poder: la guía tiene que aparecer en los envíos pendientes de la cuenta. Si ya salió a ruta o fue entregada, la operación responde 404 con un mensaje claro.

El cambio de clave es el único que no pide código; el resto siempre se confirma con un código que envía Shalom.

Dos pasos, un solo cobro

Primero llamas a POST /shipments/self-management con lo que quieres cambiar; la plataforma valida los datos, guarda la intención y le pide a Shalom que envíe el código. Te devuelve un challengeId que dura 10 minutos.

Después llamas a POST /shipments/self-management/confirm con ese challengeId y el código. Solo ahí se aplica el cambio y solo eso consume cuota: pedir el código es gratis.

Qué puedes cambiar en cada tipo

cambiar_contacto agrega o reemplaza el contacto autorizado (documento del nuevo contacto). cambio_destino mueve la guía a otra agencia. devolucion_mercaderia la devuelve. retencion_entrega y liberacion_carga retienen o liberan la carga en agencia. reparto_domicilio agenda la entrega a una dirección con su ubigeo.

Para reparto a domicilio primero resuelve el ubigeo con GET /shipments/home-delivery/ubigeo y manda las tarifas de reparto que Shalom cotiza.

Errores de esta sección

400	Faltan campos del tipo elegido, el teléfono o email no son válidos, o el código alfanumérico es incorrecto.
404	La guía no está en los envíos pendientes, o el challenge no existe o expiró.
409	La instancia perdió la sesión de Shalom Pro: hay que reconectar.
429	Demasiadas solicitudes de código o demasiados intentos con el mismo código.

Preguntas frecuentes

¿Puedo cambiar el destino de una guía ya creada?

Sí, con el tipo cambio_destino: inicias la autogestión con la agencia destino y el teléfono, y confirmas con el código que llega por SMS o email.

¿Me avisan cuando la guía llega a la agencia de destino?

Eso es otro flujo: el estado de la guía te llega por webhook (AT_DESTINATION). Aquí de lo que se trata es de cambiar algo de una guía ya creada.

¿Por qué me pide un código si yo ya estoy autenticado?

Porque Shalom exige confirmar con el contacto del envío. El código lo genera Shalom y llega al teléfono o correo que indiques; sin él la operación no se aplica.

¿Puedo pedir el código por correo en vez de SMS?

Sí, con canal: "email" y el correo en el campo email. Con SMS usa el teléfono de 9 dígitos.

¿Qué pasa si el código se vence?

El challenge dura 10 minutos y admite 5 intentos. Si se vence, vuelve a llamar a POST /shipments/self-management para pedir uno nuevo.

Continúa con

Crear envíos en Shalom Pro Consultar el estado de una guía Recibir cambios de estado

¿Aún no tienes API key?

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

Solicitar API key