Vincular un jugador a su cuenta de Lingara

Versión de la API 2026-10-virile-dragon

put https://api.getlingara.com/v1/embed/players/{player_ref}/link

Vincula a uno de tus jugadores con la cuenta de Lingara que acaba de dar acceso a tu app. Llámala con el token delegado que tu servidor recibió para esa cuenta, nunca con el token propio de tu cliente. Desde entonces los tokens del jugador actúan como la cuenta, hasta donde lo permita la concesión: pide events:read o no sabrás nada del jugador después del vínculo. Los planes terminados pasan a la cuenta; un plan que aún se está escribiendo se queda hasta que vuelvas a llamar. Se puede repetir sin riesgo: una repetición responde existing y mueve lo que antes no se pudo mover. Vincular no te cuesta nada.

Ámbitos embed:play

Parámetros

Lingara-Versionheaderstringopcional: La versión de la API con la que se responde a esta solicitud. Sin ella, un token de acceso recibe la versión a la que está vinculado su cliente, y una solicitud sin token recibe la versión actual. La versión aún en desarrollo solo se alcanza nombrándola aquí. Una versión desconocida responde 400 con el código api_version_unknown. GET /v1/versions enumera las versiones.
player_refpathstringobligatorio: El player_ref con el que emitiste los tokens del jugador, codificado con porcentajes: guild/42 es guild%2F42.

Respuestas

200 El vínculo del jugador

statusLinkStatusobligatorio
subjectstringobligatorio: El lgr_sub_ de la cuenta: lo que llevan los eventos de este jugador a partir de ahora.
previous_subjectstringobligatorio: El lgr_sub_ del invitado: lo que conservan los eventos anteriores del jugador. Dirige ambos al mismo player_ref.
linked_atstringobligatorio: Cuándo se creó el vínculo. En una respuesta existing, la hora de la primera llamada.
scopesarray of stringobligatorio: Lo máximo que puede tener ahora un token para este jugador: lo que concedió la cuenta, de los permisos que puede llevar el token de un jugador.
carriedobjectobligatorio: Filas que esta llamada movió a la cuenta, por tabla. Solo aparecen las tablas con un recuento.
keptobjectobligatorio: Filas que esta llamada dejó con el invitado, por tabla: un plan que aún se está escribiendo, o una fila que la cuenta ya tenía. Vuelve a llamar cuando lesson_plans aquí tenga un plan terminado.

Errores

402application/json: Se rechazó la llamada de un cliente con facturación por uso antes de que gastara nada. spend_cap_reached: el cliente o su cuenta ha alcanzado su límite de gasto mensual; sube el límite en la página Integraciones. metered_billing_inactive: la facturación por uso no está activa para esta cuenta; configúrala o actualiza el método de pago en la página Integraciones.
410application/json: La versión de la API con la que se responde a esta solicitud se ha retirado. Envía una versión admitida en Lingara-Version o vincula el cliente a otra versión.
4XXapplication/json: La solicitud fue rechazada. code indica el motivo y error lo explica con palabras.
503application/json · text/plain: El servicio no está disponible temporalmente; vuelve a intentarlo tras el número de segundos indicado en Retry-After. Durante el mantenimiento, el cuerpo es texto sin formato en lugar del sobre de error.
5XXapplication/json: La solicitud fue rechazada. code indica el motivo y error lo explica con palabras.

codestringobligatorio: Por qué se rechazó la solicitud, como un código estable con el que ramificar: por ejemplo insufficient_scope (403), rate_limited (429) y, para un cliente con facturación por uso, spend_cap_reached (402) y metered_billing_inactive (402).
errorstringobligatorio

Ejemplo

curl -X PUT "https://api.getlingara.com/v1/embed/players/$PLAYER_REF/link" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

¿Prefieres una biblioteca? Consulta la sección Bibliotecas.

Si una traducción y la referencia en inglés difieren, prevalece la referencia en inglés.