Changelog da API - Novus CRM

Histórico de mudanças da API pública do Novus CRM. Aqui entram endpoints novos, campos novos em requisições e respostas, mudanças de comportamento e ferramentas MCP. Esta página é para quem integra sistemas com o Novus CRM. As novidades da plataforma, como telas e recursos que aparecem para quem usa o produto, ficam em Novidades.

Os caminhos abaixo são relativos à base da API pública e usam a versão v1. A autenticação por chave de API continua a mesma — veja Autenticação. A referência completa dos endpoints está na aba API.

Atualizações recentes

Configure o departamento alternativo na ausência de atendentes

As rotas de departamentos aceitam e retornam o campo opcional idDepartamentoAlternativoNaAusencia. Ele identifica o departamento que recebe o atendimento quando não há atendente elegível no departamento original.O departamento alternativo precisa pertencer à mesma conta, estar ativo e ser diferente do departamento configurado. Se ele também não tiver atendentes disponíveis, o atendimento permanece pendente no departamento original.

Use o servidor MCP sem afinidade de sessão

O transporte HTTP do servidor MCP da API pública agora é stateless. Você pode distribuir as requisições entre réplicas do serviço.Não é necessário manter a mesma sessão em uma réplica específica.

A assinatura das ferramentas MCP não mudou. Se a sua infraestrutura usava afinidade de sessão, essa configuração deixa de ser necessária para o servidor MCP.

Atualize um atendimento e reinicie a base do tempo de espera

PUT /v1/atendimento/{idAtendimento} continua com a mesma assinatura. Quando idDepartamento muda, a API passa a registrar uma nova entrada no departamento.

A alteração de departamento reinicia a base usada para calcular o tempo de espera na fila. Os demais campos e regras da rota permanecem iguais.

Resposta de pipeline informa a origem do responsável

As atividades por etapa nas respostas de pipeline passam a trazer o campo origemDoResponsavel. O valor indica quem recebe a atividade.Ele informa se a atividade não tem responsável, usa uma pessoa específica ou acompanha o responsável do negócio.

Atualizações parciais de ticket disparam fluxos

PATCH /v1/ticket/{idTicket} mantém a mesma assinatura. Depois de gravar a alteração, a API também pode executar os fluxos configurados para o gatilho de atualização do ticket.

A mudança é de comportamento. Confira o estado do ticket antes de repetir uma chamada quando o seu fluxo de integração também reagir ao evento.

Listagens reduzem textos ricos

As listagens públicas de anotações de negócio, contatos, negócios e produtos removem imagens embutidas. Os textos ricos ficam limitados a 500 caracteres.O restante da resposta mantém os mesmos campos.

Filtre negócios por criação, fechamento e falta de interação

GET /v1/pipelines/{idPipeline}/negocios aceita os filtros opcionais criacaoInicio, criacaoFim, fechamentoInicio, fechamentoFim e semInteracaoDesde.criacaoInicio e fechamentoInicio são inclusivos. criacaoFim, fechamentoFim e semInteracaoDesde são exclusivos. Todos usam datas em ISO 8601.Cada item da resposta também traz dataDaUltimaInteracao, dataDeEntradaNaEtapa, dataDeFechamento e nomeEtapa.

A ferramenta MCP listar_negocios recebeu os mesmos cinco filtros de data e comportamento.

Configure os dias que não contam no prazo da atividade

As respostas de pipeline passam a trazer diasIgnorados nas atividades por etapa. O campo é uma lista de números de 0 a 6, em que 0 representa domingo. Uma lista vazia mantém a contagem em dias corridos.

Crie tickets sem usuário logado

POST /v1/ticket pode criar um ticket sem uma sessão de usuário. O ticket identifica a origem como Integração via API.

Se a integração dependia de um usuário logado para criar tickets, remova essa exigência no cliente e trate a origem Integração via API na resposta.

Crie tickets pela API pública

POST /v1/ticket cria um ticket e retorna o recurso criado com status 201 Created.

{
  "assunto": "Problema no acesso",
  "descricao": "O contato não consegue entrar na conta.",
  "idContatoSolicitante": "00000000-0000-0000-0000-000000000000",
  "idServico": "00000000-0000-0000-0000-000000000000",
  "idCategoria": "00000000-0000-0000-0000-000000000000",
  "idUrgencia": "00000000-0000-0000-0000-000000000000",
  "privacidade": "Publico"
}

assunto é obrigatório e aceita até 500 caracteres. descricao é obrigatória e aceita até 8.000 caracteres. Os quatro IDs precisam apontar para registros da mesma conta da chave de API. privacidade é opcional e assume Publico quando omitida.O ticket começa com o status Novo, quando esse status existe na conta. A primeira interação recebe a descrição enviada no request.

Alterações parciais disparam fluxos de ticket

PATCH /v1/ticket/{idTicket} continua com a mesma assinatura. Agora, quando a alteração é gravada, os fluxos configurados para o gatilho de atualização do ticket também podem ser executados.

A criação dispara os fluxos de ticket como uma criação feita por outro canal. Se a conta não tiver nenhum status de ticket, a API retorna erro de validação.

Tickets excluídos respondem como inexistentes

As rotas públicas de tickets não retornam mais tickets excluídos. Isso vale para consultas por ID, por código e para alterações parciais. A listagem também remove esses registros.

A assinatura das rotas não mudou. Se a integração mantinha um ticket excluído como válido, trate a resposta como recurso inexistente e ajuste o fluxo de sincronização.

Envie imagens ao executar prompts

POST /v1/ia/prompts/executar aceita o campo opcional anexos. Envie até cinco imagens do armazenamento do Novus para análise visual.

{
  "prompt": "Descreva a imagem",
  "anexos": [
    {
      "nome": "produto.png",
      "url": "https://..."
    }
  ]
}

Cada item exige nome e url. A URL precisa apontar para o armazenamento do Novus. O uso de imagens exige o provedor Gemini. O limite é de cinco imagens por solicitação.

Liste as interações e os anexos de um ticket

GET /v1/ticket/{id}/interacoes lista as interações de um ticket com paginação. Cada item da resposta traz id, dataIteracao, modelo, conteudo e anexos.Cada anexo traz nomeArquivo e urlArquivo. Use page e pageSize para percorrer a lista.

Execute prompts pela API pública

POST /v1/ia/prompts/executar executa um prompt usando o provedor de IA configurado na conta.O request aceita prompt, instrucoes, provedor, modelo, temperatura e maximoDeTokensDeSaida. A response retorna resposta, modelo, provedor, tokensDeEntrada, tokensDeSaida, motivoDoTermino e creditosDebitados.Quando a conta usa a chave da plataforma, o consumo debita créditos de IA.

Gerencie versões de plugins hospedados

A API pública ganhou estas rotas para plugins hospedados:

Método	Rota	Observação
`GET`	`/v1/plugins`	Lista os plugins da conta
`GET`	`/v1/plugins/{id}/versoes`	Lista as versões enviadas
`POST`	`/v1/plugins/{id}/versoes`	Envia um pacote sem publicar
`POST`	`/v1/plugins/{id}/versoes/{numero}/publicar`	Publica uma versão
`POST`	`/v1/plugins/{id}/reverter/{numero}`	Reverte para uma versão anterior

A resposta de listagem inclui id, titulo, hospedagem, slug, visibilidade, idVersaoAtiva, numeroDaVersaoAtiva e url. Publicar ou reverter retorna 409 quando a versão pede uma permissão ainda não aprovada.

Falhas no envio de templates trazem orientação

Ao enviar um template pelo WhatsApp Oficial, a API explica quando ele não foi encontrado ou quando a Meta recusou o envio. A resposta inclui o nome do template e, quando disponível, o motivo retornado pela Meta.A validação de TemplateName também ficou explícita em POST /v1/message/SendTemplate/{idCanal}. Quando o campo obrigatório não é enviado, a mensagem é Informe o nome do template em TemplateName..

A assinatura da rota e os campos de sucesso não mudaram. Atualize o tratamento de erros se o integrador exibe mensagens específicas para esse envio.

Resultado de movimentação em massa informa itens bloqueados

POST /v1/pipelines/{idPipeline}/negocios/mover-em-massa agora retorna idsBloqueados. O objeto usa o ID de cada item como chave e a mensagem da regra que impediu a movimentação como valor. A ferramenta MCP mover_negocios_em_massa retorna o mesmo campo.

{
  "itensMovidos": 2,
  "idsNaoEncontrados": [],
  "idsBloqueados": {
    "3f2a0000-0000-0000-0000-000000000000": "A etapa de destino exige um campo preenchido"
  }
}

Itens bloqueados não entram em itensMovidos. A assinatura dos demais campos continua a mesma.

Reabertura de atendimento reinicia o controle de inatividade

Ao reativar um atendimento por POST /v1/atendimento/{idAtendimento}/reativar, o controle de inatividade começa novamente. O marco usado antes da finalização não encerra o atendimento reativado no primeiro ciclo.

A assinatura da rota não mudou. A alteração é de comportamento e vale para atendimentos reativados pela API.

GET /v1/disponibilidade mudou o tipo dos campos inicio e fim de DateTime para DateTimeOffset. Atualize o integrador para ler o deslocamento no valor recebido. Os horários agora chegam com o fuso da regra, e não com o fuso do servidor.

Resposta de disponibilidade traz contexto do horário

Cada item de horarios em GET /v1/disponibilidade agora também retorna os campos diaDaSemana, rotulo e fusoHorario. inicio e fim incluem o deslocamento correspondente ao fuso da regra.

{
  "inicio": "2026-09-07T10:00:00-03:00",
  "fim": "2026-09-07T10:30:00-03:00",
  "diaDaSemana": "segunda-feira",
  "rotulo": "segunda-feira, 07/09 às 10:00",
  "fusoHorario": "America/Sao_Paulo"
}

O cálculo separa cada faixa de horário. O intervalo entre duas faixas não vira vaga. Compromissos, bloqueios e eventos externos não cancelados ocupam o período, considerando os intervalos reservados antes e depois do compromisso. Na modalidade Grupo, o horário permanece na resposta enquanto houver vaga.Ferramenta MCP: consultar_horarios_disponiveis retorna os mesmos campos e aplica as mesmas regras.

Consulta de horários livres considera eventos externos

GET /v1/disponibilidade deixou de oferecer horários ocupados por eventos sincronizados de uma agenda externa. Isso vale mesmo quando o evento não virou um compromisso do Novus CRM.

A assinatura e os parâmetros não mudaram. Eventos externos não cancelados que cruzam o período consultado passam a ocupar o horário na resposta.

Ferramenta MCP: consultar_horarios_disponiveis aplica a mesma regra.

Consulta de horários livres

Nova rota GET /v1/disponibilidade para consultar os horários livres de um ou mais usuários. Ela cruza as regras de disponibilidade com reuniões, compromissos e bloqueios já gravados.

Parâmetro	Obrigatório	Regra
`de`	Sim	Primeiro dia do período, inclusive
`ate`	Sim	Último dia do período, inclusive. O intervalo aceita até 92 dias
`usuarios`	Não	Repita o parâmetro para consultar mais de um usuário. Omitido consulta todos com regra ativa
`duracaoEmMinutos`	Não	Omitido usa a duração padrão de cada regra
`idRegra`	Não	Limita a consulta a uma regra
`limite`	Não	Teto por usuário. O padrão é 100 e o máximo é 500

Cada item da resposta traz idUsuario, nomeDoUsuario, horarios e observacao. Cada horário informa inicio, fim, duracaoEmMinutos, idRegra, descricaoDaRegra, modalidade e vagasRestantes.Bloqueio e compromisso não cancelado ocupam o período. Compromisso cancelado não ocupa. Na modalidade Grupo, vagasRestantes informa quantas marcações ainda cabem no mesmo horário.Ferramenta MCP: consultar_horarios_disponiveis, com os mesmos filtros e regras.

Vínculo de reunião com negócio

POST /v1/reunioes e PUT /v1/reunioes/{id} passaram a sincronizar o vínculo informado em tipoEntidade e idEntidade com a lista de reuniões do negócio.

A assinatura não mudou. Ao trocar ou remover o negócio em uma atualização, o vínculo anterior também é removido.

Gravação do primeiro valor em campo personalizado

Duas rotas deixaram de falhar quando o request preenche um campo personalizado que ainda não tinha valor no registro.

Método	Rota
`PUT`	`/v1/atendimento/{idAtendimento}/atributos-personalizados`
`PUT`	`/v1/pipelines/{idPipeline}/negocios/{idItem}/campos-personalizados`

O contrato não mudou. Os mesmos requests agora criam o primeiro valor sem tentar cadastrar novamente a definição do campo personalizado.

Atualização parcial de cadastros

Quinze recursos ganharam uma rota PATCH. Envie apenas os campos que precisam mudar. Campo omitido mantém o valor atual.

Recurso	Rota
Reunião	`PATCH /v1/reunioes/{id}`
Anotação de negócio	`PATCH /v1/negocios/{idNegocio}/anotacoes/{id}`
Campo personalizado	`PATCH /v1/campos-personalizados/{id}`
Contato	`PATCH /v1/contatodechat/{idContato}`
Departamento	`PATCH /v1/departamentos/{id}`
Etiqueta	`PATCH /v1/etiquetas/{id}`
Lista de contato	`PATCH /v1/listas-de-contato/{id}`
Motivo de venda	`PATCH /v1/motivos-de-venda/{id}`
Origem do negócio	`PATCH /v1/origens-do-negocio/{id}`
Atividade	`PATCH /v1/pipelines/{idPipeline}/items/{idItem}/atividades/{idAtividade}`
Etapa	`PATCH /v1/pipelines/{idPipeline}/etapas/{idEtapa}`
Negócio	`PATCH /v1/pipelines/{idPipeline}/negocios/{idItem}`
Funil	`PATCH /v1/pipelines/{id}`
Produto do negócio	`PATCH /v1/pipelines/{idPipeline}/negocios/{idItem}/produtos/{idVinculo}`
Tipo de atividade	`PATCH /v1/tipos-de-atividade/{id}`

Listas têm substituição completa quando são enviadas. Omitir a lista preserva os vínculos atuais. Enviar [] remove todos os itens.As 16 ferramentas MCP de atualização relacionadas passaram a seguir a mesma regra. Elas alteram somente os campos enviados, em vez de substituir o cadastro inteiro.

Participantes e convidados da reunião

POST /v1/reunioes, PUT /v1/reunioes/{id} e o novo PATCH /v1/reunioes/{id} aceitam dois campos novos. As respostas de reunião também trazem as duas listas.

Campo	O que faz
`idsUsuariosParticipantes`	Define os usuários que veem o compromisso na agenda
`idsLeads`	Define os contatos convidados pelo e-mail do cadastro

{
  "assunto": "Revisão da proposta",
  "dataInicio": "2026-08-31T13:00:00Z",
  "dataFim": "2026-08-31T13:30:00Z",
  "idsUsuariosParticipantes": ["3f2a…"],
  "idsLeads": ["9b71…"]
}

Na criação, informe ao menos um usuário da conta. Quando a reunião está ligada a um negócio e a lista de participantes vem vazia, a API usa o responsável pelo negócio. Nas atualizações, omitir uma lista preserva os valores atuais. A lista de participantes não aceita [].A ferramenta MCP criar_reuniao segue a mesma regra. As ferramentas atualizar_reuniao e obter_reuniao também trabalham com as duas listas.

Mudança de comportamento em buscar_mensagens_conversa. A ferramenta devolvia a conversa inteira numa chamada e agora devolve 50 mensagens por vez, com teto de 200. Integração que contava com o histórico completo de uma vez precisa avançar o skip até o fim.

Paginação e teto de tamanho nas ferramentas MCP

As ferramentas de listagem passaram a apertar page e pageSize na mesma faixa que o REST já exige. page menor que 1 vira 1. pageSize menor que 1 cai no padrão de 20, e acima de 200 é cortado no teto.Duas ferramentas de atendimento não tinham paginação nenhuma e ganharam skip e take.

Ferramenta MCP	Parâmetros novos	Padrão	Teto
`buscar_atendimentos_chat`	`skip`, `take`	`skip` 0, `take` 20	`take` 100
`buscar_mensagens_conversa`	`skip`, `take`	`skip` 0, `take` 50	`take` 200

Para varrer a lista inteira, avance o skip até o total devolvido na resposta.

Erro legível e teto de tempo na chamada de ferramenta

Falha de ferramenta MCP deixou de subir como erro cru de protocolo, do tipo “A task was canceled”. A resposta agora vem com isError e um texto que diz o que houve e o que tentar em seguida.Três situações têm texto próprio.

Chamada acima de 90 segundos é interrompida, e a mensagem pede período menor ou pageSize menor
Resultado acima de 400 mil caracteres é descartado antes de virar JSON, e a mensagem pede take menor ou filtro mais estreito
Falha do banco ou erro nosso devolve um código de rastreio para informar ao suporte

Na falha, a resposta não afirma que nada foi gravado. Ferramenta de escrita pode ter parado no meio, então confira o estado antes de repetir a chamada.

Mudança que quebra integração. A conta cujo plano não inclui o servidor MCP passa a receber 403 em toda requisição ao endereço /mcp. Se a sua integração depende dele, confira o plano da conta antes de seguir.

Servidor MCP exige plano Avançado, Premium ou Revenda

O corpo da resposta traz o motivo: “Seu plano não inclui o servidor MCP. Ele está nos planos Avançado, Premium e Revenda.” Conta em avaliação continua conectando normalmente.A conferência do plano vem antes do interruptor da conta. Conta que tinha o servidor ligado e trocou para um plano sem o recurso recebe o 403 do plano, não a resposta de servidor desativado. Pelo mesmo motivo, tools/list volta vazio nesse caso.

A API REST em v1/ não mudou. A integração por chave de API continua valendo em qualquer plano.

Credencial de sessão de suporte não vale na API pública

O acesso temporário de suporte gera uma credencial assinada com a mesma chave do CRM. Ela é recusada na validação do token da API pública, então a requisição volta 401 mesmo com a credencial dentro do prazo.

A assinatura não mudou. Quem autentica por chave de API não é afetado.

Produtos relacionados e similares em `v1/produto`

POST /v1/produto e PUT /v1/produto/{id} aceitam dois campos novos, os dois com lista de Guid:

Campo	O que faz
`idsProdutosRelacionados`	Vincula produtos indicados junto com este, como acessório e kit
`idsProdutosSimilares`	Vincula produtos que servem de alternativa a este

{
  "nome": "Furadeira de impacto 650W",
  "idsProdutosRelacionados": ["3f2a…", "9b71…"],
  "idsProdutosSimilares": ["c04e…"]
}

Cada campo é substituição completa do vínculo daquele tipo. Omitir o campo (ou mandar null) preserva o que já estava gravado, e mandar [] remove tudo. Id repetido conta uma vez só, e o id do próprio produto é ignorado em vez de virar erro.As respostas de produto trazem os dois vínculos resolvidos, cada item com id e nome:

{
  "id": "8a1f…",
  "nome": "Furadeira de impacto 650W",
  "produtosRelacionados": [{ "id": "3f2a…", "nome": "Kit de brocas 10 peças" }],
  "produtosSimilares": [{ "id": "c04e…", "nome": "Furadeira de impacto 700W" }]
}

PATCH /v1/produto/{id} não aceita esses dois campos. Para mexer nos vínculos, use PUT com o produto inteiro.

Autorização OAuth do servidor MCP

O redirecionamento do fluxo OAuth do servidor MCP apontava para um endereço de desenvolvimento que saiu do ar, e a autorização travava na volta. Agora ele vai para https://app.novuscrm.com.br.

Nada mudou no contrato. Se o seu cliente MCP guarda a URL de autorização em cache ou em arquivo de configuração, refaça a conexão para pegar o endereço novo.

Consulta de CNPJ e de CEP por MCP

Duas ferramentas MCP novas no servidor da API pública. As duas são de leitura, não gravam nada na conta e aceitam o documento com ou sem máscara.

Ferramenta	Parâmetro	O que devolve
`consultar_cnpj`	`cnpj` (14 dígitos)	Dados cadastrais na Receita Federal
`consultar_cep`	`cep` (8 dígitos)	Endereço do CEP

A resposta de consultar_cep traz cep, logradouro, complemento, unidade, bairro, cidade, uf, estado, regiao, codigoIbge, ddd e codigoSiafi.A de consultar_cnpj é maior.

{
  "cnpj": "12345678000195",
  "razaoSocial": "...",
  "nomeFantasia": "...",
  "situacao": "ATIVA",
  "dataDaSituacao": "2010-05-03",
  "dataDaAbertura": "2010-05-03",
  "naturezaJuridica": "...",
  "capitalSocial": "100000.00",
  "optanteSimples": false,
  "optanteSimei": false,
  "atividadePrincipal": { "codigo": "6201501", "descricao": "..." },
  "atividadesSecundarias": [{ "codigo": "...", "descricao": "..." }],
  "endereco": {
    "cep": "01001000",
    "logradouro": "...",
    "numero": "100",
    "complemento": "...",
    "bairro": "...",
    "cidade": "...",
    "uf": "SP"
  },
  "telefones": ["1133334444"],
  "email": "...",
  "inscricoesEstaduais": [{ "numero": "...", "uf": "SP", "ativa": true }],
  "socios": [{ "nome": "...", "qualificacao": "..." }]
}

Quando a consulta falha, a ferramenta devolve { "error": "...", "code": "..." } em vez do objeto.

As duas entraram no catálogo de ferramentas que o agente de IA pode ligar, nos grupos Consulta de CNPJ e Consulta de CEP, ambos de risco baixo.

API pública no ar

O Novus CRM lança hoje, e a API pública lança junto.A partir de hoje, todo endpoint, campo e ferramenta MCP novos entram registrados aqui.

​Atualizações recentes

​Configure o departamento alternativo na ausência de atendentes

​Use o servidor MCP sem afinidade de sessão

​Atualize um atendimento e reinicie a base do tempo de espera

​Resposta de pipeline informa a origem do responsável

​Atualizações parciais de ticket disparam fluxos

​Listagens reduzem textos ricos

​Filtre negócios por criação, fechamento e falta de interação

​Configure os dias que não contam no prazo da atividade

​Crie tickets sem usuário logado

​Crie tickets pela API pública

​Alterações parciais disparam fluxos de ticket

​Tickets excluídos respondem como inexistentes

​Envie imagens ao executar prompts

​Liste as interações e os anexos de um ticket

​Execute prompts pela API pública

​Gerencie versões de plugins hospedados

​Falhas no envio de templates trazem orientação

​Resultado de movimentação em massa informa itens bloqueados

​Reabertura de atendimento reinicia o controle de inatividade

​Resposta de disponibilidade traz contexto do horário

​Consulta de horários livres considera eventos externos

​Consulta de horários livres

​Vínculo de reunião com negócio

​Gravação do primeiro valor em campo personalizado

​Atualização parcial de cadastros

​Participantes e convidados da reunião

​Paginação e teto de tamanho nas ferramentas MCP

​Erro legível e teto de tempo na chamada de ferramenta

​Servidor MCP exige plano Avançado, Premium ou Revenda

​Credencial de sessão de suporte não vale na API pública

​Produtos relacionados e similares em v1/produto

​Autorização OAuth do servidor MCP

​Consulta de CNPJ e de CEP por MCP

​API pública no ar

Atualizações recentes

Configure o departamento alternativo na ausência de atendentes

Use o servidor MCP sem afinidade de sessão

Atualize um atendimento e reinicie a base do tempo de espera

Resposta de pipeline informa a origem do responsável

Atualizações parciais de ticket disparam fluxos

Listagens reduzem textos ricos

Filtre negócios por criação, fechamento e falta de interação

Configure os dias que não contam no prazo da atividade

Crie tickets sem usuário logado

Crie tickets pela API pública

Alterações parciais disparam fluxos de ticket

Tickets excluídos respondem como inexistentes

Envie imagens ao executar prompts

Liste as interações e os anexos de um ticket

Execute prompts pela API pública

Gerencie versões de plugins hospedados

Falhas no envio de templates trazem orientação

Resultado de movimentação em massa informa itens bloqueados

Reabertura de atendimento reinicia o controle de inatividade

Resposta de disponibilidade traz contexto do horário

Consulta de horários livres considera eventos externos

Consulta de horários livres

Vínculo de reunião com negócio

Gravação do primeiro valor em campo personalizado

Atualização parcial de cadastros

Participantes e convidados da reunião

Paginação e teto de tamanho nas ferramentas MCP

Erro legível e teto de tempo na chamada de ferramenta

Servidor MCP exige plano Avançado, Premium ou Revenda

Credencial de sessão de suporte não vale na API pública

Produtos relacionados e similares em `v1/produto`

Autorização OAuth do servidor MCP

Consulta de CNPJ e de CEP por MCP

API pública no ar