{"openapi":"3.1.0","info":{"title":"LDX Consultas API — shalom","description":"API de consulta de LDX Software: un solo gateway, un solo token y un mismo\nformato de respuesta para todos los servicios del catálogo. Cada servicio\ndeclara sus parámetros y sus campos en su propio documento OpenAPI.\n\n**Autenticación.** Toda petición lleva `Authorization: Bearer ldx_live_...`.\nCrea tu token en el portal; se muestra una sola vez.\n\n**Prueba gratis.** Al registrarte tienes 3 días y 300 consultas. Después el\nacceso se bloquea con un `402` hasta que habilitemos tu cuenta.\n\n**Volumen.** Hasta 25 ítems por lote síncrono; para más, usa\n`POST /v1/batch/jobs` y recoge los resultados por webhook o por sondeo.\n\n**Origen de los datos.** Provienen de los sistemas de consulta pública de\nterceros y pertenecen a esas fuentes, no a LDX Software. LDX Software no\nmantiene relación oficial con ninguna de ellas, no las representa y no\ngarantiza la exactitud, la vigencia ni la disponibilidad de la información que\npublican.","version":"1.0.0"},"servers":[{"url":"https://ldxsoftware.com.pe"}],"paths":{"/consultas/v1/me":{"get":{"tags":["consultas"],"summary":"Mi Cuenta","operationId":"mi_cuenta_consultas_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Mi Cuenta Consultas V1 Me Get"}}}}}}},"/consultas/v1/shalom/tracking":{"get":{"tags":["consultas"],"summary":"Consultar un envío","description":"Devuelve el estado actual, el historial completo y las fotos de evidencia (cuando el courier las provee) de un solo envío.\n\n**Datos personales.** La respuesta de este endpoint identifica a una persona. Consúltala solo con una finalidad que puedas sustentar ante su titular, no la conserves más de lo que esa finalidad necesite y trátala conforme a la normativa peruana de protección de datos personales.","operationId":"tracking_consultas_v1__shalom__tracking_get","parameters":[{"name":"numero","in":"query","required":true,"description":"Número de la orden de servicio que figura en el comprobante de Shalom. Solo dígitos.","example":"99999999","schema":{"type":"string","pattern":"^[0-9]{1,15}$"}},{"name":"codigo","in":"query","required":true,"description":"Código alfanumérico que acompaña al número en el comprobante. Se envía en mayúsculas; el gateway convierte las minúsculas.","example":"ZZZZ","schema":{"type":"string","pattern":"^[A-Z0-9]{2,10}$"}},{"name":"raw","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Raw"}}],"responses":{"200":{"description":"El envío, o el motivo de que no salga.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Envío de shalom","properties":{"ok":{"type":"boolean","description":"`true` cuando la consulta se resolvió. Un envío que el courier no encuentra responde igualmente 200, con `ok: false`.","example":true},"request_id":{"type":"string","description":"Identificador de esta petición, el mismo que viaja en la cabecera `X-Request-Id`. Cítalo al reportar una incidencia.","example":"req_9505"},"courier":{"type":"string","enum":["shalom"],"description":"Courier consultado.","example":"shalom"},"tracking":{"type":"string","description":"Número de guía u orden, tal y como lo publica el courier.","example":"99999999"},"estado_actual":{"type":["string","null"],"description":"Estado que DECLARA el courier. Si no declara ninguno se usa el del último evento del historial. Los textos son los del courier: no hay un catálogo común entre couriers, así que para decidir en tu código usa `entregado`, no este campo.","example":"ENTREGADO"},"fecha_estado":{"type":["string","null"],"description":"Fecha del último evento del historial, en ISO-8601 con la zona de Lima.","format":"date-time","example":"2026-08-21T17:04:52-05:00"},"entregado":{"type":"boolean","description":"El envío llegó a su destinatario. Sale de la bandera que publica el courier cuando la publica; si no, de que el estado actual sea uno de los terminales.","example":true},"fecha_emision":{"type":["string","null"],"description":"Fecha de emisión de la guía, en ISO-8601 con la zona de Lima. Olva solo publica el día, así que sus envíos salen a las 00:00.","format":"date-time","example":"2026-08-17T13:02:38-05:00"},"contenido":{"type":["string","null"],"description":"Descripción de lo que se envía, tal y como la declaró el remitente.","example":"1 PAQUETE L"},"origen":{"type":["string","null"],"description":"Ciudad o agencia de origen del envío. shalom no publica este dato: viene siempre vacío."},"destino":{"type":["string","null"],"description":"Ciudad o agencia de destino del envío. shalom no publica este dato: viene siempre vacío."},"remitente":{"type":["string","null"],"description":"Quien envía. shalom no publica este dato: viene siempre vacío."},"destinatario":{"type":["string","null"],"description":"Quien recibe."},"historial":{"type":"array","description":"Eventos del envío en orden cronológico ascendente: el último elemento es el más reciente.","items":{"type":"object","title":"Evento del historial","properties":{"fecha":{"type":["string","null"],"description":"Fecha del evento en ISO-8601 con la zona de Lima (-05:00). `null` si el courier la devolvió en un formato que no supimos interpretar.","format":"date-time","example":"2026-08-17T13:02:00-05:00"},"estado":{"type":["string","null"],"description":"Estado del envío en ese momento, en MAYÚSCULAS y sin espacios sobrantes. Los textos son los del courier: no hay un catálogo común entre couriers.","example":"EN TRANSITO"},"sede":{"type":["string","null"],"description":"Sede o agencia donde ocurrió el evento, si el courier la da."},"detalle":{"type":["string","null"],"description":"Observación que el courier adjunta al evento."}},"required":["fecha","estado","sede","detalle"]}},"evidencias":{"type":"array","description":"URLs de las fotos de entrega que publica el courier. shalom no publica ninguna: la lista viene siempre vacía.","items":{"type":"string","format":"uri"}},"detalle":{"type":"object","title":"Detalle de shalom","description":"Campos que publica shalom y no forman parte del contrato común, porque el resto de couriers no los tiene. Las claves son siempre estas y solo estas: lo que el courier no devuelva viaja en `null`.","properties":{"codigo_orden":{"type":["string","null"],"description":"Código alfanumérico del comprobante, el mismo que se envía en la consulta. Viene devuelto para poder casar cada resultado de un lote con su ítem: `tracking` solo trae el número.","example":"ZZZZ"},"ose_id":{"type":["string","null"],"description":"Identificador interno del envío en Shalom. Útil al reportar una incidencia. Shalom lo manda como número; se publica como cadena, igual que `tracking`, porque es un identificador y no una cantidad.","example":"95730181"},"tipo_pago":{"type":["string","null"],"description":"Cómo se paga el servicio, tal y como lo rotula Shalom.","example":"Contra entrega"},"monto":{"type":["string","null"],"description":"Importe del servicio en soles, tal y como lo devuelve Shalom. Se publica como cadena y sin tocar los decimales: convertirlo a número perdería los céntimos exactos que el courier cobra.","example":"20.00"},"fecha_traslado":{"type":["string","null"],"description":"Fecha del traslado, en ISO-8601 con la zona de Lima.","example":"2026-08-17T13:02:00-05:00"},"direccion_entrega":{"type":["string","null"],"description":"Instrucción de reparto que Shalom imprime en el comprobante («ENTREGAR EN AGENCIA», por ejemplo). NO es una dirección postal ni una ciudad: no sirve para deducir el destino del envío.","example":"ENTREGAR EN AGENCIA"},"aereo":{"type":["boolean","null"],"description":"El envío viaja por vía aérea.","example":false},"reparto":{"type":["boolean","null"],"description":"El envío se reparte a domicilio. En falso se recoge en agencia, que es lo que suele decir también `direccion_entrega`.","example":false},"tiene_cambio_destino":{"type":["boolean","null"],"description":"El envío cambió de destino después de emitirse.","example":false},"tiene_devolucion_mercaderia":{"type":["boolean","null"],"description":"La mercadería se devolvió al remitente.","example":false}},"example":{"codigo_orden":"ZZZZ","ose_id":"95730181","tipo_pago":"Contra entrega","monto":"20.00","fecha_traslado":"2026-08-17T13:02:00-05:00","direccion_entrega":"ENTREGAR EN AGENCIA","aereo":false,"reparto":false,"tiene_cambio_destino":false,"tiene_devolucion_mercaderia":false},"required":["codigo_orden","ose_id","tipo_pago","monto","fecha_traslado","direccion_entrega","aereo","reparto","tiene_cambio_destino","tiene_devolucion_mercaderia"]},"cached":{"type":"boolean","description":"La respuesta se sirvió de nuestra caché en vez de consultar al courier. Se cobra igual, y el dato tiene como mucho unos minutos.","example":false},"raw":{"type":["object","null"],"description":"La respuesta cruda del courier, SOLO si pides `?raw=true`. Su forma la decide el courier y puede cambiar sin aviso: no es parte del contrato.","additionalProperties":true}},"required":["ok","request_id","courier","tracking","estado_actual","fecha_estado","entregado","fecha_emision","contenido","origen","destino","remitente","destinatario","historial","evidencias","detalle","cached","raw"]},{"type":"object","title":"Envío no resuelto","description":"El courier no encontró el envío, rechazó los datos o no respondió. La consulta se cobra igual: llegó al courier.","properties":{"ok":{"type":"boolean","enum":[false],"example":false},"error":{"type":"string","description":"Código del fallo de ESTE envío.","example":"no_encontrado"},"mensaje":{"type":"string","description":"Explicación en español."},"request_id":{"type":"string","example":"req_9505"},"courier":{"type":"string","example":"olva"}},"required":["ok","error","mensaje"]}],"description":"Distínguelas por `ok`."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/consultas/v1/shalom/tracking/bulk":{"post":{"tags":["consultas"],"summary":"Consultar varios envíos","description":"Resuelve hasta el máximo síncrono configurado para tu cuenta en una sola petición; para volúmenes mayores usa /v1/batch/jobs.\n\n**Datos personales.** La respuesta de este endpoint identifica a una persona. Consúltala solo con una finalidad que puedas sustentar ante su titular, no la conserves más de lo que esa finalidad necesite y trátala conforme a la normativa peruana de protección de datos personales.","operationId":"tracking_lote_consultas_v1__shalom__tracking_bulk_post","parameters":[{"name":"raw","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Raw"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"object","title":"Envío de shalom","properties":{"numero":{"type":"string","pattern":"^[0-9]{1,15}$","description":"Número de la orden de servicio que figura en el comprobante de Shalom. Solo dígitos.","example":"99999999"},"codigo":{"type":"string","pattern":"^[A-Z0-9]{2,10}$","description":"Código alfanumérico que acompaña al número en el comprobante. Se envía en mayúsculas; el gateway convierte las minúsculas.","example":"ZZZZ"}},"example":{"numero":"99999999","codigo":"ZZZZ"},"required":["numero","codigo"]},"description":"Hasta 25 envíos por petición. Para volúmenes mayores, POST /v1/batch/jobs."}},"example":{"items":[{"numero":"99999999","codigo":"ZZZZ"}]}}}}},"responses":{"200":{"description":"Un resultado por ítem enviado.","content":{"application/json":{"schema":{"type":"object","title":"Lote de shalom","properties":{"ok":{"type":"boolean","example":true},"request_id":{"type":"string","example":"req_9505"},"courier":{"type":"string","enum":["shalom"],"example":"shalom"},"total":{"type":"integer","description":"Número de resultados, igual al de ítems enviados.","example":1},"resultados":{"type":"array","description":"Un resultado por ítem, EN EL MISMO ORDEN en que se enviaron. Cada uno se resuelve por separado: que uno falle no anula a los demás.","items":{"oneOf":[{"type":"object","title":"Envío de shalom","properties":{"ok":{"type":"boolean","description":"`true` cuando la consulta se resolvió. Un envío que el courier no encuentra responde igualmente 200, con `ok: false`.","example":true},"request_id":{"type":"string","description":"Identificador de esta petición, el mismo que viaja en la cabecera `X-Request-Id`. Cítalo al reportar una incidencia.","example":"req_9505"},"courier":{"type":"string","enum":["shalom"],"description":"Courier consultado.","example":"shalom"},"tracking":{"type":"string","description":"Número de guía u orden, tal y como lo publica el courier.","example":"99999999"},"estado_actual":{"type":["string","null"],"description":"Estado que DECLARA el courier. Si no declara ninguno se usa el del último evento del historial. Los textos son los del courier: no hay un catálogo común entre couriers, así que para decidir en tu código usa `entregado`, no este campo.","example":"ENTREGADO"},"fecha_estado":{"type":["string","null"],"description":"Fecha del último evento del historial, en ISO-8601 con la zona de Lima.","format":"date-time","example":"2026-08-21T17:04:52-05:00"},"entregado":{"type":"boolean","description":"El envío llegó a su destinatario. Sale de la bandera que publica el courier cuando la publica; si no, de que el estado actual sea uno de los terminales.","example":true},"fecha_emision":{"type":["string","null"],"description":"Fecha de emisión de la guía, en ISO-8601 con la zona de Lima. Olva solo publica el día, así que sus envíos salen a las 00:00.","format":"date-time","example":"2026-08-17T13:02:38-05:00"},"contenido":{"type":["string","null"],"description":"Descripción de lo que se envía, tal y como la declaró el remitente.","example":"1 PAQUETE L"},"origen":{"type":["string","null"],"description":"Ciudad o agencia de origen del envío. shalom no publica este dato: viene siempre vacío."},"destino":{"type":["string","null"],"description":"Ciudad o agencia de destino del envío. shalom no publica este dato: viene siempre vacío."},"remitente":{"type":["string","null"],"description":"Quien envía. shalom no publica este dato: viene siempre vacío."},"destinatario":{"type":["string","null"],"description":"Quien recibe."},"historial":{"type":"array","description":"Eventos del envío en orden cronológico ascendente: el último elemento es el más reciente.","items":{"type":"object","title":"Evento del historial","properties":{"fecha":{"type":["string","null"],"description":"Fecha del evento en ISO-8601 con la zona de Lima (-05:00). `null` si el courier la devolvió en un formato que no supimos interpretar.","format":"date-time","example":"2026-08-17T13:02:00-05:00"},"estado":{"type":["string","null"],"description":"Estado del envío en ese momento, en MAYÚSCULAS y sin espacios sobrantes. Los textos son los del courier: no hay un catálogo común entre couriers.","example":"EN TRANSITO"},"sede":{"type":["string","null"],"description":"Sede o agencia donde ocurrió el evento, si el courier la da."},"detalle":{"type":["string","null"],"description":"Observación que el courier adjunta al evento."}},"required":["fecha","estado","sede","detalle"]}},"evidencias":{"type":"array","description":"URLs de las fotos de entrega que publica el courier. shalom no publica ninguna: la lista viene siempre vacía.","items":{"type":"string","format":"uri"}},"detalle":{"type":"object","title":"Detalle de shalom","description":"Campos que publica shalom y no forman parte del contrato común, porque el resto de couriers no los tiene. Las claves son siempre estas y solo estas: lo que el courier no devuelva viaja en `null`.","properties":{"codigo_orden":{"type":["string","null"],"description":"Código alfanumérico del comprobante, el mismo que se envía en la consulta. Viene devuelto para poder casar cada resultado de un lote con su ítem: `tracking` solo trae el número.","example":"ZZZZ"},"ose_id":{"type":["string","null"],"description":"Identificador interno del envío en Shalom. Útil al reportar una incidencia. Shalom lo manda como número; se publica como cadena, igual que `tracking`, porque es un identificador y no una cantidad.","example":"95730181"},"tipo_pago":{"type":["string","null"],"description":"Cómo se paga el servicio, tal y como lo rotula Shalom.","example":"Contra entrega"},"monto":{"type":["string","null"],"description":"Importe del servicio en soles, tal y como lo devuelve Shalom. Se publica como cadena y sin tocar los decimales: convertirlo a número perdería los céntimos exactos que el courier cobra.","example":"20.00"},"fecha_traslado":{"type":["string","null"],"description":"Fecha del traslado, en ISO-8601 con la zona de Lima.","example":"2026-08-17T13:02:00-05:00"},"direccion_entrega":{"type":["string","null"],"description":"Instrucción de reparto que Shalom imprime en el comprobante («ENTREGAR EN AGENCIA», por ejemplo). NO es una dirección postal ni una ciudad: no sirve para deducir el destino del envío.","example":"ENTREGAR EN AGENCIA"},"aereo":{"type":["boolean","null"],"description":"El envío viaja por vía aérea.","example":false},"reparto":{"type":["boolean","null"],"description":"El envío se reparte a domicilio. En falso se recoge en agencia, que es lo que suele decir también `direccion_entrega`.","example":false},"tiene_cambio_destino":{"type":["boolean","null"],"description":"El envío cambió de destino después de emitirse.","example":false},"tiene_devolucion_mercaderia":{"type":["boolean","null"],"description":"La mercadería se devolvió al remitente.","example":false}},"example":{"codigo_orden":"ZZZZ","ose_id":"95730181","tipo_pago":"Contra entrega","monto":"20.00","fecha_traslado":"2026-08-17T13:02:00-05:00","direccion_entrega":"ENTREGAR EN AGENCIA","aereo":false,"reparto":false,"tiene_cambio_destino":false,"tiene_devolucion_mercaderia":false},"required":["codigo_orden","ose_id","tipo_pago","monto","fecha_traslado","direccion_entrega","aereo","reparto","tiene_cambio_destino","tiene_devolucion_mercaderia"]},"cached":{"type":"boolean","description":"La respuesta se sirvió de nuestra caché en vez de consultar al courier. Se cobra igual, y el dato tiene como mucho unos minutos.","example":false},"raw":{"type":["object","null"],"description":"La respuesta cruda del courier, SOLO si pides `?raw=true`. Su forma la decide el courier y puede cambiar sin aviso: no es parte del contrato.","additionalProperties":true}},"required":["ok","request_id","courier","tracking","estado_actual","fecha_estado","entregado","fecha_emision","contenido","origen","destino","remitente","destinatario","historial","evidencias","detalle","cached","raw"]},{"type":"object","title":"Envío no resuelto","description":"El courier no encontró el envío, rechazó los datos o no respondió. La consulta se cobra igual: llegó al courier.","properties":{"ok":{"type":"boolean","enum":[false],"example":false},"error":{"type":"string","description":"Código del fallo de ESTE envío.","example":"no_encontrado"},"mensaje":{"type":"string","description":"Explicación en español."}},"required":["ok","error","mensaje"]}],"description":"Distínguelos por `ok`."}}},"required":["ok","request_id","courier","total","resultados"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/consultas/v1/shalom/agencias":{"get":{"tags":["consultas"],"summary":"Agencias de Shalom","description":"Padrón de agencias de Shalom Empresarial en todo el Perú: dirección, distrito, ubigeo, coordenadas, horario de atención y límites de peso que acepta cada local. Se puede filtrar por departamento y provincia, o buscar por cualquier campo o solo por nombre.","operationId":"operacion_agencias_consultas_v1__shalom__agencias_get","parameters":[{"name":"q","in":"query","required":false,"description":"Texto a buscar. Se ignoran mayúsculas, tildes y signos de puntuación, y se exigen TODAS las palabras: «av arequipa» devuelve solo las agencias que tengan las dos. Sin este parámetro se devuelve el padrón completo.","example":"miraflores","schema":{"type":"string","pattern":"^[^\\x00-\\x1f\\x7f]{0,80}$"}},{"name":"ambito","in":"query","required":false,"description":"Dónde buscar: «todo» mira nombre, dirección, distrito, provincia, departamento, teléfono, horario y límites de peso; «nombre» mira solo el nombre de la agencia.","example":"todo","schema":{"type":"string","pattern":"^(todo|nombre)$","default":"todo"}},{"name":"departamento","in":"query","required":false,"description":"Departamento exacto, ignorando mayúsculas y tildes: «ancash» y «ÁNCASH» son el mismo. Un departamento en el que Shalom no tiene ninguna agencia se rechaza con un 400 que lista los que sí, para que una lista vacía signifique siempre «no hay agencias» y nunca «lo escribiste mal».","example":"LIMA","schema":{"type":"string","pattern":"^[^\\x00-\\x1f\\x7f]{0,60}$"}},{"name":"provincia","in":"query","required":false,"description":"Provincia exacta, ignorando mayúsculas y tildes. Se puede usar sola o junto a `departamento`; combinadas tienen que ser una pareja que exista. Como con el departamento, una provincia sin agencias de Shalom se rechaza en vez de devolver la lista vacía.","example":"","schema":{"type":"string","pattern":"^[^\\x00-\\x1f\\x7f]{0,60}$"}},{"name":"detalle","in":"query","required":false,"description":"«completo» devuelve los 18 campos de cada agencia; «minimo» devuelve solo identificación, ubicación y coordenadas, para listados y mapas.","example":"completo","schema":{"type":"string","pattern":"^(completo|minimo)$","default":"completo"}},{"name":"limite","in":"query","required":false,"description":"Cuántas agencias devolver, de 1 a 1000. El padrón entero son 548, así que `limite=1000` lo trae de una sola vez.","example":"100","schema":{"type":"string","pattern":"^([1-9][0-9]{0,2}|1000)$","default":"100"}},{"name":"pagina","in":"query","required":false,"description":"Página a devolver, empezando en 1. `total` dice cuántas agencias encontró la búsqueda entera, no cuántas trae esta página.","example":"1","schema":{"type":"string","pattern":"^[1-9][0-9]{0,2}$","default":"1"}},{"name":"raw","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Raw"}}],"responses":{"200":{"description":"El dato consultado, o `encontrado: false` si la fuente no lo tiene.","content":{"application/json":{"schema":{"type":"object","title":"agencias de shalom","properties":{"ok":{"type":"boolean","description":"`true` cuando la consulta se resolvió. Que la fuente no tenga el dato NO es un fallo: eso se mira en `encontrado`.","example":true},"request_id":{"type":"string","description":"Identificador de esta petición, el mismo que viaja en la cabecera `X-Request-Id`. Cítalo al reportar una incidencia.","example":"req_9505"},"servicio":{"type":"string","enum":["shalom"],"description":"Servicio consultado.","example":"shalom"},"operacion":{"type":"string","enum":["agencias"],"description":"Operación del servicio que resolvió esta petición. Un servicio puede publicar varias —shalom publica rastreo, agencias y cotización— y cada una devuelve un `datos` distinto, así que es esto y no `servicio` lo que dice qué forma tiene.","example":"agencias"},"encontrado":{"type":"boolean","description":"La fuente tiene el dato. Cuando es `false`, `datos` viene en `null` y la consulta se cobra igual: se llegó a la fuente y respondió que no existe.","example":true},"consultado":{"type":"object","title":"Consultado en shalom","description":"Los parámetros que se consultaron de verdad, ya normalizados por el gateway. Útil para casar la respuesta con la petición cuando se lanzan varias en paralelo.","properties":{"q":{"type":"string","description":"Texto a buscar. Se ignoran mayúsculas, tildes y signos de puntuación, y se exigen TODAS las palabras: «av arequipa» devuelve solo las agencias que tengan las dos. Sin este parámetro se devuelve el padrón completo.","example":"miraflores"},"ambito":{"type":"string","description":"Dónde buscar: «todo» mira nombre, dirección, distrito, provincia, departamento, teléfono, horario y límites de peso; «nombre» mira solo el nombre de la agencia.","example":"todo"},"departamento":{"type":"string","description":"Departamento exacto, ignorando mayúsculas y tildes: «ancash» y «ÁNCASH» son el mismo. Un departamento en el que Shalom no tiene ninguna agencia se rechaza con un 400 que lista los que sí, para que una lista vacía signifique siempre «no hay agencias» y nunca «lo escribiste mal».","example":"LIMA"},"provincia":{"type":"string","description":"Provincia exacta, ignorando mayúsculas y tildes. Se puede usar sola o junto a `departamento`; combinadas tienen que ser una pareja que exista. Como con el departamento, una provincia sin agencias de Shalom se rechaza en vez de devolver la lista vacía.","example":""},"detalle":{"type":"string","description":"«completo» devuelve los 18 campos de cada agencia; «minimo» devuelve solo identificación, ubicación y coordenadas, para listados y mapas.","example":"completo"},"limite":{"type":"string","description":"Cuántas agencias devolver, de 1 a 1000. El padrón entero son 548, así que `limite=1000` lo trae de una sola vez.","example":"100"},"pagina":{"type":"string","description":"Página a devolver, empezando en 1. `total` dice cuántas agencias encontró la búsqueda entera, no cuántas trae esta página.","example":"1"}},"required":["q","ambito","departamento","provincia","detalle","limite","pagina"],"example":{"q":"miraflores","ambito":"todo","departamento":"LIMA","provincia":"","detalle":"completo","limite":"100","pagina":"1"}},"datos":{"type":["object","null"],"title":"Datos de shalom","description":"Lo que publica la fuente. Las claves son siempre estas y solo estas: lo que la fuente no devuelva viaja en `null`. Es `null` entero cuando `encontrado` es `false`.","properties":{"total":{"type":["integer","null"],"description":"Agencias que encontró la búsqueda entera, no las de esta página. Es 0 cuando no hay ninguna, y ese 0 es una respuesta correcta.","example":3},"mostradas":{"type":["integer","null"],"description":"Agencias que trae esta página.","example":3},"pagina":{"type":["integer","null"],"description":"Página devuelta.","example":1},"limite":{"type":["integer","null"],"description":"Tamaño de página aplicado.","example":100},"actualizado":{"type":["string","null"],"description":"Fecha en que se capturó el padrón (AAAA-MM-DD).","example":"2026-08-25"},"agencias":{"type":"array","description":"Las agencias encontradas. Lista vacía si no hubo ninguna.","items":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Identificador de la agencia en Shalom.","example":3},"codigo":{"type":["string","null"],"description":"Abreviatura con la que Shalom la rotula.","example":"CHH"},"nombre":{"type":["string","null"],"description":"Nombre corto del local.","example":"CHACHAPOYAS CO DOS DE MAYO"},"nombre_completo":{"type":["string","null"],"description":"Departamento / provincia / distrito / local, como lo lista Shalom.","example":"AMAZONAS / CHACHAPOYAS / CHACHAPOYAS / CHACHAPOYAS CO DOS DE MAYO"},"departamento":{"type":["string","null"],"description":"Departamento.","example":"AMAZONAS"},"provincia":{"type":["string","null"],"description":"Provincia.","example":"CHACHAPOYAS"},"distrito":{"type":["string","null"],"description":"Distrito; Shalom lo llama «zona».","example":"CHACHAPOYAS"},"ubigeo":{"type":["string","null"],"description":"Ubigeo del INEI, seis dígitos. Solo con `detalle=completo`.","example":"010101"},"direccion":{"type":["string","null"],"description":"Dirección con la referencia que da Shalom.","example":"JR. DOS DE MAYO CDRA. 15 S/N CHACHAPOYAS, REFERENCIA: JUNTO A TERMINAL DE COMBIS ETSA"},"telefono":{"type":["string","null"],"description":"Teléfono publicado para esa agencia. Casi siempre es la central de Shalom, no una línea propia del local. Solo con `detalle=completo`.","example":"(01) 500 7878"},"latitud":{"type":["number","null"],"description":"Latitud en grados decimales. Null si Shalom no la publica.","example":-6.2386732901495},"longitud":{"type":["number","null"],"description":"Longitud en grados decimales.","example":-77.868008265336},"categoria":{"type":["string","null"],"description":"Tamaño del local según Shalom. Solo con `detalle=completo`.","example":"GRANDE / CO"},"envia_hasta":{"type":["string","null"],"description":"Peso y volumen máximos que la agencia admite para enviar. Solo con `detalle=completo`.","example":"HASTA 1500 KG"},"recibe_hasta":{"type":["string","null"],"description":"Peso y volumen máximos que la agencia admite para recibir. Solo con `detalle=completo`.","example":"HASTA 1500 KG"},"reparto_a_domicilio":{"type":["boolean","null"],"description":"Si la agencia tiene el reparto habilitado. Solo con `detalle=completo`.","example":true},"envio_aereo":{"type":["boolean","null"],"description":"Si la agencia opera envíos aéreos. Solo con `detalle=completo`.","example":true},"horario":{"type":["object","null"],"description":"Horario de atención, en texto y en rangos. Solo con `detalle=completo`.","properties":{"texto":{"type":"array","description":"Horario tal como lo muestra la web de Shalom.","items":{"type":"string"},"example":["LUNES A SÁBADOS - 08:00 AM A 08:00 PM","DOMINGOS - 08:00 AM A 05:00 PM"]},"lunes_viernes":{"type":["string","null"],"description":"Horario de lunes a viernes, en texto.","example":"LUNES A VIERNES - 8:00 AM A 8:00 PM"},"domingo":{"type":["string","null"],"description":"Horario de domingo, en texto.","example":"DOMINGOS DE 8:00 AM A 5:00 PM"},"rangos":{"type":["object","null"],"description":"Las mismas horas en formato HH:MM:SS, para calcular si está abierta.","properties":{"lunes":{"type":["object","null"],"description":"Atención del lunes.","properties":{"inicio":{"type":["string","null"],"description":"Hora de apertura.","example":"08:00:00"},"fin":{"type":["string","null"],"description":"Hora de cierre.","example":"20:00:00"}},"required":["inicio","fin"],"example":{"inicio":"08:00:00","fin":"20:00:00"}},"sabado":{"type":["object","null"],"description":"Atención del sabado.","properties":{"inicio":{"type":["string","null"],"description":"Hora de apertura.","example":"08:00:00"},"fin":{"type":["string","null"],"description":"Hora de cierre.","example":"20:00:00"}},"required":["inicio","fin"],"example":{"inicio":"08:00:00","fin":"20:00:00"}},"domingo":{"type":["object","null"],"description":"Atención del domingo.","properties":{"inicio":{"type":["string","null"],"description":"Hora de apertura.","example":"08:00:00"},"fin":{"type":["string","null"],"description":"Hora de cierre.","example":"17:00:00"}},"required":["inicio","fin"],"example":{"inicio":"08:00:00","fin":"17:00:00"}}},"required":["lunes","sabado","domingo"],"example":{"lunes":{"inicio":"08:00:00","fin":"20:00:00"},"sabado":{"inicio":"08:00:00","fin":"20:00:00"},"domingo":{"inicio":"08:00:00","fin":"17:00:00"}}}},"required":["texto","lunes_viernes","domingo","rangos"],"example":{"texto":["LUNES A SÁBADOS - 08:00 AM A 08:00 PM","DOMINGOS - 08:00 AM A 05:00 PM"],"lunes_viernes":"LUNES A VIERNES - 8:00 AM A 8:00 PM","domingo":"DOMINGOS DE 8:00 AM A 5:00 PM","rangos":{"lunes":{"inicio":"08:00:00","fin":"20:00:00"},"sabado":{"inicio":"08:00:00","fin":"20:00:00"},"domingo":{"inicio":"08:00:00","fin":"17:00:00"}}}}},"required":["id","codigo","nombre","nombre_completo","departamento","provincia","distrito","direccion","latitud","longitud"]},"example":[{"id":3,"codigo":"CHH","nombre":"CHACHAPOYAS CO DOS DE MAYO","nombre_completo":"AMAZONAS / CHACHAPOYAS / CHACHAPOYAS / CHACHAPOYAS CO DOS DE MAYO","departamento":"AMAZONAS","provincia":"CHACHAPOYAS","distrito":"CHACHAPOYAS","ubigeo":"010101","direccion":"JR. DOS DE MAYO CDRA. 15 S/N CHACHAPOYAS, REFERENCIA: JUNTO A TERMINAL DE COMBIS ETSA","telefono":"(01) 500 7878","latitud":-6.2386732901495,"longitud":-77.868008265336,"categoria":"GRANDE / CO","envia_hasta":"HASTA 1500 KG","recibe_hasta":"HASTA 1500 KG","reparto_a_domicilio":true,"envio_aereo":true,"horario":{"texto":["LUNES A SÁBADOS - 08:00 AM A 08:00 PM","DOMINGOS - 08:00 AM A 05:00 PM"],"lunes_viernes":"LUNES A VIERNES - 8:00 AM A 8:00 PM","domingo":"DOMINGOS DE 8:00 AM A 5:00 PM","rangos":{"lunes":{"inicio":"08:00:00","fin":"20:00:00"},"sabado":{"inicio":"08:00:00","fin":"20:00:00"},"domingo":{"inicio":"08:00:00","fin":"17:00:00"}}}}]}},"required":["total","mostradas","pagina","limite","actualizado","agencias"],"example":{"total":3,"mostradas":3,"pagina":1,"limite":100,"actualizado":"2026-08-25","agencias":[{"id":3,"codigo":"CHH","nombre":"CHACHAPOYAS CO DOS DE MAYO","nombre_completo":"AMAZONAS / CHACHAPOYAS / CHACHAPOYAS / CHACHAPOYAS CO DOS DE MAYO","departamento":"AMAZONAS","provincia":"CHACHAPOYAS","distrito":"CHACHAPOYAS","ubigeo":"010101","direccion":"JR. DOS DE MAYO CDRA. 15 S/N CHACHAPOYAS, REFERENCIA: JUNTO A TERMINAL DE COMBIS ETSA","telefono":"(01) 500 7878","latitud":-6.2386732901495,"longitud":-77.868008265336,"categoria":"GRANDE / CO","envia_hasta":"HASTA 1500 KG","recibe_hasta":"HASTA 1500 KG","reparto_a_domicilio":true,"envio_aereo":true,"horario":{"texto":["LUNES A SÁBADOS - 08:00 AM A 08:00 PM","DOMINGOS - 08:00 AM A 05:00 PM"],"lunes_viernes":"LUNES A VIERNES - 8:00 AM A 8:00 PM","domingo":"DOMINGOS DE 8:00 AM A 5:00 PM","rangos":{"lunes":{"inicio":"08:00:00","fin":"20:00:00"},"sabado":{"inicio":"08:00:00","fin":"20:00:00"},"domingo":{"inicio":"08:00:00","fin":"17:00:00"}}}}]}},"cached":{"type":"boolean","description":"La respuesta se sirvió de nuestra caché en vez de consultar a la fuente. Se cobra igual.","example":false},"raw":{"type":["object","null"],"description":"La respuesta cruda de la fuente, SOLO si pides `?raw=true`. Su forma la decide la fuente y puede cambiar sin aviso: no es parte del contrato.","additionalProperties":true}},"required":["ok","request_id","servicio","operacion","encontrado","consultado","datos","cached","raw"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/consultas/v1/shalom/cotizacion":{"get":{"tags":["consultas"],"summary":"Cotizar un envío","description":"Precio de un envío entre dos agencias de Shalom, por vía terrestre o aérea: cuánto cuesta cada tamaño de bulto y en cuánto tiempo llega. Los identificadores de agencia son los que devuelve la operación `agencias` de este mismo servicio.","operationId":"operacion_cotizacion_consultas_v1__shalom__cotizacion_get","parameters":[{"name":"origen","in":"query","required":true,"description":"Identificador de la agencia de origen (`id` de la operación `agencias`). Búscalo con `GET /v1/shalom/agencias?q=<texto>`.","example":"7","schema":{"type":"string","pattern":"^[0-9]{1,6}$"}},{"name":"destino","in":"query","required":true,"description":"Identificador de la agencia de destino (`id` de la operación `agencias`). Búscalo con `GET /v1/shalom/agencias?q=<texto>`.","example":"582","schema":{"type":"string","pattern":"^[0-9]{1,6}$"}},{"name":"via","in":"query","required":false,"description":"Vía del envío. «aereo» cotiza la tarifa aérea, que es más cara y más rápida; no todas las agencias la operan y Shalom cobra entonces una conexión aérea que no viaja en esta respuesta.","example":"terrestre","schema":{"type":"string","pattern":"^(terrestre|aereo)$","default":"terrestre"}},{"name":"raw","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Raw"}}],"responses":{"200":{"description":"El dato consultado, o `encontrado: false` si la fuente no lo tiene.","content":{"application/json":{"schema":{"type":"object","title":"cotizacion de shalom","properties":{"ok":{"type":"boolean","description":"`true` cuando la consulta se resolvió. Que la fuente no tenga el dato NO es un fallo: eso se mira en `encontrado`.","example":true},"request_id":{"type":"string","description":"Identificador de esta petición, el mismo que viaja en la cabecera `X-Request-Id`. Cítalo al reportar una incidencia.","example":"req_9505"},"servicio":{"type":"string","enum":["shalom"],"description":"Servicio consultado.","example":"shalom"},"operacion":{"type":"string","enum":["cotizacion"],"description":"Operación del servicio que resolvió esta petición. Un servicio puede publicar varias —shalom publica rastreo, agencias y cotización— y cada una devuelve un `datos` distinto, así que es esto y no `servicio` lo que dice qué forma tiene.","example":"cotizacion"},"encontrado":{"type":"boolean","description":"La fuente tiene el dato. Cuando es `false`, `datos` viene en `null` y la consulta se cobra igual: se llegó a la fuente y respondió que no existe.","example":true},"consultado":{"type":"object","title":"Consultado en shalom","description":"Los parámetros que se consultaron de verdad, ya normalizados por el gateway. Útil para casar la respuesta con la petición cuando se lanzan varias en paralelo.","properties":{"origen":{"type":"string","description":"Identificador de la agencia de origen (`id` de la operación `agencias`). Búscalo con `GET /v1/shalom/agencias?q=<texto>`.","example":"7"},"destino":{"type":"string","description":"Identificador de la agencia de destino (`id` de la operación `agencias`). Búscalo con `GET /v1/shalom/agencias?q=<texto>`.","example":"582"},"via":{"type":"string","description":"Vía del envío. «aereo» cotiza la tarifa aérea, que es más cara y más rápida; no todas las agencias la operan y Shalom cobra entonces una conexión aérea que no viaja en esta respuesta.","example":"terrestre"}},"required":["origen","destino","via"],"example":{"origen":"7","destino":"582","via":"terrestre"}},"datos":{"type":["object","null"],"title":"Datos de shalom","description":"Lo que publica la fuente. Las claves son siempre estas y solo estas: lo que la fuente no devuelva viaja en `null`. Es `null` entero cuando `encontrado` es `false`.","properties":{"via":{"type":["string","null"],"description":"Vía cotizada: «terrestre» o «aereo». Es la que se pidió.","example":"terrestre"},"origen":{"type":["object","null"],"description":"Agencia desde la que se envía.","properties":{"id":{"type":["integer","null"],"description":"Identificador de la agencia en Shalom.","example":7},"nombre":{"type":["string","null"],"description":"Rótulo del local, tal y como lo lista la operación `agencias`.","example":"AV PARRA 379"}},"required":["id","nombre"],"example":{"id":7,"nombre":"AV PARRA 379"}},"destino":{"type":["object","null"],"description":"Agencia a la que llega el envío.","properties":{"id":{"type":["integer","null"],"description":"Identificador de la agencia en Shalom.","example":582},"nombre":{"type":["string","null"],"description":"Rótulo del local, tal y como lo lista la operación `agencias`.","example":"CHALA"}},"required":["id","nombre"],"example":{"id":582,"nombre":"CHALA"}},"tiempo_entrega":{"type":["string","null"],"description":"Plazo que promete Shalom para esa ruta, en el texto que él mismo publica («48 horas»). No es un compromiso de LDX.","example":"48 horas"},"precios":{"type":["object","null"],"description":"Precio en soles de cada tamaño de bulto, tal y como Shalom lo enseña en su cotizador. Se publican en cadena y sin retocar los decimales: la fuente manda unas veces «8» y otras «8.5», y reformatearlo sería inventarse una precisión que no trae. `null` si Shalom no da ese tamaño para esa ruta.","properties":{"sobre":{"type":["string","null"],"description":"Sobre manila tamaño A4, para documentos.","example":"8"},"paquete_xxs":{"type":["string","null"],"description":"Paquete XXS: 15 × 10 × 10 cm, hasta 250 g.","example":"8"},"paquete_xs":{"type":["string","null"],"description":"Paquete XS: 20 × 15 × 12 cm, hasta 500 g.","example":"10"},"paquete_s":{"type":["string","null"],"description":"Paquete S: 30 × 20 × 12 cm, hasta 2 kg.","example":"12"},"paquete_m":{"type":["string","null"],"description":"Paquete M: 30 × 24 × 20 cm, hasta 5 kg.","example":"16"},"paquete_l":{"type":["string","null"],"description":"Paquete L: 42 × 30 × 23 cm, hasta 10 kg (9 kg por vía aérea).","example":"20"}},"required":["sobre","paquete_xxs","paquete_xs","paquete_s","paquete_m","paquete_l"],"example":{"sobre":"8","paquete_xxs":"8","paquete_xs":"10","paquete_s":"12","paquete_m":"16","paquete_l":"20"}},"minimo_facturable":{"type":["object","null"],"description":"Peso y volumen mínimos que Shalom factura en esa ruta: un bulto por debajo de ellos se cobra igual que uno que los alcance. Vienen en cero en las tarifas aéreas, donde Shalom no los aplica.","properties":{"peso_kg":{"type":["string","null"],"description":"Peso mínimo facturable, en kilos.","example":"0.9"},"volumen":{"type":["string","null"],"description":"Volumen mínimo facturable, en la unidad de su motor de tarifas —no publica cuál—.","example":"198"}},"required":["peso_kg","volumen"],"example":{"peso_kg":"0.9","volumen":"198"}}},"required":["via","origen","destino","tiempo_entrega","precios","minimo_facturable"],"example":{"via":"terrestre","origen":{"id":7,"nombre":"AV PARRA 379"},"destino":{"id":582,"nombre":"CHALA"},"tiempo_entrega":"48 horas","precios":{"sobre":"8","paquete_xxs":"8","paquete_xs":"10","paquete_s":"12","paquete_m":"16","paquete_l":"20"},"minimo_facturable":{"peso_kg":"0.9","volumen":"198"}}},"cached":{"type":"boolean","description":"La respuesta se sirvió de nuestra caché en vez de consultar a la fuente. Se cobra igual.","example":false},"raw":{"type":["object","null"],"description":"La respuesta cruda de la fuente, SOLO si pides `?raw=true`. Su forma la decide la fuente y puede cambiar sin aviso: no es parte del contrato.","additionalProperties":true}},"required":["ok","request_id","servicio","operacion","encontrado","consultado","datos","cached","raw"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/consultas/v1/batch/jobs":{"post":{"tags":["masivo"],"summary":"Crear Job","operationId":"crear_job_consultas_v1_batch_jobs_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["courier","items"],"properties":{"courier":{"type":"string","enum":["shalom"],"example":"shalom","description":"Courier al que se consultan todos los ítems del trabajo."},"items":{"type":"array","minItems":1,"maxItems":5000,"items":{"type":"object","title":"Envío de shalom","properties":{"numero":{"type":"string","pattern":"^[0-9]{1,15}$","description":"Número de la orden de servicio que figura en el comprobante de Shalom. Solo dígitos.","example":"99999999"},"codigo":{"type":"string","pattern":"^[A-Z0-9]{2,10}$","description":"Código alfanumérico que acompaña al número en el comprobante. Se envía en mayúsculas; el gateway convierte las minúsculas.","example":"ZZZZ"}},"example":{"numero":"99999999","codigo":"ZZZZ"},"required":["numero","codigo"]},"description":"Un objeto por envío, con los mismos campos que la consulta individual del courier. El tope de tu cuenta es el `job_max` que devuelve GET /v1/me."},"callback_url":{"type":"string","format":"uri","maxLength":400,"example":"https://tu-servidor.com/webhooks/ldx","description":"Opcional. URL https a la que avisamos al terminar el trabajo. Se rechazan las direcciones de red interna."}},"example":{"courier":"shalom","items":[{"numero":"99999999","codigo":"ZZZZ"}]}}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Crear Job Consultas V1 Batch Jobs Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["masivo"],"summary":"Listar Jobs","operationId":"listar_jobs_consultas_v1_batch_jobs_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Listar Jobs Consultas V1 Batch Jobs Get"}}}}}}},"/consultas/v1/batch/jobs/{job_id}":{"get":{"tags":["masivo"],"summary":"Ver Job","operationId":"ver_job_consultas_v1_batch_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Ver Job Consultas V1 Batch Jobs  Job Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["masivo"],"summary":"Cancelar","operationId":"cancelar_consultas_v1_batch_jobs__job_id__delete","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Cancelar Consultas V1 Batch Jobs  Job Id  Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/consultas/v1/batch/jobs/{job_id}/results":{"get":{"tags":["masivo"],"summary":"Resultados","operationId":"resultados_consultas_v1_batch_jobs__job_id__results_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","default":"json","title":"Format"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":200,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Los resultados del trabajo, paginados.","content":{"application/json":{"schema":{"type":"object","title":"Resultados del trabajo","description":"Con `format=csv` o `format=ndjson` este mismo endpoint devuelve texto plano en vez de este objeto, y sin paginar.","properties":{"ok":{"type":"boolean","example":true},"job_id":{"type":"string","example":"job_3f2a1b4c"},"offset":{"type":"integer","description":"Primer ítem devuelto, contando desde 0.","example":0},"limit":{"type":"integer","description":"Tope de ítems por página; 200 por defecto, 1000 como máximo.","example":200},"resultados":{"type":"array","description":"Los ítems del trabajo, en el orden en que se enviaron.","items":{"type":"object","title":"Ítem del trabajo","properties":{"idx":{"type":"integer","description":"Posición del ítem en el lote que enviaste, empezando en 0. Es lo que casa cada resultado con su entrada.","example":0},"estado":{"type":"string","enum":["pendiente","ok","error"],"description":"Estado de ESTE ítem, no el del trabajo.","example":"ok"},"error":{"type":["string","null"],"description":"Código del fallo del ítem (`validacion`, `no_encontrado`, `proveedor`, `interno`). `null` si salió bien."},"resultado":{"oneOf":[{"type":"object","title":"Envío de shalom","properties":{"ok":{"type":"boolean","description":"`true` cuando la consulta se resolvió. Un envío que el courier no encuentra responde igualmente 200, con `ok: false`.","example":true},"request_id":{"type":"string","description":"Identificador de esta petición, el mismo que viaja en la cabecera `X-Request-Id`. Cítalo al reportar una incidencia.","example":"req_9505"},"courier":{"type":"string","enum":["shalom"],"description":"Courier consultado.","example":"shalom"},"tracking":{"type":"string","description":"Número de guía u orden, tal y como lo publica el courier.","example":"99999999"},"estado_actual":{"type":["string","null"],"description":"Estado que DECLARA el courier. Si no declara ninguno se usa el del último evento del historial. Los textos son los del courier: no hay un catálogo común entre couriers, así que para decidir en tu código usa `entregado`, no este campo.","example":"ENTREGADO"},"fecha_estado":{"type":["string","null"],"description":"Fecha del último evento del historial, en ISO-8601 con la zona de Lima.","format":"date-time","example":"2026-08-21T17:04:52-05:00"},"entregado":{"type":"boolean","description":"El envío llegó a su destinatario. Sale de la bandera que publica el courier cuando la publica; si no, de que el estado actual sea uno de los terminales.","example":true},"fecha_emision":{"type":["string","null"],"description":"Fecha de emisión de la guía, en ISO-8601 con la zona de Lima. Olva solo publica el día, así que sus envíos salen a las 00:00.","format":"date-time","example":"2026-08-17T13:02:38-05:00"},"contenido":{"type":["string","null"],"description":"Descripción de lo que se envía, tal y como la declaró el remitente.","example":"1 PAQUETE L"},"origen":{"type":["string","null"],"description":"Ciudad o agencia de origen del envío. shalom no publica este dato: viene siempre vacío."},"destino":{"type":["string","null"],"description":"Ciudad o agencia de destino del envío. shalom no publica este dato: viene siempre vacío."},"remitente":{"type":["string","null"],"description":"Quien envía. shalom no publica este dato: viene siempre vacío."},"destinatario":{"type":["string","null"],"description":"Quien recibe."},"historial":{"type":"array","description":"Eventos del envío en orden cronológico ascendente: el último elemento es el más reciente.","items":{"type":"object","title":"Evento del historial","properties":{"fecha":{"type":["string","null"],"description":"Fecha del evento en ISO-8601 con la zona de Lima (-05:00). `null` si el courier la devolvió en un formato que no supimos interpretar.","format":"date-time","example":"2026-08-17T13:02:00-05:00"},"estado":{"type":["string","null"],"description":"Estado del envío en ese momento, en MAYÚSCULAS y sin espacios sobrantes. Los textos son los del courier: no hay un catálogo común entre couriers.","example":"EN TRANSITO"},"sede":{"type":["string","null"],"description":"Sede o agencia donde ocurrió el evento, si el courier la da."},"detalle":{"type":["string","null"],"description":"Observación que el courier adjunta al evento."}},"required":["fecha","estado","sede","detalle"]}},"evidencias":{"type":"array","description":"URLs de las fotos de entrega que publica el courier. shalom no publica ninguna: la lista viene siempre vacía.","items":{"type":"string","format":"uri"}},"detalle":{"type":"object","title":"Detalle de shalom","description":"Campos que publica shalom y no forman parte del contrato común, porque el resto de couriers no los tiene. Las claves son siempre estas y solo estas: lo que el courier no devuelva viaja en `null`.","properties":{"codigo_orden":{"type":["string","null"],"description":"Código alfanumérico del comprobante, el mismo que se envía en la consulta. Viene devuelto para poder casar cada resultado de un lote con su ítem: `tracking` solo trae el número.","example":"ZZZZ"},"ose_id":{"type":["string","null"],"description":"Identificador interno del envío en Shalom. Útil al reportar una incidencia. Shalom lo manda como número; se publica como cadena, igual que `tracking`, porque es un identificador y no una cantidad.","example":"95730181"},"tipo_pago":{"type":["string","null"],"description":"Cómo se paga el servicio, tal y como lo rotula Shalom.","example":"Contra entrega"},"monto":{"type":["string","null"],"description":"Importe del servicio en soles, tal y como lo devuelve Shalom. Se publica como cadena y sin tocar los decimales: convertirlo a número perdería los céntimos exactos que el courier cobra.","example":"20.00"},"fecha_traslado":{"type":["string","null"],"description":"Fecha del traslado, en ISO-8601 con la zona de Lima.","example":"2026-08-17T13:02:00-05:00"},"direccion_entrega":{"type":["string","null"],"description":"Instrucción de reparto que Shalom imprime en el comprobante («ENTREGAR EN AGENCIA», por ejemplo). NO es una dirección postal ni una ciudad: no sirve para deducir el destino del envío.","example":"ENTREGAR EN AGENCIA"},"aereo":{"type":["boolean","null"],"description":"El envío viaja por vía aérea.","example":false},"reparto":{"type":["boolean","null"],"description":"El envío se reparte a domicilio. En falso se recoge en agencia, que es lo que suele decir también `direccion_entrega`.","example":false},"tiene_cambio_destino":{"type":["boolean","null"],"description":"El envío cambió de destino después de emitirse.","example":false},"tiene_devolucion_mercaderia":{"type":["boolean","null"],"description":"La mercadería se devolvió al remitente.","example":false}},"example":{"codigo_orden":"ZZZZ","ose_id":"95730181","tipo_pago":"Contra entrega","monto":"20.00","fecha_traslado":"2026-08-17T13:02:00-05:00","direccion_entrega":"ENTREGAR EN AGENCIA","aereo":false,"reparto":false,"tiene_cambio_destino":false,"tiene_devolucion_mercaderia":false},"required":["codigo_orden","ose_id","tipo_pago","monto","fecha_traslado","direccion_entrega","aereo","reparto","tiene_cambio_destino","tiene_devolucion_mercaderia"]},"cached":{"type":"boolean","description":"La respuesta se sirvió de nuestra caché en vez de consultar al courier. Se cobra igual, y el dato tiene como mucho unos minutos.","example":false},"raw":{"type":["object","null"],"description":"La respuesta cruda del courier, SOLO si pides `?raw=true`. Su forma la decide el courier y puede cambiar sin aviso: no es parte del contrato.","additionalProperties":true}},"required":["ok","request_id","courier","tracking","estado_actual","fecha_estado","entregado","fecha_emision","contenido","origen","destino","remitente","destinatario","historial","evidencias","detalle","cached","raw"]},{"type":"object","title":"Ítem no resuelto","description":"El ítem no se pudo resolver. El motivo va en el `error` del ítem, no aquí; `mensaje` solo aparece cuando el fallo trae uno.","properties":{"ok":{"type":"boolean","enum":[false],"example":false},"mensaje":{"type":["string","null"],"description":"Detalle del fallo, cuando lo hay."}},"required":["ok"]},{"type":"null"}],"description":"El envío resuelto, el motivo de que no lo esté, o `null` si el ítem todavía no se ha procesado. Distínguelos por `ok`."}},"required":["idx","estado","error","resultado"]}}},"required":["ok","job_id","offset","limit","resultados"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"**Datos personales.** La respuesta de este endpoint identifica a una persona. Consúltala solo con una finalidad que puedas sustentar ante su titular, no la conserves más de lo que esa finalidad necesite y trátala conforme a la normativa peruana de protección de datos personales."}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token de API con formato `ldx_live_...`. Se obtiene en https://ldxsoftware.com.pe/apis/cuenta y se envía como `Authorization: Bearer <token>`."}}},"security":[{"bearerAuth":[]}]}