Vincular um jogador à sua conta Lingara

Versão da API 2026-10-virile-dragon

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

Vincula um dos teus jogadores à conta Lingara que acabou de dar acesso à tua app. Chama-a com o token delegado que o teu servidor recebeu para essa conta, nunca com o token próprio do teu cliente. A partir daí, os tokens do jogador atuam como a conta, até onde a concessão permitir: pede events:read ou não saberás nada do jogador depois do vínculo. Os planos concluídos passam para a conta; um plano ainda em escrita fica até voltares a chamar. É seguro repetir: uma repetição responde existing e move o que antes não podia ser movido. Vincular não te custa nada.

Âmbitos embed:play

Parâmetros

Lingara-Versionheaderstringopcional: A versão da API com que responder a este pedido. Sem ela, um token de acesso recebe a versão a que o seu cliente está associado, e um pedido sem token recebe a versão atual. A versão ainda em desenvolvimento só é alcançada indicando-a aqui. Uma versão desconhecida responde 400 com o código api_version_unknown. GET /v1/versions lista as versões.
player_refpathstringobrigatório: O player_ref com que emitiu os tokens do jogador, codificado em percentagem: guild/42 é guild%2F42.

Respostas

200 O vínculo do jogador

statusLinkStatusobrigatório
subjectstringobrigatório: O lgr_sub_ da conta: o que os eventos deste jogador levam a partir de agora.
previous_subjectstringobrigatório: O lgr_sub_ do convidado: o que os eventos anteriores do jogador mantêm. Encaminha ambos para o mesmo player_ref.
linked_atstringobrigatório: Quando o vínculo foi criado. Numa resposta existing, a hora da primeira chamada.
scopesarray of stringobrigatório: O máximo que um token para este jogador pode ter agora: o que a conta concedeu, entre os âmbitos que o token de um jogador pode levar.
carriedobjectobrigatório: Linhas que esta chamada moveu para a conta, por tabela. Só aparecem tabelas com uma contagem.
keptobjectobrigatório: Linhas que esta chamada deixou com o convidado, por tabela: um plano ainda em escrita, ou uma linha que a conta já tinha. Volta a chamar quando lesson_plans aqui tiver um plano concluído.

Erros

402application/json: A chamada de um cliente com faturação por utilização foi recusada antes de gastar o que quer que fosse. spend_cap_reached: o cliente ou a sua conta atingiu o limite de gastos mensal; aumente o limite na página Integrações. metered_billing_inactive: a faturação por utilização não está ativa para esta conta; configure-a ou atualize o método de pagamento na página Integrações.
410application/json: A versão da API com que este pedido é respondido foi descontinuada. Envie uma versão suportada em Lingara-Version, ou associe o cliente a outra versão.
4XXapplication/json: O pedido foi recusado. code indica o motivo e error descreve-o por palavras.
503application/json · text/plain: O serviço está temporariamente indisponível; tente novamente após o número de segundos indicado em Retry-After. Durante a manutenção, o corpo é texto simples em vez do envelope de erro.
5XXapplication/json: O pedido foi recusado. code indica o motivo e error descreve-o por palavras.

codestringobrigatório: O motivo pelo qual o pedido foi recusado, como um código estável para ramificar a lógica: por exemplo insufficient_scope (403), rate_limited (429) e, para um cliente com faturação por utilização, spend_cap_reached (402) e metered_billing_inactive (402).
errorstringobrigatório

Exemplo

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

Prefere uma biblioteca? Veja a secção Bibliotecas.

Se uma tradução e a referência em inglês divergirem, prevalece a referência em inglês.