Agentes de IA

Boa parte das integrações é escrita hoje por um agente, no Cursor, no Claude Code ou no Copilot. O que muda é o seu trabalho: dar o contexto certo antes e revisar o código depois.

Cole isto no seu agente

O prompt abaixo descreve a integração inteira e as regras que costumam sair erradas: chave de teste, texto sem acento, erro tratado por código e envio idempotente.

prompt

Integre o envio de SMS da SMSKit neste projeto.

Documentação: https://smskit.dev/llms.txt (índice) e https://smskit.dev/docs
Base da API: https://api.smskit.dev

Autenticação
- Troque a chave de API pelo token: POST /v1/auth/token com o header X-API-Key.
- O token vale 48 horas e vai em "Authorization: Bearer" nas demais rotas.
- Guarde o token em memória e peça outro ao receber 401 token_expired.
- Em TypeScript e Python, use o SDK oficial (pacote "smskit"): ele já faz a troca e a renovação.

Envio
- POST /v1/sms com "to" em E.164 (+55) e "text", ou "template" + "variables".
- Responde 202 com o envio na fila; o resultado por destinatário vem em GET /v1/sms/{id} ou por webhook.
- Toda mensagem abre com o nome de quem envia: "from" define esse nome e o padrão é a empresa do workspace. No SDK Python o parâmetro é "from_", porque "from" é palavra reservada; no MCP a ferramenta chama "sender". Em um modelo, esse nome preenche a variável "empresa" sozinho.
- O texto final, já com o nome do remetente, tem no máximo 160 caracteres.
- Prefira "template" + "variables" quando a mensagem se repete: o modelo é aprovado uma vez e o envio nunca espera por revisão.
- Envie o header Idempotency-Key em todo envio para que uma repetição não duplique a mensagem.

Regras que não podem ser ignoradas
- Use a chave sk_test_ durante o desenvolvimento: mesmo fluxo, sem entregar nem cobrar.
- O texto é ASCII: sem acento e sem emoji, ou a API responde 422 antes de cobrar.
- Trate o erro por error.code, nunca pela mensagem. Em 429, respeite o header Retry-After.
- Em 409 review_required, a análise automática não aprovou o texto e nada foi cobrado: corrija o texto com o que vier em details, ou repita a requisição com "accept_review": true se aceitar esperar pela revisão manual. Não repita em laço.
- Valide o webhook com HMAC-SHA256 sobre o corpo cru, comparando em tempo constante.
- Não invente endpoints nem campos: o que existe está em https://smskit.dev/docs/referencia.

Dê a documentação inteira

O arquivo llms.txt lista todas as páginas desta documentação com título, descrição e endereço, em uma única requisição. É por onde um agente começa.

terminal

curl https://smskit.dev/llms.txt

Para uma página específica, use o botão ao lado do título. Ele copia a página inteira em markdown, com os exemplos nas três linguagens, pronta para colar na conversa.

Conecte o servidor MCP

Com o MCP o agente passa a operar a conta, e não só a ler a documentação: ele consulta o saldo, lista os modelos aprovados e faz envios com a sua chave. Use uma chave sk_test_ até a integração estar pronta. Os detalhes estão em Servidor MCP.

configuração do cliente

{
  "mcpServers": {
    "smskit": {
      "url": "https://mcp.smskit.dev/mcp",
      "headers": { "Authorization": "Bearer sk_test_..." }
    }
  }
}

O que conferir no código que voltar

Os mesmos pontos aparecem errados com frequência. Confira antes de subir.

O token é reaproveitado enquanto vale e renovado no 401, em vez de ser pedido a cada requisição.
O tratamento de erro usa error.code. Nenhuma comparação depende da mensagem.
Em 429, a espera segue o header Retry-After, sem repetição em laço.
Todo envio leva Idempotency-Key, derivada do identificador do seu pedido e não de um número aleatório.
O webhook confere a assinatura sobre o corpo cru antes de ler o JSON e responde 2xx rápido. A reentrega vai até 6 vezes.
O texto sai sem acento e sem emoji, e os números estão em E.164 com +55.