API do IXC Provedor na prática: autenticação, Postman e exemplos reais

Como a API do IXC funciona

A API do IXC segue um padrão diferente do REST mais comum. Vale entender estes pontos antes da primeira chamada:

• O endereço é o do seu IXC seguido de /webservice/v1/ e o nome da tabela, por exemplo /webservice/v1/cliente.
• A autenticação é Basic Auth com o token de um usuário do IXC. O token tem o formato número:hash; o número vai como usuário e o hash como senha.
• Consultas também são POST. O que diz ao IXC que é uma listagem é o header ixcsoft: listar.
• Filtros vão no corpo, no campo grid_param: uma lista em JSON, enviada como texto, com tabela.campo (TB), operador (OP) e valor (P).
• A paginação usa page e rp (registros por página), e a ordenação, sortname e sortorder.

Primeira consulta no Postman

1. Crie um usuário só para a APINo IXC, use um usuário dedicado à integração, com permissão apenas nas tabelas de que você precisa. Para começar, só leitura.
2. Monte a requisiçãoMétodo POST para https://seu-ixc/webservice/v1/cliente.
3. Configure a autenticaçãoNa aba Authorization, escolha Basic Auth. Em Username, a parte do token antes dos dois-pontos; em Password, a parte depois.
4. Adicione os headersContent-Type: application/json e ixcsoft: listar.
5. Escreva o corpoEm Body → raw → JSON, use o exemplo abaixo, trocando o CPF por um cadastro de teste.
6. Envie e confiraA resposta traz total e a lista de registros. Confira se o cliente devolvido é mesmo o do filtro (veja os cuidados mais abaixo).

Exemplo: buscar cliente pelo CPF

{
  "grid_param": "[{\"TB\":\"cliente.cnpj_cpf\",\"OP\":\"=\",\"P\":\"123.456.789-00\"}]",
  "page": "1",
  "rp": "20",
  "sortname": "cliente.id",
  "sortorder": "desc"
}

Exemplo: faturas em aberto de um cliente

Os títulos ficam na tabela fn_areceber. Status A é em aberto. Ordenar pelo vencimento ajuda a mostrar primeiro o que venceu.

{
  "grid_param": "[{\"TB\":\"fn_areceber.id_cliente\",\"OP\":\"=\",\"P\":\"894\"},{\"TB\":\"fn_areceber.status\",\"OP\":\"=\",\"P\":\"A\"}]",
  "page": "1",
  "rp": "100",
  "sortname": "fn_areceber.data_vencimento",
  "sortorder": "asc"
}

Tabelas mais usadas no atendimento

cliente

Cadastro: nome, CPF/CNPJ (campo cnpj_cpf), telefones, endereço e se o cadastro está ativo.

radusuarios

Logins de conexão. O campo online (S/N) e a data da última conexão dizem se o cliente está navegando, base para detectar massiva.

fn_areceber

Títulos a receber: valor, vencimento e status. É daqui que sai a resposta para "tenho conta em aberto?".

get_boleto

Devolve o boleto de um título. Em algumas instalações a resposta não é JSON, e sim o PDF em base64.

Cuidados que a documentação não conta

Estes pontos vieram de integrações em produção. Vários deles, se ignorados, entregam o dado de um cliente para outro.

Revalide todo resultado

Em algumas instalações, um filtro de igualdade se comporta como "contém": buscar o id 894 também traz 1894 e 2894. Confira sempre se o registro devolvido é o pedido antes de usar.

CPF com e sem máscara

O mesmo CPF pode estar gravado com pontos e traço em um cadastro e só com números em outro. Busque nos dois formatos e compare só os dígitos.

Erro com HTTP 200

O IXC pode responder 200 com {"type": "error"} no corpo. Não confie só no status HTTP.

Formato da resposta varia

As linhas podem vir em registros ou em rows, e o total vem como texto. Normalize antes de usar.

Falha não é "não encontrado"

Se o IXC não respondeu, não diga ao cliente que ele não tem cadastro. Trate a falha como falha e passe para um atendente.

Paginação com trava

Ao percorrer tabelas grandes, pare quando a página vier vazia ou menor que o rp, e tenha um limite máximo de páginas.

E o webhook do IXC?

Quem busca "ixc webhook" normalmente quer ser avisado quando algo muda, como um pagamento ou uma queda. O que existe de gatilho varia com a versão e a configuração do IXC, então vale conferir na sua instalação. Para o atendimento, o caminho mais previsível costuma ser consultar a API na hora em que o cliente chama e sincronizar de tempos em tempos o que precisa de visão geral, como o status de conexão usado para detectar massivas.

Perguntas frequentes