Admin Company Management Endpoints for Client Admins

Client admin users interact with their own company through the /api/v1/admin/mi-empresa namespace. Every request must carry a valid session token issued at login for a user with the cliente_admin role. These endpoints let you read and update company information, configure Conekta and Mercado Pago payment credentials, upload your brand logo, inspect your routers, and browse the company dashboard — all scoped strictly to the company associated with your account.

All endpoints in this section require the header Authorization: Bearer <session_token> for a user with role cliente_admin. Tokens are obtained from the /api/v1/auth/login endpoint.

GET /api/v1/admin/mi-empresa

Returns the full public profile of the authenticated user’s company, including payment gateway modes and Telegram notification settings. Sensitive private keys are never returned by this endpoint.

cURL

curl -X GET "https://api.example.com/api/v1/admin/mi-empresa" \
  -H "Authorization: Bearer <session_token>"

Response

string

required

Unique company identifier in EMP_ + 10 hex characters format. Example: EMP_3A9F1C0B2D.

nombre

string

required

Company display name.

contacto_email

string

required

Primary contact email address for the company.

contacto_telefono

string

Optional contact phone number.

logo_url

string

Relative path to the uploaded company logo, e.g. /static/logos/logo_EMP_xxx_a1b2c3.png. Build the full URL by prepending your API base URL.

conekta_mode

string

required

Conekta operating mode. One of "test" or "live".

conekta_public_key

string

Conekta public key (safe to expose to the captive portal frontend).

mercado_pago_mode

string

Mercado Pago operating mode. Defaults to "test".

mercado_pago_public_key

string

Mercado Pago public key (safe to expose to the captive portal frontend).

activa

boolean

required

Whether the company account is currently active.

creada_en

string (ISO 8601)

Timestamp of when the company was created.

telegram_bot_token

string

Telegram Bot Token used for payment notifications. Stored in the database, returned as-is for display in the admin panel.

telegram_chat_id

string

Telegram Chat ID where notifications are sent.

notificaciones_telegram

boolean

Whether Telegram payment notifications are enabled. Defaults to false.

PUT /api/v1/admin/mi-empresa

Updates the company’s basic contact information and Telegram notification settings. Only fields included in the request body are modified (partial update).

cURL

curl -X PUT "https://api.example.com/api/v1/admin/mi-empresa" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "WiFi Parque Central",
    "contacto_email": "[email protected]",
    "contacto_telefono": "+52 55 1234 5678",
    "telegram_bot_token": "7123456789:AAFxxxxxxxxxxxxxxxx",
    "telegram_chat_id": "-1001234567890",
    "notificaciones_telegram": true
  }'

Request Body

nombre

string

New display name for the company.

contacto_email

string

New primary contact email.

contacto_telefono

string

New contact phone number.

telegram_bot_token

string

Telegram Bot Token. Obtain one by messaging @BotFather on Telegram.

telegram_chat_id

string

Telegram Chat ID. Can be a personal chat ID or a group/channel ID (prefixed with -100).

notificaciones_telegram

boolean

Set to true to enable Telegram notifications for new payments and hotspot user creation events.

Response

{
  "message": "Información de la empresa actualizada correctamente",
  "empresa": {
    "nombre": "WiFi Parque Central",
    "contacto_email": "[email protected]",
    "contacto_telefono": "+52 55 1234 5678",
    "telegram_bot_token": "7123456789:AAFxxxxxxxxxxxxxxxx",
    "telegram_chat_id": "-1001234567890",
    "notificaciones_telegram": true
  }
}

GET /api/v1/admin/mi-empresa/conekta

Returns the current Conekta configuration for the company. The private key is masked as "********" for security — it is never returned in full.

cURL

curl -X GET "https://api.example.com/api/v1/admin/mi-empresa/conekta" \
  -H "Authorization: Bearer <session_token>"

Response

message

string

Always "Configuración cargada" on success.

configuracion_actual

object

Show configuracion_actual fields

conekta_public_key

string

The Conekta public key currently configured.

conekta_mode

string

Current mode: "test" or "live".

conekta_private_key

string

Always "********" if a key is stored, or null if none has been configured.

PUT /api/v1/admin/mi-empresa/conekta-config

Updates Conekta credentials (legacy endpoint, still supported). Prefer POST /configurar-conekta for new integrations.

cURL

curl -X PUT "https://api.example.com/api/v1/admin/mi-empresa/conekta-config" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "conekta_private_key": "key_live_xxxxxxxxx",
    "conekta_public_key": "key_pub_live_xxxxxxxxx",
    "conekta_mode": "live"
  }'

Request Body

conekta_private_key

string

Conekta secret key (starts with key_test_ or key_live_). Only updated if provided.

conekta_public_key

string

Conekta public key. Only updated if provided.

conekta_mode

string

default:"test"

Gateway mode. Accepted values: "test", "live".

POST /api/v1/admin/mi-empresa/configurar-conekta

Sets or replaces Conekta credentials. This is the preferred endpoint used by the desktop admin application. Accepts the same body as PUT /conekta-config.

cURL

curl -X POST "https://api.example.com/api/v1/admin/mi-empresa/configurar-conekta" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "conekta_private_key": "key_live_xxxxxxxxx",
    "conekta_public_key": "key_pub_live_xxxxxxxxx",
    "conekta_mode": "live"
  }'

Request Body

conekta_private_key

string

Conekta secret key. Only updated when a non-empty value is provided.

conekta_public_key

string

Conekta public key. Only updated when a non-empty value is provided.

conekta_mode

string

default:"test"

"test" or "live".

Response

{ "message": "Credenciales de Conekta actualizadas correctamente" }

GET /api/v1/admin/mi-empresa/mercado-pago

Returns the current Mercado Pago configuration. The access_token and webhook_secret are always masked as "********".

cURL

curl -X GET "https://api.example.com/api/v1/admin/mi-empresa/mercado-pago" \
  -H "Authorization: Bearer <session_token>"

Response

{
  "message": "Configuración cargada",
  "configuracion_actual": {
    "access_token": "********",
    "public_key": "APP_USR-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "mode": "test",
    "webhook_secret": "********"
  }
}

POST /api/v1/admin/mi-empresa/configurar-credenciales

Sets or replaces Mercado Pago credentials. Fields are only updated when a non-empty value is provided.

cURL

curl -X POST "https://api.example.com/api/v1/admin/mi-empresa/configurar-credenciales" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "APP_USR-xxxx-access-token",
    "public_key": "APP_USR-xxxx-public-key",
    "webhook_secret": "my_webhook_secret",
    "mode": "live"
  }'

Request Body

access_token

string

Mercado Pago private access token (starts with APP_USR- or TEST-).

public_key

string

Mercado Pago public key, safe to include in the captive portal frontend.

webhook_secret

string

Secret used to validate incoming Mercado Pago webhook signatures.

mode

string

default:"test"

"test" or "live".

Response

{ "message": "Credenciales de Mercado Pago actualizadas correctamente" }

POST /api/v1/admin/mi-empresa/logo

Uploads or replaces the company logo. The file is saved under static/logos/ with a UUID-derived filename to prevent caching conflicts.

Accepted formats: .jpg, .jpeg, .png, .webp. Any other extension returns HTTP 400.

cURL

curl -X POST "https://api.example.com/api/v1/admin/mi-empresa/logo" \
  -H "Authorization: Bearer <session_token>" \
  -F "file=@/path/to/logo.png"

Request

Field	Type	Required	Description
file	multipart/form-data file	✅	Image file (`.jpg`, `.jpeg`, `.png`, `.webp`)

Response

{
  "message": "Logo actualizado correctamente",
  "logo_url": "/static/logos/logo_EMP_3A9F1C0B2D_a1b2c3.png"
}

GET /api/v1/admin/mi-empresa/dashboard

Returns aggregated statistics for the company: transaction counts, total revenue, and the 5 most recent transactions. Useful for building summary dashboards in the admin panel.

cURL

curl -X GET "https://api.example.com/api/v1/admin/mi-empresa/dashboard" \
  -H "Authorization: Bearer <session_token>"

Response

empresa

object

Show empresa fields

nombre

string

Company name.

activa

boolean

Whether the company account is active.

estadisticas

object

Show estadisticas fields

total_transacciones

integer

Total number of transactions ever created.

ingresos_totales

number

Sum of all transaction amounts (all states).

transacciones_pagadas

integer

Count of transactions with estado_pago = "paid".

transacciones_pendientes

integer

Count of transactions with estado_pago = "pending".

total_routers

integer

Total number of routers registered to the company.

transacciones_recientes

array

Array of the 5 most recent transactions, ordered by creada_en descending.

Show transaction item fields

integer

Internal transaction database ID.

transaccion_id

string

Unique transaction reference string.

monto

number

Transaction amount as a float.

estado

string

Payment state: "paid", "pending", "approved", or "rejected".

fecha

string (ISO 8601)

Creation timestamp.

Example Response

{
  "empresa": {
    "nombre": "WiFi Parque Central",
    "activa": true
  },
  "estadisticas": {
    "total_transacciones": 142,
    "ingresos_totales": 7100.0,
    "transacciones_pagadas": 138,
    "transacciones_pendientes": 4,
    "total_routers": 3
  },
  "transacciones_recientes": [
    {
      "id": 142,
      "transaccion_id": "ord_2xxxxxxxxxxxxxb",
      "monto": 50.0,
      "estado": "paid",
      "fecha": "2025-01-15T14:32:10.123456"
    }
  ]
}

GET /api/v1/admin/mi-empresa/routers

Lists all routers registered to the authenticated user’s company.

cURL

curl -X GET "https://api.example.com/api/v1/admin/mi-empresa/routers" \
  -H "Authorization: Bearer <session_token>"

Response

{
  "empresa_id": "EMP_3A9F1C0B2D",
  "total": 2,
  "routers": [
    {
      "id": "RTR_A1B2C3D4",
      "nombre": "Router Principal",
      "host": "192.168.88.1",
      "ubicacion": "Lobby Piso 1",
      "activo": true,
      "creado_en": "2025-01-10T09:00:00"
    },
    {
      "id": "RTR_E5F6G7H8",
      "nombre": "Router Terraza",
      "host": "192.168.88.2",
      "ubicacion": "Terraza",
      "activo": true,
      "creado_en": "2025-01-11T10:30:00"
    }
  ]
}

PUT /api/v1/admin/mi-empresa/routers/

Updates the configuration of a specific router that belongs to the company. Fails with HTTP 404 if the router does not exist or belongs to a different company.

cURL

curl -X PUT "https://api.example.com/api/v1/admin/mi-empresa/routers/RTR_A1B2C3D4" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Router Principal (Actualizado)",
    "host": "10.0.0.1",
    "ubicacion": "Lobby Piso 2"
  }'

Path Parameters

router_id

string

required

The router ID to update, e.g. RTR_A1B2C3D4.

Request Body

nombre

string

New display name for the router.

host

string

MikroTik router IP address or hostname.

puerto

integer

default:"8728"

MikroTik API port. Defaults to 8728 if omitted.

usuario

string

MikroTik API username.

password_encrypted

string

MikroTik API password.

ubicacion

string

Human-readable physical location description.

Response

{
  "message": "Router actualizado correctamente",
  "router": {
    "id": "RTR_A1B2C3D4",
    "nombre": "Router Principal (Actualizado)",
    "host": "10.0.0.1",
    "puerto": 8728,
    "usuario": "admin",
    "ubicacion": "Lobby Piso 2",
    "activo": true
  }
}

GET /api/v1/admin/mi-empresa/transacciones

Returns paginated transaction history for the company, ordered by creation date descending. See the Transactions page for full detail.

cURL

curl -X GET "https://api.example.com/api/v1/admin/mi-empresa/transacciones?limit=20&offset=0" \
  -H "Authorization: Bearer <session_token>"

Query Parameters

limit

integer

default:"50"

Maximum number of transactions to return per page.

offset

integer

default:"0"

Number of records to skip for pagination.

POST /api/v1/admin/mi-empresa/verify-api-key

Verifies that an API Key belongs to the authenticated user’s company, and returns which router it is associated with along with usage metadata.

The API Key must start with the jwt_ prefix. This endpoint only looks up keys scoped to your company — it cannot verify keys from other companies.

cURL

curl -X POST "https://api.example.com/api/v1/admin/mi-empresa/verify-api-key" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "jwt_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }'

Request Body

api_key

string

required

The full API Key to verify, including the jwt_ prefix.

Response

{
  "status": "valid",
  "message": "API Key encontrada",
  "key_id": "key_a1b2c3d4e5f6g7h8",
  "router": {
    "id": "RTR_A1B2C3D4",
    "nombre": "Router Principal",
    "activo": true
  },
  "info": {
    "issued_at": "2025-01-10T09:00:00",
    "expires_at": "2026-01-10T09:00:00",
    "last_used": "2025-01-15T14:30:00",
    "use_count": 87,
    "revoked": false,
    "revoked_at": null
  }
}

status

string

"valid" if the key is active, "revoked" if it has been revoked.

POST /api/v1/admin/test-telegram

Sends a test Telegram message to verify bot credentials. You can pass temporary credentials in the request body to test them before saving — useful for the credential configuration UI.

cURL

curl -X POST "https://api.example.com/api/v1/admin/test-telegram" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "7123456789:AAFxxxxxxxxxxxxxxxx",
    "chat_id": "-1001234567890"
  }'

Request Body

token

string

Telegram Bot Token to test. If omitted, uses the token stored in the company’s database record.

chat_id

string

Telegram Chat ID to send the test message to. If omitted, uses the chat ID stored in the company’s database record.

Pass token and chat_id in the request body to test credentials that have not been saved yet. The endpoint falls back to stored database values if either field is absent.

Response

{ "message": "Mensaje de prueba enviado con éxito" }

Error Responses

Status	Detail
`400`	`"Faltan credenciales (Token o Chat ID)"` — neither the request nor the DB has both values
`500`	`"Error de Telegram. Verifica que el Token sea válido y que hayas iniciado chat con el bot."`

Public Endpoints

Admin Endpoints

Super Admin Endpoints

Webhooks

Documentation Index

​GET /api/v1/admin/mi-empresa

​Response

​PUT /api/v1/admin/mi-empresa

​Request Body

​Response

​GET /api/v1/admin/mi-empresa/conekta

​Response

​PUT /api/v1/admin/mi-empresa/conekta-config

​Request Body

​POST /api/v1/admin/mi-empresa/configurar-conekta

​Request Body

​Response

​GET /api/v1/admin/mi-empresa/mercado-pago

​Response

​POST /api/v1/admin/mi-empresa/configurar-credenciales

​Request Body

​Response

​POST /api/v1/admin/mi-empresa/logo

​Request

​Response

​GET /api/v1/admin/mi-empresa/dashboard

​Response

​GET /api/v1/admin/mi-empresa/routers

​Response

​PUT /api/v1/admin/mi-empresa/routers/

​Path Parameters

​Request Body

​Response

​GET /api/v1/admin/mi-empresa/transacciones

​Query Parameters

​POST /api/v1/admin/mi-empresa/verify-api-key

​Request Body

​Response

​POST /api/v1/admin/test-telegram

​Request Body

​Response

​Error Responses

Build docs developers (and LLMs) love

GET /api/v1/admin/mi-empresa

Response

PUT /api/v1/admin/mi-empresa

Request Body

Response

GET /api/v1/admin/mi-empresa/conekta

Response

PUT /api/v1/admin/mi-empresa/conekta-config

Request Body

POST /api/v1/admin/mi-empresa/configurar-conekta

Request Body

Response

GET /api/v1/admin/mi-empresa/mercado-pago

Response

POST /api/v1/admin/mi-empresa/configurar-credenciales

Request Body

Response

POST /api/v1/admin/mi-empresa/logo

Request

Response

GET /api/v1/admin/mi-empresa/dashboard

Response

GET /api/v1/admin/mi-empresa/routers

Response

PUT /api/v1/admin/mi-empresa/routers/

Path Parameters

Request Body

Response

GET /api/v1/admin/mi-empresa/transacciones

Query Parameters

POST /api/v1/admin/mi-empresa/verify-api-key

Request Body

Response

POST /api/v1/admin/test-telegram

Request Body

Response

Error Responses