API V1 - Hub de Marketplaces - ERP

API used when creating a platform-type ERP channel in the Marketplaces Hub

To start developing the integration of the ERP platform with the Marketplaces Hub using the new passive APIs of the Marketplaces Hub, it is necessary to understand that the processing flow requires the ERP channel to have a pair of access credentials to use the APIs authenticated.

This pair of authentication keys can be generated by creating a new platform-type Marketplaces Hub integration with the ERP channel.

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

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.

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

The Marketplaces Hub APIs have two levels of authentication: Application authentication and Integration channel authentication (ERP platform type channel).

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 homologation AppToken, as shown in the example below:

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).

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

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.

POST /v1/logistic/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.

Request

{
	"apiKey": "1234A5678B9012C3456",
	"secretKey":"3456D9012E5678F1234"
}

Request details

Response

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvYXBpLm9tbmkud2Fwc3RvcmUuY29tLmJyXC8iLCJhdWQiOiJBcGkgZGUgVGVzdGUiLCJpYXQiOjE1NTc0NTc2OTYsIm5iZiI6MTU1NzQ1NzY5NiwiZXhwIjoxNTU3NDU5NDk2LCJ0aWQiOiI5MzRjZTY2ZGY5MDQ1YWNmMzY1MGIyZWEzNWUxYjMwMSJ9.Ii148QGob19NI2-fsMbqvMpmVFyGR3bkJjSbOxaCxmg"
}

Response details

GET /v1/logistic/orders/{id}/shipment_labels

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

GET /v1/erp/channels

Response

{
    "canais":[
       {
          "id":123,
          "hash":"abc123",
          "nome":"Canal A",
          "ativo":true
       },
       {
          "id":456,
          "hash":"def456",
          "nome":"Canal B",
          "ativo":false
       }
    ],
    "info":{
       "total":2
    }
 }
 

Response details

GET /v1/erp/products/security-stock

Resource available to check the safety stock of products

This resource can be used to check the amount of safety stock available for products in your store.

Important: If the product does not have safety stock, it will not be returned

Response

{
    "produtosEstoqueSeguranca": {
        "Wapstore Marketplace": [
            {
                "idProduto": 4,
                "skuProduto": "produto-2-tete-36",
                "idCanalIntegracao": 459,
                "qtdEstoqueSeguranca": 12
            }
        ],
        "Shopee": [
            {
                "idProduto": 9,
                "skuProduto": "produto-teste-1",
                "idCanalIntegracao": 708,
                "qtdEstoqueSeguranca": 10
            }
        ]
    },
    "info": {
        "filtros": [],
        "prev": "",
        "self": "https://omni.wapstore.com.br/v1/erp/products/security-stock?offset=0&limit=5",
        "next": "https://omni.wapstore.com.br/v1/erp/products/security-stock?offset=5&limit=5",
        "offset": 0,
        "limit": 2,
        "exibindo": 2,
        "total": 55
    }
}

Response details

PUT /v1/erp/products/security-stock

Resource responsible for changing the safety stock of a product

This resource can be used to update an existing safety stock or create a new one.

Important: The product must be registered on the HUB

Request

{
  "idCanalIntegracao": 205,
  "sku": "TESTE-ITEM02",
  "estoqueSeguranca": 8
}

Request details

Response

{
    "ProdutoEstoqueSeguranca": [
        {
            "idProduto": 3,
            "idAtributoSimples": 2,
            "idCanalIntegracao": 207,
            "idIntegracao": 3,
            "estoqueSeguranca": 10,
            "dataCadastro": "2024-02-15 20:28:35",
            "dataAtualizacao": "2024-02-15 21:39:29"
        },
        {
            "idProduto": 3,
            "idAtributoSimples": 3,
            "idCanalIntegracao": 207,
            "idIntegracao": 3,
            "estoqueSeguranca": 10,
            "dataCadastro": "2024-02-15 20:28:35",
            "dataAtualizacao": "2024-02-15 21:39:29"
        },
        {
            "idProduto": 3,
            "idAtributoSimples": 4,
            "idCanalIntegracao": 207,
            "idIntegracao": 3,
            "estoqueSeguranca": 10,
            "dataCadastro": "2024-02-15 20:28:35",
            "dataAtualizacao": "2024-02-15 21:39:29"
        }
    ]
}

Response details

GET /v1/erp/products/customized-prices

Resource available to consult products with personalized prices in the HUB.

This feature can be used to consult products with personalized prices in your store, returning "from" price and "per" price

Important: If the product does not have a personalized price, it will not be returned

Response

{
    "produtosPrecoPersonalizado": {
        "Dafiti": [
            {
                "idProduto": 77,
                "skuProduto": "Teste",
                "idCanalIntegracao": 177,
                "precoDePersonalizado": "100,00",
                "precoPorPersonalizado": "80,00"
            }
        ],
        "Mercado Livre": [
            {
                "idProduto": 58,
                "skuProduto": "produto-teste",
                "idCanalIntegracao": 177,
                "precoDePersonalizado": "20,00",
                "precoPorPersonalizado": "10,00"
            }
        ]
    },
    "info": {
        "filtros": [],
        "prev": "",
        "self": "https://omni.wapstore.com.br/v1/erp/products/customized-prices?offset=0&limit=2",
        "next": "https://omni.wapstore.com.br/v1/erp/products/customized-prices?offset=2&limit=2",
        "offset": "0",
        "limit": "2",
        "exibindo": 2,
        "total": "14"
    }
}

Response details

PUT /v1/erp/products/customized-prices

Resource available to change/create personalized prices for products registered in the HUB.

With this functionality it is possible for the same product to have different prices per integration channel. This can be applied at both levels: (Product/Variation).

Important: The product must be registered in the HUB.

Request

{
    "precos": [
      {
        "idCanalIntegracao": 1,
        "skuProduto": "ABC123",
        "precoDe": 25.50,
        "precoPor": 20.00
      },
      {
        "idCanalIntegracao": 2,
        "skuProduto": "XYZ789",
        "precoDe": 35.75,
        "precoPor": 30.50
      },
      {
        "idCanalIntegracao": 1,
        "skuProduto": "DEF456",
        "precoDe": 18.99,
        "precoPor": 15.49
      }
    ]
  }
  

Request details

Response

{
    "resultados": [
      {
        "skuProduto": "ABC123",
        "sucessos": [
          {
            "idCanalIntegracao": 1,
            "precoDe": 25.50,
            "precoPor": 20.00
          },
          {
            "idCanalIntegracao": 2,
            "precoDe": 35.75,
            "precoPor": 30.50
          }
        ],
        "erros": []
      },
      {
        "skuProduto": "XYZ789",
        "sucessos": [],
        "erros": [
          {
            "idCanalIntegracao": 1,
            "mensagem": "Produto não encontrado"
          }
        ]
      },
      {
        "skuProduto": "DEF456",
        "sucessos": [
          {
            "idCanalIntegracao": 1,
            "precoDe": 18.99,
            "precoPor": 15.49
          }
        ],
        "erros": []
      }
    ]
  }
  

Response details

DELETE /v1/erp/products/customized-prices/{idCanalIntegracao}/{skuProduto}

Resource responsible for deleting a custom price.

PUT /v1/erp/mercadolivre/items/customized-prices

Resource available to change/create personalized prices for ads in the Hub that are published on MercadoLivre.

Important: The ad must be published on MercadoLivre.

Request

{
    "precos": [
      {
        "idCanalIntegracao": 1,
        "prefixoCanalIntegracao": "MLB",
        "skuProduto": "ABC123",
        "precoDe": 25.50,
        "precoPor": 20.00
      },
      {
        "idCanalIntegracao": 1,
        "prefixoCanalIntegracao": "MLP",
        "skuProduto": "ABC123",
        "precoDe": 35.75,
        "precoPor": 30.50
      },
      {
        "idCanalIntegracao": 1,
        "prefixoCanalIntegracao": "MLF",
        "skuProduto": "DEF456",
        "precoDe": 18.99,
        "precoPor": 15.49
      }
    ]
  }
  

Request details

Response

{
    "resultados": [
      {
        "skuProduto": "ABC123",
        "sucessos": [
          {
            "idCanalIntegracao": 1,
            "prefixoCanalIntegracao": "MLB",
            "codigoMlb": "MLB1999999999",
            "precoDe": 25.50,
            "precoPor": 20.00
          },
          {
            "idCanalIntegracao": 1,
            "prefixoCanalIntegracao": "MLP",
            "codigoMlb": "MLB2999999999",
            "precoDe": 35.75,
            "precoPor": 30.50
          }
        ],
        "erros": []
      },
      {
        "skuProduto": "DEF456",
        "sucessos": [],
        "erros": [
          {
            "idCanalIntegracao": 1,
            "prefixoCanalIntegracao": "MLF",
            "mensagem": "Não foi possível localizar anúncios Grátis para este SKU."
          }
        ]
      }
    ]
  }
  

Response details

DELETE /v1/erp/mercadolivre/items/customized-prices/{idCanalIntegracao}/{prefixoCanalIntegracao}/{skuProduto}

Resource responsible for deleting a custom price.

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": "Requisição rejeitada.",
    "details": [
        "O SKU 'TESTEAPISIMPLES' já está cadastrado"
    ]
}