Visão geral
O Magento é uma plataforma open-source para criação/desenvolvimento de lojas virtuais. O Magento é construído em cima de um framework PHP que pode ser explorado para desenvolver aplicações e adpatações dinâmicas, conforme a necessidade da loja do seu cliente.
Estrutura em Módulos
O magento possui seu código organizado em módulos individuais, onde seus arquivos são agrupados por suas funcionalidades. Para cada módulo existe uma pasta específica. Por exemplo:
1 app / code / core / Sales /
Para cada novo módulo criado, deve-se notificar sobre isso. Este procedimento é realizado inserindo um arquivo XML na pasta:
1 app / etc / modules
Criação de atributos personalizados de produto
Na plataforma Magento é possível criar atributos específicos para o produto. Esses atributos podem ser dos seguintes tipos:
- Campo texto (Text Field)
- Área de texto (Text Area)
- Data (Date)
- Sim/Não (Yes/No)
- Múltiplas seleções (Multiple Select)
- Select (Dropdown)
- Preço (Price)
- Imagem (Media Image)
- Taxa Adicional (Fixed Product Tax)
Para criação de atributos do produto, deve-se:
- Acessar o painel administrativo, na opção: Catalog -> Attributes -> Manage Attribute Sets ou na opçãoCatálogo -> Atributos -> Gerenciar Grupo de Atributos, caso a loja tenha sido traduzida.
- Depois de criado/configurado o atributo, deve-se realizar a associação do atributo ao Grupo de Atributos, através da opção Catalog > Attributes > Manage Attribute Sets ou Catálogo > Atributos > Gerenciar Grupo de Atributos.
Criação do atributo NCM no produto
NCM é um código de classificação fiscal das mercadorias, obrigatório no envio da Nota Fiscal. Porém, a plataforma magento não possui este campo no cadastro de produtos, sendo necessário a criação.
Para criar o atributo NCM, deve-se seguir os passos 1 e 2, da seção 1 - Criação de atributos personalizados de produto acima neste manual.
Na aba Manage Label/Options, deve adicionar uma descrição para o rótulo deste atributo.
Em seguida, deve-se realizar a associação deste atributo ao grupo de atributos, clicando no atributo recém criado e arrastando para o grupo General ou para um grupo de sua preferência.
Depois de realizado este procedimento, deve-se adicionar em sua conta Bling, a identificação do atributo criado, ou seja, o Attribute Code, através da opção:
Preferências -> Integrações -> Configurações de integração com Magento -> Configurações Opcionais -> Campos Personalizados -> Produto -> NCM
Criação de atributos de endereço
Atualmente, o magento não possuí alguns campos de endereço por padrão, como o de número, complemento e bairro, o que faz, muitas vezes, optar-se pela instalação de módulos que os incluam. Porém, não é necessário instalar nenhum módulo para ter estes campos, basta apenas realizar algumas alterações na API do magento.
Para isso, primeiramente deve-se, por motivos de segurança, realizar uma cópia de segurança da loja magento e realizar todos os testes iniciais em ambiente de desenvolvimento(testes), seguindo as seguintes instruções:
1 - Altere para 4 (Quatro) o número de linha no campo de endereço, no painel administrativo da loja. Para isso, acesse: System -> Configuration -> Customers -> Customer Configuration -> Name and Address Options, e altere o campo Number of Lines in a Street Address para 4.
2 - Altere o arquivo de checkout billing.phtml. Para isso abra para edição o arquivoapp/design/frontend/base/default/template/persistent/checkout/onepage/billing.phtml.
Procure pelo seguinte trecho de código:
1 for ($_i = 2, $_n = $this->helper('customer/address')->getStreetLines(); $_i <= $_n; $_i++):
Em seguida, entre o li class="wide" e o div class="input-box", insira o seguinte trecho de código:
1 <?php if($_i==2): ?>
2 <label for="billing:street2" class="required"><em>*</em><?php echo $this->__('Número') ?>
3 </label>
4 <?php elseif($_i==3): ?>
5 <label for="billing:street3" class="required"><em></em><?php echo $this->__('Complemento') ?>
6 </label>
7 <?php else: ?>
8 <label for="billing:street4" class="required"><em>*</em><?php echo $this->__('Bairro') ?>
9 </label>10<?php endif ?>
3 - Altere o arquivo de checkout shipping.phtml. Para isso abra para edição o arquivoapp/design/frontend/base/default/template/checkout/onepage/shipping.phtml.
Assim como no passo 2, insira o seguinte trecho de código:
1 <?php if($_i==2): ?>
2 <label for="shipping:street2" class="required"><em>*</em>
3 <?php echo $this->__('Número') ?></label>
4 <?php elseif($_i==3): ?>
5 <label for="shipping:street3" class="required"><em></em>
6 <?php echo $this->__('Complemento') ?></label>
7 <?php else: ?>
8 <label for="shipping:street4" class="required"><em>*</em>
9 <?php echo $this->__('Bairro') ?></label>
10 <?php endif ?>
4 - Altere o arquivo register.phtml. Para isso, abra o arquivoapp/design/frontend/base/default/template/persistent/customer/form/register.phtml para edição.
Da mesma forma, que os passos anteriores, insira o seguinte trecho de código.
1 <?php if($_i==2): ?>
2 <label for="billing:street2" class="required"><em>*</em>
3 <?php echo $this->__('Número') ?></label>
4 <label for="shipping:street2" class="required"><em>*</em>
5 <?php echo $this->__('Número') ?></label>
6 <?php elseif($_i==3): ?>
7 <label for="billing:street3" class="required"><em></em>
8 <?php echo $this->__('Complemento') ?></label>
9 <label for="shipping:street3" class="required"><em></em>
10 <?php echo $this->__('Complemento') ?></label>
11 <?php else: ?>
12 <label for="billing:street4" class="required"><em>*</em>
13 <?php echo $this->__('Bairro') ?></label>
14 <label for="shipping:street4" class="required"><em>*</em>
15 <?php echo $this->__('Bairro') ?></label>
16 <?php endif ?>
5 - Altere o arquivo edit.phtml.
Para isso abra para edição o arquivo app/design/frontend/base/default/template/customer/address/edit.phtml. Com este procedimento o usuário conseguirá realizar a edição dessas informações.
1 <?php if($_i==2): ?>
2 <label for="street2" class="required"><em>*</em><?php echo $this->__('Número') ?></label>
3 <?php elseif($_i==3): ?>
4 <label for="street3" class="required"><em></em><?php echo $this->__('Complemento') ?></label>
5 <?php else: ?>
6 <label for="street4" class="required"><em>*</em><?php echo $this->__('Bairro') ?></label>
7 <?php endif ?>
6 - Altere o arquivo info.phtml.
Para isso abra para edição o arquivo app/design/adminhtml/default/template/sales/order/view/info.phtml. Este procedimento possibilitará a visualização das informações da compra.
Primeiramente, altere as informações de cobrança (billing). Em seguida, procure pelo seguinte trecho de código:
1 <?php echo $_order->getBillingAddress()->getFormated(true) ?>
Substitua por:
1 <address><?php
2 $order = $this->getOrder();
3 $billing_address = $order->getBillingAddress();
5 echo "<font color='red'>Nome: </font> ".' '.ucwords(strtolower($billing_address->getFirstname())).' '.ucwords(strtolower($billing_address->getLastname()));
6 echo "<br>";
7 echo "<font color='red'>Endereço: </font> "." ".ucwords(strtolower($billing_address->getStreet(1))).", <font color='red'>N°</font> ".ucwords(strtolower($billing_address->getStreet(2)));
9 $complemento = $billing_address->getStreet(3);
11 if ($complemento == NULL) {
12 echo "<br>";
13 } else {
14 echo "<br>";
15 echo "<font color='red'>Complemento: </font> ".' '.ucwords(strtolower($billing_address->getStreet(3)));
16 echo "<br>";
17 }
19 echo "<font color='red'>Bairro: </font> ".' '.ucwords(strtolower($billing_address->getStreet(4)));
20 echo "<br>";
22 echo "<font color='red'>Cidade: </font> ".' '.ucwords(strtolower($billing_address->getCity()));
23 echo "<br>";
25 echo "<font color='red'>UF: </font> ".' '.$billing_address->getRegion().' '."<font color='red'>CEP: </font> ".' '.$billing_address->getPostcode();
26 echo "<br>";
27
28 echo "<font color='red'>Telefone: </font> ".' '.$billing_address->getTelephone();
29 echo "<br>";
30 echo "<font color='red'>Celular: </font> ".' '.$billing_address->getFax();
31 ?></address>
Em seguida, altere as informações de entrega (shipping).
Procure pelo seguinte trecho de código:
1 <?php echo $_order->getShippingAddress()->getFormated(true) ?>
Substitua por:
1 <address><?php
2 $order = $this->getOrder();
3 $shipping_address = $order->getShippingAddress();
5 echo "<font color='red'>Nome: </font> ".' '.ucwords(strtolower($shipping_address->getFirstname())).' '.ucwords(strtolower($shipping_address->getLastname()));
6 echo "<br>";
7 echo "<font color='red'>Endereço: </font> ".' '.ucwords(strtolower($shipping_address->getStreet(1))).', N° '.ucwords(strtolower($shipping_address->getStreet(2)));
8 $complemento = $shipping_address->getStreet(3);
10 if ($complemento == NULL) {
11 echo "<br>";
12 } else {
13 echo "<br>";
14 echo "<font color='red'>Complemento: </font> ".' '.ucwords(strtolower($shipping_address->getStreet(3)));
15 echo "<br>";
16 }
18 echo "<font color='red'>Bairro: </font> ".' '.ucwords(strtolower($shipping_address->getStreet(4)));
19 echo "<br>";
20 echo "<font color='red'>Cidade: </font> ".' '.ucwords(strtolower($shipping_address->getCity()));
21 echo "<br>";
22 echo "<font color='red'>UF: </font> ".' '.$shipping_address->getRegion().' '."<font color='red'>CEP: </font> ".' '.$shipping_address->getPostcode();
23 echo "<br>";
24 echo "<font color='red'>Telefone: </font> ".' '.$shipping_address->getTelephone();
25 echo "<br>";
26 echo "<font color='red'>Celular: </font> ".' '.$shipping_address->getFax();
27 ?></address>
Depois de realizado essas alterações, quando for realizado uma compra na loja magento,será possível visualizar todos os dados referente ao(s) endereço(s) do cliente.
Essas configurações/alterações foram realizadas em uma loja magento na versão 1.7, mas elas devem funcionar em versões superiores a essa. Essas alterações foram realizadas utilizando o tema padrão do magento. Sendo assim, para temas diferentes, o desenvolvedor da loja deverá realizar as adaptações necessárias, com base nesse manual. È altamente recomendável que seja realizado cópias de segurança da loja magento e que essas alterações sejam testadas em ambiente de testes para depois serem movidas para ambiente de produção. O Bling não se responsabiliza por qualquer erro que possa ser ocasionado.
Configurações de atributos personalizados de endereço na API de venda
Para que seja possível importar as informações de endereço: número, bairro e complemento, do cliente, pela importação de pedidos é necessário realizar algumas configurações na API do magento. Visto que, até a presente versão do magento não existem esses campos como padrão. Para isso, deve-se solicitar ao desenvolvedor de sua loja que realize as seguintes alterações:
1 - Abrir em modo de edição o arquivo Api.php, localizado na pasta principal de sua loja, em:app/code/core/Mage/Sales/Model/Order/Api.php
2 - Procurar pelo metódo info, e antes do return deste metódo, incluir o seguinte trecho de código:
1 $result['shipping_address']['numeroPersonalizado'] = $order->getShippingAddress()->getStreet(2);
2 $result['shipping_address']['complementoPersonalizado']= $order->getShippingAddress()->getStreet(3);
3 $result['shipping_address']['bairroPersonalizado'] = $order->getShippingAddress()->getStreet(4);
5 $result['billing_address']['numeroPersonalizado'] = $order->getBillingAddress()->getStreet(2);
6 $result['billing_address']['complementoPersonalizado'] = $order->getBillingAddress()->getStreet(3);
7 $result['billing_address']['bairroPersonalizado'] = $order->getBillingAddress()->getStreet(4);
3 - Para que o Bling consiga capturar as informações de endereço do cliente, deve-se adicionar a identificação do indíce nas configurações de integração com o magento, através de Preferências -> Integrações -> Configurações de integração com o magento -> Configurações Opcionais -> Campos Personalizados. Preenchendo os campos bairro, número e complemento, baseado no exemplo, respectivamente, com as informações: bairroPersonalizado, complementoPersonalizado e numeroPersonalizado.
4 - Deve-se definir o tipo de endereço do cliente que será importado. Esta configuração é realizada em: Preferências -> Integrações -> Configurações de integração com o magento -> Configurações Opcionais -> Pedidos -> Endereço do Cliente.
OBS: É importante ressaltar que as informações de endereço podem variar de loja para loja. Por isso, é de suma responsabilidade do desenvolvedor da loja verificar as posições corretas a serem passadas para as chamadas desses dados, através do metódo getStreet(). O exemplo descrito, refere-se quando as informações complementares de endereço(bairro, complemento e número) são utilizadas como 2°, 3° e 4° linha do campo Street Address do cliente no painel administrativo da loja magento.
Caso não possua todos os campos de endereço (Número, Bairro e Complemento), consulte a seção 3 - Criação de atributos de endereço acima.
Configurações de atributos personalizados de endereço na API de cliente
Para que seja possível importar as informações de endereço do cliente: número, bairro e complemento, pela importação de contatos é necessário realizar algumas configurações na API do magento.
Para isso, o desenvolvedor responsavél pela loja deve realizar as seguintes alterações:
1 - Abrir em modo de edição o arquivo Api.php, localizado na pasta principal de sua loja, em:app/code/core/Mage/Customer/Model/Customer/Api.php.
2 - Procurar pelo metódo items, e antes do return deste metódo, antes do seguinte trecho de código:
1 $result[] = $row;
Em seguida, deve-se inserir o seguinte trecho de código:
1 $clientData = Mage::getModel('customer/customer')->load($row["customer_id"]);
3 // Cobrança
4 $billingAddress = Mage::getModel('customer/address')->load($clientData->default_billing);
5 $aBilling = $billingAddress ->getData();
6 $strBilling = $aBilling["street"];
7 $addressBilling = preg_split ('/$\R?^/m', $strBilling);
9 // Entrega
10 $shippingAddress = Mage::getModel('customer/address')->load($clientData->default_shipping);
11 $aShipping = $shippingAddress ->getData();
12 $strShipping = $aShipping["street"];
13 $addressShipping = preg_split ('/$\R?^/m', $strShipping);
15 $row['shipping_address']['numeroPersonalizado'] = $addressShipping[1];
16 $row['shipping_address']['bairroPersonalizado'] = $addressShipping[2];
17 $row['shipping_address']['complementoPersonalizado'] = $addressShipping[3];
19 $row['billing_address']['numeroPersonalizado'] = $addressBilling[1];
20 $row['billing_address']['bairroPersonalizado'] = $addressBilling[2];
21 $row['billing_address']['complementoPersonalizado'] = $addressBilling[3];
3- Para que o Bling consiga capturar as informações de endereço do cliente(Cobrança/Entrega), deve-se adicionar o attribute code nas configurações de integração com o magento, através de Preferências -> Integrações -> Configurações de integração com o magento -> Configurações Opcionais -> Campos Personalizados. Preenchendo os campos bairro, número e complemento, baseado no exemplo, respectivamente, com as informações: bairroPersonalizado, complementoPersonalizado e numeroPersonalizado. Esse procedimento é igual ao realizado no item 3 da seção Configurações de atributos personalizados de endereço na API de venda, ou seja, se este passo já foi realizado não será necessário fazê-lo novamente.
4 - Para que o Bling consiga importar as informações de contato corretamente, é necessário que as informações de endereço(Entrega/Cobrança) no cadastro do cliente na loja magento estejam marcadas como Default Billing Address e Default Shipping Address. Com isso, será possível enviar as informações corretas para o cadastro de cliente do Bling, através daImportação de Contatos do Magento.
Configurações do CPF/CNPJ do cliente na API de venda
Para que seja possível importar o campo referente ao CPF/CNPJ do cliente, através da integração de pedidos do magento, é preciso que esta informação seja incluída no campo customer_taxtvat. Visto que, o sistema Bling utiliza a informação contida neste campo para a identificação do CPF/CNPJ do cliente. De acordo com o tamanho desse registro, é definido o Tipo de Pessoa.
Para isso, o desenvolvedor responsavél pela loja deve realizar as seguintes alterações:
- Abrir em modo de edição o arquivo Api.php, localizado na pasta principal de sua loja, em:app/code/core/Mage/Sales/Model/Order/Api.php
- Procurar pelo metódo info, e antes do return deste metódo, adicionar o seguinte trecho de código
1 $result['customer_taxvat'] = $result['shipping_address']['cpfcnpj'];
Onde, $result['shipping_address']['cpfcnpj']; deve ser trocado pelo campo utilizado para armazenamento da informação do cpf/cnpj do cliente.
Configurações do RG e IE do cliente na API de venda
Para que seja possível importar o campo referente ao RG do cliente e/ou Inscrição Estadual, através da integração de pedidos do magento, é preciso que esta informação seja incluída na API do magento.
Para isso, o desenvolvedor responsavél pela loja deve realizar as seguintes alterações:
- Abrir em modo de edição o arquivo Api.php, localizado na pasta principal de sua loja, em: app/code/core/Mage/Sales/Model/Order/Api.php
- Procurar pelo metódo info, e antes do return deste metódo, adicionar o seguinte trecho de código:
1 // RG
2 $result['rg_personalizado'] = $result['billing_address']['rg'];
4 // IE
5 $result['ie_personalizado'] = $result['billing_address']['ie'];
Onde:
- $result['billing_address']['rg'], deve ser trocado pelo campo utilizado para armazenamento da informação do RG do cliente;
- $result['billing_address']['ie'], deve ser trocado pelo campo utilizado para armazenamento da informação do IE do cliente;
Configurações do Número do Boleto na API de venda
Para que seja possível importar o campo referente ao Número do Boleto gerado, através da integração de pedidos do magento, é preciso que esta informação seja incluída no campo numeroBoleto dentro do índice payment. Visto que, o sistema utiliza a informação contida neste campo para a identificação do número do boleto.
Para isso, o desenvolvedor responsavél pela loja deve realizar as seguintes alterações:
- Abrir em modo de edição o arquivo Api.php, localizado na pasta principal de sua loja, em: app/code/core/Mage/Sales/Model/Order/Api.php
- Procurar pelo metódo info, e antes do return deste metódo, adicionar o seguinte trecho de código
$result['payment']['numeroBoleto'] = "9999999999";
Onde, 9999999999 deve ser trocado pelo campo utilizado para armazenamento da informação do número do boleto.
Mapeamento de Campos Personalizados
São chamados de Campos Personalizados, aqueles campos que não existem por padrão na plataforma magento. Estes campos são comumente adicionados na loja para complementar determinado cadastro, extendendo e adaptando esta para que possa ser utilizada em diversas e diferentes áreas do negócio do seu cliente.
O Bling faz um mapeamento de determinados campos que possuem equivalência com os cadastros atuais do sistema, ou seja, para alguns campos existente no Bling, é possível adicionar um respectivo no magento e realizar um mapeamento destes, para que estes campos sejam interpretados e importados para o sistema.
Este mapeamento pode ser visualizado, através da seguinte tabela:
Campos Personalizados
|
Grupo Magento |
Nome Bling |
Descrição |
|
Vendas/Sales |
Endereço do Cliente |
Tipo do endereço a ser considerado (Shipping|Billing). |
|
Vendas/Sales |
Bairro |
Campo personalizado para o campo bairro do endereço do cliente. |
|
Vendas/Sales |
Número |
Campo personalizado para o campo número do endereço do cliente. |
|
Vendas/Sales |
Complemento |
Campo personalizado para o campo complemento do endereço do cliente. |
|
Vendas/Sales |
Inscrição Estadual |
Campo personalizado para o campo inscrição estadual do cliente. |
|
Vendas/Sales |
RG |
Campo personalizado para o campo RG do cliente. |
|
Vendas/Sales |
CPF/CNPJ do Cliente |
Campo personalizado para o campo CPF/CNPJ do cliente. |
|
Produto/Product |
NCM |
Campo personalizado para o campo NCM do produto. |
|
Produto/Product |
Altura |
Campo personalizado para o campo altura do produto. |
|
Produto/Product |
Largura |
Campo personalizado para o campo largura do produto. |
|
Produto/Product |
Profundidade |
Campo personalizado para o campo profundidade do produto. |
|
Produto/Product |
Peso Líquido |
Campo personalizado para o campo peso líquido do produto. |
|
Produto/Product |
EAN |
Campo personalizado para o campo EAN do produto. |
|
Produto/Product |
Estoque Mínimo |
Campo personalizado para o campo estoque mínimo do produto. |
|
Produto/Product |
Unidade |
Campo personalizado para o campo unidade do produto. |
|
Produto/Product |
Observacoes |
Campo personalizado para o campo observacoes do produto. |
Problemas e Soluções
|
Problema |
Causa Provável |
Solução |
|
failed to load external entity |
|
|
|
Erro 9 |
|
|
|
Erro 50 |
|
|
|
Acess Denied (no teste da configuração de integração) |
|
|
|
Acess Denied (Durante uma operação. Ex: Importação de pedidos) |
|
|
|
Não importa campos de endereço (Número, bairro e complemento) através da importação de pedidos |
|
|
|
looks like we got no XML document |
|
|
|
Could not connect to host |
|
|
|
XML declaration allowed only at the start of the document |
|
|
|
DTD are not supported by SOAP |
|
|
|
Invalid XML encoding name |
|
|