Quando aplicações consumirem dados do CIGAM — seja por meio dos serviços disponibilizados ou pela camada de objetos do banco de dados — deverão informar os parâmetros de data e hora referentes ao controle de gravação dos registros. Dessa forma, será possível filtrar apenas os registros alterados a partir da data e hora especificadas.
Caso esses parâmetros não sejam informados, todos os dados do respectivo cadastro serão retornados.
O CIGAM não realiza controle por flags de leitura ou integração. Caso esse tipo de controle seja necessário, ele deverá ser implementado pelas aplicações de terceiros em suas próprias tabelas.

Para integrações, recomenda-se informar os parâmetros correspondentes à chave única do cadastro, permitindo assim a obtenção de dados de um único registro específico, quando necessário.
O controle de acesso é feito por meio do parâmetro de PIN, que será detalhado mais adiante.

Quando aplicações de terceiros enviam dados para o CIGAM, essas informações são registradas na tabela de integração, desde que sejam aceitas pelo sistema. A importação e o processamento dos dados só ocorrerão quando o programa específico da Aplicação de Importação for executado.
Caso algum dado não seja aceito, nenhum registro será inserido na tabela de integração, e será retornada ao chamador uma mensagem de erro contendo o código e a descrição do problema.

Para o controle de existência de registros, as camadas de consulta disponibilizam uma lista contendo apenas os campos-chave de todos os registros existentes na tabela. Essa lista permite que a aplicação de terceiros compare com sua base local e identifique registros que foram excluídos no CIGAM.

Se a tabela possuir um grande volume de registros ou se ocorrerem muitas exclusões, é possível criar uma trigger para consumir o respectivo serviço a cada exclusão.
No entanto, é importante destacar que o uso de triggers pode impactar negativamente a performance da aplicação, especialmente quando acionadas por requisições de webservices.

Serviços disponíveis

Compras

Configurador

Estoque

Faturamento

Financeiro

Genérico

Projetos

Estrutura dos registros

A tabela de integração é onde devem ser inseridos os registros a serem posteriormente importados pelo CIGAM.
Todos os tipos de cadastros utilizam essa mesma tabela, e um campo chamado Tipo identifica qual rotina de importação será responsável por processar cada registro.

Exemplos de valores para o campo Tipo:

MATCAD - Cadastro de materiais
EMPCAD - Cadastro de empresas

Essa tabela possui um grande número de campos, projetados para acomodar diferentes tipos de cadastros do CIGAM.
Entretanto, somente os campos de ID e Tipo são indexados, garantindo melhor desempenho nas consultas essenciais.

Camada de Serviços

A camada de serviços funciona como porta de entrada para as integrações.
Para cada tipo de cadastro/registro, existe um serviço específico.
Além dos parâmetros próprios de cada rotina, esses serviços incluem o parâmetro PIN, utilizado para identificar o usuário ou aplicação responsável pela requisição.

Controle de Status dos Registros

Na tabela de integração existe um campo de controle de status, utilizado para gerenciar o processamento dos registros.
Quando há relacionamento máster-detalhe, o controle é feito no registro máster.

Esse controle é necessário para evitar que o programa de importação execute enquanto os dados ainda estão sendo inseridos.
Assim, o status do registro máster só é liberado após todos os registros de detalhe terem sido incluídos, garantindo consistência.

Outra estratégia possível é a de o programa de integração inserir o registro máster por último, assegurando também a integridade dos dados no momento da importação.

Consulta à Tabela de Integração

Existe um webservice de listagem da tabela de integração, que permite filtrar registros por:

ID da tabela
Data de inclusão do registro
Tipo de registro
Ou combinações desses filtros

Esse serviço auxilia as aplicações de terceiros a verificar se um determinado registro já foi importado, permitindo um controle mais eficiente dos dados integrados.

Validação de parâmetros

Durante a requisição de um serviço, caso algum parâmetro obrigatório não seja informado, o sistema retornará uma mensagem de erro indicando o nome do parâmetro ausente.

Se houver mais de um parâmetro obrigatório faltando, todos os nomes serão listados na mesma mensagem, facilitando a identificação e correção pela aplicação integradora.

Para parâmetros que possuem dependência de outro parâmetro, será exibido um asterisco (<*>) após o nome.
Essa marcação sinaliza que a obrigatoriedade está condicionada ao preenchimento de outro campo relacionado.

Tabela de integração e log

Tabelas envolvidas:
- Integração %GEINTEGRADOR%
- Log de integração %GEINTEGRADORLOG%

Todas as alterações de dados requisitadas para o CIGAM ficarão na tabela de integração até seu processamento pela Aplicação de Integração. Sempre que uma das camadas alterarem os dados dessa tabela será adicionada uma linha da tabela de log.
Como a tabela de integração e log possuem campos com nomes genéricos a qualquer cadastro ou rotina do CIGAM, a consulta bem como a inclusão de dados deverá ser feita pelas respectivas camadas as quais apresentarão os nomes dos campos adequadamente.
As tabelas de integração e log ficarão em um banco separado. Esse banco será acesso pelo Database CIGAM_INTEGRA em aplicações do CIGAM e pela Aplicação de Integração (componente CGIntegrador.ecf)
Se o banco de dados for diferente ao utilizado pelo CIGAM (inclusive se mudar apenas o database/usuário), deve-se informar uma connection string chamada INTEGRACAO no arquivo de configuração.

Também deve ser informado o banco de dados nessa nova conexão no parâmetro providerName.
   Exemplo:
       <add name="CIGAM" connectionString="Server=servidor;Database=BD;User ID=USER;Password=SENHA;
       <add name="INTEGRACAO" connectionString="Server=servidor;Database=BD;User ID=USER;Password=SENHA;" providerName="02"/>

O código de banco de dados do CIGAM deve ser informado na configuração BANCO_DADOS da aplicação.
   Exemplo:
      <add key="BANCO_DADOS" value="03" />

Para registrar requisições provenientes de aplicativos de terceiros, é necessário utilizar o parâmetro chamado CGREQUISICAOWS. Já para registrar requisições de serviços específicos, deve-se empregar o parâmetro CGREQUISICAOWS_ seguido do tipo de registro desejado. Por exemplo, para registrar requisições relacionadas a cadastros de notas fiscais, o parâmetro seria GREQUISICAOWS_CADNF1.

Exemplo de aplicabilidade dentro do arquivo web.config na sessão settings ou quando existir, diretamente no arquivo settings.config:

   <add key="CGREQUISICAOWS" value="C:\cigam\Temp\"/>

   <add key="CGREQUISICAOWS_CADNF1" value="C:\cigam\Temp\NF\"/>

Caso não seja necessário gravar nenhuma requisição em arquivo, nenhum dos parâmetros mencionados acima deve ser utilizado.

Registros correlatos

A tabela de integração poderá ter registros correlatos pendentes de importações, como por exemplo, pedidos versus itens versus grade do item. Neste caso quando o pedido for importado será feita uma verificação se existem itens para esse pedido. Da mesma forma, quando o item do pedido for importado será verificado se existe grade do item. Nesse ponto, somente os registros com status liberado serão avaliados e importados/recursados.
Os registros correlatos que não estão liberados, não serão tratados e, portanto jamais serão reavaliados. Para evitar registros perdidos na tabela de integração, será executada uma rotina de limpeza que irá excluir os registros com ID correlato cujo registro máster não esteja mais pendente de importação. Essa exclusão registrará um log específico.

Segurança

As aplicações de terceiros não utilizam o cadastro de usuários nem os direitos do CIGAM, pois não têm como gerenciar adequadamente essas informações.
A autenticação e o controle de acesso são realizados através de PINs e da chave de criptografia (CHAVE_CRYPTA) definidos no arquivo de configurações do ambiente do Web Service (seção <appSettings>).

📌 PIN

O PIN é utilizado para identificar quem está realizando a requisição e definir os serviços disponíveis para cada integração.

Ele deve ser configurado no arquivo de ambiente do Web Service.

No exemplo abaixo, as requisições que utilizarem o PIN XW@#25Qo terão acesso apenas aos serviços CADMAT e CADEMP.

Os demais PINs @#0Q1o2, W#12@Abfg e 20020004 não possuem restrições definidas e podem acessar todos os serviços:

  <appSettings>
    <add key="pin" value="XW@#25Qo;@#0Q1o2;W#12@Abfg;20020004" />
    <add key="XW@#25Qo" value="CADMAT;CADEMP" />
  </appSettings>

💡 Recomendação: Defina PINs com alta complexidade para reforçar a segurança das informações trafegadas entre os sistemas.

📌 CHAVE_CRYPTA

A CHAVE_CRYPTA é utilizada para criptografar e descriptografar dados sensíveis transmitidos entre o CIGAM e aplicações externas, garantindo a confidencialidade e integridade da comunicação.

Essa chave também deve ser configurada no <appSettings> do ambiente do Web Service:

  <appSettings>
    <add key="CHAVE_CRYPTA" value="MinhaChaveSegura123!" />
  </appSettings>

Todos os sistemas envolvidos na integração devem utilizar a mesma CHAVE_CRYPTA.
Caso as chaves estejam divergentes entre os ambientes, ocorrerão erros de descriptografia e falhas de comunicação.
A alteração da chave deve ser coordenada em todos os pontos de integração.
Mantenha a chave em sigilo e compartilhe somente com equipes autorizadas.

Requisição e resposta dos Webservices

Serão suportadas as tecnologias SOAP e Rest/JSon sendo que nessa segunda opção os parâmetros devem ser enviados por POST e o nome do método junto na URL. As respostas dos serviços também estarão disponíveis nessas duas tecnologias.
Quando o retorno contiver mais de um registro, a exportação será feita com duas coleções (objetos), uma para as colunas e outra para os dados. Neste caso as colunas ganham cabeçalhos nomeados para referenciar os dados (c1, c2...).
A opção EXPORT_HEADERS pode ser inserida no arquivo de configurações do ambiente do Web Service (seção <appSettings>) para indicar se a exportação deve ocorrer sempre usando os cabeçalhos ou não, independentemente da quantidade de registros.
    Exemplo:
       <appSettings>
       <add key="EXPORT_HEADERS" value="N"/>
É possível incluir no arquivo Settings.
Quando o nome da coluna da tabela no banco de dados for diferente do nome utilizado no CIGAM/CGData, na coleção dos nomes de colunas existirá uma tag com essa identificação.
Não serão exportados campos ainda não nomeados (exemplo: Campo31, Campo32...). Exceção: Campos de usuário que são os iniciados com nome <Usr>.
No formato JSON será necessário atributar ambas as propriedades, pois não há como colocar um valor para a tag principal como no XML. Neste caso, o apelido da coluna deverá ficar na tag <db_alias>.
Como primeiro nó da árvore, em ambos os formatos será utilizado o valor da tradução do Nome Lógico da tabela exportada. As colunas serão agrupadas na coleção <col> e os campos de cada registro na coleção <reg>. Os dados serão formatados com decodificação UTF-8.
    Exemplos de resposta:

XML

JSON

<esmateri>
      <col>
         <cd_material>c1</cd_material>
         <descricao>c2</descricao>
         <valor_imposto>c3</valor_imposto>
      </col>
      <reg>
         <c1>001</c1>
         <c2>Material Teste 1</c2>
         <c3>10</c3>
      </reg>
      <reg>
         <c1>002</c1>
         <c2>Material Teste 2</c2>
         <c3>20</c3>
      </reg>
   </esmateri>

{
       "col": [
      {
          "cd_empresa": "c1",
          "descricao": "c2",
          "valor_imposto": {
          "db_column": "campo3",
          "db_alias": "c3"
       }
     }
     ],
       "esmateri": [
       {
          "c1": "001",
          "c2": "Material Teste 1",
          "c3": "10"
       },
       {
          "c1": "002",
          "c2": "Material Teste 2",
          "c3": "20"
     }
     ]

Existe um validador para o padrão JSON em http://jsonlint.com

Tipos especiais

Alguns dados terão formatos especiais na requisições e respostas.

Tipo do dado	Formato	Máscara	Exemplo	Onde
Data	XML	DateTime (conforme ambiente em que o Serviço está rodando)	01-jan-2013	Requisição
Data	XML	dd/mm/yyyy	01/01/2013	Resposta
Data	JSON	dd/mm/yyyy ou dd-mmm-yyyy	01/12/2013 ou 01-dec-2013	Requisição e Resposta
Booleano	XML	Bool (conforme tipagem)	True	Requisição
Booleano	XML	True ou False	True ou False	Resposta
Booleano	JSON	TRUE,True,true ou FALSE,False,false	True ou false	Requisição
Booleano	JSON	True ou False	True ou False	Resposta
Time	XML e JSON	161050	161050	Requisição e Resposta
Numéricos	XML e JSON	Sem separador de milhar e com ponto (“.”) como separador decimal	150 120.00 1250.33222	Requisição e Resposta

Quando utilizar o formato XML, os valores enviados para parâmetros de tipos especiais, no serviço SOAP o próprio serviço garante o dado de entrada correto. Quando exportado irá seguir conforme a tabela anterior.
Quando utilizar o formato JSON, para os campos do tipo data o dado terá que vir no formato conforme a tabela anterior e para campos do tipo booleano terá que vir um “true” (não importando a capitalização) para que seja verdadeiro, pois para qualquer outra coisa será considerado como falso.

Para campos de dados do tipo hora, terão o dia com 24 horas e sem dois pontos “:” (HHMMSS)

Configurações especiais do banco de dados

Para que os serviços acessem corretamente os dados do tipo Date e DateTime, é obrigatório que a sessão com o banco de dados permita a informação de filtros por datas no formato americano “dd-mmm-yyyy” Exemplo: 01-jan-2013, 20-feb-2013 e 12-oct-2013. Para bancos de dados SQLServer essa parametrização já vem por padrão.
Para bancos de dados Oracle esse parâmetro pode variar de acordo com o idioma do Sistema Operacional no momento da instalação. Neste caso, verifique se o parâmetro de sessão “nls_language” está definido como “AMERICAN”. Esse valor pode ser ajustado no Registro do Windows para que todas as sessões sejam inicializadas dessa forma. Observar também se o Web Server que hospeda os serviços está com o modo 32bits/x86 habilitado, pois neste caso também é necessário ajustar os “nls_language” do Client32 do Oracle.

Validação do Integrador pelo IIS

Primeiramente para essa validação, é preciso acessar a pastas de instalação do Integrador (Webservices) e ajustar as configurações dos arquivos Settings.config e web.config, lembrando de remover o @ que vem por default com a implementação:

Para o arquivo web.config deve ser ajustado os campos de ConnectionString "CIGAM" e "INTEGRACAO" que podem ser gerados pelo programa CGConnectionString que se encontra no CIGAM_INSTAL ou também ser utilizada a mesma string informada na API e Portais, lembrando que no ProviderName 02 é SQL Server e 03 Oracle. Importante criptografar a string de conexão.

Em seguida é necessário criar a pasta Bin dentro da estrutura de instalação do integrador com as DLL's (encontradas no CIGAM_INSTAL):

CIGAM.Ambiente;

CIGAM.Extensions;

CIGAM.Sgbd;

CIGAM.Utils;

CIGAM.Webservices;

Feito isso, retornando ao IIS, no parte inferior é necessário alterar a forma de exibição para Content View, após isso selecionar o arquivo TesteBancoDados.ashx e clicar em Browse para abrir o navegador com a validação do Integrador.

Log

A tabela de log é praticamente uma cópia da tabela de integração com a adição dos campos para a data e hora da ocorrência/execução. O processo de criação e registro dos Logs será feito da seguinte forma:

O Webservice recebe a requisição e verifica se todos os parâmetros são válidos. Caso não sejam, retorna um erro ao usuário e não registra qualquer tipo de inserção na tabela de integração ou de log.
Se os parâmetros passados para o webservice forem válidos, insere na tabela de integração, retorna uma mensagem e sucesso ao usuário sem registrar log.
Quando o programa da aplicação de integração executar e importar o registro da tabela de integração, o log é criado com os dados importados (inclusive o usuário logado no CIGAM que fez a importação). Após isso, o registro da tabela de integração será apagado.
No log é um campo para saber se o registro foi importado ou recusado. Caso recursado, armazena também o código e a mensagem de erro. Isso se faz necessário para que os registros com erro não fiquem na tabela de integração.

Após liberar os registros pendentes será registrado log. Se tentar liberar um registro inexistente será retornado um erro e não será registrado log. Não será testado se está sendo liberado um registro já liberado pois teria também que ser feito um controle para a liberação dos correlatos.

Em Genéricos/Pesquisas/Rotinas existe uma tela on-line para que o usuário/administrador/DBA possa visualizar a tabela de Log.
A tabela de log não é indexada para ganho de performance. Se a tabela do log for grande, poderão ser criados os índices de acordo com as necessidades.
Não é gerado log sobre as consultas de dados efetuadas.

O log poderá ser limpo ou mantido apenas “n” dias conforme a necessidade do administrador do banco de dados (a limpeza será manual por segurança).

Aplicação de Integração

A camada de serviços e ou de banco de dados garantem “apenas” que o dado chegue até à tabela de integração. A importação dos dados é feita por um programa específico da aplicação de integração chamado Integrador.

Ao indicar statusRegistro igual a pendente o registro enviado não será integrado ao ERP CIGAM até que tenha seu status igual a liberado. Sendo possível sua liberação através do método LiberarPendentes. Também é possível criar o registro com o status Liberado sem a necessidade de requisitar um novo método para liberação.

Utilizando o retorno dos Serviços

Xml

Os serviços que utilizam o protocolo SOAP, tem como retorno uma String no formato Xml, para melhor visualização destes dados, está disponível na classe “Xml”, do namespace Cigam.Utils, um método estático chamado “XmlStringToDataTable”. Este retorna um objeto do tipo System.Data.DataTable. Segue abaixo um exemplo de implementação.

Também pode ser utilizada a classe XmlDocument, do namespace System.Xml para fazer a manipulação dos dados. Segue abaixo um exemplo de implementação.

Json

Os serviços que utilizam o protocolo REST, tem como retorno uma String no formato JSon, para trabalhar com estes dados, está disponível a classe “JSonDocument” no namespace Cigam.Utils. Esta classe fornece a interpretação da string retornada além de propriedades e métodos para manipulação dos dados. Seguem abaixo exemplos de como instanciar e alimentar a classe.

   Exemplo 1:

   Exemplo 2:

   Exemplo 3:

Esta classe também fornece uma propriedade contendo uma lista genérica que guarda objetos do tipo Cigam.Utils.JSonObject, e esta lista fornece informações sobre os registros da consulta, como o nome da coluna e o valor. Através desta classe também é possível obter o nome original das colunas, caso a consulta possua um cabeçalho de apelidos, ou saber se a consulta retornou exception, success ou query. Veja os exemplos abaixo:
   Exemplo 1:

   Exemplo 2:

Anônimo

Pesquisa

IN CIGAM Integrador

Índice