Ir al contenido
SShalom API

Instancias (sesión Shalom Pro)

Conecta tu cuenta Shalom Pro como instancia: crea, lista y elimina instancias, y gestiona la sesión de Shalom Pro (login, estado y logout) por API.

Una instancia es una cuenta de Shalom Pro conectada a tu cuenta de Shalom API. Todas las operaciones marcadas como Requiere Shalom Pro (crear guías, listar pendientes, ticket, rótulo, autogestiones) usan tu API key más el instanceId de la instancia.

Crear y conectar

POST /instances crea la instancia con un nombre para identificarla y POST /instances/login abre la sesión con el usuario y la contraseña de Shalom Pro. La cantidad de instancias depende de tu plan; el plan gratuito no incluye instancias.

La sesión se reconecta sola

La sesión de Shalom Pro se guarda en la instancia y sobrevive a reinicios del servidor. No se mantiene viva con consultas periódicas: se usa cuando una operación la necesita.

Si Shalom ya la venció, la API lo detecta en esa misma operación, vuelve a iniciar sesión con las credenciales guardadas y reintenta una vez. Para tu integración es transparente: la llamada solo tarda unos segundos más. Si llegan varias operaciones a la vez, comparten un solo login.

La reconexión necesita las credenciales guardadas. Se pierden con POST /instances/logout y dejan de servir si cambia la contraseña de Shalom Pro. En ese caso las operaciones Pro fallan (por lo general con 409, "La instancia perdió la sesión de Shalom Pro") y hay que volver a llamar a POST /instances/login.

Comprobar la sesión

POST /instances/status dice si la sesión está abierta en este momento, pero no reconecta. Úsalo para mostrar el estado en tu panel, no como requisito antes de cada operación.

Crear una instancia

POST /instances

Crea una instancia vacía en tu cuenta. Después inicia sesión en ella con POST /instances/login. No consume cuota.

ParámetroRequeridoDescripción
nameNoNombre para identificarla (ej. Tienda Lima). Por defecto "Mi Instancia".
curl -X POST "https://api.shalom-api.lat/instances" \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Tienda Lima"
}'
Respuesta
{
  "status": "created",
  "instanceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Tienda Lima",
  "message": "Instance created successfully"
}
Responde 403 si tu plan no incluye instancias o si ya alcanzaste su máximo. El plan gratuito no incluye instancias.

Listar instancias

GET /instances

Devuelve las instancias de tu cuenta. No consume cuota.

curl -X GET "https://api.shalom-api.lat/instances" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "instances": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Tienda Lima",
      "username": "[email protected]",
      "createdAt": "2026-11-01T10:30:00.000Z",
      "isLoggedIn": true
    }
  ]
}
Aquí isLoggedIn indica que la instancia tiene credenciales y una sesión guardada, sin consultar a Shalom. Para comprobarla en vivo usa POST /instances/status.

Eliminar una instancia

DELETE /instances

Elimina la instancia, su sesión y sus credenciales guardadas. No se puede deshacer. No consume cuota.

ParámetroRequeridoDescripción
instanceIdSíInstancia a eliminar (en el body).
curl -X DELETE "https://api.shalom-api.lat/instances" \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
Respuesta
{
  "status": "closed",
  "message": "Instance closed successfully"
}

Estado de la sesión

POST /instances/status

Requiere Shalom Pro

Este endpoint usa una instancia con la sesión de Shalom Pro iniciada. Ver Instancias.

Comprueba con Shalom si la sesión de la instancia está abierta en este momento. Solo informa, no reconecta: un isLoggedIn en false con credenciales guardadas no es un error, porque la próxima operación Pro se reconecta sola. No consume cuota.

ParámetroRequeridoDescripción
instanceIdSíInstancia a revisar (en el body).
curl -X POST "https://api.shalom-api.lat/instances/status" \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
Respuesta
{
  "isLoggedIn": true,
  "username": "[email protected]",
  "url": "https://pro.shalom.pe/#/envios/list"
}
Sin sesión responde isLoggedIn en false, username en null y url "https://pro.shalom.pe/login". El resultado de la comprobación se reutiliza hasta un minuto.

Iniciar sesión en Shalom Pro

POST /instances/login

Requiere Shalom Pro

Este endpoint usa una instancia con la sesión de Shalom Pro iniciada. Ver Instancias.

Inicia sesión en pro.shalom.pe con el usuario y la contraseña de la cuenta. La sesión y las credenciales quedan guardadas en la instancia para reconectar sola cuando la sesión vence, así que basta con hacerlo una vez. Puede tardar varios segundos. No consume cuota.

ParámetroRequeridoDescripción
instanceIdSíInstancia donde iniciar sesión.
usernameSíUsuario o correo de Shalom Pro.
passwordSíContraseña de Shalom Pro.
curl -X POST "https://api.shalom-api.lat/instances/login" \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "username": "[email protected]",
  "password": "tu-contraseña"
}'
Respuesta
{
  "success": true,
  "message": "Login successful",
  "url": "https://pro.shalom.pe/#/envios/list"
}
Si la instancia ya tenía la sesión abierta con esas mismas credenciales, responde message "Already logged in". Con credenciales incorrectas responde 401 con { success: false, message }.

Cerrar sesión en Shalom Pro

POST /instances/logout

Requiere Shalom Pro

Este endpoint usa una instancia con la sesión de Shalom Pro iniciada. Ver Instancias.

Cierra la sesión y borra las credenciales guardadas. Después la instancia ya no se reconecta sola hasta un nuevo POST /instances/login. No consume cuota.

ParámetroRequeridoDescripción
instanceIdSíInstancia donde cerrar sesión (en el body).
curl -X POST "https://api.shalom-api.lat/instances/logout" \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
Respuesta
{
  "success": true,
  "message": "Logged out and session cleared"
}

Errores

CódigoSignificado
400Falta instanceId, username o password.
401Falta la API key, la key es inválida (POST y GET /instances), o el usuario o la contraseña de Shalom Pro son incorrectos (login).
403En las rutas con instanceId, la key es inválida o la instancia no es de tu cuenta. En POST /instances, tu plan no permite crear más instancias.
404La instancia no existe.
500No se pudo completar el login, el logout o la creación. El campo details trae el motivo cuando está disponible.

Preguntas frecuentes

Relacionado