API V1 - Hub de Marketplaces - ERP

API utilizada ao criar um canal de ERP do tipo plataforma no Hub de Marketplaces

Para começar a desenvolver a integração da plataforma ERP com o Hub de Marketplaces utilizando as novas APIs passivas do Hub de Marketplaces é necessário entender que o fluxo de processamento exige que o canal ERP possua um par de credenciais de acesso para utilizar as APIs autenticadas.

Este par de chaves de autenticação pode ser gerado criando uma nova integração no Hub de Marketplaces do tipo plataforma com o canal ERP.

Os ambientes de produção e homologação são dividos e podem ser acessados pelas URLs abaixo:

Sandbox

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

Produção

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

Requisições POST, PUT e DELETE possuem alguns headers úteis em seu response, contendo o ID da requisição gerada (Request-Id) e os limites de requisições para cada endpoint (X-RateLimit-Limit e X-RateLimit-Remaining). Caso encontre problemas com alguma requisição, basta informar ID da requisição ao time de suporte, pois isso facilitará a obtenção dos logs e diminuirá o tempo de correção do problema.

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

As APIs do Hub de Marketplaces possuem dois níveis de autenticação: Autenticação da aplicação e Autenticação do canal de integração (canal do tipo plataforma ERP).

Autenticação da aplicação

Todas as aplicações integradas possuem um token de identificação chamado AppToken que deve ser enviado no header de todas as requisições, pois sem ele, não é possível identificar a aplicação conectada e sua conexão será negada imediatamente.

Em produção, cada aplicação possui um AppToken exclusivo, porém em homologação, todas as aplicações devem utilizar o AppToken homologacao, conforme o exemplo abaixo:

App-Token: homologacao
Content-Type: application/json
cache-control: no-cache

Autenticação da integração

O segundo nível de autenticação é o da integração, ou seja, da conta do seller a ser requisitada.

A autenticação da integração é feita a partir de um token de acesso temporário, gerado no recurso de autenticação e que deve ser enviado no header de todas as requisões no índice Authorization (exceto a requisição de autenticação, onde apenas o AppToken deve ser enviado).

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

Em produção, temos vários serviços de proteção ligados (firewall, proteção anti DDoS, TLS sempre atualizado, entre outros) e todos esses serviços trabalham para garantir a integridade do sistema (principalmente porque os dados que transitam pela plataforma são sensíveis - dados de cartão, endereços, etc).

Para que seu sistema não seja bloqueado por nossos serviços de segurança e consiga criar uma comunicação estável com nossas APIs de produção, é de suma importância que em todas as requisições sejam enviados user-agents válidos, todas as conexões sejam feitas utilizando o protocolo HTTPS e que seu sistema tenha suporte aos certificados TLS/SSL mais atualizados (utilize algum serviço online como o SSL Labs para verificar qual certificado TLS/SSL é suportado pelos servidores de produção).

Além disso, a utilização de um IP fixo nas requisições de produção também é muito importante, pois nossa equipe de infraestrutura e segurança pode criar regras específicas para esse IP, o que aumenta muito a segurança e diminui o risco de bloqueios.

No ambiente de homologação o risco de bloqueio pelos serviços de segurança é baixo, por isso sempre desenvolva sua aplicação focando nos níveis máximos de segurança que serão exigidos em produção.

POST /v1/logistic/auth

Recurso responsável por gerar o token de autenticação da integração.

Para esse recurso, o único token que deverá enviar no header é o AppToken, pois nesse momento você ainda não terá o token da integração.
Os dados enviados no body (ApiKey e SecretKey) são relacionados a conta de integração do Seller (conta de homologação ou produção).

Após o token ser gerado, ele será válido por 30 minutos e deverá ser enviado no header Authorization das demais APIs.

Importante: Sempre que um novo token for gerado o anterior será revogado e perderá o acesso imediatamente.

Request

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

Detalhes da Request

Response

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

Detalhes do Response

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
  }
}

Detalhes do Response

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
    }
 }
 

Detalhes do Response

GET /v1/erp/products/security-stock

Recurso disponível para consultar o estoque de segurança dos produtos

Esse recurso pode ser utilizado para consultar a quantidade de estoque de segurança disponível dos produtos em sua loja.

Importante: Caso o produto não tenha estoque de segurança ele não será retornado

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
    }
}

Detalhes do Response

PUT /v1/erp/products/security-stock

Recurso responsável por alterar o estoque de segurança de um produto

Esse recurso pode ser utilizado para atualizar um estoque de segurança já existente ou então criar um novo.

Importante: É necessário que o produto esteja cadastrado no HUB

Request

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

Detalhes da Request

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"
        }
    ]
}

Detalhes do Response

GET /v1/erp/products/customized-prices

Recurso disponível para consultar os produtos com preços personalizados no HUB.

Esse recurso pode ser utilizado para consultar os produtos com preços personalizados de sua loja, retornando preço "de" e preço "por"

Importante: Caso o produto não tenha preço personalizado ele não será retornado

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"
    }
}

Detalhes do Response

PUT /v1/erp/products/customized-prices

Recurso disponível para alterar/criar preços personalizados de produtos cadastrados no HUB.

Com essa funcionalidade é possível que um mesmo produto tenha preços diferentes por canal de integração. Isso pode ser aplicado nos dois níveis: (Produto/Variação).

Importante: É necessário que o produto esteja cadastrado no 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
      }
    ]
  }
  

Detalhes da Request

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": []
      }
    ]
  }
  

Detalhes do Response

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

Recurso responsável por excluir um preço personalizado.

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

Recurso disponível para alterar/criar preços personalizados de anúncios no Hub que estão publicados no MercadoLivre.

Importante: É necessário que o anúncio esteja publicado no 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
      }
    ]
  }
  

Detalhes da Request

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."
          }
        ]
      }
    ]
  }
  

Detalhes do Response

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

Recurso responsável por excluir um preço personalizado.

Todas as requisições que resultarem em erros, terão o mesmo padrão de retorno. O código de status HTTP retornado indicará se o problema está na requisição (client-site - 4xx) ou no processamento (server-site - 5xx) e a mensagem descreverá os detalhes adicionais sobre o problema.

{
    "error": "Requisição rejeitada.",
    "details": [
        "O SKU 'TESTEAPISIMPLES' já está cadastrado"
    ]
}