Primeros pasos con la API

La API REST se encuentra bajo /api/v1. El cliente web usa los mismos endpoints que los integradores y ningún endpoint privado, así que todo lo que puede hacer la consola de administración está disponible a través de la API.

La referencia se genera a partir del código: el documento OpenAPI 3.1 en /api/v1/openapi.json y la interfaz de Scalar en /api/docs. De forma predeterminada, ambos requieren que quien llama esté autenticado (http.docs puede ser authenticated, public o disabled). Cada operación indica el permiso que necesita como su ámbito (scope).

Autenticación

Hay dos tipos de credenciales. Ambas se envían de la misma manera:

Authorization: Bearer <access token or API key>

Token de acceso (usuarios)

Inicie sesión con correo electrónico y contraseña:

curl -sS https://pbx.example.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"...","client":"my script"}'

La respuesta:

{
  "access_token": "eyJhbGciOiJFZERTQSIs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "mpbx_rt_...",
  "refresh_expires_at": 1790000000,
  "session_id": "0199b5a2-6c1e-7d3a-9f00-3c8e1b2a4d55"
}

• El token de acceso es un JWT EdDSA de vida corta (15 minutos de forma predeterminada).
• Si la cuenta tiene activada la autenticación de dos factores y no envió totp_code, recibe 401 con el código MPBX-AUTH-TOTP-REQUIRED después de una contraseña correcta. Repita la solicitud con "totp_code":"123456".
• Renueve el token con POST /api/v1/auth/refresh y {"refresh_token":"..."}. Cada token de renovación funciona una sola vez. Presentar uno ya usado termina toda la sesión (MPBX-AUTH-REFRESH-REUSED), así que realice como máximo una renovación a la vez por sesión y guarde siempre el token más reciente.
• POST /api/v1/auth/logout termina la sesión.
• Los navegadores pueden pedir "refresh_delivery":"cookie", que guarda el token de renovación en una cookie HttpOnly en lugar del cuerpo de la respuesta.

Claves de API (integraciones)

Una clave de API tiene la forma mpbx_k1_<company>_<id>_<secret> y se envía directamente como token de portador. No hay un intercambio de clave por token. Una clave actúa en nombre del usuario que la creó y solo tiene los ámbitos con los que se emitió, intersecados con los permisos actuales de ese usuario, así que si se degrada al usuario, la clave se reduce de inmediato. Las claves no pueden crear claves. La clave completa se muestra una sola vez, al crearla.

Quién soy

GET /api/v1/me devuelve quien llama, la empresa y cada permiso que posee con su alcance (toda la empresa o una lista de departamentos). Úselo para verificar lo que puede hacer una credencial.

Selección de empresa

La empresa siempre proviene de la credencial, nunca de la URL ni del cuerpo. Un administrador del sistema (un System Owner o System Admin, con un token de ámbito de sistema) selecciona la empresa en la que trabajará con el encabezado X-Mpbx-Tenant: <company id>. Esa acción queda registrada en auditoría.

Convenciones

• Paginación: ?limit=50&cursor=.... limit va de 1 a 200 (predeterminado 50); un valor fuera de rango es un 400. La respuesta es {"items":[...],"next_cursor":"..."}, y next_cursor no aparece en la última página. Los cursores están ligados al filtro y al orden para los que se emitieron.
• Filtrado y orden: filter=field:op:value, repetible, con los operadores eq ne gt gte lt lte contains starts_with in, y sort=-created_at,name. Solo se aceptan los campos que declara el endpoint.
• Concurrencia optimista: el GET de un recurso devuelve un ETag. PATCH, PUT y DELETE requieren If-Match con ese valor: si falta es 428 (MPBX-PRECONDITION-REQUIRED), si está obsoleto es 412 (MPBX-PRECONDITION-FAILED).
• PATCH: solo cambian los campos presentes. null significa sin cambios, exactamente igual que un campo ausente. Para borrar un campo de texto, envíe una cadena vacía.
• Idempotencia: envíe Idempotency-Key (de 1 a 255 caracteres ASCII visibles; un UUID sirve) en un POST para que sea seguro reintentarlo. Una repetición de la misma persona que llama, con el mismo cuerpo, reproduce la respuesta 2xx guardada con Idempotent-Replayed: true. La misma clave con una solicitud distinta da 422 (MPBX-IDEMPOTENCY-KEY-REUSED). La misma clave mientras la primera solicitud todavía se ejecuta da 409 (MPBX-IDEMPOTENCY-IN-PROGRESS). Las rutas que llevan secretos (todas las rutas /auth/*, la creación de usuarios, los restablecimientos de contraseña y las cargas de certificados) ignoran el encabezado.

Errores

Cada error es application/problem+json (RFC 9457):

{
  "type": "https://mpbx.example/errors/MPBX-NOT-FOUND",
  "title": "Not Found",
  "status": 404,
  "detail": "extension 1001 does not exist",
  "code": "MPBX-NOT-FOUND",
  "errors": [{"field": "filter", "message": "unknown field `colour`"}]
}

code es el valor estable y legible por máquina. Tome decisiones con base en code, no en detail. errors aparece solo cuando hay campos inválidos. El URI de type usa un host de marcador de posición (mpbx.example) hasta que se decida el dominio real. Retry-After se envía con 429 y 503. Los errores internos nunca incluyen su mensaje. Vea Códigos de error para los códigos de cada área.

Ejemplos que encontrará primero:

Código	Estado	Significado
MPBX-AUTH-INVALID-CREDENTIALS	401	El inicio de sesión falló. Un solo código para cualquier motivo, para no revelar qué cuentas existen.
MPBX-AUTH-TOKEN-EXPIRED	401	El token de acceso venció. Renuévelo.
MPBX-APIKEY-INVALID	401	La clave de API es desconocida, fue revocada, venció o es incorrecta.
MPBX-RBAC-FORBIDDEN	403	No tiene el permiso que necesita la operación. GET /api/v1/me indica lo que posee.
MPBX-RATE-LIMITED	429	Demasiados intentos de inicio de sesión, renovación o TOTP. Espere el valor de Retry-After.
MPBX-INVALID-QUERY, MPBX-INVALID-CURSOR	400	Un filter, sort, limit o cursor no es válido.

Límites de frecuencia

Las rutas de autenticación tienen límite de frecuencia por red de cliente y por minuto: 10 inicios de sesión, 60 renovaciones y 10 llamadas TOTP de forma predeterminada (http.login_rate_per_min, http.refresh_rate_per_min, http.totp_rate_per_min). Las cuentas también se bloquean después de varios inicios de sesión fallidos (5 fallos en 15 minutos de forma predeterminada). Algunas otras rutas tienen sus propios límites, por ejemplo 10 solicitudes de llamada con un clic por minuto y por usuario, 60 solicitudes de control de llamadas por minuto y por usuario y 120 mensajes de chat por minuto y por usuario. Cada límite responde 429 con MPBX-RATE-LIMITED y un encabezado Retry-After. La mayoría de las demás rutas no tienen límite por clave ni por usuario; un administrador puede restringir quién llega a la API según la dirección (vea Seguridad y acceso a la red).

Eventos e integraciones

• Webhooks salientes: MonoPbx puede llamar a su URL con los eventos, con solicitudes firmadas, reintentos y mensajes muertos. Vea Webhooks.
• WebSocket de eventos: para un flujo en vivo en un cliente, vea el WebSocket de eventos.
• Llamada con un clic: POST /api/v1/calls/click-to-call hace sonar uno o todos los dispositivos del usuario que inició sesión y, cuando uno contesta, marca el destino como ese usuario a través del plan de marcación. Envíe un Idempotency-Key.

Lo que todavía no está disponible

• Los SDK de cliente no están publicados. Los clientes en TypeScript y Dart se generan a partir del documento OpenAPI dentro del repositorio.