Callix para Desenvolvedores

A API da Callix segue o padrão JSON:API — 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

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. 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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.