Cross Segmentos - TOTVS CRM Automação e Força de Vendas (SFA) - WEB - Integração - Guia de utilização e integração com API Builder

Tempo aproximado para leitura: 00:09:00 min

Dúvida
Como conectar, autenticar, consumir e validar requisições nas rotas de integração do API Builder no TOTVS CRM SFA?

Ambiente
Cross Segmentos - TOTVS CRM Automação e Força de Vendas (SFA) - WEB - Integração - Todas as versões

Solução

O API Builder é a ferramenta passiva de integração do TOTVS CRM SFA. Ele disponibiliza endpoints HTTP/REST para que sistemas terceiros (ERPs, e-commerces, sistemas legados ou regras customizadas) enviem ou consultem dados cadastrais e operacionais (como clientes, pedidos, títulos, preços e produtos).

Abaixo está o guia com os passos essenciais para iniciar o consumo e realizar testes no seu ambiente:

1. Onde consultar a Documentação Oficial das Rotas

A estrutura das rotas, parâmetros, métodos (GET, POST, PUT) e exemplos de JSON estão catalogados na documentação interativa:

• Documentação Oficial: APIs Padrão - TOTVS CRM SFA

Importante! 
A documentação técnica apresenta exemplos com hosts genéricos. Na prática, a sua integração deve disparar as requisições para o Host do seu próprio ambiente.

2. Como localizar o Host do seu API Builder

• Ambientes T-Cloud:
  Acesse o portal T-Cloud e navegue até: Meu ambiente > Informações de ambiente > Link do apibuilder.
   

• Via Consulta de Banco de Dados (SFA):
  Caso possua acesso ao banco de dados do SFA, execute a instrução abaixo: 

  SELECT HOST FROM APIBUILDER.ENDPOINTLOG LIMIT 1;

   

• Ambientes On-Premise / Servidor Próprio:
  A URL responde no IP/domínio do servidor da aplicação na porta 8095 (ex.: http://<IP_DO_SERVIDOR>:8095).

3. Estrutura Padrão das URLs das Rotas

Todas as rotas do API Builder utilizam o prefixo obrigatório /wspr/ seguido da entidade desejada:

https://<host-do-seu-apibuilder>/wspr/<nome_da_entidade>

Exemplos:

• Clientes: https://<host-do-seu-apibuilder>/wspr/cliente

• Preços: https://<host-do-seu-apibuilder>/wspr/tabelaprecoproduto

• Pedidos: https://<host-do-seu-apibuilder>/wspr/pedido

4. Autenticação e Credenciais (Provider)

As requisições utilizam autenticação Basic Auth (Usuário e Senha):

• Os dados de acesso são configurados diretamente no Provider do API Builder.
   

• Caso precise alterar ou consultar a senha configurada para uma rota, consulte o artigo:
  🔗 Alterar a senha do usuário do Provider API Builder
  

Nos cabeçalhos (Headers) da requisição, envie:

• Content-Type: application/json

• Authorization: Basic <CREDENCIAIS_BASE64>

5. Regras de Firewall e Teste de Conectividade

Por motivos de segurança em nuvem (T-Cloud / SaaS), a porta 8095 não é aberta publicamente:

1. Regra de Whitelist: Envie os IPs públicos fixos de saída dos seus servidores integradores ao Suporte para liberação no Firewall da TOTVS.
    

2. Validação de Porta: Execute no PowerShell da máquina de integração: powershellTest-NetConnection -ComputerName <IP_OU_HOST_DO_SERVIDOR> -Port 8095 Retorno esperado: TcpTestSucceeded : True.
    

3. Validação Web: Acesse pelo navegador http://<HOST_DO_APIBUILDER>:8095/#/login. A tela de login do API Builder deve carregar.

6. Como consultar o Histórico de Requisições e Logs

Todas as chamadas recebidas pelo API Builder ficam gravadas na tabela APIBUILDER.ENDPOINTLOG:

• requestmethod: Método utilizado (POST, PUT, GET).

• pathinfo: Rota manipulada (ex.: //wspr/cliente).

• requestdate: Data e hora da requisição.

• requestbody: Payload JSON recebido.

• requestresult: Resposta do processamento ou código de erro.
   

Para consultar requisições em ambiente T-Cloud pelo módulo PAAS > Banco de Dados, consulte:
🔗 Consultar requisições APIBuilder em ambiente TCloud

Pontos Importantes & Erros Comuns:

• Erro internalid does not exists no PUT:
  Ocorre ao enviar um PUT tentando atualizar um registro com internalid inexistente no SFA. Para novos registros, deve-se utilizar o método POST.
  🔗 Saiba mais: Erro na importação com APIBUILDER
  

• Erro SQLException: No suitable driver:
  Indica falha nas conexões do banco configuradas no painel do API Builder.
  🔗 Saiba mais: Erro Requisição APIBUILDER
  

• Disponibilidade do Serviço:
  O suporte padrão não realiza a instalação inicial nem manutenção de contêineres/serviços no servidor. Se a porta não responder mesmo com o IP liberado no Firewall, abra um chamado para o time de Infraestrutura / Cloud TOTVS solicitando a inicialização do serviço API Builder.

Artigos Relacionados:

• Consultar o host utilizado pelo API Builder

• Realizar uma requisição GET em integração via API Builder

• Alterar a senha do usuário do Provider API Builder

• Consultar requisições APIBuilder de preço produto em ambiente TCloud

• Erro Requisição APIBUILDER

• Erro na importação com APIBUILDER