Integração externa (Como Funciona)

1. Introdução

Quando um chamado (ocorrência) é atendido no Sistema Multidados, é feita a mudança do Status atual do chamado para refletir a ação executada. Durante a mudança de Status, podemos executar uma série de ações como por exemplo: Envio de email, sms ou whatsapp, a Integração Externa entre outras.
A Integração Externa é um recurso do CRM que permite o envio automático de informações sempre que uma Ocorrência é movimentada para um determinado Status. Esse envio é feito por meio de uma requisição HTTP POST, contendo um JSON com os dados da Ocorrência, do Cliente e do Contrato/Projeto, além de eventuais campos adicionais configurados.

Quando a Integração Externa é acionada?

A integração é disparada automaticamente sempre que uma Ocorrência atinge um Status que tenha a Integração Externa configurada. Esse mecanismo permite que sistemas externos recebam e processem essas informações em tempo real.

Benefícios e Casos de Uso

A Integração Externa pode ser utilizada para diversos fins, como:

• Sincronização de dados entre o CRM e outros sistemas internos da empresa.
• Disparo de notificações para sistemas de monitoramento ou suporte.
• Automação de processos baseados na movimentação de Ocorrências.

Esse recurso possibilita uma maior eficiência operacional, garantindo que informações críticas sejam compartilhadas de forma automática e padronizada.

---

2. Pré-requisitos

Para utilizar a Integração Externa, é necessário atender aos seguintes pré-requisitos:

2.1 Solicitação de Liberação

Antes de configurar a Integração Externa, o plugin de integração deve ser liberado no sistema. Para isso, é necessário entrar em contato com o Suporte Multidados e solicitar a ativação do recurso.

2.2 Permissão de Acesso

A configuração da Integração Externa deve ser realizada por usuários com conhecimento técnico adequado, pois o envio dos dados pode incluir informações sensíveis dos clientes.

Uma vez liberado pelo Suporte, o recurso ficará disponível na aba Integração Externa dentro do cadastro de Status no CRM.

---

3. Configuração

A configuração da Integração Externa é realizada dentro do cadastro de Status no CRM. Apenas usuários com experiência técnica devem realizar essa configuração, pois ela envolve o envio de dados sensíveis para sistemas externos.

3.1 Acessando a Configuração

Para configurar a integração:

1. Acesse o Menu CRM > Cadastros > Status.
2. Selecione um Status e clique em Editar.
3. Vá até a aba Integração Externa.

3.2 Configurando a Integração

Dentro da aba Integração Externa, os seguintes campos estarão disponíveis:

• Ativar integração externa neste Status?(Checkbox)
  • Habilita ou desabilita a integração para o Status selecionado.
• Método de Ativação(Seleção de método de disparo)
  • Define como os dados serão enviados. Algumas opções incluem:
    • Abrir popup com a URL e enviar os dados solicitados.
    • Abrir popup com a URL retornada após enviar os dados.
    • Executar no fundo ao salvar uma movimentação.
    • Plugins comerciais: Integrações específicas, como Serasa, RD Station e Mobuss.
• Método de Envio de Dados(Seleção de método HTTP)
  • Define se os dados serão enviados via GET ou POST.
• URL da Integração Externa(Campo de texto)
  • Endpoint para o qual os dados serão enviados.
• Parâmetros da Integração(Lista de parâmetros configuráveis)
  • Permite adicionar N parâmetros para envio.
  • Cada parâmetro possui:
    • Nome do parâmetro (definido pelo usuário).
    • Valor do parâmetro (selecionado a partir de uma lista de campos disponíveis no CRM).
  • Os valores podem ser obtidos a partir de:
    • Dados da Ocorrência.
    • Dados do Cliente.
    • Dados do Contrato/Projeto.
    • Campos adicionais.
    • Dados do usuário logado no momento da movimentação.

Após configurar os parâmetros e salvar as alterações, a integração será ativada e disparará sempre que uma Ocorrência for movida para o Status configurado.

---

4. Estrutura dos Dados Enviados

A Integração Externa do CRM envia os dados no formato JSON, com um array de nível único. O conteúdo enviado depende da configuração dos Parâmetros da Integração, permitindo a inclusão de informações da Ocorrência, do Cliente, do Contrato/Projeto e de Campos Adicionais.

4.1 Formato do Payload

Os dados são enviados via POST em um JSON simples, sem estrutura aninhada. Cada campo configurado na integração será enviado como uma chave dentro do objeto JSON.

4.2 Dados Disponíveis para Envio

Os seguintes grupos de informações podem ser utilizados para compor o payload da integração:

• Dados da Ocorrência
  • Status da ocorrência
  • Divisão
  • Tipo de solicitação
  • SLA e prazos
  • Campos adicionais configurados na Ocorrência
• Dados do Cliente
  • Nome
  • Documento (CPF/CNPJ)
  • Telefones
  • Endereços
  • Campos adicionais do Cliente
• Dados do Contrato/Projeto
  • Número ou código do contrato/projeto
  • Empreendimento associado
  • Bloco e unidade vinculados
  • Campos adicionais do Contrato/Projeto
• Dados do Usuário Logado
  • Nome
  • Identificação de usuário

4.3 Exemplo de Payload

(Exemplo fictício — a estrutura real dependerá da configuração feita no CRM)

{
  "status": "Concluído",
  "divisao": "Técnica",
  "solicitacao": "Reparo Elétrico",
  "sla": "24 horas",
  "cliente_nome": "João da Silva",
  "cliente_documento": "123.456.789-00",
  "telefone": "(11) 99999-9999",
  "endereco": "Rua Exemplo, 123 - SP",
  "contrato_codigo": "CTR-2024-001",
  "empreendimento": "Residencial Alfa",
  "bloco": "B",
  "unidade": "101",
  "usuario_logado": "Administrador"
}

4.4 Observações Importantes

• O payload não possui estrutura aninhada (todos os campos ficam no primeiro nível do JSON).
• Apenas os campos configurados nos Parâmetros da Integração serão incluídos no envio.
• O método de envio pode ser POST ou GET, conforme definido na configuração.
• Caso o método seja GET, os dados serão passados como parâmetros na URL.

---

5. Validação e Registro do Envio

A Integração Externa não realiza validação de cabeçalhos ou autenticação nativa. O envio dos dados ocorre de forma direta, e o resultado da requisição é registrado dentro da Ocorrência.

5.1 Validação da Requisição

• O sistema não valida cabeçalhos HTTP antes de enviar os dados.
• O endpoint configurado deve estar preparado para processar a requisição conforme os dados enviados.
• Caso seja necessária autenticação, isso deve ser tratado no sistema de destino.

5.2 Registro do Envio na Ocorrência

Independente do sucesso ou falha na requisição, o resultado do envio é registrado automaticamente na aba de Narrativas da Ocorrência. Isso permite que os usuários acompanhem o histórico da integração diretamente no CRM.

O registro pode incluir:

• Status da requisição (sucesso ou erro).
• Código de resposta HTTP retornado pelo servidor de destino.
• Mensagem de erro, caso ocorra alguma falha na comunicação.

5.3 Reenvio da Integração

A Integração Externa não possui um mecanismo automático de reenvio. Caso um envio falhe, será necessário ajustar a configuração e realizar a movimentação da Ocorrência novamente para disparar a integração manualmente.

---

6. Segurança e Boas Práticas

A Integração Externa lida com dados sensíveis de clientes e contratos, exigindo cuidados especiais para garantir a segurança das informações e evitar acessos indevidos.

6.1 Restrição de Configuração

• Apenas usuários com conhecimento técnico devem configurar a Integração Externa.
• A configuração incorreta pode expor dados privados de clientes, como documentos, endereços e informações contratuais.
• Recomenda-se que apenas administradores ou usuários autorizados tenham acesso à aba Integração Externa dentro do cadastro de Status.

6.2 Proteção dos Dados

• A URL configurada como endpoint da integração deve ser de um sistema confiável e seguro.
• Se a integração exigir autenticação, a proteção deve ser implementada no servidor de destino, pois o CRM não valida credenciais no envio dos dados.
• Se possível, utilizar HTTPS para proteger a transmissão dos dados.

6.3 Monitoramento e Auditoria

• O registro da integração na aba de Narrativas da Ocorrência deve ser monitorado regularmente para identificar possíveis falhas ou comportamentos inesperados.
• Caso um endpoint externo mude sua estrutura ou requisitos, a configuração da integração deve ser revisada para evitar falhas no envio.

6.4 Atualizações e Manutenção

• Sempre testar a integração em um ambiente de homologação antes de ativá-la em produção.
• Evitar modificar a configuração sem validar o impacto nos sistemas integrados.
• Manter a documentação da integração sempre atualizada para referência futura.

6.5 Uso de um Intermediador para Integrações Avançadas

Em casos onde o sistema de destino exige um formato mais complexo de dados, como arrays multinível ou validação de cabeçalhos, é possível criar uma página intermediária para atuar como um meio de campo entre a Integração Externa e o sistema final.

Como funciona?

1. A Integração Externa do CRM envia os dados no formato padrão (JSON de nível único).
2. A página intermediária recebe o POST da integração do CRM.
3. A página processa os dados recebidos e os reestrutura conforme o formato exigido pelo sistema de destino.
4. Após a transformação, os dados são enviados ao endpoint final com a formatação correta.

Vantagens do Intermediador

• Permite a adaptação dos dados sem alterar a estrutura nativa da Integração Externa.
• Possibilita a inclusão de cabeçalhos HTTP para autenticação ou validação.
• Facilita a compatibilidade com APIs que exigem JSON aninhado ou outros formatos específicos.
• Permite a implementação de regras de negócio antes do envio dos dados ao sistema de destino.

Quem pode desenvolver essa solução?

• A Multidados pode desenvolver essa página intermediária sob demanda.
• O cliente pode solicitar que um desenvolvedor de confiança implemente a solução, seguindo as necessidades específicas da integração.

---

7. Considerações Finais

A Integração Externa do CRM é uma ferramenta poderosa para automatizar a troca de informações com sistemas externos. No entanto, para garantir seu funcionamento correto e seguro, é fundamental que sua configuração seja realizada com atenção às diretrizes apresentadas neste manual.

7.1 Resumo dos Pontos-Chave

• A Integração deve ser liberada pelo Suporte da Multidados antes de ser utilizada.
• A configuração deve ser feita apenas por usuários experientes, dentro da aba Integração Externa do cadastro de Status.
• Os dados são enviados no formato JSON de nível único via POST ou GET, sem validação de cabeçalhos.
• O resultado do envio é sempre registrado na aba de Narrativas da Ocorrência, independentemente do sucesso ou falha.
• Não há reenvio automático – qualquer falha deve ser corrigida manualmente.
• A configuração incorreta pode expor dados sensíveis de clientes, exigindo restrições de acesso.
• Para integrações mais complexas, é possível criar um intermediador que transforme os dados antes de enviá-los ao sistema final.

7.2 Contato e Suporte

Caso haja dúvidas ou necessidade de suporte técnico, entre em contato com a equipe da Multidados através dos canais oficiais.

• E-mail: suporte@multidadosti.com.br
• Telefone: (11) 2579-8759
• Documentação Adicional: Integração Externa