Limites e boas práticas
Limites de requisição, tamanho de página, comportamento assíncrono e recomendações para integrações estáveis.
Limites de requisição, tamanho de página, comportamento assíncrono e recomendações para integrações estáveis.
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:
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.
| Limite | Valor |
|---|---|
pageSize máximo | 200 registros |
pageSize padrão | 20 registros |
Texto de mensagem (SendText) | 4.096 caracteres |
| Telefone do contato | 13 caracteres |
| Nome do contato | 200 caracteres |
| Observação do contato | 4.000 caracteres |
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.
Alguns endpoints registram a intenção e devolvem 200 antes do trabalho acontecer.
Um 200 neles significa "aceito", e não "concluído":
| Endpoint | O que acontece depois |
|---|---|
POST /v1/message/Send* | A mensagem entra na fila do canal, e a entrega ao cliente vem depois |
POST /v1/atendimento/{id}/mensagens/{idMensagem}/reenviar | A mensagem volta para Pendente e um processo em segundo plano reenvia |
POST /v1/atendimento/{id}/enviar-transcricao | O e-mail com a transcrição é montado e enviado fora da requisição |
POST /v1/solicitacoes-de-pagamento | A transação nasce Pendente, e o gateway confirma depois |
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.
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 SunchatPlus 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.
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.