A Integração de dados acessando webservices Demander

Objetivo Descrever as implementações necessárias para uma integração direta (sem utilização do Sincronizador Demander) entre o ERP e Demander.

Campos de controle no ERP Para implementar a integração direta entre ERP e Demander se faz necessário a criação de dois campos de controle, uma para registrar o token da empresa no Demander (campo tipo varchar com tamanho 200) e outro para registrar a última data/hora de busca de dados no Demander (campo datetime)

Separador de campos O leiaute padrão de integração do Demander é um arquivo texto no qual o separador de campos é o |

Importante considerar na geração dos dados, nos campos texto, que existe a possibilidade de o usuário ter utilizado um | ao cadastrar alguma informação no ERP, obrigatoriamente, esse | deve ser removido na exportação de dados para não causar problemas na integração.

Encode dos dados O Demander trabalha com o encode UTF8.

Na rotina de geração de dados a serem enviados para o Demander, deve-se observar a geração dos arquivos em UTF8, eventualmente algumas linguagens de programação ou mesmo sistemas operacionais trabalham por padrão com outros encodes, logo, sugerimos forçar a geração de dados a serem em UTF8 para garantir que a integração não seja afetada.

Na prática, a não utilização do encode UTF8 nos dados a serem enviados ao Demander, somente farão com que os dados importados pelo Demander sejam importados com caracteres especiais e não com as devidas letras, exemplo de: ç, ã, é, … que não serão mostrados e no seu lugar serão mostrados caracteres especiais.

Na rotina de imporação de dados no ERP, da mesma forma como na exportação de dados, sugere-se que a abertura do arquivo para leitura das informações seja forçado a utilização do encode UTF8, garantindo a importação dos dados de forma adequada no ERP.

Criação de empresas no Demander Se faz necessário a criação de uma empresa no Demander web para que um token seja gerado para a mesma, essa geração pode ser feita de duas formas, manual ou via integração.

Cadastro manual Essa documentação ainda está sendo detalhada e futuramente será adicionado o link para a mesma, enquanto não ocorre, seguir o descrito abaixo.

No Demander web para cadastrar uma empresa, utilizar o link abaixo, se faz necessário o preenchimento dos dados (essa tela somente o parceiro tem acesso, se você for o ERP de uma empresa que está integrando, solicite o token para a empresa ou para o Demander: sistema.demander.com.br/dinamico/empresas

Após o cadastro da empresa, será necessário a geração do token (aba integração) pelo link abaixo, essa operação se dá em duas telas pois a primeira somente o parceiro ou o Demander tem acesso e a segunda a empresa também tem acesso, pois se trata da tela de configuração do Demander: sistema.demander.com.br/dinamico/configuracoes-da-empresa

Integração via webservice Para integração via webservice, ver documentação abaixo: https://atendimento.demander.com.br/kb/article/140100/api-do-parceiro

Envio de dados do ERP para Demander Requisição de envio de dados No link abaixo está descrito como fazer a requisição de ENVIO de informações no Demander: https://atendimento.demander.com.br/kb/article/185185/api-demander-enviar-dados-para-o-demander?ticketId=&q=

Leiautes a serem integrados Os laiautes a serem integrados dependem das funcionalidades que a empresa irá utilizar, abaixo o link para todas as tabelas de integração possíves do Demander, perceba que existem tabelas que o Demander somente importa, outras que o Demander somente exporta e outra que são importadas e exportadas pelo Demander. https://atendimento.demander.com.br/kb/pt-br/article/131110/layout-de-integracao

Geração dos arquivos por tabelas Cada arquivo a ser gerado e enviado ao Demander obrigatoriamente deve conter na primeira linha do mesmo a versão na qual a geração foi baseada, logo ao iniciar a integração, questionar a equipe de implantação de qual código deve ser este.

Ao gerar o arquivo com os dados, sugerimos que sejam gerados arquivos separadamente, pois se o volume de dados da empresa for muito grande, pode acontecer um time-out no envio de dados, logo com arquivos menores, essa possibilidade se torna bem menor.

Algumas tabelas obrigatoriamente precisam estar no mesmo arquivo de dados, seguem abaixo relação de tabelas, as não citadas, podem estar em arquivos distintos. 16-Pedido + 17-Itens de pedido + 26-Grade dos itens de pedido 41-Tipo cliente tributário + 42-Tributação 31-Níveis comissão + 32-Comissão 51-Equipe vendas + 52-Vendedores equipe vendas + 53-Gerentes equipe vendas 60-Perspectiva metas + 61-Niveis meta + 62-Valores meta 09-Tabela preço + 13-preços + 15-produtos 20-Rota + 21-Clientes da rota 19-Títulos financeiros 57-Estoque pronta entrega 180-Faixa flex por tabela de preço

Logs de exportação No link abaixo podemos ver a relação dos arquvos que o ERP enviou ao Demander nos últimos 3 meses, que é o tempo que mantemos de log: sistema.demander.com.br/dinamico/arquivos-recebidos-do-erp

Busca de dados do Demander para ERP Requisição da busca de dados No link abaixo está descrito como fazer a requisição de BUSCA de informações no Demander: https://atendimento.demander.com.br/kb/article/185186/api-demander-receber-dados-do-demander?ticketId=&q=

Controle da data da última busca No arquivo baixado, a primeira linha do mesmo contém informações importantes, segue abaixo exemplo da primeira linha que todos os arquivos que serão disponibilizados pelo Demander terão: DADOS_SINCRONIZACAO|71408323|30/03/2021 13:07:42|30/03/2021 13:09:21|

onde: DADOS_SINCRONIZACAO -> primeiro campo, é um texto fixo 71408323 -> segundo campo, é o Id do log de integração no Demander, o arquivo texto disponibilização tem esse mesmo nome 30/03/2021 13:07:42 -> terceiro campo, é a data/hora que foi enviada (e que está salva no ERP conforme descrição em ‘Campos de controle no ERP’) na requisição de busca de informações no Demander. 30/03/2021 13:09:21 -> quarto campo, é a data/hora que a requisição de busca chegou no Demander, então o arquivo em questão possui dados que foram incluídos ou alterados entre data/hora do campo 3 e campo 4. Esse conteúdo deve ser salvo no campo criado (conforme descrição em ‘Campos de controle no ERP’), pois essa data/hora deverá ser enviada na requisição seguinte de busca de dados no Demander.

Logs de importação No link abaixo podemos ver a relação dos arquvos que o ERP buscou no Demander nos últimos 3 meses, que é o tempo que mantemos de log: sistema.demander.com.br/dinamico/arquivos-recebidos-do-erp

Logs retornados nas requisições de busca e envio O retorno das requisições de envio e busca é um texto. Dependendo do erro, no caso de envio de dados, o renvio do arquivo se faz necesário.

Retornos possíveis: Retorno iniciando por ‘ERRO 01: Nenhuma empresa localizada com o Token’ -> Não existe empresa no Demander com este token

Retorno iniciando por ‘ERRO 02:’ -> Empresa inativa no Demander (precisa reenviar o arquivo)

Retorno iniciando por ‘ERRO 03:’ -> Parâmetro Arquivo não está na requisição (precisa reenviar o arquivo)

Retorno iniciando por ‘ERRO 04:’ -> Problema no upload do arquivo (precisa reenviar o arquivo)

Retorno iniciando por ‘ERRO 05:’ -> Empresa inadimplente no Demander (precisa reenviar o arquivo)

Retorno iniciando por ‘ERRO 08:’ -> Empresa fora do tempo de testes no Demander (precisa reenviar o arquivo)

Retorno iniciando por ‘ERRO: A primeira linha do arquivo deve ser a versao do Layout de Integracao.’ -> Cada arquivo a ser enviado para o Demander deve conter a versão na qual se baseou a geração de dados (precisa reenviar o arquivo)

Retorno iniciando por ‘ERRO na linha’ -> Existe algum erro em algum registro do arquivo, exemplo: um cliente veio sem razão social. Esse erro precisa ser tratado caso a caso, o ideal é logar e orientar a alguém olhar esse log, ou então somente orientar a olhar os logs de tempos em tempos pelo Demander web.

Retorno iniciando por ‘A empresa não está configurada para importar pedidos, caso necessário entre em contato com o suporte do Demander.’ -> como o retorno de pedidos para o Demander (vindos do ERP), necessita de homologação, essa opção somente é liberada quando solicitada a Retta que assim o faça, até para acompanharmos essa integração. (ativar configuração e reenviar o arquivo)

Retorno iniciando por ‘ERRO=A empresa não está configurada para calcular IPI e/ou ICMS ST. A configuração não foi importada.’ -> No envio de dados de tributação (tabela 41 e 42), somente iremos importar as mesmas se a empresa estiver configurada para apurar os impostos. (ativar configuração e reenviar o arquivo)

Retorno iniciando por ‘O Demander ignorou a importação deste arquivo.’ -> Ao importarmos os dados de um arquivo, geramos ua hash do conteúdo do arquivo, e se este arquivo já foi importado nas últimas 6 horas, o mesmo é ignorado, o objetivo disso é melhorar o tempo de resposta da solução, não processando dados que já foram processados anteriormente. Se a empresa envia somente alterações dados, contatar implantação Demander para receber orientações.

Retorno iniciando por ’ Tempo upload s3: ’ -> indica que o arquivo foi enviado com sucesso Retorno iniciando por ’Tempo: ’ -> indica o tempo que o processamente do arquivo levou Retorno iniciando por ‘Arquivo processado.’ -> significa que o arquivo foi processado Retorno iniciando por ‘SUCESSO=’ -> Significa que o processo foi concluído com sucesso

Na prática a preocupação deve ser com os logs nos quais o arquivo como um todo não foi processado (exceto o ignorar arquivos), e nesse caso, o arquivo deveria ser reenviado em um segundo momento.

O ideal é que o arquivo fique numa pasta e ao iniciar o processo, se um arquivo estiver na pasta, que primeiro seja feito o envio do mesmo para então somente um novo arquivo de dados seja enviado.

Ainda sugerimos em caso de um erro ocorrer, que alguém seja notificado por email do erro, para que exista uma avaliação pró-ativa.