Saltar al contenido
Shalom APIDocumentación
Empieza aquí

Documentación de Shalom API

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.

1. Autenticación

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.

GET/v1/yo
curl https://shalom.smartflow.pe/v1/yo \
  -H "x-api-key: sk_tu_llave"

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).

Bien / Mal
{ "ok": true,  "data": { … } }

{ "ok": false,
  "codigo_error": "DATOS",
  "error": "Falta el teléfono.",
  "errores": [ { "campo": "telefono", "mensaje": "…" } ] }

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ódigoHTTPQué significa y qué hacer
DATOS400Faltan datos o no son válidos. La lista va en errores. No se llamó a Shalom: corrige y vuelve a mandar.
NO_EXISTE404La cuenta, guía, agencia o trámite no existe (o no es tuyo).
CREDENCIALES422Shalom no aceptó el correo o la clave de la cuenta. Actualízala con PUT /v1/cuentas/{id}.
SHALOM_NO_DISPONIBLE503Shalom Pro no responde o está en mantenimiento. Reintenta en unos minutos.
SIN_TARIFA422Shalom no tiene precio para esa ruta o producto. Prueba otra agencia o tamaño.
SHALOM_RECHAZO422Shalom rechazó el pedido; el motivo de Shalom va en error.
POSIBLE_DUPLICADO409Un intento anterior de esa referencia quedó sin respuesta. Revisa pendientes y reintenta con forzar: true.
REFERENCIA_OCUPADA409Esa referencia ya se usó para otro envío. Usa una nueva.
CORREO_EN_USO409Esa cuenta Shalom ya está conectada por otro cliente.
OCUPADO503La cuenta tiene muchos pedidos en espera. Reintenta en unos minutos.
LIMITE429Superaste tus llamadas por minuto. Espera y reintenta.
LIMITE_DIA429Prueba gratis: llegaste a las consultas del día. Vuelve mañana (Retry-After) o elige un plan.
PRUEBA_TERMINADA402Tu prueba gratis terminó (14 días o 30 guías). Elige un plan en el panel.
SIN_CREDITOS402No quedan guías de prueba para esta guía. Elige un plan.
PLAN_VENCIDO402Tu plan venció sin renovarse. Renuévalo en el panel; no se borró nada.
LIMITE_PLAN403Tu 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…

  1. Arma la cadena t + "." + cuerpo_crudo (los bytes tal como llegaron, antes de leer el JSON).
  2. Calcula HMAC-SHA256 en hexadecimal con tu secreto whsec_… completo como clave.
  3. Compara con v1 en tiempo constante y rechaza si t tiene más de 5 minutos.
Node.js
const crypto = require('crypto');
function firmaValida(cabecera, cuerpoCrudo, secreto) {
  const p = Object.fromEntries(cabecera.split(',').map((x) => x.split('=')));
  const esperado = crypto.createHmac('sha256', secreto)
    .update(`${p.t}.${cuerpoCrudo}`).digest('hex');
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
  return !!p.v1 && p.v1.length === esperado.length &&
    crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(p.v1));
}
PHP
[$t, $v1] = [null, null];
foreach (explode(',', $_SERVER['HTTP_X_SHALOM_FIRMA']) as $kv) {
  [$k, $v] = explode('=', $kv, 2);
  if ($k === 't') $t = $v;
  if ($k === 'v1') $v1 = $v;
}
$cuerpo = file_get_contents('php://input');
$ok = abs(time() - (int) $t) <= 300 && hash_equals(
  hash_hmac('sha256', $t . '.' . $cuerpo, $secreto), (string) $v1);

Referencia de la API

Todas las rutas, con sus campos, ejemplos y un probador. Puedes descargar la especificación OpenAPI desde el visor.

Cargando la referencia…