Ir al contenido
SShalom API

Operaciones de envíos

Gestiona los envíos ya creados en Shalom Pro: lista y anula pendientes, consulta el seguimiento en tránsito, filtra el historial de entregados y obtén los comprobantes con su enlace de descarga.

Estos endpoints consultan y gestionan las guías que ya existen en tu cuenta de Shalom Pro, igual que las vistas del panel. Todos requieren una instancia con la sesión iniciada (instanceId).

Las tres etapas de una guía

Pendiente: registrada y todavía no despachada. Solo en esta etapa se puede anular, y puede que todavía no aparezca en el rastreo público. En tránsito: ya salió y está en camino. Entregada: aparece en el historial y en los comprobantes.

Anular un pendiente

DELETE /account/pending-shipments busca la guía en tus pendientes y la anula con el mismo mecanismo que el panel. No se puede deshacer: confirma la guía antes de llamarlo.

Listados paginados

GET /account/tracking-list, GET /account/history y GET /account/vouchers devuelven data.items y la paginación del panel en data.meta. El historial y los comprobantes aceptan los mismos filtros. Los comprobantes traen ticket_url para descargar el ticket oficial (ver Rastrear envíos).

Lista de envíos pendientes

POST /account/pending-shipments

Requiere Shalom Pro

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

Devuelve, tal como los entrega Shalom Pro, los envíos de la cuenta que siguen pendientes (registrados y aún no despachados). Consume 1 operación.

ParámetroRequeridoDescripción
instanceIdSíInstancia de la cuenta Shalom Pro (en el body).
curl -X POST "https://api.shalom-api.lat/account/pending-shipments" \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc"
}'
Respuesta
{
  "0": {
    "id": 19763252,
    "shipping_date": "2026-11-09",
    "service_order_id_empresarial": 106620694,
    "service_order_guia_empresarial": "103149077",
    "code_service_order_empresarial": "HC7N",
    "service_order_serie_empresarial": "V207",
    "origin_station": { "ter_id": 7, "name": "AGENCIA ORIGEN", "abbreviation": "ORI" },
    "destination_station": { "ter_id": 582, "name": "AGENCIA DESTINO", "abbreviation": "DES" },
    "recipient_id": 23958
  }
}
Espejo de la vista de envíos pendientes de Shalom Pro. Ojo: es un objeto con claves "0", "1", …, no un array; recórrelo con Object.values() (JavaScript) o .values() (Python). service_order_id_empresarial es el ose_id y service_order_guia_empresarial el número de guía que acepta DELETE /account/pending-shipments. Cualquier fallo, incluida una sesión que no se pudo reconectar, responde 500 con "Ocurrió un error al listar los envíos pendientes (Mirror)."

Anular un envío pendiente

DELETE /account/pending-shipments

Requiere Shalom Pro

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

Anula un envío que todavía está pendiente en la cuenta Shalom Pro, con el mismo mecanismo que el panel. No se puede deshacer. Consume 1 operación.

ParámetroRequeridoDescripción
instanceIdSíInstancia de la cuenta Shalom Pro (en el body).
guiaNoNúmero de guía (string de 8 a 12 dígitos). Envía guia u ose_id.
ose_idNoose_id del envío pendiente (string o número). Envía guia u ose_id.
curl -X DELETE "https://api.shalom-api.lat/account/pending-shipments" \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceId": "2e656a02-7e37-4573-9d68-e76740d337dc",
  "guia": "103149077"
}'
Respuesta
{
  "success": true,
  "message": "Envío pendiente eliminado",
  "guia": "103149077",
  "ose_id": 106620694,
  "resultado": { "...": "respuesta de Shalom Pro tal cual" }
}
Primero se busca el envío en tus pendientes. Si no está ahí responde 404; si Shalom no confirma la anulación, 409 con su mensaje; si Shalom no devuelve la lista de pendientes, 502.

Seguimiento de envíos (en tránsito)

GET /account/tracking-list

Requiere Shalom Pro

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

Espejo de la vista "Seguimiento de envíos" de Shalom Pro: envíos en tránsito, paginados, con guía, código, fecha, origen y destino. Consume 1 operación.

ParámetroRequeridoDescripción
instanceIdSíInstancia de la cuenta Shalom Pro (querystring).
pageNoPágina (entero, por defecto 1).
curl -X GET "https://api.shalom-api.lat/account/tracking-list?instanceId=2e656a02-7e37-4573-9d68-e76740d337dc&page=1" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "success": true,
  "message": "Lista de envíos en tránsito.",
  "data": {
    "items": [
      {
        "id": 91230250,
        "guideNumber": "12345678",
        "code": "ABCD",
        "shippingDate": "2026-11-10 10:00:00",
        "origin": { "id": 159, "name": "Agencia Origen" },
        "destination": { "id": 497, "name": "Agencia Destino" }
      }
    ],
    "meta": { "current_page": 1, "last_page": 3, "per_page": 20, "total": 48 }
  }
}

Historial de envíos entregados

GET /account/history

Requiere Shalom Pro

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

Espejo de la vista "Historial de envíos" de Shalom Pro: envíos entregados, paginados, con filtros por fecha, documento, guía y destino. Consume 1 operación.

ParámetroRequeridoDescripción
instanceIdSíInstancia de la cuenta Shalom Pro (querystring).
pageNoPágina (entero, por defecto 1).
from_dateNoFecha inicial, YYYY-MM-DD.
to_dateNoFecha final, YYYY-MM-DD.
document_typeNoDNI, RUC o CE.
document_numberNoDocumento del remitente o del destinatario.
order_numberNoNúmero de guía.
destinationNoID o nombre de la agencia destino.
curl -X GET "https://api.shalom-api.lat/account/history?instanceId=2e656a02-7e37-4573-9d68-e76740d337dc&page=1&from_date=2026-11-01&to_date=2026-11-15" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "success": true,
  "message": "Historial de envíos entregados.",
  "data": {
    "items": [
      {
        "id": 91234250,
        "serviceOrderIdEmpresarial": 91234250,
        "guideNumber": "12345678",
        "code": "ABCD",
        "series": "V336",
        "shippingDate": "2026-11-10 10:00:00",
        "origin": { "id": 159, "name": "Agencia Origen" },
        "destination": { "id": 497, "name": "Agencia Destino" },
        "receiver": { "name": "CLIENTE DE PRUEBA", "document": "12345678" },
        "packageDelivered": true,
        "price": "12.00",
        "product": { "id": 1096, "name": "PAQUETE XXS" }
      }
    ],
    "meta": { "current_page": 1, "last_page": 44, "per_page": 20, "total": 861 }
  }
}
Son los mismos filtros que el panel de Shalom Pro y se envían tal cual.

Lista de comprobantes

GET /account/vouchers

Requiere Shalom Pro

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

Lista los envíos entregados, ya normalizados, con su ose_id y el enlace para descargar el ticket oficial con GET /track/voucher. Acepta los mismos filtros que el historial. Consume 1 operación.

ParámetroRequeridoDescripción
instanceIdSíInstancia de la cuenta Shalom Pro (querystring).
pageNoPágina (entero, por defecto 1).
from_dateNoFecha inicial, YYYY-MM-DD.
to_dateNoFecha final, YYYY-MM-DD.
document_typeNoDNI, RUC o CE.
document_numberNoDocumento del remitente o del destinatario.
order_numberNoNúmero de guía.
destinationNoID o nombre de la agencia destino.
curl -X GET "https://api.shalom-api.lat/account/vouchers?instanceId=2e656a02-7e37-4573-9d68-e76740d337dc&page=1" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "success": true,
  "message": "Historial de envíos entregados.",
  "data": {
    "items": [
      {
        "ose_id": 91234250,
        "guia": "12345678",
        "codigo": "ABCD",
        "serie": "V336",
        "fecha": "2026-11-10 10:00:00",
        "producto": "PAQUETE XXS",
        "monto": "12.00",
        "entregado": true,
        "origen": "Agencia Origen",
        "destino": "Agencia Destino",
        "destinatario": { "nombre": "CLIENTE DE PRUEBA", "documento": "12345678" },
        "ticket_path": "/track/voucher?instanceId=2e656a02-7e37-4573-9d68-e76740d337dc&ose_id=91234250",
        "ticket_url": "https://api.shalom-api.lat/track/voucher?instanceId=2e656a02-7e37-4573-9d68-e76740d337dc&ose_id=91234250"
      }
    ],
    "meta": { "current_page": 1, "last_page": 44, "per_page": 20, "total": 861 }
  }
}
ticket_url apunta al ticket oficial en PDF; agrega &format=image para JPEG. Descargarlo es otra llamada y consume su propia operación.

Errores

CódigoSignificado
400Falta instanceId, falta guia y también ose_id, o una fecha no tiene el formato YYYY-MM-DD.
403El instanceId no existe o no pertenece a tu API key.
404La guía o el ose_id no está en tus envíos pendientes (DELETE).
409Shalom no confirmó la anulación (DELETE), o la instancia perdió la sesión de Shalom Pro (listados).
500Falló el listado de pendientes o la anulación por un error no previsto.
502Shalom no respondió el listado. Reintenta en unos minutos.

Relacionado