> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.callix.dev.br/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.callix.dev.br/_mcp/server. # Callix para Desenvolvedores A API da Callix segue o padrão [JSON:API](https://jsonapi.org/) — todas as requisições e respostas usam o content type `application/vnd.api+json`. Autentique com um Bearer token e comece a integrar em minutos. #### [Autenticação](#autenticação) Gere seu token em Configurações > API e envie no header `Authorization`. #### [API Reference](/api-reference) Todos os endpoints da API v1: campanhas, chamadas, contatos, WhatsApp e mais. #### [SDK](/sdk) Embarque a telefonia da Callix na sua aplicação: softphone no browser, estado do operador e contexto da chamada. #### [Convenções](#convenções) Paginação, ordenação, filtros, includes e formato de datas. #### [Base URL](#base-url) `https://{tenant}.callix.com.br/api/v1` #### [Limite de requisições](#limite-de-requisições) 10 requisições/minuto por rota por padrão; algumas rotas têm limites próprios. ## Autenticação A API usa Bearer token. Gere o token no menu **API** da seção **Configurações** dentro da sua conta e envie no header `Authorization` em toda requisição: ``` Authorization: Bearer SEU_TOKEN ``` Mantenha o token em segredo — ele dá acesso total aos dados da sua conta. ## Base URL A URL base é composta pelo subdomínio exclusivo da sua conta mais o sufixo da versão da API: ``` https://{tenant}.callix.com.br/api/v1 ``` Onde `{tenant}` é o subdomínio da sua conta (ex: `sua-conta` em `sua-conta.callix.com.br`). Após a URL base, adicione o identificador dos dados que deseja consultar e os parâmetros desejados. Por exemplo, para listar todos os usuários: ``` https://sua-conta.callix.com.br/api/v1/users ``` ## Formato das requisições A troca de dados é feita em JSON, com estrutura baseada na especificação [JSON:API](https://jsonapi.org/format/). Em toda requisição que envia um corpo (POST, PATCH), é obrigatório especificar o header `Content-Type` com o valor `application/vnd.api+json`. O corpo segue o envelope JSON:API: os dados ficam em `data`, com `type` e `attributes` (e `relationships`, quando aplicável). Por exemplo: ```json { "data": { "type": "campaign_lists", "attributes": { "name": "Minha lista" } } } ``` ## Convenções Os parâmetros abaixo são universais no padrão JSON:API e valem para as rotas que os suportam. Eles ficam documentados aqui uma única vez; nos endpoints, a documentação apenas aponta para esta seção. ### Formato de data Valores de data e hora seguem o padrão ISO 8601 (`YYYY-MM-DDThh:mm:ss.sss`). As datas retornadas nas respostas estão no fuso UTC+0, indicado pelo `Z` ao final. Exemplo: ``` 2018-06-19T15:47:00.000Z ``` O mesmo formato deve ser usado nas datas passadas como parâmetro em filtros. Intervalos são informados como duas datas separadas por vírgula. ### Filtros Use `filter[campo]` para restringir os resultados de uma listagem, conforme os filtros documentados em cada endpoint. Exemplo de intervalo de datas: ``` ?filter[started_at]=2018-06-01T00:00:00.000Z,2018-06-01T23:59:59.999Z ``` ### Relacionamentos Por padrão, as respostas trazem o mínimo de informações das entidades relacionadas — normalmente apenas o `id` e os links do relacionamento. Por exemplo, ao solicitar uma chamada, vem também o `id` do agente que a realizou: ```json { "data": [ { "id": "124", "type": "outgoing_completed_calls", "attributes": {}, "relationships": { "agent": { "links": { "self": "/api/v1/outgoing_completed_calls/124/relationships/agent", "related": "/api/v1/outgoing_completed_calls/124/agent" }, "data": { "type": "users", "id": "2" } } } } ] } ``` Com o parâmetro `include`, os dados das entidades relacionadas são trazidos em uma seção `included` separada. Para incluir vários relacionamentos, separe-os por vírgula. Adicionando `include=agent` à URL do exemplo acima: ```json { "data": [ { "id": "124", "type": "outgoing_completed_calls", "attributes": {}, "relationships": { "agent": { "links": { "self": "/api/v1/outgoing_completed_calls/124/relationships/agent", "related": "/api/v1/outgoing_completed_calls/124/agent" }, "data": { "type": "users", "id": "2" } } } } ], "included": [ { "id": "2", "type": "users", "attributes": { "name": "operador1" } } ] } ``` Alguns relacionamentos são editáveis pela URL `self` contida no campo `links` do relacionamento, com três verbos: * `POST` — adiciona itens à coleção do relacionamento. * `DELETE` — remove itens da coleção. * `PATCH` — sobrescreve completamente a coleção pela nova lista. Nos três casos o corpo tem a mesma forma. Por exemplo, para editar as campanhas associadas a uma lista de bloqueio: ```json { "data": [ { "type": "campaigns", "id": "1" }, { "type": "campaigns", "id": "2" } ] } ``` ### Seleção de atributos Use `fields` para escolher quais atributos e relacionamentos de um recurso serão retornados (sparse fieldsets). O conjunto disponível está na documentação de cada entidade. Exemplo: ``` ?fields[campaign]=name ``` ### Paginação Controle a paginação pelo parâmetro `page`: * `page[limit]` — quantidade de registros por página. O valor padrão é `2000` e o máximo permitido é `5000`. Recomenda-se usar o valor máximo. * `page[offset]` — ponto de início da lista. Se omitido ou `0`, começa pelo primeiro item. ``` ?page[limit]=2000&page[offset]=10 ``` ### Ordenação Use `sort` com o nome do atributo. O prefixo `-` inverte para ordem decrescente. Consulte a documentação de cada entidade para saber quais atributos são ordenáveis. ``` ?sort=started_at # ascendente ?sort=-started_at # descendente ``` ## Limite de requisições A API tem um limite padrão de **10 requisições por minuto** para cada rota. Algumas rotas têm limites próprios: | Rota | Limite | | -------------------------------------- | ---------- | | `/campaign_missed_calls` | 1 req/min | | `/customer_campaign_missed_calls` | 1 req/min | | `/click_to_call` | 20 req/min | | `/click_to_sms` | 10 req/min | | `/campaigns/{id}/start` | 1 req/min | | `/campaigns/{id}/agent_groups` | 1 req/min | | `/campaign_contacts` | 1 req/min | | `/campaign_contacts_async` | 2 req/min | | `/campaign_contacts_async/{id}/result` | 2 req/min | | `/agent_groups` | 10 req/min | | `/agent_groups/{id}/agents` | 30 req/min | | `/campaign_lists` | 2 req/min | | `/outbound_blacklisted_phones` | 2 req/min | | `/qualifications` | 1 req/min | | `/user_performance_reports` | 2 req/min | | `/user_service_status_change_reports` | 2 req/min | Ao atingir o limite, a API retorna `429 Too Many Requests`. Os headers `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset` informam quando o contador será reiniciado.