Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sistemashm24/pagos_hotspot_api/llms.txt

Use this file to discover all available pages before exploring further.

The auto-reconnect endpoint re-authenticates a customer who has already paid and holds valid hotspot credentials, but whose device MAC address has changed since they originally connected. This happens frequently on modern mobile devices that randomize their WiFi MAC address (RANDMAC) on each reconnection. The endpoint handles MAC-cookie injection, optional RANDMAC user cloning, and MikroTik version detection — all in a single API call initiated by the captive portal JavaScript when a returning visitor is detected via localStorage.
RANDMAC support: Up to 15 MAC clones can be created per base user. When a returning user connects with a new MAC address, the endpoint checks whether any existing _RANDMAC* clone already holds that MAC. If found, it logs in with that clone. If not, a new clone (e.g., AB3C9D_RANDMAC3) is created with the current MAC and used for the session. This allows a single paid account to seamlessly roam across MAC changes without re-purchasing.

​
Request

Method: POST
Path: /api/v1/hotspot/auto-reconnect
Content-Type: application/json

​
Headers

​
X-API-Key
string
required
Router API Key in the format jwt_<token>. Identifies the company and the MikroTik router where the user’s hotspot account resides.

​
Body

​
username
string
required
The hotspot username as stored in localStorage on the client device. This is the value from usuario_hotspot.usuario returned by the original payment endpoint. May also be a _RANDMAC*-suffixed clone name if the user was previously reconnected.URL-encoded values are automatically decoded by the server.
​
password
string
default:"\"\""
The hotspot password as stored in localStorage. Pass an empty string "" for PIN-type users (where the password is empty). The server automatically detects the user type and ignores this field for PIN users.
​
stored_mac
string
The previous MAC address stored in localStorage from the last successful connection. Used as a reference to look up the correct user clone. Optional — if not provided, the server falls back to searching by username only.
​
current_mac
string
required
The device’s current MAC address as seen on the captive portal network. This is the new MAC that triggered the reconnect flow. URL-encoded values are automatically decoded.Format: "AA:BB:CC:DD:EE:FF" (colons or hyphens, upper or lower case — all formats accepted).
​
current_ip
string
The device’s current IP address on the hotspot network. Passed to MikroTik’s cookie injection call to target the correct active lease. Highly recommended for reliable auto-connection.
​
current_ssid
string
The SSID the device is currently connected to. Optional informational field — not used in the connection logic but available for logging.

​
Response

​
success
boolean
true if the reconnection attempt completed without a fatal error (note: success: true does not necessarily mean the user is connected — check auto_conexion).
​
estado
string
High-level status of the user account check. Possible values:
ValueMeaning
"activo"User account was found and the connection was attempted.
"expirado"User account was not found on MikroTik, or the username field contains a MAC address (expired/invalid session).
"empresa_inactiva"The company associated with the API Key is deactivated.
"router_inactivo"The router associated with the API Key is deactivated.
"error"An unexpected server-side error occurred.
​
auto_conexion
string
Result of the MikroTik connection attempt. Either "conectado" (login succeeded and was verified in active sessions) or "no_conectado" (login not attempted or failed).
​
datos_sesion
object | null
MikroTik user or session data returned from the router. Contains the raw fields from /ip/hotspot/user or the active session entry. null if no session data was retrieved. Structure depends on MikroTik version and profile.
​
nueva_mac
string | null
The current_mac value as processed by the server (normalized to uppercase colon-separated format). Returned so the frontend can update its localStorage entry.
​
tiempo_acumulado
string | null
Accumulated uptime for the user account, if available from MikroTik (e.g., "00:45:12"). May be null if not reported by the router.
​
tiempo_restante
string | null
Remaining session time, if the MikroTik profile has a time limit configured. May be null if the profile has no limit or the router does not report it.
​
primera_sesion
string | null
ISO 8601 timestamp of the user’s first connection. May be null if not tracked.
​
mensaje
string | null
Human-readable message describing the connection outcome. Display this to the user when auto_conexion is "no_conectado".
​
error_detalle
string | null
Technical error details for debugging. Only present when estado is "error". Do not display to end users.
​
timestamp
string
ISO 8601 UTC datetime of the server’s response (e.g., "2024-07-01T17:00:00.000000").

​
Reconnect Flow

1. Decode URL-encoded username and current_mac
2. Check empresa.activa and router.activo → return early if inactive
3. If username looks like a MAC address → return estado: "expirado"
4. Open MikroTik API connection
5. Strip _RANDMAC* suffix to get base_username
6. Look up base user in /ip/hotspot/user
7. If user not found → return estado: "expirado"
8. If user has RANDMAC comment markers (MODE=, TL=, TA=):
   a. Normalize current_mac
   b. Search all _RANDMAC* clones for a matching MAC
   c. If match found → use that clone's username for login
   d. If no match AND clone count < 15 → create new _RANDMAC{n} clone
   e. Inject MAC cookie for the selected username
9. Detect MikroTik major version (v6 vs v7 login flow)
10. Execute auto-connection (MAC + IP based login)
11. Return result

​
Examples

​
cURL

curl -X POST "https://api.example.com/api/v1/hotspot/auto-reconnect" \
  -H "X-API-Key: jwt_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb3V0ZXJfaWQiOjMsImVtcHJlc2FfaWQiOjF9.SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "AB3C9D",
    "password": "4821",
    "stored_mac": "AA:BB:CC:DD:EE:FF",
    "current_mac": "11:22:33:44:55:66",
    "current_ip": "192.168.88.175",
    "current_ssid": "WiFi-Cafe"
  }'

​
Response — Connected 200 OK

{
  "success": true,
  "estado": "activo",
  "auto_conexion": "conectado",
  "datos_sesion": {
    ".id": "*3",
    "name": "AB3C9D_RANDMAC2",
    "profile": "5Mbps-1hora",
    "mac-address": "11:22:33:44:55:66",
    "comment": "MODE=RANDMAC TL=3600 TA=1800",
    "disabled": "no"
  },
  "nueva_mac": "11:22:33:44:55:66",
  "tiempo_acumulado": "00:30:14",
  "tiempo_restante": "00:29:46",
  "primera_sesion": null,
  "mensaje": null,
  "error_detalle": null,
  "timestamp": "2024-07-01T17:00:00.123456"
}

​
Response — Expired user 200 OK

{
  "success": false,
  "estado": "expirado",
  "auto_conexion": "no_conectado",
  "datos_sesion": null,
  "nueva_mac": "11:22:33:44:55:66",
  "tiempo_acumulado": null,
  "tiempo_restante": null,
  "primera_sesion": null,
  "mensaje": "Usuario no encontrado",
  "error_detalle": null,
  "timestamp": "2024-07-01T17:05:00.654321"
}

​
Response — Inactive company 200 OK

{
  "success": false,
  "estado": "empresa_inactiva",
  "auto_conexion": "no_conectado",
  "datos_sesion": null,
  "nueva_mac": "11:22:33:44:55:66",
  "tiempo_acumulado": null,
  "tiempo_restante": null,
  "primera_sesion": null,
  "mensaje": null,
  "error_detalle": null,
  "timestamp": "2024-07-01T17:10:00.000000"
}
This endpoint always returns HTTP 200 regardless of the connection outcome. Check the estado and auto_conexion fields to determine the actual result. A success: false response with estado: "expirado" is the normal case for a user whose access period has ended — direct them to the payment page to purchase a new session.
The recommended frontend pattern is: on captive portal load, check localStorage for username, password, and stored_mac. If all three exist, immediately call this endpoint with the device’s current MAC. If auto_conexion is "conectado", the user is online. If estado is "expirado", show the product catalog. This provides a seamless returning-user experience without requiring a new purchase.

Build docs developers (and LLMs) love

Get started for freeTalk to us