Manual de Integração¶

Envio de Duplicatas
Portal de Clientes - API
CRM
Digitação de Pedidos
Digitação de Pedidos - Imagens dos Produtos
Loja Virtual
Loja Virtual - Imagens
Loja Virtual - Pop ups
Loja Virtual - Estilos (Layout Personalizado)
Loja Virtual - Login Externo
Produção
Gestão de Cobrança
Gestão de Crédito

Índice

1. Introdução
2. Acesso via JDBC
3. Tabelas de Integração
   1. Representantes
   2. Municípios do Representante
   3. Clientes e Prospects
   4. Marcas do Cliente
   5. Coleções
   6. Linhas de Produto
   7. Marcas
   8. Vendas
   9. Liquidez (depreciado)
   10. Faturamento - Contrato
   11. Meta do Representante
   12. Meta do Escritório

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.

Atenção!! Os campos que estiverem com a descrição "Campo Específico" retornar null, salvo se for combinado algo diferente com a IBTech durante o processo.

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

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.

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

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	Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech
telefone 2	String	255	Telefone de Contato 2
telefone 3	String	255	Telefone de Contato 3
codigoAdministrador	String	255	Código do administrador do representante no erp
cnpj	String	255	CNPJ do representante
codAgrupadorEscritorio	String	255	Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech
flagAgrupadorMaster	Integer		0 - Não, 1 - Sim (Somente um por grupo) / Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech

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.
Atenção! Tabela não obrigatória. Retornar apenas se existir no ERP

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

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 no ERP.
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
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. Não Obrigatório
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. Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech
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 GeoVendas
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	Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech. 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.
codRamoAtividade	String	255	Código do Ramo de atividade do cliente. Não obrigatório. Se não tiver retornar null.
limiteCredito	Double		Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech. Limite de crédito do cliente.
ultimoFaturamento	Date
dataReativacao	Date
codSitCreditoERP	Integer	10
descSitCreditoERP	String	255
motivoInativo	String	255	Motivo cujo o qual o cliente foi inativado no ERP. Não obrigatório. Se não tiver retornar null

Cliente e Prospect - Histórico
Atenção! Tabela específica. Retornar apenas se for combinado algo com a IBTech¶

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

Marcas do Cliente
Atenção! Tabela específica. Retornar apenas se for combinado algo com a IBTech¶

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

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

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

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

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		Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech. Valor da Rentabilidade do Pedido. Se o seu ERP não tem rentabilidade por pedido, retornar null
dataUltFaturamento	Date		Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech. Data do último faturamento do Pedido. Retornar apenas se for uma informação fácil
valorFaturado	Double		Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech. Valor já Faturado do pedido
valorSaldo	Double		Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech. 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	Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech. Código do representante agrupador (atacado)
flagPolitica	Integer		Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech. Pedido de acordo com a politica comercial (0 - não / 1 - sim)
codTabPreco	String	255	Código da Tabela de Preço
qtdeItens	Double		Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech. Quantidade de Itens do Pedido
qtdeEmQuilos	Double		Campo Específico. Retornar null , salvo alguma orientação diferente da IBTech. Quantidade de Peças das Vendas em Quilos

Liquidez (Deprecated)¶

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.

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

Faturamento - Contrato
Atenção! Tabela específica. Retornar apenas se for combinado algo com a IBTech¶

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
#LINHAS	String	10	Linha 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

Meta do Representante
Atenção! Tabela específica. Retornar apenas se for combinado algo com a IBTech¶

Campo	Tipo	Precisão	Descrição
codEmpresa *	String/Integer	255	Código da empresa
codColecao *	String	255	Código da coleção no ERP.
codMarca	String	255	Código da marca no ERP.
codRepres *	String/Integer	255	Código do Representante no ERP
metaValor	Double		Meta em valor do representante
metaQtde	Double		Meta em quantidade do representante
metaPrazoMedio	Double		Meta em prazo médio do representante

Meta do Representante - Linha de Produto
Atenção! Tabela específica. Retornar apenas se for combinado algo com a IBTech¶

Campo	Tipo	Precisão	Descrição
codEmpresa *	String/Integer	255	Código da empresa
codColecao *	String	255	Código da coleção no ERP.
codMarca	String	255	Código da marca no ERP.
codRepres *	String/Integer	255	Código do Representante no ERP
codLinha	Double		Código da linha de produto no ERP.
percMeta	Double		Percentual de representatividade da linha sobre a meta geral

Meta do Escritório
Atenção! Tabela específica. Retornar apenas se for combinado algo com a IBTech¶

Campo	Tipo	Precisão	Descrição
codEmpresa *	String/Integer	255	Código da empresa
codColecao *	String	255	Código da coleção no ERP.
codMarca	String	255	Código da marca no ERP.
codEscritorio *	String/Integer	255	Código do escritório de representação no ERP
metaValor	Double		Meta em valor do escritório
metaQtde	Double		Meta em quantidade do escritório
metaPrazoMedio	Double		Meta em prazo médio do escritório

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
#LINHAS	String	10	Linha 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

Valores para Cálculo Desconto Fidelidade Acumulativa¶

Deve retornar o valor total somado, agrupado por cliente e data a ser considerada para o cálculo de desconto acumulativo por cliente
Parâmetro obrigatório :p1 e :p2, codEmpresa e data limite cujo a qual o sistema irá considerar os registros para cálculo, ultima dia do mês anteiror ao calculo. os vide exemplo abaixo.

Campo	Tipo	Precisão	Descrição
data	Date		Data vigente da compra, dependendo do cliente pode ser considerada a data de emissão, de faturamento
codCliente	Varchar	255	Código do cliente
valor	Double		Valor somado por cliente e data

Ex:

SELECT DataEmissao,
codCliente,
SUM(valorBruto)
FROM (
select date_trunc('month', dataEmissao) DataEmissao,
codCliente, 
valorBruto
FROM ETLPedido pedido
WHERE pedido.codEmpresa = :p1
AND pedido.dataEmissao<=:p2) Pedidos
GROUP BY DataEmissao,codCliente
ORDER BY codCliente, DataEmissao DESC