kambasms / php-sdk

v1.1.1 2026-07-24 10:31 UTC

Requires

• php: ^8.0
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^9.5

MIT

• KambaSMS

Published on Packagist.org on 2026-07-24 10:31 UTC

README

SDK oficial e sem dependências externas para SMS, OTP, Verify, Lookup, Notify, Email e Transactions.

Requer PHP 8.0+, ext-curl e ext-json.

Instalação

composer require kambasms/php-sdk

Configuração

use KambaSMS\KambaSMS;

$client = new KambaSMS(apiKey: $_ENV['KAMBA_API_KEY']);

A URL padrão é https://api.kambasms.ao. O construtor também aceita baseUrl e timeout.

SMS e OTP

$sms = $client->sms->send([
    'to' => '[phone]',
    'text' => 'O seu pedido foi recebido.',
], ['idempotency_key' => 'order:123:sms']);

$otp = $client->otp->send(['phone' => '[phone]']);
$result = $client->otp->verify(['phone' => '[phone]', 'code' => '123456']);

O recurso SMS também oferece sendBulk, schedule, listScheduled, cancelScheduled, listBulk e getBulk.

Verify

Verify gere código, expiração, tentativas, reenvio e estado de cada sessão.

$session = $client->verify->start([
    'phone' => '[phone]',
    'metadata' => ['customer_id' => '123'],
], ['idempotency_key' => 'verify:customer:123']);

$result = $client->verify->check($session['verification_id'], '123456');

Também podes usar list, get, events, stats e resend.

Lookup

$number = $client->lookup->lookup('923 456 789');
$batch = $client->lookup->bulk(['923456789', '[phone]']);

A operadora é estimada pelo prefixo e não confirmada em tempo real.

Notify

A chave API precisa do scope notify.

$client->notify->createTemplate([
    'key' => 'appointment_reminder',
    'name' => 'Lembrete',
    'body' => 'Olá {{name}}, a sua consulta está marcada para {{date}}.',
]);

$client->notify->send([
    'to' => '[phone]',
    'template_key' => 'appointment_reminder',
    'variables' => ['name' => 'Ana', 'date' => '10/10 às 09:00'],
], ['idempotency_key' => 'appointment:123:reminder']);

Kamba Email

Email usa volume próprio, separado dos créditos SMS. Em produção, adiciona e verifica um domínio. A chave API precisa do scope email.

$domain = $client->email->createDomain('example.ao');
$client->email->verifyDomain($domain['id']);

$client->email->send([
    'to' => '[e-mail]',
    'domain_id' => $domain['id'],
    'from_local' => 'alertas',
    'from_name' => 'Minha Empresa',
    'subject' => 'Pedido recebido',
    'html' => '<p>O pedido <strong>#123</strong> foi recebido.</p>',
], ['idempotency_key' => 'order:123:email']);

O recurso inclui domínios, templates, renderização, Sandbox e bulk de até 500 destinatários por pedido.

Kamba Transactions

Transactions recebe eventos e entrega comunicações por SMS e/ou email. Não processa pagamentos, cartões ou dinheiro. A chave API precisa do scope transactions.

$client->transactions->createTemplate([
    'key' => 'meeting_notice',
    'event_type' => 'meeting.scheduled',
    'name' => 'Reunião agendada',
    'channels' => ['sms'],
    'sms_body' => 'A sua reunião foi agendada para {{date}}.',
]);

$event = $client->transactions->sendEvent([
    'event' => 'meeting.scheduled',
    'template_key' => 'meeting_notice',
    'external_reference' => 'meeting-123',
    'customer' => ['phone' => '[phone]'],
    'data' => ['date' => '10/10 às 09:00'],
    'channels' => ['sms'],
], ['idempotency_key' => 'meeting:123']);

Conta e Sandbox

$balance = $client->account->getBalance();
$history = $client->account->getHistory(20);
$stats = $client->account->getStats();
$usage = $client->account->getUsage();

Usa uma chave Sandbox para simular operações sem consumir créditos reais.

Tratamento de erros

use KambaSMS\Exceptions\KambaAPIException;
use KambaSMS\Exceptions\KambaValidationException;

try {
    $client->sms->send(['to' => '923456789', 'text' => 'Mensagem']);
} catch (KambaValidationException $error) {
    echo $error->getMessage();
} catch (KambaAPIException $error) {
    echo $error->getStatusCode();
    echo $error->getAPIErrorCode();
    print_r($error->getDetails());
}

O estado 0 indica falha de rede ou timeout. O SDK não repete pedidos automaticamente. Reutiliza a mesma chave de idempotência quando precisares de confirmar uma operação incerta.

Documentação: kambasms.ao/dashboard/docs