Documentação da API

Documentação da API SMS

Base URL: https://api.shortcode.com.br

Autenticação:

Authorization: Bearer SEU_TOKEN_AQUI

POST

https://api.shortcode.com.br/messages

Permite o envio de até 1000 mensagens por requisição.

Corpo da Requisição (JSON)

[
  {
    "external_id": "001",
    "number": "41999999999",
    "message": "Ola, esta e uma mensagem."
  }
]

Resposta de sucesso (201):

[
  {
    "external_id": "001",
    "number": "41999999999",
    "operadora": "CLARO",
    "status": "accepted"
  },
  {
    "external_id": "002",
    "number": "41988888888",
    "operadora": "invalido",
    "status": "failed",
    "reason": "Número com operadora inválida"
  }
]

Status Disponíveis

accepted – Envio aceito com sucesso
failed – Envio não aceito (ver reason)

Erros Comuns

Webhook: DLR

Notificação de entrega da mensagem.

{
  "dlrs": [
    {
      "date": "2021-07-14 08:00:07",
      "external_id": "1525",
      "number": "41992375284",
      "operadora": "VIVO",
      "id_status": 3,
      "status": "Entregue com confirmação",
      "message": "Envio de Teste 01"
    }
  ]
}

id_status possíveis

Webhook: MO (Resposta do Cliente)

Notificação quando o cliente responde um SMS.

{
  "mos": [
    {
      "date": "2021-07-14 10:33:47",
      "external_id": "",
      "number": "41992375284",
      "operadora": "VIVO",
      "message": "Me liga por favor"
    }
  ]
}

Documentação da API VOZ

Base URL: https://api.shortcode.com.br

Endpoints:

GET /voz/templates — Lista os templates de áudio disponíveis.
POST /voz/messages — Envia mensagens de voz diretas ou por template.

Autenticação:

Authorization: Bearer SEU_TOKEN_AQUI

GET

https://api.shortcode.com.br/voz/templates

Retorna todos os templates de voz cadastrados para o usuário.

Resposta de sucesso (200):

{
  "templates": [
    {
      "id": 1,
      "nome": "Boas-vindas",
      "descricao": "Mensagem de boas-vindas automatizada",
      "audio_url": "https://app.shortcode.com.br/uploads/audio_boas_vindas.mp3",
      "criado_em": "2025-10-23 10:40:12"
    },
    {
      "id": 2,
      "nome": "Aviso de promoção",
      "descricao": "Template de aviso promocional",
      "audio_url": "https://app.shortcode.com.br/uploads/audio_promocao.mp3",
      "criado_em": "2025-10-21 14:30:44"
    }
  ]
}

POST

https://api.shortcode.com.br/voz/messages

Permite enviar até 300 mensagens de voz por requisição.

Corpo da Requisição (JSON)

[
  {
    "external_id": "voz_001",
    "numero": "5511999999999",
    "tipo": "audio",
    "audio_url": "https://app.shortcode.com.br/uploads/audio_teste.mp3"
  },
  {
    "external_id": "voz_002",
    "numero": "5511888888888",
    "tipo": "template",
    "id_template": 2
  }
]

Resposta de sucesso (201):

[
  {
    "external_id": "voz_001",
    "numero": "5511999999999",
    "status": "accepted",
    "message_id": "voz.82b9fbb7a4c9...",
    "operadora": "Vivo"
  },
  {
    "external_id": "voz_002",
    "numero": "5511888888888",
    "status": "accepted",
    "message_id": "voz.f7a2e9d0a31b...",
    "operadora": "Claro"
  }
]

Erros Comuns

400 – JSON inválido ou campos obrigatórios ausentes
401 – Token ausente ou IP não autorizado
403 – Usuário sem permissão VOZ
404 – Template não encontrado
422 – audio_url inválido (sem http/https)

Webhook: DLR (Relatório de Entrega)

Notificação automática enviada pelo sistema de voz quando ocorre mudança no status da chamada.

{
  "voz_delivery_report": [
    {
      "mensagem_id": "voz.8c3b4c9d1e2f",
      "external_id": "001",
      "numero": "5511999999999",
      "operadora": "Vivo",
      "id_status": 59,
      "status": "Atendida",
      "audio_url": "https://app.shortcode.com.br/uploads/audio_boas_vindas.wav",
      "enviado_em": "2025-10-23 14:00:01",
      "entregue_em": "2025-10-23 14:00:09",
      "duracao_segundos": 8
    },
    {
      "mensagem_id": "voz.7a5f2c1d9b0e",
      "external_id": "voz_002",
      "numero": "5511888888888",
      "operadora": "Claro",
      "id_status": 58,
      "status": "Falha",
      "audio_url": "https://app.shortcode.com.br/uploads/audio_cobranca.wav",
      "enviado_em": "2025-10-23 14:02:00",
      "entregue_em": "2025-10-23 14:02:00",
      "duracao_segundos": 0
    }
  ]
}

id_status possíveis

Documentação da API RCS

Base URL: https://api.shortcode.com.br

Endpoint: POST /rcs/messages

Autenticação:

Authorization: Bearer SEU_TOKEN_AQUI

Informações Gerais

Envie um array de mensagens no corpo (máx. 300 itens).
numero: MSISDN com ou sem 55 (ex.: 5511999999999 ou 11999999999).
agente_id: ID do agente RCS aprovado para o usuário.
external_id: ID externo único por mensagem (evita duplicidade).
fallback_sms: Mensagem alternativa enviada caso o RCS não esteja disponível. Se este campo não for definido, o sistema registrará a tentativa como falha em RCS e não realizará o envio.
tipo: text | media | carousel | template.
Envios com links/palavras sensíveis podem entrar em revisão interna.

Importante: Se enviar o campo carousel, o tipo deve ser carousel.

POST

https://api.shortcode.com.br/rcs/messages

Permite o envio de até 300 mensagens por requisição.

Corpo da Requisição (JSON)

[
  {
    "external_id": "rcs_001",
    "numero": "5511999999999",
    "agente_id": 7,
    "tipo": "text",
    "mensagem": "Olá! Tudo bem com você?",
    "fallback_sms": "Essa mensagem vai or SMS se não tiver RCS",
    "sugestoes": [
      { "type": "reply", "text": "Suporte", "id": "suporte_1" },
      { "type": "url",   "text": "Site",    "url": "https://shortcode.com.br" },
      { "type": "dial",  "text": "Central", "phone_number": "0800123456" }
    ]
  },
  {
    "external_id": "rcs_002",
    "numero": "11999999999",
    "agente_id": 7,
    "tipo": "media",
    "media_url": "https://exemplo.com/imagem.jpg",
    "mensagem": "Confira nossa nova coleção!"
  },
  {
    "external_id": "rcs_003",
    "numero": "11999999999",
    "agente_id": 7,
    "tipo": "carousel",
    "carousel": [
      {
        "title": "Produto 1",
        "text": "Descrição 1",
        "media": "https://exemplo.com/img1.jpg",
        "buttons": [ { "type": "url", "text": "Ver", "url": "https://produto1.com" } ]
      },
      {
        "title": "Produto 2",
        "text": "Descrição 2",
        "media": { "url": "https://exemplo.com/img2.jpg", "contentType": "image/jpeg" },
        "buttons": [
          { "type": "reply", "text": "Quero", "id": "quero_2" },
          { "type": "dial", "text": "Ligar", "phone_number": "0800123456" }
        ]
      }
    ]
  }
]

Resposta de sucesso (201):

[
  {
    "external_id": "rcs_001",
    "numero": "5511999999999",
    "tipo": "text",
    "status": "accepted",
    "message_id": "rcs.9d6f9cba342...",
    "operadora": "Vivo"
  },
  {
    "external_id": "rcs_002",
    "numero": "11999999999",
    "tipo": "media",
    "status": "accepted",
    "message_id": "rcs.1a2b3c4d5e...",
    "operadora": "Claro"
  },
  {
    "external_id": "rcs_003",
    "numero": "11999999999",
    "tipo": "carousel",
    "status": "accepted",
    "message_id": "rcs.abc123def45...",
    "operadora": "TIM"
  }
]

Erros Comuns

Sugestões (botões)

Sugestões podem ser enviadas como sugestoes (globais) para qualquer tipo ou dentro de cada card do carousel.

[
  {
    "external_id": "rcs_txt_btn",
    "numero": "5511999999999",
    "agente_id": 7,
    "tipo": "text",
    "mensagem": "Como podemos ajudar?",
    "sugestoes": [
      { "type": "reply", "text": "Suporte", "id": "suporte_1" },
      { "type": "url", "text": "Site", "url": "https://shortcode.com.br" },
      { "type": "dial", "text": "Central", "phone_number": "0800123456" }
    ]
  }
]

Máximo de 4 botões.
url deve ser http ou https.
reply exige id; dial exige phone_number.

Carrossel (tipo: carousel)

Envie carousel como array de cards. Cada card deve ter ao menos um dos campos: title, text ou media.

Quantidade de cards: 1 a 10.
media pode ser string URL http/https ou objeto { "url": "..." , "contentType": "..." }.
Botões por card: máximo 4 (tipos: url, dial, reply).

[
  {
    "external_id": "rcs_car001",
    "numero": "11999999999",
    "agente_id": 7,
    "tipo": "carousel",
    "carousel": [
      {
        "title": "Produto 1",
        "text": "Descrição 1",
        "media": "https://exemplo.com/img1.jpg",
        "buttons": [ { "type": "url", "text": "Ver", "url": "https://produto1.com" } ]
      },
      {
        "title": "Produto 2",
        "text": "Descrição 2",
        "media": { "url": "https://exemplo.com/img2.jpg", "contentType": "image/jpeg" },
        "buttons": [ { "type": "reply", "text": "Quero", "id": "quero_2" }, { "type": "dial", "text": "Ligar", "phone_number": "0800123456" } ]
      }
    ],
    "sugestoes": [ { "type": "reply", "text": "Falar com atendente", "id": "atd" } ]
  }
]

Regra: Se o campo carousel estiver presente, o tipo deve ser carousel.

Webhooks RCS

Cadastre URLs para receber atualizações de mensagens recebidas e relatórios de entrega.

📥 messages_received

{
  "messages_received": [
    {
      "message_id": "rcs.9d6f9cba342...",
      "date": "2025-07-08 14:32:00",
      "external_id": "",
      "numero": "5511999999999",
      "mensagem": "Oi, quero saber mais!",
      "tipo": "text",
      "media_url": null
    }
  ]
}

📤 delivery_reports

{
  "delivery_reports": [
    {
      "message_id": "rcs.9d6f9cba342...",
      "date": "2025-07-08 14:32:00",
      "external_id": "rcs_car001",
      "numero": "5511999999999",
      "operadora": "Vivo",
      "tipo": "carousel",
      "tipo_envio": "single",
      "id_status": 22,
      "status": "lido"
    }
  ]
}

📤 rcs_click

{
  "rcs_click": [
    {
      "date": "2025-07-08 14:32:00",
      "external_id": "rcs_car001",
      "numero": "5511999999999",
      "agente_id": 15,
      "click_button": "Quero"
    }
  ]
}

id_status possíveis

Documentação da API WhatsApp Business (WABA)

Base URL: https://api.shortcode.com.br

Endpoint: POST /whatsapp/messages

Autenticação:

Authorization: Bearer SEU_TOKEN_AQUI

Informações Gerais

Envie até 300 mensagens por requisição
canal_id: ID do canal WhatsApp configurado para o usuário
external_id: Identificador único da mensagem
number: Número do destinatário (10 a 15 dígitos)
type: text | template | image | audio | video | document | sticker | location | contact | button | list
fallback_sms (opcional): Mensagem alternativa via SMS se WhatsApp falhar
Templates requerem aprovação prévia do Meta
Mensagens fora de template exigem janela de 24h

POST

https://api.shortcode.com.br/whatsapp/messages

Envio de mensagens pelo WhatsApp Business API oficial.

Exemplo: Mensagem de Texto com Fallback

[
  {
    "external_id": "msg001",
    "number": "5547991170182",
    "canal_id": 1,
    "type": "text",
    "message": "Olá! Como posso ajudar?",
    "fallback_sms": "Olá! Como posso ajudar? (via SMS)"
  }
]

Exemplo: Mensagem de Texto (sem Fallback)

[
  {
    "external_id": "msg001",
    "number": "5547991170182",
    "canal_id": 1,
    "type": "text",
    "message": "Olá! Como posso ajudar?"
  }
]

Exemplo: Template com Fallback

[
  {
    "external_id": "msg002",
    "number": "5547991170182",
    "canal_id": 1,
    "type": "template",
    "fallback_sms": "Olá João Silva, seu pedido está confirmado!",
    "template": {
      "name": "boas_vindas",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "text": "João Silva" }
          ]
        }
      ]
    }
  }
]

Exemplo: Imagem

[
  {
    "external_id": "msg003",
    "number": "5547991170182",
    "canal_id": 1,
    "type": "image",
    "media_url": "https://exemplo.com/imagem.jpg",
    "mimetype": "image/jpeg",
    "caption": "Confira nossa promoção!"
  }
]

Resposta de sucesso (201):

[
  {
    "external_id": "msg001",
    "number": "5547991170182",
    "type": "text",
    "status": "accepted",
    "message_id": "wamid.HBgNNTU0Nzk5MTE3MDE4Mg..."
  }
]

Tipos de Mensagens

1. text - Texto Simples

{
  "type": "text",
  "message": "Sua mensagem aqui",
  "fallback_sms": "Mensagem alternativa via SMS (opcional)"
}

💡 Campo Opcional: fallback_sms pode ser adicionado em qualquer tipo de mensagem para envio automático via SMS caso o WhatsApp falhe.

2. template - Template Aprovado

{
  "type": "template",
  "fallback_sms": "Texto alternativo se WhatsApp falhar (opcional)",
  "template": {
    "name": "nome_do_template",
    "components": [
      {
        "type": "header",
        "parameters": [
          { "type": "image", "image": { "link": "URL_IMAGEM" } }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "text": "Variável 1" },
          { "text": "Variável 2" }
        ]
      },
      {
        "type": "button",
        "index": 0,
        "parameters": [
          { "text": "Código123" }
        ]
      }
    ]
  }
}

3. image - Imagem

{
  "type": "image",
  "media_url": "https://exemplo.com/foto.jpg",
  "mimetype": "image/jpeg",
  "caption": "Legenda opcional"
}

4. video - Vídeo

{
  "type": "video",
  "media_url": "https://exemplo.com/video.mp4",
  "mimetype": "video/mp4",
  "caption": "Assista agora!"
}

5. audio - Áudio

{
  "type": "audio",
  "media_url": "https://exemplo.com/audio.mp3",
  "mimetype": "audio/mpeg"
}

6. document - Documento

{
  "type": "document",
  "media_url": "https://exemplo.com/arquivo.pdf",
  "mimetype": "application/pdf",
  "caption": "Contrato anexo"
}

7. button - Botões Interativos

{
  "type": "button",
  "interactive": {
    "body": "Escolha uma opção:",
    "buttons": [
      { "id": "btn1", "title": "Opção 1" },
      { "id": "btn2", "title": "Opção 2" },
      { "id": "btn3", "title": "Opção 3" }
    ]
  }
}

8. list - Lista Interativa

{
  "type": "list",
  "interactive": {
    "header": "Menu Principal",
    "body": "Selecione uma categoria:",
    "footer": "Atendimento 24h",
    "button": "Ver opções",
    "sections": [
      {
        "title": "Produtos",
        "rows": [
          { "id": "prod1", "title": "Produto A", "description": "Descrição A" },
          { "id": "prod2", "title": "Produto B", "description": "Descrição B" }
        ]
      }
    ]
  }
}

Templates com Variáveis

Templates devem ser previamente aprovados pelo Meta e cadastrados no sistema.

⚠️ Importante: A quantidade de variáveis enviadas deve corresponder exatamente ao template cadastrado.

Estrutura de Components:

header – Cabeçalho com texto ou mídia
body – Corpo da mensagem com variáveis
button – Botões dinâmicos (com index)

Exemplo Completo:

{
  "type": "template",
  "template": {
    "name": "confirmacao_pedido",
    "components": [
      {
        "type": "header",
        "parameters": [
          { "type": "image", "image": { "link": "https://exemplo.com/logo.jpg" } }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "text": "João" },
          { "text": "12345" },
          { "text": "R$ 150,00" }
        ]
      },
      {
        "type": "button",
        "index": 0,
        "parameters": [
          { "text": "https://loja.com/pedido/12345" }
        ]
      }
    ]
  }
}

Fallback SMS

Configure uma mensagem alternativa para ser enviada via SMS caso o envio via WhatsApp falhe.

✅ Quando usar: Garanta que sua mensagem chegue ao destinatário mesmo se ele não tiver WhatsApp ativo ou houver falha no envio.

Exemplo com Fallback:

[
  {
    "external_id": "msg001",
    "number": "5547991170182",
    "canal_id": 1,
    "type": "template",
    "template": {
      "name": "boas_vindas",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "text": "João Silva" }
          ]
        }
      ]
    },
    "fallback_sms": "Olá João Silva, bem-vindo ao nosso sistema!"
  }
]

Como funciona:

1️⃣ Sistema tenta enviar via WhatsApp
2️⃣ Se falhar (número sem WhatsApp, erro de envio, etc)
3️⃣ Envia automaticamente via SMS usando o texto do fallback_sms
✅ Você recebe notificação do canal usado (WhatsApp ou SMS)

⚠️ Opcional: O campo fallback_sms é opcional. Se não for fornecido e o WhatsApp falhar, a mensagem não será enviada.

Janela de Conversação (24 horas)

Mensagens fora de template só podem ser enviadas dentro de 24 horas após a última mensagem recebida do cliente.

💡 Regra: Se não houver mensagem recebida nas últimas 24 horas, você DEVE usar um template aprovado.

✅ Dentro da janela: Qualquer tipo de mensagem
❌ Fora da janela: Apenas templates aprovados
🔄 Janela reinicia: A cada mensagem recebida

Webhooks WhatsApp

Você pode cadastrar URLs para receber atualizações automáticas sobre mensagens enviadas ou recebidas.

🔔 Notificações em tempo real: Configure seus webhooks para receber eventos assim que eles acontecerem.

📩 messages_received (mensagens recebidas)

Disparado quando o cliente envia uma mensagem para seu número oficial.

Exemplo de Payload:

{
  "messages_received": [
    {
      "message_id": "wamid.HBgNNTU0Nzk5MTE3MDE4Mg...",
      "date": "2025-07-08 14:32:08",
      "external_id": "",
      "number": "5547991170182",
      "message": "Oi, quero saber mais!",
      "type": "text",
      "media_url": null
    }
  ]
}

Campos do Payload:

message_id – ID único da mensagem no WhatsApp
date – Data e hora do recebimento
external_id – ID externo (vazio para mensagens recebidas)
number – Número do cliente que enviou a mensagem
message – Conteúdo da mensagem
type – Tipo da mensagem (text, image, audio, video, document, etc)
media_url – URL do arquivo de mídia (se aplicável)

📊 delivery_reports (relatório de entrega)

Disparado quando há atualização de status de mensagens enviadas (enviada, entregue, lida, falha).

Exemplo de Payload:

{
  "delivery_reports": [
    {
      "message_id": "wamid.HBgNNTU0Nzk5MTE3MDE4Mg...",
      "date": "2025-07-08 14:32:08",
      "external_id": "mh-0001",
      "number": "5541999999999",
      "type": "text",
      "status": "delivered"
    }
  ]
}

Campos do Payload:

message_id – ID único da mensagem no WhatsApp
date – Data e hora da atualização
external_id – ID externo enviado por você na requisição
number – Número do destinatário
type – Tipo da mensagem
status – Status atual da mensagem

Status possíveis:

sent – Mensagem enviada
delivered – Mensagem entregue ao celular
read – Mensagem lida
failed – Falha no envio

💡 Configuração: Configure suas URLs de webhook no painel administrativo da plataforma.

⚠️ Importante: Sua URL deve responder com status HTTP 200 para confirmar o recebimento. Caso contrário, tentaremos reenviar o webhook.

Erros Comuns

400 – JSON inválido ou limite excedido
400 – Tipo de mensagem inválido
400 – Campos obrigatórios ausentes
400 – Canal não encontrado ou não pertence ao usuário
400 – Número inválido (deve ter 10-15 dígitos)
400 – Template não cadastrado
400 – Quantidade de variáveis incorreta
400 – Sem janela de conversação (use template)
400 – media_url ou mimetype ausente
401 – Token ausente ou inválido

Documentação da API de Links Encurtados

Base URL: https://api.shortcode.com.br

Endpoint: /links

Autenticação:

Authorization: Bearer SEU_TOKEN_AQUI

Tipos de Links

Link Encurtado – Redireciona para uma URL personalizada
WhatsApp – Abre conversa no WhatsApp com mensagem pré-definida
Rotativo – Distribui conversas entre múltiplos números de WhatsApp

GET

https://api.shortcode.com.br/links

Lista todos os links do usuário. Opcionalmente filtre por tipo usando o parâmetro tipo.

Exemplos de Requisição

GET /links
GET /links?tipo=Link Encurtado
GET /links?tipo=Whatsapp
GET /links?tipo=Rotativo

Resposta de sucesso (200):

[
  {
    "id": 1,
    "id_dominio": 5,
    "keyword": "promo2025",
    "url": "https://seusite.com/promocao-2025",
    "mensagem": null,
    "celular": null,
    "celulares": null,
    "data": "2025-11-18 10:30:00",
    "status": "Aprovado",
    "tipo": "Link Encurtado"
  },
  {
    "id": 2,
    "id_dominio": 5,
    "keyword": "suporte",
    "url": "https://api.whatsapp.com/send?phone=47991170182&text=Ol%C3%A1%2C%20preciso%20de%20ajuda%21",
    "mensagem": "Olá, preciso de ajuda!",
    "celular": "47991170182",
    "celulares": null,
    "data": "2025-11-18 11:00:00",
    "status": "Aprovado",
    "tipo": "Whatsapp"
  },
  {
    "id": 3,
    "id_dominio": 5,
    "keyword": "vendas",
    "url": "https://api.whatsapp.com/send?text=Quero%20mais%20informa%C3%A7%C3%B5es",
    "mensagem": "Quero mais informações",
    "celular": null,
    "celulares": "47991170182,47984629062,47991916262",
    "data": "2025-11-18 11:30:00",
    "status": "Aprovado",
    "tipo": "Rotativo"
  }
]

POST

https://api.shortcode.com.br/links

1. Criar Link Encurtado

Cria um link que redireciona para uma URL de sua escolha.

Corpo da Requisição (JSON)

{
  "tipo": "link",
  "id_dominio": 5,
  "keyword": "promo2025",
  "url": "https://seusite.com/promocao-2025"
}

Campos obrigatórios:

tipo – "link"
id_dominio – ID do domínio cadastrado
keyword – Palavra-chave única (alfanuméricos, hífens e underscores)
url – URL de destino completa (http/https)

Resposta de sucesso (201):

{
  "success": true,
  "id": 10,
  "message": "Link criado com sucesso",
  "link_rastreavel": "@@LinkRastreavel10@@"
}

POST

https://api.shortcode.com.br/links

2. Criar Link WhatsApp

Cria um link que abre conversa no WhatsApp com mensagem pré-digitada.

Corpo da Requisição (JSON)

{
  "tipo": "whatsapp",
  "id_dominio": 5,
  "keyword": "suporte",
  "mensagem": "Olá, preciso de ajuda!",
  "celular": "47991170182"
}

Campos obrigatórios:

tipo – "whatsapp"
id_dominio – ID do domínio cadastrado
keyword – Palavra-chave única
celular – Número do WhatsApp (apenas números, mínimo 10 dígitos)

Campos opcionais:

mensagem – Mensagem pré-digitada (padrão: vazio)

Nota: A URL gerada automaticamente usará a API oficial do WhatsApp no formato:
https://api.whatsapp.com/send?phone=CELULAR&text=MENSAGEM

Resposta de sucesso (201):

{
  "success": true,
  "id": 11,
  "message": "Link WhatsApp criado com sucesso",
  "link_rastreavel": "@@LinkRastreavel11@@"
}

POST

https://api.shortcode.com.br/links

3. Criar Link Rotativo

Cria um link que distribui conversas entre múltiplos números de WhatsApp.

Corpo da Requisição (JSON)

{
  "tipo": "rotativo",
  "id_dominio": 5,
  "keyword": "vendas",
  "mensagem": "Quero mais informações sobre o produto",
  "celulares": "47991170182,47984629062,47991916262"
}

Ou envie como array:

{
  "tipo": "rotativo",
  "id_dominio": 5,
  "keyword": "vendas",
  "mensagem": "Quero mais informações sobre o produto",
  "celulares": ["47991170182", "47984629062", "47991916262"]
}

Campos obrigatórios:

tipo – "rotativo"
id_dominio – ID do domínio cadastrado
keyword – Palavra-chave única
celulares – String separada por vírgula ou array com no mínimo 2 celulares

Campos opcionais:

mensagem – Mensagem pré-digitada (padrão: vazio)

Resposta de sucesso (201):

{
  "success": true,
  "id": 12,
  "message": "Link Rotativo criado com sucesso",
  "link_rastreavel": "@@LinkRastreavel12@@"
}

🔍 Rastreamento de Cliques

Todos os links criados incluem automaticamente um código de rastreamento que permite monitorar os cliques.

✅ Formato do Link Rastreável:
@@LinkRastreavelID@@

Onde ID é o identificador único do link retornado na criação.

Como usar:

Use o código retornado no campo link_rastreavel em suas mensagens.

Exemplo prático:

// Após criar o link, você recebe:
{
  "success": true,
  "id": 15,
  "message": "Link criado com sucesso",
  "link_rastreavel": "@@LinkRastreavel15@@"
}

// Use em uma mensagem SMS:
"Confira nossa promoção: @@LinkRastreavel15@@"

// Ou em um e-mail HTML:
<a href="@@LinkRastreavel15@@">Clique aqui</a>

// O sistema converterá automaticamente para a URL real
// e registrará cada clique para análise

Benefícios:

📊 Monitore quantas pessoas clicaram no link
📅 Veja data e hora de cada clique
🌍 Identifique origem dos acessos
📱 Rastreie conversões e engajamento
👤 Saiba quem clicou no seu número

💡 Como funciona o rastreamento por destinatário:
Quando você envia mensagens via SMS, RCS ou qualquer outro canal do nosso sistema usando o código @@LinkRastreavel4@@, geramos automaticamente um link com terminação única para cada destinatário. Dessa forma, conseguimos identificar exatamente quem clicou no link, permitindo análises detalhadas de engajamento individual.

📡 Webhook: Cliques nos Links

Receba notificações automáticas em tempo real sempre que alguém clicar em seus links rastreáveis.

⚙️ Configuração: Configure a URL do webhook no painel de controle para receber as notificações de cliques.

Payload do Webhook:

{
  "clicks": [
    {
      "date": "2025-11-19 14:30:45",
      "external_id": "1525",
      "number": "5547991170182",
      "ip_address": "177.174.250.22",
      "country": "BR",
      "region": "SC",
      "city": "Florianópolis",
      "click_type": "human"
    },
    {
      "date": "2025-11-19 14:31:12",
      "external_id": "1525",
      "number": "5511987654321",
      "ip_address": "200.123.45.67",
      "country": "BR",
      "region": "SP",
      "city": "São Paulo",
      "click_type": "human"
    },
    {
      "date": "2025-11-19 14:33:00",
      "external_id": "1525",
      "number": "5547991170182",
      "ip_address": "66.249.83.71",
      "country": "US",
      "region": "CA",
      "city": "Mountain View",
      "click_type": "robot"
    }
  ]
}

Campos do Payload:

date – Data e hora exata do clique (formato: YYYY-MM-DD HH:MM:SS)
external_id – ID externo do link (use para correlacionar com suas campanhas)
number – Número de telefone do destinatário que clicou
ip_address – Endereço IP de origem do clique
country – Código do país (ex: BR, US, AR)
region – Código do estado/região (ex: SC, SP, CA)
city – Cidade de origem do clique
click_type – Tipo de clique: human (pessoa) ou robot (bot/crawler)

Características:

✅ Notificação em tempo real
✅ Suporte a múltiplos cliques em batch
✅ Geolocalização automática (país, região, cidade)
✅ Detecção automática de bots vs humanos (click_type)
✅ Rastreamento por destinatário individual
✅ Cada notificação é enviada apenas uma vez

💡 Dica: Use o campo number para identificar qual destinatário clicou no link e o external_id para correlacionar com suas campanhas de SMS, RCS ou WhatsApp.

🤖 Click Type: O campo click_type ajuda a filtrar cliques reais de pessoas (human) de acessos automáticos de bots e crawlers (robot), como Google Bot, que não representam interesse real.

PUT

https://api.shortcode.com.br/links

Editar Link

Atualiza um link existente. O sistema detecta automaticamente o tipo do link e permite atualizar apenas os campos desejados.

Exemplo: Editar Link Encurtado

{
  "id": 10,
  "keyword": "nova-keyword",
  "url": "https://novosite.com/nova-pagina",
  "id_dominio": 6
}

Exemplo: Editar Link WhatsApp

{
  "id": 11,
  "mensagem": "Nova mensagem pré-definida",
  "celular": "47999887766"
}

Exemplo: Editar Link Rotativo

{
  "id": 12,
  "celulares": ["47991111111", "47992222222", "47993333333"]
}

Importante: Ao alterar a keyword de links WhatsApp ou Rotativo, a URL será automaticamente atualizada.

Resposta de sucesso (200):

{
  "success": true,
  "message": "Link atualizado com sucesso"
}

DELETE

https://api.shortcode.com.br/links

Deletar Link

Remove permanentemente um link do sistema.

Corpo da Requisição (JSON)

{
  "id": 10
}

Resposta de sucesso (200):

{
  "success": true,
  "message": "Link deletado com sucesso"
}

Erros Comuns

400 – JSON inválido, campos obrigatórios ausentes ou URL/celular inválido
400 – Domínio não pertence ao usuário
400 – Keyword já existe
400 – Keyword inválida (use apenas letras, números, hífens e underscores)
400 – Link não encontrado ou não pertence ao usuário
400 – Link rotativo precisa de pelo menos 2 celulares
401 – Token ausente ou IP não autorizado
403 – Token inválido
405 – Método não permitido