API pública: primeiros passos

A API pública conecta seus sistemas ao Grupos Inteligentes. Você pode consultar dados e automatizar tarefas sem repetir ações no painel.

Antes de começar

Você precisará de:

acesso à sua conta do Grupos Inteligentes;
uma assinatura Scale ativa;
um local seguro para guardar o token;
uma ferramenta capaz de fazer pedidos HTTPS.

Um token de API funciona como uma senha exclusiva da integração. Ele permite que outro sistema acesse os dados da sua conta.

Como criar um token

Entre no aplicativo do Grupos Inteligentes.
Abra Configurações no menu lateral.
Selecione Acesso à API.
Clique em Criar token.
Digite um nome que identifique a integração.
Confirme em Criar.
Copie o token e guarde-o imediatamente.

Use nomes claros, como Automação de relatórios ou Integração do CRM.

Dica: Guarde o token em um gerenciador de senhas ou de segredos. Nunca o coloque em uma página pública, aplicativo de navegador ou arquivo compartilhado.

Faça seu primeiro pedido

O endereço base da API é:

https://api.gruposinteligentes.com/api

Envie o token no cabeçalho Authorization, precedido pela palavra Bearer.

curl --request GET \
  --url https://api.gruposinteligentes.com/api/v1/redirectors \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $GI_API_TOKEN"

No exemplo, GI_API_TOKEN é uma variável segura no seu sistema. Não substitua essa variável por um token real em códigos compartilhados.

Para pedidos que enviam dados, adicione também este cabeçalho:

Content-Type: application/json

Encontre a operação certa

Abra a referência completa da API para consultar:

os endereços disponíveis;
os campos aceitos em cada pedido;
exemplos de respostas;
os possíveis códigos de erro.

A referência mostra exemplos com o cabeçalho Authorization. Por segurança, execute esses exemplos na sua própria ferramenta.

Consulte os grupos de um redirecionador

A API registra grupos que já existem no WhatsApp. Ela não cria grupos novos no WhatsApp. Depois do cadastro, o campo whatsapp_url não pode ser alterado.

Listar grupos: GET /api/v1/redirectors/{redirector}/groups
Consultar um grupo: GET /api/v1/redirectors/{redirector}/groups/{group}

Na lista, você pode usar estes parâmetros:

Parâmetro	Para que serve
`limit`	Quantidade por página. O padrão é 15, e o máximo é 100.
`filter[name]`	Busca grupos pelo nome.
`filter[whatsapp_url]`	Busca grupos pelo link de convite.
`filter[filled_slots]`	Mostra grupos com exatamente esse número de vagas preenchidas.
`filter[empty]`	Mostra grupos publicados que ainda têm vagas.
`sort`	Ordena por `id`, `created_at`, `name`, `filled_slots`, `last_track_at` ou `occupancy`. Use `-` antes do campo para ordem decrescente.

Dica: Para buscar grupos com vagas, use filter[empty]=1&sort=occupancy.

Automatize links preservados

A API também permite preservar um link público ao excluir um redirecionador. Um slug virtual é o nome usado na referência da API para esse link preservado.

Ao excluir o redirecionador original, envie merge_into_redirector_id com o identificador do destino e confirm_merge: true.
Você pode listar e consultar os links preservados da sua conta.
Você pode restaurar o redirecionador original ou agendar a exclusão do link preservado.
Links preservados não podem ser criados ou editados diretamente. Eles surgem somente após uma mesclagem confirmada.

O redirecionador original permanece recuperável por 30 dias. Consulte os campos e respostas de cada operação na referência da API.

Limites e validade

Cada token aceita até 60 pedidos por minuto.
O token permanece ativo até você revogá-lo.
Tokens revogados deixam de funcionar imediatamente.
Tokens de integração não podem criar, listar ou revogar outros tokens.

Para trocar um token, crie outro e atualize sua integração. Depois, revogue o antigo.

Como revogar um token

Revogue um token perdido, exposto ou que não seja mais usado:

Abra Configurações no aplicativo.
Selecione Acesso à API.
Encontre o token pelo nome.
Clique em Revogar e confirme.

A integração deixa de acessar sua conta assim que você confirma.

Erros comuns

Código	O que significa	Como resolver
`401`	Token inválido ou revogado	Crie um token e atualize a integração
`403`	O plano atual não permite usar tokens	Ative ou renove o plano Scale
`404`	O item não existe, não é da sua conta ou o identificador está em formato inválido	Confira os identificadores usados no endereço
`422`	Algum campo está ausente ou incorreto	Confira os campos na referência da API
`429`	Muitos pedidos em pouco tempo	Aguarde e reduza a frequência dos pedidos
`503`	A criação de redirecionadores está indisponível no momento	Aguarde os segundos indicados no cabeçalho `Retry-After` e tente de novo

Se ainda precisar de ajuda, envie um e-mail para suporte@gruposinteligentes.com.