Integração Analytics

h1. Manual de Integração

[[Envio de Duplicatas]]

[[Portal de Clientes - API]]

[[CRM]]

[[Digitação de Pedidos]]

[[Digitação de Pedidos - Padrão]]

[[Digitação de Pedidos - Imagens dos Produtos]]

[[Loja Virtual]]

[[Loja Virtual - Imagens]]

[[Produção]]

[[Gestão de Cobrança]]

[[Gestão de Crédito]]

*Í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#Marcas-do-Cliente|Marcas do Cliente]] 

## [[Manual de Integração#Coleções|Coleções]] 

## [[Manual de Integração#Linhas-de-Produto|Linhas de Produto]] 

## [[Manual de Integração#Marcas|Marcas]] 

## [[Manual de Integração#Vendas|Vendas]] 

## -[[Manual de Integração#Liquidez|Liquidez]]- (depreciado)

## [[Manual de Integração#Faturamento-Contrato|Faturamento - Contrato]]

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 suporte@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 |

| Cod Repres Agrupador | String   | 255        | ???  |

| telefone 2     | String   | 255        | Telefone de Contato 2 |

| telefone 3     | String   | 255        | Telefone de Contato 3 |

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 |

| nomeDistrito       | String   | 255        | Nome da Cidade ou Distrito |

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 |

| cnpjCpf | String | 255 | CNPJ ou CPF do cliente |

| emailCobranca | String | 255 | Endereço de e-mail de cobrança |

| nomeDistrito       | String   | 255        | Nome do Distrito (para o caso de São Paulo, os bairros – para o caso de Brasília, os Distritos)

Se o seu sistema não tiver esta informação, retornar o bairro. |

| celular       | String   | 255        | Numero do Celular |

| inscricaoEstadual       | String   | 255        | Inscrição estadual do cliente |

| enderecoNumero       | String   | 255        | Número do endereço do cliente  |

| complemento       | String   | 255        | Complemento do endereço |

| IndicePontualidade       | Number   | 5,2       | Indice de Pontualidade. |

| telefone2       | String   | 255        | Telefone 2. Se não existir o campo, retornar null |

| telefoneCobranca       | String   | 255        | Telefone de cobrança. Se não existir o campo, retornar null |

| grupoCliente | String | 255 | Grupo Economico do Cliente (conforme regra de negócio de cada empresa). Se o seu ERP não tem isso, retornar null |

| codClientePrincipalGrupo | String | 255 | Código do cliente principal do Grupo Economico (conforme regra de negócio de cada empresa). Se o seu ERP não tem isso, retornar null |

| situacaoEdt     | String |   255       | Descrição da Situação |

| nomeGrupoCliente | String | 255 | Nome do Grupo Economico do Cliente (conforme regra de negócio de cada empresa). Se o seu ERP não tem isso, retornar null |

| flagInadimplente| Integer| | 0 - Não / 1 - Sim. Conforme regra da empresa. Não obrigatório para o IGS |

| cidade| String| | cidade do cliente |

| uf| String| | UF do cliente |

| nomeFantasia| String| | Nome Fantasia do cliente. Não obrigatório |

| ramoAtividade| String| | Descrição do Ramo de atividade do cliente. Não obrigatório. Se não tiver retornar null |

| dataPrimeiraCompra| Date| | Não obrigatório. Retornar apenas se for um campo fácil de ser buscado. Se não tiver retornar null |

| dataUltimaCompra| Date| | Não obrigatório. Retornar apenas se for um campo fácil de ser buscado. Se não tiver retornar null |

| maiorCompra| Double| | Retornar o valor da maior Compra do Cliente. Não obrigatório. Retornar apenas se for um campo fácil de ser buscado. Se não tiver retornar null |

| maiorAcumulado| Double| | Retornar o valor do maior Acumulo deste cliente. Não obrigatório. Retornar apenas se for um campo fácil de ser buscado. Se não tiver retornar null |

| codClienteERP| String |255| Codigo do cliente dentro do ERP. Retornar apenas se for um campo fácil de ser buscado. Caso contrário, retornar null. Geralmente, é o mesmo valor do campo  codCliente. |

| limiteCredito | Double | | Limite de crédito do cliente. |

| codRamoAtividade | String |255| Código do Ramo de atividade do cliente. Não obrigatório. Se não tiver retornar null. |

h2. Cliente e Prospect - Histórico

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

| dataAlteracao | Date |             | Data da Alteração | 

| horaAlteracao | Date  |           | Hora da Alteração |

| codUsuario     |  String | 255  | Código do Usuário |

| nomeUsuario  | String | 255  | Nome do usuário |

| situacao           | String | 255  | Código da Situação |

| situacaoEdt     | String | 255  | Descrição da Situação |

Lista de Parâmetros:

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

|  codEmpresa | :p1    | String          | 255           | Código da Empresa  |

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

h2. Marcas do Cliente

Tabela com a relação de marcas do cliente, conforme vendas.

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

| codEmpresa * | String | 255         | Código da Empresa origem dos dados |

| codCliente *    | String   | 255          | Codigo do Cliente |

| codMarca * | String   | 255          | Código da Marca |

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. Marcas

_Integração Opcional - Confirme com a IBTech a necessidade de criar esta integração._

Lista de marcas por empresa.

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

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

| codMarca *     | String  | 255        | Código da marca |

| nome      | String   | 255          | Nome da marca |

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 |

| dataPrevFaturamento | Date    |        | Data de Previsão de Faturamento |

| nomeDistrito *       | String   | 255        |  Nome do Distrito (para o caso de São Paulo, os bairros – para o caso de Brasília, os Distritos)

Se o seu sistema não tiver esta informação, retornar o bairro. |

| grupoCliente       | String   | 255        | Grupo Econômico do Cliente (conforme regra de negócio de cada empresa). Se o seu ERP não tem isso, retornar null |

| valorRentabilidade | Double   |            | Valor da Rentabilidade do Pedido. Se o seu ERP não tem rentabilidade por pedido, retornar null |

| dataUltFaturamento | Date   |            | Data do último faturamento |

| valorFaturado | Double   |            | Valor Faturado |

| valorSaldo | Double   |            | Valor Saldo |

| codMarca *       | String   | 255        | Código da Marca do Produto |

| nomeGrupoCliente | String | 255 | Descrição do Grupo do Cliente |

| dataEmissao | Date | | Data de Emissão do Pedido |

| codRepresAgrupador | String | 255 | Código do representante agrupador (atacado) |

| flagPolitica | Integer| | Pedido de acordo com a politica comercial (0 - não / 1 - sim) |

| codTabPreco | String | 255 | Código da Tabela de Preço |

| qtdeItens | Double | | Quantidade de Itens do Pedido |

| qtdeEmQuilos | Double | | Quantidade de Peças das Vendas em Quilos |

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.

A Liquidez resume-se a:

- O Valor a vencer no período e pago dividido pelo a vencer no período.

- Não entra no cálculo da Liquidez os títulos pagos fora do período de vencimento.

*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. Faturamento - Contrato

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

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

| qtdeFaturada | Double   |            | Quantidade Faturada |

| valorFaturado    | Double   |            | Valor Faturado |

Lista de Parâmetros:

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

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

| :p2     | String   | 10         | Data inicial para filtrar a emissão da nota fiscal |

| :p3        | String   | 10         | Data final para filtrar a emissão da nota fiscal |

| #COLECOES  | String   | 10         | Coleção da nota fiscal |

| #MARCAS       | String   | 10         | Marca da nota fiscal |

| #CORINGA1   | String   | 10         | Campo valores diversos, inicialmente retornar NULL - Ver com IBTech |

| #CORINGA2   | String   | 10         | Campo valores diversos, inicialmente retornar NULL - Ver com IBTech |

| #CORINGA3   | String   | 10         | Campo valores diversos, inicialmente retornar NULL - Ver com IBTech |