---
title: Referência da API
---

# 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`](https://github.com/Captcha-La/captchala-php) ([中文](https://github.com/Captcha-La/captchala-php/blob/main/README_zh.md))
> - **Go** — `go get github.com/Captcha-La/captchala-go` · [README](https://github.com/Captcha-La/captchala-go)

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 {#server-token}

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.
:::

## 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. |