API Aivo Suite — guia e exemplos para integradores

Documentação e exemplos prontos para consumir a API pública v1 da Aivo Suite com um token da sua organização. Tudo aqui é código de exemplo: use, copie e adapte.

Este repositório não contém credenciais. Todo exemplo lê o token de uma variável de ambiente. Se você chegou aqui procurando um token, ele é gerado por você mesmo, no painel — veja abaixo.

Índice

Documento	Responde
docs/autenticacao.md	como criar o token, como enviá-lo e o que são escopos
docs/endpoints.md	que módulos existem, URLs base e recursos de cada um
docs/erros-e-limites.md	formato de erro, rate limit, retentativa e paginação
docs/seguranca.md	como guardar e rotacionar o token sem se expor
docs/limitacoes-conhecidas.md	o que ainda não funciona como deveria, e o contorno
SECURITY.md	como reportar uma vulnerabilidade

1. Crie o seu token

No painel: Contas → Conta → Tokens de API (é preciso ser owner ou admin da organização). O valor — algo como aivo_org_... — aparece uma única vez; guarde-o no cofre de segredos da sua aplicação.

O token pertence à organização: as respostas já vêm restritas aos dados dela. Você nunca envia o id da organização nas chamadas.

2. Primeira chamada

export AIVO_TOKEN="aivo_org_xxxxxxxxxxxx"

curl -H "Authorization: Bearer $AIVO_TOKEN" \
  https://contas.aivosuite.com/api/v1/auth/me

Se responder com os dados da sua organização, está tudo certo. Se responder 401, o token está errado, expirado ou revogado.

3. Exemplos completos

Cada exemplo faz o mesmo roteiro — identifica a organização, lista leads com paginação e trata erro, limite e retentativa — para você comparar e escolher:

Linguagem	Como rodar	Dependências
Python	python quickstart.py	requests
Node.js	node quickstart.mjs	nenhuma (Node 18+)
PHP	php quickstart.php	nenhuma (ext-curl)

4. Módulos disponíveis

Módulo	URL base	Principais recursos
Vendas (CRM)	https://vendas.aivosuite.com/api/v1	leads, produtos, funis, cadencias, canais-aquisicao, tags, creditos, prospeccoes, dashboard/metricas-historicas, atendimento/conversas
Teams	https://teams.aivosuite.com/api/v1	tarefas, tarefas/boards, tarefas/pipelines, equipes, desafios, medalhas, meu-time/agenda/reunioes
Contas	https://contas.aivosuite.com/api/v1	auth/me, organization/verify-status, billing/modules

Cada módulo publica a especificação legível por máquina em GET <base>/openapi (OpenAPI 3.1) e uma página navegável em /docs. Detalhes em docs/endpoints.md.

5. Sem escrever código

Se o objetivo é apenas conversar com os dados — perguntar sobre leads, pipeline, métricas — existe o conector MCP da Aivo para o Claude, que não exige integração nenhuma. Instruções em docs/endpoints.md.

Suporte

Dúvidas de integração: fale com o seu contato comercial na Aivo. Para relatar um problema de segurança, siga o SECURITY.md — não abra issue pública.

Licença

MIT. Os exemplos são fornecidos como estão, para você adaptar.