> ## Documentation Index
> Fetch the complete documentation index at: https://help.ciarem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Cada mudança no contrato da API pública, aditiva ou corretiva, em um só lugar.

Cada mudança no contrato da API pública aparece aqui — novos endpoints e campos no dia em que saem, e a rara correção no lugar antes de ter uso real. Inscreva sua integração na tolerância, e esta página na consciência.

<Update label="2026-09-10" description="Acesso no teste gratuito, limites por segundo e 403 que dizem o que fazer">
  * **A API está aberta durante o teste gratuito.** Uma organização em teste recebe todos os endpoints, com um orçamento menor, para construir e testar uma integração antes de pagar.
  * **Os limites de uso agora são por segundo**: **20 solicitações/segundo** no Scale, **5 solicitações/segundo** durante o teste, compartilhadas entre as chaves da organização. Os cabeçalhos `X-RateLimit-*` não mudam; `Retry-After` em um `429` agora é sempre `1`.
  * **`GET /v1/me`** ganha `trial` (booleano) — `true` enquanto a organização está no teste gratuito. `plan` agora informa o código real do plano em vez de sempre `"scale"`.
  * **`403` mais claros.** `scale_plan_required` agora significa apenas "um plano ativo abaixo do Scale — faça upgrade". Dois novos detalhes cobrem o resto: `trial_expired` (o teste terminou sem método de pagamento) e `subscription_required` (cancelada, ou suspensa por falta de pagamento). Veja [Autenticação](/api-reference/authentication).
</Update>

<Update label="2026-08-28" description="Modelos do WhatsApp, envios e campanhas">
  A API já pode enviar.

  * **Modelos do WhatsApp** — listar, ler, criar e excluir (`/v1/templates`). Criar um modelo também o envia à Meta para aprovação na mesma chamada, então ele volta como `PENDING`; consulte-o até a Meta mudá-lo para `APPROVED` ou `REJECTED`.
  * **`GET /v1/templates/{id}/send-requirements`** — o que um modelo precisa preenchido antes de poder ser enviado: os tokens de variáveis, quais deles se resolvem sozinhos a partir do contato, slots de catálogo, botões de URL dinâmicos, superfícies de mídia, e o motivo quando um modelo nunca pode ser enviado. Leia isso antes do primeiro envio em vez de descobrir por meio de 422s.
  * **`POST /v1/templates/{id}/send`** — até 100 destinatários em uma chamada, cada um identificado por `contact_id` ou `phone` e carregando **suas próprias** `variables`, `url_suffixes`, `coupon_code`, `lto_expiration` e mídia. `recipients` aceita um único objeto ou um array — enviar para uma pessoa não precisa de embrulho. Cabeçalhos de mídia aceitam uma URL pública (`header_media_url` / `card_media_urls`), baixada no servidor. Retorna **202** e a campanha que criou.
    * Um `phone` que não corresponde a nenhum contato **cria um**, então um envio pode fazer seu CRM crescer.
    * Envie `Idempotency-Key` e repetir é seguro: a mesma chave devolve a campanha original por 24 horas em vez de enviar de novo.
    * A requisição é recusada **inteira** — nada enfileirado, nada cobrado — se faltar uma variável, se uma chave não for usada pelo modelo, se uma URL de mídia não puder ser baixada, ou se o lote exceder o que resta do limite de mensagens de 24 horas do WhatsApp.
  * **Campanhas** — `GET /v1/broadcasts` e `GET /v1/broadcasts/{id}` para o progresso (`sent` / `failed` / `pending` sempre somam `requested`), `GET /v1/broadcasts/{id}/recipients` para o resultado de cada destinatário, e `POST /v1/broadcasts/{id}/cancel` para abandonar o restante não enviado. Mensagens já aceitas pelo WhatsApp não podem ser recuperadas.
  * **`GET /v1/channels/whatsapp/phones`** — os números conectados de onde um envio pode sair, para que `channel_id` seja descobrível. Opcional quando sua conta do WhatsApp tem exatamente um número; obrigatório quando tem mais.
</Update>

<Update label="2026-08-26" description="Lançamento da v1">
  A primeira superfície pública da API da Ciarem:

  * **Contatos** — CRUD completo (`/v1/contacts`).
  * **Metadados de CRM** — propriedades e etapas do funil, CRUD completo (`/v1/properties`, `/v1/funnel-stages`).
  * **Conversas** — histórico somente leitura (`/v1/conversations`), cada mensagem com um `sender` de `contact`, `agent`, `ai` ou `system`.
  * **`/v1/me`** — identidade da organização, plano, fuso horário e idioma.
  * Chaves de API `oak_` vinculadas à organização, 60 solicitações/minuto por organização.
</Update>