Q: Como enviar SMS em Angola com a Kassala SMS API?

Cria uma conta, obtém a api_key, autoriza o domínio no painel do programador e faz um POST para /api/enviar-sms com api_key, destinatario e mensagem.

Q: Como enviar OTP por SMS?

Faz um POST para /api/enviar-otp com api_key, destinatario e mensagem. Se mensagem for null ou vazia, a API gera automaticamente o código OTP.

Q: Como consultar o saldo da minha conta pela API?

Faz um POST para /api/saldo com a tua api_key a partir de um domínio autorizado no painel do programador. A resposta inclui o saldo actual em Kwanzas (AOA).

Q: Porque recebo erro de origem não autorizada?

Esse erro ocorre quando a URL ou domínio de origem do pedido não está autorizado no painel do programador. Adiciona o domínio correto e tenta novamente.

Q: Porque recebo erro de créditos insuficientes?

A conta não tem saldo suficiente para enviar SMS ou OTP. Consulta o saldo com /api/saldo, recarrega a conta ou reduz o tamanho da mensagem para consumir menos segmentos de SMS.

Introdução

A Kassala SMS API, uma plataforma SUDOMAKE, permite integrar envio de SMS e códigos OTP para números angolanos em qualquer aplicação ou website. Regista-te em smsapi.sudomakes.com, autoriza o teu domínio no painel do programador e começa a enviar pedidos.

Autenticação

Cada pedido precisa de um campo api_key — a tua chave secreta encriptada, disponível no Dashboard (botão "Copiar chave da API"). Além da chave, a forma como validamos o pedido depende de onde é feito:

A partir do browser (JavaScript numa página web): o pedido tem sempre um cabeçalho Origin/Referer, por isso o domínio dessa página tem de estar registado e activo em "Websites autorizados" no teu Dashboard.
A partir do teu servidor (PHP, Node.js, Python, curl, Postman, etc.): estes pedidos não têm naturalmente Origin/Referer, por isso validamos apenas a api_key — basta teres pelo menos um website activo em "Websites autorizados" (qualquer um; não precisa de corresponder ao domínio de onde chamas a API).

Se todos os teus websites estiverem desactivados no Dashboard, todos os pedidos são recusados até reactivares pelo menos um — o site nunca é apagado, só fica em pausa.

Exemplo servidor-a-servidor (PHP)

$ch = curl_init('https://smsapi.sudomakes.com/api/saldo');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_key' => $apiKey,
    ]),
]);
$resposta = json_decode(curl_exec($ch), true);

Endpoints

Todos os endpoints abaixo aceitam pedidos POST com corpo em JSON ou multipart/form-data e respondem em JSON.

POST /api/enviar-sms

Envia uma mensagem SMS para um número angolano.

Parâmetros

Campo	Tipo		Descrição
`api_key`	string	obrigatório	A tua chave de API encriptada.
`destinatario`	string	obrigatório	Número angolano de destino (ex: `923000000` ou `+244923000000`).
`mensagem`	string	obrigatório	Conteúdo da mensagem a enviar.

Exemplo de pedido

curl -X POST "https://smsapi.sudomakes.com/api/enviar-sms" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "a_tua_chave_encriptada",
    "destinatario": "923000000",
    "mensagem": "Olá! A tua encomenda foi enviada."
  }'

fetch("https://smsapi.sudomakes.com/api/enviar-sms", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "a_tua_chave_encriptada",
    destinatario: "923000000",
    mensagem: "Olá! A tua encomenda foi enviada."
  })
})
  .then((res) => res.json())
  .then((dados) => console.log(dados));

$.ajax({
  url: "https://smsapi.sudomakes.com/api/enviar-sms",
  method: "POST",
  contentType: "application/json",
  data: JSON.stringify({
    api_key: "a_tua_chave_encriptada",
    destinatario: "923000000",
    mensagem: "Olá! A tua encomenda foi enviada."
  }),
  success: function (resposta) {
    console.log(resposta);
  }
});

const resposta = await fetch("https://smsapi.sudomakes.com/api/enviar-sms", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "a_tua_chave_encriptada",
    destinatario: "923000000",
    mensagem: "Olá! A tua encomenda foi enviada."
  })
});
const dados = await resposta.json();
console.log(dados);

$ch = curl_init('https://smsapi.sudomakes.com/api/enviar-sms');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_key' => 'a_tua_chave_encriptada',
        'destinatario' => '923000000',
        'mensagem' => 'Olá! A tua encomenda foi enviada.',
    ]),
]);
$resposta = json_decode(curl_exec($ch), true);

import requests

resposta = requests.post(
    "https://smsapi.sudomakes.com/api/enviar-sms",
    json={
        "api_key": "a_tua_chave_encriptada",
        "destinatario": "923000000",
        "mensagem": "Olá! A tua encomenda foi enviada.",
    },
)
print(resposta.json())

var body = """
    {
      "api_key": "a_tua_chave_encriptada",
      "destinatario": "923000000",
      "mensagem": "Olá! A tua encomenda foi enviada."
    }""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://smsapi.sudomakes.com/api/enviar-sms"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Resposta de sucesso

{
  "status": 1,
  "otp": "SMS enviado com sucesso."
}

Resposta de erro (ex: sem saldo)

{
  "status": -1,
  "otp": "Sem créditos de SMS disponíveis."
}

POST /api/enviar-otp

Envia um código de verificação (OTP) por SMS. Se não enviares mensagem, a API gera e envia automaticamente um código.

Parâmetros

Campo	Tipo		Descrição
`api_key`	string	obrigatório	A tua chave de API encriptada.
`destinatario`	string	obrigatório	Número angolano de destino.
`mensagem`	string	opcional	Mensagem personalizada. Deixa vazio para a API gerar o código OTP automaticamente.

Exemplo de pedido

curl -X POST "https://smsapi.sudomakes.com/api/enviar-otp" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "a_tua_chave_encriptada",
    "destinatario": "923000000"
  }'

fetch("https://smsapi.sudomakes.com/api/enviar-otp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "a_tua_chave_encriptada",
    destinatario: "923000000"
  })
})
  .then((res) => res.json())
  .then((dados) => console.log(dados));

$.ajax({
  url: "https://smsapi.sudomakes.com/api/enviar-otp",
  method: "POST",
  contentType: "application/json",
  data: JSON.stringify({
    api_key: "a_tua_chave_encriptada",
    destinatario: "923000000"
  }),
  success: function (resposta) {
    console.log(resposta);
  }
});

const resposta = await fetch("https://smsapi.sudomakes.com/api/enviar-otp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "a_tua_chave_encriptada",
    destinatario: "923000000"
  })
});
const dados = await resposta.json();
console.log(dados);

$ch = curl_init('https://smsapi.sudomakes.com/api/enviar-otp');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_key' => 'a_tua_chave_encriptada',
        'destinatario' => '923000000',
    ]),
]);
$resposta = json_decode(curl_exec($ch), true);

import requests

resposta = requests.post(
    "https://smsapi.sudomakes.com/api/enviar-otp",
    json={
        "api_key": "a_tua_chave_encriptada",
        "destinatario": "923000000",
    },
)
print(resposta.json())

var body = """
    {
      "api_key": "a_tua_chave_encriptada",
      "destinatario": "923000000"
    }""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://smsapi.sudomakes.com/api/enviar-otp"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Resposta de sucesso

{
  "status": 1,
  "otp": "123456"
}

Resposta de erro (ex: número inválido)

{
  "status": -1,
  "log": "O número de telefone não é angolano."
}

POST /api/saldo

Consulta o saldo actual da tua conta, em Kwanzas (AOA). Útil para mostrares o saldo no teu próprio painel ou para avisares os teus utilizadores antes que o saldo se esgote.

Parâmetros

Campo	Tipo		Descrição
`api_key`	string	obrigatório	A tua chave de API encriptada.

Exemplo de pedido

curl -X POST "https://smsapi.sudomakes.com/api/saldo" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "a_tua_chave_encriptada"
  }'

fetch("https://smsapi.sudomakes.com/api/saldo", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "a_tua_chave_encriptada"
  })
})
  .then((res) => res.json())
  .then((dados) => console.log(dados));

$.ajax({
  url: "https://smsapi.sudomakes.com/api/saldo",
  method: "POST",
  contentType: "application/json",
  data: JSON.stringify({
    api_key: "a_tua_chave_encriptada"
  }),
  success: function (resposta) {
    console.log(resposta);
  }
});

const resposta = await fetch("https://smsapi.sudomakes.com/api/saldo", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "a_tua_chave_encriptada"
  })
});
const dados = await resposta.json();
console.log(dados);

$ch = curl_init('https://smsapi.sudomakes.com/api/saldo');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_key' => 'a_tua_chave_encriptada',
    ]),
]);
$resposta = json_decode(curl_exec($ch), true);

import requests

resposta = requests.post(
    "https://smsapi.sudomakes.com/api/saldo",
    json={"api_key": "a_tua_chave_encriptada"},
)
print(resposta.json())

var body = """
    {
      "api_key": "a_tua_chave_encriptada"
    }""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://smsapi.sudomakes.com/api/saldo"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Resposta de sucesso

{
  "status": true,
  "saldo": 1250.5,
  "moeda": "AOA"
}

Códigos de erro comuns

Estes erros de autorização são partilhados por todos os endpoints acima.

HTTP	Campo	Causa
401	`erro: "Chave de API inválida."`	A `api_key` enviada não pôde ser decifrada.
401	`erro: "Sem autorização para utilizar esta chave."`	Não existe nenhuma conta associada a essa chave.
403	`erro: "Origem da requisição não identificada."`	O pedido não enviou cabeçalho `Origin` nem `Referer`.
403	`erro: "Requisição de origem não autorizada."`	O domínio de origem não está registado (ou está desactivado) em "Websites autorizados".
422	`errors: {...}`	Faltam campos obrigatórios no pedido.

Sandbox

Testa qualquer endpoint em tempo real com a tua própria api_key e vê logo o código equivalente na linguagem que preferires.

Este sandbox faz o pedido directamente a partir desta página (smsapi.sudomakes.com), por isso precisas de ter este domínio autorizado e activo em "Websites autorizados" no teu Dashboard para o teste funcionar.

Pedido

Endpoint

POST /api/enviar-sms

Atenção: isto envia mesmo uma mensagem real e consome saldo da tua conta.

api_key

Nunca partilhes a tua api_key publicamente — este teste corre só no teu browser.

destinatario

mensagem

Resposta

A resposta ao pedido aparece aqui depois de clicares em "Testar agora".

Documentação da Kassala SMS API

Introdução

Autenticação

Exemplo servidor-a-servidor (PHP)

Endpoints

Parâmetros

Exemplo de pedido

Resposta de sucesso

Resposta de erro (ex: sem saldo)

Parâmetros

Exemplo de pedido

Resposta de sucesso

Resposta de erro (ex: número inválido)

Parâmetros

Exemplo de pedido

Resposta de sucesso

Códigos de erro comuns

Sandbox

Pedido

Resposta

Código equivalente