INTRODUÇÃO
Este documento tem por objetivo disponibilizar layout de arquivos para integração de dados entre a plataforma de E-Commerce Chleba e seus parceiros. O modelo de integração vai ser por WebService, fazendo autenticação e passando o modelo XML Este documento contempla layout dos seguintes arquivos de dados:
- Situação dos pedidos – Status de pedidos no parceiro
- Arquivo de Produtos
- Pedidos gerados
WEBSERVICE
O modelo tem por objetivo fazer autenticação no sistema e será consumido pelo sistema do parceiro.
LINK DE ACESSO AO EXEMPLO:
Integração
USUÁRIO PARA AUTENTICAÇÃO
Para efetuar os primeiros testes utilize o login e senha padrão do sistema.
Username = admin
Password = admin
MODELO DE RETORNO DE DADOS
Para cada método consumido o sistema vai responder no formato:
Exemplo de formato resposta de método
<?xml version='1.0' encoding='iso-8859-1' standalone='yes'?>"
<Parceiro>
<codigo><![CDATA[codigo]]</codigo>
<mensagem><![CDATA[mensagem]]</mensagem>
</Parceiro>
TABELA DE MENSAGENS
Os codigo-mensagem de retorno são:
Código (0 – Descrição do erro)
Código (1 - Login e/ou senha inválido(s))
Codigo (2 – Processado)
Exemplo de chamada no .NET
net.chleba.tecnologia.ServiceAuthHeader sah = new WebApplicationTeste.net.chleba.tecnologia.ServiceAuthHeader();
sah.UserName = "admin";
sah.Password = "admin";
net.chleba.tecnologia.Integracao integracao = new WebApplicationTeste.net.chleba.tecnologia.Integracao();
integracao.ServiceAuthHeaderValue = sah;
string retorno = integracao.IntegracaoProdutos("<xml><Parceiro>teste</Parceiro><xml>");
MÉTODOS QUE COMPÕE O WEBSERVICE
AtualizaStatusPedido › Atualização dos status dos pedidos. O parceiro deve enviar no formato XML os dados de integração.
IntegracaoProdutos › Publicação e atualização dos produtos na loja. O parceiro deve enviar no formato XML os dados de integração.
RecuperaPedidos › Recupera os pedidos da loja passando a data inicial e final. O WebService vai retornar no formato XML os dados de integração.
MÉTODOS DA API
AtualizaStatusPedido
Este método tem por objetivo integrar os dados dos status dos pedidos entre o sistema do parceiro e a loja virtual. Este arquivo será fornecido pelo parceiro, para que o sistema da loja possa consumir os dados fornecidos no formato do arquivo apresentado abaixo.
EXEMPLO DE ARQUIVO XML
<?xml version="1.0" encoding="iso-8859-1" ?>
<loja nome="LojaParceiro" codigo="1">
<pedidos>
<pedido order_id="1" idstatus="1" datastatus="2000-11-12 15:50" idtransporte="1656565" motivocancelamento="loremloremlorem" />
</pedidos>
</loja>
ESTRUTURA DO ARQUIVO XML
Campo |
Tamanho |
Observação |
| Informações do pedido | ||
| order_id | Inteiro | Identificação do pedido no sistema da loja virtual. |
| idstatus | Char(02) | Neste campo deve ser informado o status do pedido no lojista. Abaixo segue uma tabela com os possíveis Status que a loja disponibiliza. |
| datastatus | Date | Data que a o status foi mudado no sistema do parceiro e consequentemente será informado na loja, pois algumas consultas de pedidos leva em consideração esta data. O formato da data é: “yyyy-MM-dd hh:mm”. |
| idtransporte | Char(50) | Neste campo, o parceiro poderá enviar a identificação da compra da transportadora ou correios, para o cliente consultar e acompanhar o andamento da entrega da compra. |
| motivoCancelamento | Char(255) | Quando um determinado pedido for cancelado, ele deverá ser informado o motivo do cancelamento. * Só deverá ser usado, caso o pedido em questão estiver com status cancelado. |
IntegracaoProdutos
Este método tem por objetivo integrar os dados dos produtos entre o sistema do parceiro e a loja virtual.
Este arquivo será fornecido pelo parceiro, para que o sistema da loja possa consumir os dados fornecidos no formado do arquivo apresentado abaixo.
O link definitivo de acesso ao arquivo ou a disponibilização de uma área para upload do arquivo na loja será definido no momento que iniciar a operação de integração.
ESTRUTURA DO ARQUIVO XML:
Abaixo estão descritos informações da tabela de departamentos, atributos, itens de atributos e de produtos.
Estas tabelas em conjunto, montam o arquivo de produtos.
ESTRUTURA DA TABELA DE DEPARTAMENTOS
Campo |
Tamanho |
Observação |
| Informações do departamento | ||
| nome | Char(100) | Nome do departamento. Campo obrigatório. |
| codigo | Char(100) | Identificação do departamento. Campo obrigatório. |
| Informações das categorias do departamento | ||
| nome | Char(100) | Nome da categoria pertencente a um departamento. Campo obrigatório. |
| codigo | Char(100) | Identificação da categoria. Campo obrigatório. |
ESTRUTURA DA TABELA DE ATRIBUTOS:
| Informações dos atributos | ||
Campo |
Tamanho |
Observação |
| atributo_id | inteiro | Identificação do atributo. Campo obrigatório. |
| nome | Char(50) | Nome do atributo do produto. (Ex: Cor, Tamanho, Voltagem). Campo obrigatório. |
ESTRUTURA DA TABELA DE ITENS DE ATRIBUTOS:
Campo |
Tamanho |
Observação |
| Informações dos itens dos atributos | ||
| atributoitem_id | inteiro | Identificação do item do atributo. Campo obrigatório. |
| atributo_id | inteiro | Identificação atributo. Campo obrigatório. |
| nome | Char(255) | Nome do atributo do produto. Exemplo: Azul (Item do Atributo cor). Campo obrigatório. |
ESTRUTURA DA TABELA DE PRODUTOS:
Campo |
Tamanho |
Observação |
| Informações do produto | ||
| CodigoProduto | Char(15) | Identificação do produto no parceiro. Campo obrigatório. |
| SKU | Char(100) | Identificação do produto no Fabricante. Campo obrigatório. |
| Fabricante | Char(100) | Nome do fabricante. Campo obrigatório. |
| modeloFabricante | Char(100) | Modelo do produto no fabricante. Campo obrigatório. |
| descricao | Char(2000) | Descrição do produto. Campo obrigatório. |
| fichaTecnica | Char(2000) | Ficha técnica do produto, ou seja, uma descrição detalhada e técnica do produto. Campo obrigatório. |
| pesoProduto | Inteiro | Peso do produto sem embalagem. Campo obrigatório. |
| precoNormal | Decimal(18,2) | Preço do produto. Campo obrigatório. |
| precoPromocao | Decimal(18,2) | Preço do produto em promoção. Caso o produto não esteja em promoção, deve ser informado o preço normal do produto. Na apresentação de produtos na loja, caso o preço do produto seja diferente do preço de promoção, então será apresentado a informação De >> Por. Campo obrigatório. |
| largura | Decimal(6,2) | Largura do produto. Campo opcional. |
| altura | Decimal(6,2) | Altura do produto. Campo opcional. |
| profundidade | Decimal(6,2) | Profundidade do produto. Campo opcional. |
| larguraemb | Decimal(6,2) | Largura da embalagem do produto. Campo opcional. |
| alturaemb | Decimal(6,2) | Altura da embalagem do produto. Campo opcional. |
| profundidadeemb | Decimal(6,2) | Profundidade da embalagem do produto. Campo opcional. |
| Informações do departamento onde o produto será publicado na loja | ||
| cod_depto | inteiro | Neste campo deverá vir o código do departamento, que irá remeter para a tabela de departamento que também deve vir mapeada no arquivo XML, conforme descrito na tabela de departamentos. Campo obrigatório. |
| cod_secao | inteiro | Neste campo deverá vir o código da categoria, que irá remeter para a tabela de departamento que também
deve vir mapeada no arquivo XML, conforme descrito na tabela de departamentos / categorias. Campo obrigatório. |
| Informações de modelos do produto | ||
| item | inteiro | Neste campo deverá vir um identificador de modelos do produto. Campo obrigatório. |
| CodigoProdutoModelo | Char(100) | Identificação única do produto no Fabricante. Campo obrigatório. |
| Estoque | Inteiro | Quantidade em estoque do produto filho. Campo obrigatório. |
| atributoitem_id | inteiro | Neste campo deverá vir o código dos atributos que compõe cada modelo do produto. Exemplo: O produto é uma geladeira branca, com tamanho grande de 350 litros e com voltagem 110. Então para este produto será enviado 3 atributos. um para identificar a cor, outro para identificar o tamanho e outro para identificar a voltagem. Para o sistema da loja localizar estes atributos, será usado a tabela de atributos e itens descritos acima. Campo obrigatório. |
Exemplo de arquivo XML
<?xml version="1.0" encoding="iso-8859-1"?>
<loja nome="iGEletro" codigo="1">
<departamentos>
<departamento nome="CINE E FOTO" codigo="01">
<secao nome="Câmeras Digitais - Até 1 Megapixel" codigo="010404"/>
<secao nome="Câmeras Digitais - De 1 a 1.9 Megapixels" codigo="010408"/>
</departamento>
<departamento nome="ELETRÔNICOS" codigo="02">
<secao nome="DVD - DVD Player" codigo="020404"/>
<secao nome="DVD - Filmes" codigo="020408"/>
<secao nome="Home theater" codigo="0208"/>
</departamento>
</departamentos>
<atributos>
<atributo atributo_id="1" nome="Cor"/>
<atributo atributo_id="2" nome="Voltagem"/>
<atributo atributo_id="3" nome="Tamanho"/>
<atributo atributo_id="17" nome="Modelo"/>
<atributo atributo_id="20" nome="Numeração"/>
<atributo atributo_id="21" nome="Polegadas"/>
</atributos>
<atributoitens>
<atributoitem atributoitem_id="5" atributo_id="3" nome="P"/>
<atributoitem atributoitem_id="6" atributo_id="3" nome="M"/>
<atributoitem atributoitem_id="19" atributo_id="1" nome="Preto"/>
</atributoitens>
<produtos>
<produto CodigoProduto="02647" SKU="CodigoProdutoNoFabrincante"
Fabricante="ICONCEPTS" modeloFabricante="xxxxxxx"
descricao="descrição do produto." pesoProduto=" 0.000" preco="28.70" precoPromocao="28.70"
largura="1.00" altura="1.00" profundidade="1.00" larguraemb="7.40"
alturaemb="16.30" profundidadeemb="1.50" prazoentrega="0" >
<local cod_depto="04" cod_secao="04041212"/>
<modelos>
<modelo item="1" CodigoProdutoModelo=”XXX” estoque=”10”>
<atributo atributoitem_id="55"/>
<atributo atributoitem_id="19"/>
</modelo>
<modelo item="2" CodigoProdutoModelo=”YYY” estoque=”10”>
<atributo atributoitem_id="55"/>
<atributo atributoitem_id="20"/>
</modelo>
<modelo item="3" CodigoProdutoModelo=”ZZZ” estoque=”10”>
<atributo atributoitem_id="56"/>
<atributo atributoitem_id="20"/>
</modelo>
</modelos>
</produto>
</produtos>
</loja>
<!--Copyright 2013 Chleba Marketing Interativo - Todos os Direitos Reservados ¿?-->
RecuperaPedido
Layout do arquivo de pedidos, itens de pedidos, clientes e endereço de entrega:
Este arquivo tem por objetivo integrar os dados dos pedidos, itens do pedido (produto(s) comprado pelo cliente), informações do cliente, assim como dados do endereço do cliente e o endereço de entrega, entre a loja virtual e o sistema do parceiro.
Este arquivo será fornecido pela loja e será consumido pelo sistema de integração do parceiro.
Desta forma, o parceiro deve se adequar para consumir os dados fornecidos no formado do arquivo apresentado abaixo.
ESTRUTURA DO ARQUIVO XML:
Campo |
Tamanho |
Observação |
| Informações do Pedido | ||
| order_id | Inteiro | Identificação do pedido na loja. |
| dataVenda | Date | Data que a venda foi realizada na loja. O formato da data é: “yyyy-MM-dd hh:mm” |
| Transportadora | Char(01) | Os valores deste campo São: S: Sedex; E: E-Sedex; *Caso o parceiro tenha outra forma de entrega, é necessário conversar com a pessoa responsável pela integração dos dados na Chleba para que combinem quais serão os valores enviados para outras formas de entregas. |
| FormaPagamento | Char(02) | Neste campo enviamos a forma de pagamento do pedido. Os valores previamente enviados neste campo são: 1: Itau 5: Bradesco 6: MasterCard 7: Visa 8: Hipercard 9: Aura 10: Diners Club 11: Caixa 12: HSBC 13: Banco do Brasil 14: ABN Amro Real 15: Citibank 16: Unibanco 17: Boleto * * Caso o parceiro já tenha uma tabela de valores e queira que seja enviado estes valores que ele já possui, deve ser conversado com o responsável pela integração na chleba, para verificar a possibilidade de alteração dos valores acima e conseqüentemente enviado outros valores. *Caso o parceiro tenha outra forma de pagamento, deve ser combinado com o responsável pela integração na chleba, para combinarem os valores a serem enviados. |
| Parcelas | Char(02) | Neste campo vai o total de parcelas que o cliente parcelou a compra. Caso seja pagamento á vista, vai o valor 1. |
| ValorFrete | Decimal(18,2) | Neste campo vai o valor do frete pago pelo cliente. |
| SubTotalCompra | Decimal(18,2) | Neste campo vai o valor da compra (sem inclusão do valor do frete e com desconto, caso tenha) pago pelo cliente. |
| Valorcompra | Decimal(18,2) | Neste campo vai o valor total da compra pago pelo cliente (inclui o valor do frete e já com o desconto calculado, caso tenha). |
| PorcentagemDesconto | Decimal(18,2) | Neste campo vai o desconto da compra caso a mesma tenha desconto. Se não tem desconto, o valor enviado é 0. |
| Informações do Cliente | ||
| TipoPessoa | Char(01) | Neste campo será informado se o cliente é pessoa Física “F” ou Jurídica “J”. |
| CPFCNPJ | Char(20) | Neste campo será enviado o CPF, caso seja pessoa física ou o CNPJ do cliente, caso seja pessoa jurídica. |
| ClienteNome | Char(100) | Neste campo será enviado o nome, caso seja pessoa física ou a Razão social do cliente, caso seja pessoa jurídica. |
| InscRg | Char(10) | Neste campo será enviado o RG, caso seja pessoa física ou a Inscrição estadual do cliente, caso seja pessoa jurídica. |
| Char(100) | Neste campo será informado o e-mail do cliente. | |
| DTNasc | Char(10) | Neste campo será a data de nascimento do cliente, caso seja pessoa física. Caso seja pessoa jurídica, este campo vai em branco |
| Sexo | Char(01) | Neste campo será informado o sexo do cliente, caso o cliente seja pessoa física. Caso seja pessoa jurídica, informaremos o valor M. Os valores enviados podem ser: M: masculino; F: Feminino; |
| Informações e endereço de entrega do Cliente | ||
| tipoEndereco | Char(01) | Neste campo será informado se o endereço é do cliente ou é o endereço de entrega. Os valores deste campo são: C: Endereço do cliente; E: Endereço de entrega da compra; * Caso o endereço de entrega seja o mesmo endereço do cliente, mesmo assim será enviado dois registros (um identificando cliente e outro a entrega). |
| Nome | Char(100) | Neste campo será enviado o nome do destinatário cadastrado no endereço. Caso o endereço seja do próprio cliente, o nome vai em branco. |
| CEP | Char(08) | Neste campo será enviado o CEP do endereço |
| Endereco | Char(100) | Neste campo será enviado o endereço em questão. |
| Numero | Char(10) | Neste campo será enviado o número do endereço. |
| Complemento | Char(50) | Neste campo será enviado o complemento do endereço. |
| Bairro | Char(100) | Neste campo será enviado o bairro do endereço. |
| Cidade | Char(50) | Neste campo será enviado o nome da cidade do endereço. |
| UF | Char(02) | Neste campo será enviado o Estado do endereço. |
| DDDRes | Char(02) | Neste campo será enviado o DDD do telefone residencial. * Caso o DDD não tenha sido informado, será enviado em branco. * pode não ser informado o DDD para o endereço de entrega. |
| FoneRes | Char(15) | Neste campo será enviado o telefone residencial. * Caso o telefone residencial não tenha sido informado, será enviado em branco. * pode não ser informado o telefone para o endereço de entrega. |
| DDDCom | Char(02) | Neste campo será enviado o DDD do telefone comercial. * Caso o DDD não tenha sido informado, será enviado em branco. * pode não ser informado o DDD para o endereço de entrega. |
| FoneCom | Char(15) | Neste campo será enviado o telefone comercial. * Caso o telefone comercial não tenha sido informado, será enviado em branco. * pode não ser informado o telefone para o endereço de entrega. |
| Informações de itens de pedido (produtos e modelo do produto) | ||
| CodigoProduto | Char(15) | Identificação do produto no parceiro. |
| QTDE | Inteiro | Neste campo será enviado a quantidade de itens que o cliente comprou do produto em questão. |
| ValorUnitario | Decimal(18,2) | Neste campo será enviado o valor unitário do produto. |
| Atributoitem_id | Char(5) | Identificação do modelo do produto. Exemplo: O produto é uma geladeira branca, com tamanho grande de 350 litros e com voltagem 110. Então para este produto será enviado 3 atributos. um para identificar a cor, outro para identificar o tamanho e outro para identificar a voltagem. * O parceiro deve entrar em contato com o responsável pela integração na Chleba, para combinarem os códigos que serão enviados para identificação dos atributos do produto. |
EXEMPLO DE ARQUIVO XML
<?xml version="1.0" encoding="iso-8859-1"?>
<loja nome="LojaParceiro" codigo="1">
<pedidos>
<pedido order_id ="3175" Transportadora="S" FormaPagamento="6"
Parcelas="1" ValorFrete="4.50" SubTotalCompra="49.78" Valorcompra="54.28"
PorcentagemDesconto="5" dataVenda=”2013-05-15” >
<cliente TipoPessoa="F" CPFCNPJ="00000000000" ClienteNome="Marcio Chleba"
InscRg="00000000" Email="[email protected]" DTNasc="1980-10-20" Sexo="M">
<endereco>
<enderecoItem tipoEndereco="C" Nome=" Marcio Chleba "
CEP="80030001" Endereco="Av. João Gualberto"
Numero="1259" Complemento="19 andar" Bairro="Juveve"
Cidade="Curitiba" UF="PR" DDDRes="41"
FoneRes="33236985" DDDCom="41" FoneCom="33139380"/>
<enderecoItem tipoEndereco="E" Nome=" Marcio Chleba"
CEP="80030001" Endereco="Av. João Gualberto"
Numero="1259" Complemento="19 Andar" Bairro="Juveve"
Cidade="Curitiba" UF="PR" DDDRes="41"
FoneRes="33236985" DDDCom="41" FoneCom="33139380"/>
</endereco>
</cliente>
<pedidoItens>
<pedidoItem CodigoProduto ="02647" QTDE="1" CodigoProdutoModelo=”YYYYY” ValorUnitario="28.70">
<modelo>
<atributo Atributoitem_id="55"/>
<atributo Atributoitem_id="20"/>
</modelo>
</pedidoItem>
<pedidoItem CodigoProduto ="1024" CodigoProdutoModelo=”XXXXXX” QTDE="1" ValorUnitario="23.70">
<modelo>
<atributo Atributoitem_id="55"/>
<atributo Atributoitem_id="33"/>
</modelo>
</pedidoItem>
</pedidoItens>
</pedido>
</pedidos>
</loja>
<!--Copyright 2011 Chleba Marketing Interativo - Todos os Direitos Reservados ¿?-->