Glossário

Organização

A unidade isolada de dados no CRM. Cada API key pertence a uma organização e só acessa dados daquela organização. Identificada por UUID (organization_id).

API key

Token Bearer no formato crm_live_<random> (64 chars) usado para autenticar requisições à API. Criada em Configurações → API no console do CRM, rotacionável e revogável.

Escopo

Permissão granular associada a uma API key. Determina quais endpoints e operações a chave pode acessar (ex: contacts:read, messages:write). Veja Escopos mínimos.

Contato

Pessoa registrada no CRM. Pode ter múltiplos identificadores (telefone, email) e estar associada a múltiplas conversas em diferentes canais.

Conversa

Sequência de mensagens entre um contato e a organização em um único canal. Um contato pode ter conversas paralelas em WhatsApp, Instagram, etc.

Mensagem

Unidade individual de comunicação dentro de uma conversa. Tem direction (inbound = enviada pelo contato; outbound = enviada pela organização) e channel.

Canal

Origem da conversa. Valores possíveis hoje:

• whatsapp — WhatsApp via Evolution API
• whatsapp_cloud_api — WhatsApp via Meta Cloud API oficial
• instagram — Instagram Direct
• telegram — Telegram
• email — Email

Direction (direção)

• inbound — mensagem recebida (enviada pelo contato à organização)
• outbound — mensagem enviada (pela organização ao contato)
• all — ambas, quando usado como filtro

Match (modo de combinação)

Ao buscar por múltiplos termos:

• any — retorna contatos que mencionaram pelo menos um dos termos
• all — retorna contatos que mencionaram todos os termos (em qualquer mensagem)

Termo / keyword

String de busca (palavra ou frase). A API normaliza acentos e capitalização. Veja Buscar leads por termo.

Paginação

Mecânica de dividir resultados grandes em páginas. A API usa offset (limit + offset). Veja Paginação.

Beta

Status de maturidade. API funcional e suportada, mas com possibilidade de mudança de contrato. Mudanças quebradoras vêm com 30+ dias de aviso via changelog e header Sunset.

GA (General Availability)

Status final. Contrato estável. Mudanças quebradoras só em major version bump.

Idempotency-Key

Header em requisições POST/PUT/DELETE (futuras) para evitar duplicação em retry. UUID v4 por intenção de negócio. Cache de 24h no servidor.

Sunset header

Header HTTP RFC 8594 que indica data futura de remoção de um endpoint deprecado. Formato: Sunset: Sat, 31 Dec 2026 23:59:59 GMT.