Documentación.

API REST para consultar tracking, agencias y ubicaciones de shalom.com.pe, y crear pedidos en pro.shalom.pe.

Auth

X-API-Key

Rate limit

60 / min

Formato

JSON

Base URL: https://api.shalom-api-peru.com

Autenticación

Todas las rutas requieren el header X-API-Key con tu key.

X-API-Key: tu-api-key

Solicita tu API key por WhatsApp:

925 875 418

Errores

Estructura consistente en todos los errores:

{
  "error": {
    "code": "not_found",
    "message": "orden no existe",
    "request_id": "01JXZ..."
  }
}

HTTP	code	Descripción
400	bad_request	Parámetros faltantes o inválidos
401	unauthorized	API key invalida o ausente
401	shalom_auth_failed	Credenciales de Shalom Pro rechazadas (solo /v1/orders)
403	forbidden	Sin permisos
404	not_found	Recurso no existe
409	conflict	Conflicto de estado (ej. persona duplicada en /v1/orders)
422	upstream_rejected	Shalom Pro rechazó la solicitud por una regla de negocio
429	rate_limited	Rate limit excedido
502	upstream_unavailable	Shalom Pro no respondió o devolvió algo inesperado
502	shalom_unavailable	Shalom Pro no disponible (solo /v1/orders)
504	upstream_timeout	Shalom Pro tardó más de 30s en responder
500	internal	Error interno

Rate Limits

Limite por defecto: 60 requests por minuto por API key.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1713200060

GET/v1/tracking

Busca una orden y retorna orden + estados en paralelo.

Query params (al menos 1 requerido)

Param	Tipo	Descripción
numero	string	El identificador del envío que aparece impreso en el comprobante físico. 8 a 10 dígitos (ej. `"12345678"`). Mismo que `guia` en la respuesta de `POST /v1/orders`.
codigo	string	Identificador alternativo, alfanumérico de 4 caracteres (ej. `"CJTW"`). Lo asigna Shalom.
ose_id	string	ID que asigna el sistema OSE (Operador de Servicios Electrónicos / SUNAT). Lo devuelve esta misma respuesta en `order.ose_id` y se usa como path param en los endpoints siguientes (`/events`, `/voucher`, `/grt`). Si ya tienes `numero` o `codigo`, no necesitas este.

Necesitas al menos uno de los tres params. El caso más común es mandar numero + codigo juntos (ambos vienen impresos en el comprobante físico). El ose_id se usa cuando ya lo tienes de la respuesta de POST /v1/orders.

Request — por numero + codigo

curl -H "X-API-Key: mi-key" \
  "https://api.shalom-api-peru.com/v1/tracking?numero=82100156&codigo=W79H"

Request — por ose_id

curl -H "X-API-Key: mi-key" \
  "https://api.shalom-api-peru.com/v1/tracking?ose_id=584210"

200 OK

{
  "order": {
    "ose_id": 584210,
    "numero_orden": "0123456789",
    "entregado": true,
    "origen": { "nombre": "LIMA" },
    "destino": { "nombre": "AREQUIPA" }
  },
  "status": {
    "origen":    { "fecha": "15/04/2026", "hora": "09:30" },
    "entregado": { "fecha": "16/04/2026", "hora": "11:40" }
  }
}

GET/v1/tracking/{ose_id}/events

Hitos del envio: origen, transito, demora, destino, entregado, reparto.

Path	Tipo	Descripción
ose_id	string	ID del sistema OSE (SUNAT) — el campo `order.ose_id` de la respuesta de `GET /v1/tracking`. Es el handle público para acceder a eventos, comprobante y GRT.

200 OK

{
  "origen":    { "fecha": "15/04/2026", "hora": "09:30", "descripcion": "Recibido en agencia de origen" },
  "transito":  { "fecha": "15/04/2026", "hora": "14:20", "descripcion": "En viaje" },
  "demora":    null,
  "destino":   { "fecha": "16/04/2026", "hora": "08:15", "descripcion": "Llegó a destino" },
  "entregado": { "fecha": "16/04/2026", "hora": "11:40", "descripcion": "Entregado al destinatario" },
  "reparto":   null
}

GET/v1/tracking/{ose_id}/voucher

Comprobante de la orden. Retorna 404 si no tiene comprobante emitido.

GET/v1/tracking/{ose_id}/grt?cap_id={cap_id}

Enlace a la Guía de Remisión del Transportista. Un envío puede pasar por varios cargueros (transportistas) y cada uno emite su propio GRT — por eso el cap_id es obligatorio.

Param	En	Descripción
ose_id	path	ID del sistema OSE (SUNAT) — el campo `order.ose_id` de la respuesta de `GET /v1/tracking`.
cap_id	query	ID del carguero (transportista). Los ids están en `status.transito.cargueros[]` de `GET /v1/tracking`. (requerido)

Request

curl -H "X-API-Key: tu-api-key" \
  "https://api.shalom-api-peru.com/v1/tracking/584210/grt?cap_id=898441"

200 OK

{
  "enlace": "https://..."
}

GET/v1/agencies

Lista paginada de agencias.

Param	Default	Descripción
page	1	Página
per_page	100	Ítems por página (máx 500)

200 OK

{
  "page": 1,
  "per_page": 100,
  "items": [
    {
      "id": 1,
      "nombre": "LIMA CENTRO",
      "departamento": "LIMA",
      "aereo": true,
      "latitud": -12.046,
      "longitud": -77.030
    }
  ]
}

GET/v1/agencies/search

Busca por texto y/o filtros de ubicacion.

Param	Tipo	Descripción
q	string	Texto libre
departamento	string	Filtrar por depto
provincia	string	Filtrar por provincia
aereo	bool	Servicio aereo

GET/v1/agencies/{id}

Detalle completo de una agencia por ID numérico.

GET/v1/locations/departments

Todos los departamentos del Perú.

{
  "items": [
    { "id": 1, "name": "AMAZONAS", "ubi_id": 101 }
  ]
}

GET/v1/locations/departments/{depId}/provinces

Provincias de un departamento.

Path	Descripción
depId	ID del departamento

GET/v1/locations/departments/{depId}/provinces/{provId}/districts

Distritos de una provincia.

Path	Descripción
depId	ID del departamento
provId	ID de la provincia

Crear pedido en Shalom Pro

Crea una guía de envío real en la cuenta de Shalom Pro del cliente y devuelve los identificadores para tracking, descarga de PDF y operaciones posteriores. La resolución de remitente y destinatario, la validación del servicio de cobranza y la cotización se hacen automáticamente en una sola llamada.

Auth a dos niveles. Además del header X-API-Key, estos endpoints exigen las credenciales del cliente final contra Shalom Pro. Hay dos formas — elige una.

Importante: cada llamada exitosa a POST /v1/orders crea una preguía real en la cuenta de Shalom Pro. La orden queda registrada y visible en el panel de pro.shalom.pe. Si fue creada por error, puedes borrarla con DELETE /v1/orders/{id} mientras no haya sido despachada.

Auth Shalom — opción A (recomendada): token efímero

Haces POST /v1/shalom/sessions una vez con email + password en el body, recibes un session_token con TTL de 2 horas, y las llamadas siguientes (productos, crear/listar/borrar orden) usan header X-Shalom-Session: ssk_.... El password viaja una sola vez. Recomendado para integraciones que loguean requests.

Auth Shalom — opción B: email/password directo

Mandás X-Shalom-Email + X-Shalom-Password en cada request. Más simple — sin paso previo — pero el password viaja en cada llamada. Ideal para scripts cortos o pruebas rápidas.

Headers

Header	Cuándo	Descripción
X-API-Key	siempre	Tu API key de Shalom API Perú.
X-Shalom-Session	opción A	Token `ssk_...` emitido por `POST /v1/shalom/sessions`. Si está, tiene precedencia sobre email/password.
X-Shalom-Email	opción B	Email de la cuenta del cliente en pro.shalom.pe.
X-Shalom-Password	opción B	Password de esa cuenta. NO se loguea ni persiste en nuestro servidor.
Content-Type	POST/PUT	`application/json`

Latencia y cache

Latencia típica: 700ms – 1.5s en el primer pedido de cada cuenta, ~700ms en los siguientes (la sesión se reutiliza durante 90 minutos sin re-autenticación).

POST/v1/shalom/sessions

Valida las credenciales contra pro.shalom.pe y emite un token efímero (formato ssk_<64-hex>) con TTL de 2 horas.

El password viaja en el body, no en headers. Headers HTTP suelen aparecer en logs por defecto (proxies, error trackers, observabilidad); el body solo si configuras logging de bodies. El password no se persiste en ningún lado — se usa solo para emitir el token y se descarta.

Request

curl -X POST https://api.shalom-api-peru.com/v1/shalom/sessions \
  -H "X-API-Key: tu-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "cliente@empresa.com",
    "password": "tu-password-de-shalom-pro"
  }'

200 OK

{
  "session_token": "ssk_a1b2c3d4e5f6...",
  "expires_at": "2026-05-08T18:23:01Z"
}

Body

Campo	Tipo	Descripción
email	string	Email de la cuenta en pro.shalom.pe.
password	string	Password de esa cuenta.

Cuándo el token expira

TTL del token: 2 horas desde la emisión. Si una request usa un token vencido, devuelve 401 con código shalom_auth_failed — pide uno nuevo. Los tokens se mantienen en memoria, así que los reinicios del servicio los invalidan.

Errores

HTTP	code	Cuándo se da
400	bad_request	Body inválido o `email`/`password` vacíos.
401	shalom_auth_failed	Credenciales rechazadas por Shalom Pro.
502	shalom_unavailable	Pro Web caído o respuesta inesperada.

DELETE/v1/shalom/sessions

Revoca un token antes de que expire. Idempotente: si el token ya estaba revocado o nunca existió, igual responde 200. Útil para forzar logout cuando el cliente cambia de cuenta o detecta actividad sospechosa.

Request

curl -X DELETE https://api.shalom-api-peru.com/v1/shalom/sessions \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Session: ssk_a1b2c3d4e5f6..."

200 OK

{ "revoked": true }

El token a revocar va en el header X-Shalom-Session, no en el path ni en el body. Si el header falta, devuelve 400.

GET/v1/products

Lista los productos disponibles en la cuenta de Shalom Pro del cliente: Sobre, Caja Paquete XXS/XS/S/M/L y Otra Medida. Devuelve el id que usas en el body de POST /v1/orders y las dimensiones default de cada uno.

Mismo auth Shalom que el resto. Requiere X-API-Key + X-Shalom-Session (recomendado) o X-Shalom-Email + X-Shalom-Password. La sesión se cachea por 90 min y se comparte entre todos los endpoints Shalom: si ya creaste una orden con esas credenciales, este call no paga login.

Request

curl https://api.shalom-api-peru.com/v1/products \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro"

200 OK

{
  "products": [
    {
      "id": 3,
      "title": "Sobre",
      "img": "https://pro.shalom.pe/img/products/sobre.png",
      "content": "Hasta 0.5 kg",
      "sub_content": "Documentos y similares",
      "measurements": {
        "weight": 0.5,
        "width": 0.3,
        "height": 0.02,
        "length": 0.4
      }
    },
    {
      "id": 1098,
      "title": "Otra Medida",
      "img": "https://pro.shalom.pe/img/products/custom.png",
      "content": "Definí dimensiones",
      "sub_content": "Para bultos fuera de catálogo",
      "measurements": { "weight": 0, "width": 0, "height": 0, "length": 0 }
    }
  ]
}

Campos del producto

Campo	Tipo	Descripción
id	int	ID del producto. Pasalo en `product_id` al crear la orden.
title	string	Nombre legible: `"Sobre"`, `"Caja Paquete XS"`, `"Otra Medida"`, etc.
content	string	Descripción corta del límite de peso.
sub_content	string	Texto auxiliar: ejemplos de uso.
img	string	URL del thumbnail para mostrar en tu UI.
measurements	object	Medidas default `{ weight, width, height, length }` en kg/m. Para Otra Medida vienen en cero — defÃnelas tú en el body de la orden.

 Otra Medida — bulto fuera de catálogo
 
Si tu envío no entra en los tamaños estándar, usa el producto cuyo title sea "Otra Medida" y manda el campo opcional dimensions en el body de POST /v1/orders con { weight_kg, height_m, length_m, width_m }. Para los demás productos puedes omitirlo y se usan las medidas default.

GET/v1/persons/search?document={document}&type={type}

Resuelve un documento (DNI/RUC/CE) a una persona registrada en pro.shalom.pe. Útil para autocomplete en formularios — el usuario tipea su DNI y tú pre-cargas nombre, apellidos y teléfono antes del submit.

No es obligatorio antes de crear una orden. POST /v1/orders ya resuelve la persona automáticamente cuando le pasas el documento. Este endpoint sirve cuando quieres mostrar los datos al usuario antes del submit, o conseguir el id para reusarlo en envíos siguientes.

Request

curl "https://api.shalom-api-peru.com/v1/persons/search?document=70123456&type=DNI" \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro"

200 OK

{
  "id": 1234567,
  "document_type": "DNI",
  "document": "70123456",
  "name": "JUANA",
  "last_name": "RAMOS",
  "sur_name": "LOPEZ",
  "full_name": "JUANA RAMOS LOPEZ",
  "phone": 999111222,
  "email": null,
  "address": null
}

Query params

Param	Tipo	Descripción
document	string	Documento a buscar (8 dígitos para DNI, 11 para RUC, alfanumérico ≥4 para CE) (requerido)
type	string	`"DNI"`, `"RUC"` o `"CE"` (case-insensitive) (requerido)

Errores específicos

HTTP	code	Cuándo se da
400	bad_request	Falta `document` o `type`, type fuera de DNI/RUC/CE, o longitud inválida (DNI≠8, RUC≠11, etc.)
404	not_found	El DNI/RUC/CE no figura en Shalom Pro.

404 — persona no encontrada

{
  "error": {
    "code": "not_found",
    "message": "persona no registrada en Shalom Pro",
    "request_id": "01KS..."
  }
}

POST/v1/tariff/calculate

Calcula el precio de un envío entre dos terminales sin comprometer la orden. Devuelve el precio para cada tipo de producto del catálogo (sobre, cajas XXS/XS/S/M/L y otra medida) para que puedas mostrar la cotización antes del checkout.

Request

curl -X POST https://api.shalom-api-peru.com/v1/tariff/calculate \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_terminal_id": 66,
    "destiny_terminal_id": 7,
    "dimensions": {
      "weight_kg": 1.0,
      "height_m": 0.1,
      "length_m": 0.2,
      "width_m": 0.15
    }
  }'

200 OK

{
  "currency": "PEN",
  "breakdown": {
    "sobre": 8.00,
    "caja_paquete_xxs": 8.00,
    "caja_paquete_xs": 10.00,
    "caja_paquete_s": 12.00,
    "caja_paquete_m": 15.00,
    "caja_paquete_l": 20.00,
    "otra_medida": 25.00
  }
}

Body

Campo	Tipo	Descripción
origin_terminal_id	integer	ID del terminal de origen (lo obtienes de `/v1/agencies`) (requerido)
destiny_terminal_id	integer	ID del terminal de destino (requerido)
dimensions	object	Peso y medidas del paquete (`weight_kg`, `height_m`, `length_m`, `width_m`). Afectan SOLO el precio de `otra_medida`. Si no se pasan, se usan defaults mínimos.
product_id	integer	Si lo pasas, la respuesta incluye un campo `product` con el precio puntual para mostrar al usuario. Si el id no existe en el catálogo, el campo se omite (la respuesta sigue siendo 200 con el breakdown).

Con `product_id` — precio puntual

Si ya sabes qué producto va a comprar el usuario, manda product_id y te ahorras el mapeo manual del breakdown:

Request

curl -X POST https://api.shalom-api-peru.com/v1/tariff/calculate \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_terminal_id": 66,
    "destiny_terminal_id": 7,
    "product_id": 3
  }'

200 OK

{
  "currency": "PEN",
  "breakdown": {
    "sobre": 8.00,
    "caja_paquete_xxs": 8.00,
    "caja_paquete_xs": 10.00,
    "caja_paquete_s": 12.00,
    "caja_paquete_m": 15.00,
    "caja_paquete_l": 20.00,
    "otra_medida": 25.00
  },
  "product": {
    "id": 3,
    "title": "Sobre",
    "price": 8.00
  }
}

Errores específicos

HTTP	code	Cuándo se da
400	bad_request	Body inválido o faltan `origin_terminal_id` / `destiny_terminal_id`
401	shalom_auth_failed	Credenciales Shalom Pro rechazadas
502	shalom_unavailable	Pro Web caído o respuesta inesperada

POST/v1/orders

Crea una guía de envío. Devuelve guia, serie y codigo — los identificadores con los que después puedes trackear o borrar la orden.

Request

curl -X POST https://api.shalom-api-peru.com/v1/orders \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_terminal_id": 404,
    "destiny_terminal_id": 7,
    "product_id": 3,
    "quantity": 1,
    "payer": "sender",
    "sender": {
      "id": 2833026
    },
    "receiver": {
      "document_type": "DNI",
      "document": "87654321",
      "name": "MARIA",
      "last_name": "GOMEZ",
      "sur_name": "TORRES",
      "phone": 998765432
    },
    "pickup_code": "2415"
  }'

200 OK

{
  "guia": "80574902",
  "serie": "v872",
  "codigo": "CJTW"
}

Qué es cada campo

guia — Identificador con el que se rastrea el envío públicamente. 8 a 10 dígitos (ej. "12345678"). Es lo que aparece impreso en el comprobante físico que el cliente final recibe, y lo mismo que pasas como numero= en GET /v1/tracking.
serie — Prefijo del talonario del que sale la guía (ej. "v872", "s001"). No interviene en tracking ni en ninguna llamada de esta API — es informativo, sirve si tienes que reconciliar contra papeles físicos.
codigo — Identificador alternativo con el que también puedes rastrear el envío. Alfanumérico, 4 caracteres (ej. "CJTW"). Lo asigna Shalom al crear la orden — tú no lo eliges. Lo pasas como codigo= en GET /v1/tracking.

¿Y la clave de retiro? La clave de 4 dígitos que el destinatario presenta en agencia es la que tú elegiste en pickup_code del body al crear. Este endpoint no la devuelve — tú ya la sabes porque la elegiste — pero la ves reflejada en GET /v1/orders.

GET/v1/orders

Lista todas las órdenes de la cuenta del cliente — preguías + envíos despachados — en una sola respuesta. Útil para construir un dashboard, exportar historial o reconciliar con tu sistema interno.

Sin paginación ni filtros server-side. Este endpoint devuelve la lista completa de la cuenta en una sola respuesta. Si necesitas filtrar o paginar, hazlo en el cliente sobre el array.

Cuidado con cuentas grandes. Cada orden ocupa ~3 KB en la respuesta limpia. Una cuenta con 5.000 envíos = ~15 MB en una sola request. Cachea del lado del cliente cuando puedas (TTL de pocos minutos suele ser suficiente).

Request

curl https://api.shalom-api-peru.com/v1/orders \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro"

200 OK

{
  "orders": [
    {
      "id": 87654321,
      "internal_id": 4567890,
      "guia": "12345678",
      "serie": "s001",
      "codigo": "ABCD",
      "pickup_code": "2415",
      "created_at": "2026-05-08 10:11:12",
      "updated_at": "2026-05-08 10:11:13",
      "shipping_date": "2026-05-08",
      "status": 1,
      "payer": "receiver",
      "aereo": false,
      "delivered": false,
      "paid": false,
      "origin": {
        "ter_id": 404,
        "name": "SALAS ICA",
        "address": "SUB LOTE 01 ZONA PANAMERICANA SUR KM. 293.350...",
        "abbreviation": "sls",
        "phone": "(01) 500 7878",
        "ubigeo": "ICA - ICA - SALAS"
      },
      "destination": {
        "ter_id": 7,
        "name": "AV PARRA 379 CO",
        "address": "AV. PARRA 379",
        "abbreviation": "AQP",
        "phone": "0",
        "ubigeo": "AREQUIPA - AREQUIPA - AREQUIPA"
      },
      "sender": {
        "id": 1234567,
        "document": "12345678",
        "name": "JUAN",
        "last_name": "PEREZ",
        "sur_name": "GARCIA",
        "full_name": "JUAN PEREZ GARCIA",
        "phone": 999888777
      },
      "receiver": { "id": 7654321, "document": "87654321", "...": "..." },
      "items": [
        {
          "id": 11223344,
          "quantity": 1,
          "weight": 0,
          "width": 0,
          "length": 0,
          "height": 0,
          "status": 1,
          "product_name": "Sobre",
          "product_detail": "Documentos simples en sobre manila / Tamaño A4",
          "product_price": 20
        }
      ],
      "warranty": { "active": false, "amount": 0, "total_cost": 0, "percent": 0.01 }
    }
  ]
}

Campos de la orden

Campo	Tipo	Descripción
id	int	ID que pro.shalom.pe le asigna a la orden dentro de la cuenta empresarial. Lo usas como path param en `DELETE /v1/orders/{id}` para borrarla. No confundir con `ose_id`: este es para operar sobre la orden (borrar), `ose_id` es para tracking.
internal_id	int	ID interno que Shalom Pro asigna a cada orden (visible en su panel como "id"). Útil solo si necesitas cruzar información contra capturas o reportes de Shalom Pro — no se usa en ninguna llamada de esta API.
guia	string	Identificador con el que se rastrea el envío públicamente. 8 a 10 dígitos (ej. `"12345678"`). Es lo que aparece impreso en el comprobante físico que el cliente final recibe, y lo que pasas como `numero=` en `GET /v1/tracking`.
serie	string	Prefijo del talonario del que sale la guía (ej. `"s001"`). Informativo — no se usa en ninguna llamada.
codigo	string	Identificador alternativo para tracking, alfanumérico de 4 caracteres (ej. `"ABCD"`). Lo asigna Shalom al crear. Lo pasas como `codigo=` en `GET /v1/tracking`.
pickup_code	string	Clave de 4 dígitos que el destinatario presenta en la agencia para retirar el envío. La elegiste tú al crear la orden.
created_at / updated_at / shipping_date	string	Timestamps en formato Lima (`YYYY-MM-DD HH:MM:SS` y `YYYY-MM-DD`).
status	int	Código numérico de estado de la orden (1 = creada, etc.). El significado lo define el flujo operativo de Shalom Pro.
payer	string	`"sender"` o `"receiver"` (mapeado de REMITENTE/DESTINATARIO).
aereo / delivered / paid	bool	Booleanos que indican si el envío es aéreo, ya fue entregado y/o ya fue pagado.
origin / destination	object	Agencia con `ter_id`, `name`, `address`, `abbreviation`, `phone`, `ubigeo`.
sender / receiver	object	Persona con `id`, `document`, `name`, `last_name`, `sur_name`, `full_name`, `phone`, `email`, `address`.
items[]	array	Detalle por bulto: `quantity`, `weight`, `width`, `length`, `height`, `product_name`, `product_detail`, `product_price`.
warranty	object	`{ active, amount, total_cost, percent }`. Si la orden no tiene garantía, `active` es `false`.

 Privacidad
 
La respuesta que ves arriba es exactamente lo que llega al cliente. Filtramos cualquier campo sensible (passwords, banderas internas, datos de la company del cliente) antes de devolverlo, así no hay sorpresas en lo que termine en tus logs.

   DELETE/v1/orders/{id}
 
Borra una orden de la cuenta del cliente. Funciona tanto para borradores (preguías sin guía empresarial real) como para guías ya emitidas que aún no fueron recibidas en agencia.
  Path param. {id} es el campo id que devuelve GET /v1/orders — el ID de la orden dentro de la cuenta empresarial. No es ose_id (eso es para tracking) ni la guia.
 
  Operación destructiva. La orden no se puede recuperar una vez borrada. Conviene confirmar con el usuario antes del submit.
 
    Request  
   curl -X DELETE https://api.shalom-api-peru.com/v1/orders/87654321 \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro"
 
 
    200 OK  
   {
  "deleted": true,
  "id": 87654321
}
 
 
  
 Errores específicos
  HTTP code Cuándo se da
  400 bad_request El path param {id} no es un entero positivo válido.
 404 not_found La orden no existe en la cuenta del cliente (ya fue borrada o el id es de otra cuenta).
 422 upstream_rejected Shalom Pro rechaza el borrado — típicamente porque la guía ya fue recibida en agencia o despachada.
 502 shalom_unavailable Pro Web caído, lento o respuesta inesperada. Reintentar.
 
 
    422 — Shalom rechaza el borrado  
   {
  "error": {
    "code": "upstream_rejected",
    "message": "Shalom Pro rechazó el borrado: shalompro: delete /delete-guia: La guia ya fue recibida en agencia",
    "request_id": "01KQ..."
  }
}
 
 
  
 
   GET/v1/orders/{ose_id}/label
 
Descarga el rótulo de la orden (etiqueta que se pega en el paquete) como PDF. Pensado para imprimir y entregar en la agencia. Respuesta binaria con Content-Type: application/pdf.
  El path param {ose_id} NO es el mismo que el id empresarial. Es el campo ose_id que devolvemos al crear la orden con POST /v1/orders. Guárdalo cuando crees la orden si piensas imprimir el rótulo después.
 
    Request  
   curl https://api.shalom-api-peru.com/v1/orders/1234567890/label \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro" \
  --output rotulo.pdf
 
 
  
 Errores específicos
  HTTP code Cuándo se da
  400 bad_request El path param {ose_id} no es entero positivo.
 404 not_found El ose_id no existe en la cuenta del cliente.
 502 shalom_unavailable Pro Web caído o respuesta inesperada.
 
 
   GET/v1/orders/{ose_id}/voucher
 
Descarga el comprobante de la orden (resumen con datos de remitente, destinatario e items) como PDF. Mismo contrato que /label: Content-Type: application/pdf binario y mismo path param {ose_id}.
    Request  
   curl https://api.shalom-api-peru.com/v1/orders/1234567890/voucher \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro" \
  --output comprobante.pdf
 
 
  
 Errores específicos
 Mismos códigos que /label (400, 404, 502).
 
   Campos del body
 Requeridos
  Campo Tipo Descripción
  origin_terminal_id int ID de la agencia de origen (campo id de GET /v1/agencies)
 destiny_terminal_id int ID de la agencia de destino (campo id de GET /v1/agencies)
 product_id int ID del producto (Sobre, Caja XXS/XS/S/M/L, Otra Medida). Listalo con GET /v1/products.
 sender object Remitente (ver subcampos abajo).
 receiver object Destinatario.
 pickup_code string Clave de retiro de 4 dígitos. No puede ser repetido (1111..9999) ni consecutivo (1234..6789).
 
 
 Opcionales
  Campo Tipo Descripción
  quantity int Default 1.
 payer string "sender" (default, paga al despachar) o "receiver" (contra entrega).
 dimensions object Dimensiones custom { weight_kg, height_m, length_m, width_m }. Solo para producto "Otra Medida".
 aereo bool Servicio aéreo. Solo si origen y destino lo soportan.
 warranty object { "amount": "100.00" } activa garantía con monto declarado.
 collection_service object Cobro contra entrega. Requiere cuenta bancaria registrada en Shalom Pro previamente.
 documentation array Guías adicionales: [{ "guide": "G123", "series": "S01" }].
 declaracion_jurada string Tipo de contenido declarado. Acepta 4 alias cortos — "art", "docs", "ropa", "electro" — o los 4 textos literales que Shalom imprime en la guía: "Articulos de uso personal" (sin tilde), "Documentos", "Ropa", "Electrodomésticos" (con tilde). Internamente mapeamos al texto literal antes de enviarlo. Legacy: "merc" se acepta y mapea a "Articulos de uso personal".
 contacto_doc string Documento de la persona que recoge.
 
 
 Sender / receiver
 
Hay dos formas de identificar a un remitente o destinatario (persona natural o empresa):
  Por id: cuando ya conoces su id (por ejemplo de GET /v1/persons/search o de un envío anterior). Pasas solo { "id": 2833026 } y los demás campos se completan automáticamente.
 Por datos completos: cuando todavía no existe en Shalom Pro. Pasás document_type, document, name, phone y — solo para DNI/CE — last_name + sur_name. Si ya existe se reusa; si no, se registra con esos datos.
 
  Empresas (RUC): la razón social va completa en name. last_name y sur_name no aplican.
 
 Ejemplo: persona (DNI)
     {
  "document_type": "DNI",
  "document": "12345678",
  "name": "JUAN",
  "last_name": "PEREZ",
  "sur_name": "GARCIA",
  "phone": 999888777
}
 
 
  Ejemplo: empresa (RUC)
     {
  "document_type": "RUC",
  "document": "20100070970",
  "name": "MI EMPRESA S.A.C.",
  "phone": 999888777
}
 
 
   Campo Tipo Descripción
  id int person_id de Shalom Pro. Si lo pasas, los demás campos no son necesarios.
 document_type string "DNI" (8 dígitos), "RUC" (11 dígitos, empresas) o "CE" (carnet de extranjería).
 document string Solo dígitos para DNI/RUC; alfanumérico ≥4 chars para CE.
 name string Nombre (persona) o razón social completa (empresa). Obligatorio.
 last_name string Primer apellido. Obligatorio para DNI/CE, no aplica a RUC.
 sur_name string Segundo apellido. No aplica a RUC.
 phone int Teléfono numérico (sin código de país, ej. 999888777).
 email string Opcional.
 address string Opcional.
 
 
 
   Errores específicos de /v1/orders
 Además de los códigos generales, este endpoint puede devolver:
  HTTP code Cuándo se da
  401 shalom_auth_failed Falta X-Shalom-Email/X-Shalom-Password o son rechazados por Shalom Pro.
 409 conflict Persona ya registrada con ese documento — pasa id en lugar de los datos.
 422 upstream_rejected El cliente no tiene servicio de cobranza habilitado, producto restringido para esa ruta, etc.
 502 shalom_unavailable Pro Web caído, lento o respuesta inesperada. Reintentar.
 
 
    401 — credenciales rechazadas  
   {
  "error": {
    "code": "shalom_auth_failed",
    "message": "X-Shalom-Email/Password rechazados por Shalom Pro",
    "request_id": "01KQ..."
  }
}
 
 
  
 
   Health Checks
 Publicos, sin auth.
   GET/healthz
 Liveness. 200 si el servidor está vivo.
 
  GET/readyz
 Readiness. 200 cuando está listo para recibir tráfico.

HTTP	code	Cuándo se da
400	bad_request	El path param `{id}` no es un entero positivo válido.
404	not_found	La orden no existe en la cuenta del cliente (ya fue borrada o el id es de otra cuenta).
422	upstream_rejected	Shalom Pro rechaza el borrado — típicamente porque la guía ya fue recibida en agencia o despachada.
502	shalom_unavailable	Pro Web caído, lento o respuesta inesperada. Reintentar.

HTTP	code	Cuándo se da
400	bad_request	El path param `{ose_id}` no es entero positivo.
404	not_found	El `ose_id` no existe en la cuenta del cliente.
502	shalom_unavailable	Pro Web caído o respuesta inesperada.

Campo	Tipo	Descripción
origin_terminal_id	int	ID de la agencia de origen (campo `id` de `GET /v1/agencies`)
destiny_terminal_id	int	ID de la agencia de destino (campo `id` de `GET /v1/agencies`)
product_id	int	ID del producto (Sobre, Caja XXS/XS/S/M/L, Otra Medida). Listalo con `GET /v1/products`.
sender	object	Remitente (ver subcampos abajo).
receiver	object	Destinatario.
pickup_code	string	Clave de retiro de 4 dígitos. No puede ser repetido (1111..9999) ni consecutivo (1234..6789).

Campo	Tipo	Descripción
quantity	int	Default 1.
payer	string	`"sender"` (default, paga al despachar) o `"receiver"` (contra entrega).
dimensions	object	Dimensiones custom `{ weight_kg, height_m, length_m, width_m }`. Solo para producto "Otra Medida".
aereo	bool	Servicio aéreo. Solo si origen y destino lo soportan.
warranty	object	`{ "amount": "100.00" }` activa garantía con monto declarado.
collection_service	object	Cobro contra entrega. Requiere cuenta bancaria registrada en Shalom Pro previamente.
documentation	array	Guías adicionales: `[{ "guide": "G123", "series": "S01" }]`.
declaracion_jurada	string	Tipo de contenido declarado. Acepta 4 alias cortos — `"art"`, `"docs"`, `"ropa"`, `"electro"` — o los 4 textos literales que Shalom imprime en la guía: `"Articulos de uso personal"` (sin tilde), `"Documentos"`, `"Ropa"`, `"Electrodomésticos"` (con tilde). Internamente mapeamos al texto literal antes de enviarlo. Legacy: `"merc"` se acepta y mapea a `"Articulos de uso personal"`.
contacto_doc	string	Documento de la persona que recoge.

Campo	Tipo	Descripción
id	int	person_id de Shalom Pro. Si lo pasas, los demás campos no son necesarios.
document_type	string	`"DNI"` (8 dígitos), `"RUC"` (11 dígitos, empresas) o `"CE"` (carnet de extranjería).
document	string	Solo dígitos para DNI/RUC; alfanumérico ≥4 chars para CE.
name	string	Nombre (persona) o razón social completa (empresa). Obligatorio.
last_name	string	Primer apellido. Obligatorio para DNI/CE, no aplica a RUC.
sur_name	string	Segundo apellido. No aplica a RUC.
phone	int	Teléfono numérico (sin código de país, ej. `999888777`).
email	string	Opcional.
address	string	Opcional.

HTTP	code	Cuándo se da
401	shalom_auth_failed	Falta `X-Shalom-Email`/`X-Shalom-Password` o son rechazados por Shalom Pro.
409	conflict	Persona ya registrada con ese documento — pasa `id` en lugar de los datos.
422	upstream_rejected	El cliente no tiene servicio de cobranza habilitado, producto restringido para esa ruta, etc.
502	shalom_unavailable	Pro Web caído, lento o respuesta inesperada. Reintentar.

Documentación.

Autenticación

Errores

Rate Limits

Query params (al menos 1 requerido)

Crear pedido en Shalom Pro

Auth Shalom — opción A (recomendada): token efímero

Auth Shalom — opción B: email/password directo

Headers

Latencia y cache

Body

Cuándo el token expira

Errores

Campos del producto

Otra Medida — bulto fuera de catálogo

Query params

Errores específicos

Body

Con product_id — precio puntual

Errores específicos

Qué es cada campo

Campos de la orden

Privacidad

Errores específicos

Errores específicos

Errores específicos

Campos del body

Requeridos

Opcionales

Sender / receiver

Ejemplo: persona (DNI)

Ejemplo: empresa (RUC)

Errores específicos de /v1/orders

Health Checks

Con `product_id` — precio puntual