​
Limite de requisições

A API limita a quantidade de requisições em processamento ao mesmo tempo, e não um total por minuto. Enquanto a sua integração fizer chamadas em ritmo normal, mesmo que muitas, ela não encosta no limite. Quando o limite é atingido, a requisição entra em uma fila e é atendida em ordem de chegada. Se a fila também estiver cheia, a resposta é 429 Too Many Requests. Como reagir a um 429:
  • Espere antes de repetir, com espera exponencial e um pouco de variação aleatória: 1s, 2s, 4s, 8s. Repetir imediatamente em laço só aumenta a fila.
  • Reduza o paralelismo. Um 429 quase sempre vem de código que dispara dezenas de chamadas ao mesmo tempo. Poucas requisições em série terminam antes do que muitas em paralelo se atropelando.
Precisa carregar um volume grande, como um catálogo inteiro? Use pageSize=200, o máximo, e percorra as páginas em série. Menos requisições grandes rende mais do que muitas pequenas.

​
Limites de valores

O limite de tamanho de cada campo está no schema da página do endpoint. Estourar qualquer um deles resulta em 422, com o campo apontado.

​
Operações que não terminam na resposta

Alguns endpoints registram a intenção e devolvem 200 antes do trabalho acontecer. Um 200 neles significa “aceito”, e não “concluído”: Para saber o desfecho, consulte o registro mais tarde. As mensagens de um atendimento trazem o campo Status, cujos valores estão aqui, e a venda traz o Status do pagamento.

​
Não existem webhooks

A API pública não envia notificações para o seu sistema. Não há endpoint para cadastrar URL de retorno, nem eventos de saída. Para reagir a algo que acontece no Novus CRM você tem duas opções. A primeira é consultar periodicamente, filtrando por um intervalo de datas. Endpoints como GET /v1/atendimento aceitam criacaoInicio e criacaoFim, então guarde o horário da última consulta e busque só o que veio depois. A segunda é usar as automações da plataforma. Um fluxo consegue chamar um endereço externo quando um evento ocorre, o que costuma ser melhor do que consultar em laço. Se você optar por consultar, escolha um intervalo compatível com a necessidade real. Um minuto entre consultas atende quase todo caso de uso. Um segundo não traz benefício e gasta cota dos dois lados.

​
Não chame a API pelo navegador

A API responde a requisições de qualquer origem, porque o CORS é permissivo. Isso torna tecnicamente possível chamá-la de JavaScript no navegador. Não faça isso. A chave de API dá acesso total à conta, e qualquer visitante consegue lê-la no código da página ou na aba de rede. Chame a API sempre de um servidor seu, que guarda a chave e expõe ao navegador apenas o que aquele usuário pode ver.

​
Recomendações para integrações duradouras

O domínio da API vai mudar de api-publica.cpluschat.com.br para api-publica.novuscrm.com.br. Se o endereço estiver em uma variável de ambiente, a migração é uma linha. Se estiver espalhado pelo código, é uma caçada.
Campos novos entram na v1 sem aviso de quebra. Desserializador configurado para falhar diante de propriedade desconhecida quebra na primeira melhoria da API.
Nome de etiqueta, de departamento e de etapa muda, e o Id não. Descubra o ID uma vez, guarde-o na sua configuração e não resolva nome a cada chamada.
O corpo do 500 traz um traceId. Sem ele, investigar um erro intermitente depende de adivinhação, e é o primeiro dado que o suporte pede.
PUT grava o objeto inteiro, então campo omitido é apagado. Leia o registro, altere o que precisa e devolva tudo. Onde existir PATCH, em produtos e tickets, prefira ele para alterar campos isolados.
O Changelog da API registra cada endpoint, campo e mudança de comportamento. É o único lugar onde as mudanças de contrato são anunciadas.