API de SMS para Desenvolvedores

Começar em 3 passos

Compre SMS — no seu sistema AXAM (fundo do ecrã → SMS AXAM → pedir pacote ou outra quantidade) ou fale connosco pelo WhatsApp +258 82 213 5020.
Crie a chave de API em SMS AXAM → Criar chave. A chave começa por axk_ e só é mostrada uma vez: guarde-a num sítio seguro (nunca dentro de código que corre no navegador).
Envie um pedido POST para https://api.axam.co.mz/v1/sms.php com o número e o texto.

Endereço da API: https://api.axam.co.mz/v1 (também disponível em https://axam.co.mz/sistema/api/v1).

Preços

Por SMS1,26 MT

Compra mínima100 SMS

Validade12 meses

Também há pacotes de 500, 2 000 e 10 000 SMS. Os SMS de uma mensagem que o operador não aceita voltam ao seu saldo. Não há mensalidade.

Autenticação

Envie a chave em todos os pedidos, no cabeçalho Authorization:

Authorization: Bearer axk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx

Também aceitamos o cabeçalho X-API-Key: axk_.... Pode ter até 5 chaves ativas (ex.: uma por site) e desativar uma chave a qualquer momento no sistema.

POST/sms.php — enviar SMS

Campo	Tipo	Descrição
`para`	texto ou lista	Número(s) de Moçambique: `841234567`, `+258841234567` ou uma lista `["84…","85…"]` (até 1 000 por pedido).
`texto`	texto	A mensagem (até 918 caracteres).
`referencia`	texto (opcional)	O seu identificador (ex.: nº da encomenda), para consultar depois.

curl -X POST https://api.axam.co.mz/v1/sms.php \
  -H "Authorization: Bearer $AXAM_SMS_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"para": "841234567", "texto": "A sua encomenda 1234 esta pronta.", "referencia": "enc-1234"}'

<?php
$ch = curl_init('https://api.axam.co.mz/v1/sms.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AXAM_SMS_CHAVE'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['para' => '841234567', 'texto' => 'A sua encomenda 1234 esta pronta.', 'referencia' => 'enc-1234']),
]);
$r = json_decode(curl_exec($ch), true);
if (!empty($r['ok'])) echo 'Enviado. Saldo: ' . $r['data']['saldo'];
else echo 'Erro: ' . $r['error'];

const r = await fetch('https://api.axam.co.mz/v1/sms.php', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.AXAM_SMS_CHAVE, 'Content-Type': 'application/json' },
  body: JSON.stringify({ para: ['841234567', '851234567'], texto: 'Promocao: 10% de desconto hoje!' }),
});
const j = await r.json();
console.log(j.ok ? 'Saldo: ' + j.data.saldo : 'Erro: ' + j.error);

import os, requests
r = requests.post('https://api.axam.co.mz/v1/sms.php',
    headers={'Authorization': 'Bearer ' + os.environ['AXAM_SMS_CHAVE']},
    json={'para': '841234567', 'texto': 'A sua consulta e amanha as 9h.', 'referencia': 'consulta-77'})
j = r.json()
print(j['data']['saldo'] if j['ok'] else j['error'])

Resposta (202)

{"ok": true, "data": {"ids": [5012], "partes": 1, "sms_gastos": 1, "saldo": 1499}}

A mensagem entra na fila e sai em segundos. O valor é descontado logo; se o operador recusar a mensagem, os SMS voltam ao saldo.

GET/sms.php?id=… — estado de uma mensagem

curl "https://api.axam.co.mz/v1/sms.php?id=5012" -H "Authorization: Bearer $AXAM_SMS_CHAVE"
# ou todas as mensagens com a sua referência:
curl "https://api.axam.co.mz/v1/sms.php?referencia=enc-1234" -H "Authorization: Bearer $AXAM_SMS_CHAVE"

Estados: fila, enviando, enviado, falhou (os SMS voltam ao saldo) e cancelado.

GET/saldo.php — saldo

curl https://api.axam.co.mz/v1/saldo.php -H "Authorization: Bearer $AXAM_SMS_CHAVE"
# {"ok":true,"data":{"empresa":"A minha loja","saldo":1499,"expira_primeiro":"2027-10-10","lotes":[…]}}

Erros e limites

Código	Quando
`400`	Falta o número ou o texto, número inválido, texto longo demais.
`401`	Chave em falta, errada ou desativada.
`402`	Saldo insuficiente — compre mais SMS.
`403`	A conta da empresa está suspensa.
`429`	Mais de 120 pedidos por minuto com a mesma chave. Espere uns segundos.

Todas as respostas são JSON: {"ok": true, "data": …} ou {"ok": false, "error": "mensagem"}.

Regras do texto

Até 160 caracteres = 1 SMS. Mensagens mais longas gastam 1 SMS por cada 153 caracteres (máximo 6 partes, 918 caracteres).
Os acentos são retirados no envio (ex.: "ação" sai "acao"), para a mensagem chegar bem a todos os telemóveis.
O texto das mensagens é apagado ao fim de 90 dias; fica só a contagem para a sua fatura.
Use a API só para mensagens que os seus clientes esperam receber (avisos, confirmações, promoções a quem aceitou).

Especificação OpenAPI

Para gerar um cliente automaticamente ou importar no Postman/Insomnia: openapi.json (OpenAPI 3.0).

Dúvidas? WhatsApp +258 82 213 5020 · axam@axam.co.mz

API de SMS AXAM