Referência da API

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

URL base

https://apiv1.captcha.la

Só existe uma URL base

Todos os endpoints desta página ficam em apiv1.captcha.la. Os hosts de contingência (bypass.*, fallbackapiv1.*) são alvos de failover que os SDKs acionam sozinhos durante uma queda — apontar sua integração para eles retorna service_online.

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.

bash

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" }

client_ip é opcional, mas recomendado: o IP do usuário final obtido da sua requisição de entrada, usado para verificações de risco adicionais. Pode ser omitido sem problemas.

json

{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "captcha_args": {
      "platform": "web",
      "user_ip": "1.2.3.4",
      "referer": "https://your-site.com/login",
      "pkg": null,
      "solved_at": 1750000000,
      "risk_score": 12
    }
  }
}

O objeto captcha_args é apenas informativo (para seus logs / análise de risco):

Campo	Descrição
`platform`	Plataforma de onde o desafio foi resolvido.
`user_ip`	IP registrado no momento da resolução.
`referer`	URL de referência da página do desafio.
`pkg`	Identificador de pacote do app (mobile), quando aplicável.
`solved_at`	Timestamp Unix da resolução.
`risk_score`	Pontuação de risco da sessão de resolução.

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.

bash

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

json

{
  "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.

Endpoints de contingência offline

A CaptchaLa mantém um serviço de contingência em hosts separados para que a verificação continue funcionando quando a API principal está inacessível:

Host	Chamado por	Função
`bypass.captchala.com` · `bypass.captcha-cdn.net`	SDK web / nativo (lado do usuário final)	Faz a verificação offline e emite um pass token `offline_` enquanto a API principal está fora
`fallbackapiv1.captchala.com` · `fallbackapiv1.captcha-cdn.net`	SDKs de servidor	Valida tokens `offline_` (`POST /api/validate`)

São alvos de failover, não uma API alternativa. Os SDKs migram para eles por conta própria, apenas depois de a API principal realmente falhar, e voltam assim que ela se recupera. Nada na sua configuração deve apontar para esses hosts.

`service_online` (HTTP 503)

json

{ "code": -1, "error": "service_online", "message": "Main API is online, please use main API" }

Você recebe isso enquanto a API principal está no ar: o serviço de contingência só atende durante uma queda. A requisição chegou em bypass.* em vez de https://apiv1.captcha.la — corrija a URL; repetir não adianta.

Causas comuns:

Causa	Correção
Opção `apiServer` do SDK apontando para um host bypass	Volte para `https://apiv1.captcha.la` ou remova a opção e deixe o SDK escolher
`bypassServers` sobrescrito manualmente	Remova a sobrescrita, a menos que tenhamos passado hosts específicos
Cliente HTTP próprio copiou uma URL bypass (ex.: das devtools durante um incidente)	Chame `https://apiv1.captcha.la` e deixe o failover com o SDK — o serviço de contingência não aceita tráfego normal de desafio
Load balancer / proxy / DNS reescrevendo o host da API	Aponte o upstream de volta para `apiv1.captcha.la`

TIP

A validação no servidor também não precisa do host de contingência: POST /v1/validate em apiv1.captcha.la resolve, e os SDKs PHP / Go tratam tokens offline_ na API de backup automaticamente.

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.
`service_online`	A requisição chegou ao serviço de contingência offline enquanto a API principal está no ar. Use `https://apiv1.captcha.la` — veja Endpoints de contingência offline.

Referência da API ​

URL base ​

Autenticação ​

API de validação no servidor ​

Validação de token no servidor ​

Token de desafio emitido pelo servidor ​

Emitir Server Token ​

Parâmetros do corpo (form-urlencoded) ​

Inicializar desafio ​

Endpoints de contingência offline ​

service_online (HTTP 503) ​

Códigos de erro ​

Referência da API

URL base

Autenticação

API de validação no servidor

Validação de token no servidor

Token de desafio emitido pelo servidor

Emitir Server Token

Parâmetros do corpo (form-urlencoded)

Inicializar desafio

Endpoints de contingência offline

`service_online` (HTTP 503)

Códigos de erro