ama4devs
EN PT

Início rápido

Do docker run a uma entrega que falha de propósito, com o painel do aparelho do lado. Cada comando abaixo roda como está escrito contra um container novo.

  1. Suba

    Execute o container oficial do mock de SMS. A porta é 8899 e o serviço fica pronto na hora, sem banco de dados e sem tocar em nenhuma operadora.

    docker run --rm -p 127.0.0.1:8899:8899 ghcr.io/instituto-ama/sms-mock:latest

    No repositório, make up MOCKS=sms sobe o mock pelo compose, ao lado dos outros serviços.

    Verifique o estado do serviço no endpoint de saúde:

    curl http://localhost:8899/health
{
  "status": "ok",
  "service": "sms",
  "version": "0.2.0"
}

  2. Abra o painel

    O painel fica em http://localhost:8899. Ele é o aparelho: cada número é uma conversa, o que a sua aplicação envia aparece à esquerda, com o remetente, o chip do código de OTP para copiar, o selo de segmentos e o status, e o que você escreve no rodapé da conversa é a resposta do aparelho — com o webhook de entrada disparado. O ícone de ajustes abre o painel de controle: entrega, webhook, eventos, números mágicos e a API inteira.

    A conversa do painel do mock de SMS: à esquerda o SMS do BANCO com o código de verificação 482913 em um chip para copiar, e à direita a resposta escrita como o celular.
    O que a sua aplicação envia aparece à esquerda; o que você escreve no rodapé é a resposta do aparelho, à direita.

    No repositório, o make up da raiz sobe o mock de SMS junto com o do Asaas: os dois ficam no ar ao mesmo tempo, cada mock na sua porta, e o mock do Asaas manda para o de SMS os SMS do pagador.

    Para começar com conteúdo, peça a caixa de exemplo — um OTP, um aviso de entrega, uma promoção longa em UCS-2, uma mensagem que falha e uma resposta:

    curl -X POST http://localhost:8899/_mock/sms/demo

  3. Envie

    A API nativa recebe JSON e devolve 201 com a mensagem enfileirada. O remetente padrão é AMA4DEVS e o código de verificação presente no texto é extraído para codes.

    curl -X POST http://localhost:8899/v1/messages \
  -H 'Content-Type: application/json' \
  -d '{"to": "+5511912340010", "body": "Seu código de verificação é 482913"}'

    Se preferir o envio de uma linha só, a interface simples aceita GET ou POST em /sms/send:

    curl "http://localhost:8899/sms/send?to=%2B5511912340010&message=Alerta+rapido&sender=AMA4DEVS"

  4. Leia de volta

    A listagem aceita filtros e um long poll em wait: se já existe uma mensagem que combine com o filtro, a resposta vem na hora; se não, a requisição espera a próxima, até 5000 ms (o teto do mock é 30000 ms) e devolve a lista vazia no fim da espera. Acrescente status=delivered para esperar a entrega. É assim que o seu teste espera a mensagem sem sleep.

    curl 'http://localhost:8899/v1/messages?to=%2B5511912340010&wait=5000'

  5. Responda como o aparelho

    O painel faz isso com o teclado; por API, é a rota de controle /_mock/sms/inbound. A resposta entra como mensagem recebida e dispara o webhook de entrada.

    curl -X POST http://localhost:8899/_mock/sms/inbound \
  -H 'Content-Type: application/json' \
  -d '{"from": "+5511912340010", "body": "Recebi, obrigado!"}'

  6. Provoque uma falha

    Os quatro últimos dígitos do destino decidem o desfecho. Um número terminado em 0001 chega a sent e falha com o código 30003; um terminado em 0003 é rejeitado na hora, com 400.

    curl -X POST http://localhost:8899/v1/messages \
  -H 'Content-Type: application/json' \
  -d '{"to": "+5511912340001", "body": "Teste de falha na entrega"}'

    O mesmo desfecho na mão: crie uma mensagem e mude o status dela.

    ID=$(curl -s -X POST http://localhost:8899/v1/messages \
  -H 'Content-Type: application/json' \
  -d '{"to": "+5511912340010", "body": "Teste manual"}' | grep -o '"id": *"[^"]*"' | head -1 | cut -d'"' -f4)
curl -X POST "http://localhost:8899/_mock/sms/messages/$ID/status" \
  -H 'Content-Type: application/json' \
  -d '{"status": "failed", "errorCode": 30003}'

  7. Aponte um cliente Twilio

    O caminho, os corpos de formulário e os códigos de erro são os do Twilio. Qualquer credencial é aceita, porque o mock não valida token:

    curl -X POST http://localhost:8899/2010-04-01/Accounts/ACmock00000000000000000000000000/Messages.json \
  -u ACmock00000000000000000000000000:mock-auth-token \
  -d "To=+5511912340010" \
  -d "From=AMA4DEVS" \
  -d "Body=Seu codigo e 482913"

    Com o SDK oficial, basta trocar a URL base:

    import twilio from 'twilio';

const client = twilio('ACmock00000000000000000000000000', 'mock-auth-token');
client.api.baseUrl = 'http://localhost:8899';

const message = await client.messages.create({
  to: '+5511912340010',
  from: 'AMA4DEVS',
  body: 'Seu codigo e 482913',
});

  8. Desligue

    O mock de SMS guarda mensagens, conversas e o log de webhooks só na memória. Pare o contêiner com Ctrl+C ou docker stop: ao subir de novo, ele começa limpo.