Olá Desenvolvedor(a)!

Bem-vindo a porta de entrada para começar a vender ‘online’ em mais de 80 canais de vendas, dentre e-commerce e marketplaces.

 

Este é um guia de primeiros passos, para aprofundamento nos endpoints específicos da API, consulte a nossa documentação técnica.

 

Sumário

1. Ambientes

2. Autenticação da API

2.1 Token de acesso (accessToken)

2.2 Token de renovação (refreshToken)

3. Produtos

3.1 Preparando o seu Software

3.2 Canais de Venda

3.3 Cadastrando um novo produto 

3.4 Cadastrando imagem para um produto

3.5 Atualizando um produto

4. Pedidos

4.1 Buscando Pedidos

4.2 Webhook de Pedidos

4.3 Confirmação de pedido

4.4 Notificação de Faturamento

4.5 Notificação de Despacho/Envio

4.6 Confirmação de Entrega

5. Documentação Técnica

6. Check list dos ambientes sandbox

  6.1 Checklist

  6.2 Collection para testes

7. Aprovação pela consultoria técnica

8. Configurações White Label

9. Cadastro da loja em produção

10. Materiais de apoio comercial

 

 

1. Ambientes

Atualmente a nossa API conta com dois ambientes distintos para serem utilizados, sendo eles o Hub (painel da loja) e App (painel de monitoramento). Para esse momento de homologação, você irá utilizar esses ambientes em sandbox.

É necessário realizar todo processo de homologação em sandbox para garantir que corra tudo certo nos ambiente em produção.

O acesso a estes ambientes sandbox se dão através das URL's abaixo:

Hub: https://hub.sandbox.plug4market.com.br/Login

App: https://app.sandbox.plug4market.com.br/

 

 

2. Autenticação da API

Para se autenticar na API e começar a integrar seus produtos e recebimento de vendas nos marketplaces é necessário acessar o painel do App (monitoramento) para você poder ver as lojas que você possui cadastradas em nossa aplicação e gerar os tokens de acesso para ela. Sim, são dois tokens. 

Para gerar os tokens da loja, acesse o painel de monitoramento, selecione a opção "Lojas" e localize a loja desejada para integrar. Em seguida, visualize suas informações (clicar sobre a linha da loja desejada ou sobre o botão com ícone de olho). 

No final da página será possível ver uma seção chamada "Token da Loja", que conta com um campo e dois botões, sendo respectivamente um botão para "gerar tokens" (1) e outro para "copiar"(2), e o campo anteriormente vazio será preenchido com os tokens para utilizar na integração.

Gere os tokens clicando no botão "Gerar Token", em seguida copie o conteúdo no campo, seja pelo botão ou manualmente selecionando e copiando. 

Em seguida, note-se que são dois tokens: o accessToken e o refreshToken.

{
   "accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "refreshToken": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}

 

2.1 Token de acesso (accessToken) 

Este é o token que deverá ser enviado em todas as requisições para nossa API.

Você deverá passar esse token através do header "Authorization", conforme abaixo:

Authorization: Bearer <token>

// exemplo:

Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Este token tem validade de 24 horas, então será necessário renovar ele periodicamente, como sugestão a cada 23 horas. Para renovação deste token é aconselhável possuir o seu token de atualização, denominado refreshToken. 

 

2.2 Token de renovação (RefreshToken)

Este é nosso token de atualização, você deverá armazená-lo seguramente em seu sistema/banco de dados, pois com ele você poderá criar uma rotina para atualização do seu token de acesso à API, caso contrário será necessário fazer a geração manualmente via painel do Plug4Market. 

Este token é gerado sempre com um token de acesso, é único por accessToken, ou seja, a cada renovação de accessToken haverá um novo refreshToken. 

A renovação do accessToken se dá através da rota POST /auth/refresh, onde no body deverá ser enviado o refreshToken.

Para esta rota não há necessidade de informar o header Authorization.

// POST /auth/refresh

{
   "refreshToken": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}

O retorno desta requisição será novamente um par de tokens, accessToken e refreshToken. Armazene o par e utilize nas suas próximas requisições e renovação.

Caso ainda tenha ficado alguma dúvida, você pode conferir Nesse Vídeo como funciona a autenticação com os tokens.

 

3. Produtos

O gerenciamento de produtos em nossa API é feita através do endpoint  "/products". Através deste endpoint é possível realizar o cadastro, envio de imagem, atualização de preços, estoque e entre outros campos.

Importante frisar que os canais de venda (marketplaces e ecommerces) não respondem de maneira síncrona, ou seja, ao enviar um produto (seja novo ou uma atualização) para o Plug4Market não significa que o mesmo foi aceito pelos canais de venda. 

3.1 Preparando o seu software

Antes de realizar a integração com o Plug4Market é necessário que seu software esteja preparado. Isto porque necessitamos de alguns dados previamente configurados, sendo eles dados fixos onde deverá ser informado apenas o id do dado, que é o caso de categorias, cores, tamanhos, voltagem e sabores.

Para isso, disponibilizamos os dados para download e posteriormente você fazer a importação em seu software. 

Eles irão funcionar para todos os canais de venda. Portanto, deve-se utilizar o mesmo independente se produtos serão anunciados no Mercado Livre ou na Amazon, por exemplo.

Importante frisar que receberemos apenas os IDs dos respectivos dados. Clique para realizar o download:

 

Categorias

Obrigatório em todos os produtos, sendo utilizado para categorização dentro dos marketplaces. Uma dica é tornar este campo obrigatório no cadastro de produto de seu software.

 

Planilha atualizada das categorias

Você pode conferir esse vídeo que mostra como categorizar produtos

Nesse outro vídeo, falamos sobre as categorias de e-commerces personalizadas

 

Categorias Globais

Planilha de categorias globais

Utilizada para produtos que serão enviados para marketplaces (Ex: Mercado Livre, Shopee, Amazon, etc)

 

Cores

Cores Sandbox

Cores Produção

Recomendado em produtos que tem variação por cor (tênis, blusas, calças, produtos do vestuário em geral...)

 

Tamanhos

Tamanhos Sandbox

Tamanhos Produção

Recomendado em produtos que tem variação por tamanho (tênis, blusas, calças, produtos do vestuário em geral...)

 

Voltagem

Voltagem Sandbox

Voltagem Produção

Recomendado em produtos que tem variação por voltagem (eletrodomésticos)

 

Sabores

Sabores Sandbox

Sabores Produção

Recomendado em produtos que tem variação por sabores (produtos alimentícios)

 

Potência

Potência Sandbox

Potência Produção

Recomendado em produtos que tem variação por potência (lâmpadas, por exemplo) 

 

Caso você ou seu cliente encontre valores não mapeados nestes arquivos, entre em contato conosco para realizarmos a homologação destes valores junto aos marketplaces do mercado.

3.2 Canais de Venda

Canais de venda, é como chamamos e-commerces e marketplaces, você irá ouvir falar muito por aqui. Atualmente estamos com 78 canais de vendas disponíveis para integrarmos através de uma única integração. Veja abaixo quais são:

 

 

É importante que você tenha essa lista em seu sistema/banco de dados, pois ao receber uma venda ela virá com o ID do canal de venda que a originou, assim você conseguirá fazer o devido cruzamento de dados.

 

3.3 Cadastrando um novo produto

O cadastro de produto é um POST, para nossa API, contendo os campos que deseja ser informado. Neste exemplo será cadastrado um tênis, ou seja, um produto que contém variação (cor e tamanho), porém há cenários que não existe, ou o cliente não deseja trabalhar com variações, como, por exemplo, peças automobilísticas. 

 

URL

POST https://api.sandbox.plug4market.com.br/products

 

Body

{
   "sku": "001-1",
   "productId": "001",
   "active": true,
   "brand": "Nike",
   "categoryId": "5d420cb3e2f97a00163d677f",
   "color": "5be53b945bf3de00013b3541",
   "crossDockingDays": 7,
   "description": "<div class='detalhes-produto__descricao descricao-completa'><p><b>ESTILO LENDÁRIO COM SOFISTICAÇÃO.</b></p><br><p>O brilho perdura no Nike Air Force 1 '07, o tênis original do basquete que dá um toque de inovação naquilo que você conhece bem: sobreposições costuradas e duráveis, acabamentos simples e a quantidade perfeita de brilho para fazer você se destacar.</p><br><p><b>Benefícios</b></p><ul><li>As camadas costuradas na parte de cima trazem estilo, durabilidade e sustentação de herança.</li><li>Projetado originalmente para jogos de basquete de alto desempenho, o amortecimento Nike Air adiciona leveza para conforto o dia todo.</li><li>A silhueta de corte baixo proporciona um look simplificado e minimalista.</li><li>A gola acolchoada é macia e confortável.</li></ul><br><p><b>Detalhes do produto</b></p><ul><li>Entressola de espuma</li><li>Perfurações na ponta</li><li>Sola de borracha</li></ul><br><p><b>Origens do Air Force 1</b></p><p>Estreando em 1982, o AF1 foi o primeiro tênis de basquete a abrigar o Nike Air, revolucionando o jogo e ganhando tração rapidamente em todo o mundo. Hoje, o Air Force 1 permanece fiel às suas raízes com o mesmo amortecimento macio e elástico que mudou a história dos sneakers.</p><br> </div>",
   "gender": "masculino",
   "height": 24,
   "length": 37,
   "images": [
      "https://images.lojanike.com.br/1024x1024/produto/tenis-nike-air-force-1-07-masculino-CW2288-111-1.jpg",
      "https://images.lojanike.com.br/500x500/produto/tenis-nike-air-force-1-07-masculino-CW2288-111-1.jpg",
      "https://images.lojanike.com.br/1024x1024/produto/tenis-nike-air-force-1-07-masculino-CW2288-111-5.jpg",
      "https://images.lojanike.com.br/1024x1024/produto/tenis-nike-air-force-1-07-masculino-CW2288-111-6.jpg"
   ],
   "ean": "752852368",
   "costPrice": 400,
   "salesChannels": [
      {
         "id": 1,
         "price": 649.99,
         "forSale": {
         "salePrice": 599.99,
            "saleDateStart": "2020-04-30T13:22:00",
            "saleDateEnd": "2025-05-30T13:22:00"
         }   
      },
      {
         "id": 4,
         "price": 679.99,
     },
     {
         "id": 26
      }
   ],
   "manufacturerPartNumber": "5",
   "model": "Air Force",
   "name": "Tenis TESTE Nike",
   "origin": "importado",
   "ncm": "6404.11.00",
   "price": 699.99,
   "productName": "Tenis Nike Air Force",
   "size": "5c0ef9e9452cfa0001eb24ab",
   "stock": 10,
   "warranty": 90,
   "weight": 13,
   "width": 40,
   "customCategory": {
      "alternativeId": "0001"
   },
   "flavor": "60aea8290aa25c000166a66c",
   "measurementUnit": "un",
   "unitMultiplier": 1,
   "metafields": [
   {
      "key": "Tipo de Tênis",
      "value": "Costura"
   }
   ],
   "potency": "5e021f22ea047f0001d51bc1",
   "salePrice": 599.99,
   "saleDateStart": "2020-04-30T13:22:00Z",
   "saleDateEnd": "2025-05-30T13:22:00Z",
   "voltage": "618545fea08a2f00015eea0e",
   "videos": [
      "https://www.youtube.com/watch?v=6U5ItG1Y654&pp=ygUNdGVuaXMgZGEgbmlrZQ%3D%3D",
      "https://www.youtube.com/watch?v=de1rD-CNLn0&pp=ygUNdGVuaXMgZGEgbmlrZQ%3D%3D"
   ]
}

Obs: Os campos em vermelho claro são os campos obrigatórios

 

Note que alguns campos não recebem valores literais, no caso dos campos categoryId, color e size, os quais recebem apenas ID's, que servem para a normatização entre os variados marketplaces.

 

3.4 Cadastrando imagem para um produto

É inegável que imagens são pontos decisivos para a compra de produtos na internet. Por isso é importante que seu cliente capriche nas imagens, fornecendo imagens de boa qualidade e boa resolução (Cerca de 1000px é o ideal).

Assim sendo, temos API's para envio de imagens onde existem atualmente dois formatos para cadastrar imagens em produtos.

 

A maneira mais indicada é informar no próprio body do cadastro de produto, no Plug4Market, uma URL pública da imagem. Assim basta uma requisição para que o produto já esteja sendo disponibilizado para marketplaces, como no exemplo abaixo extraído do passo anterior.

"images": [
   "https://images.lojanike.com.br/1024x1024/produto/tenis-nike-air-force-1-07-masculino-CW2288-111-1.jpg",
   "https://images.lojanike.com.br/500x500/produto/tenis-nike-air-force-1-07-masculino-CW2288-111-1.jpg",
   "https://images.lojanike.com.br/1024x1024/produto/tenis-nike-air-force-1-07-masculino-CW2288-111-5.jpg",
   "https://images.lojanike.com.br/1024x1024/produto/tenis-nike-air-force-1-07-masculino-CW2288-111-6.jpg"
],

 

Caso este ainda não seja um processo viável no seu software, é possível a realização do envio do binário da imagem, mas para isso é necessário fazer uma imagem de cada vez após a criação do produto.

 

URL

POST https://api.sandbox.plug4market.com.br/products/{SKU do Produto}/images

Body

{
   "base64Image": "{base64 da imagem}"
}

 

Formato de imagem que o Plug4Market aceita:

GIF, JPG e PNG

 

3.5 Atualizando um produto

Esta, com toda certeza, será uma das rotas que seu software mais terá interação. Isto porque esta é rota para atualização de produtos, sendo os principais campos atualizados estoque, preço, e disponibilidade.

 

URL

PUT https://api.sandbox.plug4market.com.br/products/{SKU do Produto}

 

Body

{
   "productId": "produtoExemplo"
   "stock": 10,
   "price": 699.99,
   "salesChannels": [{}]
}

Neste exemplo, apenas os campos informados serão atualizados e apenas o campo "productId" é obrigatório, sendo a quantidade de estoque e o preço. Porém é possível atualizar grande parte dos campos, para isto consulte nossa documentação técnica.

Obs: Para remover o produto de todos os canais de vendas, basta informar o array "salesChannels" com um objeto vazio.

 

4. Pedidos

Este conjunto de endpoints permite a busca e atualização de pedidos através do seu sistema. Dentre as operações permitidas através de API estão a busca de pedidos, a confirmação do recebimento no seu sistema, o faturamento do pedido, o despacho/envio das mercadorias e a confirmação de entrega.

Para facilitar a integração da API, é importante também você ter seu sistema preparado, é importante que você faça um mapeamento dos canais de venda conforme a tabela no item 4.1.1 Canais de Venda.

Pedidos em sandbox:

Para esse momento de homologação nos ambientes sandbox, você irá criar pedidos fictícios através do endpoint: https://atendimento.tecnospeed.com.br/hc/pt-br/articles/18617207518103-Criar-pedido-em-Sandbox

 

4.1 Buscando pedidos

A busca de pedidos é através da requisição GET para o endpoint "orders". 

Indicamos que sejam criadas rotinas para verificação automática de tempos em tempos, por exemplo, a cada 15 minutos irá realizar esta requisição para obter os pedidos novos. 

Lembrando que o Plug4Market só aceita 100 request (rate limit) por minuto. 

 

GET https://api.sandbox.plug4market.com.br/orders

 

Exemplo de Response: 

 

{
   "data": [
   {
      "id": "955df2f1-5f43-4493-9a80-f3fadb90772a",
      "saleChannelId": "7",
      "orderSaleChannelId": "TESTE_$998547491949",
      "status": "APPROVED",
      "amount": 1564,
      "integratedStore": false,
      "invoice": null,
      "shipments": null,
      "orderIdStore": null,
      "createdAt": "2022-12-26T20:31:49.726Z",
      "updatedAt": "2022-12-26T20:31:49.763Z",
      "note": null,
      "storeOrderId": null
   },
   {
      "id": "bc5330b3-1e64-45e2-b37b-47bcfe3ee375",
      "saleChannelId": "7",
      "orderSaleChannelId": "TESTE_$675864564473",
      "status": "APPROVED",
      "amount": 9825,
      "integratedStore": false,
      "invoice": null,
      "shipments": null,
      "orderIdStore": null,
      "createdAt": "2022-12-26T20:12:47.862Z",
      "updatedAt": "2022-12-26T20:12:47.903Z",
      "note": null,
      "storeOrderId": null
   },
   {
      "id": "18726989-0ee9-4669-9483-cd251ccacb40",
      "saleChannelId": "7",
      "orderSaleChannelId": "TESTE_$657454030912",
      "status": "APPROVED",
      "amount": 9825,
      "integratedStore": false,
      "invoice": null,
      "shipments": null,
      "orderIdStore": null,
      "createdAt": "2022-12-26T20:11:58.082Z",
      "updatedAt": "2022-12-26T20:11:58.117Z",
      "note": null,
      "storeOrderId": null
   }
 ]
}

 

4.2 Webhook

Você também pode utilizar o webhook  para ser notificado sobre novos pedidos.

 

4.3 Confirmação de pedido

Esta etapa do processo consiste em confirmar para o Plug4Market que o produto foi integrado em seu software. Isso garante uma maior segurança na integração e você ao acessar nosso hub, consegue saber a qual pedido em seu software corresponde o pedido em nossa plataforma. 

Para realizar a confirmação basta enviar o ID/Número do pedido em seu software, conforme exemplo abaixo:

 

URL:

POST https://api.sandbox.plug4market.com.br/orders/{id do pedido no plug4market}/confirm

 

Body:

{
   "orderIdStore": "string",
}

4.4 Notificação de Faturamento

Para atendimento da legislação tributária, é necessário fazer o envio da Nota Fiscal para os canais de venda, assim que emitida. Deverá ser enviado as seguintes informações:

• Número da Nota Fiscal
• Série da Nota Fiscal
• Chave de Acesso da Nota Fiscal
• XML da Nota Fiscal (enviar em ‘string’ somente o conteúdo)
• Data-hora de emissão da Nota Fiscal

 

 

URL: https://api.sandbox.plug4market.com.br/orders/{orderId}/invoice

POST

{
   "orderIdStore": "string"
}

 

Body:

{
   "nfeDate": "{Data e hora da Nota Fiscal}",
   "nfeNumber": "{Número da Nota Fiscal}",
   "nfeSerialNumber": "{Série da Nota Fiscal}",
   "nfeAccessKey": "{Chave de Acesso da Nota Fiscal}",
   "xml": "{XML da Nota Fiscal}"
}

 

Este é o cenário considerando que não está sendo utilizado Mercado Livre Full, caso seja o caso da loja de seu cliente, desconsidere esta etapa, pois será o próprio Mercado Livre que realizará esta notificação.

 

4.5 Notificação de Despacho/Envio

 O envio dos dados de rastreamento do pedido deve ser feito o quanto antes, geralmente após a emissão da NF-e já se tem essas informações. Segue a mesma linha do envio da nota fiscal.

Os dados necessários nesta etapa são:

• Código de Rastreio
• URL de Rastreio
• Transportadora

 

URL:

POST https://api.sandbox.plug4market.com.br/orders/{id do pedido no plug4market}/shipment

 

Body:

{
   "trackingNumber": "{Código de Rastreio}",
   "shippingCarrier": "{Transportadora}",
   "trackingUrl": "{URL de rastreio}"
}

 

Este é o cenário considerando que não está sendo utilizado Mercado Livre Full, caso seja o caso da loja de seu cliente, desconsidere esta etapa, pois será o próprio Mercado Livre que realizará esta notificação.

 

4.6 Confirmação de entrega

Essa é a última etapa a ser executada. Em casos que não possuímos integração com uma transportadora, é necessário fazer a notificação da entrega do pedido. Para tal, basta enviar qual a data/hora onde a entrega foi realizada. 

 

Este é um processo que marketplaces que não possuem sistema de rastreamento de encomendas integrado solicitam, muitas vezes sendo essencial para recebimento dos valores.

 

URL:

POST https://api.sandbox.plug4market.com.br/orders/{id do pedido no plug4market}/delivered

 

Body:

{
   "deliveredAt": "{Data-hora da entrega}"
}

 

Este é o cenário considerando que não está sendo utilizado Mercado Livre Full, caso seja o caso da loja de seu cliente, desconsidere esta etapa, pois será o próprio Mercado Livre que realizará esta notificação.

 

5. Documentação Técnica

Nossa documentação técnica é destinada para entender as particularidades dos campos e seus tipos existentes em cada um dos endpoints.

Por isso, acesse a página de nossa documentação técnica clicando aqui.

 

6. Check list dos ambientes sandbox

Esse check list é importante para que você tenha mais garantias de que irá sair tudo de acordo no momento em que passarmos para a produção.

Portanto, é necessário realizar cada item dessa lista.

6.1 Checklist

6.2 Collection para testes

 

7. Aprovação pela consultoria técnica

Após realizar todos os itens do checklist dos ambientes sandbox, você pode informar nossa equipe de consultoria técnica que já está pronto para entrar em produção.

Será agendada uma chamada através no Meet que durará em média 1 hora onde nossa equipe fará a revisão dos testes necessários. Caso tenha alguma inconsistência, você será orientado a fazer as correções necessárias e será agendada uma nova chamada.

No momento em que a consultoria técnica aprovar a sua implementação, você estará apto a realizar o processo de passagem para os ambientes em produção.

O contato com nossos consultores técnicos (suporte técnico), deve ser feito sempre através da nossa Central de Atendimento.

 

8. Configurações White Label

Nessa etapa, nossa equipe de consultoria técnica irá realizar as configurações white label da sua conta.

Para isso, são necessários os seguintes itens: 

- Logo da empresa no formato .PNG (fundo transparente)

- Logo da empresa para FavIcon

- Cor principal em RGB

#0000FF (principal)

#73D0F6 (secundária)

 

Sugestão Domínio:

- Domínio SandBox:  https://suaSH.sandbox.plug4market.com.br

- Domínio Produção: https://suaSH.plug4market.com.br

 

Observações:

1 - Tamanho maximo da logo da tela de login é width="250"

2 - Tamanho maximo da logo na barra da tela principal: width="107"

3 - A cor principal é o verde claro, verde escuro é a cor do botão, podendo ser cor secundaria ou na matriz de cores a que melhor se adequa a este caso.

 

 

9. Cadastro da loja em produção

Com a integração nos ambientes sandbox validada, você será orientado pelos consultores sobre como passar para os ambientes em produção. 

Basta solicitar as orientações através da nossa Central de Atendimento

Parabéns!! Ao fim dessa etapa sua integração estará apta a cadastrar cada vez mais lojas.

 

10. Materiais de apoio comercial

Além de todo apoio técnico para seu software, também disponibilizamos uma variedade de materiais de apoio comercial com conteúdos sobre o mercado das vendas online.
Trazendo assim, mais expertise sobre a área e potencialmente aumentando as suas vendas e as dos seus clientes.

Você encontra esses materiais em nosso Repositório de Materiais. 

 

Anexos: