API v1
Enviar código
/v1/sendCria um envio para processamento assíncrono. A resposta 202 Accepted confirma o aceite do pedido; consulte o status para acompanhar a entrega.
Nesta página
Requisição
Use Authorization: Bearer SUA_CHAVE e Content-Type: application/json. O cabeçalho opcional Idempotency-Key evita duplicações em retentativas.
| Campo | Tipo | Regra |
|---|---|---|
to | string, obrigatório | Telefone válido em formato internacional E.164, iniciado por +. Exemplo: +5531999999999. |
code | string, opcional | De 4 a 10 dígitos. Quando omitido, a aut2fa gera 6 dígitos em live ou usa 000000 em test. |
locale | string, opcional | Use pt-BR ou en. Quando omitido, usa o idioma da conta. |
Preserve zeros iniciais: envie "0042", não um número. O telefone é normalizado; números sem o sinal + e código do país são rejeitados.
curl https://api.aut2fa.com/v1/send \
-H "Authorization: Bearer $AUT2FA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to":"+5531999999999","locale":"pt-BR"}'// Execute no servidor (Node.js 22+).
const idempotencyKey = crypto.randomUUID();
const body = JSON.stringify({ to: "+5531999999999", locale: "pt-BR" });
// Guarde idempotencyKey e body antes de chamar; reutilize-os ao retentar.
const response = await fetch("https://api.aut2fa.com/v1/send", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AUT2FA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body,
signal: AbortSignal.timeout(15000),
});
const result = await response.json();
if (!response.ok) throw new Error(result.code);
// Guarde result.id na sessão de autenticação do seu servidor.import json
import os
import urllib.request
import uuid
idempotency_key = str(uuid.uuid4())
body = json.dumps({"to": "+5531999999999", "locale": "pt-BR"}).encode("utf-8")
# Guarde idempotency_key e body antes de chamar; reutilize-os ao retentar.
request = urllib.request.Request(
"https://api.aut2fa.com/v1/send",
data=body,
headers={
"Authorization": "Bearer " + os.environ["AUT2FA_API_KEY"],
"Content-Type": "application/json",
"Idempotency-Key": idempotency_key,
},
method="POST",
)
with urllib.request.urlopen(request, timeout=15) as response:
result = json.load(response)
# Guarde result["id"] na sessão de autenticação do servidor.<?php
$idempotencyKey = bin2hex(random_bytes(16));
$requestBody = json_encode([
'to' => '+5531999999999', 'locale' => 'pt-BR',
], JSON_THROW_ON_ERROR);
// Guarde a chave e $requestBody antes de chamar; reutilize-os ao retentar.
$request = curl_init('https://api.aut2fa.com/v1/send');
curl_setopt_array($request, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('AUT2FA_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: ' . $idempotencyKey,
],
CURLOPT_POSTFIELDS => $requestBody,
]);
$body = curl_exec($request);
if ($body === false) throw new RuntimeException(curl_error($request));
$status = curl_getinfo($request, CURLINFO_HTTP_CODE);
curl_close($request);
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($status !== 202) throw new RuntimeException($result['code'] ?? 'http_error');
// Guarde $result['id'] na sessão de autenticação do servidor.Os clientes nativos geram uma chave única por novo pedido. Antes da chamada, guarde essa chave e o corpo serializado para reutilizá-los em uma retentativa. O cURL mínimo omite idempotência; consulte idempotência para repetir chamadas com segurança.
Resposta 202
{
"id": "snd_01m4prwckhd0kyjgv5vw8a5wjr",
"status": "queued",
"verification": "pending",
"mode": "test",
"channel": null,
"from": null,
"expires_at": "2026-10-11T15:10:00Z",
"created_at": "2026-10-11T15:00:00Z",
"sent_at": null,
"delivered_at": null,
"read_at": null,
"verified_at": null,
"failed_at": null,
"failure_reason": null
}Este exemplo usa uma chave test. Em uma aplicação live, mode será live. Uma retentativa idempotente pode retornar o estado atual de um envio já existente.
A resposta nunca contém o código OTP. Guarde o id no servidor para consultar e verificar o envio.
| Campo | Tipo | Significado |
|---|---|---|
id | string | Identificador do envio; use em status e verificação. |
status | string | Estado da entrega. Veja os estados de entrega. |
verification | string | pending, verified, expired ou locked; separado do estado da entrega. |
mode | string | test ou live, conforme a aplicação da chave. |
channel | string ou null | Canal escolhido pela plataforma. null antes do roteamento; sandbox em teste. |
from | string ou null | Remetente usado, quando definido. |
expires_at | data e hora | Prazo de validade do código. Compare com o horário atual. |
created_at | data e hora | Quando o envio foi criado. |
sent_at | data e hora ou null | Quando o provedor aceitou a mensagem. |
delivered_at | data e hora ou null | Quando a entrega foi confirmada, se houver recibo. |
read_at | data e hora ou null | Quando a leitura foi confirmada, se houver recibo. |
verified_at | data e hora ou null | Quando o código foi verificado com sucesso. |
failed_at | data e hora ou null | Quando a entrega encerrou com falha. |
failure_reason | string ou null | Motivo da falha de entrega. Veja falhas de entrega. |
Datas usam o formato RFC 3339. null indica que a informação ainda não existe ou não está disponível; trate isso antes de formatar uma data.
Validação e erros
| HTTP | Códigos principais |
|---|---|
| 401 | missing_credentials, invalid_api_key |
| 402 | insufficient_credits |
| 409 | idempotency_key_reused |
| 422 | invalid_json, invalid_recipient, invalid_code, invalid_locale, invalid_idempotency_key, channel_unavailable |
| 429 | rate_limited, com Retry-After |
Veja o envelope de erro para tratar a resposta pelo campo code. Após uma falha de rede, repita os mesmos bytes do corpo e a mesma chave de idempotência.