Skip to content

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:

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.

Parâmetros da requisição ​

ParâmetroObrigatórioDescrição
pass_tokenSimToken retornado pelo SDK do frontend
client_ipNãoIP do usuário final obtido da sua requisição de entrada
keep_tokenNãotrue = verificar sem consumir o token (padrão false)
expected_actionNãoAçã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_hostnameNãoHostname (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.

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
    },
    "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). null se desconhecido.
  • challenge_ts — quando o desafio foi resolvido, em ISO 8601 UTC. null se 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 exemplo automation, 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:

json
{ "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 resolvido
  • referer — URL da página de resolução (web); null no nativo
  • pkg — pacote do app / bundle id (nativo); null na web
  • solved_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:

PrefixoEmitido quando/v1/validate retornaTratamento recomendado
pt_Verificação aprovada normalmentevalid: true (uso único)Aceitar
dg_Cota do plano esgotada (modo degradado)valid: false, degraded: true, reasonDecisão sua — veja abaixo
offline_API principal inacessível; emitido pelo bypass workerVerificado automaticamente na API de backup ao usar um SDK de servidorAceitar após a verificação de backup
co_API principal e backup inacessíveis; gerado no clienteNão pode ser verificado no servidorAplique 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/validate do seu servidor retorna:
json
{
  "code": 0,
  "data": {
    "valid": false,
    "degraded": true,
    "reason": "quota_exhausted",
    "expired": false
  }
}

Propriedades principais:

  • valid é sempre false para tokens degradados — seguro por padrão. Se seu código verifica apenas valid, nada muda para você.
  • Deixar a requisição passar é decisão sua: aceite valid || degraded para 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) e result.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.

ComportamentoX-App-KeyX-App-Secret
Sempre aprovatest_pass_7f3c9a2e5b18d4f6test_secret_pass_c41e8b0d27a95f3e
Sempre falhatest_fail_2d9e6b4a0c7f1835test_secret_fail_9b5f03e7d1a46c28
  • Sempre aprova — qualquer pass_token não vazio retorna valid: true. A resposta tem os mesmos campos de um sucesso real, mais test: true, para que seu código de parsing seja exercitado:
json
{
  "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_token não vazio retorna:
json
{ "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 um pass_token vazio retorna missing_token, como em apps reais.
  • keep_token, expected_action e expected_hostname sã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.test em 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.

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) ​

CampoDescrição
actionCenário de negócio, ex.: login, register, pay. Deve coincidir com a action usada na inicialização do desafio.
ttlTempo de vida do token em segundos. Padrão 300, máximo 900.
max_usesNúmero máximo de vezes que o token pode ser consumido. Padrão 10.
bind_ipVincula o token a um IP de cliente. Inicializações a partir de outro IP são rejeitadas.
bind_device_idVincula o token a um ID de dispositivo específico.
bind_fingerprintVincula 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.

CampoDescrição
app_keySua App Key pública.
actionCenário de negócio. Deve coincidir com a action usada ao emitir o server_token.
server_tokenOpcional; 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:

HostChamado porFunção
bypass.captchala.com · bypass.captcha-cdn.netSDK 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.netSDKs de servidorValida 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:

CausaCorreção
Opção apiServer do SDK apontando para um host bypassVolte para https://apiv1.captcha.la ou remova a opção e deixe o SDK escolher
bypassServers sobrescrito manualmenteRemova 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 APIAponte 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ódigoDescrição
invalid_app_keyApp Key inválida
invalid_app_secretApp Secret inválido
challenge_expiredDesafio expirado
challenge_not_foundDesafio não encontrado
invalid_answerResposta inválida
token_expiredToken expirado
token_already_usedToken já usado
token_not_foundToken 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_exceededCota excedida
rate_limitedTaxa limitada
rate_limit_exceededExcesso 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_onlineA 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.

MIT-licensed examples · CaptchaLa is operated independently