{"openapi":"3.1.0","info":{"title":"LDX Consultas API — olva","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/olva/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__olva__tracking_get","parameters":[{"name":"guia","in":"query","required":true,"description":"Número de guía (tracking) impreso en el comprobante de Olva. Solo dígitos.","example":"9999999","schema":{"type":"string","pattern":"^[0-9]{1,15}$"}},{"name":"emision","in":"query","required":false,"description":"Año de emisión de la guía en dos dígitos (23 = 2023). Si se omite se asume 26: una guía emitida otro año no se encontrará.","example":"23","schema":{"type":"string","pattern":"^[0-9]{1,3}$","default":"26"}},{"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 olva","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":["olva"],"description":"Courier consultado.","example":"olva"},"tracking":{"type":"string","description":"Número de guía u orden, tal y como lo publica el courier.","example":"9999999"},"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."},"destino":{"type":["string","null"],"description":"Ciudad o agencia de destino del envío."},"remitente":{"type":["string","null"],"description":"Quien envía."},"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.","items":{"type":"string","format":"uri"}},"detalle":{"type":"object","title":"Detalle de olva","description":"Campos que publica olva 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":{"emision":{"type":["string","null"],"description":"Año de emisión de la guía, 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 de guía.","example":"23"},"id_envio":{"type":["string","null"],"description":"Identificador interno del envío en Olva. Útil al reportar una incidencia; es también el id con el que Olva indexa las fotos.","example":"137220572"},"peso":{"type":["string","null"],"description":"Peso declarado en kilogramos, tal y como lo devuelve Olva. Se publica como cadena, sin tocar los decimales.","example":"4.60"},"cantidad":{"type":["string","null"],"description":"Número de piezas que componen el envío.","example":"1"},"nombre_oficina":{"type":["string","null"],"description":"Oficina de Olva asociada al envío, con su dirección.","example":"OLVA EJEMPLO - AV. LOS EJEMPLOS 1427"}},"example":{"emision":"23","id_envio":"137220572","peso":"4.60","cantidad":"1","nombre_oficina":"OLVA EJEMPLO - AV. LOS EJEMPLOS 1427"},"required":["emision","id_envio","peso","cantidad","nombre_oficina"]},"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/olva/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__olva__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 olva","properties":{"guia":{"type":"string","pattern":"^[0-9]{1,15}$","description":"Número de guía (tracking) impreso en el comprobante de Olva. Solo dígitos.","example":"9999999"},"emision":{"type":"string","pattern":"^[0-9]{1,3}$","description":"Año de emisión de la guía en dos dígitos (23 = 2023). Si se omite se asume 26: una guía emitida otro año no se encontrará.","example":"23","default":"26"}},"example":{"guia":"9999999","emision":"23"},"required":["guia"]},"description":"Hasta 25 envíos por petición. Para volúmenes mayores, POST /v1/batch/jobs."}},"example":{"items":[{"guia":"9999999","emision":"23"}]}}}}},"responses":{"200":{"description":"Un resultado por ítem enviado.","content":{"application/json":{"schema":{"type":"object","title":"Lote de olva","properties":{"ok":{"type":"boolean","example":true},"request_id":{"type":"string","example":"req_9505"},"courier":{"type":"string","enum":["olva"],"example":"olva"},"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 olva","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":["olva"],"description":"Courier consultado.","example":"olva"},"tracking":{"type":"string","description":"Número de guía u orden, tal y como lo publica el courier.","example":"9999999"},"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."},"destino":{"type":["string","null"],"description":"Ciudad o agencia de destino del envío."},"remitente":{"type":["string","null"],"description":"Quien envía."},"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.","items":{"type":"string","format":"uri"}},"detalle":{"type":"object","title":"Detalle de olva","description":"Campos que publica olva 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":{"emision":{"type":["string","null"],"description":"Año de emisión de la guía, 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 de guía.","example":"23"},"id_envio":{"type":["string","null"],"description":"Identificador interno del envío en Olva. Útil al reportar una incidencia; es también el id con el que Olva indexa las fotos.","example":"137220572"},"peso":{"type":["string","null"],"description":"Peso declarado en kilogramos, tal y como lo devuelve Olva. Se publica como cadena, sin tocar los decimales.","example":"4.60"},"cantidad":{"type":["string","null"],"description":"Número de piezas que componen el envío.","example":"1"},"nombre_oficina":{"type":["string","null"],"description":"Oficina de Olva asociada al envío, con su dirección.","example":"OLVA EJEMPLO - AV. LOS EJEMPLOS 1427"}},"example":{"emision":"23","id_envio":"137220572","peso":"4.60","cantidad":"1","nombre_oficina":"OLVA EJEMPLO - AV. LOS EJEMPLOS 1427"},"required":["emision","id_envio","peso","cantidad","nombre_oficina"]},"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/olva/agencias":{"get":{"tags":["consultas"],"summary":"Agencias de Olva","description":"Padrón de agencias de Olva Courier en todo el Perú: dirección, distrito, ubigeo, coordenadas, horario de atención día por día y si está abierta en este momento. Se puede filtrar por departamento y provincia, o buscar por cualquier campo.","operationId":"operacion_agencias_consultas_v1__olva__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, ubigeo y tipo de local; «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 Olva 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 Olva 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 12 campos de cada agencia; «minimo» quita el ubigeo y el horario día por día —el horario solo es el 51 % del peso de cada registro— y deja identificación, ubicación, coordenadas y `abierta`, 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 432, 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 olva","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":["olva"],"description":"Servicio consultado.","example":"olva"},"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 olva","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, ubigeo y tipo de local; «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 Olva 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 Olva se rechaza en vez de devolver la lista vacía.","example":""},"detalle":{"type":"string","description":"«completo» devuelve los 12 campos de cada agencia; «minimo» quita el ubigeo y el horario día por día —el horario solo es el 51 % del peso de cada registro— y deja identificación, ubicación, coordenadas y `abierta`, para listados y mapas.","example":"completo"},"limite":{"type":"string","description":"Cuántas agencias devolver, de 1 a 1000. El padrón entero son 432, 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 olva","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":1},"mostradas":{"type":["integer","null"],"description":"Agencias que trae esta página.","example":1},"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"},"momento":{"type":["string","null"],"description":"Instante en hora de Perú con el que se calculó `abierta` en cada agencia de esta respuesta.","example":"2026-08-25T09:30:00-05:00"},"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 Olva.","example":579},"nombre":{"type":["string","null"],"description":"Rótulo del local tal y como lo lista Olva. Suele llevar la dirección dentro; la dirección limpia va en su propio campo.","example":"TIENDA CHACHAPOYAS - JR. ORTIZ ARRIETA Nº 270 S/N"},"tipo":{"type":["string","null"],"description":"Qué clase de local es: «AGENTE» es un negocio de terceros que trabaja con Olva; «OFICINA OPERACIONES», «OFICINAS EXTERNAS» y «OFICINA IN HOUSE» son de la propia Olva. En el volcado se llama `office_type`.","example":"OFICINAS EXTERNAS"},"departamento":{"type":["string","null"],"description":"Departamento.","example":"AMAZONAS"},"provincia":{"type":["string","null"],"description":"Provincia.","example":"CHACHAPOYAS"},"distrito":{"type":["string","null"],"description":"Distrito.","example":"CHACHAPOYAS"},"ubigeo":{"type":["string","null"],"description":"Ubigeo del INEI, seis dígitos. Los códigos de departamento, provincia y distrito son sus tres pares (`010101` = 01 / 01 / 01), así que no se publican por separado. Solo con `detalle=completo`.","example":"010101"},"direccion":{"type":["string","null"],"description":"Dirección del local, con la referencia cuando Olva la da.","example":"JR. ORTIZ ARRIETA Nº 270 S/N"},"latitud":{"type":["number","null"],"description":"Latitud en grados decimales. Null si Olva no la publica o si el par de coordenadas no cae dentro del Perú.","example":-6.226970099021466},"longitud":{"type":["number","null"],"description":"Longitud en grados decimales.","example":-77.87291566856221},"abierta":{"type":["boolean","null"],"description":"Si el horario publicado cubre este momento, en hora de Perú (UTC-5); el instante usado viaja en `momento`. NO sabe de feriados ni de cierres imprevistos, y da `false` cuando Olva no publica horario ese día o cuando el rango termina antes de empezar (12 rangos en 4 agencias, que se publican tal y como Olva los da).","example":true},"horario":{"type":["object","null"],"description":"Atención de cada día de la semana, en hora local. Solo con `detalle=completo`.","properties":{"lunes":{"type":["object","null"],"description":"Atención del lunes. Los dos valores en `null` significan que Olva no publica atención ese día —no se puede distinguir de «cierra»—; los domingos vienen así en las 432 agencias.","properties":{"inicio":{"type":["string","null"],"description":"Hora de apertura, HH:MM:SS.","example":"08:00:00"},"fin":{"type":["string","null"],"description":"Hora de cierre, HH:MM:SS.","example":"19:00:00"}},"required":["inicio","fin"],"example":{"inicio":"08:00:00","fin":"19:00:00"}},"martes":{"type":["object","null"],"description":"Atención del martes. Los dos valores en `null` significan que Olva no publica atención ese día —no se puede distinguir de «cierra»—; los domingos vienen así en las 432 agencias.","properties":{"inicio":{"type":["string","null"],"description":"Hora de apertura, HH:MM:SS.","example":"08:00:00"},"fin":{"type":["string","null"],"description":"Hora de cierre, HH:MM:SS.","example":"19:00:00"}},"required":["inicio","fin"],"example":{"inicio":"08:00:00","fin":"19:00:00"}},"miercoles":{"type":["object","null"],"description":"Atención del miercoles. Los dos valores en `null` significan que Olva no publica atención ese día —no se puede distinguir de «cierra»—; los domingos vienen así en las 432 agencias.","properties":{"inicio":{"type":["string","null"],"description":"Hora de apertura, HH:MM:SS.","example":"08:00:00"},"fin":{"type":["string","null"],"description":"Hora de cierre, HH:MM:SS.","example":"19:00:00"}},"required":["inicio","fin"],"example":{"inicio":"08:00:00","fin":"19:00:00"}},"jueves":{"type":["object","null"],"description":"Atención del jueves. Los dos valores en `null` significan que Olva no publica atención ese día —no se puede distinguir de «cierra»—; los domingos vienen así en las 432 agencias.","properties":{"inicio":{"type":["string","null"],"description":"Hora de apertura, HH:MM:SS.","example":"08:00:00"},"fin":{"type":["string","null"],"description":"Hora de cierre, HH:MM:SS.","example":"19:00:00"}},"required":["inicio","fin"],"example":{"inicio":"08:00:00","fin":"19:00:00"}},"viernes":{"type":["object","null"],"description":"Atención del viernes. Los dos valores en `null` significan que Olva no publica atención ese día —no se puede distinguir de «cierra»—; los domingos vienen así en las 432 agencias.","properties":{"inicio":{"type":["string","null"],"description":"Hora de apertura, HH:MM:SS.","example":"08:00:00"},"fin":{"type":["string","null"],"description":"Hora de cierre, HH:MM:SS.","example":"19:00:00"}},"required":["inicio","fin"],"example":{"inicio":"08:00:00","fin":"19:00:00"}},"sabado":{"type":["object","null"],"description":"Atención del sabado. Los dos valores en `null` significan que Olva no publica atención ese día —no se puede distinguir de «cierra»—; los domingos vienen así en las 432 agencias.","properties":{"inicio":{"type":["string","null"],"description":"Hora de apertura, HH:MM:SS.","example":"08:00:00"},"fin":{"type":["string","null"],"description":"Hora de cierre, HH:MM:SS.","example":"14:30:00"}},"required":["inicio","fin"],"example":{"inicio":"08:00:00","fin":"14:30:00"}},"domingo":{"type":["object","null"],"description":"Atención del domingo. Los dos valores en `null` significan que Olva no publica atención ese día —no se puede distinguir de «cierra»—; los domingos vienen así en las 432 agencias.","properties":{"inicio":{"type":["string","null"],"description":"Hora de apertura, HH:MM:SS."},"fin":{"type":["string","null"],"description":"Hora de cierre, HH:MM:SS."}},"required":["inicio","fin"],"example":{"inicio":null,"fin":null}}},"required":["lunes","martes","miercoles","jueves","viernes","sabado","domingo"],"example":{"lunes":{"inicio":"08:00:00","fin":"19:00:00"},"martes":{"inicio":"08:00:00","fin":"19:00:00"},"miercoles":{"inicio":"08:00:00","fin":"19:00:00"},"jueves":{"inicio":"08:00:00","fin":"19:00:00"},"viernes":{"inicio":"08:00:00","fin":"19:00:00"},"sabado":{"inicio":"08:00:00","fin":"14:30:00"},"domingo":{"inicio":null,"fin":null}}}},"required":["id","nombre","tipo","departamento","provincia","distrito","direccion","latitud","longitud","abierta"]},"example":[{"id":579,"nombre":"TIENDA CHACHAPOYAS - JR. ORTIZ ARRIETA Nº 270 S/N","tipo":"OFICINAS EXTERNAS","departamento":"AMAZONAS","provincia":"CHACHAPOYAS","distrito":"CHACHAPOYAS","ubigeo":"010101","direccion":"JR. ORTIZ ARRIETA Nº 270 S/N","latitud":-6.226970099021466,"longitud":-77.87291566856221,"abierta":true,"horario":{"lunes":{"inicio":"08:00:00","fin":"19:00:00"},"martes":{"inicio":"08:00:00","fin":"19:00:00"},"miercoles":{"inicio":"08:00:00","fin":"19:00:00"},"jueves":{"inicio":"08:00:00","fin":"19:00:00"},"viernes":{"inicio":"08:00:00","fin":"19:00:00"},"sabado":{"inicio":"08:00:00","fin":"14:30:00"},"domingo":{"inicio":null,"fin":null}}}]}},"required":["total","mostradas","pagina","limite","actualizado","momento","agencias"],"example":{"total":1,"mostradas":1,"pagina":1,"limite":100,"actualizado":"2026-08-25","momento":"2026-08-25T09:30:00-05:00","agencias":[{"id":579,"nombre":"TIENDA CHACHAPOYAS - JR. ORTIZ ARRIETA Nº 270 S/N","tipo":"OFICINAS EXTERNAS","departamento":"AMAZONAS","provincia":"CHACHAPOYAS","distrito":"CHACHAPOYAS","ubigeo":"010101","direccion":"JR. ORTIZ ARRIETA Nº 270 S/N","latitud":-6.226970099021466,"longitud":-77.87291566856221,"abierta":true,"horario":{"lunes":{"inicio":"08:00:00","fin":"19:00:00"},"martes":{"inicio":"08:00:00","fin":"19:00:00"},"miercoles":{"inicio":"08:00:00","fin":"19:00:00"},"jueves":{"inicio":"08:00:00","fin":"19:00:00"},"viernes":{"inicio":"08:00:00","fin":"19:00:00"},"sabado":{"inicio":"08:00:00","fin":"14:30:00"},"domingo":{"inicio":null,"fin":null}}}]}},"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":["olva"],"example":"olva","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 olva","properties":{"guia":{"type":"string","pattern":"^[0-9]{1,15}$","description":"Número de guía (tracking) impreso en el comprobante de Olva. Solo dígitos.","example":"9999999"},"emision":{"type":"string","pattern":"^[0-9]{1,3}$","description":"Año de emisión de la guía en dos dígitos (23 = 2023). Si se omite se asume 26: una guía emitida otro año no se encontrará.","example":"23","default":"26"}},"example":{"guia":"9999999","emision":"23"},"required":["guia"]},"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":"olva","items":[{"guia":"9999999","emision":"23"}]}}}}},"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 olva","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":["olva"],"description":"Courier consultado.","example":"olva"},"tracking":{"type":"string","description":"Número de guía u orden, tal y como lo publica el courier.","example":"9999999"},"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."},"destino":{"type":["string","null"],"description":"Ciudad o agencia de destino del envío."},"remitente":{"type":["string","null"],"description":"Quien envía."},"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.","items":{"type":"string","format":"uri"}},"detalle":{"type":"object","title":"Detalle de olva","description":"Campos que publica olva 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":{"emision":{"type":["string","null"],"description":"Año de emisión de la guía, 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 de guía.","example":"23"},"id_envio":{"type":["string","null"],"description":"Identificador interno del envío en Olva. Útil al reportar una incidencia; es también el id con el que Olva indexa las fotos.","example":"137220572"},"peso":{"type":["string","null"],"description":"Peso declarado en kilogramos, tal y como lo devuelve Olva. Se publica como cadena, sin tocar los decimales.","example":"4.60"},"cantidad":{"type":["string","null"],"description":"Número de piezas que componen el envío.","example":"1"},"nombre_oficina":{"type":["string","null"],"description":"Oficina de Olva asociada al envío, con su dirección.","example":"OLVA EJEMPLO - AV. LOS EJEMPLOS 1427"}},"example":{"emision":"23","id_envio":"137220572","peso":"4.60","cantidad":"1","nombre_oficina":"OLVA EJEMPLO - AV. LOS EJEMPLOS 1427"},"required":["emision","id_envio","peso","cantidad","nombre_oficina"]},"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":[]}]}