¶ iClass
A integração com o iClass conecta as Ordens de Serviço do HubSoft à plataforma de gestão de campo
do iClass. Ela tem duas funcionalidades que podem ser habilitadas juntas ou separadamente:
- Envio de Eventos — cada acontecimento de uma O.S. no HubSoft (abertura, alteração,
agendamento, fechamento, cancelamento) é enviado automaticamente para o iClass. - Agendamento pela Plataforma — a agenda usada para marcar a O.S. é a do próprio iClass. A tela
de agendamento deles é aberta dentro do HubSoft e, ao confirmar o horário, a O.S. já é agendada
aqui.
Ambas trabalham no sentido HubSoft → iClass: o HubSoft informa e agenda; o acompanhamento da
execução em campo continua na plataforma do iClass.
¶ ⚠️ Atenção: é obrigatório um de-para no iClass
¶ 🔴 Os códigos do HubSoft precisam estar cadastrados no iClass
A integração não usa códigos próprios do iClass: ela envia os códigos do HubSoft, e o iClass
precisa reconhecê-los. Por isso, antes de usar a integração, é obrigatório montar o de-para
abaixo junto ao suporte do iClass:
O que precisa ser mapeado Código enviado pelo HubSoft Se não estiver mapeado Tipos de O.S. O id (código) do Tipo de O.S. cadastrado no HubSoft A agenda do iClass não abre para aquele tipo de atendimento — a tela deles informa que a área/tipo não foi encontrado Técnicos O id (código) do usuário técnico cadastrado no HubSoft O técnico alocado pelo iClass não é reconhecido aqui, e a O.S. fica com o técnico padrão da integração Cidades / regiões O código IBGE da cidade A agenda do iClass não abre para aquela cidade O cadastro desse de-para é feito pelo iClass, do lado deles. O papel do provedor é informar a
relação de códigos — Tipos de O.S., técnicos e cidades — ao suporte do iClass, e avisá-los
sempre que essa relação mudar: um Tipo de O.S. novo, um técnico novo ou uma cidade nova só
funcionam na agenda depois de mapeados lá.
¶ Onde encontrar os ids para enviar ao iClass
Os códigos não precisam ser solicitados: eles estão disponíveis no próprio sistema.
| Código | Onde consultar |
|---|---|
| Id do Tipo de O.S. | Na tela Configurações > Geral > Tipos de O.S., na coluna ID da listagem |
| Id do técnico | Na tela de Usuários, na coluna ID da listagem |
| Código IBGE da cidade | No cadastro da cidade, no campo de código IBGE |
💡 Os ids também podem ser coletados pela API Oficial do HubSoft, o que costuma ser o caminho
mais prático quando a relação é grande ou quando o próprio iClass vai buscar os códigos —
consultando os Tipos de O.S. e os usuários e usando o campo de id de cada registro.
Em caso de dúvida, o suporte HubSoft também pode fornecer a relação pronta para envio.
¶ Pré-requisitos
Antes de configurar, é necessário:
- Contratar a integração com o iClass e solicitar ao suporte deles os dados de acesso
(relacionados no próximo tópico). - Ter o de-para de Tipos de O.S., técnicos e cidades cadastrado no iClass, conforme o tópico
acima. Este é o ponto que mais gera dúvida depois: sem o mapeamento, a configuração fica correta e
a agenda ainda assim não abre. - Cidades com código IBGE preenchido no cadastro do HubSoft. Sem o IBGE, a agenda do iClass não
abre para aquela cidade. - Um usuário técnico ativo no HubSoft, para ser o responsável padrão das O.S. agendadas pela
plataforma. - Permissões de acesso para o usuário que vai configurar (Integrações) e para quem vai agendar
(Agendar O.S.).
¶ Dados a solicitar ao iClass
| Dado | Para que serve | Quando é necessário |
|---|---|---|
| URL | Endereço que recebe os eventos das O.S. | Envio de Eventos |
| Token | Credencial de autenticação do envio | Envio de Eventos |
| URL de agendamento | Endereço da tela de agenda do iClass | Agendamento pela Plataforma |
| Token de agendamento | Credencial da tela de agenda | Agendamento pela Plataforma |
⚠️ O token de agendamento é diferente do token de envio — são acessos distintos, gerados de
formas diferentes pelo iClass. Um não substitui o outro; solicite os dois quando for usar as duas
funcionalidades.
ℹ️ O token de agendamento tem validade. Quando a tela de agenda parar de abrir ou passar a
apresentar erro de acesso, o primeiro ponto a verificar é se o token expirou — nesse caso, solicite
um novo ao iClass e atualize o parâmetro.
¶ Configurando a integração
Acesse Configurações > Integrações > ERP e clique em Adicionar.
1. Preencha os dados da integração:
| Campo | Como preencher |
|---|---|
| Nome | Um nome para identificar a integração (ex.: iClass) |
| Gateway | Selecione iClass |
| Envio de Eventos | Habilite para enviar as O.S. para o iClass |
| Agendamento pela Plataforma | Habilite para usar a agenda do iClass ao marcar as O.S. |
2. Informe os parâmetros, conforme os dados recebidos do iClass:
| Parâmetro | Valor |
|---|---|
url |
Endereço que recebe os eventos |
token |
Credencial de autenticação do envio. Pode ser colada exatamente como o iClass enviou |
agendamento.url |
Endereço da tela de agenda |
agendamento.token |
Credencial da tela de agenda |
agendamento.id_tecnico |
Código do usuário técnico que será o responsável padrão das O.S. agendadas pela plataforma (Caso não venha no retorno do agendamento) |
Os três parâmetros iniciados por agendamento. só são exigidos quando a opção Agendamento pela
Plataforma está habilitada. Se ela ficar desabilitada, basta informar url e token.
3. Selecione os eventos que serão enviados ao iClass, no grupo Ordem de Serviço:
| Evento | Quando é enviado |
|---|---|
| Criar | Ao abrir uma nova O.S. |
| Atualizar | Ao alterar os dados de uma O.S. |
| Agendar | Ao agendar a O.S. (por qualquer meio) |
| Desagendar | Ao remover o agendamento da O.S. |
| Fechar | Ao fechar/finalizar a O.S. |
| Remover | Ao cancelar/remover a O.S. |
Marque apenas os que o iClass deve receber — o mais comum é habilitar todos, para que a plataforma
acompanhe a O.S. do início ao fim.
4. Salve a integração.
✅ Ao salvar, o HubSoft confere se todos os parâmetros obrigatórios foram informados e se o código
informado emagendamento.id_tecnicocorresponde a um usuário que é técnico e está ativo.
Se algo estiver pendente, a mensagem indica exatamente o que corrigir.
¶ O que é enviado nos eventos
O envio acontece automaticamente e em segundo plano, logo após o acontecimento na O.S. — quem
está atendendo não precisa fazer nada, e uma eventual indisponibilidade do iClass não interrompe a
operação no HubSoft (o sistema tenta novamente).
Cada evento leva os dados da O.S. no formato definido pelo iClass:
- Ordem de Serviço — número, atendimento de origem, tipo, status, data de abertura, data e hora
do agendamento, técnico responsável e a observação (na abertura, a descrição de abertura; no
fechamento, a descrição de fechamento). - Cliente — código, nome/razão social, telefones, e-mail, contato e o plano contratado.
- Endereço do atendimento — logradouro, número, complemento, bairro, CEP, cidade, UF e
coordenadas. - Dados técnicos do serviço — login, senha, MAC e ponto de acesso (POP).
ℹ️ Neste gateway o conteúdo enviado não é editável: o formato é definido pelo iClass, para que a
plataforma reconheça as informações. Se a necessidade for enviar as O.S. para um sistema próprio, em
formato personalizado, utilize o gateway Outros (Webhook).
¶ Agendando uma O.S. pela agenda do iClass
Com a opção Agendamento pela Plataforma habilitada, a agenda do iClass passa a estar disponível
em dois momentos:
- Na abertura da O.S. — depois de informar a cidade e o Tipo de O.S., a agenda pode ser
aberta para já marcar o horário. - Em uma O.S. já existente — pela ação de agendamento na tela da O.S.
Como funciona:
- A tela de agenda do iClass é aberta dentro do HubSoft, já filtrada pela cidade e pelo Tipo
de O.S. informados. - A disponibilidade exibida é a do iClass — datas e períodos livres para aquela região e tipo de
atendimento. - Ao confirmar o horário, a O.S. é agendada no HubSoft com a data e o período escolhidos.
- O técnico responsável é o que o iClass alocou para aquele horário. Quando o iClass não informa
a equipe, a O.S. fica com o técnico configurado emagendamento.id_tecnico. - O agendamento é registrado no histórico da O.S., com a identificação da integração, o horário e
o período informado pelo iClass.
ℹ️ O agendamento pela plataforma pode ficar habilitado em apenas uma integração de ERP por vez.
¶ Perguntas/Problemas Frequentes
Abaixo serão listadas algumas perguntas/problemas frequentes relacionados com a integração iClass. Caso alguma dessas situações aconteça e você tenha dificuldades para resolver, não hesite em chamar nosso suporte, pois estamos aqui para lhe ajudar.
¶ A agenda do iClass não abre. O que verificar?
- A cidade do atendimento está com o código IBGE preenchido no cadastro.
- A cidade e o Tipo de O.S. foram informados antes de abrir a agenda.
- O token de agendamento não expirou.
- O de-para está cadastrado no iClass para a região (IBGE) e para o id do Tipo de O.S. em
questão. Quando algum dos dois não está mapeado lá, a tela deles informa que a área de atendimento
não foi encontrada — e essa é a causa mais comum, principalmente depois de criar um Tipo de O.S.
novo ou passar a atender uma cidade nova.
¶ A agenda abre, mas não aparece nenhum horário disponível.
A disponibilidade é gerada pelo iClass, a partir das equipes e da agenda cadastradas lá. Não havendo
horário para a região e o tipo de atendimento, o caminho é verificar a configuração de agenda com o
suporte do iClass.
¶ A O.S. foi agendada com um técnico diferente do que eu esperava.
O responsável é o técnico que a agenda do iClass alocou para o horário confirmado — ele prevalece
sobre o que estava na O.S., porque o horário foi reservado na agenda dele. Quando o iClass não informa
a equipe, vale o técnico configurado em agendamento.id_tecnico.
Se todas as O.S. estão caindo no técnico padrão, o provável é que os técnicos não estejam
mapeados no iClass — o código que eles devolvem precisa ser o id do usuário técnico do HubSoft.
¶ Como sei se um evento chegou ao iClass?
Todo envio fica registrado no HubSoft, com o retorno da plataforma. Se houver dúvida sobre um envio
específico, acione o suporte HubSoft informando o número da O.S. e o horário aproximado.
¶ A ação Testar não funciona para o iClass.
O teste de comunicação ainda não está disponível para este gateway. A validação é feita abrindo a
agenda (no caso do agendamento) ou conferindo os eventos de uma O.S. de teste com o suporte.