Documentação da Kassala SMS API

Introdução

A Kassala SMS API permite que desenvolvedores integrem o envio de SMS em suas aplicações, exclusivamente para números de telefone nacionais de Angola (formato +244). 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.

URL Base: https://smsapi.chanceapp.ao/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.chanceapp.ao para obter sua chave.

Endpoints

Enviar SMS

Envia uma mensagem SMS 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.

Exemplo de Requisição

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

Resposta

Sucesso (200 OK):

{
  "status": "success",
  "mensagem": "SMS enviado com sucesso."
}

Erro (401 Não Autorizado):

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

Erro (403 Proibido):

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

Erro (403 Proibido - Sem Créditos):

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

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

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

Notas Adicionais

O domínio de origem da requisição deve estar registrado no painel do usuário.
O usuário deve ter créditos suficientes para enviar o SMS.
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 enviarSMS($apiKey, $recipient, $message)
{
    $url = 'https://smsapi.chanceapp.ao/api/enviar-sms';
    $payload = [
        'api_key' => $apiKey,
        'destinatario' => $recipient,
        'mensagem' => $message,
    ];
    $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) {
        return json_decode($response, true);
    } else {
        return ['status' => 'error', 'mensagem' => "Erro HTTP: $httpCode"];
    }
}
// Exemplo de uso
$apiKey = 'sua_chave_api_criptografada';
$recipient = '+244923000000';
$message = 'Olá, esta é uma mensagem de teste!';
$response = enviarSMS($apiKey, $recipient, $message);
echo json_encode($response, JSON_PRETTY_PRINT);

JavaScript (Node.js)

const fetch = require('node-fetch');
async function enviarSMS(apiKey, recipient, message) {
    const url = 'https://smsapi.chanceapp.ao/api/enviar-sms';
    const payload = {
        api_key: apiKey,
        destinatario: recipient,
        mensagem: message
    };
    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!';
enviarSMS(apiKey, recipient, message);

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 {
        public String api_key;
        public String destinatario;
        public String mensagem;
        public SMSPayload(String apiKey, String recipient, String message) {
            this.api_key = apiKey;
            this.destinatario = recipient;
            this.mensagem = message;
        }
    }
    public static void enviarSMS(String apiKey, String recipient, String message) throws Exception {
        String url = "https://smsapi.chanceapp.ao/api/enviar-sms";
        SMSPayload payload = new SMSPayload(apiKey, recipient, message);
        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(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!";
        enviarSMS(apiKey, recipient, message);
    }
}

Python

import requests
import json
def enviar_sms(api_key, recipient, message):
    url = "https://smsapi.chanceapp.ao/api/enviar-sms"
    payload = {
        "api_key": api_key,
        "destinatario": recipient,
        "mensagem": message
    }
    headers = {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        print(json.dumps(response.json(), indent=2))
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Erro: {e}")
        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_sms(api_key, recipient, message)

Ruby

require 'net/http'
require 'json'
def enviar_sms(api_key, recipient, message)
  url = URI('https://smsapi.chanceapp.ao/api/enviar-sms')
  payload = {
    api_key: api_key,
    destinatario: recipient,
    mensagem: message
  }
  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!'
enviar_sms(api_key, recipient, message)

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 de retentativa para falhas temporárias e verifique os códigos de erro retornados.
Segurança da Chave: Armazene a chave de API de forma segura 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.
Gestão de Créditos: Monitore o saldo de créditos no painel para evitar interrupções.

Suporte

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