Documentação da Kassala SMS API

Introdução

A Kassala SMS API permite que desenvolvedores integrem o envio de mensagens em suas aplicações, exclusivamente para números de telefone nacionais de Angola (formato +244). A API oferece suporte ao envio de SMS tradicional e, para usuários com subscrição ativa, ao envio de mensagens via WhatsApp.

A API utiliza uma interface JSON simples, com autenticação por chave de API criptografada, validação de domínio de origem e verificação de créditos do usuário (para SMS) ou status da subscrição (para WhatsApp).

URL Base: https://smsapi.sudomakes.com/api

Autenticação

A autenticação é realizada por uma chave de API criptografada, fornecida no campo api_key do corpo da requisição. A chave é associada a um usuário registrado. Além disso, o domínio de origem da requisição (via cabeçalhos Origin ou Referer) deve estar autorizado no painel do usuário. Registre-se em smsapi.sudomakes.com para obter sua chave.

Endpoints

Enviar Mensagem

Envia uma mensagem SMS ou WhatsApp para um número de telefone nacional de Angola.

Endpoint: /enviar-sms
Método: POST
Content-Type: application/json
Accept: application/json

Parâmetros da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
`api_key`	String	Sim	Chave de API criptografada do usuário.
`destinatario`	String	Sim	Número de telefone em formato E.164 (e.g., `+244923000000`). Apenas números angolanos são permitidos.
`mensagem`	String	Sim	Conteúdo da mensagem (máximo de 160 caracteres). A abreviação do usuário será automaticamente adicionada.
`whatsapp`	Boolean	Não	Se `true`, envia a mensagem via WhatsApp. Requer uma subscrição de usuário ativa. Se omitido ou `false`, o envio padrão é por SMS.

Exemplo de Requisição (SMS)

{
  "api_key": "sua_chave_api_criptografada",
  "destinatario": "+244923000000",
  "mensagem": "Olá, esta é uma mensagem de teste!"
}

Exemplo de Requisição (WhatsApp)

{
  "api_key": "sua_chave_api_criptografada",
  "destinatario": "+244923000000",
  "mensagem": "Olá, esta é uma mensagem de teste via WhatsApp!",
  "whatsapp": true
}

Resposta

Sucesso (200 OK):

{
  "status": "success",
  "mensagem": "Mensagem enviada com sucesso."
}

Erro (401 Não Autorizado - Chave Inválida):

{
  "erro": "Chave de API inválida."
}

Erro (401 Não Autorizado - Chave não associada):

{
  "erro": "Sem autorização para utilizar esta chave."
}

Erro (403 Proibido - Origem não autorizada):

{
  "erro": "Requisição de origem não autorizada."
}

Erro (403 Proibido - Sem Créditos de SMS):

{
  "erro": "Sem créditos de SMS disponíveis."
}

Erro (400 Requisição Inválida):

{
  "status": "error",
  "mensagem": "Falha desconhecida ao enviar a mensagem."
}

Notas Adicionais

O domínio de origem da requisição deve estar registrado no painel do usuário.
Para envio de SMS, o usuário deve ter créditos suficientes.
Para envio via WhatsApp, o usuário deve ter uma subscrição ativa.
A mensagem final enviada incluirá a abreviação da empresa (em maiúsculas) seguida de ": " antes do texto fornecido.

Área de Teste

Teste a Kassala SMS API usando o simulador abaixo. Insira sua chave de API, número de destinatário angolano e mensagem para visualizar a resposta em tempo real. Certifique-se de que o domínio de origem está autorizado.

Exemplos de Integração

Abaixo estão exemplos de como integrar a Kassala SMS API em linguagens de programação populares.

PHP

function enviarMensagem($apiKey, $recipient, $message, $isWhatsApp = false)
{
    $url = 'https://smsapi.sudomakes.com/api/enviar-sms';
    $payload = [
        'api_key' => $apiKey,
        'destinatario' => $recipient,
        'mensagem' => $message,
    ];
    if ($isWhatsApp) {
        $payload['whatsapp'] = true;
    }
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json', 'Accept: application/json']);
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($httpCode >= 200 && $httpCode < 300) {
        return json_decode($response, true);
    } else {
        return ['status' => 'error', 'mensagem' => "Erro HTTP: $httpCode", 'response' => json_decode($response, true)];
    }
}
// Exemplo de uso (SMS)
$apiKey = 'sua_chave_api_criptografada';
$recipient = '+244923000000';
$message = 'Olá, esta é uma mensagem de teste!';
$response = enviarMensagem($apiKey, $recipient, $message);
echo json_encode($response, JSON_PRETTY_PRINT);

// Exemplo de uso (WhatsApp)
$responseWhatsApp = enviarMensagem($apiKey, $recipient, $message, true);
echo json_encode($responseWhatsApp, JSON_PRETTY_PRINT);

JavaScript (Node.js)

const fetch = require('node-fetch');
async function enviarMensagem(apiKey, recipient, message, isWhatsApp = false) {
    const url = 'https://smsapi.sudomakes.com/api/enviar-sms';
    const payload = {
        api_key: apiKey,
        destinatario: recipient,
        mensagem: message
    };
    if (isWhatsApp) {
        payload.whatsapp = true;
    }
    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            },
            body: JSON.stringify(payload)
        });
        const data = await response.json();
        console.log(JSON.stringify(data, null, 2));
        return data;
    } catch (error) {
        console.error('Erro:', error.message);
        return { status: 'error', mensagem: error.message };
    }
}
// Exemplo de uso
const apiKey = 'sua_chave_api_criptografada';
const recipient = '+244923000000';
const message = 'Olá, esta é uma mensagem de teste!';
enviarMensagem(apiKey, recipient, message); // Envia como SMS
enviarMensagem(apiKey, recipient, message, true); // Envia como WhatsApp

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.google.gson.Gson;

public class KassalaSMS {
    public static class SMSPayload {
        String api_key;
        String destinatario;
        String mensagem;
        Boolean whatsapp; // Usar Boolean para permitir valor nulo

        public SMSPayload(String apiKey, String recipient, String message, boolean isWhatsApp) {
            this.api_key = apiKey;
            this.destinatario = recipient;
            this.mensagem = message;
            if (isWhatsApp) {
                this.whatsapp = true;
            }
        }
    }

    public static void enviarMensagem(String apiKey, String recipient, String message, boolean isWhatsApp) throws Exception {
        String url = "https://smsapi.sudomakes.com/api/enviar-sms";
        SMSPayload payload = new SMSPayload(apiKey, recipient, message, isWhatsApp);
        Gson gson = new Gson();
        String jsonPayload = gson.toJson(payload);

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json")
                .header("Accept", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
                .build();

        HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("Status Code: " + response.statusCode());
        System.out.println("Response Body: " + response.body());
    }

    public static void main(String[] args) throws Exception {
        String apiKey = "sua_chave_api_criptografada";
        String recipient = "+244923000000";
        String message = "Olá, esta é uma mensagem de teste!";
        
        System.out.println("Enviando SMS...");
        enviarMensagem(apiKey, recipient, message, false);
        
        System.out.println("\nEnviando WhatsApp...");
        enviarMensagem(apiKey, recipient, message, true);
    }
}

Python

import requests
import json

def enviar_mensagem(api_key, recipient, message, is_whatsapp=False):
    url = "https://smsapi.sudomakes.com/api/enviar-sms"
    payload = {
        "api_key": api_key,
        "destinatario": recipient,
        "mensagem": message
    }
    if is_whatsapp:
        payload["whatsapp"] = True
        
    headers = {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()  # Lança exceção para status de erro HTTP
        print(json.dumps(response.json(), indent=2))
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Erro: {e}")
        if e.response:
            print(f"Detalhes: {e.response.text}")
        return {"status": "error", "mensagem": str(e)}

# Exemplo de uso
api_key = "sua_chave_api_criptografada"
recipient = "+244923000000"
message = "Olá, esta é uma mensagem de teste!"

# Enviar como SMS
enviar_mensagem(api_key, recipient, message)

# Enviar como WhatsApp
enviar_mensagem(api_key, recipient, message, is_whatsapp=True)

Ruby

require 'net/http'
require 'json'
require 'uri'

def enviar_mensagem(api_key, recipient, message, is_whatsapp: false)
  url = URI('https://smsapi.sudomakes.com/api/enviar-sms')
  payload = {
    api_key: api_key,
    destinatario: recipient,
    mensagem: message
  }
  payload[:whatsapp] = true if is_whatsapp

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  request = Net::HTTP::Post.new(url)
  request['Content-Type'] = 'application/json'
  request['Accept'] = 'application/json'
  request.body = payload.to_json

  begin
    response = http.request(request)
    puts JSON.pretty_generate(JSON.parse(response.body))
    JSON.parse(response.body)
  rescue StandardError => e
    puts "Erro: #{e.message}"
    { status: 'error', mensagem: e.message }
  end
end

# Exemplo de uso
api_key = 'sua_chave_api_criptografada'
recipient = '+244923000000'
message = 'Olá, esta é uma mensagem de teste!'

puts "--- Enviando SMS ---"
enviar_mensagem(api_key, recipient, message)

puts "\n--- Enviando WhatsApp ---"
enviar_mensagem(api_key, recipient, message, is_whatsapp: true)

Boas Práticas

Valide Entradas: Verifique se o número de destinatário está no formato E.164 (+244) e se a mensagem tem até 160 caracteres.
Gerencie Erros: Implemente lógica para tratar os diferentes códigos e mensagens de erro retornados pela API.
Segurança da Chave: Armazene a chave de API de forma segura em variáveis de ambiente ou secrets manager e evite expô-la em código do lado do cliente.
Autorização de Domínio: Registre todos os domínios de origem no painel do usuário para evitar erros de acesso proibido.
Gestão de Créditos e Subscrição: Monitore o saldo de créditos (para SMS) e o status da sua subscrição (para WhatsApp) no painel para evitar interrupções no serviço.

Suporte

Para assistência, entre em contato com sudomake.startup@gmail.com ou ligue para o Apoio a cliente.