Referência da API
A CaptchaLa fornece uma API RESTful para todas as integrações server-side.
URL base
https://apiv1.captcha.laSó 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_SECRETWARNING
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" }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.
Parâmetros da requisição
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
pass_token | Sim | Token retornado pelo SDK do frontend |
client_ip | Não | IP do usuário final obtido da sua requisição de entrada |
keep_token | Não | true = verificar sem consumir o token (padrão false) |
expected_action | Não | Ação que você espera para este endpoint, por exemplo login. Se definido e o token tiver sido emitido para outra ação, a resposta é valid: false com error: "action_mismatch". Correspondência exata, diferenciando maiúsculas de minúsculas. |
expected_hostname | Não | Hostname (web) ou pacote do app / bundle id (nativo) que você espera, por exemplo www.example.com. Aceita uma string separada por vírgulas ou um array; *.example.com corresponde a qualquer subdomínio (não ao domínio raiz). Não diferencia maiúsculas de minúsculas. Se definido e o token tiver sido resolvido em outro lugar — ou a origem não puder ser determinada — a resposta é valid: false com error: "hostname_mismatch". |
Omitir expected_action / expected_hostname mantém exatamente o comportamento anterior. Quando uma divergência é reportada, o token ainda é consumido (a menos que keep_token seja true), portanto não pode ser reutilizado.
{
"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
},
"hostname": "your-site.com",
"challenge_ts": "2025-06-15T15:06:40Z",
"risk_level": "low",
"risk_labels": []
}
}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) — ou simplesmente passe expected_action / expected_hostname e deixe a API fazer isso. Os tokens são de uso único.
Campos adicionais
Adicionados às respostas bem-sucedidas (todos os campos existentes permanecem inalterados):
hostname— hostname da página onde o desafio foi resolvido (web), ou o pacote do app / bundle id (nativo).nullse desconhecido.challenge_ts— quando o desafio foi resolvido, em ISO 8601 UTC.nullse desconhecido.risk_level— nível de risco no momento da resolução:low/medium/high/critical.risk_labels— categorias de risco gerais observadas nesta sessão, por exemploautomation,proxy,velocity,ip_reputation,device,inconsistency. Array vazio quando não há nada notável. Novos rótulos podem ser adicionados com o tempo — trate valores desconhecidos como informativos.
São sinais suaves para seus próprios logs e decisões de risco; o token já foi aceito.
Resposta de divergência:
{ "code": 0, "data": { "valid": false, "error": "action_mismatch" } }captcha_args
captcha_args devolve o contexto registrado no momento da resolução — para seus logs / sua própria análise de risco:
platform—web/android/ios/flutter/windows/ …user_ip— o IP do usuário final visto quando o desafio foi resolvidoreferer— URL da página de resolução (web);nullno nativopkg— pacote do app / bundle id (nativo);nullna websolved_at— horário de conclusão da resolução (segundos unix)risk_score— pontuação de risco no momento da resolução (0-100, maior = mais arriscado)
Tipos de token
O SDK pode entregar ao seu frontend diferentes tipos de token, dependendo das condições do serviço. O prefixo diz tudo:
| Prefixo | Emitido quando | /v1/validate retorna | Tratamento recomendado |
|---|---|---|---|
pt_ | Verificação aprovada normalmente | valid: true (uso único) | Aceitar |
dg_ | Cota do plano esgotada (modo degradado) | valid: false, degraded: true, reason | Decisão sua — veja abaixo |
offline_ | API principal inacessível; emitido pelo bypass worker | Verificado automaticamente na API de backup ao usar um SDK de servidor | Aceitar após a verificação de backup |
co_ | API principal e backup inacessíveis; gerado no cliente | Não pode ser verificado no servidor | Aplique seus próprios controles de risco (limites de taxa etc.) |
Modo degradado (cota esgotada)
Quando um app esgota sua cota mensal (e a cobrança de excedente não está disponível), o widget não interrompe o fluxo do usuário final. Em vez de exibir um erro, o SDK conclui imediatamente com um token dg_:
- O usuário final não vê nenhum erro — seu formulário é enviado normalmente.
- O
/v1/validatedo seu servidor retorna:
{
"code": 0,
"data": {
"valid": false,
"degraded": true,
"reason": "quota_exhausted",
"expired": false
}
}Propriedades principais:
validé semprefalsepara tokens degradados — seguro por padrão. Se seu código verifica apenasvalid, nada muda para você.- Deixar a requisição passar é decisão sua: aceite
valid || degradedpara manter as conversões enquanto você faz upgrade do plano, ou rejeite e mostre seu próprio fallback. - Tokens
dg_são assinados com HMAC por app e expiram após 5 minutos. Emiti-los não consome cota e nunca é cobrado. - Os SDKs de servidor expõem isso como
isDegraded()/getDegradedReason()(PHP) eresult.Degraded/result.DegradedReason(Go).
INFO
Assinaturas expiradas nunca acionam o modo degradado — elas voltam automaticamente ao plano Free e continuam atendendo dentro da cota gratuita. O modo degradado cobre apenas o uso além da cota do seu plano.
Chaves de teste
Use estes pares de chaves públicas para testar o tratamento de /v1/validate do seu servidor — em CI, staging ou desenvolvimento local — sem criar um app nem resolver um CAPTCHA. Elas funcionam com os SDKs de servidor exatamente como uma app key / secret real.
| Comportamento | X-App-Key | X-App-Secret |
|---|---|---|
| Sempre aprova | test_pass_7f3c9a2e5b18d4f6 | test_secret_pass_c41e8b0d27a95f3e |
| Sempre falha | test_fail_2d9e6b4a0c7f1835 | test_secret_fail_9b5f03e7d1a46c28 |
- Sempre aprova — qualquer
pass_tokennão vazio retornavalid: true. A resposta tem os mesmos campos de um sucesso real, maistest: true, para que seu código de parsing seja exercitado:
{
"code": 0,
"data": {
"valid": true,
"test": true,
"challenge_id": null,
"action": "test",
"uid": null,
"captcha_args": {
"platform": "web",
"user_ip": null,
"referer": null,
"pkg": null,
"solved_at": 1750000000,
"risk_score": 0
},
"hostname": null,
"challenge_ts": "2025-06-15T15:06:40Z",
"risk_level": "low",
"risk_labels": []
}
}- Sempre falha — qualquer
pass_tokennão vazio retorna:
{ "code": 0, "data": { "valid": false, "error": "test_always_fail", "test": true } }Observações:
- O secret deve corresponder à sua chave; um secret errado ou trocado retorna
invalid_app_secret, e umpass_tokenvazio retornamissing_token, como em apps reais. keep_token,expected_actioneexpected_hostnamesão ignorados para chaves de teste.- Chaves de teste nunca criam registros, nunca contam para nenhuma cota e nunca são cobradas. Não podem ser usadas como credenciais de um app real.
- Verifique
data.testem produção e rejeite-o — ou simplesmente garanta que chaves de teste nunca sejam configuradas em produção. - Por enquanto, apenas no servidor. Estas chaves testam a chamada de validação do seu backend; não são sitekeys de frontend e não podem ser usadas para renderizar o widget. Sitekeys de teste para frontend serão disponibilizadas futuramente.
- Tokens que começam com
pt_test_são reservados para testes e sempre rejeitados por apps reais (valid: false,error: "token_invalid").
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.
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)
{ "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 |
token_invalid | /v1/validate: o token não é válido para esta aplicação (por exemplo, um token de teste pt_test_ enviado a uma aplicação real). |
test_always_fail | /v1/validate: retornado pela chave de teste que sempre falha. |
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. |
action_mismatch | /v1/validate: expected_action foi definido e o token pertence a outra ação. |
hostname_mismatch | /v1/validate: expected_hostname foi definido e o token foi resolvido em outro hostname / pacote (ou desconhecido). |
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. |