ReferenciaAPI del servidor RTC
URL base: https://api.rtc.champrep.com
Esta referencia abarca las rutas de integración compatibles con las clavesAPI de proyecto de RTC. El inicio de sesión en la consola, la configuración de la organización, la administración de claves y las operaciones de administración de la plataforma no son rutas de integración con claves de servidor. Géstelas a través de la interfaz de usuario adecuada en lugar de copiar los tokens de sesión del navegador en scripts.
Enviar Authorization: Bearer YOUR_RTC_API_KEY y, para los cuerpos JSON,
Content-Type: application/json. Los ejemplos utilizan marcadores de posición, nunca credenciales válidas. Las claves siguen estando restringidas al acceso de su proyecto y del plan actual.
Convenciones de solicitud y respuesta
Sección titulada «Convenciones de solicitud y respuesta»- Los ID son cadenas UUID. Utilice los ID devueltos por RTC, no los nombres de visualización.
- Los nombres se recortan y admiten entre 1 y 80 caracteres.
- Los cuerpos JSON tienen un límite de 64 KiB y rechazan los campos desconocidos.
- Los puntos finales de lista devuelven matrices JSON, con los más recientes en primer lugar.
?limit(1-200) establece el tamaño de la página; cuando existen más elementos, elX-Next-CursorEl encabezado de respuesta contiene el cursor que se debe devolver como?cursor. - No confíe en campos de respuesta no documentados ni construya URL de medios o almacenamiento.
- Las mutaciones no ofrecen un contrato general de idempotencia-clave. Concilie los resultados antes de volver a intentarlo tras un tiempo de espera agotado o una pérdida de conexión.
Resumen de métodos
Sección titulada «Resumen de métodos»| Método y ruta | Ámbito requerido | Resultado |
|---|---|---|
GET /v1/projects | Cualquier clave de proyecto válida | Matriz filtrada por proyecto |
GET /v1/rooms | rooms:read | Matriz de salas |
POST /v1/rooms | rooms:write | 201, sala creada |
POST /v1/rooms/{roomId}/end | rooms:write | { "ended": true } |
POST /v1/rooms/{roomId}/tokens | tokens:write | Conjunto de credenciales de los participantes |
GET /v1/recordings | recordings:read | Matriz de grabaciones |
POST /v1/recordings | recordings:write | 202, grabación en cola |
POST /v1/recordings/{recordingId}/stop | recordings:write | { "stopping": true } |
POST /v1/recordings/{recordingId}/tracks/{trackId}/download | recordings:read | URL de descarga temporal |
POST /v1/recordings/{recordingId}/transcript | recordings:write | 202, se solicita la transcripción (transcripción) |
GET /v1/recordings/{recordingId}/transcript | recordings:read | La transcripción en formato JSON, o un archivo con ?format=vtt, srt o txt |
GET /v1/transcripts | recordings:read | Sus transcripciones y su estado, sin texto |
GET /v1/usage | Cualquier clave de proyecto válida | Uso completado y asignaciones |
GET /v1/webhooks/endpoints, GET /v1/webhooks/deliveries | webhooks:read | Puntos finales y el registro de entrega (webhooks) |
POST, PATCH /v1/webhooks/endpoints…, reproducciones y pruebas | webhooks:write | Gestione los puntos de conexión (webhooks) |
POST /v1/join | Ninguno (un token de incorporación) | Conjunto de credenciales del participante (tokens de incorporación) |
GET /v1/error-codes | Ninguna | El Catálogo de códigos de error |
Las respuestas correctas utilizan 200 salvo que se indique lo contrario. Ambas rutas de lectura sin ámbito nombrado siguen requiriendo una clave de proyecto válida y no caducada, así como acceso al servicio.
Proyectos y salas
Sección titulada «Proyectos y salas»GET /v1/projects devuelve únicamente el proyecto asociado a la clave. La creación del proyecto se lleva a cabo en la consola.
Para POST /v1/rooms, envíe:
{ "projectId": "00000000-0000-4000-8000-000000000001", "name": "Customer conversation", "maxParticipants": 4}projectId y name son obligatorios. maxParticipants es opcional, su valor por defecto es 8 y debe ser un número entero de al menos 2 dentro del límite de su plan. Establezca explícitamente un valor menor si su plan no permite el valor por defecto. La respuesta incluye la nueva sala id, projectId, name, maxParticipants, status
(open), y createdAt.
GET /v1/rooms enumera las salas del proyecto de la clave. Finalice una sala con
POST /v1/rooms/{roomId}/end, sin cuerpo. La finalización bloquea nuevas incorporaciones y desconecta las sesiones activas. Asimismo, solicita que se detengan los trabajos de grabación activos. Si se repite la operación en una sala cerrada, se devuelve 404; no se trata de una respuesta de éxito idempotente. Actualmente no existe ningún método para cambiar el nombre, reabrir o eliminar una sala.
Emisión de credenciales de los participantes
Sección titulada «Emisión de credenciales de los participantes»POST /v1/rooms/{roomId}/tokens acepta un objeto JSON opcional:
{ "canPublish": false }canPublish El valor por defecto es true. Configúrelo en false para un cliente de solo recepción. La sala debe estar abierta y pertenecer al proyecto de la clave. La respuesta contiene:
| Campo | Significado |
|---|---|
token | Token de participante sensible y de corta duración |
participantId | Identificador asignado a esta incorporación |
expiresIn | Duración de las credenciales de acceso en segundos; actualmente, 300 |
url | URL de señalización para el cliente |
iceServers | Configuración de ICE, incluidas las credenciales de retransmisión temporales |
Solicite credenciales nuevas para cada incorporación y reconexión. No dé por sentada la admisión satisfactoria por el mero hecho de la emisión de un token: el estado de la sala, la capacidad y la autorización se comprueban también en el momento de la incorporación. Consulte El flujo completo del cliente.
Tareas de grabación y descargas
Sección titulada «Tareas de grabación y descargas»Comience con POST /v1/recordings y { "roomId": "ROOM_UUID" }. El 202
La respuesta incluye una grabación id y status: "queued"; esto no significa que ya exista un archivo descargable. Una grabación activa duplicada para la misma sala devuelve 409.
GET /v1/recordings devuelve tareas filtradas por proyecto, incluyendo su id,
roomId, status, y tracks. Los metadatos de la pista incluyen id, kind,
source, participantId, y bytes. Utilice los ID de seguimiento devueltos por RTC.
Detenga un trabajo en cola o en grabación con
POST /v1/recordings/{recordingId}/stop, sin cuerpo. Consulte la lista o utilice un
recording.ready webhook para determinar la finalización. Un trabajo que ya se está procesando, está listo o ha fallado no es un objetivo de detención activo y devuelve 404.
Para una pista lista, envíe la información a su /download ruta. La respuesta es
{ "url": "TEMPORARY_DOWNLOAD_URL", "expiresIn": 300 }. Obtenga la URL devuelta sin modificaciones para descargar los bytes del archivo adjunto. La propia URL autoriza el acceso hasta su caducidad; trátela como una credencial. Es no un enlace público permanente. Véase Seguridad y formatos de las grabaciones.
GET /v1/usage devuelve:
| Campo | Significado |
|---|---|
participantSeconds | Suma de las duraciones completadas de las sesiones de los participantes incluidas en el ámbito |
sessions | Número de conexiones completadas dentro del ámbito |
period | all-time para estos contadores de actividad |
billingStatus | Indica una facturación gestionada de forma centralizada |
quotas | Decisiones actuales sobre derechos de acceso para las funciones RTC del espacio de trabajo |
Divida los segundos de los participantes entre 60 para mostrar los minutos de los participantes. Estos contadores de actividad no constituyen una factura ni un recuento de participantes en tiempo real. Una clave de proyecto filtra la actividad hacia su proyecto, mientras que las asignaciones pertenecen al espacio de trabajo propietario. El uso facturable puede actualizarse de forma asíncrona; utilice el sistema central de facturación para obtener información sobre suscripciones y facturas.
Errores
Sección titulada «Errores»Los errores devuelven un JSON error cadena y un valor estable code, que también se envía en el
X-Error-Code encabezado. Envíe RTC-Version: 2026-11-01 para la envoltura de error estructurada. Consulte errores Para las formas y el catálogo de código,
Límites de tasa para 429, y control de versiones para lo que pueda cambiar en /v1. No se base en el texto exacto del mensaje.
| Estado | Comprobación o acción |
|---|---|
400 | Campos obligatorios, UUID, campos desconocidos o rangos de entrada |
401 | Credenciales ausentes, no válidas, revocadas o caducadas |
403 | Ámbito de la clave, acceso al proyecto, derechos del plan o asignación |
404 | Recurso ausente, fuera del ámbito de aplicación o que no se encuentra en el estado requerido |
409 | Operación en conflicto, como una grabación activa |
413 | El cuerpo de la solicitud supera el límite de tamaño |
429 | Limitación de tasa; aplazar el intento y respetar la restricción Retry-After cuando se faciliten |
5xx | Fallo temporal del servicio; vuelva a intentar las lecturas con retrasos y concilie las escrituras |
Nunca compruebe los recursos de otro cliente para distinguir entre una denegación de acceso y una ausencia. Siga Pautas de resolución de problemas.