# Verificar código OTP

> Confere o código digitado pelo usuário contra o `request_id` emitido. Uso único e gratuito.

- **Consulta:** `otp-verify`
- **Categoria:** Mensageria
- **Preço:** Grátis — não debita saldo
- **Endpoint:** `POST https://app.fontedata.com/api/v1/consulta/otp-verify`
- **Autenticação:** header `X-API-Key`
- **Página:** https://fontedata.com/docs/mensageria/otp-verify

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> Confere o código digitado pelo usuário. **Esta consulta é gratuita** — você paga o envio, não a verificação.
>
> O código é de **uso único**: uma verificação bem-sucedida encerra o `request_id`, e uma segunda chamada com o mesmo código é recusada. Cada erro consome uma tentativa; depois de 5 erros o `request_id` trava e é preciso emitir outro.
>
> **Código errado, expirado ou travado não é erro de HTTP.** A resposta vem com `200` e `verificado: false`, e o campo `motivo` diz o que aconteceu. Trate a decisão pelo corpo, não pelo status.

## Requisição

### cURL

```bash
curl -X POST -H "X-API-Key: SUA_CHAVE" \
  "https://app.fontedata.com/api/v1/consulta/otp-verify?request_id=otp_5c1d0e00000000000000000000000000&codigo=123456"
```

### Python

```python
import requests

resp = requests.post(
    "https://app.fontedata.com/api/v1/consulta/otp-verify",
    params={"request_id": "otp_5c1d0e00000000000000000000000000", "codigo": "123456"},
    headers={"X-API-Key": "SUA_CHAVE"},
    timeout=60,
)
resp.raise_for_status()
print(resp.json())
```

### Node.js

```javascript
const url = new URL("https://app.fontedata.com/api/v1/consulta/otp-verify");

url.search = new URLSearchParams({
  "request_id": "otp_5c1d0e00000000000000000000000000",
  "codigo": "123456"
}).toString();

const resp = await fetch(url, {
  method: "POST",
  headers: { "X-API-Key": "SUA_CHAVE" }
});

if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());
```

## Parâmetros

| Nome | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|
| `request_id` | texto | sim | Identificador devolvido no envio do código. | `otp_5c1d0e00000000000000000000000000` |
| `codigo` | texto | sim | Código que o usuário digitou. | `123456` |

## Resposta

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> - `verificado` — `true` quando o código confere. Só este campo vem no caso de sucesso.
> - `motivo` — Por que não conferiu. Presente apenas quando `verificado` é `false`:
>   - `incorrect` — Código errado. Ainda dá para tentar de novo, se restar tentativa.
>   - `expired` — Passou da validade definida no envio. Emita um novo código.
>   - `locked` — As 5 tentativas se esgotaram. Emita um novo código.
>   - `failed_delivery` — O SMS não chegou a ser aceito para envio; não há código válido a conferir.
> - `tentativas_restantes` — Quantas tentativas ainda restam neste `request_id`. Vem junto com `motivo: incorrect`.

### Exemplo de resposta

```json
{
  "verificado": true
}
```

### Schema da resposta

```json
{
  "type": "object",
  "properties": {
    "motivo": {
      "type": [
        "string",
        "null"
      ]
    },
    "verificado": {
      "type": [
        "boolean",
        "null"
      ]
    },
    "tentativas_restantes": {
      "type": [
        "integer",
        "null"
      ]
    }
  },
  "additionalProperties": true
}
```

## Códigos de erro

| Código | Mensagem | Quando acontece |
|---|---|---|
| `404` | Verificação não encontrada. | O `request_id` não existe ou pertence a outra conta. |
| `409` | Este código já foi utilizado. | O `request_id` já foi verificado com sucesso — o código é de uso único. |

## Quando usar

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> Chame no envio do formulário de código. Use `tentativas_restantes` para avisar o usuário antes de ele travar a verificação — e ofereça o **Reenviar código OTP** quando ela chegar perto de zero ou quando o `motivo` for `expired`.

---

Página em HTML: https://fontedata.com/docs/mensageria/otp-verify
Catálogo completo: https://fontedata.com/docs
OpenAPI (JSON): https://app.fontedata.com/api/v1/openapi.json
Conectar via MCP: https://fontedata.com/docs/mcp