Ir al contenido
SShalom API

Autogestiones: gestionar una guía ya creada

Gestiona una guía ya creada en Shalom por API: cambia la clave de recojo, agrega un contacto, cambia el destino, registra una devolución, retiene o libera la carga y pide reparto a domicilio, con verificación por SMS o email.

Una guía ya creada todavía se puede gestionar: cambiar la clave de recojo, cambiar el contacto, cambiar el destino, devolver la mercadería, retener o liberar la carga y pedir reparto a domicilio. Todo usa el módulo de autogestión de Shalom Pro y requiere una instancia con la sesión iniciada.

Con código de seguridad, en cualquier estado

Si envías el código de seguridad de la guía (campo codigo), la autogestión funciona con el envío en ruta, en destino o entregado: la API verifica la orden con el mismo módulo del panel y es Shalom quien decide qué se permite según el estado. Por ejemplo, cambiar el destino de una guía entregada se rechaza con el mensaje de Shalom (409).

Sin el código, la operación solo aplica a los envíos pendientes de la cuenta. Si la guía ya salió, responde 404 y te pide el código.

Dos pasos, un solo cobro

Salvo el cambio de clave, toda autogestión se confirma con un código que envía Shalom. Primero llamas a POST /shipments/self-management con lo que quieres cambiar: la API valida los datos, guarda el cambio y pide 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 recibido. Solo ahí se aplica el cambio, y solo ese paso consume una operación.

Qué cambia cada tipo

cambiar_contacto cambia el contacto autorizado (documento en destinatario). cambio_destino lleva la guía a otra agencia. devolucion_mercaderia la devuelve a la agencia que indiques. retencion_entrega retiene la entrega y liberacion_carga libera una carga retenida. reparto_domicilio pide la entrega en una dirección: primero resuelve el ubigeo con GET /shipments/home-delivery/ubigeo y envía las tarifas de reparto y de etiqueta que cobra Shalom.

Cambiar la clave de recojo

POST /shipments/pickup-code

Requiere Shalom Pro

Este endpoint usa una instancia con la sesión de Shalom Pro iniciada. Ver Instancias.

Cambia la clave de recojo (4 dígitos) de una guía en un solo paso, sin código de verificación. Consume 1 operación.

ParámetroRequeridoDescripción
instanceIdSíInstancia de la cuenta Shalom Pro.
guiaSíNúmero de guía (6 a 12 dígitos).
codigoNoCódigo de seguridad de la guía (4 a 8 letras o números). Recomendado: con él funciona con la guía en ruta, en destino o entregada; sin él, solo con envíos pendientes.
claveSíNueva clave de 4 dígitos.
curl -X POST "https://api.shalom-api.lat/shipments/pickup-code" \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc",
  "guia": "77175223",
  "codigo": "9MPJ",
  "clave": "2008"
}'
Respuesta
{
  "success": true,
  "tipo": "cambio_clave",
  "guia": "77175223",
  "message": "Clave de recojo actualizada",
  "resultado": { "...": "respuesta de Shalom Pro tal cual" }
}
Shalom valida los datos del envío y, si rechaza el cambio por una regla propia (por ejemplo, si tu cuenta no es la remitente), la API responde 409 o 400 con su mensaje.

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

POST /shipments/self-management

Requiere Shalom Pro

Este endpoint usa una instancia con la sesión de Shalom Pro iniciada. Ver Instancias.

Paso 1: valida los datos, guarda el cambio que quieres hacer y pide a Shalom que envíe el código de verificación por SMS o email. Devuelve un challengeId de un solo uso que dura 10 minutos. No consume cuota.

ParámetroRequeridoDescripción
instanceIdSíInstancia de la cuenta Shalom Pro.
guiaSíNúmero de guía (6 a 12 dígitos).
tipoSícambiar_contacto, cambio_destino, devolucion_mercaderia, retencion_entrega, liberacion_carga o reparto_domicilio.
telefonoSíCelular de 9 dígitos que empieza con 9. Recibe el código por SMS y Shalom lo usa para validarlo.
codigoNoCódigo de seguridad de la guía (4 a 8 letras o números). Recomendado: con él la guía se puede operar en ruta, en destino o entregada; sin él, solo si está en tus envíos pendientes.
canalNosms (por defecto) o email.
emailNoCorreo que recibe el código. Obligatorio con canal = email.
destinatarioNoDocumento del destinatario (7 a 12 dígitos). Obligatorio en cambiar_contacto. En cambio_destino y devolucion_mercaderia se toma del envío si no lo envías; si no se encuentra, responde 400.
destinoNoter_id o nombre de la agencia destino. Obligatorio en cambio_destino y devolucion_mercaderia.
direccionNoDirección de entrega (mínimo 5 caracteres). Obligatoria en reparto_domicilio.
dep_idNoDepartamento de entrega (entero). Obligatorio en reparto_domicilio; sale de GET /shipments/home-delivery/ubigeo.
prov_idNoProvincia de entrega (entero). Obligatoria en reparto_domicilio.
dist_idNoDistrito de entrega (entero). Obligatorio en reparto_domicilio.
rateNoTarifa de reparto que cobra Shalom (número, 0 o más). Obligatoria en reparto_domicilio.
label_rateNoTarifa de etiqueta (número, 0 o más). Obligatoria en reparto_domicilio.
curl -X POST "https://api.shalom-api.lat/shipments/self-management" \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc",
  "guia": "77175223",
  "codigo": "9MPJ",
  "tipo": "cambio_destino",
  "telefono": "987654321",
  "destino": 582
}'
Respuesta
{
  "success": true,
  "challengeId": "83e9cc9607eb9475e7a96f6be742e0a9",
  "expiresAt": "2026-11-11T09:02:46.299Z",
  "tipo": "cambio_destino",
  "guia": "77175223",
  "canal": "sms",
  "mensaje": "Te enviamos un código por SMS. Confírmalo en /shipments/self-management/confirm."
}
Máximo 5 solicitudes de código por instancia cada 10 minutos; la sexta responde 429.

Confirmar la autogestión con el código

POST /shipments/self-management/confirm

Requiere Shalom Pro

Este endpoint usa una instancia con la sesión de Shalom Pro iniciada. Ver Instancias.

Paso 2: valida el código contra Shalom y aplica el cambio guardado en el paso 1. Máximo 5 intentos por código. Consume 1 operación.

ParámetroRequeridoDescripción
instanceIdSíLa misma instancia del paso 1.
challengeIdSíIdentificador que devolvió el paso 1.
claveSíCódigo de 4 a 8 letras o números recibido por SMS o email (ej. M9M7NT). Se ignoran espacios y guiones.
curl -X POST "https://api.shalom-api.lat/shipments/self-management/confirm" \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc",
  "challengeId": "83e9cc9607eb9475e7a96f6be742e0a9",
  "clave": "M9M7NT"
}'
Respuesta
{
  "success": true,
  "tipo": "cambio_destino",
  "guia": "77175223",
  "message": "Destino actualizado en Shalom",
  "resultado": { "...": "respuesta de Shalom Pro tal cual" }
}
Un código incorrecto responde 400 y suma un intento; al sexto intento el challenge se borra (429) y hay que pedir otro código. Si Shalom rechaza el cambio, responde 400 con su mensaje.

Historial de autogestiones

GET /shipments/self-management

Requiere Shalom Pro

Este endpoint usa una instancia con la sesión de Shalom Pro iniciada. Ver Instancias.

Lista las autogestiones hechas en la cuenta, con filtros por guía, tipo y fechas. No consume cuota.

ParámetroRequeridoDescripción
instanceIdSíInstancia de la cuenta Shalom Pro.
guiaNoFiltra por número de guía.
tipoNoFiltra por uno de los tipos de autogestión.
desdeNoFecha inicial (YYYY-MM-DD).
hastaNoFecha final (YYYY-MM-DD).
pageNoPágina (entero, por defecto 1).
per_pageNoResultados por página (1 a 50, por defecto 20).
curl -X GET "https://api.shalom-api.lat/shipments/self-management?instanceId=2e656a02-7e37-4573-9d68-e76740d337dc&per_page=5" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "success": true,
  "data": [
    {
      "id": 47378,
      "fecha_autogestion": "2026-11-10T08:53:17.000000Z",
      "autogestion": "cambio_clave",
      "codigo_guia": "P9JP"
    }
  ],
  "meta": { "current_page": 1, "per_page": 20, "total": 1 }
}

Ubigeo para reparto a domicilio

GET /shipments/home-delivery/ubigeo

Requiere Shalom Pro

Este endpoint usa una instancia con la sesión de Shalom Pro iniciada. Ver Instancias.

Sin dep_id devuelve departamentos; con dep_id, sus provincias; con dep_id y prov_id, sus distritos. Son los IDs que pide reparto_domicilio. No consume cuota.

ParámetroRequeridoDescripción
instanceIdSíInstancia de la cuenta Shalom Pro.
dep_idNoID del departamento (entero).
prov_idNoID de la provincia (entero). Requiere dep_id.
curl -X GET "https://api.shalom-api.lat/shipments/home-delivery/ubigeo?instanceId=2e656a02-7e37-4573-9d68-e76740d337dc" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "success": true,
  "data": [ { "id": 15, "name": "LIMA" } ],
  "nivel": "departamentos"
}

Errores

CódigoSignificado
400Falta un campo del tipo elegido o tiene un formato inválido (guía, teléfono, email, documento, código), el código de verificación es incorrecto, o Shalom rechazó el cambio con su mensaje.
403El instanceId no existe o no pertenece a tu API key.
404No se pudo ubicar la guía (envía codigo si ya salió de pendientes), o el challenge no existe, expiró o es de otra instancia.
409Shalom no permite esa autogestión para la guía en su estado actual, o la instancia perdió la sesión de Shalom Pro.
429Más de 5 solicitudes de código en 10 minutos, o más de 5 intentos con el mismo código.
502Shalom no respondió o rechazó el envío del código. Reintenta.
503El servicio de autogestión no está disponible en este momento.

Preguntas frecuentes

Relacionado