Integração Analytics

h1. Manual de Integração

_Versão: 1.1.0 (2012-04-25)_

*Índice*
# [[Manual de Integração#Introdução|Introdução]]
# [[Manual de Integração#Acesso-via-JDBC|Acesso via JDBC]]
# [[Manual de Integração#Tabelas-de-Integração|Tabelas de Integração]]
## [[Manual de Integração#Representantes|Representantes]]
## [[Manual de Integração#Municípios-do-Representante|Municípios do Representante]]
## [[Manual de Integração#Clientes-e-Prospects|Clientes e Prospects]]
## [[Manual de Integração#Coleções|Coleções]]
## [[Manual de Integração#Linhas-de-Produto|Linhas de Produto]]
## [[Manual de Integração#Vendas|Vendas]]
## [[Manual de Integração#Liquidez|Liquidez]]

h1. Introdução

O presente documento tem por objetivo orientar as empresas de ERP na geração dos arquivos e/ou tabelas necessárias para integração com o IGS.

Dúvidas ou maiores esclarecimentos podem ser obtidos pelo e-mail contato@ibtech.inf.br ou pelo telefone (47) 3370-0504.

h1. Acesso via JDBC

*Pré-Requisito:* Suporte por parte do Banco de Dados da Empresa fornecedora do ERP a acesso JDBC.

Na integração via JDBC a fornecedora de ERP deve disponibilizar para a IBTech tabelas (ou visões) conforme os layouts especificados neste documento, também deverá fornecer um usuário e senha que tenha permissão de consulta nas referidas tabelas ou visões. A IBTech fará acesso via JDBC à base de dados do cliente para extrair as informações.

h1. Tabelas de Integração

Todas as tabelas/visões tem um campo chamado “codEmpresa” que separa a geração dos dados entre as possíveis várias empresas que o cliente tenha na mesma base de ERP.

*Observação:* Os campos com asteriscos (*) compõem a “primaryKey” e poderão serem enviados como String ou Integer dependendo da necessidade do cliente.

Seguem os layouts das tabelas/visões

h2. Representantes

Esta tabela será utilizada para carregar no IGS a lista de representantes. Não é uma integração obrigatória, pois o cliente pode digitar os representantes diretamente no IGS.

|_. Campo |_. Tipo |_. Precisão |_. Descrição |
| codEmpresa * | String | 10 | Código da Empresa origem dos dados |
| codRepres * | String | 255 | Código do Representante no ERP |
| nome | String | 255 | Nome do Representante |
| telefone | String | 255 | Telefone de Contato |
| email | String | 255 | E-Mail |
| endereco | String | 255 | Rua + Número do endereço do Representante |
| bairro | String | 255 | Bairro do Endereço do Representante |
| CEP | String | 8 | CEP do endereço do Representante |
| Cidade | String | 255 | Nome da Cidade do Endereço do Representante |
| UF | String | 2 | Sigla da UF da Cidade |
| codIBGE | String | 7 | Codigo do IBGE da Cidade |
| situacao | Integer | | Situação do cadastro do representante: 0 - Inativo, 1 - Ativo |

h2. Municípios do Representante

Tabela/visão com a relação dos municípios que o representante atende. Esta não é uma integração obrigatória.

|_. Campo |_. Tipo |_. Precisão |_. Descrição |
| codEmpresa * | String | 10 | Código da Empresa origem dos dados |
| codRepres * | String | 255 | Código do Representante no ERP |
| codIBGE | String | 7 | Codigo do IBGE da Cidade |

h2. Clientes e Prospects

Tabela/visão com a relação dos clientes e prospects.
Podem ser listados clientes ativos ou inativos dependendo da necessidade do cliente.

|_. Campo |_. Tipo |_. Precisão |_. Descrição |
| codEmpresa * | String | 10 | Código da Empresa origem dos dados |
| codIBGE * | String | 7 | Codigo do IBGE da Cidade |
| codCliente * | String | 255 | Codigo do Cliente ou Prospect |
| tipo | Integer | | Tipo de registro: 1 - Cliente, 2 - Prospect |
| codRepres1 | String | 255 | Código do Representante no ERP |
| nome | String | 255 | Nome do Representante |
| telefone | String | 255 | Telefone de Contato |
| email | String | 255 | E-Mail |
| endereco | String | 255 | Rua + Número do endereço do Representante |
| bairro | String | 255 | Bairro do Endereço do Representante |
| CEP | String | 8 | CEP do endereço do Representante |
| situacao | Integer | | Situação do cadastro do representante: 0 - Inativo, 1 - Ativo |

h3. Coleções

Tabela/visão com a relação das coleções.

|_. Campo |_. Tipo |_. Precisão |_. Descrição |
| codEmpresa * | String | 10 | Código da Empresa origem dos dados |
| codColecao * | String | 255 | Codigo da coleção |
| nome | String | 255 | Nome da coleção |

h2. Linhas de Produto

Lista das linhas de produtos que tiveram dados gerados.

|_. Campo |_. Tipo |_. Precisão |_. Descrição |
| codEmpresa * | String | 10 | Código da Empresa origem dos dados |
| codLinha * | String | 255 | Codigo da linha de produto |
| nome | String | 255 | Nome da linha de produto |

h2. Vendas

Esta é a principal tabela do processo de integração. Ela deverá armazenar os dados necessários para apresentação dos valores relativos às vendas realizadas.
Geralmente é gerada em cima dos pedidos de venda. Caso o ERP não consiga gerar os dados com base em pedido de venda devemos acionar o cliente para definir qual outra tabela iremos usar de base (Exemplo: Notas Fiscais).
Caso a geração seja por coleção (no caso de Confecções, por exemplo), a fornecedora de ERP deve manter uma configuração onde o cliente deverá informar de quais coleções as informações devem ser geradas.
Caso a geração seja por período (caso de outros ramos de negócio), deve-se definir com o cliente de qual período ele quer as informações (ultimo ano, últimos 2 anos, etc).

*Prazo Médio:* Média em dias do prazo de pagamento (condição de pagamento). Por exemplo, condição 30/60/90: 30+60+90 = 180, 180 / 3 parcelas = 60 dias. *Importante!* Este cálculo deve retornar valor maior igual a 1 (um), caso o cálculo retorne valor menor que 1 (um), então, substituir o resultado por 1 (um).

*Observação:* Os campos com (*) asterisco deverão ser agrupados e os demais somados (sum).

|_. Campo |_. Tipo |_. Precisão |_. Descrição |
| codEmpresa * | String | 10 | Código da Empresa origem dos dados |
| codColecao * | String | 255 | Código da Coleção sobre a qual estamos gerando os dados. |
| dataReferencia * | Date | 255 | Armazena a data de emissão do Pedido de Venda. (Caso a geração seja em cima das notas fiscais, deverá armazenar a data de emissão da Nota Fiscal) |
| codLinha * | String | 255 | Código da Linha de Produto. Define-se com o cliente o que ele quer gerar como linha de produto. Em caso de confecções, por exemplo, pode-se utilizar os critérios de Infantil, Masculino, Feminino, Bebe, etc. |
| codRepres * | String | 255 | Código do Representante no ERP |
| codCliente * | String | 255 | Codigo do Cliente |
| codIBGE * | String | 7 | Codigo do IBGE da Cidade do Cliente |
| UF * | String | 2 | Sigla da UF da Cidade do Cliente |
| valorBruto | Double | | Valor Bruto das Vendas |
| valorLiquido | Double | | Valor Liquido das Vendas (ex: Valor Bruto - Valor Descontos) |
| valorDesconto | Double | | Valor de Descontos das Vendas |
| valorComissao | Double | | Valor de Comissão das Vendas |
| prazoMedioXValor | Double | | Valor Líquido das Vendas multiplicado pelo Prazo Médio de pagamento. |
| quantidade | Double | | Quantidade de Peças das Vendas |
| nomeCliente * | String | 255 | Nome do Cliente |
| codPedido * | String | 255 | Código do Pedido |
| codProduto * | String | 255 | Código do produto ou referência |
| valorCoringa1 * | String | 255 | Campo valores diversos, inicialmente retornar NULL diversos - Ver com IBTech |
| valorCoringa2 * | String | 255 | Campo valores diversos, inicialmente retornar NULL diversos - Ver com IBTech |
| valorCoringa3 * | String | 255 | Campo valores diversos, inicialmente retornar NULL diversos - Ver com IBTech |

h2. Liquidez

Listar dados totalizados os valores a receber e os valores recebidos agrupando por representante. Normalmente estes registros são provenientes do cadastro de contas a receber.

*Importante!* Este SQL possui parâmetros.

Layout da tabela/visão:

|_. Campo |_. Tipo |_. Precisão |_. Descrição |
| codRepres * | String | 255 | Código do Representante no ERP |
| valorAReceber | Double | | Valor a receber acumulado por representante |
| valorRecebido | Double | | Valor recebido acumulado por representante |

Lista de Parâmetros:

_Formato sugerido de data: dd/mm/yyyy (31/12/2013)_

|_. Parâmetro |_. Tipo |_. Precisão |_. Descrição |
| :pCodEmpresa | String | 10 | (opcional) Código da empresa no ERP |
| :pDataInicio | String | 10 | Data inicial para filtrar o vencimento e pagamento (formato a combinar) |
| :pDataFim | String | 10 | Data final para filtrar o vencimento e pagamento (formato a combinar) |

Exemplo:

Supomos que você possua duas tabelas, uma para Contas a Receber e outra tabela para Contas Recebidas. Então decidimos fazer um UNION das duas tabelas a fim de facilitar a manutenção do SQL:

Observação: Note que usamos uma função to_date que converte o String para o campo data, utilize uma função compatível com o seu banco. Caso necessite de outro formato, o mesmo deve ser repassado a nossa equipe para configuração.

<pre>
SELECT codRepres, sum(valorAReceber), sum(valorRecebido)
FROM (
SELECT codRepres,
valorTitulo as valorAReceber,
0.0 as valorRecebido
FROM ContasAReceber
WHERE codempresa = :pCodEmpresa
AND dataVecto >= to_date(:pDataInicio,'dd/mm/yyyy')
AND dataVecto <=to_date(:pDataFim,'dd/mm/yyyy')
UNION ALL
SELECT codrepres,
0.0 as valorAReceber,
sum(valorTitulo) as valorRecebido
FROM ContasRecebidas
WHERE codempresa = :pCodEmpresa
AND dataPagto >= to_date(:pDataInicio,'dd/mm/yyyy')
AND dataPagto <=to_date(:pDataFim,'dd/mm/yyyy')
AND dataVecto >= to_date(:pDataInicio,'dd/mm/yyyy')
AND dataVecto <=to_date(:pDataFim,'dd/mm/yyyy')
)
GROUP BY codRepres
</pre>