API V1 - Hub de Marketplaces

Documentation of resources available in public APIs for integrations of Uappi marketplace platforms or ERPs with the Marketplaces Hub.

First steps

To start developing your system's integration with the Marketplaces Hub, you will need an account in the sandbox environment, so that you can test all the features available in the API before going to production.

Click the button below and request your account in the sandbox environment.

I want to request my sandbox account

Once you have finished testing, you must request approval of your application by filling out the form with evidence of the integrated functionalities. Then, our support team will analyze the information sent and, if everything is correct, your application will be approved and you will receive the production AppToken, which must be used to integrate all the sellers of your system into production.

The approval process will be done only once and, after approval, your application will be able to work in production.

If your application is in production and many errors are reported, you can have your AppToken revoked and will have to go through the approval process again

Click the button below to request approval of your integration.

I have already developed the integration and want to request approval

Endpoints

The production and approval environments are divided and can be accessed via the URLs below:

Sandbox

  • API: https://omni.sandbox.wapstore.com.br/omni-api
  • Portal: https: //omni.sandbox.wapstore.com.br

Production

  • API: https://omni.wapstore.com.br/omni-api
  • Portal: https:// omni.wapstore.com.br

Response Headers

POST, PUT and DELETE requests have some useful headers in their response, containing the ID of the generated request (Request-Id) and the request limits for each endpoint (X-RateLimit -Limit and X-RateLimit-Remaining). If you encounter problems with a request, simply inform the support team of the request ID, as this will make it easier to obtain the logs and reduce the time it takes to fix the problem.

Response header example
Cache-Control: no-cache, private
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
Request-Id: 1R17E20190510133646C1557506206412V9676

Authentication

The Marketplace Hub APIs have two levels of authentication: Application authentication and Integration authentication.

Application authentication

All integrated applications have an identification token called AppToken which must be sent in the header of all requests, as without it, it is not possible to identify the connected application and its connection will be denied immediately.

In production, each application has a unique AppToken, however in approval, all applications must use the homologacao AppToken, as shown in the example below:

Header example with AppToken
App-Token: homologacao
Content-Type: application/json
cache-control: no-cache

Integration authentication

The second level of authentication is that of integration, that is, of the seller's account to be requested.

Integration authentication is done using a temporary access token, generated in the authentication and which must be sent in the header of all requests in the Authorization index (except the authentication request, where only the AppToken must be sent).

Example of header with Authorization
App-Token: homologacao
Content-Type: application/json
cache-control: no-cache
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvYXBpLm9tbmkud2Fwc3RvcmUuY29tLmJyXC8iLCJhdWQiOiJBcGkgZGUgVGVzdGUiLCJpYXQiOjE1NTc0MjgzMjcsIm5iZiI6MTU1NzQyODMyNywiZXhwIjoxNTU3NDMwMTI3LCJ0aWQiOiIwOWI4ZGI5YWYxNjhkMDRhMmE2OTBhNTQ1NmEyZWRmMSJ9.Gfvm1Z54pUXZhlNhafV1fEoOBiMGS_sku4o2a8CKWmY

Firewall and security (TLS/SSL)

In production, we have several protection services connected (firewall, anti-DDoS protection, always updated TLS, among others) and all of these services work to guarantee the integrity of the system (mainly because the data that passes through the platform is sensitive - data card numbers, addresses, etc.).

So that your system is not blocked by our security services and can create stable communication with our production APIs, it is extremely important that all requests are sent valid user-agents, all connections are made using the HTTPS protocol and that your system supports the most up-to-date TLS/SSL certificates (use an online service such as SSL Labs to check which TLS/SSL certificate is supported by production servers).

In addition, the use of a fixed IP in requests production is also very important, as our infrastructure and security team can create specific rules for this IP, which greatly increases security and reduces the risk of blocking.

In the approval environment, the risk of blocking by security services is low, so always develop your application focusing on the maximum levels of security that will be required in production.

Authorization

POST /v1/auth

Resource responsible for generating the integration authentication token.

For this resource, the only token that must be sent in the header is the AppToken, as at this moment you have not yet will have the integration token.
The data sent in the body (ApiKey and SecretKey) is related to the Seller's integration account (approval or production account).

After the token is generated, it will be valid for 30 minutes and must be sent in the Authorization header of other APIs.

Important: Whenever a new token is generated, the previous one will be revoked and you will lose access immediately.

Endpoint information
Environment Sandbox / Production
Success Status 201 Created

Request

Example of authorization request
{
	"apiKey": "1234A5678B9012C3456",
	"secretKey":"3456D9012E5678F1234"
}

Request details

Field Type Mandatory Description
apiKey String Yes Seller integration API public key
secretKey String Yes Seller Integration API Private Key

Response

Example of authorization response (generated token)
{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvYXBpLm9tbmkud2Fwc3RvcmUuY29tLmJyXC8iLCJhdWQiOiJBcGkgZGUgVGVzdGUiLCJpYXQiOjE1NTc0NTc2OTYsIm5iZiI6MTU1NzQ1NzY5NiwiZXhwIjoxNTU3NDU5NDk2LCJ0aWQiOiI5MzRjZTY2ZGY5MDQ1YWNmMzY1MGIyZWEzNWUxYjMwMSJ9.Ii148QGob19NI2-fsMbqvMpmVFyGR3bkJjSbOxaCxmg"
}

Response details

Field Type Description
token String Access token generated for the APIs

Ping (Test)

GET /v1/ping

Token test route. Use this URL to test the token generated in the authorization resource. If you receive the word 'pong' (in plain text), it means that your request was successfully authenticated, that is, your AppToken and temporary token are valid.

Endpoint information
Environment Sandbox / Production
Success Status 200 Ok

Webhook de atualizações

Recurso responsável por notificar uma url configurada sempre que houver uma atualização de pedido dentro do HUB.

URL

A url configurada será receptora das notificações e deverá responder com o status HTTP 200 OK e retornando os campos "idInterno" e "status" a todas notificações. Caso o status code seja diferente ou não retorne os campos esperados, o webhook será inativado automaticamente, sendo necessário a ativação novamente pelo painel do HUB.

Confirmação de leitura

É extremamente importante que, após o consumo de uma atualização de um item na api, a confirmação de leitura desse item seja realizada, para remover o item da fila e possibilitar que futuras atualizações do mesmo sejam sincronizadas. Você também pode ativar através do painel do HUB a confirmação de leitura da fila de forma automática, ou seja, assim que a notificação de um item é enviada, o mesmo é removido da fila de atualizações, sem necessitar uma confirmação manual de leitura nas rotas de api.

Recomendamos fortemente que habilite a leitura de pedidos de forma automática para evitar inconsistências nas notificações. Porém caso deseje manter o processo manual pode deixar a configuração desabilitada e neste caso deverá realizar a confirmação da leitura da notificação através das rotas disponíveis.

Notificações

Cada notificação possui o id do pedido no HUB, o domínio da fila referente à notificação atual, urls de leitura e confirmação de leitura (quando em confirmação manual), a data de envio da requisição

Exemplo de notificação
{
  "id": 123321456,
  "dominio":"pedido",
  "urlLeitura":"GET http://localhost/omni/omni-api/v1/order/{idPedido}",
  "urlConfirmacaoLeitura":"confirmacao-automatica",
  "data":"2022-10-14 08:12:17"
}

Products

The following features allow complete management of products and their variations.

Important: Products can also be changed via the dashboard, however changes will be lost if of new updates coming from the API.


GET /v1/products

Resource responsible for listing all registered products, ordered by registration date.

In this resource, only the basic product data will be returned, making it necessary to make a call to the individual product query resource to obtain all data about a specific product.

Endpoint information
Environment Sandbox / Production
Success Status 200 Ok
Offset/Limit Mandatory the sending of the offset and limit parameters in the request URL.
Example of requisition: /v1/products?offset=0&limit=100
Maximum value for the limit parameter: 100

Response

Product inquiry response example
{
    "produtos": [
        {
            "skuProdutoLider": "HDEXT1TB",
            "skuProduto": "HDEXT1TB",
            "nome": "HD externo 1tb",
            "ativo": true,
            "precoDe":350.00,
            "precoPor":299.99,
            "precoDeMidia":350.00,
            "precoPorMidia":299.99,
            "estoque": 0,
            "prazoProducao": 1,
            "links": {
                "GET": "https://api.sandbox.omni.wapstore.com.br/v1/products/HDEXT1TB",
                "PUT": "https://api.sandbox.omni.wapstore.com.br/v1/products/HDEXT1TB"
            }
        },
        {
            "skuProdutoLider": "SLTALTOVERMELHO",
            "skuProduto": "SLTALTOVERMELHO",
            "nome": "Salto alto vermelho",
            "ativo": true,
            "precoDe": 199,
            "precoPor": 129.5,
            "precoDeMidia": 199,
            "precoPorMidia": 129.5,
            "estoque": 0,
            "prazoProducao": 2,
            "links": {
                "GET": "https://api.sandbox.omni.wapstore.com.br/v1/products/SLTALTOVERMELHO",
                "PUT": "https://api.sandbox.omni.wapstore.com.br/v1/products/SLTALTOVERMELHO"
            }
        },
        {
            "skuProdutoLider": "FURADEIRAABC",
            "skuProduto": "FURADEIRAABC",
            "nome": "Furadeira profissional 800w",
            "ativo": true,
            "precoDe": 199,
            "precoPor": 199,
            "precoDeMidia": 199,
            "precoPorMidia": 199,
            "estoque": 0,
            "prazoProducao": 1,
            "links": {
                "GET": "https://api.sandbox.omni.wapstore.com.br/v1/products/FURADEIRAABC",
                "PUT": "https://api.sandbox.omni.wapstore.com.br/v1/products/FURADEIRAABC"
            }
        }
    ],
    "info": {
        "filtros": [],
        "prev": "",
        "self": "https://api.sandbox.omni.wapstore.com.br/v1/products?offset=0&limit=100",
        "next": "",
        "offset": 0,
        "limit": 100,
        "exibindo": 3,
        "total": 3
    }
}

Response details

Field Type Description
produtos Data Collection Products listed
   skuProduto String Product SKU
   skuProdutoLider String Leading Product SKU
   nome String Product name
   precoDe Number Product 'from' price
   precoPor Number Price 'per' of the product
   precoDeMidia Number 'From' price of the product for media channels (Google Shopping, Buscapé, etc.)
   precoPorMidia Number Price 'per' of the product for media channels (Google Shopping, Buscapé, etc.)
   estoque Number Product stock
   prazoProducao Number Product production time in days (added to delivery time)
   ativo Boolean Product Status
   links Object Useful product links in the API
      GET String Endpoint for consulting complete product data
      PUT String Endpoint to change product data
info Object Information about the listing (paging, filters, total items, etc.)
   filtros Object (key/value) Filters applied to the URL
   prev String Previous page
   self String Current page
   next String Next page
   offset Number Requested offset
   limit Number Limit requested
   exibindo Number Number of records being displayed on the current page
   total Number Total records on all pages

GET /v1/products/{sku}

Individual product query resource responsible for returning all registered data for a product.

Endpoint information
Environment Sandbox / Production
Success Status 200 Ok
/v1/products/{sku} Product SKU (skuProduto)

Response

Example of a query response for a product with color and size
{
    "skuProdutoLider": "SLTALTOVERMELHO",
    "skuProduto": "SLTALTOVERMELHO",
    "nome": "Salto alto vermelho",
    "ativo": true,
    "precoDe": 199,
    "precoPor": 129.5,
    "precoDeMidia": 199,
    "precoPorMidia": 129.5,
    "estoque": 0,
    "prazoProducao": 2,
    "descricao": "<b>Salto alto vermelho com verniz</b><br><ul><li>Solado resistente e muito confortável</li><li>1 ano de garantia</li></ul>",
    "descricaoCurta": "Salto alto cor vermlho com verniz",
    "descricaoSimples": "Salto alto vermelho com verniz, solado resistente e muito confortável. Acompanha nota fiscal. 1 ano de garantia.",
    "altura":10.00,
    "largura":15.00,
    "comprimento":25.00,
    "peso":0.500,
    "ean": "1234567890128",
    "mpn": "",
    "ncm": "",
    "idCategoriaGoogle": 0,
    "condicao": "novo",
    "faixaEtaria": "adulto",
    "genero": "feminino",
    "urlProduto": "",
    "urlVideo": "",
    "marca": "Teste API",
    "categoria": [
        "Moda e Acessórios",
        "Sapatos",
        "Salto Alto"
    ],
    "caracteristicas": {
        "Garantia": "1 ano"
    },
    "tags": [
        "nacional", "internacional"
    ],
    "imagens": [
        {
            "id": 1,
            "url": "https://www.seusite.com.br/imagens/produto-teste.jpg"
        },
        {
            "id": 2,
            "url": "https://www.seusite.com.br/imagens/produto-teste-2.jpg"
        },
        {
            "id": 3,
            "url": "https://www.seusite.com.br/imagens/produto-teste-3.jpg"
        },
        {
            "id": 4,
            "url": "https://www.seusite.com.br/imagens/produto-teste-4.jpg"
        }
    ],
    "cor": "Vermelho",
    "variacoes": [
        {
            "skuProduto": "SLTALTOVERMELHO",
            "skuVariacao": "SLTALTOVERMELHO-37",
            "ean": "1234567890128",
            "tamanho": "37",
            "precoDe": 199,
            "precoPor": 129.5,
            "precoDeMidia": 199,
            "precoPorMidia": 129.5,
            "estoque": 0,
            "altura":10.00,
            "largura":15.00,
            "comprimento":25.00,
            "peso":0.500
        },
        {
            "skuProduto": "SLTALTOVERMELHO",
            "skuVariacao": "SLTALTOVERMELHO-38",
            "ean": "1234567890128",
            "tamanho": "38",
            "precoDe": 199,
            "precoPor": 129.5,
            "precoDeMidia": 199,
            "precoPorMidia": 129.5,
            "estoque": 0,
            "altura":10.00,
            "largura":15.00,
            "comprimento":25.00,
            "peso":0.500
        }
    ]
}

Response details

Field Type Description
skuProduto String Product SKU
skuProdutoLider String Leading Product SKU
nome String Product name
descricao String Full product description (may contain HTML)
descricaoCurta String Short description of the product (some marketplaces use this description instead of the full description)
descricaoSimples String Full product description without HTML
ncm String Product NCM code
ean String Product EAN/GTIN/DUN code
mpn String MPN Code
condicao String Condition/status of the product
Accepted values: indefinido, novo, usado, recondicionado
faixaEtaria String Age group the product is intended for
Accepted values: indefinido, recem-nascido, 3-a-12-meses, 1-a-5-anos, infantil, adulto
genero String Gender the product is intended for
Accepted values: indefinido, masculino, feminino, unissex
idCategoriaGoogle String Product Google Category ID
precoDe Number Product 'from' price
precoPor Number Price 'per' of the product
precoDeMidia Number 'From' price of the product for media channels (Google Shopping, Buscapé, etc.)
precoPorMidia Number Price 'per' of the product for media channels (Google Shopping, Buscapé, etc.)
estoque Number Product stock
prazoProducao Number Product production time in days (added to delivery time)
ativo Boolean Product Status
altura Number Height in cm
largura Number Width in cm
comprimento Number Length in cm
peso Number Weight in kg
categoria Array de strings Product category hierarchy
marca String Product brand
imagens Data Collection Product Images
Minimum size: 1 | Maximum size: 4
   id Number Image platform ID
Minimum size: 1 | Maximum size: 250
   url String Image URL
Minimum value: 1 | Maximum value: 250
urlVideo String Product video URL (YouTube, Vimeo, etc)
urlProduto String Product URL on your website
caracteristicas Object (key/value) Product features
tags Array de strings Tags do produto
cor String Product color
variacoes Data Collection Product size and voltage variations
   skuProduto String Product SKU
   skuVariacao String Variation SKU
   tamanho String Size (S,M,L,39,40,etc)
   voltagem String Voltage (110v, 220v, etc.)
   precoDe Number Variation 'from' price
   precoPor Number Price 'per' of the variation (cannot be greater than the 'priceFrom' field)
   precoDeMidia Number Variation 'from' price for media channels (Google Shopping, Buscapé, etc.)
   precoPorMidia Number Variation 'per' price for media channels (Google Shopping, Buscapé, etc.)
   estoque Number Variation Stock
   ean String Item EAN/GTIN/DUN code
   altura Number Height in cm
   largura Number Width in cm
   comprimento Number Length in cm
   peso Number Weight in kg

GET /v1/products/variation/{sku}

Individual query resource for a variation (voltage/size) of a product, responsible for returning all registered data for a variation

Endpoint information
Environment Sandbox / Production
Success Status 200 Ok
/v1/products/variation/{sku} Variation SKU (skuVariacao)

Response

Example query response from a variation
{
    "skuProduto": "FURADEIRAABC",
    "skuVariacao": "FURADEIRAABC-220v",
    "ean": "1234567890128",
    "voltagem": "220v",
    "precoDe": 199,
    "precoPor": 199,
    "precoDeMidia": 199,
    "precoPorMidia": 199,
    "estoque": 0,
    "altura": 10,
    "largura": 15,
    "comprimento": 25,
    "peso": 1
}

Response details

Field Type Description
skuProduto String Product SKU
skuVariacao String Variation SKU
tamanho String Size (S,M,L,39,40,etc)
voltagem String Voltage (110v, 220v, etc.)
precoDe Number Variation 'from' price
precoPor Number Price 'per' of the variation (cannot be greater than the 'priceFrom' field)
precoDeMidia Number Variation 'from' price for media channels (Google Shopping, Buscapé, etc.)
precoPorMidia Number Variation 'per' price for media channels (Google Shopping, Buscapé, etc.)
estoque Number Variation Stock
ean String Item EAN/GTIN/DUN code
altura Number Height in cm
largura Number Width in cm
comprimento Number Length in cm
peso Number Weight in kg

POST /v1/products

Individual product registration feature, responsible for registering a product per request.

Each product can only have one color and vary by size or voltage, that is, it is not possible to have more than one color in the same product or the same product has variations in size and voltage at the same time. To have products with different colors, simply register the two products, linking them using the skuProdutoLider field. If the current product is a leader (leader of color variations or a single product, without variations), send the same SKU in the skuProduto and skuProdutoLider fields.

Important: the leader product must be registered before the child products.

Endpoint information
Environment Sandbox / Production
Success Status 201 Created
Limit requests per minute 60

Requests

Example of a simple product registration request
{
  "skuProduto":"HDEXT1TB",
  "skuProdutoLider":"HDEXT1TB",
  "nome":"HD externo 1tb",
  "descricao":"<b>HD externo de 1tb</b><br><ul><li>Conexão USB 3.0</li><li>1 ano de garantia</li></ul>",
  "descricaoCurta":"HD externo 1tb com conexão USB 3.0",
  "descricaoSimples":"HD externo de 1tb com Conexão USB 3.0, 1 ano de garantia e acompanha cabo USB.",
  "ean":"1234567890128",
  "condicao":"novo",
  "idCategoriaGoogle":0,
  "precoDe":350.00,
  "precoPor":299.99,
  "ativo":true,
  "prazoProducao":1,
  "altura":2.00,
  "largura":10.00,
  "comprimento":5.00,
  "peso":0.100,
  "caracteristicas":{
      "Armazenamento": "1tb",
      "Garantia": "1 ano",
      "Conexão": "USB 3.0"
  },
  "categoria":[
    "Informática",
    "Acessórios",
    "HDs externos"
  ],
  "tags": [
    "nacional", "internacional"
  ],
  "marca":"MarcaTeste",
  "urlVideo":"https://www.youtube.com.br/?watch=abc123",
  "imagens":[
    {
      "id": 1,
      "url": "https://www.seusite.com.br/imagens/produto-teste.jpg"
    },
    {
      "id": 2,
      "url": "https://www.seusite.com.br/imagens/produto-teste-2.jpg"
    },
    {
      "id": 3,
      "url": "https://www.seusite.com.br/imagens/produto-teste-3.jpg"
    },
    {
      "id": 4,
      "url": "https://www.seusite.com.br/imagens/produto-teste-4.jpg"
    }
  ]
}
Example of a request to register a product with color and size
{
  "skuProduto":"SLTALTOVERMELHO",
  "skuProdutoLider":"SLTALTOVERMELHO",
  "nome":"Salto alto vermelho",
  "descricao":"<b>Salto alto vermelho com verniz</b><br><ul><li>Solado resistente e muito confortável</li><li>1 ano de garantia</li></ul>",
  "descricaoCurta":"Salto alto cor vermlho com verniz",
  "descricaoSimples":"Salto alto vermelho com verniz, solado resistente e muito confortável. Acompanha nota fiscal. 1 ano de garantia.",
  "ean":"1234567890128",
  "condicao":"novo",
  "faixaEtaria":"adulto",
  "genero":"feminino",
  "idCategoriaGoogle":0,
  "precoDe":199.00,
  "precoPor":129.50,
  "ativo":true,
  "prazoProducao":2,
  "altura":10.00,
  "largura":15.00,
  "comprimento":25.00,
  "peso":0.500,
  "caracteristicas":{
      "Garantia": "1 ano"
  },
  "tags": [
    "nacional", "internacional"
  ],
  "categoria":[
    "Moda e Acessórios",
    "Sapatos",
    "Salto Alto"
  ],
  "marca":"Teste API",
  "urlVideo":"https://www.youtube.com.br/?watch=abc123",
  "imagens":[
    {
      "id": 1,
      "url": "https://www.seusite.com.br/imagens/produto-teste.jpg"
    },
    {
      "id": 2,
      "url": "https://www.seusite.com.br/imagens/produto-teste-2.jpg"
    },
    {
      "id": 3,
      "url": "https://www.seusite.com.br/imagens/produto-teste-3.jpg"
    },
    {
      "id": 4,
      "url": "https://www.seusite.com.br/imagens/produto-teste-4.jpg"
    }
  ],
  "cor":"Vermelho",
  "variacoes":[
  	{
      "skuVariacao":"SLTALTOVERMELHO-37",
      "tamanho":"37",
      "precoDe":199.00,
      "precoPor":129.50
    },
    {
      "skuVariacao":"SLTALTOVERMELHO-38",
      "tamanho":"38",
      "precoDe":199.00,
      "precoPor":129.50
    }
  ]
}
Example of registration request for a product with voltage
{
  "skuProduto":"FURADEIRAABC",
  "skuProdutoLider":"FURADEIRAABC",
  "nome":"Furadeira profissional 800w",
  "descricao":"<b>Furadeira profissional 800w</b><br><ul><li>Indicada para paredes, madeira, metais e até concreto</li><li>1 ano de garantia</li></ul>",
  "descricaoCurta":"Furadeira profissional 800w para paredes, madeira, metais e concreto",
  "descricaoSimples":"Furadeira profissional 800w, indicada para paredes, madeira, metais e até concreto com 1 ano de garantia.",
  "ean":"1234567890128",
  "condicao":"novo",
  "idCategoriaGoogle":0,
  "precoDe":199.00,
  "precoPor":199.00,
  "ativo":true,
  "prazoProducao":1,
  "altura":10.00,
  "largura":15.00,
  "comprimento":25.00,
  "peso":1.000,
  "caracteristicas":{
      "Potência": "800w",
      "Garantia": "1 ano"
  },
  "categoria":[
    "Ferramentas",
    "Elétricas",
    "Furadeiras"
  ],
  "tags": [
    "nacional", "internacional"
  ],
  "marca":"Teste API",
  "urlVideo":"https://www.youtube.com.br/?watch=abc123",
  "imagens":[
    {
      "id": 1,
      "url": "https://www.seusite.com.br/imagens/produto-teste.jpg"
    },
    {
      "id": 2,
      "url": "https://www.seusite.com.br/imagens/produto-teste-2.jpg"
    },
    {
      "id": 3,
      "url": "https://www.seusite.com.br/imagens/produto-teste-3.jpg"
    },
    {
      "id": 4,
      "url": "https://www.seusite.com.br/imagens/produto-teste-4.jpg"
    }
  ],
  "variacoes":[
  	{
      "skuVariacao":"FURADEIRAABC-110v",
      "voltagem":"110v",
      "precoDe":199.00,
      "precoPor":199.00
    },
    {
      "skuVariacao":"FURADEIRAABC-220v",
      "voltagem":"220v",
      "precoDe":199.00,
      "precoPor":199.00
    }
  ]
}

Request details

Field Type Mandatory Description
skuProduto String Yes Product SKU
Minimum size: 1 | Maximum size: 250
skuProdutoLider String Yes Leading product SKU. Use this field to link products (if the current product is not linked to another product, send the same value as the 'skuProduto' field)
Minimum size: 1 | Maximum size: 250
nome String Yes Product name
Minimum size: 1 | Maximum size: 250
descricao String Yes Full product description (may contain HTML)
Minimum size: 1
descricaoCurta String No Short description of the product (some marketplaces use this description instead of the full description)
Minimum size: 1
descricaoSimples String No Full product description without HTML. Most marketplaces do not accept descriptions with HTML in the body, so this field must be filled in with the description without HTML tags
Minimum size: 1
ncm String No Product NCM code
ean String Yes Product EAN/GTIN/DUN code
mpn String No MPN Code
condicao String No Condition/status of the product
Accepted values: novo, usado, recondicionado
faixaEtaria String No Age group the product is intended for
Accepted values: recem-nascido, 3-a-12-meses, 1-a-5-anos, infantil, adulto
genero String No Gender the product is intended for
Accepted values: masculino, feminino, unissex
idCategoriaGoogle Number No Google category ID of the product. See more details at Google product category
precoDe Number Yes Product 'from' price
Minimum value: 0.01 | Maximum value: 999999.99
precoPor Number Yes Price 'per' of the product (cannot be greater than the 'priceFrom' field)
Minimum value: 0.01 | Maximum value: 999999.99
precoDeMidia Number No 'From' price of the product for media channels (Google Shopping, Buscapé, etc.). Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
precoPorMidia Number No Price 'per' of the product for media channels (Google Shopping, Buscapé, etc.). It cannot be greater than the 'priceDeMidia' field. Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
ativo Boolean Yes Product Status
prazoProducao Number Yes Product production time in days (added to delivery time)
altura Number Yes Height in cm
Minimum value: 0.01
largura Number Yes Width in cm
Minimum value: 0.01
comprimento Number Yes Length in cm
Minimum value: 0.01
peso Number Yes Weight in kg
Minimum value: 0.01
categoria Array de strings Yes Product category hierarchy
Minimum size: 1 | Maximum size: 4
marca String Yes Product brand
Minimum size: 1 | Maximum size: 250
imagens Data Collection Yes Product Images
Minimum size: 1 | Maximum size: 4
   id Number Yes Image platform ID
Minimum size: 1 | Maximum size: 250
   url String Yes Image URL
Minimum value: 1 | Maximum value: 250
urlVideo String No Product video URL (YouTube, Vimeo, etc). Not all marketplaces accept videos
Maximum size: 250
Valid URL: e.g. https://sualoja.com.br/retorno
urlProduto String No Product URL on your website
Minimum size: 1 | Maximum size: 250
Valid URL: e.g. https://sualoja.com.br/retorno
caracteristicas Object (key/value) No Product features
Maximum size: 100
tags Array de strings No Tags do produto
cor String No Product color (If the product has more than one color, send it as an example: 'Black and Red')
Minimum size: 1 | Maximum size: 250
variacoes Data Collection No Product size and voltage variations
   skuVariacao String Yes Variation SKU
Minimum size: 1 | Maximum size: 250
   tamanho String No Size (S,M,L,39,40,etc)
Minimum size: 1 | Maximum size: 250
   voltagem String No Voltage (110v, 220v, etc.)
Minimum size: 1 | Maximum size: 250
   precoDe Number Yes Variation 'from' price
Minimum value: 0.01 | Maximum value: 999999.99
   precoPor Number Yes Price 'per' of the variation (cannot be greater than the 'priceFrom' field)
Minimum value: 0.01 | Maximum value: 999999.99
   precoDeMidia Number No Variation 'from' price for media channels (Google Shopping, Buscapé, etc.). Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
   precoPorMidia Number No Variation 'per' price for media channels (Google Shopping, Buscapé, etc.). It cannot be greater than the 'priceDeMidia' field. Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
   ean String No 13-digit EAN/GTIN code
   altura Number No Height in cm
Minimum value: 0.01
   largura Number No Width in cm
Minimum value: 0.01
   comprimento Number No Length in cm
Minimum value: 0.01
   peso Number No Weight in kg
Minimum value: 0.001

Response

Example of a product registration response with color and size
{
    "skuProdutoLider": "SLTALTOVERMELHO",
    "skuProduto": "SLTALTOVERMELHO",
    "nome": "Salto alto vermelho",
    "ativo": true,
    "precoDe": 199,
    "precoPor": 129.5,
    "precoDeMidia": 199,
    "precoPorMidia": 129.5,
    "estoque": 0,
    "prazoProducao": 2,
    "descricao": "<b>Salto alto vermelho com verniz</b><br><ul><li>Solado resistente e muito confortável</li><li>1 ano de garantia</li></ul>",
    "descricaoCurta": "Salto alto cor vermlho com verniz",
    "descricaoSimples": "Salto alto vermelho com verniz, solado resistente e muito confortável. Acompanha nota fiscal. 1 ano de garantia.",
    "altura":10.00,
    "largura":15.00,
    "comprimento":25.00,
    "peso":0.500,
    "ean": "1234567890128",
    "mpn": "",
    "ncm": "",
    "idCategoriaGoogle": 0,
    "condicao": "novo",
    "faixaEtaria": "adulto",
    "genero": "feminino",
    "urlProduto": "",
    "urlVideo": "",
    "marca": "Teste API",
    "categoria": [
        "Moda e Acessórios",
        "Sapatos",
        "Salto Alto"
    ],
    "caracteristicas": {
        "Garantia": "1 ano"
    },
    "tags": [
        "nacional", "internacional"
    ],
    "imagens": [
        {
            "id": 1,
            "url": "https://www.seusite.com.br/imagens/produto-teste.jpg"
        },
        {
            "id": 2,
            "url": "https://www.seusite.com.br/imagens/produto-teste-2.jpg"
        },
        {
            "id": 3,
            "url": "https://www.seusite.com.br/imagens/produto-teste-3.jpg"
        },
        {
            "id": 4,
            "url": "https://www.seusite.com.br/imagens/produto-teste-4.jpg"
        }
    ],
    "cor": "Vermelho",
    "variacoes": [
        {
            "skuProduto": "SLTALTOVERMELHO",
            "skuVariacao": "SLTALTOVERMELHO-37",
            "ean": "1234567890128",
            "tamanho": "37",
            "precoDe": 199,
            "precoPor": 129.5,
            "precoDeMidia": 199,
            "precoPorMidia": 129.5,
            "estoque": 0,
            "altura":10.00,
            "largura":15.00,
            "comprimento":25.00,
            "peso":0.500
        },
        {
            "skuProduto": "SLTALTOVERMELHO",
            "skuVariacao": "SLTALTOVERMELHO-38",
            "ean": "1234567890128",
            "tamanho": "38",
            "precoDe": 199,
            "precoPor": 129.5,
            "precoDeMidia": 199,
            "precoPorMidia": 129.5,
            "estoque": 0,
            "altura":10.00,
            "largura":15.00,
            "comprimento":25.00,
            "peso":0.500
        }
    ]
}

Response details

Field Type Description
skuProduto String Product SKU
skuProdutoLider String Leading Product SKU
nome String Product name
descricao String Full product description (may contain HTML)
descricaoCurta String Short description of the product (some marketplaces use this description instead of the full description)
descricaoSimples String Full product description without HTML
ncm String Product NCM code
ean String Product EAN/GTIN/DUN code
mpn String MPN Code
condicao String Condition/status of the product
Accepted values: indefinido, novo, usado, recondicionado
faixaEtaria String Age group the product is intended for
Accepted values: indefinido, recem-nascido, 3-a-12-meses, 1-a-5-anos, infantil, adulto
genero String Gender the product is intended for
Accepted values: indefinido, masculino, feminino, unissex
idCategoriaGoogle String Product Google Category ID
precoDe Number Product 'from' price
precoPor Number Price 'per' of the product
precoDeMidia Number 'From' price of the product for media channels (Google Shopping, Buscapé, etc.)
precoPorMidia Number Price 'per' of the product for media channels (Google Shopping, Buscapé, etc.)
estoque Number Product stock
prazoProducao Number Product production time in days (added to delivery time)
ativo Boolean Product Status
altura Number Height in cm
largura Number Width in cm
comprimento Number Length in cm
peso Number Weight in kg
categoria Array de strings Product category hierarchy
marca String Product brand
imagens Data Collection Product Images
Minimum size: 1 | Maximum size: 4
   id Number Image platform ID
Minimum size: 1 | Maximum size: 250
   url String Image URL
Minimum value: 1 | Maximum value: 250
urlVideo String Product video URL (YouTube, Vimeo, etc)
urlProduto String Product URL on your website
caracteristicas Object (key/value) Product features
tags Array de strings Tags do produto
cor String Product color
variacoes Data Collection Product size and voltage variations
   skuProduto String Product SKU
   skuVariacao String Variation SKU
   tamanho String Size (S,M,L,39,40,etc)
   voltagem String Voltage (110v, 220v, etc.)
   precoDe Number Variation 'from' price
   precoPor Number Price 'per' of the variation (cannot be greater than the 'priceFrom' field)
   precoDeMidia Number Variation 'from' price for media channels (Google Shopping, Buscapé, etc.)
   precoPorMidia Number Variation 'per' price for media channels (Google Shopping, Buscapé, etc.)
   estoque Number Variation Stock
   ean String Item EAN/GTIN/DUN code
   altura Number Height in cm
   largura Number Width in cm
   comprimento Number Length in cm
   peso Number Weight in kg

POST /v1/products/batch

Batch product registration feature, responsible for registering several products at once. The restrictions for color, size, voltage and product link registrations are the same as those for the individual registration feature.

Important: if the same batch has a leader product and its children, the leader product must come before its child products.

Use the batch query feature to check the processing status of the created batch.

Endpoint information
Environment Sandbox / Production
Success Status 201 Created
Limit requests per minute 10

Request

Example of request to register products in batch
{
  "produtos":[
    {
      "skuProduto":"HDEXT1TB",
      "skuProdutoLider":"HDEXT1TB",
      "nome":"HD externo 1tb",
      "descricao":"<b>HD externo de 1tb</b><br><ul><li>Conexão USB 3.0</li><li>1 ano de garantia</li></ul>",
      "descricaoCurta":"HD externo 1tb com conexão USB 3.0",
      "descricaoSimples":"HD externo de 1tb com Conexão USB 3.0, 1 ano de garantia e acompanha cabo USB.",
      "ean":"1234567890128",
      "condicao":"novo",
      "idCategoriaGoogle":0,
      "precoDe":350.00,
      "precoPor":299.99,
      "ativo":true,
      "prazoProducao":1,
      "altura":2.00,
      "largura":10.00,
      "comprimento":5.00,
      "peso":0.100,
      "caracteristicas":{
          "Armazenamento": "1tb",
          "Garantia": "1 ano",
          "Conexão": "USB 3.0"
      },
      "tags": [
        "nacional", "internacional"
      ],
      "categoria":[
        "Informática",
        "Acessórios",
        "HDs externos"
      ],
      "marca":"MarcaTeste",
      "urlVideo":"https://www.youtube.com.br/?watch=abc123",
      "imagens":[
        { 
          "id": 1,
          "url": "https://www.seusite.com.br/imagens/produto-teste.jpg"
        },
        { 
          "id": 2,
          "url": "https://www.seusite.com.br/imagens/produto-teste-2.jpg"
        },
        { 
          "id": 3,
          "url": "https://www.seusite.com.br/imagens/produto-teste-3.jpg"
        },
        { 
          "id": 4,
          "url": "https://www.seusite.com.br/imagens/produto-teste-4.jpg"
        }
      ]
    }
  ]
}

Request details

Field Type Mandatory Description
produtos Data Collection Yes Lot of products
Minimum size: 1 | Maximum size: 100
   skuProduto String Yes Product SKU
Minimum size: 1 | Maximum size: 250
   skuProdutoLider String Yes Leading product SKU. Use this field to link products (if the current product is not linked to another product, send the same value as the 'skuProduto' field)
Minimum size: 1 | Maximum size: 250
   nome String Yes Product name
Minimum size: 1 | Maximum size: 250
   descricao String Yes Full product description (may contain HTML)
Minimum size: 1
   descricaoCurta String No Short description of the product (some marketplaces use this description instead of the full description)
Minimum size: 1
   descricaoSimples String No Full product description without HTML. Most marketplaces do not accept descriptions with HTML in the body, so this field must be filled in with the description without HTML tags
Minimum size: 1
   ncm String No Product NCM code
   ean String Yes Product EAN/GTIN/DUN code
   mpn String No MPN Code
   condicao String No Condition/status of the product
Accepted values: novo, usado, recondicionado
   faixaEtaria String No Age group the product is intended for
Accepted values: recem-nascido, 3-a-12-meses, 1-a-5-anos, infantil, adulto
   genero String No Gender the product is intended for
Accepted values: masculino, feminino, unissex
   idCategoriaGoogle Number No Google category ID of the product. See more details at Google product category
   precoDe Number Yes Product 'from' price
Minimum value: 0.01 | Maximum value: 999999.99
   precoPor Number Yes Price 'per' of the product (cannot be greater than the 'priceFrom' field)
Minimum value: 0.01 | Maximum value: 999999.99
   precoDeMidia Number No 'From' price of the product for media channels (Google Shopping, Buscapé, etc.). Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
   precoPorMidia Number No Price 'per' of the product for media channels (Google Shopping, Buscapé, etc.). It cannot be greater than the 'priceDeMidia' field. Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
   ativo Boolean Yes Product Status
   prazoProducao Number Yes Product production time in days (added to delivery time)
   altura Number Yes Height in cm
Minimum value: 0.01
   largura Number Yes Width in cm
Minimum value: 0.01
   comprimento Number Yes Length in cm
Minimum value: 0.01
   peso Number Yes Weight in kg
Minimum value: 0.01
   categoria Array de strings Yes Product category hierarchy
Minimum size: 1 | Maximum size: 4
   marca String Yes Product brand
Minimum size: 1 | Maximum size: 250
   imagens Data Collection Yes Product Images
Minimum size: 1 | Maximum size: 4
      id Number Yes Image platform ID
Minimum size: 1 | Maximum size: 250
      url String Yes Image URL
Minimum value: 1 | Maximum value: 250
   urlVideo String No Product video URL (YouTube, Vimeo, etc). Not all marketplaces accept videos
Maximum size: 250
Valid URL: e.g. https://sualoja.com.br/retorno
   urlProduto String No Product URL on your website
Minimum size: 1 | Maximum size: 250
Valid URL: e.g. https://sualoja.com.br/retorno
   caracteristicas Object (key/value) No Product features
Maximum size: 100
   tags Array de strings No Tags do produto
   cor String No Product color (If the product has more than one color, send it as an example: 'Black and Red')
Minimum size: 1 | Maximum size: 250
   variacoes Data Collection No Product size and voltage variations
      skuVariacao String Yes Variation SKU
Minimum size: 1 | Maximum size: 250
      tamanho String No Size (S,M,L,39,40,etc)
Minimum size: 1 | Maximum size: 250
      voltagem String No Voltage (110v, 220v, etc.)
Minimum size: 1 | Maximum size: 250
      precoDe Number Yes Variation 'from' price
Minimum value: 0.01 | Maximum value: 999999.99
      precoPor Number Yes Price 'per' of the variation (cannot be greater than the 'priceFrom' field)
Minimum value: 0.01 | Maximum value: 999999.99
      precoDeMidia Number No Variation 'from' price for media channels (Google Shopping, Buscapé, etc.). Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
      precoPorMidia Number No Variation 'per' price for media channels (Google Shopping, Buscapé, etc.). It cannot be greater than the 'priceDeMidia' field. Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
      ean String No 13-digit EAN/GTIN code
      altura Number No Height in cm
Minimum value: 0.01
      largura Number No Width in cm
Minimum value: 0.01
      comprimento Number No Length in cm
Minimum value: 0.01
      peso Number No Weight in kg
Minimum value: 0.001

Response

Sample batch creation response
{
    "id": 80
}

Response details

Field Type Description
id Number Generated batch ID

PUT /v1/products/{sku}

Individual product change feature, responsible for changing product information.

Important: once registered, a product cannot have the skuProdutoLider fields or skuProduto changed, if any color is defined for the product (in registration or in an update), it cannot be removed via API and it is not possible to remove size or voltage variations via API.

Endpoint information
Environment Sandbox / Production
Success Status 200 Ok
/v1/products/{sku} Product SKU (skuProduto)
Limit requests per minute 60

Request

Example of a request to change just some product fields
{
  "skuProduto": "SLTALTOVERMELHO",
  "nome": "Salto alto vermelho",
  "ativo": true,
  "precoDe": 199,
  "precoPor": 129.5
}

Request details

Field Type Mandatory Description
skuProduto String Yes Product SKU
Minimum size: 1 | Maximum size: 250
nome String No Product name
Minimum size: 1 | Maximum size: 250
descricao String No Full product description (may contain HTML)
Minimum size: 1
descricaoCurta String No Short description of the product (some marketplaces use this description instead of the full description)
Minimum size: 1
descricaoSimples String No Full product description without HTML. Most marketplaces do not accept descriptions with HTML in the body, so this field must be filled in with the description without HTML tags
Minimum size: 1
ncm String No Product NCM code
ean String No Product EAN/GTIN/DUN code
mpn String No MPN Code
condicao String No Condition/status of the product
Accepted values: novo, usado, recondicionado
faixaEtaria String No Age group the product is intended for
Accepted values: recem-nascido, 3-a-12-meses, 1-a-5-anos, infantil, adulto
genero String No Gender the product is intended for
Accepted values: masculino, feminino, unissex
idCategoriaGoogle Number No Google category ID of the product. See more details at Google product category
precoDe Number Yes Product 'from' price
Minimum value: 0.01 | Maximum value: 999999.99
precoPor Number Yes Price 'per' of the product (cannot be greater than the 'priceFrom' field)
Minimum value: 0.01 | Maximum value: 999999.99
precoDeMidia Number No 'From' price of the product for media channels (Google Shopping, Buscapé, etc.). Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
precoPorMidia Number No Price 'per' of the product for media channels (Google Shopping, Buscapé, etc.). It cannot be greater than the 'priceDeMidia' field. Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
ativo Boolean No Product Status
prazoProducao Number No Product production time in days (added to delivery time)
altura Number No Height in cm
Minimum value: 0.01
largura Number No Width in cm
Minimum value: 0.01
comprimento Number No Length in cm
Minimum value: 0.01
peso Number No Weight in kg
Minimum value: 0.01
categoria Array de strings No Product category hierarchy
Minimum size: 1 | Maximum size: 4
marca String No Product brand
Minimum size: 1 | Maximum size: 250
imagens Data Collection No Product Images
Minimum size: 1 | Maximum size: 4
   id Number Yes Image platform ID
Minimum size: 1 | Maximum size: 250
   url String Yes Image URL
Minimum value: 1 | Maximum value: 250
urlVideo String No Product video URL (YouTube, Vimeo, etc). Not all marketplaces accept videos
Maximum size: 250
Valid URL: e.g. https://sualoja.com.br/retorno
urlProduto String No Product URL on your website
Minimum size: 1 | Maximum size: 250
Valid URL: e.g. https://sualoja.com.br/retorno
caracteristicas Object (key/value) No Product features
Maximum size: 100
tags Array de strings No Tags do produto
cor String No Product color (If the product has more than one color, send it as an example: 'Black and Red')
Minimum size: 1 | Maximum size: 250
variacoes Data Collection No Product size and voltage variations
   skuVariacao String Yes Variation SKU
Minimum size: 1 | Maximum size: 250
   tamanho String No Size (S,M,L,39,40,etc)
Minimum size: 1 | Maximum size: 250
   voltagem String No Voltage (110v, 220v, etc.)
Minimum size: 1 | Maximum size: 250
   precoDe Number Yes Variation 'from' price
Minimum value: 0.01 | Maximum value: 999999.99
   precoPor Number Yes Price 'per' of the variation (cannot be greater than the 'priceFrom' field)
Minimum value: 0.01 | Maximum value: 999999.99
   precoDeMidia Number No Variation 'from' price for media channels (Google Shopping, Buscapé, etc.). Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
   precoPorMidia Number No Variation 'per' price for media channels (Google Shopping, Buscapé, etc.). It cannot be greater than the 'priceDeMidia' field. Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
   ean String No 13-digit EAN/GTIN code
   altura Number No Height in cm
Minimum value: 0.01
   largura Number No Width in cm
Minimum value: 0.01
   comprimento Number No Length in cm
Minimum value: 0.01
   peso Number No Weight in kg
Minimum value: 0.001

Response

Changed product response example
{
    "skuProdutoLider": "SLTALTOVERMELHO",
    "skuProduto": "SLTALTOVERMELHO",
    "nome": "Salto alto vermelho",
    "ativo": true,
    "precoDe": 199,
    "precoPor": 129.5,
    "precoDeMidia": 199,
    "precoPorMidia": 129.5,
    "estoque": 0,
    "prazoProducao": 2,
    "descricao": "<b>Salto alto vermelho com verniz</b><br><ul><li>Solado resistente e muito confortável</li><li>1 ano de garantia</li></ul>",
    "descricaoCurta": "Salto alto cor vermlho com verniz",
    "descricaoSimples": "Salto alto vermelho com verniz, solado resistente e muito confortável. Acompanha nota fiscal. 1 ano de garantia.",
    "altura":10.00,
    "largura":15.00,
    "comprimento":25.00,
    "peso":0.500,
    "ean": "1234567890128",
    "mpn": "",
    "ncm": "",
    "idCategoriaGoogle": 0,
    "condicao": "novo",
    "faixaEtaria": "adulto",
    "genero": "feminino",
    "urlProduto": "",
    "urlVideo": "",
    "marca": "Teste API",
    "categoria": [
        "Moda e Acessórios",
        "Sapatos",
        "Salto Alto"
    ],
    "caracteristicas": {
        "Garantia": "1 ano"
    },
    "tags": [
        "nacional", "internacional"
    ],
    "imagens": [
        {
            "id": 1,
            "url": "https://www.seusite.com.br/imagens/produto-teste.jpg"
        },
        {
            "id": 2,
            "url": "https://www.seusite.com.br/imagens/produto-teste-2.jpg"
        },
        {
            "id": 3,
            "url": "https://www.seusite.com.br/imagens/produto-teste-3.jpg"
        },
        {
            "id": 4,
            "url": "https://www.seusite.com.br/imagens/produto-teste-4.jpg"
        }
    ],
    "cor": "Vermelho",
    "variacoes": [
        {
            "skuProduto": "SLTALTOVERMELHO",
            "skuVariacao": "SLTALTOVERMELHO-37",
            "ean": "1234567890128",
            "tamanho": "37",
            "precoDe": 199,
            "precoPor": 129.5,
            "precoDeMidia": 199,
            "precoPorMidia": 129.5,
            "estoque": 0,
            "altura":10.00,
            "largura":15.00,
            "comprimento":25.00,
            "peso":0.500
        },
        {
            "skuProduto": "SLTALTOVERMELHO",
            "skuVariacao": "SLTALTOVERMELHO-38",
            "ean": "1234567890128",
            "tamanho": "38",
            "precoDe": 199,
            "precoPor": 129.5,
            "precoDeMidia": 199,
            "precoPorMidia": 129.5,
            "estoque": 0,
            "altura":10.00,
            "largura":15.00,
            "comprimento":25.00,
            "peso":0.500
        }
    ]
}

Response details

Field Type Description
skuProduto String Product SKU
skuProdutoLider String Leading Product SKU
nome String Product name
descricao String Full product description (may contain HTML)
descricaoCurta String Short description of the product (some marketplaces use this description instead of the full description)
descricaoSimples String Full product description without HTML
ncm String Product NCM code
ean String Product EAN/GTIN/DUN code
mpn String MPN Code
condicao String Condition/status of the product
Accepted values: indefinido, novo, usado, recondicionado
faixaEtaria String Age group the product is intended for
Accepted values: indefinido, recem-nascido, 3-a-12-meses, 1-a-5-anos, infantil, adulto
genero String Gender the product is intended for
Accepted values: indefinido, masculino, feminino, unissex
idCategoriaGoogle String Product Google Category ID
precoDe Number Product 'from' price
precoPor Number Price 'per' of the product
precoDeMidia Number 'From' price of the product for media channels (Google Shopping, Buscapé, etc.)
precoPorMidia Number Price 'per' of the product for media channels (Google Shopping, Buscapé, etc.)
estoque Number Product stock
prazoProducao Number Product production time in days (added to delivery time)
ativo Boolean Product Status
altura Number Height in cm
largura Number Width in cm
comprimento Number Length in cm
peso Number Weight in kg
categoria Array de strings Product category hierarchy
marca String Product brand
imagens Data Collection Product Images
Minimum size: 1 | Maximum size: 4
   id Number Image platform ID
Minimum size: 1 | Maximum size: 250
   url String Image URL
Minimum value: 1 | Maximum value: 250
urlVideo String Product video URL (YouTube, Vimeo, etc)
urlProduto String Product URL on your website
caracteristicas Object (key/value) Product features
tags Array de strings Tags do produto
cor String Product color
variacoes Data Collection Product size and voltage variations
   skuProduto String Product SKU
   skuVariacao String Variation SKU
   tamanho String Size (S,M,L,39,40,etc)
   voltagem String Voltage (110v, 220v, etc.)
   precoDe Number Variation 'from' price
   precoPor Number Price 'per' of the variation (cannot be greater than the 'priceFrom' field)
   precoDeMidia Number Variation 'from' price for media channels (Google Shopping, Buscapé, etc.)
   precoPorMidia Number Variation 'per' price for media channels (Google Shopping, Buscapé, etc.)
   estoque Number Variation Stock
   ean String Item EAN/GTIN/DUN code
   altura Number Height in cm
   largura Number Width in cm
   comprimento Number Length in cm
   peso Number Weight in kg

PUT /v1/products/variation/{sku}

Individual variation update feature, responsible for changing information about a single variation of a product

Important: it is not possible to change the SKU of a variation.

Endpoint information
Environment Sandbox / Production
Success Status 200 Ok
/v1/products/variation/{sku} Variation SKU (skuVariacao)
Limit requests per minute 60

Request

Example of a request to change some fields of a variation
{
    "skuVariacao": "FURADEIRAABC-220v",
    "ean": "5554443322212",
    "precoDe": 1000.00,
    "precoPor": 200.00,
    "peso": 10.00
}

Request details

Field Type Mandatory Description
skuVariacao String Yes Variation SKU
Minimum size: 1 | Maximum size: 250
tamanho String No Size (S,M,L,39,40,etc)
Minimum size: 1 | Maximum size: 250
voltagem String No Voltage (110v, 220v, etc.)
Minimum size: 1 | Maximum size: 250
precoDe Number Yes Variation 'from' price
Minimum value: 0.01 | Maximum value: 999999.99
precoPor Number Yes Price 'per' of the variation (cannot be greater than the 'priceFrom' field)
Minimum value: 0.01 | Maximum value: 999999.99
precoDeMidia Number No Variation 'from' price for media channels (Google Shopping, Buscapé, etc.). Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
precoPorMidia Number No Variation 'per' price for media channels (Google Shopping, Buscapé, etc.). It cannot be greater than the 'priceDeMidia' field. Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
ean String No 13-digit EAN/GTIN code
altura Number No Height in cm
Minimum value: 0.01
largura Number No Width in cm
Minimum value: 0.01
comprimento Number No Length in cm
Minimum value: 0.01
peso Number No Weight in kg
Minimum value: 0.001

Response

Sample batch creation response
{
    "skuProduto": "FURADEIRAABC",
    "skuVariacao": "FURADEIRAABC-220v",
    "ean": "1234567890128",
    "voltagem": "220v",
    "precoDe": 199,
    "precoPor": 199,
    "precoDeMidia": 199,
    "precoPorMidia": 199,
    "estoque": 0,
    "altura": 10,
    "largura": 15,
    "comprimento": 25,
    "peso": 1
}

Response details

Field Type Description
skuProduto String Product SKU
skuVariacao String Variation SKU
tamanho String Size (S,M,L,39,40,etc)
voltagem String Voltage (110v, 220v, etc.)
precoDe Number Variation 'from' price
precoPor Number Price 'per' of the variation (cannot be greater than the 'priceFrom' field)
precoDeMidia Number Variation 'from' price for media channels (Google Shopping, Buscapé, etc.)
precoPorMidia Number Variation 'per' price for media channels (Google Shopping, Buscapé, etc.)
estoque Number Variation Stock
ean String Item EAN/GTIN/DUN code
altura Number Height in cm
largura Number Width in cm
comprimento Number Length in cm
peso Number Weight in kg

PUT /v1/products/batch

Batch product update feature, responsible for updating multiple products at once. Restrictions for changes are the same as for the individual update feature.

Use the batch query feature to check the processing status of the created batch.

Endpoint information
Environment Sandbox / Production
Success Status 201 Created
Limit requests per minute 10

Request

Example of request to update products in batch
{
  "produtos":[
    {
      "skuProduto":"HDEXT1TB",
      "nome":"HD externo 1tb",
      "descricao":"<b>HD externo de 1tb</b><br><ul><li>Conexão USB 3.0</li><li>1 ano de garantia</li></ul>",
      "descricaoCurta":"HD externo 1tb com conexão USB 3.0",
      "descricaoSimples":"HD externo de 1tb com Conexão USB 3.0, 1 ano de garantia e acompanha cabo USB.",
      "precoDe":350.00,
      "precoPor":299.99,
    }
  ]
}

Request details

Field Type Mandatory Description
produtos Data Collection Yes Lot of products
Minimum size: 1 | Maximum size: 100
   skuProduto String Yes Product SKU
Minimum size: 1 | Maximum size: 250
   nome String No Product name
Minimum size: 1 | Maximum size: 250
   descricao String No Full product description (may contain HTML)
Minimum size: 1
   descricaoCurta String No Short description of the product (some marketplaces use this description instead of the full description)
Minimum size: 1
   descricaoSimples String No Full product description without HTML. Most marketplaces do not accept descriptions with HTML in the body, so this field must be filled in with the description without HTML tags
Minimum size: 1
   ncm String No Product NCM code
   ean String No Product EAN/GTIN/DUN code
   mpn String No MPN Code
   condicao String No Condition/status of the product
Accepted values: novo, usado, recondicionado
   faixaEtaria String No Age group the product is intended for
Accepted values: recem-nascido, 3-a-12-meses, 1-a-5-anos, infantil, adulto
   genero String No Gender the product is intended for
Accepted values: masculino, feminino, unissex
   idCategoriaGoogle Number No Google category ID of the product. See more details at Google product category
   precoDe Number Yes Product 'from' price
Minimum value: 0.01 | Maximum value: 999999.99
   precoPor Number Yes Price 'per' of the product (cannot be greater than the 'priceFrom' field)
Minimum value: 0.01 | Maximum value: 999999.99
   precoDeMidia Number No 'From' price of the product for media channels (Google Shopping, Buscapé, etc.). Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
   precoPorMidia Number No Price 'per' of the product for media channels (Google Shopping, Buscapé, etc.). It cannot be greater than the 'priceDeMidia' field. Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
   ativo Boolean No Product Status
   prazoProducao Number No Product production time in days (added to delivery time)
   altura Number No Height in cm
Minimum value: 0.01
   largura Number No Width in cm
Minimum value: 0.01
   comprimento Number No Length in cm
Minimum value: 0.01
   peso Number No Weight in kg
Minimum value: 0.01
   categoria Array de strings No Product category hierarchy
Minimum size: 1 | Maximum size: 4
   marca String No Product brand
Minimum size: 1 | Maximum size: 250
   imagens Data Collection No Product Images
Minimum size: 1 | Maximum size: 4
      id Number Yes Image platform ID
Minimum size: 1 | Maximum size: 250
      url String Yes Image URL
Minimum value: 1 | Maximum value: 250
   urlVideo String No Product video URL (YouTube, Vimeo, etc). Not all marketplaces accept videos
Maximum size: 250
Valid URL: e.g. https://sualoja.com.br/retorno
   urlProduto String No Product URL on your website
Minimum size: 1 | Maximum size: 250
Valid URL: e.g. https://sualoja.com.br/retorno
   caracteristicas Object (key/value) No Product features
Maximum size: 100
   tags Array de strings No Tags do produto
   cor String No Product color (If the product has more than one color, send it as an example: 'Black and Red')
Minimum size: 1 | Maximum size: 250
   variacoes Data Collection No Product size and voltage variations
      skuVariacao String Yes Variation SKU
Minimum size: 1 | Maximum size: 250
      tamanho String No Size (S,M,L,39,40,etc)
Minimum size: 1 | Maximum size: 250
      voltagem String No Voltage (110v, 220v, etc.)
Minimum size: 1 | Maximum size: 250
      precoDe Number Yes Variation 'from' price
Minimum value: 0.01 | Maximum value: 999999.99
      precoPor Number Yes Price 'per' of the variation (cannot be greater than the 'priceFrom' field)
Minimum value: 0.01 | Maximum value: 999999.99
      precoDeMidia Number No Variation 'from' price for media channels (Google Shopping, Buscapé, etc.). Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
      precoPorMidia Number No Variation 'per' price for media channels (Google Shopping, Buscapé, etc.). It cannot be greater than the 'priceDeMidia' field. Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
      ean String No 13-digit EAN/GTIN code
      altura Number No Height in cm
Minimum value: 0.01
      largura Number No Width in cm
Minimum value: 0.01
      comprimento Number No Length in cm
Minimum value: 0.01
      peso Number No Weight in kg
Minimum value: 0.001

Response

Sample batch creation response
{
    "id": 80
}

Response details

Field Type Description
id Number Generated batch ID

PUT /v1/products/stock-batch

Product inventory batch update feature.

Use the batch query feature to check the processing status of the created batch.

Endpoint information
Environment Sandbox / Production
Success Status 201 Created
Limit requests per minute 10

Request

Example of request to change stocks in batch
{
	"estoques": [
		{
		    "sku": "SLTALTOVERMELHO-37",
		    "estoque":232
		},
		{
			"sku": "SLTALTOVERMELHO-38",
			"estoque":32
		},
		{
			"sku": "HDEXT1TB",
			"estoque":32
		}
	]
}

Request details

Field Type Mandatory Description
estoques Data Collection Yes Lot of stocks
Minimum size: 1 | Maximum size: 100
   sku String Yes Product SKU/variation. Important: products with voltage or size variations cannot receive changes directly to the product's SKU, that is, the SKU sent must be that of the corresponding variation, as the product's total stock is generated from the sum of its size variations and voltage
Minimum size: 1 | Maximum size: 250
   estoque Number Yes Quantity in stock
Minimum value: 0 | Maximum value: 999999

Response

Sample batch creation response
{
    "id": 80
}

Response details

Field Type Description
id Number Generated batch ID

PUT /v1/products/price-batch

Product price batch update feature.

Use the batch query feature to check the processing status of the created batch.

Endpoint information
Environment Sandbox / Production
Success Status 201 Created
Limit requests per minute 10

Request

Example of request to change prices in batch
{
	"precos": [
		{
		    "sku": "SLTALTOVERMELHO-37",
		    "precoDe":190.00,
		    "precoPor":190.00
		},
		{
			"sku": "SLTALTOVERMELHO-38",
			"precoDe":190.00,
		    "precoPor":190.00
		},
		{
			"sku": "HDEXT1TB",
			"precoDe":250.00,
		    "precoPor":229.90
		}
	]
}

Request details

Field Type Mandatory Description
precos Data Collection Yes Price lot
Minimum size: 1 | Maximum size: 100
   sku String Yes Product SKU/variation
Minimum size: 1 | Maximum size: 250
   precoDe Number Yes Product 'from' price/variation
Minimum value: 0.01 | Maximum value: 999999.99
   precoPor Number Yes Price 'per' of the product/variation (cannot be greater than the 'priceFrom' field)
Minimum value: 0.01 | Maximum value: 999999.99
   precoDeMidia Number No Product 'from' price/variation for media channels (Google Shopping, Buscapé, etc.). Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99
   precoPorMidia Number No Price 'per' product/variation for media channels (Google Shopping, Buscapé, etc.). It cannot be greater than the 'priceDeMidia' field. Only use this field if there is price variation between marketplaces and media channels. If there is no variation, only use the 'priceFrom' and 'priceBy' fields
Minimum value: 0.01 | Maximum value: 999999.99

Response

Sample batch creation response
{
    "id": 80
}

Response details

Field Type Description
id Number Generated batch ID

DELETE /v1/products/{sku}

Individual product exclusion feature, responsible for deleting a product.

Important: it is not possible to delete products that are linked to a marketplace channel and it is not possible to delete products that have children, in this case it is necessary to first delete the child products and then delete the leader product

Endpoint information
Environment Sandbox / Production
Success Status 204 No Content
/v1/products/{sku} Product SKU (skuProduto)

Batch (lots)

GET /v1/batch/{id}

Resource responsible for returning all details about a batch, such as its status, processed items, errors found, creation date and processing date of each item.

Important: Batches can be consulted via API up to 10 days after their creation. After this period, details of a batch can only be obtained via call.

Endpoint information
Environment Sandbox / Production
Success Status 200 Ok
/v1/batch/{id} Batch ID

Response

Example query response from a batch
{
    "batchId": "80",
    "requestId": "CI1O18G20190614104404P1560519844050X2326",
    "data": "2019-05-14 13:44:04",
    "tipo": "produto",
    "acao": "atualizarEstoque",
    "status": "processado",
    "contemErros": true,
    "observacoes": [
        {
            "identificador": "12345ABC",
            "sucesso": true,
            "info": "Ação executada com sucesso",
            "data": "2019-05-14 10:44:10"
        },
        {
            "identificador": "123456ABCD",
            "sucesso": false,
            "error": "Problemas ao executar ação",
            "details": [
                "SKU  '123456ABCD' não encontrado"
            ],
            "data": "2019-05-14 10:44:10"
        }
    ]
}

Response details

Field Type Description
batchId Number Batch ID
requestId String Request ID
tipo String Batch type (product, order, purchase list, etc.)
acao String Batch action (updateStock, updateProduct, etc)
data String Batch processing date
status String Batch status
Accepted values: aguardando, processando, processado
contemErros Boolean Defines whether errors were found in the processing
observacoes Data Collection Notes on batch processing
   idLista String List identifier
   identificador String Identifier of the item in the batch (product SKU/variation, for example)
   sucesso Boolean Defines whether the item was processed successfully
   info String Information about processing (only returned if successful)
   error String Information about the error presented (returned only in case of error)
   details Array de strings Details about the error presented (returned in some error cases)
   data String Item processing date

Orders

GET /v1/orders

Resource responsible for listing all seller orders in the Marketplaces Hub, ordered by date of issue.

In this resource, only the basic order data will be returned, requiring a call to the query resource individual orders to obtain all data about a specific order.

Endpoint information
Environment Sandbox / Production
Success Status 200 Ok
Filters status: Filter orders by status. Send the hash of one or more statuses separated by '|'
Exemplo de requisição: /v1/orders?status=novo|pago
Offset/Limit Mandatory the sending of the offset and limit parameters in the request URL.
Example of requisition: /v1/orders?offset=0&limit=100
Maximum value for the limit parameter: 100

Response

Sample order query response
{
    "pedidos": [
        {
            "idPedido": 192062,
            "idPedidoCanal": "MKTP-5678",
            "referenciaPedidoCanal": "MKTP-5678",
            "idInterno": 0,
            "dataEmissao": "2019-05-09 00:36:00",
            "dataIntegracao": "2019-05-13 08:28:58",
            "status": "novo",
            "moeda": "BRL",
            "canal": {
                "canal": "Mktplace Wapstore",
                "canalIntegracao": "Api de Teste",
                "hashCanal": "api"
            },
            "cliente": {
                "nome": "João de Oliveira",
                "email": "exemplo@teste.com.br",
                "cpfCnpj": "123.789.456-48",
                "pessoa": "f",
                "telefone": "(11) 1234-4567",
                "celular": "(11) 999999-9999"
            },
            "entrega": {
                "cep": "01310-940",
                "destinatario": "João de Oliveira",
                "endereco": "Av. Paulista",
                "bairro": "Centro",
                "cidade": "São Paulo",
                "uf": "SP",
                "numero": "1234",
                "complemento": "Sala 123",
                "referencia": "Aurora Center",
                "prazoEntrega": 12,
                "tipoFrete": "SEDEX",
                "codigoRastreio": "",
                "linkRastreio": ""
            },
            "valores": {
                "subtotal": 199,
                "frete": 29,
                "desconto": 0,
                "total": 228
            },
            "fiscal": {
                "nfeSerie": "",
                "nfeNumero": "",
                "nfeChave": "",
                "nfseNumero":"",
                "nfseCodigoVerificacao":"",
                "nfseUrlConsulta":""
            },
            "links": {
                "GET": "https://api.sandbox.omni.wapstore.com.br/v1/orders/192062",
                "PUT": {
                    "faturado": "https://api.sandbox.omni.wapstore.com.br/v1/orders/192062/invoiced",
                    "enviado": "https://api.sandbox.omni.wapstore.com.br/v1/orders/192062/sent",
                    "entregue": "https://api.sandbox.omni.wapstore.com.br/v1/orders/192062/delivered"
                }
            }
        }
    ],
    "info": {
        "filtros": [],
        "prev": "",
        "self": "https://api.sandbox.omni.wapstore.com.br/v1/orders?offset=0&limit=100",
        "next": "",
        "offset": 0,
        "limit": 100,
        "exibindo": 1,
        "total": 1
    }
}

Response details

Field Type Description
pedidos Data Collection Orders listed
   idPedido Number Order ID within the Marketplaces Hub (used for status changes and order query)
   idPedidoCanal String Order ID within the marketplace
   referenciaPedidoCanal String Reference code for the order in the channel. Example: B2W orders have a code within B2W (referenciaPedidoCanal) and another code within SkyHub (idPedidoCanal)
   idInterno Number Order ID within your system
   dataEmissao String Date of issuance of the order on the marketplace
Expected format: 2019-05-11 22:15:00
   dataIntegracao String Date the order was integrated into the Marketplaces Hub
Expected format: 2019-05-11 22:15:00
   status String Order status in the Marketplaces Hub (see available statuses in references)
   moeda String Currency code in ISO 4217 format
   canal Object Data from the channel that generated the order
      canal String Name of the channel where the order was generated (name of the channel within the marketplace. Example: Lojas Americanas)
      canalIntegracao String Name of the integration channel in the Marketplaces Hub (name added by the Seller when adding a marketplace channel in the Marketplaces Hub. Example: B2W)
      hashCanal String Channel hash within the Marketplaces Hub (see available hashes in channel references)
   cliente Object Customer data
      nome String Customer's full name or business name
      email String Customer email
      cpfCnpj String Customer CPF or CNPJ
      pessoa String Natural person (f) or legal entity (j)
Accepted values: f, j
      telefone String Customer phone
      celular String Customer cell phone
   entrega Object Delivery details
      cep String Delivery zip code
      destinatario String Recipient name
      endereco String Name of the street or avenue
      bairro String Neighborhood name
      cidade String City name
      uf String destination state
      numero String House number
      complemento String Address complement
      referencia String Reference point
      prazoEntrega Number Delivery time in working days
      tipoFrete String Shipping identification code sent by the Marketplace (in some marketplaces this code is specific to the marketplace, in others it is the name of the contingency table or the name returned in the shipping API)
      codigoRastreio String Order tracking code
      linkRastreio String Order tracking URL
   valores Object Order values
      frete Number Amount charged for shipping
      subtotal Number Amount charged for items
      desconto Number Discount amount applied
      total Number Total order value (shipping + items - discount)
   fiscal Object Invoice data
      nfeChave String Electronic sales invoice key
      nfeNumero String Electronic sales invoice number
      nfeSerie String Electronic sales invoice series number
      nfseNumero String Electronic service invoice number
      nfseCodigoVerificacao String Electronic service invoice verification code
      nfseUrlConsulta String URL to consult the electronic service invoice
   links Object Useful API order links
      GET String Endpoint for consulting complete order data
      PUT Object Endpoint to change order statuses
         faturado String Endpoint to update status to invoiced
         enviado String Endpoint to update status to sent
         entregue String Endpoint to update status to delivered
info Object Information about the listing (paging, filters, total items, etc.)
   filtros Object (key/value) Filters applied to the URL
   prev String Previous page
   self String Current page
   next String Next page
   offset Number Requested offset
   limit Number Limit requested
   exibindo Number Number of records being displayed on the current page
   total Number Total records on all pages

GET /v1/orders/{id}

Individual order query feature, responsible for returning all information about an order

Endpoint information
Environment Sandbox / Production
Success Status 200 Ok
/v1/orders/{id} Order ID in the Marketplaces Hub (idPedido)

Response

Example query response for a specific order
{
    "idPedido": 192062,
    "idPedidoCanal": "MKTP-5678",
    "referenciaPedidoCanal": "MKTP-5678",
    "idInterno": 0,
    "dataEmissao": "2019-05-09 00:36:00",
    "dataIntegracao": "2019-05-13 08:28:58",
    "status": "novo",
    "moeda": "BRL",
    "canal": {
        "canal": "Mktplace Wapstore",
        "canalIntegracao": "Api de Teste",
        "hashCanal": "api"
    },
    "cliente": {
        "nome": "João de Oliveira",
        "email": "exemplo@teste.com.br",
        "cpfCnpj": "123.789.456-48",
        "pessoa": "f",
        "telefone": "(11) 1234-4567",
        "celular": "(11) 999999-9999",
        "rgIe": "11.123.123-4",
        "sexo": "m",
        "nascimento": "10/06/1995"
    },
    "entrega": {
        "cep": "01310-940",
        "destinatario": "João de Oliveira",
        "endereco": "Av. Paulista",
        "bairro": "Centro",
        "cidade": "São Paulo",
        "uf": "SP",
        "numero": "1234",
        "complemento": "Sala 123",
        "referencia": "Aurora Center",
        "prazoEntrega": 12,
        "tipoFrete": "SEDEX",
        "codigoRastreio": "",
        "linkRastreio": "",
        "freteMapeado": {
            "id": "1235",
            "nome": "SEDEX"
        }
    },
    "valores": {
        "subtotal": 199,
        "frete": 29,
        "desconto": 0,
        "total": 228
    },
    "fiscal": {
        "nfeSerie": "",
        "nfeNumero": "",
        "nfeChave": "",
        "nfseNumero":"",
        "nfseCodigoVerificacao":"",
        "nfseUrlConsulta":""
    },
    "itens": [
        {
            "sku": "FURADEIRAABC-220v",
            "nome": "Furadeira profissional 800w",
            "detalhes": "Voltagem:220v",
            "valor": 199,
            "qtd": 1
        }
    ],
    "pagamentos": [
        {
            "metodo": "Cartão de Crédito",
            "descricao": "Visa 10x",
            "qtdParcelas": 10,
            "valor": 228
        }
    ]
}

Response details

Field Type Description
idPedido Number Order ID within the Marketplaces Hub (used for status changes and order query)
idPedidoCanal String Order ID within the marketplace
referenciaPedidoCanal String Reference code for the order in the channel. Example: B2W orders have a code within B2W (referenciaPedidoCanal) and another code within SkyHub (idPedidoCanal)
idInterno Number Order ID within your system
dataEmissao String Date of issuance of the order on the marketplace
Expected format: 2019-05-11 22:15:00
dataIntegracao String Date the order was integrated into the Marketplaces Hub
Expected format: 2019-05-11 22:15:00
status String Order status in the Marketplaces Hub (see available statuses in references)
moeda String Currency code in ISO 4217 format
canal Object Data from the channel that generated the order
   canal String Name of the channel where the order was generated (name of the channel within the marketplace. Example: Lojas Americanas)
   canalIntegracao String Name of the integration channel in the Marketplaces Hub (name added by the Seller when adding a marketplace channel in the Marketplaces Hub. Example: B2W)
   hashCanal String Channel hash within the Marketplaces Hub (see available hashes in channel references)
cliente Object Customer data
   nome String Customer's full name or business name
   email String Customer email
   cpfCnpj String Customer CPF or CNPJ
   rgIe String RG or state registration of the client
   sexo String Customer's gender. ('j' for legal entities, 'ni' for unspecified gender.)
Accepted values: m, f, j, ni
   pessoa String Natural person (f) or legal entity (j)
Accepted values: f, j
   nascimento String Customer's date of birth
   telefone String Customer phone
   celular String Customer cell phone
entrega Object Delivery details
   cep String Delivery zip code
   destinatario String Recipient name
   endereco String Name of the street or avenue
   bairro String Neighborhood name
   cidade String City name
   uf String destination state
   numero String House number
   complemento String Address complement
   referencia String Reference point
   prazoEntrega Number Delivery time in working days
   tipoFrete String Shipping identification code sent by the Marketplace (in some marketplaces this code is specific to the marketplace, in others it is the name of the contingency table or the name returned in the shipping API)
   codigoRastreio String Order tracking code
   linkRastreio String Order tracking URL
   freteMapeado Object As each marketplace can send its own shipping type codes, it is possible to create a mapping [from/to] of shipping types between the marketplace and the Marketplaces Hub. If the order's shipping is mapped, the corresponding shipping will appear here
      id Number Shipping type ID in Marketplaces Hub
      nome String Shipping type name
valores Object Order values
   frete Number Amount charged for shipping
   subtotal Number Amount charged for items
   desconto Number Discount amount applied
   total Number Total order value (shipping + items - discount)
fiscal Object Invoice data
   nfeChave String Electronic sales invoice key
   nfeNumero String Electronic sales invoice number
   nfeSerie String Electronic sales invoice series number
   nfseNumero String Electronic service invoice number
   nfseCodigoVerificacao String Electronic service invoice verification code
   nfseUrlConsulta String URL to consult the electronic service invoice
itens Data Collection Item data
Minimum size: 1
   sku String Product SKU/variation
   nome String Product name
   detalhes String Product color, size and voltage
   qtd Number Amount
   valor Number Unit value
pagamentos Data Collection Payment details
   metodo String Payment method (There is no standard and may vary from marketplace to marketplace)
   descricao String Payment description (There is no standard and may vary from marketplace to marketplace)
   qtdParcelas Number Number of installments (not all marketplaces inform the number of installments chosen by the customer)
   valor Number Amount paid

GET /v1/orders/queue

Order update queue query feature. Whenever a new order arrives or has its status updated by the marketplace, it will appear in this queue. Configure your system to consume the update queue to always receive new orders and status updates.

In this feature, all order data is returned, that is, it is not necessary to make a second request to get all order information.

Important: After updating your system, you must remove the order from the queue using the remove orders from queue feature. If you don't do this, every time you query the queue you will continue to receive the same requests.

Endpoint information
Environment Sandbox / Production
Success Status 200 Ok
Filters status: Filter orders by status. Send the hash of one or more statuses separated by '|'
Exemplo de requisição: /v1/orders/queue?status=novo|pago
Offset/Limit Mandatory to send the limit parameter in the request URL (it is not allowed to send the offset parameter for this request).
Example of requisition: /v1/orders/queue?limit=100
Maximum value for the limit parameter: 100

Response

Request queue query response example
{
    "pedidos": [
        {
            "idPedido": 192062,
            "idPedidoCanal": "MKTP-5678",
            "referenciaPedidoCanal": "MKTP-5678",
            "idInterno": 0,
            "dataEmissao": "2019-05-09 00:36:00",
            "dataIntegracao": "2019-05-13 08:28:58",
            "status": "novo",
            "moeda": "BRL",
            "canal": {
                "canal": "Mktplace Wapstore",
                "canalIntegracao": "Api de Teste",
                "hashCanal": "api"
            },
            "cliente": {
                "nome": "João de Oliveira",
                "email": "exemplo@teste.com.br",
                "cpfCnpj": "123.789.456-48",
                "pessoa": "f",
                "telefone": "(11) 1234-4567",
                "celular": "(11) 999999-9999",
                "rgIe": "11.123.123-4",
                "sexo": "m",
                "nascimento": "10/06/1995"
            },
            "entrega": {
                "cep": "01310-940",
                "destinatario": "João de Oliveira",
                "endereco": "Av. Paulista",
                "bairro": "Centro",
                "cidade": "São Paulo",
                "uf": "SP",
                "numero": "1234",
                "complemento": "Sala 123",
                "referencia": "Aurora Center",
                "prazoEntrega": 12,
                "tipoFrete": "SEDEX",
                "codigoRastreio": "",
                "linkRastreio": "",
                "freteMapeado": {
                    "id": "1235",
                    "nome": "SEDEX"
                }
            },
            "valores": {
                "subtotal": 199,
                "frete": 29,
                "desconto": 0,
                "total": 228
            },
            "fiscal": {
                "nfeSerie": "",
                "nfeNumero": "",
                "nfeChave": "",
                "nfseNumero":"",
                "nfseCodigoVerificacao":"",
                "nfseUrlConsulta":""
            },
            "itens": [
                {
                    "sku": "FURADEIRAABC-220v",
                    "nome": "Furadeira profissional 800w",
                    "detalhes": "Voltagem:220v",
                    "valor": 199,
                    "qtd": 1
                }
            ],
            "pagamentos": [
                {
                    "metodo": "Cartão de Crédito",
                    "descricao": "Visa 10x",
                    "qtdParcelas": 10,
                    "valor": 228
                }
            ]
        }
    ],
    "info": {
        "filtros": [],
        "limit": 100,
        "exibindo": 1,
        "total": 1
    }
}

Response details

Field Type Description
pedidos Data Collection Orders listed
   idPedido Number Order ID within the Marketplaces Hub (used for status changes and order query)
   idPedidoCanal String Order ID within the marketplace
   referenciaPedidoCanal String Reference code for the order in the channel. Example: B2W orders have a code within B2W (referenciaPedidoCanal) and another code within SkyHub (idPedidoCanal)
   idInterno Number Order ID within your system
   dataEmissao String Date of issuance of the order on the marketplace
Expected format: 2019-05-11 22:15:00
   dataIntegracao String Date the order was integrated into the Marketplaces Hub
Expected format: 2019-05-11 22:15:00
   status String Order status in the Marketplaces Hub (see available statuses in references)
   moeda String Currency code in ISO 4217 format
   canal Object Data from the channel that generated the order
      canal String Name of the channel where the order was generated (name of the channel within the marketplace. Example: Lojas Americanas)
      canalIntegracao String Name of the integration channel in the Marketplaces Hub (name added by the Seller when adding a marketplace channel in the Marketplaces Hub. Example: B2W)
      hashCanal String Channel hash within the Marketplaces Hub (see available hashes in channel references)
   cliente Object Customer data
      nome String Customer's full name or business name
      email String Customer email
      cpfCnpj String Customer CPF or CNPJ
      rgIe String RG or state registration of the client
      sexo String Customer's gender. ('j' for legal entities, 'ni' for unspecified gender.)
Accepted values: m, f, j, ni
      pessoa String Natural person (f) or legal entity (j)
Accepted values: f, j
      nascimento String Customer's date of birth
      telefone String Customer phone
      celular String Customer cell phone
   entrega Object Delivery details
      cep String Delivery zip code
      destinatario String Recipient name
      endereco String Name of the street or avenue
      bairro String Neighborhood name
      cidade String City name
      uf String destination state
      numero String House number
      complemento String Address complement
      referencia String Reference point
      prazoEntrega Number Delivery time in working days
      tipoFrete String Shipping identification code sent by the Marketplace (in some marketplaces this code is specific to the marketplace, in others it is the name of the contingency table or the name returned in the shipping API)
      codigoRastreio String Order tracking code
      linkRastreio String Order tracking URL
      freteMapeado Object As each marketplace can send its own shipping type codes, it is possible to create a mapping [from/to] of shipping types between the marketplace and the Marketplaces Hub. If the order's shipping is mapped, the corresponding shipping will appear here
         id Number Shipping type ID in Marketplaces Hub
         nome String Shipping type name
   valores Object Order values
      frete Number Amount charged for shipping
      subtotal Number Amount charged for items
      desconto Number Discount amount applied
      total Number Total order value (shipping + items - discount)
   fiscal Object Invoice data
      nfeChave String Electronic sales invoice key
      nfeNumero String Electronic sales invoice number
      nfeSerie String Electronic sales invoice series number
      nfseNumero String Electronic service invoice number
      nfseCodigoVerificacao String Electronic service invoice verification code
      nfseUrlConsulta String URL to consult the electronic service invoice
   itens Data Collection Item data
Minimum size: 1
      sku String Product SKU/variation
      nome String Product name
      detalhes String Product color, size and voltage
      qtd Number Amount
      valor Number Unit value
   pagamentos Data Collection Payment details
      metodo String Payment method (There is no standard and may vary from marketplace to marketplace)
      descricao String Payment description (There is no standard and may vary from marketplace to marketplace)
      qtdParcelas Number Number of installments (not all marketplaces inform the number of installments chosen by the customer)
      valor Number Amount paid
info Object Information about the listing (paging, filters, total items, etc.)
   filtros Object (key/value) Filters applied to the URL
   limit Number Limit requested
   exibindo Number Number of records being displayed on the current page
   total Number Total records on all pages

DELETE /v1/orders/queue/{id}

Resource responsible for removing orders from the update queue.

In this resource it is necessary to send the status imported by your system (this information appears on the Marketplaces Hub panel for the Seller) and also a numeric ID unique to the order generated in your system. If you do not have a unique numeric ID, send the order ID generated in the Marketplaces Hub in this field.

Endpoint information
Environment Sandbox / Production
Success Status 204 No Content
/v1/orders/queue/{id} Order ID in the Marketplaces Hub (idPedido)

Request

Example of a request to remove an order from the queue
{
   "idInterno":1234,
   "status":"novo"
 }

Request details

Field Type Mandatory Description
idInterno Number Yes Order ID within your system
Minimum value: 1 | Maximum value: 999999999999999999
status String Yes Imported order status. Used to check whether the status imported into your system is up to date with the order status in the Marketplaces Hub
Accepted values: novo, pago, faturado, enviado, entregue, cancelado

POST /v1/orders (Sandbox)

Resource responsible for creating orders in sandbox.

Use this resource to simulate the creation of orders through the marketplace, as when creating a new order it will appear in the update queue

Endpoint information
Environment Sandbox
Success Status 201 Created
Limit requests per minute 60

Request

Example of a request for creating an order
{
   "idPedidoCanal":"MKTP-5678",
   "referenciaPedidoCanal":"MKTP-5678",
   "canal":"Mktplace Wapstore",
   "dataEmissao":"2019-05-09 00:36:00",
   "moeda": "BRL",
   "cliente":{
     "nome":"João de Oliveira",
     "email":"exemplo@teste.com.br",
     "cpfCnpj":"123.789.456-48",
     "rgIe":"11.123.123-4",
     "pessoa":"f",
     "sexo":"m",
     "telefone":"(11) 1234-4567",
     "celular":"(11) 999999-9999",
     "nascimento":"10/06/1995"
    },
    "entrega":{
      "cep":"01310-940",
      "destinatario":"João de Oliveira",
      "endereco":"Av. Paulista",
      "bairro":"Centro",
      "cidade":"São Paulo",
      "uf":"SP",
      "numero":"1234",
      "complemento":"Sala 123",
      "referencia":"Aurora Center",
      "prazoEntrega":12,
      "tipoFrete":"SEDEX"
     },
     "valores":{
       "frete":29.00,
       "subtotal":199.00,
       "desconto":0.00,
       "total":228.00
      },
      "itens":[
        {
          "sku":"FURADEIRAABC-220v",
          "nome":"Furadeira profissional 800w",
          "qtd":1,
          "valor":199.00
         }
      ],
       "pagamentos":[
         {
             "metodo":"Cartão de Crédito",
             "descricao":"Visa 10x",
             "qtdParcelas":10,
             "valor":228.00
          }
       ]
 }

Request details

Field Type Mandatory Description
idPedidoCanal String Yes Order ID within the marketplace
Minimum size: 1 | Maximum size: 250
referenciaPedidoCanal String No Reference code for the order in the channel. Example: B2W orders have a code within B2W (referenciaPedidoCanal) and another code within SkyHub (idPedidoCanal)
Minimum size: 1 | Maximum size: 250
canal String Yes Name of the channel where the order was generated (name of the channel within the marketplace. Example: Lojas Americanas)
Minimum size: 1 | Maximum size: 250
dataEmissao String Yes Date of issuance of the order on the marketplace
Expected format: 2019-05-11 22:15:00
moeda String Yes Currency code in ISO 4217 format
cliente Object Yes Customer data
   nome String Yes Customer's full name or business name
Minimum size: 1 | Maximum size: 250
   email String Yes Customer email
Minimum size: 1 | Maximum size: 250
   cpfCnpj String Yes Customer CPF or CNPJ
Minimum size: 1 | Maximum size: 250
   rgIe String No RG or state registration of the client
Minimum size: 1 | Maximum size: 250
   sexo String No Customer's gender. Send 'j' for legal entities or 'ni' for undisclosed gender
Accepted values: m, f, j, ni
   pessoa String Yes Natural person (f) or legal entity (j)
Accepted values: f, j
   nascimento String Yes Customer's date of birth
Minimum size: 1 | Maximum size: 250
   telefone String No Customer phone
Minimum size: 1 | Maximum size: 250
   celular String No Customer cell phone
Minimum size: 1 | Maximum size: 250
entrega Object Yes Delivery details
   cep String Yes Delivery zip code
Minimum size: 1 | Maximum size: 9
   destinatario String Yes Recipient name
Minimum size: 1 | Maximum size: 250
   endereco String Yes Name of the street or avenue
Minimum size: 1 | Maximum size: 250
   bairro String Yes Neighborhood name
Minimum size: 1 | Maximum size: 250
   cidade String Yes City name
Minimum size: 1 | Maximum size: 250
   uf String Yes destination state
Minimum size: 2 | Maximum size: 2
   numero String Yes House number
Minimum size: 1 | Maximum size: 50
   complemento String No Address complement
Minimum size: 1 | Maximum size: 250
   referencia String No Reference point
Minimum size: 1 | Maximum size: 250
   prazoEntrega Number Yes Delivery time in working days
Minimum value: 1 | Maximum value: 365
   tipoFrete String No Shipping identification code sent by the Marketplace (in some marketplaces this code is specific to the marketplace, in others it is the name of the contingency table or the name returned in the shipping API)
Minimum size: 1 | Maximum size: 250
valores Object Yes Order values
   frete Number Yes Amount charged for shipping
Minimum value: 0 | Maximum value: 999999.99
   subtotal Number Yes Amount charged for items
Minimum value: 0 | Maximum value: 999999.99
   desconto Number Yes Discount amount applied
Minimum value: 0 | Maximum value: 999999.99
   total Number Yes Total order value (shipping + items - discount)
Minimum value: 0 | Maximum value: 999999.99
itens Data Collection Yes Item data
Minimum size: 1
   sku String Yes Product SKU/variation
Minimum size: 1 | Maximum size: 250
   nome String Yes Product name
Minimum size: 1 | Maximum size: 250
   qtd Number Yes Amount
Maximum size: 99999
Minimum value: 1
   valor Number Yes Unit value
Minimum value: 0 | Maximum value: 999999.99
pagamentos Data Collection Yes Payment details
Minimum size: 1
   metodo String Yes Payment method (There is no standard and may vary from marketplace to marketplace)
Minimum size: 1 | Maximum size: 250
   descricao String Yes Payment description (There is no standard and may vary from marketplace to marketplace)
Minimum size: 1 | Maximum size: 250
   qtdParcelas Number Yes Number of installments (not all marketplaces inform the number of installments chosen by the customer)
Maximum size: 99999
Minimum value: 1
   valor Number Yes Amount paid
Minimum value: 0 | Maximum value: 999999.99

Response

Example response for creating an order
{
    "idPedido": 192062,
    "idPedidoCanal": "MKTP-5678",
    "referenciaPedidoCanal": "MKTP-5678",
    "idInterno": 0,
    "dataEmissao": "2019-05-09 00:36:00",
    "dataIntegracao": "2019-05-13 08:28:58",
    "status": "novo",
    "moeda": "BRL",
    "canal": {
        "canal": "Mktplace Wapstore",
        "canalIntegracao": "Api de Teste",
        "hashCanal": "api"
    },
    "cliente": {
        "nome": "João de Oliveira",
        "email": "exemplo@teste.com.br",
        "cpfCnpj": "123.789.456-48",
        "pessoa": "f",
        "telefone": "(11) 1234-4567",
        "celular": "(11) 999999-9999",
        "rgIe": "11.123.123-4",
        "sexo": "m",
        "nascimento": "10/06/1995"
    },
    "entrega": {
        "cep": "01310-940",
        "destinatario": "João de Oliveira",
        "endereco": "Av. Paulista",
        "bairro": "Centro",
        "cidade": "São Paulo",
        "uf": "SP",
        "numero": "1234",
        "complemento": "Sala 123",
        "referencia": "Aurora Center",
        "prazoEntrega": 12,
        "tipoFrete": "SEDEX",
        "codigoRastreio": "",
        "linkRastreio": "",
        "freteMapeado": {
            "id": "1235",
            "nome": "SEDEX"
        }
    },
    "valores": {
        "subtotal": 199,
        "frete": 29,
        "desconto": 0,
        "total": 228
    },
    "fiscal": {
        "nfeSerie": "",
        "nfeNumero": "",
        "nfeChave": "",
        "nfseNumero":"",
        "nfseCodigoVerificacao":"",
        "nfseUrlConsulta":""
    },
    "itens": [
        {
            "sku": "FURADEIRAABC-220v",
            "nome": "Furadeira profissional 800w",
            "detalhes": "Voltagem:220v",
            "valor": 199,
            "qtd": 1
        }
    ],
    "pagamentos": [
        {
            "metodo": "Cartão de Crédito",
            "descricao": "Visa 10x",
            "qtdParcelas": 10,
            "valor": 228
        }
    ]
}

Response details

Field Type Description
idPedido Number Order ID within the Marketplaces Hub (used for status changes and order query)
idPedidoCanal String Order ID within the marketplace
referenciaPedidoCanal String Reference code for the order in the channel. Example: B2W orders have a code within B2W (referenciaPedidoCanal) and another code within SkyHub (idPedidoCanal)
idInterno Number Order ID within your system
dataEmissao String Date of issuance of the order on the marketplace
Expected format: 2019-05-11 22:15:00
dataIntegracao String Date the order was integrated into the Marketplaces Hub
Expected format: 2019-05-11 22:15:00
status String Order status in the Marketplaces Hub (see available statuses in references)
moeda String Currency code in ISO 4217 format
canal Object Data from the channel that generated the order
   canal String Name of the channel where the order was generated (name of the channel within the marketplace. Example: Lojas Americanas)
   canalIntegracao String Name of the integration channel in the Marketplaces Hub (name added by the Seller when adding a marketplace channel in the Marketplaces Hub. Example: B2W)
   hashCanal String Channel hash within the Marketplaces Hub (see available hashes in channel references)
cliente Object Customer data
   nome String Customer's full name or business name
   email String Customer email
   cpfCnpj String Customer CPF or CNPJ
   rgIe String RG or state registration of the client
   sexo String Customer's gender. ('j' for legal entities, 'ni' for unspecified gender.)
Accepted values: m, f, j, ni
   pessoa String Natural person (f) or legal entity (j)
Accepted values: f, j
   nascimento String Customer's date of birth
   telefone String Customer phone
   celular String Customer cell phone
entrega Object Delivery details
   cep String Delivery zip code
   destinatario String Recipient name
   endereco String Name of the street or avenue
   bairro String Neighborhood name
   cidade String City name
   uf String destination state
   numero String House number
   complemento String Address complement
   referencia String Reference point
   prazoEntrega Number Delivery time in working days
   tipoFrete String Shipping identification code sent by the Marketplace (in some marketplaces this code is specific to the marketplace, in others it is the name of the contingency table or the name returned in the shipping API)
   codigoRastreio String Order tracking code
   linkRastreio String Order tracking URL
   freteMapeado Object As each marketplace can send its own shipping type codes, it is possible to create a mapping [from/to] of shipping types between the marketplace and the Marketplaces Hub. If the order's shipping is mapped, the corresponding shipping will appear here
      id Number Shipping type ID in Marketplaces Hub
      nome String Shipping type name
valores Object Order values
   frete Number Amount charged for shipping
   subtotal Number Amount charged for items
   desconto Number Discount amount applied
   total Number Total order value (shipping + items - discount)
fiscal Object Invoice data
   nfeChave String Electronic sales invoice key
   nfeNumero String Electronic sales invoice number
   nfeSerie String Electronic sales invoice series number
   nfseNumero String Electronic service invoice number
   nfseCodigoVerificacao String Electronic service invoice verification code
   nfseUrlConsulta String URL to consult the electronic service invoice
itens Data Collection Item data
Minimum size: 1
   sku String Product SKU/variation
   nome String Product name
   detalhes String Product color, size and voltage
   qtd Number Amount
   valor Number Unit value
pagamentos Data Collection Payment details
   metodo String Payment method (There is no standard and may vary from marketplace to marketplace)
   descricao String Payment description (There is no standard and may vary from marketplace to marketplace)
   qtdParcelas Number Number of installments (not all marketplaces inform the number of installments chosen by the customer)
   valor Number Amount paid

PUT /v1/orders/{id}/paid (Sandbox)

Resource responsible for updating the status of the order paid in sandbox.

Use this feature to simulate the status update to 'paid' by the marketplace, because when you update an order to 'paid' it will appear in the update queue

Important: The order must have a 'new' status

Endpoint information
Environment Sandbox
Success Status 204 No Content
/v1/orders/{id}/paid Order ID in the Marketplaces Hub (idPedido)
Limit requests per minute 60

Request

Example of request to change status to 'paid'
{
   "dataOcorrencia":"2019-04-25 14:15:00"
 }

Request details

Field Type Mandatory Description
dataOcorrencia String Yes Actual status change date
Expected format: 2019-05-11 22:15:00

PUT /v1/orders/{id}/invoiced

Resource responsible for updating the order status to 'invoiced'.

Important: the order must have the status 'paid'

Endpoint information
Environment Sandbox / Production
Success Status 204 No Content
/v1/orders/{id}/invoiced Order ID in the Marketplaces Hub (idPedido)
Limit requests per minute 60

Request

Example of request to change status to 'invoiced'
{
   "dataOcorrencia":"2019-04-25 14:15:00",
   "nfeChave":"11112222333344445555666677778888999900001234",
   "nfeNumero":"11000.1",
   "nfeSerie":"001",
   "nfePdfUrl": "",
   "nfseNumero":"2022/191",
   "nfseCodigoVerificacao":"f31bfa55",
   "nfseUrlConsulta":"www.exemplo.com.br/exemploNfse"
 }

Request details

Field Type Mandatory Description
dataOcorrencia String Yes Actual status change date
Expected format: 2019-05-11 22:15:00
nfeChave String No Electronic sales invoice key
nfeNumero String No Electronic sales invoice number
Maximum size: 50
nfeSerie String No Electronic sales invoice series number
Maximum size: 50
nfePdfUrl String No NFe PDF URL
Maximum size: 255
nfseNumero String No Electronic service invoice number
Maximum size: 50
nfseCodigoVerificacao String No Electronic service invoice verification code
Maximum size: 50
nfseUrlConsulta String No URL to consult the electronic service invoice
Maximum size: 255

PUT /v1/orders/{id}/sent

Resource responsible for updating the order status to 'shipped'.

Important: the order must have the status 'invoiced'

Endpoint information
Environment Sandbox / Production
Success Status 204 No Content
/v1/orders/{id}/sent Order ID in the Marketplaces Hub (idPedido)
Limit requests per minute 60

Request

Example of request to change status to 'sent'
{
   "dataOcorrencia":"2019-04-25 14:15:00",
   "codigoRastreio":"AB00000000000000BR",
   "linkRastreio":"https://www.linkcorreios.com.br/AB00000000000000BR"
 }

Request details

Field Type Mandatory Description
dataOcorrencia String Yes Actual status change date
Expected format: 2019-05-11 22:15:00
codigoRastreio String Yes Order tracking code
Minimum size: 1 | Maximum size: 50
linkRastreio String Yes Order tracking URL
Minimum size: 1 | Maximum size: 255
Valid URL: e.g. https://sualoja.com.br/retorno

PUT /v1/orders/{id}/delivered

Resource responsible for updating the order status to 'delivered'.

Important: the order must have the status 'shipped' and the status 'delivered' ' is a final status, the order status can no longer be changed.

Endpoint information
Environment Sandbox / Production
Success Status 204 No Content
/v1/orders/{id}/delivered Order ID in the Marketplaces Hub (idPedido)
Limit requests per minute 60

Request

Example of request to change status to 'delivered'
{
   "dataOcorrencia":"2019-04-25 14:15:00"
 }

Request details

Field Type Mandatory Description
dataOcorrencia String Yes Actual status change date
Expected format: 2019-05-11 22:15:00

PUT /v1/orders/{id}/canceled (Sandbox)

Resource responsible for updating the order status to 'canceled' in sandbox.

Use this resource to simulate the status update to 'cancelled' by the marketplace, as when updating an order to 'cancelled' it will appear in the update queue

Important: as the 'canceled' status is a final status, the order status can no longer be changed.

Endpoint information
Environment Sandbox
Success Status 204 No Content
/v1/orders/{id}/canceled Order ID in the Marketplaces Hub (idPedido)
Limit requests per minute 60

Request

Example of request to change status to 'cancelled'
{
   "dataOcorrencia":"2019-04-25 14:15:00"
 }

Request details

Field Type Mandatory Description
dataOcorrencia String Yes Actual status change date
Expected format: 2019-05-11 22:15:00

Shipping labels

GET /v1/orders/{id}/shipment_labels

Endpoint information
Environment Sandbox / Production
Success Status 200 Ok
Offset/Limit Mandatory the sending of the offset and limit parameters in the request URL.
Example of requisition: /v1/orders/{id}/shipment_labels?offset=0&limit=100
Maximum value for the limit parameter: 100

Response

Example of tag query response
{
  "etiquetas": [
    {
      "conteudo": "YXJxdWl2byB0ZXN0ZQ==",
      "tipo": "pdf",
      "canal": "string",
      "idPedidoCanal": "123"
    },
    {
      "conteudo": "YXJxdWl2byB0ZXN0ZQ==",
      "tipo": "zpl",
      "canal": "string",
      "idPedidoCanal": "123"
    },
    {
      "conteudo": "YXJxdWl2byB0ZXN0ZQ==",
      "tipo": "png|jpg",
      "canal": "string",
      "idPedidoCanal": "123"
    }
  ],
  "info": {
    "filtros": [],
    "prev": "",
    "self": "http://localhost/v1/logistic/orders/13127721/shipment_labels?offset=0&limit=100",
    "next": "",
    "offset": 0,
    "limit": 100,
    "exibindo": 0,
    "total": 0
  }
}

Response details

Field Type Description
etiquetas Data Collection Order label list
   conteudo String Tag content converted to base64
   tipo String File type before converting to base64
   canal String Marketplace channel where the order was generated
   idPedidoCanal Number Order ID in the marketplace channel where it was generated
info Object Information about the listing (paging, filters, total items, etc.)
   filtros Object (key/value) Filters applied to the URL
   prev String Previous page
   self String Current page
   next String Next page
   offset Number Requested offset
   limit Number Limit requested
   exibindo Number Number of records being displayed on the current page
   total Number Total records on all pages

Error response

All requests that result in errors will have the same return pattern. The HTTP status code returned will indicate whether the problem is with the request (client-site - 4xx) or processing (server-site - 5xx) and the message will describe additional details about the problem.

Error response example
{
    "error": "Requisição rejeitada.",
    "details": [
        "O SKU 'TESTEAPISIMPLES' já está cadastrado"
    ]
}
Field Type Description
error String Information about the error presented
details Array de strings Details about the error presented (returned in some error cases)

Seller Shipping

The Marketplaces Hub has an internal freight calculation system based on contingency tables and is also integrated with external freight intelligence systems (Intellipost, SimFrete and Frenet), but if you have an internal freight calculation in your system, you can provide an API so that the Marketplaces Hub can execute shipping queries.

Each time a customer adds a product to the cart and requests a shipping calculation, the Marketplaces Hub will send a POST request to your endpoint with all the calculation data and you must calculate and return the information.

Important: configuring this URL in the Marketplaces Hub is mandatory for calculations external (other than the contingency table) of the wap.store marketplace, however, for other marketplaces it is recommended that your URL be configured directly on their respective portals, as the response time limits are very strict, the fewer hops the connection you have, the faster the response will be. If you want to configure your URL in the Marketplaces Hub to calculate MercadoLivre or B2W shipping, for example, the total response time from your API (connection + processing) to the Marketplaces Hub must be up to 300ms.

See below the requirements for integrating your shipping API:

  • Endpoint must be in HTTPs;
  • Success status must be '200 Ok', any other status will be understood as an error in your API and the Marketplaces Hub will use the contingency table;
  • The total response time is up to 1000ms (the Marketplaces Hub will use the contingency table contingency if this limit is exceeded);
  • The response format must correspond to the model described in this documentation;
  • The contingency calculation cannot exceed 10% of requests (10 days).

POST /seller/freight

Endpoint information
Environment Sandbox / Production
Success Status 200 Ok

Request

Example of freight inquiry
{
    "id": "85bovfu28230so6sqtbldq2j30",
    "cep": "01310940",
    "produtos": [
        {
            "sku": "FURADEIRAABC-220v",
            "precoPor":199.00,
            "altura":10.00,
            "largura":15.00,
            "comprimento":25.00,
            "peso":1.000,
            "qtd": 1,
            "tags": [
                "nacional", "internacional"
            ]
        }
    ]
}

Request details

Field Type Mandatory Description
id String Yes ID da requisição de frete
cep String Yes CEP de destino
produtos Data Collection Yes Produtos requisitados
   sku String Yes SKU do produto/variação
   precoPor Number Yes Preço 'por' unitário do produto/variação exibido para o cliente
   altura Number Yes Altura do produto/variação
   largura Number Yes Largura do produto/variação
   comprimento Number Yes Comprimento do produto/variação
   peso Number Yes Peso do produto/variação
   qtd Number Yes Quantidade solicitada do produto/variação
   tags Array No Nome(s) da(s) tag(s) do produto

Response

Example of a successful response to a freight inquiry
{
    "produtos": [
        {
            "sku": "FURADEIRAABC-220v",
            "qtdDisponivel":1,
            "status":"ok",
            "fretes":[
              {
                "id":"SEDEX10",
                "tipo":"expresso",
                "valor":39.00,
                "prazoEntrega":1
              },              
              {
                "id":"SEDEX",
                "tipo":"normal",
                "valor":29.00,
                "prazoEntrega":10
              },
              {
                "id":"PAC",
                "tipo":"economico",
                "valor":15.00,
                "prazoEntrega":20
              }
            ]
        }
    ]
}
Example of out-of-stock response to shipping query
{
  "produtos":[
    {
        "sku": "FURADEIRAABC-220v",
        "qtdDisponivel":0,
        "status":"semEstoque",
        "fretes":[]
    }
  ]
}
Example of region unavailable response for shipping query
{
  "produtos":[
    {
        "sku": "FURADEIRAABC-220v",
        "qtdDisponivel":1,
        "status":"regiaoIndisponivel",
        "fretes":[]
    }
  ]
}
Example of error response for shipping query
{
  "produtos":[
    {
        "sku": "FURADEIRAABC-220v",
        "qtdDisponivel":1,
        "status":"erro",
        "fretes":[]
    }
  ]
}

Response details

Field Type Description
produtos Data Collection Produtos requisitados
   sku String SKU do produto/variação
   qtdDisponivel Number Quantidade total do produto/variação disponível em estoque no momento
   status String Status do cálculo de frete para o produto. Retorne ok para todos os casos em que o frete foi calculado corretamente, retorne semEstoque ou regiaoIndisponivel para impedir a venda do produto no marketplace e retorn erro para indicar ao Omni que o cálculo deve ser feito pela tabela de contingência.
Accepted values: ok, semEstoque, regiaoIndisponivel, erro
   fretes Data Collection Opções de frete
      id String Identificador do frete no seu sistema (aparecerá no pedido no campo 'tipoFrete', caso o canal de marketplace nos informe)
      tipo String Tipo de frete
Accepted values: economico, normal, expresso
      valor Number Valor total do frete a ser cobrado
Minimum value: 0 | Maximum value: 999999.99
      prazoEntrega Number Prazo de entrega do produto em dias úteis (para alguns marketplaces, o prazo de entrega mostrado para o cliente será o maior prazo entre os itens calculados)
Minimum value: 1 | Maximum value: 365

URL configuration and activation

For your shipping URL to be activated in the Marketplaces Hub, in addition to configuring the correct endpoint, you must run a battery of tests to ensure that your API is returning data correctly and respecting response time limits, described in the documentation. Follow the steps below to configure and activate your URL in the Marketplaces Hub:

  • Access the Settings > Shipping module and click the New Shipping button;
  • Give a name for your shipping integration, select the API option for the type of shipping and submit the form;
  • Go back to the shipping list and add click on the shipping integration configuration button you just created;
  • Add the URL of your shipping API and submit the form;
  • As of now, your URL is configured, but it is not yet active. To activate, click on the Activate integration button;
  • Fill in all the data requested for the tests (CEP, product data, etc.) and click on the Run tests button;
  • Wait for the execution to finish and see the results obtained. If you failed any of the tests, your URL will remain inactive until the problems in your integration are fixed and a new test is run. You can see the details of each test by clicking the View details button.
  • If your URL has passed all tests, it will be activated immediately and you just have to wait for the propagation of the registration and it will be active in production.
  • Important: is It is necessary to add freight integration in each marketplace channel where it is necessary to use the calculation through it and to do this, simply access the Settings > Channels module, click on the desired channel configuration button and select integration in the Shipping type field.

References

References and code used in the APIs. Fields that have possible fixed values (product condition, gender, type of person, etc), have their references configured directly in the resource's request or response schema.

Order status

Valid status for orders in Marketplaces Hub.

Hash Status
novo Awaiting Payment
pago Paid
faturado Invoiced Order
enviado Order Sent
entregue Delivery Completed
cancelado Order Canceled

Integrated Marketplaces

Marketplace channels integrated with the Marketplaces Hub

Hash Channel Sales Channels
amazon Amazon Amazon
anymarket Anymarket Anymarket
b2w B2W Americanas, Submarino e Shoptime
carrefour Carrefour Carrefour
colombo Colombo Colombo
dafiti Dafiti Dafiti
kabum Kabum Kabum
leroymerlin Leroy Merlin Leroy Merlin
madeiramadeira Madeira Madeira Madeira Madeira
magazineluiza Magazine Luiza Magazine Luiza
mercadolivre Mercado Livre Mercado Livre
merchantcenter Merchant Center Merchant Center Mídia
olist Olist Olist
pluggto Plugg.to Plugg.to
ricardoeletro Ricardo Eletro Ricardo Eletro
shopee Shopee Shopee
cnova Via Marketplace Ponto Frio, Casas Bahia e Extra
vtex Vtex Vtex
walmart Walmart Walmart
wapstoremarketplace wap.store marketplace Wapstore Marketplace
westwing Westwing Integração de pedido do site Westwing
xmlgenerico XML Genérico (mídias) XML Genérico para as mídias
zoom Zoom Zoom marketplace
zoombuscapev2 Zoom Buscape V2 Zoom Buscape V2 Mídia

HTTP response status

HTTP return codes for API resources.

Code Status Description Type
200 OK Successful return for query and data changes (except in batch) Success
201 Created Successful return for data creation (orders, products, batches, etc.) Success
204 No Content Successful return for methods for actions that don't require a return body, like deletions for example. Success
400 Bad Request Error return when something in the sent request is not as expected by the APIs. Error
401 Unauthorized Error returned when app or integration token is invalid or missing. Error
404 Not Found Error returned when the requested resource does not exist (endpoint, product, order, etc). Error
406 Not Acceptable Error returned when endpoint accessed without HTTPS. Error
429 Too Many Requests Error returned when the request limit for the requested resource is reached. Error
500 Internal Server Error Error returned when an unexpected problem prevents the API from working correctly. If the error persists, contact support. Error
503 Service Unavailable Error returned when a resource or system service is not available. If the error persists, contact support. Error