> For the complete documentation index, see [llms.txt](https://docs.smsfunnel.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smsfunnel.com.br/api/parceiros/quickstart.md). # Quickstart Este guia mostra, em poucos minutos, como autenticar-se e realizar seu **primeiro envio de SMS** através da API Oficial da SMS Funnel. {% hint style="success" %} **A URL de base de todos os endpoints é**: {% endhint %} #### Pré-requisitos 1. Ter a **API de Parceiros habilitada** em sua conta. Caso ainda não tenha, entre em contato com nosso suporte. 2. Possuir uma **Chave de API** válida. Veja como gerá-la em Autenticação. 3. Possuir **créditos de SMS** disponíveis em sua conta. *** ### Passo 1 — Autenticação Todas as requisições devem conter o header `Authorization` com sua Chave de API no formato `Bearer`. ```json Authorization: Bearer ``` {% hint style="danger" %} **ATENÇÃO:** Não compartilhe sua Chave de API com terceiros. Este conteúdo é de uso confidencial e exclusivo seu. {% endhint %} *** ### Passo 2 — Enviar seu primeiro SMS **POST**** /sms/messages** **Função:** Enfileira o disparo de uma ou mais mensagens SMS. Cada chamada gera um **broadcast** que agrupa as mensagens enviadas. **Exemplo de requisição:** {% code title="cURL" %} ```bash curl -X POST "https://web.smsfunnel.com.br/api/parceiros/v1/sms/messages" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "to": "5511999999999", "message": "Ola! Esta e sua primeira mensagem via SMS Funnel." } ] }' ``` {% endcode %} **Corpo de envio:** ```json5 { "messages": [ // Lista de mensagens (1 a 5000) { "to": "5511999999999", // Telefone do destinatário (10 a 15 dígitos, com DDI/DDD) "message": "Ola! Esta e sua primeira mensagem via SMS Funnel.", // Texto (1 a 1530 caracteres) "reference": "pedido-123" // Opcional: seu identificador. Se omitido, geramos um automaticamente. } ] } ``` **Corpo de resposta — `202 Accepted`:** ```json5 { "broadcast_id": "019c7114-7c4b-77b6-8deb-12cb5c885ea5", // ID do broadcast gerado "messages": [ { "id": "019c7114-abab-7da9-9a46-4da50bd49147", // ID da mensagem "reference": "pedido-123", // Sua referência (ou a gerada por nós) "phone": "5511999999999", // Telefone normalizado "status": "queued", // Status inicial: enfileirada "bill_factor": 1 // Quantidade de créditos consumidos por esta mensagem } ], "unsupported_features": [] // Recursos solicitados que não foram aplicados, se houver } ``` {% hint style="info" %} O status `202 Accepted` indica que as mensagens foram **aceitas e enfileiradas** para envio. O disparo ocorre de forma assíncrona — utilize o **Passo 3** para acompanhar o andamento. {% endhint %} *** ### Passo 3 — Acompanhar o envio **GET**** /sms/broadcasts/{broadcast\_id}** **Função:** Consulta os detalhes e as métricas de um broadcast. Utilize o `broadcast_id` retornado no Passo 2. **Exemplo de requisição:** {% code title="cURL" %} ```bash curl -X GET "https://web.smsfunnel.com.br/api/parceiros/v1/sms/broadcasts/019c7114-7c4b-77b6-8deb-12cb5c885ea5" \ -H "Authorization: Bearer " ``` {% endcode %} **Corpo de resposta — `200 OK`:** ```json5 { "id": "019c7114-7c4b-77b6-8deb-12cb5c885ea5", // ID do broadcast "name": "Broadcast #019c7114", // Nome do broadcast "message": "Ola! Esta e sua primeira mensagem via SMS Funnel.", // Mensagem enviada "status": "completed", // Status atual do broadcast "scheduled_date": null, // Data de agendamento, se houver "leads_count": 1, // Quantidade de destinatários "partner_reference": null, // Referência informada por você no envio "flash_sms": false, // Se foi enviado como flash SMS "concat": false, // Se a concatenação de mensagens longas está ativa "from": null, // Remetente personalizado, se houver "idempotency_key": "019c7114-...", // Chave de idempotência do envio "created_at": "2026-06-30 12:00:00", // Data/hora de criação "metrics": { "sent": 1, // Mensagens enviadas "failed": 0, // Mensagens com falha "total": 1 // Total de mensagens } } ``` *** ### Personalizando com "Meu Link" Para incluir um link encurtado e rastreável em sua mensagem, utilize a variável `{meu_link}` no texto e informe o campo `url` na requisição. Nós encurtamos o link automaticamente e contabilizamos os cliques. ```json5 { "url": "https://minhaloja.com/promo", // Obrigatório quando a mensagem contém {meu_link} "messages": [ { "to": "5511999999999", "message": "Aproveite nossa promocao! Acesse: {meu_link}" } ] } ``` {% hint style="warning" %} O campo `url` é **obrigatório** quando alguma mensagem contém `{meu_link}` e **não deve ser enviado** caso nenhuma mensagem utilize a variável. {% endhint %} *** ### Evitando envios duplicados (Idempotência) Para garantir que um reenvio da mesma requisição (por exemplo, após um timeout de rede) não gere disparos duplicados, envie o header opcional `Idempotency-Key` com um valor único por operação (máx. 80 caracteres). ```json Idempotency-Key: pedido-123-envio-01 ``` Se recebermos uma nova requisição com a mesma chave em até **24 horas**, retornamos a **mesma resposta original** sem reprocessar o envio. Nesses casos, a resposta incluirá o header `Idempotency-Replayed: true`. *** ### Código de Erros Comuns * `401 Unauthorized`: Chave de API ausente, inválida ou não foi possível identificar o parceiro. * `402 Payment Required` (`INSUFFICIENT_CREDITS`): Créditos de SMS insuficientes para o envio. * `403 Forbidden`: Sua conta não possui a API de Parceiros habilitada. * `404 Not Found`: Recurso (broadcast/campanha) não encontrado ou não pertence à sua conta. * `409 Conflict`: Operação não permitida no estado atual (ex.: cancelar broadcast já finalizado) ou requisição concorrente. * `422 Unprocessable Entity` (`VALIDATION_ERROR`): Algum campo do corpo da requisição é inválido. * `429 Too Many Requests` (`RATE_LIMIT_EXCEEDED`): Limite de **60 requisições por minuto** excedido. Consulte o header `Retry-After`. * `502 Bad Gateway` (`SHORTENER_UNAVAILABLE`): Falha temporária ao encurtar o link de "Meu Link". Tente novamente. * `500 Internal Server Error`: Ocorreu um erro interno ao processar a requisição. **Corpo de resposta de erro:** ```json5 { "error": { "code": "VALIDATION_ERROR", // Código do erro "message": "Mensagem descritiva do erro", // Descrição "details": { // Opcional: detalhes por campo (presente em erros de validação) "messages.0.to": [ "O campo to e obrigatorio." ] } } } ```