Provedor de internet brasileiro tem dois eixos onde o programa de indicações pode quebrar: o cadastro inicial do lead (CRM) e a confirmação do contrato (ERP). O IXC Soft fica no segundo eixo. É lá que o cliente vira cliente de fato. É lá que a comissão deveria ser liberada de forma automática. Mas raramente é.

Esse tutorial mostra como conectar o IXC ao seu sistema de programa de indicações pra que a regra fique simples: contrato ativado no IXC, comissão liberada no programa. Carência respeitada, cancelamento detectado, PIX automático no dia 20. Vou usar o FazUp como referência, mas o esqueleto técnico (usuário API + campo customizado + webhook de saída) serve pra qualquer integração com IXC.

Quem é esse tutorial pra: gestor comercial, financeiro ou de TI em provedor de internet que já usa IXC Soft e quer estruturar (ou auditar) o programa de indicações. Você não precisa ser dev, mas precisa ter acesso de admin ao IXC pra parte da configuração.

Por que integrar (e o que dá errado sem integração)

O cenário comum em provedor sem integração é mais ou menos assim. O cliente é indicado, vira lead num WhatsApp, vendedor cadastra contrato no IXC. Tudo certo até aí. O problema vem depois: a comissão. Pra calcular ela, alguém precisa, todo mês:

  1. Rodar relatório de contratos ativos do mês no IXC
  2. Abrir a planilha de quem indicou cada cliente
  3. Cruzar uma com a outra na mão
  4. Calcular o percentual ou valor fixo de comissão
  5. Verificar se o cliente já passou da carência (não cancelou em 7 dias)
  6. Gerar lista de PIX
  7. Disparar um a um

O que dá errado:

A integração resolve os 4 com um truque simples: o IXC vira a fonte da verdade sobre status do contrato, e o sistema de indicações reage automaticamente a cada mudança.

Pré-requisitos

Passo 1: Criar usuário API no IXC com permissões mínimas

O IXC Soft expõe um webservice REST autenticado por usuário e token. A primeira coisa é criar um usuário dedicado pra integração, com escopo restrito. Não use o usuário de admin geral. Princípio do menor privilégio.

  1. Logue como admin no IXC
  2. Vá em Configurações → Cadastros → Funcionários / Usuários
  3. Crie um usuário chamado algo como api_fazup
  4. Em Permissões → Webservice, marque os 3 endpoints abaixo (somente leitura):
    • cliente
    • cliente_contrato
    • vendedor
  5. Não dê permissão a nenhum outro endpoint, especialmente fn_caixa, fn_titulo, fn_titulo_pago ou módulos financeiros
  6. Salve. O IXC gera o token que será usado nas chamadas API

A URL do webservice tem o formato:

# Cloud
https://SEU-DOMINIO.ixcsoft.com.br/webservice/v1/

# On-premise
https://ixc.SEU-DOMINIO.com.br/webservice/v1/

Autenticação é HTTP Basic, com Authorization: Basic base64(usuario:token).

⚠️ Cuidado com o token: ele dá acesso de leitura ao seu cadastro de clientes. Trate com o mesmo cuidado de uma senha. Não cole em GitHub público, prints ou chats não criptografados. Se vazar, regenere imediatamente no painel do IXC.

Passo 2: Criar campo customizado no contrato

O IXC tem o conceito de "campos extras" por entidade. Vamos criar um campo no contrato pra armazenar quem foi o indicador. Esse é o ponto de cruzamento que liga uma indicação no FazUp a um contrato no IXC.

  1. No IXC, vá em Configurações → Personalização → Campos personalizados
  2. Selecione a entidade cliente_contrato
  3. Crie o campo:
    • Nome: Indicador FazUp
    • Símbolo: id_indicador_fazup
    • Tipo: Texto
    • Tamanho: 32
  4. Salve

Pronto. Agora cada contrato tem um campo onde a FazUp grava o código do indicador no momento da criação. Esse código volta no payload do webhook pra fechar o ciclo.

Passo 3: Configurar webhook de saída

O IXC Soft permite disparar webhooks em mudanças de status de várias entidades. Vamos configurar um webhook pra disparar quando o contrato muda para o status Ativo.

  1. No IXC, vá em Configurações → Integrações → Webhooks
  2. Crie um novo webhook:
    • Nome: FazUp - Contrato ativado
    • Entidade: cliente_contrato
    • Evento: Edição (campo status alterado)
    • Filtro: status = 'A' (Ativo)
    • URL de destino: https://api.fazup.com.br/v1/webhook/ixc/contrato-ativo (a equipe FazUp fornece)
    • Método: POST
    • Header de autenticação: X-Fazup-Token: SEU_TOKEN (gerado pelo FazUp e único por cliente)
  3. Em Payload, configure pra enviar pelo menos:
    • id_contrato
    • id_cliente
    • id_vendedor
    • id_indicador_fazup (o campo customizado criado no passo 2)
    • data_ativacao
    • valor_mensalidade
  4. Salve e ative

Exemplo do payload que vai chegar no FazUp:

POST https://api.fazup.com.br/v1/webhook/ixc/contrato-ativo
Headers:
  X-Fazup-Token: "abc123..."
  Content-Type: application/json

{
  "id_contrato": "123456",
  "id_cliente": "7890",
  "id_vendedor": "42",
  "id_indicador_fazup": "U-1042",
  "data_ativacao": "2026-05-05",
  "valor_mensalidade": "99.90"
}

Passo 4: Conectar o sistema de indicações

No painel admin do FazUp (ou do seu sistema de indicações), você cola:

O FazUp armazena tudo cifrado e usa em três momentos:

Quer pular tudo isso?

A equipe FazUp configura usuário, campo customizado, webhook e teste em 24h. Sem custo adicional.

Falar com a equipe

Passo 5: Testar end-to-end

Antes de liberar pros indicadores reais, simule um fluxo completo:

  1. Crie um indicador fake no FazUp (ex: João Teste, código U-TESTE-01)
  2. Acesse o link de indicação dele
  3. Preencha o formulário com dados de teste (use o telefone do gestor pra ver as notificações)
  4. No FazUp, marque a indicação como "convertida" e force a criação de contrato no IXC (a equipe te orienta pra isso na primeira vez)
  5. No IXC, abra o contrato e mude o status pra Ativo
  6. Em até 30 segundos, valide:

Se o cliente teste cancelar antes dos 7 dias, valide que a comissão é revertida automaticamente e some da fila de pagamento.

Troubleshooting comum

"O webhook não chega no FazUp"

Verifique no IXC: o webhook está ativo? O filtro status = 'A' está correto? O IXC tem log de tentativas em Configurações → Integrações → Webhooks → Histórico. Se o IXC mostra erro 401 nas tentativas, o token de autenticação tá errado. Erro 500 ou timeout? Geralmente é firewall do seu lado bloqueando saída pra api.fazup.com.br.

"Webhook chega mas FazUp não identifica o indicador"

O campo id_indicador_fazup não foi preenchido na criação do contrato. Verifique se o vendedor não cadastrou o contrato manualmente, ignorando o fluxo do FazUp. Solução: deixar a criação do contrato como "automática via integração" e treinar a equipe.

"Comissão liberada antes da carência"

Configuração de carência incorreta no FazUp. Padrão é 7 dias após ativação. Se quiser mais (15, 30 dias), ajuste em Configurações → Regras → Carência por origem.

"Cancelamento não foi detectado"

Se você só configurou webhook de ativação, o IXC não notifica cancelamento. Configure outro webhook em cliente_contrato com filtro status = 'C' apontando para o endpoint /webhook/ixc/contrato-cancelado do FazUp.

FAQ

Preciso ter perfil de administrador no IXC?

Sim, pelo menos pra configuração inicial. É necessário criar um usuário API com permissões específicas e adicionar um campo customizado no contrato. Depois disso, o trabalho do dia a dia é só monitorar.

Funciona com IXC cloud e on-premise?

Sim. A diferença é apenas a URL base do webservice (em cloud é o subdomínio da sua instância .ixcsoft.com.br; em on-premise é o domínio interno do seu servidor).

O webhook do IXC dispara em qual evento exatamente?

Configuramos pra disparar quando o contrato muda de status pra "Ativo". Isso pode acontecer no momento da instalação ou quando o financeiro confirma o primeiro pagamento, dependendo da regra do seu provedor.

Quanto tempo a comissão fica em carência?

7 dias por padrão, contados a partir da ativação. Esse prazo pode ser ajustado pra 15 ou 30 dias se você preferir. Após a carência, a comissão é confirmada e entra na fila de PIX do dia 20.

E se o IXC ficar offline temporariamente? O webhook chega depois?

O FazUp tem um job diário de reconciliação que consulta a API do IXC e cruza contratos ativados nas últimas 48h com o que recebeu por webhook. Se algum disparo falhou, é detectado e processado retroativamente.

Pronto. Com esses 5 passos seu IXC Soft passa a falar com o programa de indicações automaticamente. Cada contrato ativado vira comissão liberada (após carência). Cada cancelamento vira reversão. Cada PIX tem rastro auditável.

Se quiser ver como o produto que conecta tudo isso funciona na prática, dá uma olhada na página de integração IXC Soft do FazUp ou na visão geral do produto.