Conceitos
Clientes HTTP
A API usa HTTPS e JSON. Os exemplos usam clientes HTTP da linguagem, sem depender de um pacote de SDK da aut2fa.
Nesta página
Escolha o cliente do servidor
| Ambiente | Cliente usado |
|---|---|
| Node.js 22 ou superior | fetch nativo. |
| Python 3 | urllib.request da biblioteca padrão. |
| PHP | Extensão cURL e json_encode. |
| Terminal | curl. |
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.Para executar o JavaScript no Node.js, salve o exemplo em enviar.mjs e rode node enviar.mjs. A extensão .mjs permite o await no nível principal. Os comandos cURL usam Bash, com AUT2FA_API_KEY no ambiente.
Guarde a chave gerada e os bytes do corpo antes da chamada. Execute a geração novamente só para um novo pedido de código. Uma retentativa reutiliza os valores guardados; trocar a linguagem do exemplo não garante os mesmos bytes de JSON.
Configure um timeout adequado ao seu fluxo. Uma falha de rede não indica que a API deixou de criar o envio; retente usando idempotência.
Fluxo de autenticação no servidor
- Receba o telefone e valide a sessão que pediu a operação.
- Crie o envio e guarde ID, prazo, chave de idempotência e corpo nessa sessão.
- Receba o código como string e recupere o ID guardado no servidor.
- Chame a verificação e conclua a operação somente com
valid: true. - Encerre a sessão de desafio depois do sucesso.
Trate HTTP e resultado separadamente
async function verifySend(sendId, code) {
const response = await fetch(
"https://api.aut2fa.com/v1/send/" + encodeURIComponent(sendId) + "/verify",
{
method: "POST",
headers: {
Authorization: "Bearer " + process.env.AUT2FA_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ code }),
signal: AbortSignal.timeout(15000),
},
);
const result = await response.json();
if (!response.ok) {
throw new Error(result.code ?? "http_error");
}
return result;
}
// Recupere o sendId da sessão do servidor antes desta chamada.
// Autorize a operação apenas quando result.valid === true.Uma verificação incorreta retorna HTTP 200 e valid: false. Para erros HTTP, leia o campo code do envelope application/problem+json.
Em Python, urllib.request.urlopen lança urllib.error.HTTPError para erros HTTP; leia o corpo desse erro para obter code. Em PHP, verifique o status retornado por CURLINFO_HTTP_CODE.