Roteiro de Integração API com E-commerce Marketplace Soulmkt
Este documento tem como objetivo simplificar o processo de integração do ERP dos vendedores com o marketplace. Primeiramente, o vendedor deverá liberar uma credencial de acesso da api. Esta configuração pode ser feita através do painel do vendedor, no menu Api Marketplace.
IMPORTANTE! Para que a associação do produto funcione corretamente é necessário configurar, na tela de criação do usuário de API, o código do atributo que relaciona o produto que está no ERP ao produto do marketplace! Para isso você deve analisar dentro da lista dos produtos disponíveis para venda o “Código Marketplace” conforme mostra a imagem abaixo:
Uma vez que o código foi identificado você precisa olhar dentro do seu ERP qual atributo do seu produto possui esse mesmo valor e pegar o código desse atributo! Por exemplo: Se dentro do seu ERP o “Código Marketplace” for representado pelo codigo_de_barra, então você deve configurar codigo_de_barra na tela de criação do usuário de API conforme mostra imagem abaixo.
Observação: Caso o “Código Marketplace” seja igual ao sku do seu produto basta deixar esse campo em branco.
Em caso de dúvida o administrador do marketplace pode entrar em contato com o suporte da Marketplace para gerar esta credencial.
Integração de produtos #
A integração de produtos começa obrigatoriamente quando o vendedor seleciona quais produtos disponibilizados pelo administrador da loja ele irá vender.
1 – Seleção e cadastro de produtos #
O vendedor poderá apenas vender os produtos que estão disponíveis na tela de Selecionar Produtos dentro do menu de Selecione e Venda. A API não possui um método que disponibiliza a lista dos produtos que podem ser vendidos, então para que o vendedor verifique quais produtos ele pode vender é necessário exportar uma planilha dentro do sistema através do menu Selecione e Venda -> Importação / Exportação -> Aba Exportar.
Metodo: catalogProductCreate
Permite selecionar um novo produto para venda e retornar o ID do produto criado. #
Observação:
Embora a API permita até quatro dígitos de precisão para todos os argumentos de preço, é fortemente recomendado que você passe dois dígitos para reduzir a imprecisão no processo de cálculo de impostos. Por exemplo, use um preço como 12.35 e não 12.3487.
Se o preço do produto não estiver dentro do range especificado pelo administrador o produto será incluído com o Status = 3 (Preço atualizado). Posteriormente o vendedor deverá atualizar o preço, corrigindo assim o valor para dentro do range especificado, para que, desta forma, o produto possa ser habilitado para venda.
Parâmetros:
Tipo | Nome | Descrição |
String | sessionid | ID da Sessão |
String | type | Tipo de produto (simple) |
String | set | Id do grupo de atributo, enviar sempre o valor 4 |
String | sku | Código do seu produto |
Array | productData | Atributos do produto |
Retorno:
Tipo | Nome | Descrição |
Inteiro | result | ID do produto que foi criado |
As opções de Atributos do produto são:
Tipo | Nome | Descrição |
String | delivery_time | Adicionar dias ao prazo de entrega (Correios) |
Array | stock_data | Array dos atributos de estoque |
Decimal (10,2) | price | Preço do produto |
Int | frete_gratis | Permite frete grátis no produto (0 – Não, 1 – Sim) |
Int | retirar_loja | Permite retirar o produto na loja do vendedor (0 – Não, 1 – Sim) |
String | extra_info | Texto adicional no produto (disponível apenas para o vendedor) |
String | weight | Peso do Produto (kg) |
Decimal (10,2) | height | Altura do produto (cm) |
Decimal (10,2) | length | Comprimento do produto (cm) |
Decimal (10,2) | breadth | Largura do produto (cm) |
Int | status | Status do Produto (1 – Habilitado, 2 – Status) |
String | key_marketplace* | Substitua esse código pelo código do atributo que se relaciona ao “Código Marketplace” caso não seja o SKU! (É o mesmo código configurado na tela do usuário de API) Ex: mande no lugar de key_marketplace codigo_de_barra caso esse seja o código do seu atributo! |
As opções de estoque do produto são:
Tipo | Nome | Descrição |
Int | is_in_stock | Disponibilidade de Estoque (0 – Esgotado, 1 – Em estoque) |
Int | qty | Quantidade disponível em estoque |
Exemplo: #
// TODO : trocar url $client = new SoapClient(‘http://marketplacehost.com.br/api/v2_soap/?wsdl’); // TODO : trocar login (api_user) and senha (api_key) $session = $client->login(‘api_user’, ‘api_key’); // Utilizar sempre o valor 4 $grupoProduto = 4; $result = $client->catalogProductCreate($session, ‘simple’, $grupoProduto, ‘product_sku’, array( ‘price’ => ‘100’, ‘stock_data’ => [‘is_in_stock’=>’1′,’qty’=>’10’], ‘weight’ => ‘0,10’, ‘height’ => ’30’, ‘length’ => ‘160’, ‘breadth’ => ’80’ )); var_dump ($result); |
2 – Atualização de produtos #
Método: catalogProductUpdate
Permite atualizar o produto necessário. Observe que você deve especificar apenas os parâmetros que deseja atualizar. #
Observação:
Embora a API permita até quatro dígitos de precisão para todos os argumentos de preço, é fortemente recomendado que você passe dois dígitos para reduzir a imprecisão no processo de cálculo de impostos. Por exemplo, use um preço como 12.35 e não 12.3487.
Se o preço do produto não estiver dentro do range especificado pelo administrador o produto será atualizado para o Status = 3 (Preço atualizado). Posteriormente o vendedor deverá atualizar o preço, corrigindo assim o valor para dentro do range especificado, para que, desta forma, o produto possa ser habilitado para venda.
Parâmetros:
Tipo | Nome | Descrição |
String | sessionid | ID da Sessão |
String | product\productId | ID do produto (retornado no método create) |
Array | productData | Atributos do produto |
Retorno:
Tipo | Descrição |
boolean | Verdadeiro se o produto for atualizado |
As opções de Atributos do produto são:
Tipo | Nome | Descrição |
String | delivery_time | Adicionar dias ao prazo de entrega (Correios) |
Array | stock_data | Array dos atributos de estoque |
Decimal (10,2) | price | Preço do produto |
Int | frete_gratis | Permite frete grátis no produto (0 – Não, 1 – Sim) |
Int | retirar_loja | Permite retirar o produto na loja do vendedor (0 – Não, 1 – Sim) |
String | extra_info | Informação adicional do produto para o vendedor |
String | weight | Peso do Produto (kg) |
Decimal (10,2) | height | Altura do produto (cm) |
Decimal (10,2) | length | Comprimento do produto (cm) |
Decimal (10,2) | breadth | Largura do produto (cm) |
Int | status | Status do Produto (1 – Habilitado, 2 – Status) |
String | sku | Código do seu produto |
Exemplo: #
// TODO : trocar url $client = new SoapClient(‘http://marketplacehost.com.br/api/v2_soap/?wsdl’); // TODO : trocar login (api_user) and senha (api_key) $session = $client->login(‘api_user’, ‘api_key’); $result = $client->catalogProductUpdate($session, ‘product_sku’, array( ‘price’ => ‘100’, ‘stock_data’ => [‘is_in_stock’=>’1′,’qty’=>’5’], )); var_dump ($result); |
3 – Remoção de produtos do vendedor #
Método: catalogProductDelete
Permite remover o produto da seleção de produtos á venda pelo vendedor
Parâmetros:
Tipo | Nome | Descrição |
String | sessionid | ID da Sessão |
String | product\productId | ID do produto (retornado no método create) |
Retorno:
Tipo | Nome | Descrição |
Boolean/int | result | Verdadeiro (1) se o produto for removido |
Exemplo:
// TODO : trocar url $proxy = new SoapClient(‘http://marketplacehost.com.br/api/v2_soap/?wsdl‘); // TODO : trocar login (api_user) and senha (api_key) $sessionId = $proxy->login(‘api_user’, ‘api_key’); $productId = ‘6’; $result = $proxy->catalogProductDelete($sessionId, $productId); var_dump($result); |
Integração de pedidos #
Esta integração trata-se da leitura dos novos pedidos do marketplace e o andamento do ciclo de vida até o pedido ser entregue.
1 – Filtrar pedidos #
Metodo: salesOrderList
Retorna a lista de pedidos. Filtros adicionais podem ser aplicados
Parâmetros:
Tipo | Nome | Descrição |
String | sessionid | ID da Sessão |
Array | filters | Array de filtros para a lista de pedidos |
Retorno:
Tipo | Nome | Descrição |
Array | result | Lista de pedidos |
Tabela de status dos pedidos que podem ser filtrados
Código | Descrição |
pending | Pedido criado porém ainda não pago |
processing | Pedido pago |
aguardando_nota_fiscal | Aguardando a inclusão de nota fiscal |
nf_emitida | Pedido com nota fiscal emitida |
aguardando_transporte | Pedido aguardando remessa para a transportadora |
entregue_transportadora | Pedido entregue a transportadora |
aguardando_confirmacao | Pedido aguardando confirmação de recebimento do cliente |
complete | Pedido entregue ao cliente |
reembolsado | Pedido reembolsado |
reembolsado_parcial | Pedido reembolsado parcialmente |
canceled | Pedido cancelado |
Exemplo:
// TODO : trocar url | trocar login (api_user) and senha (api_key) $proxy = new SoapClient(‘http://marketplacehost.com.br/api/v2_soap/?wsdl’); $sessionId = $proxy->login(‘api_user’, ‘api_key’); // Exemplo de requisição com filtro simples – Filtra todos os pedidos PAGOS ainda não entregues $filter = [ ‘filter’ => [ array(‘key’ => ‘status’, ‘value’ => ‘processing’) ] ]; $result = $client->salesOrderList($session, $filter); // Exemplo de requisição com filtro complexo $params = [ [ ‘filter’ => [ [ ‘key’ => ‘status’, ‘value’ => ‘processing’ ], [ ‘key’ => ‘created_at’, ‘value’ => ‘2001-11-25 12:12:07’ ] ], ‘complex_filter’ => [ [ ‘key’ => ‘order_id’, ‘value’ => [ ‘key’ => ‘in’, ‘value’ => ‘12,23’ ], ], [ ‘key’ => ‘protect_code’, ‘value’ => [ ‘key’ => ‘eq’, ‘value’ => ‘ebb2a0’ ], ], ] ] ]; $result = $client->__call(‘salesOrderList’, $params); var_dump($result); |
2 – Detalhe do pedido #
Metodo: salesOrderInfo
Retorna as informações do pedido
Parâmetros:
Tipo | Nome | Descrição |
String | sessionid | ID da Sessão |
Array | orderIncrementId | Número do pedido |
Retorno:
Tipo | Nome | Descrição |
Array | result | Dados do pedido |
Exemplo:
// TODO : trocar url $proxy = new SoapClient(‘http://marketplacehost.com.br/api/v2_soap/?wsdl’); // TODO : trocar login (api_user) and senha (api_key) $sessionId = $proxy->login(‘api_user’, ‘api_key’); $result = $proxy->salesOrderInfo($sessionId, ‘100000006’); var_dump($result); |
3 – Atualização de status e comentários do pedido #
Metodo: salesOrderAddComment
Permite incluir um novo comentário no pedido, também irá alterar o status do pedido de acordo com a informação enviada. Caso o status enviado seja igual ao status atual do pedido, apenas o comentário será inserido!
Observação:
Não é possível atualizar o status do pedido para pending, processing, canceled / reembolsado / reembolsado_parcialmente pela API pois esses status são de uso exclusivo dos métodos de pagamento. Contudo a inclusão de comentários ainda irá funcionar para estes status.
Parâmetros:
Tipo | Nome | Descrição |
String | sessionid | ID da Sessão |
String | orderIncrementId | Número do pedido |
String | status | Status do pedido Lista dos status disponíveis |
String | comment | Comentário (opcional) |
String | notify | Enviar notificação (opcional) |
Retorno:
Tipo | Descrição |
boolean\int | Verdadeiro se o comentário for incluído no pedido |
Exemplo:
// TODO : trocar url $proxy = new SoapClient(‘http://marketplacehost.com.br/api/v2_soap/?wsdl’); // TODO : trocar login (api_user) and senha (api_key) $sessionId = $proxy->login(‘api_user’, ‘api_key’); $result = $proxy->salesOrderAddComment($sessionId, ‘200000004’, ‘processing’); var_dump($result); |
#
4 – Remessas de envio #
4.1 – Criar nova remessa #
Metodo: salesOrderShipmentCreate
Permite que seja criada uma nova remessa de envio de produto.
Parâmetros: #
Tipo | Nome | Descrição |
String | sessionid | ID da Sessão |
String | orderIncrementId | Número do pedido |
Array | itemsQty | Quantidade de itens do pedido a ser enviados |
String | comment | Comentário (opcional) |
Int | Enviar notificação (opcional) | |
Int | includeComment | Flag para incluir o comentário no email (opcional) |
Retorno:
Tipo | Nome | Descrição |
String | shipmentIncrementId | Código da remessa |
As opções para o parâmetro itemsQty são:
Parâmetros: #
Tipo | Nome | Descrição |
int | order_item_id | Código do item no pedido |
double | qty | Quantidade do item a ser enviado |
Observação:
Sempre que você incluir a remessa ou código de rastreamento, é recomendável que você também inclua um comentário no pedido informando a ação realizada e atualizando o status do mesmo!
Exemplo:
// TODO : trocar url $proxy = new SoapClient(‘http://marketplacehost.com.br/api/v2_soap/?wsdl’); // TODO : trocar login (api_user) and senha (api_key) $sessionId = $proxy->login(‘api_user’, ‘api_key’); $itemsQty = [ [ ‘order_item_id’ => 3, ‘qty’ => 3 ], [ ‘order_item_id’ => 4, ‘qty’ => 5 ] ]; $result = $proxy->salesOrderShipmentCreate($sessionId, ‘200000006’, $itemsQty, ‘shipment comment’); var_dump($result); |
4.2 – Código de rastreamento
Metodo: salesOrderShipmentAddTrack
Permite que seja adicionado o código de rastreamento na remessa de envio
Parâmetros: #
Tipo | Nome | Descrição |
String | sessionid | ID da Sessão |
String | shipmentIncrementId | Código da remessa |
String | carrier | Código do método de envio |
String | title | Título do rastreio |
String | trackNumber | Número do rastreio |
Retorno:
Tipo | Descrição |
int | Código do número de rastreamento |
// TODO : trocar url $proxy = new SoapClient(‘http://marketplacehost.com.br/api/v2_soap/?wsdl’); // TODO : trocar login (api_user) and senha (api_key) $sessionId = $proxy->login(‘api_user’, ‘api_key’); $result = $proxy->salesOrderShipmentAddTrack($sessionId, ‘200000002’, ‘correios’, ‘título da remessa’, ‘123123’); var_dump($result); |
4.3 – Listar remessas #
Metodo: salesOrderShipmentList
Retorna a lista de remessas. Filtros adicionais podem ser aplicados #
Parâmetros:
Tipo | Nome | Descrição |
String | sessionid | ID da Sessão |
Array | filters | Array de filtros para a lista de remessas |
Retorno:
Tipo | Nome | Descrição |
String | result | Dados da lista de remessas |
Os dados da lista de remessa são:
Parâmetros: #
Tipo | Nome | Descrição |
String | increment_id | Código do pedido |
String | created_at | Data da criação da remessa |
String | total_qty | Quantidade total dos itens da remessa |
String | shipment_id | Código da remessa |
4.4 – Detalhe da remessas #
Metodo: salesOrderShipmentInfo
Retorna as informações completas da remessa #
Parâmetros:
Tipo | Nome | Descrição |
String | sessionid | ID da Sessão |
Array | shipmentIncrementId | Código do pedido da remessa |
Retorno:
Tipo | Nome | Descrição |
String | result | Dados da remessa, dos itens do pedido e dos comentários na remessa |
// TODO : trocar url $proxy = new SoapClient(‘http://marketplacehost.com.br/api/v2_soap/?wsdl’); // TODO : trocar login (api_user) and senha (api_key) $sessionId = $proxy->login(‘api_user’, ‘api_key’); $result = $proxy->salesOrderShipmentInfo($sessionId, ‘200000003’); var_dump($result); |
Dúvidas frequentes
- Consigo filtrar os produtos que foram cadastrados por outro vendedor ou pelo administrador da loja?
Não! Cada vendedor tem acesso apenas aos seus dados, sejam eles produtos ou pedidos. - É possível gerar uma fatura via API?
Não! Apenas os métodos de pagamento podem gerar as faturas dentro do marketplace. - Inclusão do preço em um projeto selecione e venda, é possível obter via api o range de preço definido pelo administrador?
Por enquanto isto ainda não é possível, por isso é importante que o vendedor esteja em contato com o administrador do sistema para ficar ciente de qual valor ele pode colocar em seus produtos.