Opera tu cuenta Shalom Pro por API: crea guías, cotiza, consulta agencias, descarga ticket y rótulo, rastrea y recibe avisos. Base: https://shalom.smartflow.pe/v1. Abajo tienes las reglas comunes y luego cada ruta con ejemplos y un probador.
Manda tu llave en la cabecera x-api-key en cada llamada. Las llaves empiezan con sk_ y se ven una sola vez al crearlas: guárdala como un secreto, nunca en el navegador de tus clientes.
Sin cabecera: 401 SIN_LLAVE. Llave mal o desactivada: 401 LLAVE_INVALIDA. Luego conecta tu cuenta con POST /v1/cuentas y usa su cuenta_id (cta_…) en las demás rutas.
2. Formato de respuestas
Siempre JSON con la misma forma. Revisa ok primero y, si es false, decide por codigo_error (estable), no por el texto de error (puede cambiar).
Los PDF (ticket y rótulo) llegan como archivo application/pdf, no como JSON.
3. Referencia propia: nunca guías repetidas
Al crear una guía mandas referencia: el id del envío en tu sistema (ej. PED-1001). Si la vuelves a mandar con los mismos datos, recibes 200 con la guía que ya existe y ya_existia: true; no se crea otra.
Si esa referencia ya se usó para otro envío (otro destinatario, destino o cuenta): 409 REFERENCIA_OCUPADA. Si Shalom no respondió al guardar, la guía queda incierta (pudo crearse): revisa GET /v1/pendientes y recién reintenta con "forzar": true; sin eso respondemos 409 POSIBLE_DUPLICADO.
4. Límites
Llamadas por minuto por llave según tu plan (prueba 30, Pro 120, Negocio 300, Empresa 600; míralo en GET /v1/yo → limites). Al pasarte: 429 LIMITE con Retry-After, espera y reintenta.
Prueba gratis: 14 días o 30 guías, lo que ocurra primero, y hasta 300 consultas por día (registrar guías no cuenta). Al terminar, la API responde 402 PRUEBA_TERMINADA (salvo GET /v1/yo) hasta que elijas un plan en el panel. Los planes de pago no tienen tope de guías ni de consultas. Nada se borra al terminar la prueba o al vencer un plan.
Lotes: hasta 100 guías en POST /v1/guias/lote, 50 guías en POST /v1/rastreo/lote y en POST /v1/suscripciones.
Cada cuenta Shalom atiende un pedido a la vez, en orden. Si hay demasiados en espera: 503 OCUPADO. Con la sesión abierta, una guía tarda alrededor de 1 segundo; el primer inicio de sesión, unos 5.
5. Códigos de error principales
Los más comunes. Cada ruta de la referencia lista los suyos.
Código
HTTP
Qué significa y qué hacer
DATOS
400
Faltan datos o no son válidos. La lista va en errores. No se llamó a Shalom: corrige y vuelve a mandar.
NO_EXISTE
404
La cuenta, guía, agencia o trámite no existe (o no es tuyo).
CREDENCIALES
422
Shalom no aceptó el correo o la clave de la cuenta. Actualízala con PUT /v1/cuentas/{id}.
SHALOM_NO_DISPONIBLE
503
Shalom Pro no responde o está en mantenimiento. Reintenta en unos minutos.
SIN_TARIFA
422
Shalom no tiene precio para esa ruta o producto. Prueba otra agencia o tamaño.
SHALOM_RECHAZO
422
Shalom rechazó el pedido; el motivo de Shalom va en error.
POSIBLE_DUPLICADO
409
Un intento anterior de esa referencia quedó sin respuesta. Revisa pendientes y reintenta con forzar: true.
REFERENCIA_OCUPADA
409
Esa referencia ya se usó para otro envío. Usa una nueva.
CORREO_EN_USO
409
Esa cuenta Shalom ya está conectada por otro cliente.
OCUPADO
503
La cuenta tiene muchos pedidos en espera. Reintenta en unos minutos.
LIMITE
429
Superaste tus llamadas por minuto. Espera y reintenta.
LIMITE_DIA
429
Prueba gratis: llegaste a las consultas del día. Vuelve mañana (Retry-After) o elige un plan.
PRUEBA_TERMINADA
402
Tu prueba gratis terminó (14 días o 30 guías). Elige un plan en el panel.
SIN_CREDITOS
402
No quedan guías de prueba para esta guía. Elige un plan.
PLAN_VENCIDO
402
Tu plan venció sin renovarse. Renuévalo en el panel; no se borró nada.
LIMITE_PLAN
403
Tu plan no permite más cuentas Shalom o llaves. Cambia de plan.
6. Webhooks: avisos cuando cambia un envío
Configura tu URL con PUT /v1/webhook (la respuesta trae el secreto whsec_…una sola vez) y suscribe guías con POST /v1/suscripciones. Cuando cambia el estado te llega un POST con las cabeceras x-shalom-firma y x-shalom-evento (id único: úsalo para ignorar repetidos). Responde 2xx en menos de 10 s; si no, reintentamos a 1 y a 5 minutos.
Cómo verificar la firma
Cabecera: x-shalom-firma: t=1763400000,v1=5f2b…
Arma la cadena t + "." + cuerpo_crudo (los bytes tal como llegaron, antes de leer el JSON).
Calcula HMAC-SHA256 en hexadecimal con tu secreto whsec_… completo como clave.
Compara con v1 en tiempo constante y rechaza si t tiene más de 5 minutos.