# Shalom API — referencia completa API para operar cuentas Shalom Pro (courier Shalom, Perú): crear guías, cotizar, agencias, rastreo, avisos por webhook, pendientes, ticket y rótulo, y autogestión. Un producto de SmartFlow Solutions. Autenticación: cabecera `x-api-key: sk_...`. Respuestas: `{ ok: true, data }` o `{ ok: false, codigo_error, error }`. Llave gratis en el panel: https://shalom.smartflow.pe/panel/registro (prueba de 14 días o 30 guías, lo que pase primero; 300 consultas al día). Planes de pago: guías y consultas ilimitadas, solo con freno por minuto. Códigos de plan y límites: `402 PRUEBA_TERMINADA` (terminó la prueba), `402 PLAN_VENCIDO` (venció el plan), `402 SIN_CREDITOS` (sin guías de prueba), `403 LIMITE_PLAN` / `PLAN_NO_INCLUYE` (tu plan no permite más cuentas Shalom, llaves o guías suscritas), `429 LIMITE` (freno por minuto, ver `Retry-After`), `429 LIMITE_DIA` (tope diario de la prueba). `GET /v1/yo` siempre responde, aun con la prueba terminada. Base: https://shalom.smartflow.pe. Autenticación: cabecera x-api-key: sk_… (o Authorization: Bearer sk_…), salvo las rutas marcadas "sin llave". Respuesta correcta: { "ok": true, "data": … }. Error: { "ok": false, "codigo_error": "…", "error": "…" } (decide por codigo_error, no por el texto). Códigos de error frecuentes: DATOS 400, SIN_LLAVE/LLAVE_INVALIDA 401, NO_EXISTE 404, REFERENCIA_OCUPADA/POSIBLE_DUPLICADO/EN_CURSO 409, CREDENCIALES/SIN_TARIFA/SHALOM_RECHAZO 422, LIMITE 429, OCUPADO/SHALOM_NO_DISPONIBLE 503, TIMEOUT 504. Guías sin duplicados: POST /v1/guias exige "referencia" (id del envío en tu sistema); repetirla con los mismos datos devuelve la misma guía (ya_existia: true). Webhooks: PUT /v1/webhook {url} devuelve el secreto whsec_… una vez; cada aviso es POST JSON { evento, guia, estado, estado_anterior, fecha, referencia } con x-shalom-evento (id único) y x-shalom-firma: t=,v1=. ## Cuenta ### GET /v1/yo Datos del cliente, plan (prueba, vencimiento, guías de prueba restantes) y consumo. Responde aun con la prueba terminada. ## Cuentas Shalom ### GET /v1/cuentas Lista las cuentas Shalom Pro conectadas ### POST /v1/cuentas Conecta una cuenta Shalom Pro (email + password; se guarda cifrada y se prueba el inicio de sesión) ### GET /v1/cuentas/{id} Ver una cuenta ### PUT /v1/cuentas/{id} Cambiar email, clave o nombre (se vuelve a probar) ### DELETE /v1/cuentas/{id} Desconectar la cuenta (borra la clave guardada) ### POST /v1/cuentas/{id}/probar Probar el inicio de sesión en Shalom ## Consultas ### GET /v1/agencias Agencias Shalom con filtros y cercanía Catálogo en caché 3 h por cuenta; coordenadas tomadas de /api/listar-mapa-info. Parámetros: - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). - q (query, string): Texto libre (nombre, distrito, dirección…), sin importar tildes ni mayúsculas. - departamento (query, string): Nombre, sin importar mayúsculas ni tildes. - provincia (query, string): Nombre. - distrito (query, string): Nombre. - solo_destino (query, "0" | "1"): 1 = solo agencias que reciben envíos. - aereo (query, "0" | "1"): 1 = solo aéreas, 0 = solo no aéreas. - cerca (query, string): "latitud,longitud". Agrega distancia_km y ordena de más cerca a más lejos. - radio_km (query, number): Radio para "cerca" (por defecto 10, máximo 2000). - con_restricciones (query, "0" | "1"): 1 = incluye límites de peso y volumen por agencia. Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### GET /v1/agencias/{id} Una agencia (con restricciones) Parámetros: - id (path, string, obligatorio): Id de la agencia (acepta también el aereo_id "0"+id). - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### GET /v1/ubicaciones/departamentos Departamentos Parámetros: - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### GET /v1/ubicaciones/provincias Provincias de un departamento (por nombre) Parámetros: - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). - departamento (query, string, obligatorio): Nombre del departamento, ej. LIMA. Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### GET /v1/ubicaciones/distritos Distritos de una provincia (por nombre) Parámetros: - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). - provincia (query, string, obligatorio): Nombre de la provincia, ej. LIMA. Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### GET /v1/productos Productos (tamaños) con medidas y peso estándar Parámetros: - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### POST /v1/cotizar Cotizar una ruta Sin producto ni medidas: precio de cada producto. Con producto: su precio. Con medidas (o producto OTRA MEDIDA): precio de "otra medida" (peso o las tres medidas obligatorias). Cuerpo JSON: - cuenta_id (string, obligatorio) - origen_id (integer, obligatorio) - destino_id (integer, obligatorio) - producto (string): SOBRE, PAQUETE XXS, PAQUETE XS, PAQUETE S, PAQUETE M, PAQUETE L, OTRA MEDIDA (o su id). - alto (number): metros - ancho (number): metros - largo (number): metros - peso (number): kg - aereo (boolean): Cotiza el destino por avión. Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### GET /v1/dni/{numero} Nombres y apellidos de un DNI Parámetros: - numero (path, string, obligatorio) - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### GET /v1/perfil Remitente de la cuenta y estado del cobro seguro Parámetros: - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ## Después de crear ### GET /v1/guias/{referencia}/ticket Ticket en PDF Parámetros: - referencia (path, string, obligatorio): Tu referencia (la de POST /v1/guias) o el ose_id de Shalom (solo dígitos). Si existe una referencia propia con ese valor, manda la referencia. - cuenta_id (query, string): Id de la cuenta Shalom Pro. Opcional si :referencia es una referencia propia (se usa la cuenta con la que se creó la guía). - descargar (query, string): 1 = Content-Disposition attachment (por defecto inline). Respuestas: 200 PDF (bytes que empiezan con %PDF). · 400 · 401 · 404 · 409 · 422 · 504 ### GET /v1/guias/{referencia}/rotulo Rótulo en PDF Parámetros: - referencia (path, string, obligatorio): Tu referencia (la de POST /v1/guias) o el ose_id de Shalom (solo dígitos). Si existe una referencia propia con ese valor, manda la referencia. - cuenta_id (query, string): Id de la cuenta Shalom Pro. Opcional si :referencia es una referencia propia (se usa la cuenta con la que se creó la guía). - descargar (query, string): 1 = Content-Disposition attachment. Respuestas: 200 PDF (bytes que empiezan con %PDF). · 400 · 401 · 404 · 409 · 422 · 504 ### GET /v1/pendientes Guías pendientes (aún no entregadas en agencia) Parámetros: - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). - pagina (query, integer): Página (desde 1). - desde (query, string): AAAA-MM-DD - hasta (query, string): AAAA-MM-DD - tipo_documento (query, string): DNI, RUC, CE, PS. - documento (query, string): Documento del destinatario. - cobro_seguro (query, "0" | "1"): 1 / 0 Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### DELETE /v1/pendientes/{id} Anular una pendiente Si la guía es tuya (creada con POST /v1/guias), queda con estado "anulada". Parámetros: - id (path, string, obligatorio): ose_id de Shalom de la guía pendiente. - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### POST /v1/pendientes/anular Anular varias pendientes Cuerpo JSON: - cuenta_id (string, obligatorio) - ids (string | integer[], obligatorio): ose_id de Shalom. Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### POST /v1/pendientes/{id}/clave Cambiar la clave de una pendiente Parámetros: - id (path, string, obligatorio): ose_id de Shalom de la guía pendiente. Cuerpo JSON: - cuenta_id (string, obligatorio) - clave (string, obligatorio): 4 dígitos; no los 4 iguales (0000, 1111…), ni series que suben (1234…) o bajan (4321…). Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### POST /v1/pendientes/clave Cambiar la clave de varias pendientes Cuerpo JSON: - cuenta_id (string, obligatorio) - ids (string | integer[], obligatorio): ose_id de Shalom. - clave (string, obligatorio): 4 dígitos; no los 4 iguales (0000, 1111…), ni series que suben (1234…) o bajan (4321…). Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ### POST /v1/pendientes/{id}/clonar Clonar una pendiente: devuelve su envío listo para POST /v1/guias (no crea nada en Shalom) Parámetros: - id (path, string, obligatorio): ose_id de Shalom de la guía pendiente. Cuerpo JSON: - cuenta_id (string, obligatorio) Respuestas: 200 Correcto · 400 · 401 · 404 · 422 · 504 ## Guías ### GET /v1/guias Listar guías Parámetros: - estado (query, "en_curso" | "creada" | "fallida" | "incierta") - cuenta_id (query, string) - desde (query, string) - hasta (query, string) - pagina (query, integer) - por_pagina (query, integer) Respuestas: 200 Página de guías. ### POST /v1/guias Crear una guía (con todas las opciones del registro individual) Idempotente por `referencia`: si ya hay una guía creada con esa referencia se devuelve esa (200, ya_existia) y no se crea otra. Los datos se validan antes de tocar Shalom. Las guías de una misma cuenta se registran de a una. Cuerpo JSON: - cuenta_id (string, obligatorio): Cuenta Shalom Pro del cliente (cta_…). - referencia (string, obligatorio): Id del envío en tu sistema; evita guías repetidas. - envio (object, obligatorio): Datos del envío. Se validan TODOS antes de llamar a Shalom; si algo está mal responde 400 DATOS con la lista completa. - documento (string, obligatorio): Documento del destinatario: DNI (8 números), RUC (11 números; empresa: basta `nombres` con la razón social), CE o pasaporte (8 a 12 letras o números). - telefono (string, obligatorio): Celular del destinatario: 9 números empezando con 9 (se aceptan espacios y el prefijo 51). - nombres (string): Solo si el documento no está registrado en la cuenta Shalom y Shalom no encuentra su nombre. - apellido_paterno (string) - apellido_materno (string) - origen_ter_id (integer, obligatorio): Agencia de origen (ter_id de Shalom). - destino_ter_id (integer, obligatorio): Agencia de destino (ter_id). Si aereo=true se envía a Shalom como "0"+ter_id. - producto ("SOBRE" | "PAQUETE XXS" | "PAQUETE XS" | "PAQUETE S" | "PAQUETE M" | "PAQUETE L" | "OTRA MEDIDA", por defecto "PAQUETE L"): Tamaño. OTRA MEDIDA exige peso, alto, ancho y largo; su precio es el que calcula Shalom (data.price). - peso (number): kg. Obligatorio con OTRA MEDIDA; en los demás, si falta se usa el estándar del tamaño. - alto (number): metros (igual en ancho y largo). - ancho (number) - largo (number) - cantidad (integer, por defecto 1): Número de bultos. - clave (string): Clave de recojo de 4 números. Se rechazan todos iguales (0000, 1111…) y seguidos subiendo o bajando (1234, 4321…). Si no viene, se genera una válida y se devuelve. - garantia (object): Garantía. La prima la calcula el servicio: productos fijos ≤ S/ 1 000 → S/ 5; > S/ 1 000 → 0,5 %; OTRA MEDIDA → 1 %; redondeo hacia arriba al céntimo. - valor_declarado (number, obligatorio): Valor de la mercadería en soles (máx. 40 000). - cobro_seguro (object): Cobro seguro (contraentrega). La cuenta debe tenerlo afiliado en Shalom: se verifica antes de crear. - monto (number, obligatorio): Soles a cobrar al destinatario (máx. 2 000). - aereo (boolean, por defecto false): Envío aéreo. Exige declaracion_jurada y al menos una guía de remisión; solo persona natural (no RUC). - declaracion_jurada ("Articulos de uso personal" | "Documentos" | "Ropa" | "Electrodomesticos"): Solo con aereo=true. Se acepta con o sin tildes y en cualquier mayúscula. - contacto_extra (object): Otra persona autorizada a recoger. Se registra en la cuenta Shalom si no existe. - documento (string, obligatorio): DNI (8), CE (9) o pasaporte (12). Distinto del destinatario. - nombres (string, obligatorio) - apellido_paterno (string, obligatorio) - apellido_materno (string) - telefono (string, obligatorio): 9 números empezando con 9. - guias_remision (object[]): Guías de remisión (GRR) que acompañan la carga. - serie (string, obligatorio) - numero (string | integer, obligatorio): 1 a 8 números. - forzar (boolean, por defecto false): Reintentar una referencia en estado incierta (revisa antes los pendientes en Shalom). Ejemplo de cuerpo: ```json { "cuenta_id": "cta_123", "referencia": "PED-1001", "envio": { "documento": "11111111", "telefono": "987654321", "origen_ter_id": 219, "destino_ter_id": 543, "producto": "OTRA MEDIDA", "peso": 3, "alto": 0.4, "ancho": 0.3, "largo": 0.5, "cantidad": 1, "clave": "4825", "garantia": { "valor_declarado": 1500 }, "cobro_seguro": { "monto": 150 }, "contacto_extra": { "documento": "33333333", "nombres": "RITA", "apellido_paterno": "LOZA", "apellido_materno": "VEGA", "telefono": "912345678" }, "guias_remision": [ { "serie": "T001", "numero": "123" } ] } } ``` Respuestas: 200 La referencia ya tenía guía (ya_existia: true). No se creó otra. · 201 Guía creada. · 400 DATOS: faltan datos o no son válidos (lista completa en `errores`). No se llamó a Shalom ni se guardó la referencia. · 404 NO_EXISTE: la cuenta no existe. · 409 EN_CURSO (se está registrando ahora) o POSIBLE_DUPLICADO (intento anterior sin respuesta: usar forzar). · 422 Shalom rechazó o no se pudo crear (SHALOM_RECHAZO, SIN_TARIFA, DNI_SIN_NOMBRE, CREDENCIALES, TIMEOUT…). `data` trae la guía con estado fallida o incierta. ### GET /v1/guias/{referencia} Ver una guía por su referencia Parámetros: - referencia (path, string, obligatorio) Respuestas: 200 La guía. · 404 NO_EXISTE. ### POST /v1/guias/lote Crear varias guías (máx. 100) Se procesan de a uno y en orden con la misma lógica que POST /v1/guias (idempotencia por referencia y validación previa). Si uno falla se sigue con los demás. Si la cuenta tiene la clave equivocada, el resto no se intenta (codigo_error CREDENCIALES). La respuesta llega al terminar todo el lote: cuenta unos segundos por envío. Cuerpo JSON: - cuenta_id (string, obligatorio) - envios (object[], obligatorio) - referencia (string, obligatorio): Única dentro del lote. - envio (object, obligatorio): Datos del envío. Se validan TODOS antes de llamar a Shalom; si algo está mal responde 400 DATOS con la lista completa. - documento (string, obligatorio): Documento del destinatario: DNI (8 números), RUC (11 números; empresa: basta `nombres` con la razón social), CE o pasaporte (8 a 12 letras o números). - telefono (string, obligatorio): Celular del destinatario: 9 números empezando con 9 (se aceptan espacios y el prefijo 51). - nombres (string): Solo si el documento no está registrado en la cuenta Shalom y Shalom no encuentra su nombre. - apellido_paterno (string) - apellido_materno (string) - origen_ter_id (integer, obligatorio): Agencia de origen (ter_id de Shalom). - destino_ter_id (integer, obligatorio): Agencia de destino (ter_id). Si aereo=true se envía a Shalom como "0"+ter_id. - producto ("SOBRE" | "PAQUETE XXS" | "PAQUETE XS" | "PAQUETE S" | "PAQUETE M" | "PAQUETE L" | "OTRA MEDIDA", por defecto "PAQUETE L"): Tamaño. OTRA MEDIDA exige peso, alto, ancho y largo; su precio es el que calcula Shalom (data.price). - peso (number): kg. Obligatorio con OTRA MEDIDA; en los demás, si falta se usa el estándar del tamaño. - alto (number): metros (igual en ancho y largo). - ancho (number) - largo (number) - cantidad (integer, por defecto 1): Número de bultos. - clave (string): Clave de recojo de 4 números. Se rechazan todos iguales (0000, 1111…) y seguidos subiendo o bajando (1234, 4321…). Si no viene, se genera una válida y se devuelve. - garantia (object): Garantía. La prima la calcula el servicio: productos fijos ≤ S/ 1 000 → S/ 5; > S/ 1 000 → 0,5 %; OTRA MEDIDA → 1 %; redondeo hacia arriba al céntimo. - valor_declarado (number, obligatorio): Valor de la mercadería en soles (máx. 40 000). - cobro_seguro (object): Cobro seguro (contraentrega). La cuenta debe tenerlo afiliado en Shalom: se verifica antes de crear. - monto (number, obligatorio): Soles a cobrar al destinatario (máx. 2 000). - aereo (boolean, por defecto false): Envío aéreo. Exige declaracion_jurada y al menos una guía de remisión; solo persona natural (no RUC). - declaracion_jurada ("Articulos de uso personal" | "Documentos" | "Ropa" | "Electrodomesticos"): Solo con aereo=true. Se acepta con o sin tildes y en cualquier mayúscula. - contacto_extra (object): Otra persona autorizada a recoger. Se registra en la cuenta Shalom si no existe. - documento (string, obligatorio): DNI (8), CE (9) o pasaporte (12). Distinto del destinatario. - nombres (string, obligatorio) - apellido_paterno (string, obligatorio) - apellido_materno (string) - telefono (string, obligatorio): 9 números empezando con 9. - guias_remision (object[]): Guías de remisión (GRR) que acompañan la carga. - serie (string, obligatorio) - numero (string | integer, obligatorio): 1 a 8 números. - forzar (boolean, por defecto false) Respuestas: 200 Lote procesado (aunque algunos hayan fallado). · 400 DATOS: lista vacía, más de 100, o referencias faltantes/repetidas. No se procesó nada. · 404 NO_EXISTE: la cuenta no existe. ## Públicas (sin llave) Agencias Shalom sin llave de API. Límite: 30 consultas por minuto por IP (429 LIMITE + Retry-After). Respuestas en caché 5 min. ### GET /v1/publico/agencias (sin llave) Todas las agencias Shalom (sin llave) Catálogo público de agencias, con los mismos filtros opcionales que /buscar. Sin datos internos: solo id, nombre, ubicación, dirección, horario, teléfono, si recibe o envía, aéreo y coordenadas. Si el catálogo aún no está cargado responde 503 SHALOM_NO_DISPONIBLE: reintenta en unos minutos. Parámetros: - q (query, string): Texto libre (nombre, distrito, dirección…), sin importar tildes ni mayúsculas. - departamento (query, string): Nombre del departamento (ej. LIMA). - provincia (query, string) - distrito (query, string) - lat (query, number): Latitud (ej. -12.0464). Va con lng. - lng (query, number): Longitud (ej. -77.0428). - radio_km (query, number) - solo_destino (query, "0" | "1"): 1 = solo agencias que reciben envíos. - limite (query, integer): Máximo de agencias a devolver (en /buscar, 50 por defecto). Respuestas: 200 Agencias · 400 Filtro inválido (DATOS) · 429 Límite por IP (LIMITE). Mira la cabecera Retry-After. · 503 Catálogo cargándose (SHALOM_NO_DISPONIBLE) ### GET /v1/publico/agencias/buscar (sin llave) Buscar agencias por texto, ubicación o cercanía (sin llave) Exige al menos un filtro: q, departamento, provincia, distrito o lat+lng. Con lat+lng agrega distancia_km y ordena de más cerca a más lejos (solo agencias con coordenadas en Shalom). Por defecto devuelve 50 (limite hasta 1000); total dice cuántas coinciden. Parámetros: - q (query, string): Texto libre (nombre, distrito, dirección…), sin importar tildes ni mayúsculas. - departamento (query, string): Nombre del departamento (ej. LIMA). - provincia (query, string) - distrito (query, string) - lat (query, number): Latitud (ej. -12.0464). Va con lng. - lng (query, number): Longitud (ej. -77.0428). - radio_km (query, number) - solo_destino (query, "0" | "1"): 1 = solo agencias que reciben envíos. - limite (query, integer): Máximo de agencias a devolver (en /buscar, 50 por defecto). Respuestas: 200 Agencias · 400 Sin filtro o filtro inválido (DATOS) · 429 Límite por IP (LIMITE) · 503 Catálogo cargándose (SHALOM_NO_DISPONIBLE) Ejemplo de respuesta: ```json { "ok": true, "data": { "total": 1, "items": [ { "id": 219, "nombre": "LIMA - AV. AVIACIÓN", "departamento": "LIMA", "provincia": "LIMA", "distrito": "LA VICTORIA", "es_origen": true, "es_destino": true, "aereo": true, "aereo_id": "0219", "latitud": -12.08, "longitud": -77, "distancia_km": 4.9 } ] } } ``` ## MCP (IA) Servidor Model Context Protocol para Claude, ChatGPT, Cursor y otros. Misma llave sk_ de la API. Guía: /docs/conectar-ia ### POST /mcp Servidor MCP (Streamable HTTP, sin sesión) Endpoint JSON-RPC 2.0 del Model Context Protocol. Llave en x-api-key o Authorization: Bearer sk_…; para clientes que solo aceptan una URL, POST /mcp/{tu_llave}. Herramientas: ver_cuenta, ver_perfil, buscar_agencias, cotizar, registrar_guia (crea una guía real: exige confirmado=true), rastrear, consultar_dni, listar_guias, anular_pendiente (exige confirmado=true). Cada herramienta llama a la ruta /v1 equivalente, con su mismo límite y consumo. GET y DELETE responden 405. Cuerpo JSON: - jsonrpc ("2.0", obligatorio) - id (any) - method (string, obligatorio) - params (object) Ejemplo de cuerpo: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } ``` Respuestas: 200 Respuesta JSON-RPC · 401 Sin llave o llave inválida ## Seguimiento ### GET /v1/rastreo/{guia} Rastrear una guía Busca la guía en los envíos en curso; si no está, en los entregados (estado = entregado). Parámetros: - guia (path, string, obligatorio): Número de guía (acepta también SERIE-NUMERO). - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). Respuestas: 200 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). · 422 Shalom rechazó la operación (SHALOM_RECHAZO, CREDENCIALES, SIN_TARIFA, CODIGO_INVALIDO). · 504 Shalom no respondió a tiempo (TIMEOUT). ### POST /v1/rastreo/lote Rastrear hasta 50 guías Con más de 3 guías recorre una vez las listas de Shalom y busca ahí; las que no aparecen se consultan una por una. Devuelve un ítem por guía (sin repetidas), en el orden pedido. Cuerpo JSON: - cuenta_id (string, obligatorio) - guias (string[], obligatorio) Respuestas: 200 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). · 422 Shalom rechazó la operación (SHALOM_RECHAZO, CREDENCIALES, SIN_TARIFA, CODIGO_INVALIDO). · 504 Shalom no respondió a tiempo (TIMEOUT). ### GET /v1/en-transito Envíos en curso Envíos aún no entregados. `estado` filtra por estado normalizado. Nota: `total` es el total que informa Shalom antes de los filtros locales (estado, destino). Parámetros: - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). - pagina (query, integer): Página (desde 1). - por_pagina (query, integer): Resultados por página (máx. 50). - desde (query, string): Fecha inicial AAAA-MM-DD. - hasta (query, string): Fecha final AAAA-MM-DD. - tipo_documento (query, string): Tipo de documento del destinatario (DNI, RUC, CE…). - documento (query, string): Número de documento del destinatario. - guia (query, string): Número de guía. - destino (query, string): Destino (texto; se compara sin importar mayúsculas). - estado (query, "registrado" | "en_origen" | "en_transito" | "en_reparto" | "en_destino" | "entregado" | "anulado" | "desconocido"): Estado normalizado. Respuestas: 200 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). · 422 Shalom rechazó la operación (SHALOM_RECHAZO, CREDENCIALES, SIN_TARIFA, CODIGO_INVALIDO). · 504 Shalom no respondió a tiempo (TIMEOUT). ### GET /v1/entregados Envíos entregados Parámetros: - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). - pagina (query, integer): Página (desde 1). - por_pagina (query, integer): Resultados por página (máx. 50). - desde (query, string): Fecha inicial AAAA-MM-DD. - hasta (query, string): Fecha final AAAA-MM-DD. - tipo_documento (query, string): Tipo de documento del destinatario (DNI, RUC, CE…). - documento (query, string): Número de documento del destinatario. - guia (query, string): Número de guía. - destino (query, string): Destino (texto; se compara sin importar mayúsculas). Respuestas: 200 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). · 422 Shalom rechazó la operación (SHALOM_RECHAZO, CREDENCIALES, SIN_TARIFA, CODIGO_INVALIDO). · 504 Shalom no respondió a tiempo (TIMEOUT). ## Comprobantes ### GET /v1/comprobantes Comprobantes que Shalom emitió a la cuenta Parámetros: - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). - pagina (query, integer): Página (desde 1). - por_pagina (query, integer): Resultados por página (máx. 50). - desde (query, string): Fecha inicial AAAA-MM-DD. - hasta (query, string): Fecha final AAAA-MM-DD. - tipo_documento (query, string): Tipo de documento del destinatario (DNI, RUC, CE…). - documento (query, string): Número de documento del destinatario. Respuestas: 200 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). · 422 Shalom rechazó la operación (SHALOM_RECHAZO, CREDENCIALES, SIN_TARIFA, CODIGO_INVALIDO). · 504 Shalom no respondió a tiempo (TIMEOUT). ### GET /v1/comprobantes/{serie}/{numero} Enlace de descarga de un comprobante Shalom exige reCAPTCHA v3 para esta descarga. Mientras el motor no lo genere responde 501 NO_SOPORTADO. Parámetros: - serie (path, string, obligatorio): Serie (ej. B001). - numero (path, string, obligatorio): Número. - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). Respuestas: 200 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). · 422 Shalom rechazó la operación (SHALOM_RECHAZO, CREDENCIALES, SIN_TARIFA, CODIGO_INVALIDO). · 501 NO_SOPORTADO: falta reCAPTCHA en el motor. · 504 Shalom no respondió a tiempo (TIMEOUT). ## Avisos (webhook) ### GET /v1/webhook Ver el webhook configurado (sin el secreto) Respuestas: 200 OK · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). ### PUT /v1/webhook Crear o cambiar la URL del webhook Cada llamada genera un secreto NUEVO (el anterior deja de valer). La URL debe ser https://. Cuerpo JSON: - url (string, obligatorio) Respuestas: 200 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. ### DELETE /v1/webhook Quitar el webhook Los avisos que se generen sin webhook quedan como sin_webhook (no se reintentan). Respuestas: 200 OK · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). ### GET /v1/webhook/entregas Historial de intentos de aviso Parámetros: - guia (query, string): Filtra por guía. - pagina (query, integer): Página. - por_pagina (query, integer): Máx. 100. Respuestas: 200 OK · 401 Falta la llave o no es válida. ### GET /v1/suscripciones Listar suscripciones (últimas 500) Parámetros: - activa (query, "true" | "false"): true / false. Respuestas: 200 OK · 401 Falta la llave o no es válida. ### POST /v1/suscripciones Vigilar guías (máx. 50 por llamada) Hace un primer rastreo para fijar el estado inicial (ese no se avisa). Si la guía ya está entregada o anulada, queda inactiva. Volver a suscribir una guía la reactiva. `referencia` (opcional) viaja en cada aviso; si la guía se creó con esta API se toma sola. Cuerpo JSON: - cuenta_id (string, obligatorio) - guias (string | object[], obligatorio) Respuestas: 201 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). ### GET /v1/suscripciones/{guia} Ver una suscripción Parámetros: - guia (path, string, obligatorio): Número de guía. Respuestas: 200 OK · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). ### DELETE /v1/suscripciones/{guia} Dejar de vigilar una guía Parámetros: - guia (path, string, obligatorio): Número de guía. Respuestas: 200 OK · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). ## Autogestión ### POST /v1/autogestion/{tipo}/iniciar Paso 1: validar la guía y pedir el código Shalom valida la guía con los datos del envío y manda un código por SMS o correo. `cambio-clave` responde 501 NO_SOPORTADO mientras el motor no genere reCAPTCHA. Parámetros: - tipo (path, "reparto-domicilio" | "cambio-destino" | "devolucion" | "retencion" | "liberacion" | "cambio-consignado" | "cambio-clave", obligatorio): Tipo de trámite. Cuerpo JSON: - cuenta_id (string, obligatorio) - guia (string, obligatorio): Número de guía. - codigo (string, obligatorio): Código de la guía (el de 4 caracteres impreso en el ticket). - remitente (string, obligatorio) - remitente_telefono (string, obligatorio) - destinatario (string, obligatorio) - destinatario_telefono (string, obligatorio) - fecha (string, obligatorio): Fecha de envío. - origen (string, obligatorio) - destino (string, obligatorio) - via ("sms" | "correo", por defecto "sms") - telefono (string): Celular que recibe el código (por defecto el del destinatario). - email (string): Obligatorio si via = correo. - clave_guia (string): Solo reparto-domicilio: clave de seguridad de la guía (opcional). Respuestas: 201 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). · 422 Shalom rechazó la operación (SHALOM_RECHAZO, CREDENCIALES, SIN_TARIFA, CODIGO_INVALIDO). · 501 NO_SOPORTADO (cambio-clave). · 504 Shalom no respondió a tiempo (TIMEOUT). ### GET /v1/autogestion/tramites/{id} Estado de un trámite Parámetros: - id (path, string, obligatorio): tramite_id (tra_…). Respuestas: 200 OK · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). ### GET /v1/autogestion/reparto/ubigeo Departamentos, provincias o distritos para el reparto a domicilio Sin dep_id: departamentos. Con dep_id: provincias. Con dep_id y prov_id: distritos. Parámetros: - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). - dep_id (query, string): Id de departamento. - prov_id (query, string): Id de provincia. Respuestas: 200 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). · 422 Shalom rechazó la operación (SHALOM_RECHAZO, CREDENCIALES, SIN_TARIFA, CODIGO_INVALIDO). · 504 Shalom no respondió a tiempo (TIMEOUT). ### POST /v1/autogestion/tramites/{id}/tarifa Tarifa del reparto a domicilio Solo trámites reparto-domicilio. Se guarda en el trámite y se usa al confirmar. Parámetros: - id (path, string, obligatorio): tramite_id. Cuerpo JSON: - dep_id (string | integer, obligatorio) - prov_id (string | integer, obligatorio) - dist_id (string | integer, obligatorio) Respuestas: 200 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). · 409 Trámite cerrado. · 410 Trámite vencido (VENCIDO). · 422 Shalom rechazó la operación (SHALOM_RECHAZO, CREDENCIALES, SIN_TARIFA, CODIGO_INVALIDO). · 504 Shalom no respondió a tiempo (TIMEOUT). ### POST /v1/autogestion/tramites/{id}/confirmar Paso 2: confirmar con el código recibido Datos según el tipo: - reparto-domicilio: direccion (+ dep_id, prov_id, dist_id si no se mandaron en /tarifa). Exige haber consultado la tarifa. - cambio-destino y devolucion: destino, destinatario, telefono (opcional). - cambio-consignado: destinatario (nuevo consignado). - retencion y liberacion: solo el código. - cambio-clave: clave_nueva (4 dígitos). Con código incorrecto responde 422 CODIGO_INVALIDO y se puede reintentar (hasta 5 veces). Parámetros: - id (path, string, obligatorio): tramite_id. Cuerpo JSON: - codigo (string, obligatorio): Código que Shalom mandó por SMS o correo. - direccion (string) - dep_id (string | integer) - prov_id (string | integer) - dist_id (string | integer) - destino (string) - destinatario (string) - telefono (string) - clave_nueva (string) Respuestas: 200 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). · 409 YA_COMPLETADO o TRAMITE_CERRADO. · 410 VENCIDO. · 422 Shalom rechazó la operación (SHALOM_RECHAZO, CREDENCIALES, SIN_TARIFA, CODIGO_INVALIDO). · 504 Shalom no respondió a tiempo (TIMEOUT). ### GET /v1/autogestion/historial Historial de autogestiones de la cuenta Parámetros: - cuenta_id (query, string, obligatorio): Id de la cuenta Shalom Pro del cliente (cta_…). - guia (query, string): Número de guía. - tipo (query, "reparto-domicilio" | "cambio-destino" | "devolucion" | "retencion" | "cambio-consignado" | "cambio-clave"): Tipo de trámite. - desde (query, string): AAAA-MM-DD. - hasta (query, string): AAAA-MM-DD. - pagina (query, integer): Página. - por_pagina (query, integer): Por página. Respuestas: 200 OK · 400 Datos inválidos (DATOS). · 401 Falta la llave o no es válida. · 404 No existe (NO_EXISTE). · 422 Shalom rechazó la operación (SHALOM_RECHAZO, CREDENCIALES, SIN_TARIFA, CODIGO_INVALIDO). · 504 Shalom no respondió a tiempo (TIMEOUT).