Recursos da API

Índice dos 28 recursos da API pública do SunchatPlus, com o caminho base de cada um e o que ele cobre.

A API pública tem 212 endpoints organizados em 28 recursos. Esta página é o índice. Use-a para descobrir onde está o que você precisa, e clique no nome do recurso para abrir o endpoint, com parâmetros, corpo, respostas e um playground para testar com a sua chave.

Os caminhos base não seguem um padrão único de nome. Há /v1/contatodechat, /v1/produto no singular e /v1/message em inglês. São nomes herdados de versões anteriores, mantidos para não quebrar integrações que já rodam. Copie o caminho da página do endpoint em vez de deduzi-lo.

Atendimento e mensagens

Recurso	Caminho base	Cobre
Atendimentos	`/v1/atendimento`	Conversas: abertura, atribuição, prioridade, status, etiquetas, mensagens, transferência para fluxo ou agente de IA e finalização
Mensagens	`/v1/message`	Envio ativo de texto, mídia, áudio e template do WhatsApp por um canal
Canais	`/v1/canais`	Consulta das conexões de mensageria. Somente leitura, porque canais nascem na plataforma

Atendimentos é o segundo maior recurso da API, atrás só de pipelines. Fora o CRUD da conversa, ele expõe as mensagens dela em /v1/atendimento/{idAtendimento}/mensagens, com criação, edição, exclusão e reenvio. Os guias de tela correspondentes são caixa de entrada e conversas.

Contatos e pessoas

Recurso	Caminho base	Cobre
Contatos	`/v1/contatodechat`	Contatos de chat, com anotações, etiquetas, avatar, caixas de entrada por canal e histórico de atendimentos
Pessoas	`/v1/pessoas`	Pessoa física ou jurídica por trás do contato, com endereço e dados fiscais
Listas de Contato	`/v1/listas-de-contato`	Listas usadas em campanhas e segmentações

Contato e pessoa são coisas diferentes. O contato é um ponto de contato, como um número de WhatsApp ou um perfil de Instagram. A pessoa é o cadastro que reúne vários contatos. O campo IdPessoa no contato faz o vínculo. Veja contatos e pessoas.

Para sincronizar contatos de outro sistema, use PUT /v1/contatodechat: ele localiza o contato pelo telefone e atualiza, sem precisar do Id. Se o telefone não existir na base, a resposta é 404, e aí você cria com POST. São duas chamadas no pior caso, e nenhuma delas duplica registro.

Funil de vendas

Recurso	Caminho base	Cobre
Pipelines	`/v1/pipelines`	Funis, etapas, negócios, produtos do negócio e atividades
Anotações de Negócio	`/v1/negocios/{idNegocio}/anotacoes`	Anotações registradas em um negócio
Ações Agendadas	`/v1/acoes-agendadas`	Ações programadas para rodar no futuro em um negócio, contato ou conversa
Motivos de Venda	`/v1/motivos-de-venda`	Motivos de ganho e de perda usados ao fechar um negócio
Origens do Negócio	`/v1/origens-do-negocio`	De onde o negócio veio
Tipos de Atividade	`/v1/tipos-de-atividade`	Tipos disponíveis nas atividades dos negócios

Pipelines concentra 47 endpoints porque tudo do funil fica aninhado sob ele:

/v1/pipelines/{idPipeline}/etapas
/v1/pipelines/{idPipeline}/negocios
/v1/pipelines/{idPipeline}/negocios/{idItem}/produtos
/v1/pipelines/{idPipeline}/items/{idItem}/atividades

Dois atalhos poupam trabalho aqui. GET /v1/pipelines/{idPipeline}/negocios/contatos-disponiveis lista contatos que ainda não estão no funil, e POST /v1/pipelines/{idPipeline}/negocios/mover-em-massa move vários negócios de etapa em uma chamada só. Veja funis e negócios.

Help desk

Recurso	Caminho base	Cobre
Tickets	`/v1/ticket`	Consulta por ID ou por código, atualização parcial, interações e campos personalizados
Departamentos	`/v1/departamentos`	Departamentos usados na distribuição de atendimentos e tickets
Campos Personalizados	`/v1/campos-personalizados`	Definição dos campos personalizados da conta

Tickets não têm criação pela API: eles nascem na plataforma, por e-mail ou por automação. Pela API você consulta, altera com PATCH /v1/ticket/{idTicket} e inclui interações com POST /v1/ticket/IncluirInteracao. Veja tickets.

Agenda

Recurso	Caminho base	Cobre
Reuniões	`/v1/reunioes`	Agendamentos e reuniões vinculados a contatos e negócios, com cancelamento

Veja agenda e reuniões.

Produtos e catálogo

Recurso	Caminho base	Cobre
Produtos	`/v1/produto`	Catálogo, com preço, promoção, estoque e atualização parcial
Grupos de Produto	`/v1/grupodeprodutos`	Categorias do catálogo
Grades de Produto	`/v1/produtograde`	Variações por cruzamento de dois eixos, como cor × tamanho
Tabelas de Preço	`/v1/tabelapreco`	Tabelas de preço, com inativação em lote

Produtos é um dos dois recursos com PATCH, o que o torna o caminho natural para sincronizar preço e estoque de um ERP sem reenviar o cadastro inteiro. Veja produtos.

Vendas e pagamentos

Recurso	Caminho base	Cobre
Vendas	`/v1/vendas`	Consulta das vendas e pedidos. Somente leitura
Pagamentos	`/v1/solicitacoes-de-pagamento`	Geração de solicitação de pagamento (link de cobrança)
Operações	`/v1/operacao`	Operações fiscais usadas no cálculo de impostos
Cálculos de Impostos	`/v1/calculoimposto`	Regras de cálculo associadas às operações

A solicitação de pagamento nasce com status Pendente. A confirmação vem do gateway depois, e você a lê no Status da venda. Veja cobranças e loja e pedidos.

Configuração da conta

Recurso	Caminho base	Cobre
Etiquetas	`/v1/etiquetas`	Etiquetas (tags) de contatos, atendimentos e negócios
Usuários	`/v1/usuarios`	Consulta dos usuários e leitura/escrita dos atributos chave-valor de cada um
Variáveis Globais	`/v1/variaveis-globais`	Pares nome/valor da conta, usados em fluxos e mensagens
Scripts	`/v1/scripts`	Scripts de atendimento disponíveis para o time

Os dados cadastrais dos usuários são somente leitura. Criar e desativar usuário se faz na plataforma, em usuários e permissões. O que a API escreve são os atributos do usuário, um espaço livre de chave e valor que serve bem para guardar o identificador dele no seu sistema:

curl -X PUT "$SUNCHAT_BASE/v1/usuarios/$ID_USUARIO/atributos/id_no_erp" \
  -H "X-Ambiente: $SUNCHAT_CONTA" \
  -H "X-Authorization: X-Chave-Api $SUNCHAT_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "Valor": "ERP-4471" }'

Variáveis globais aceitam upsert pelo nome, com PUT /v1/variaveis-globais/nome/{nome}, que cria se não existir e atualiza se existir. É a forma mais simples de a sua integração guardar estado do lado do SunchatPlus, sem precisar de tabela própria.