Referência da API

A CaptchaLa fornece uma API RESTful para todas as integrações server-side.

URL base

https://apiv1.captcha.la

Autenticação

Todas as requisições da API exigem headers de autenticação:

X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

WARNING

X-App-Secret é exclusivo do servidor. Nunca o exponha em navegadores, aplicativos móveis ou repositórios públicos.

API de validação no servidor

💡 Use um SDK de servidor para evitar o boilerplate. Encapsula o endpoint, gerencia retries e expõe erros tipados:

• PHP — Captcha-La/captchala-php (中文)
• Go — go get github.com/Captcha-La/captchala-go · README

Depois que o usuário passa pelo CAPTCHA no frontend, seu servidor precisa validar o token devolvido pelo SDK. Abaixo estão os endpoints de validação server-side.

Validação de token no servidor

Valida o pass_token recebido do SDK no frontend (com prefixo pt_). Exige os headers X-App-Key e X-App-Secret.

POST /v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "pt_xxx", "client_ip": "1.2.3.4" }

{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

TIP

Valide data.valid === true e que data.action coincide com o cenário esperado (rejeite se um token de um fluxo pay for apresentado em /login). Os tokens são de uso único.

Token de desafio emitido pelo servidor

Emita um server_token de curta duração a partir do seu backend. O navegador passa esse token ao inicializar um desafio, comprovando que a requisição veio do seu servidor confiável.

Emitir Server Token

Chame este endpoint apenas a partir do seu próprio servidor. Exige X-App-Key + X-App-Secret. A resposta contém um server_token (prefixo sct_) que o frontend encaminha à inicialização do desafio.

POST /v1/server/challenge/issue
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/x-www-form-urlencoded

action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4

{
  "code": 0,
  "data": {
    "server_token": "sct_xxxxxxxxxxxx",
    "expires_in": 300,
    "issued_at": 1713600000
  }
}

Parâmetros do corpo (form-urlencoded)

Campo	Descrição
action	Cenário de negócio, ex.: login, register, pay. Deve coincidir com a action usada na inicialização do desafio.
ttl	Tempo de vida do token em segundos. Padrão 300, máximo 900.
max_uses	Número máximo de vezes que o token pode ser consumido. Padrão 10.
bind_ip	Vincula o token a um IP de cliente. Inicializações a partir de outro IP são rejeitadas.
bind_device_id	Vincula o token a um ID de dispositivo específico.
bind_fingerprint	Vincula o token a uma impressão digital de navegador específica.

Inicializar desafio

Chamada pelo SDK para iniciar um desafio de CAPTCHA. Aceita um server_token opcional emitido por /v1/server/challenge/issue.

Campo	Descrição
app_key	Sua App Key pública.
action	Cenário de negócio. Deve coincidir com a action usada ao emitir o server_token.
server_token	Opcional; obrigatório quando a aplicação tem server_token_required = true.

INFO

Se server_token_required estiver habilitado para esta aplicação no painel, a inicialização do desafio rejeitará requisições que não tragam um server_token válido.

Códigos de erro

Código	Descrição
invalid_app_key	App Key inválida
invalid_app_secret	App Secret inválido
challenge_expired	Desafio expirado
challenge_not_found	Desafio não encontrado
invalid_answer	Resposta inválida
token_expired	Token expirado
token_already_used	Token já usado
token_not_found	Token não encontrado
quota_exceeded	Cota excedida
rate_limited	Taxa limitada
rate_limit_exceeded	Excesso de requisições de emissão para esta aplicação. Aguarde e tente novamente.