Tratamento de CAPTCHA

Uma instância pode exigir a solução de um CAPTCHA em um pequeno conjunto de operações sensíveis a abuso. O cliente lê o provedor selecionado e a chave de site dele na descoberta da instância, renderiza o widget desse provedor e envia a solução na requisição protegida.

Descobrindo o provedor

GET /.well-known/fluxer publica o objeto de configuração de CAPTCHA dentro do objeto de descoberta da instância. O campo provider nomeia o provedor de CAPTCHA selecionado, e hcaptcha_site_key ou turnstile_site_key é a chave de site desse provedor. A outra chave é nula, e ambas são nulas quando provider é none.

O valor none significa que a instância não desafia nenhuma operação. Uma operação protegida então prossegue sem cabeçalho de CAPTCHA. Os valores hcaptcha e turnstile nomeiam o provedor cujo widget o cliente deve renderizar.

Operações protegidas

As operações a seguir verificam um CAPTCHA enquanto a descoberta informar um provider diferente de none.

Método	Rota	Operação
POST	/v1/auth/register	Registrar uma conta
POST	/v1/auth/login	Entrar com senha
POST	/v1/auth/forgot	Solicitar recuperação de senha
POST	/v1/oauth2/applications	Criar aplicação
POST	/v1/gifts/{code}/redeem	Resgatar presente
POST	/v1/users/@me/channels	Criar canal privado
PUT	/v1/channels/{channel_id}/recipients/{user_id}	Adicionar destinatário a mensagem direta em grupo

Criar canal privado é protegido apenas no caminho de mensagem direta em grupo, em que o corpo da requisição traz o membro recipients. Uma requisição de mensagem direta individual omite o campo e nunca é protegida.

Isenção

O Decoding Chat pula a verificação em três casos, e a operação então prossegue sem cabeçalho de CAPTCHA. A política de contas da instância concede a capacidade captcha_exempt ao endereço de e-mail da conta autenticada. A conta autenticada possui o sinalizador APP_STORE_REVIEWER. O corpo da requisição traz um email pertencente a uma conta que possui esse sinalizador. A descoberta não informa isenções, então o cliente precisa saber lidar com um desafio em toda operação protegida.

Cabeçalhos da requisição

Campo	Tipo	Descrição
X-Captcha-Token?1	string	A solução emitida pelo widget do provedor
X-Captcha-Type?2	string	O provedor que produziu a solução, aceitando hcaptcha ou turnstile

¹ Um valor ausente ou vazio em operação protegida retorna 400 CAPTCHA_REQUIRED

² Um valor ausente seleciona o provedor configurado na instância, e o mesmo vale para qualquer valor diferente de hcaptcha ou turnstile. Nomear um provedor para o qual a instância não tem chave secreta retorna 400 INVALID_CAPTCHA.

O handshake de repetição

Envie a requisição sem cabeçalhos de CAPTCHA. Ao receber 400 CAPTCHA_REQUIRED, obtenha uma solução pelo widget do provedor selecionado usando a chave de site divulgada. Repita a mesma requisição com X-Captcha-Token contendo a solução e, opcionalmente, X-Captcha-Type com o provedor.

Uma solução aceita permite que a operação prossiga. Uma solução recusada retorna 400 INVALID_CAPTCHA.

Cada solução serve uma única vez

O provedor trata uma solução já resgatada como inválida. O cliente obtém uma nova solução antes de repetir depois de INVALID_CAPTCHA e NÃO DEVE reenviar o valor anterior de X-Captcha-Token.

Verificação pelo provedor

Uma solução recusada ou um provedor indisponível retornam 400 INVALID_CAPTCHA. A resposta não distingue entre essas causas.

Códigos de erro

Código	Status	Descrição
CAPTCHA_REQUIRED1	400	A operação é protegida e a requisição não traz solução
INVALID_CAPTCHA	400	O provedor recusou a solução, ou a verificação não pôde ser concluída

¹ Enviar verificação de telefone também responde com este código quando a checagem de risco do Decoding Chat sobre a tentativa de telefone decide que a requisição precisa de CAPTCHA. Essa operação não é protegida e não aceita solução, então repeti-la com X-Captcha-Token nunca resolve

Os dois códigos estão definidos no registro de códigos de erro da API, e o corpo de cada um é o envelope comum de resposta de erro.