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 /instancesCrea una instancia vacía en tu cuenta. Después inicia sesión en ella con POST /instances/login. No consume cuota.
| Parámetro | Requerido | Descripción |
|---|---|---|
name | No | Nombre 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"
}'{
"status": "created",
"instanceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Tienda Lima",
"message": "Instance created successfully"
}Listar instancias
GET /instancesDevuelve las instancias de tu cuenta. No consume cuota.
curl -X GET "https://api.shalom-api.lat/instances" \
-H "x-api-key: TU_API_KEY"{
"instances": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Tienda Lima",
"username": "[email protected]",
"createdAt": "2026-11-01T10:30:00.000Z",
"isLoggedIn": true
}
]
}Eliminar una instancia
DELETE /instancesElimina la instancia, su sesión y sus credenciales guardadas. No se puede deshacer. No consume cuota.
| Parámetro | Requerido | Descripción |
|---|---|---|
instanceId | Sí | 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"
}'{
"status": "closed",
"message": "Instance closed successfully"
}Estado de la sesión
POST /instances/statusRequiere Shalom Pro
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ámetro | Requerido | Descripción |
|---|---|---|
instanceId | Sí | 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"
}'{
"isLoggedIn": true,
"username": "[email protected]",
"url": "https://pro.shalom.pe/#/envios/list"
}Iniciar sesión en Shalom Pro
POST /instances/loginRequiere Shalom Pro
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ámetro | Requerido | Descripción |
|---|---|---|
instanceId | Sí | Instancia donde iniciar sesión. |
username | Sí | Usuario o correo de Shalom Pro. |
password | Sí | 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"
}'{
"success": true,
"message": "Login successful",
"url": "https://pro.shalom.pe/#/envios/list"
}Cerrar sesión en Shalom Pro
POST /instances/logoutRequiere Shalom Pro
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ámetro | Requerido | Descripción |
|---|---|---|
instanceId | Sí | 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"
}'{
"success": true,
"message": "Logged out and session cleared"
}Errores
| Código | Significado |
|---|---|
400 | Falta instanceId, username o password. |
401 | Falta 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). |
403 | En 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. |
404 | La instancia no existe. |
500 | No se pudo completar el login, el logout o la creación. El campo details trae el motivo cuando está disponible. |
Preguntas frecuentes
Las de la cuenta de Shalom Pro que despacha los envíos. Se guardan en la instancia para operar en su nombre y reconectar la sesión cuando vence.
No. Haces POST /instances/login una vez y la instancia se reconecta sola cuando hace falta, aunque la sesión haya vencido o el servidor se haya reiniciado.
Si cambió la contraseña de Shalom Pro, si hiciste logout o si una operación responde que la instancia perdió la sesión (409) o que el auto-login falló.
Sí, según el máximo de tu plan. Lo recomendable es una por cuenta de Shalom Pro.
Sí. Usas tu misma API key y agregas el instanceId de la instancia en cada operación Pro.