Integração Analytics

h1. Manual de Integração

[[Integração 1.3]]

_Compatível com a versão 1.1.0 e >1.2.1_

_Editado em: 10/06/2013_

*Í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]]

## [[Manual de Integração#Títulos-em-Aberto|Títulos em Aberto]] _(versão > 1.2.1)_

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 asterisco (*) compõem a “primaryKey” e podem ser enviados como String ou Integer dependendo da necessidade do cliente.

Seguem os layouts das tabelas/visões

h2. Representantes

Esta tabela/visão 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/Integer   | 10         | Código da Empresa origem dos dados |

| codRepres *  | String/Integer   | 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/Integer  | 10         | Código da Empresa origem dos dados |

| codRepres *  | String/Integer   | 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.

*Situação:* O conceito de situação do cliente para o IGS é:

* 0-Inativo: Cliente que não está comprando, mas pode voltar a comprar

* 1-Ativo: Cliente com compra regular

* 2-Bloqueado: Cliente com restrições (ex: crédito) ou "Clientes que não interessam a empresa"

Caso seu ERP tenha somente os clientes ativos e inativos, retorne desta forma.

*Representante:* Só usar os campos codRepres2 e codRepres3 caso o cliente tenha variação de representante por linha de produto

|_. Campo      |_. Tipo   |_. Precisão |_. Descrição |

| codEmpresa * | String/Integer   | 10         | Código da Empresa origem dos dados |

| codIBGE     | String   | 7          | Codigo do IBGE da Cidade |

| codCliente *    | String/Integer   | 255          | Codigo do Cliente ou Prospect |

| tipo      | Integer   |           | Tipo de registro: 1 - Cliente, 2 - Prospect |

| nome         | String   | 255        | Nome do cliente |

| situacao     | Integer |          | Situação do cadastro do cliente: 0 - Inativo, 1 - Ativo, 2 - Bloqueado |

| codRepres1   | String   | 255        | Código do Representante Principal no ERP |

| codRepres2  | String   | 255        | Código do Representante 2 no ERP |

| codRepres3   | String   | 255        | Código do Representante 3 no ERP |

| telefone     | String   | 255        | Telefone de Contato |

| email        | String   | 255        | E-Mail |

| endereco     | String   | 255        | Rua + Número do endereço do cliente |

| bairro       | String   | 255        | Bairro do Endereço do cliente |

| CEP          | String   | 8          | CEP do endereço do cliente |

| dataCadastro | Date    |          | Data de Cadastro do Cliente |

h2. Coleções

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

|_. Campo      |_. Tipo   |_. Precisão |_. Descrição |

| codEmpresa * | String/Integer   | 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.

Entendesse como Linha de Produto a forma adotada pela empresa detentora do ERP para dividir seus produtos em grupos! Em caso de confecções, por exemplo, pode-se utilizar os critérios de (Infantil, Masculino, Feminino,etc.)

|_. Campo      |_. Tipo   |_. Precisão |_. Descrição |

| codEmpresa * | String/Integer  | 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 nos pedido de venda, deveremos acionar o cliente para definir outra tabela para extração dos dados (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, 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.

*Campos Coringa:* Os campos coringa são definidos no momento da implantação, para a primeira integração deve-se retornar nestes campos valor nulo (NULL).

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

|_. Campo          |_. Tipo   |_. Precisão |_. Descrição |

| codEmpresa *     | String/Integer   | 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.  |

| codRepres *      | String/Integer   | 255        | Código do Representante no ERP |

| codCliente *     | String/Integer   | 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 |

| campoCoringa1 *  | String   | 255        | Campo valores diversos, inicialmente retornar NULL - Ver com IBTech |

| campoCoringa2 *  | String   | 255        | Campo valores diversos, inicialmente retornar NULL - Ver com IBTech |

| campoCoringa3 *  | String   | 255        | Campo valores diversos, inicialmente retornar NULL - Ver com IBTech |

h2. Liquidez

Listar dados totalizando 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/Integer   | 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/Integer   | 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:*

Supondo que o ERP possua duas tabelas/visões, uma para Contas a Receber e outra para Contas Recebidas. Então devera ser feito 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 valor String para o formato data, utilize uma função compatível com o seu banco. Caso seja necessário utilizar outro formato, favor entrar em contato com a IBTech 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>

h2. Títulos em Aberto

Listar títulos/duplicatas em aberto. 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 |

| titulo *    | String | 255        | Identificação única para o título. Em caso de chave composta, sugerimos concatenar os campos usando algum separador |

| tituloFormatado | String | 255 | Identificação do título formatada de forma visual para o usuário |

| dataVencimento | Date     |         | Data de vencimento do título |

| dataVctoOriginal | Date     |         | Data de vencimento original do título |

| codPortador      | String   | 255        | Código do Portador |

| nomePortador      | String   | 255        | Nome do Portador |

| codCliente     | String   | 255        | Código do Cliente |

| emailCliente     | String   | 255        | E-mail do Cliente |

| codRepres     | String   | 255        | Código do Representante |

| valorTitulo       | Double   |            | Valor do Título |

Lista de Parâmetros:

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

|_. Parâmetro      |_. Tipo   |_. Precisão |_. Descrição |

| :pCodEmpresa     | String/Integer   | 10         | (opcional) Código da empresa no ERP |

| :pDataInicio     | String   | 10         | Data inicial para filtrar o vencimento (formato a combinar) |

| :pDataFim        | String   | 10         | Data final para filtrar o vencimento (formato a combinar) |

O SQL deve listar somente títulos em aberto.