README

Envie códigos 2FA por WhatsApp, SMS, Telegram e e-mail com uma chamada de API.
Site · Documentação · Packagist · Criar conta grátis · Reportar problema

Por que usar

Um endpoint, quatro canais. Você chama send, e a aut2fa entrega por WhatsApp, SMS, Telegram ou e-mail.
Sem gerar nem guardar código. A API pode gerar o código; você só chama verify com o que o usuário digitou.
Zero pacotes extras. Usa só as extensões curl e json do PHP. Nada de Guzzle no seu vendor.
Funciona em qualquer projeto. Laravel, Symfony, WordPress ou PHP puro: basta o autoloader do Composer.
Seguro por padrão. Não segue redirects, não repete requisições sozinho e mantém a verificação TLS do cURL.
Erros claros. ApiError, NetworkError e InvalidResponseError separam cada tipo de falha.

Instalar

Requer PHP 8.1 ou superior com as extensões curl e json.

composer require aut2fa/aut2fa-php

Começar em 30 segundos

<?php

require __DIR__ . '/vendor/autoload.php';

use Aut2fa\Aut2fa;

$aut2fa = new Aut2fa(getenv('AUT2FA_API_KEY'));

// 1. Envia o código para o usuário
$send = $aut2fa->send(['to' => '+5531999999999']);

// 2. Confere o código que o usuário digitou
$result = $aut2fa->verify($send->id, ['code' => '482913']);

if ($result->valid) {
    echo 'Login liberado';
}

Crie sua conta em aut2fa.com para pegar a chave da aplicação.

Enviar e verificar em detalhe

Configure AUT2FA_API_KEY no servidor e carregue o autoloader do Composer:

<?php

require __DIR__ . '/vendor/autoload.php';

use Aut2fa\Aut2fa;

$aut2fa = new Aut2fa(getenv('AUT2FA_API_KEY'));
$send = $aut2fa->send(['to' => '+5531999999999']);

$result = $aut2fa->verify($send->id, ['code' => '482913']);
if ($result->valid) {
    // Continue o fluxo de autenticação da sua aplicação.
}

valid=false é um resultado normal de verificação. Consulte $result->verification e $result->attempts_left para acompanhar as tentativas restantes.

Consultar o envio

Use o ID retornado pelo envio para consultar o estado atual:

$current = $aut2fa->status($send->id);
echo $current->status;

Os métodos retornam objetos stdClass. O envio inclui id, status, verification, mode, channel, from, expires_at, created_at, sent_at, delivered_at, read_at, verified_at, failed_at e failure_reason. O cliente preserva valores null e campos adicionais da API; as datas permanecem strings.

Configurar envio e idempotência

Você pode fornecer code e locale como strings. Passe uma chave de idempotência no segundo argumento para identificar um envio lógico:

$send = $aut2fa->send([
    'to' => '+5531999999999',
    'code' => '004829',
    'locale' => 'pt-BR',
], 'login-attempt-001');

A chave aceita até 255 bytes e rejeita caracteres de controle. O cliente não repete requisições automaticamente. Ao repetir o mesmo envio manualmente, reutilize a chave e o mesmo conteúdo para evitar outro envio.

Configurar o cliente

O cliente usa https://api.aut2fa.com e timeout de 10 segundos por requisição. Para alterar a URL e o prazo, use as opções do construtor:

$aut2fa = new Aut2fa(getenv('AUT2FA_API_KEY'), [
    'baseUrl' => 'http://127.0.0.1:8080',
    'timeout' => 2.5,
]);

baseUrl aceita HTTP ou HTTPS, com um prefixo de caminho opcional. A URL não pode conter credenciais, query ou fragmento. timeout aceita números finitos, estritamente positivos, em segundos, até 2147483.647; frações são arredondadas para cima ao milissegundo. As opções reconhecidas são baseUrl e timeout.

O cliente rejeita chaves de aplicação vazias ou com caracteres de controle. IDs aceitam somente letras ASCII, números, underscore e hífen. to no envio e code na verificação precisam ser strings não vazias. O SDK não segue redirects e mantém a verificação TLS padrão do cURL.

Tratar erros

Capture a classe correspondente ao resultado da requisição:

Exceção	Quando ocorre	Propriedades
`Aut2fa\ApiError`	Resposta HTTP fora de 2xx	`status`, `code`, `detail`, `errors`, `retryAfter`
`Aut2fa\NetworkError`	Falha de conexão, TLS ou timeout	`curlCode`, `timedOut`
`Aut2fa\InvalidResponseError`	Resposta 2xx com JSON inválido ou sem os campos centrais	`status`
`InvalidArgumentException`	Credenciais, opções ou parâmetros inválidos	Mensagem de validação

ApiError->code contém o código estável da API, como rate_limited ou invalid_recipient. status contém o status HTTP real. errors preserva os campos de validação como objeto, quando presentes, e retryAfter mantém o valor do cabeçalho Retry-After como string ou null.

Corpos de erro não JSON ou fora do envelope esperado resultam em code=http_error, sem incluir o corpo na mensagem. Respostas de envio e consulta precisam ter id e status como strings não vazias; verificação exige valid booleano, verification string não vazia e attempts_left inteiro não negativo. Campos adicionais continuam disponíveis.

Uma falha de rede pode ocorrer após a API receber a requisição. Use a chave de idempotência ao repetir um envio; avalie as tentativas restantes antes de repetir uma verificação.

Desenvolver e empacotar

Na raiz do repositório, instale as dependências de desenvolvimento e execute as checagens:

composer install
composer validate --strict --no-check-lock
composer lint
composer test

Os testes usam um servidor HTTP local real e não chamam a API aut2fa. Eles precisam de proc_open e acesso ao loopback. A integração contínua executa as checagens em PHP 8.1 a 8.5 no Linux e PHP 8.5 no Windows.

Publicar novas versões

O pacote está no Packagist e é atualizado automaticamente. Para lançar uma versão, crie e envie uma tag semântica, como v0.1.1; o Composer lê a versão pela tag.

Outras linguagens

Linguagem	Pacote	Repositório
PHP	`aut2fa/aut2fa-php`	aut2fa-php
Node.js	`@aut2fa/node`	aut2fa-node
Python	`aut2fa`	aut2fa-python
Go	`github.com/jhowbhz/aut2fa-go`	aut2fa-go

Contribuir

Encontrou um bug ou tem uma ideia? Abra uma issue ou envie um pull request. Consulte o histórico de alterações para acompanhar as versões.

Se este SDK te ajudou, deixe uma ⭐ no repositório. Isso ajuda outros devs a encontrá-lo.

Documentação da API · Licença MIT · Feito pela aut2fa

aut2fa / aut2fa-php

Package info

Security

Statistics