Abaixo um exemplo de como seria o retorno de erro em um pedido no status SHIPPED:
``` https://api.skyhub.com.br/orders/{code}/cancel ``` #### Request body: ``` curl --location --request POST 'https://api.skyhub.com.br/orders/Lojas Americanas-1200000000002/cancel' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "status": "order_canceled" }' ``` #### Response esperado: {% hint style="danger" %} **422 - O pedido não pode ser cancelado devido ao seu status atual. Para prosseguir, realize a devolução do pedido no portal.** {% endhint %} # Última chamada para ajustes obrigatórios da API Informamos que, a partir de 11/08/2025, todas as atualizações que não seguirem o padrão estabelecido deixarão de funcionar. De acordo com nossa programação, será necessário adequar a documentação atual, pois os de/para anteriormente configurados no portal da Skyhub não estarão mais disponíveis. As atualizações deverão seguir rigorosamente o padrão definido nesta documentação. ### Como se adequar: * Consultar IDs de categorias (/categories) e marcas (/brands). [Categories](https://desenvolvedores.skyhub.com.br/comunicados/comunicados-2025/criacao-e-atualizacao-de-produtos-e-variacoes-no-marketplace) * Preencher corretamente o array specifications. [Specifications](https://desenvolvedores.skyhub.com.br/comunicados/comunicados-2025/criacao-e-atualizacao-de-produtos-e-variacoes-no-marketplace?q=specifications#como-era-antes-4) * Garantir valores válidos de price e promotional\_price. [Price e promotional\_price](https://desenvolvedores.skyhub.com.br/comunicados/comunicados-2025/criacao-e-atualizacao-de-produtos-e-variacoes-no-marketplace#como-sera-agora) * Enviar o campo crossdocking. [Crossdocking](https://desenvolvedores.skyhub.com.br/comunicados/comunicados-2025/criacao-e-atualizacao-de-produtos-e-variacoes-no-marketplace#crossdocking) * Sempre enviar variações completas ao atualizá-las. [Variations](https://desenvolvedores.skyhub.com.br/comunicados/comunicados-2025/criacao-e-atualizacao-de-produtos-e-variacoes-no-marketplace) Em caso de dúvidas, estamos à disposição através do nosso [canal de atendimento](https://desenvolvedores.skyhub.com.br/comunicados/comunicados-2024/novo-canal-de-atendimento). # Comunicados 2024 Relação de alterações que afetaram a API e entraram em vigor no ano de 2024 # Novo canal de atendimento O nosso e-mail para abertura de chamados referentes a nossa API mudou, fique por dentro desta atualização. Parceiros já integrados que possuem dúvidas ou problemas técnicos relacionados a API SkyHub, ou aqueles que estão iniciando o processo de homologação, agora possuem um novo e-mail para abertura de chamados. Pedimos que passem a utilizar somente o canal abaixo: ####
Exemplo do array categories presente no JSON de um produto
| Tipo | Local | Campo | Objetivo | Endpoints afetados |
|---|---|---|---|---|
| Promoção | items[].promotions[] | “value” | Informar o valor cheio da promoção aplicada no pedido | GET /queues/orders /order/:code /orders |
| Promoção | items[].promotions[] | “seller_value” | Informar o valor que o seller está pagando pela promoção aplicada no pedido | GET /queues/orders /order/:code /orders |
| Promoção | items[].promotions[] | “sponsor_value” | Informar o valor que a Americanas está pagando pela promoção aplicada no pedido | GET /queues/orders /order/:code /orders |
| Promoção | items[].promotions[] | “sponsor_percentage” | Informar o percentual que a Americanas está pagando pela promoção | GET /queues/orders /order/:code /orders |
| Promoção | items[].promotions[] | “calculation_type” | Informar o tipo do cálculo aplicado | GET /queues/orders /order/:code /orders |
| Promoção | items[].promotions[] | “name” | Informar o nome da promoção | GET /queues/orders /order/:code /orders |
| Promoção | items[].promotions[] | “category_type” | Informar a categoria da promoção Valores possíveis: CASH_DISCOUNT, CASHBACK, SCHEDULED, DISCOUNT, SUBTOTAL. | GET /queues/orders /order/:code /orders |
Normalmente ao final da página de mapeamento de campos para o marketplace vemos os campos "B2w Empresas Preço De" e "B2w Empresas Preço Por", utilizados para a definição dos atributos que deverão ser considerados para a precificação de itens para o serviço Americanas Empresas
* Códigos HTTP **4XX** indicam que a requisição contém alguma informação incorreta - dados de acesso, ausência de um campo obrigatório, entre outros;
* Códigos HTTP **5XX** indicam algum erro nos servidores da API. Esses são raros e caso receba esse código, deve entrar em contato com o nosso suporte. ## Status HTTP Os status HTTP mais comuns são:
| Status | Descrição |
|---|---|
| Status | Descrição |
| 200 | Sucesso (A requisição foi processada com sucesso) |
| 201 | Criado (A requisição foi processada com sucesso e resultou em um novo recurso criado) |
| 204 | Sem conteúdo (A requisição foi processada com sucesso e não existe conteúdo adicional na resposta) |
| 400 | Requisição mal formada (A requisição não está de acordo com o formato esperado. Verifique o JSON (body) que está sendo enviado) |
| 401 | Não autenticado (Os dados de autenticação estão incorretos. Verifique no cabeçalho (header) da requisição o e-mail e o token) |
| 403 | Não autorizado (Você está tentando acessar um recurso para o qual não tem permissão) |
| 404 | Não encontrado (Você está tentando acessar um recurso que não existe na SkyHub) |
| 406 | Formato não aceito (A SkyHub não suporta o formato de dados especificado no cabeçalho (Accept)) |
| 415 | Formato de mídia não aceito (A SkyHub não consegue processar os dados enviados por conta de seu formato. Certifique-se do uso do charset UTF-8 (tanto no header "Content-Type", quanto no próprio body da requisição)) |
| 422 | Erro semântico (Apesar do formato da requisição estar correto, os dados ferem alguma regra de negócio (por exemplo: transição inválida do status de pedido)) |
| 429 | Limite de requisições ultrapassado (Você fez mais requisições do que o permitido em um determinado recurso) |
| 500 ou 502 | Erro interno (Ocorreu um erro no servidor da SkyHub ao tentar processar a requisição) |
| 503 | Serviço indisponível (A API da SkyHub está temporariamente fora do ar) |
| 504 | Timeout (A requisição levou muito tempo e não pôde ser processada) |
| Endpoint | Limite de Requisições | Métodos | |
|---|---|---|---|
| Endpoint | Limite de Requisições | Métodos | Observações |
| Products | 9 por segundo | GET | Buscar lista ou SKU individual compartilham do mesmo limite |
| Products | 9 por segundo | POST, PUT, DELETE | Limite definido para cada método |
| Variations | 9 por segundo | PUT, DELETE | Limite definido para cada método |
| Orders | 9 por segundo | POST, PUT, DELETE | Cada endpoint em orders possui 9/s para cada método |
| Orders | 1 por segundo | GET | Buscar lista ou pedido individual possuem seu próprio limite |
| Queues | 9 por segundo | GET, DELETE | Limite definido para cada método |
| Shipments (PLP) | 9 por segundo | GET, POST, DELETE | Cada endpoint em shipments possui 9/s para cada método |
| Stores | 1 por segundo | GET | Limite definido para cada método |
| Stores | 9 por segundo | POST, PUT | Limite definido para cada método |
| SAC | 9 por segundo | POST, PUT, PATCH, GET | Limite definido para cada método |
| Fulfillment | 1 por segundo | POST, GET | Cada endpoint em fulfillment possui 1/s para cada método |
| Rehub | 27 por segundo | POST, GET, DELETE | Cada endpoint em rehub possui 27/s para cada método |
| QnA | 9 por segundo | POST | Limite definido para o método |
| Outros endpoints | 1 por segundo | POST, PUT, GET, DELETE | Limite definido para cada método |
### Infraestrutura SkyHub
Nossa infraestrutura está localizada nos servidores da Virginia, caso seus servidores estejam alocados em outra região podemos ter um tempo de resposta acrescido em **200ms**.
### Cuidado com o limite de requisições
Tenha cuidado para não ultrapassar os [limites de requisições](/guias-api-skyhub/limite-de-requisicoes) da nossa API. Caso a sua aplicação receba um HTTP 429, ela deve parar de fazer requisições por um tempo até que uma nova janela comece a contar.
{% hint style="danger" %}
Cuidado com datas com um alto volume de vendas, como a **Black Friday**. Acontece do desenvolvedor colocar mais máquinas para ter uma "integração mais rápida" e ser barrado no nosso limite de requisições.
{% endhint %}
### Atualize apenas o necessário
Alguns recursos da API, em especial a de produtos, permitem que apenas alguns campos sejam passados na requisição de atualização.
Se deseja atualizar apenas o campo "*qty*" do produto, por exemplo, recomendamos que o faça semelhante à requisição abaixo:
```
curl --request PUT \
--url https://api.skyhub.com.br/products/{sku}\
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao' \
--header 'X-Accountmanager-Key: token_account_da_plataforma'\
--data '{
"product": {
"qty": 0
}
}'
```
Como podemos observar na requisição acima, é enviada apenas a atualização do estoque, ou seja, não é enviada a estrutura completa do produto.
Desta forma sua aplicação terá que trafegar menos dados na rede, a API terá que processar uma carga menor de dados e haverá um desempenho melhor.
### Atributo de marca
Desde Março/2025 é necessário enviar no corpo do produto o identificador da marca, obtido após uma [**consulta em lista de marcas disponíveis**](/produtos/consultar-marcas).
Para que o produto tenha um filtro bem definido por meio de marca, é importante que este atributo seja declarado de forma correta.
### Categorização de itens
Desde Março/2025 é necessário categorizar os itens antes de criá-los no Marketplace.
Para isso, foi [**disponibilizada uma consulta**](/produtos/categorizacao/consultar-categorias) onde será possível percorrer todas as categorias da Americanas Marketplace e assim enviar no JSON do produto o identificador da categoria desejada.
É uma boa prática o lojista identificar em qual nível de categoria deseja catalogar seus itens e assim enviar no corpo do produto o identificador referente ao nível escolhido.
### Imagens
#### Limite de imagens
Existe um limite de imagens a serem enviadas para a API da Americanas.
Neste caso o total de imagens por produto passa a ser 20 tanto na estrutura do **produto simples** quanto para as **variações**. Sendo assim, caso tenha uma estrutura de **produto variável** é possível enviar 20 imagens para a variação **SKU A** e 20 imagens para a variação **SKU B**.
{% hint style="warning" %}
Caso envie mais de 20 imagens serão consideradas somente as **20 primeiras**.
{% endhint %}
#### Imagens da variação:
Caso no JSON constem imagens no produto pai e nas variações, apenas as imagens das variações serão levadas em conta no Marketplace.
Se no JSON as imagens forem enviadas somente no pai, as variações irão assumir as imagens do produto pai.
### Consulta de pedidos via API
Temos um limitador de retorno (**GET**) de no máximo 10.000 registros para consulta de pedidos.
Caso tenha mais registros para serem retornados o ideal é realizar filtros para adequar a quantidade de retorno de acordo com o limite existente.
### Consumo de pedidos
Para consumir pedidos, todo o processo deve ser feito pelo endpoint [`/queues/orders`](/pedidos/consumo-de-pedidos-queues), para que a SkyHub saiba que o pedido foi integrado.
Embora seja possível listar os pedidos via GET `/orders`, este endpoint como dito deve ser utilizado apenas para listar/consultar e não para consumir.
# Copy of Melhores práticas
Nesta seção é possível verificar as melhores práticas para a execução de requisições e como seguir diante erros retornados pela API
### Monitore a sua aplicação
#### Você monitora os status HTTP 4XX que a sua aplicação está recebendo?
Caso receba um retorno HTTP 4XX, é necessário efetuar a requisição novamente e em paralelo analisar o erro para identificar o seu motivo e realizar as devidas correções.
Uma vez efetuada a correção, caso o erro persista, pedimos que entre em contato para que possamos analisar.
#### Você monitora os status HTTP 5XX que a sua aplicação está recebendo?
Uma vez que o retorno do erro é HTTP 5XX, pedimos que efetue uma nova tentativa, pois o mesmo pode se tratar de uma intermitência.
Caso o erro persista, pedimos que entre em contato para que possamos analisar a causa raiz do erro.
{% hint style="info" %}
Caso necessário entrar em contato com a equipe de suporte ao desenvolvimento de nossa API, basta encaminhar as suas dúvidas para o e-mail *
### Infraestrutura SkyHub
Nossa infraestrutura está localizada nos servidores da Virginia, caso seus servidores estejam alocados em outra região podemos ter um tempo de resposta acrescido em **200ms**.
### Cuidado com o limite de requisições
Tenha cuidado para não ultrapassar os [limites de requisições](/guias-api-skyhub/limite-de-requisicoes) da nossa API. Caso a sua aplicação receba um HTTP 429, ela deve parar de fazer requisições por um tempo até que uma nova janela comece a contar.
{% hint style="danger" %}
Cuidado com datas com um alto volume de vendas, como a **Black Friday**. Acontece do desenvolvedor colocar mais máquinas para ter uma "integração mais rápida" e ser barrado no nosso limite de requisições.
{% endhint %}
### Atualize apenas o necessário
Alguns recursos da API, em especial a de produtos, permitem que apenas alguns campos sejam passados na requisição de atualização.
Se deseja atualizar apenas o campo "*qty*" do produto, por exemplo, recomendamos que o faça semelhante à requisição abaixo:
```
curl --request PUT \
--url https://api.skyhub.com.br/products/{sku}\
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao' \
--header 'X-Accountmanager-Key: token_account_da_plataforma'\
--data '{"qty":0}'
```
Como podemos observar na requisição acima, é enviada apenas a atualização do estoque, ou seja, não é enviada a estrutura completa do produto.
Desta forma sua aplicação terá que trafegar menos dados na rede, a API terá que processar uma carga menor de dados e haverá um desempenho melhor.
### Atributo de marca
Desde Março/2025 é necessário enviar no corpo do produto o identificador da marca, obtido após uma [**consulta em lista de marcas disponíveis**](/produtos/consultar-marcas).
Para que o produto tenha um filtro bem definido por meio de marca, é importante que este atributo seja declarado de forma correta.
### Categorização de itens
Desde Março/2025 é necessário categorizar os itens antes de criá-los no Marketplace.
Para isso, foi [**disponibilizada uma consulta**](/produtos/categorizacao/consultar-categorias) onde será possível percorrer todas as categorias da Americanas Marketplace e assim enviar no JSON do produto o identificador da categoria desejada.
É uma boa prática o lojista identificar em qual nível de categoria deseja catalogar seus itens e assim enviar no corpo do produto o identificador referente ao nível escolhido.
### Atributos na SkyHub
Nossa estrutura de criação de atributos não possibilita que trabalhe com a mesma **string** de um atributo com **case sensitive** tentando diferenciar essa criação. Com isso é necessário que sempre utilize em seus produtos o atributo que foi usado pela primeira vez.
\
Por exemplo, se em um primeiro momento foi criado um atributo **teste** (todas as letras em minúsculo) no array de `specifications`, precisamos que todos os seus produtos da conta recebam o atributo como **teste** (todas as letras em minúsculo). Caso em algum momento após a criação, o atributo receba uma grafia diferente - como **Teste** - não será possível indexá-lo ao produto na SkyHub.
{% hint style="warning" %}
**IMPORTANTE – Conforme o fluxo de CONTA ÚNICA, onde a conta da loja será a mesma independente da Plataforma/ERP que estiver operando, pode ser que o padrão de um sistema não seja o mesmo de outra, por isso é importante saber que pode haver diferenças e orientar os lojistas de acordo com o atributo da maneira que você utiliza.**
{% endhint %}
{% hint style="info" %}
Ao utilizar o endpoint [*`/attributes`*](/produtos/outros-recursos-de-produtos/endpoint-atributos) é possível consultar quais atributos estão criados na conta.
{% endhint %}
### Atributo Garantia
Para o atributo [**Garantia**](/comunicados/comunicados-2021/atributo-garantia-prazo-limite-06-09-21) é esperado o valor numérico e essa informação é a representação da garantia do produto em meses, além disso o atributo deve ser criado no array `specifications` do produto na API.
### Limite de Imagens
Existe um limite de imagens a serem enviadas para a API da Americanas.
Neste caso o total de imagens por produto passa a ser 20 tanto na estrutura do **produto simples** quanto para as **variações**. Sendo assim, caso tenha uma estrutura de **produto variável** é possível enviar 20 imagens para a variação **SKU A** e 20 imagens para a variação **SKU B**.
{% hint style="warning" %}
Caso envie mais de 20 imagens serão consideradas somente as **20 primeiras**.
{% endhint %}
### Consulta de pedidos via API
Temos um limitador de retorno (**GET**) de no máximo 10.000 registros para consulta de pedidos.
Caso tenha mais registros para serem retornados o ideal é realizar filtros para adequar a quantidade de retorno de acordo com o limite existente.
### Consumo de pedidos
Para consumir pedidos, todo o processo deve ser feito pelo endpoint [`/queues/orders`](/pedidos/consumo-de-pedidos-queues), para que a SkyHub saiba que o pedido foi integrado.
Embora seja possível listar os pedidos via GET `/orders`, este endpoint como dito deve ser utilizado apenas para listar/consultar e não para consumir.
# Recursos
São chamados de recursos os objetos a serem tratados na API, como por exemplo: produtos, pedidos e outros. Nessa seção mostraremos os recursos disponíveis na API da Americanas
{% hint style="danger" %}
**Todo recurso desenvolvido deve ser homologado pelo time responsável pela API da Americanas.**
Para maiores informações, entrar em contato com *Como é o processo de homologação?
Após solicitar a homologação de seu sistema, serão liberadas pelo time de suporte a integração as credenciais para uma conta de teste e a lista de tarefas (*cheklist*) que devem ser executadas para a validação dos processos desenvolvidos. Uma vez que as tarefas forem executadas, as evidências para validação devem ser encaminhadas através de um chamado para oO que é e como obtenho o header x-accountmanager-key?
O header *x-accountmanager-key* é o código identificador de seu sistema, ou seja, ele é o código que permite-nos validar qual plataforma está executando requisições para a API da Americanas. Esse identificador é fornecido exclusivamente para parceiros que solicitam o processo de [homologação](/processo-de-homologacao) e deve ser utilizado em todas as requisições via API.Não sou loja e nem plataforma, posso obter as credenciais?
Não. Somente aqueles que irão desenvolver uma solução para integrar junto a Americanas Marketplace receberão as credenciais mediante a solicitação. Não são liberadas credenciais apenas para testes, projetos individuais ou alunos/professores acadêmicos.Quais são os passos para a homologação?
O processo de homologação com a API da Americanas é simples e consiste na validação das requisições e estrutura dos dados enviados nas tarefas solicitadas em nosso *checklist*, encaminhado junto às credenciais da conta de teste (para maiores informações, acesse a guia [Processo de Homologação](/processo-de-homologacao) desta documentação). De forma mais detalhada, os passos para a homologação de seu sistema consistem em: 1. **Definição do perfil para homologação:** É importante compreender qual o perfil do sistema a ser homologado (os perfis podem ser consultados em nossa guia [Perfil para Homologação](/processo-de-homologacao/perfil-para-homologacao)); 2. **Criação da conta de teste:** Após receber o seu acionamento para início do processo de homologação, nossos times irão criar um ambiente de desenvolvimento para a plataforma/ERP. As credenciais para acesso a conta de teste serão informadas via chamado junto às tarefas que deverão ser executadas; 3. **Execução de testes e preenchimento do *****checklist*****:** Em posse das credenciais da conta de teste, o responsável pelo sistema deverá validar o nosso *checklist*, que nada mais é do que a lista de tarefas que precisam ser concluídas para que possamos validar o envio de informações para a API; 4. **Validação do desenvolvimento:** Após a execução e envio das tarefas solicitadas, o time de API da Americanas irá validar as requisições encaminhadas pelo seu sistema.Preciso solicitar uma conta de teste para cada recurso que será homologado?
Não é necessário solicitar uma conta de teste para cada recurso a ser homologado. Ao solicitar a homologação de seu sistema será preciso que realize o processo obrigatório, que visa o desenvolvimento e a validação dos recursos básicos da API (produtos, conexão via rehub, pedidos e etiquetas). No final da homologação básica, a conta de teste fornecida será mantida ativa para que, caso deseje, realize o desenvolvimento e validação (homologação) dos demais [recursos](/recursos) disponibilizados pela API. Um ponto importante é que ao desenvolver um novo recurso é imprescindível que entre em contato com o time de API da Americanas para que a homologação seja validada. Este contato se dá através do e-mailQuero trabalhar somente atualizando estoque, preciso passar por toda a homologação?
Mesmo que a solução a ser desenvolvida deseje operar somente atualizando estoque, preço, consultando pedidos, ou seja, utilizar somente uma das funcionalidades disponíveis, ela terá que obrigatoriamente passar por todo o processo de homologação. Hoje as todas as funcionalidades de produto, pedidos, etiquetas e Rehub são obrigatórios para a plataforma ser homologada conosco.Status 401 ou 403 - não autenticado/não autorizado - na criação/atualização de produtos
Um cenário que pode gerar impacto negativo para a integração ocorre quando o *seller* realiza a inativação de usuários no front da API, porém não atualiza esta informação na plataforma/ERP. Em casos como este é comum as tentativas de envio de requisições para a API – notadas principalmente nos endpoints relacionados aos produtos – retornarem status 401 (não autenticado) ou 403 (não autorizado). Para correção, é necessário entrar em contato com o *seller* para validação das credenciais da conta na API, principalmente os e-mails ativos. Caso as credenciais tenham sido validadas e ainda constem divergências, o time de API deverá ser acionado através de chamado para o e-mailEstamos enviando atualização de preço/estoque, mas no Marketplace não atualiza. O que fazer?
Aqui estão 3 dicas para solução dessa questão. 1° - Valide se no body da requisição os atributos de preço e/ou estoque estão sendo passados conforme solicitamos (dentro da raiz do 'product'/'variation'); 2° - Verifique se o seu produto é simples, ou se possui variações. Para isso, é necessário [realizar um GET no produto](/produtos/consulta-produto) e validar se no array 'variations' possui algum SKU. Não existindo, trata-se de produto simples, já se existir, trata-se de produto variável; 3° - Utilize o endpoint correto para cada tipo de produto. Se o [produto for simples, utilize o '/products'](/produtos/atualizacao-produto/produto-simples), porém [se for variável, utilize o '/variations'](/produtos/atualizacao-produto/produto-variavel-1).Será retornado algum erro ao tentar excluir um produto ainda conectado ao marketplace?
Sim, por padrão a API retorna erros para a exclusão de itens que ainda estão [conectados](/rehub/rehub-acoes-de-produto) ao marketplace Americanas. Caso haja uma tentativa de excluir um produto ainda conectado será retornado o status 422 e a mensagem "*Produto está conectado. Remova todas as conexões e tente novamente*".Fiz o processo de conexão via Rehub porém o produto não foi criado no Marketplace, o que fazer?
Neste caso, é muito provável que o produto possui alguma pendência cadastral que impediu a sua criação. Alguns motivos para o produto não ser criado: * Falta de [atributos obrigatórios](/produtos/integracao-produtos#pre-requisitos-para-a-integracao-de-produtos-em-ambiente-de-teste-e-producao); * Falta de marca; * Falta de categoria; Para saber se houve algum impedimento, é necessário fazer a consulta da carga:Status 403 ao tentar criar um pedido
Como citado em nossa seção de dúvidas sobre o recurso de [Produtos](#produtos), o status 403 é retornado em ações não autorizadas. Em relação a criação de pedidos, o status 403 é comumente visto em casos em que o parceiro realiza tentativas de criar um pedido em uma **conta de produção**. Na seção de [Criação e Aprovação de Pedido Teste](/pedidos/criacao-de-pedido-teste) mencionamos que tanto **criação** quanto **aprovação** de pedidos são ações **exclusivas para as contas de teste**, sendo assim, uma conta de produção não permitirá tais tratativas.Fluxo de status dos pedidos
Para que o pedido seja atualizado corretamente até o ponto de entregue, é necessário que o fluxo de atualização de status seja respeitado. Abaixo o fluxo: * Pagamento pendente * Pagamento aprovado * Pedido faturado * Pedido enviado * Pedido entregue Caso algum status seja pulado, a API retornará **erro na transição de status**. Exemplo: Se uma requisição colocando o pedido para enviado ocorrer primeiro que uma requisição de faturado, ocorrerá o erro citado acima quando a plataforma tentar atualizar a nota fiscal do produto, consequentemente o pedido não terá seu fluxo finalizado no Marketplace.Estou tomando o erro "TRANSIÇÃO INVÁLIDA: STATUS -> STATUS". Qual o motivo?
O erro de transição inválida ocorre quando se tenta atualizar um pedido que já está atualizado para aquele status da tentativa, ou quando se tentar regredir um status.\ \ Por exemplo, um pedido já faturado que a requisição tenta novamente faturar o pedido.\ \ Outro exemplo, um pedido já enviado que a requisição tenta voltar para o status de faturado.Serão emitidas etiquetas para os pedidos gerados em minha conta de teste?
Para o ambiente de teste as etiquetas são disponibilizadas **previamente** com dados fixos, desta forma, os pedidos criados em uma conta de teste não possuirão etiquetas com seus dados. Para realizar todo o fluxo de etiquetas em uma conta de teste - desde a criação do produto até a impressão da etiqueta e solicitação da coleta do pedido - é possível seguir as orientações fornecidas em nosso guia [Etiquetas na conta de teste](https://desenvolvedores.skyhub.com.br/etiquetas-americanas-entrega/homologacao-para-impressao-de-etiquetas-americanas-entregas#etiquetas-na-conta-de-teste) da seção [Integração Etiqueta](https://desenvolvedores.skyhub.com.br/etiquetas-americanas-entrega/integracao-etiqueta), onde disponibilizamos os passos para realizar o vínculo de um pedido criado em ambiente de teste com uma etiqueta previamente gerada.É possível consumir os pedidos Fulfillment separadamente?
Todos os pedidos gerados no marketplace e disponibilizados pela API serão consumidos sem distinção através da [*/queues/orders*](https://desenvolvedores.skyhub.com.br/pedidos/consumo-de-pedidos-queues), isto é, uma vez que o parceiro (*seller*) possui o serviço Fulfillment, todos os pedidos desta modalidade serão disponibilizados junto às demais entregas criadas para a loja. Desta forma, cabe à plataforma/ERP a identificação do tipo do pedido. Caso hajam dúvidas, é possível consultar a guia [Identificando Pedido](https://desenvolvedores.skyhub.com.br/americanas-fulfillment/identificando-pedido) de nossa seção **Fulfillment**.Como o lojista pode obter as credenciais para preencher em nossa plataforma?
O lojista deve entrar no novo portal, realizar login e ir até o Menu **Integrações > Credenciais API.**A marca do lojista não aparece na listagem, como criar o produto?
É possível o lojista solicitar a inclusão de determinada marca abrindo chamado diretamente no portal do lojista.\ \ Outra opção que pode ser realizada até se ter uma resposta do time de atendimento, é enviar o **id da marca** referente a opção "**Não disponível**" que encontra-se na listagem.Após a migração, alguns produtos não estão no novo portal, como corrigir?
Caso algum produto que existia no antigo portal não esteja no novo após a migração, significa que ele não foi migrado por conta de alguma pendência cadastral.\ \ Nesta situação, se faz necessário [**reenviar os produtos para a Skyhub**](/produtos/criacao-de-produto) já respeitando as novas exigências.Criei os produtos mas eles não aparecem no portal, o que fazer?
Após a migração realizada em **Março/2025**, somente produtos enviados de acordo com o que pedimos em [**comunicado enviado aos parceiros**](/comunicados/comunicados-2025/criacao-e-atualizacao-de-produtos-e-variacoes-no-marketplace), serão de fato criados. \ Por isso é importante que a plataforma faça a revisão do que está sendo enviado no body, como o id da marca, id da categoria e os atributos de categoria. Dito isso, são dois processos para habilitar um novo produto a venda no Marketplace:\ \ 1° - Criação do produto (POST em [**/products**](/produtos/criacao-de-produto)); 2° - Conexão do produto via API, utilizando a [**ação de conectar do Rehub**](/rehub/rehub-acoes-de-produto). A tendência é de que se o produto estiver todo correto, será criado no portal do lojista. Caso não seja, se faz necessário consultar se no resultado da carga algum erro ocorreu:\ \O envio do preço ocorre com sucesso (204), porém não é atualizado no Marketplace, o que fazer?
A SkyHub pode retornar sucesso ao receber a atualização de preços, porém pode ocorrer de no momento do envio ao Marketplace ser rejeitado por alguma pendência, onde a mais é comum trata-se de redução maior que 50%.\ \ Para consultar se algum produto teve impedimento na atualização de preço, é possível realizar um GET no endpoint abaixo:\ \3. **Informe sempre o peso do produto:**\ \- Utilize sempre a unidade de medida em **quilograma (Kg)**, por exemplo, 3.0 para três quilos;
4. **Informe sempre as dimensões do produto:**\ \- Utilize sempre a unidade de medida em **centímetros (Cm)**, por exemplo, 20.0 para vinte centímetros.
5. **Informe ao menos uma imagem por produto:**\ \- Um produto sem imagem não pode ser anunciado, portanto, é necessário que seja enviada ao menos uma imagem no produto. ### Pré-requisitos para a homologação Serão desconsiderados, principalmente, os SKUs que apresentaram erros durante o envio da requisição para a API - como, por exemplo, retorno de erro por ausência de um campo obrigatório - ou que apresentarem mais de um método POST, que deve ser utilizado exclusivamente para a criação. Para a homologação com a API da Americanas também serão validados todos os campos que constituem a estrutura de um produto, sendo: * **SKU** (`sku`): Código único responsável pela identificação do produto e por este motivo não pode ser repetido em outro item; * **Nome** (`name`): Breve título capaz de refletir de forma objetiva a proposta do item (por exemplo: Camiseta branca); * **Descrição** (`description`): A descrição deve conter mais caracteres que o título definido e precisa trazer o detalhamento do produto criado. Neste campo não são aceitas tags HTML (com exceção de \
e \
devidamente abertas e fechadas) e expressão regular;
* **Status** (`status`): Campo que irá definir se um produto está ativo (*enabled*) ou inativo (*disabled*) para a venda;
* **Quantidade** (`qty`): Número inteiro que representa o estoque do item;
* **Preço** (`price`): Valor de venda do produto;
* **Preço promocional** (`promotional_price`): Em ambiente de produção, caso o produto não possua ou deseje não trabalhar com **"promotional\_price"**, ele deve ser nulo. Para a homologação, o preenchimento do campo é validado;
* **Crossdocking** ( crossdocking ): Define o tempo de expedição do produto;
* **Custo** (`cost`): Custo do produto para o lojista;
* **Peso** (`weight`): Deverá ser considerado com quilograma (kg) e informado como inteiro, por exemplo, 3.0 será considerado três quilos;
* **Altura** (`height`): Todas as dimensões deverão ser considerados em centímetro (cm), por exemplo, 20.0 será considerado como 20 centímetros;
* **Largura** (`width`): Todas as dimensões deverão ser considerados em centímetro (cm);
* **Comprimento** (`length`): Todas as dimensões deverão ser considerados em centímetro (cm);
* **Marca** (`brand`): Será validado se o campo foi preenchido como *string*;
* **EAN** (`ean`): Será validado se o campo foi preenchido como *string* contendo de 13 a 14 números;
* **NBM** (`nbm`): Para a homologação será validado se o campo foi preenchido como *string* contendo de 8 a 10 caracteres;
* **Imagens** (`images`): Todas as imagens encaminhadas para a API devem estar no formato *https* e o servidor não pode ter redirecionamentos;
* **Especificações** (`specifications`): Responsável por receber todas as informações adicionais para um produto, como voltagem, tamanho, cor, entre outros atributos disponíveis.
Navegue pelas guias abaixo e acompanhe o detalhamento de cada ação de produto:
{% content-ref url="/pages/-MG4Gis5UfYeVHsMwz1j" %}
[Criação de Produto](/produtos/criacao-de-produto)
{% endcontent-ref %}
{% content-ref url="/pages/-MG4KKKK7iO8kF9S7J30" %}
[Atualização de Produto](/produtos/atualizacao-produto)
{% endcontent-ref %}
{% content-ref url="/pages/-MGPs\_Se8fX9P-Bng5q3" %}
[Consulta de Produto](/produtos/consulta-produto)
{% endcontent-ref %}
{% content-ref url="/pages/-MG4JxT8yc3BFw4grZQU" %}
[Exclusão de Produto](/produtos/excluir-produto)
{% endcontent-ref %}
{% content-ref url="/pages/-MG4Glj0PPvakqUVOzYu" %}
[Outros Recursos de Produtos](/produtos/outros-recursos-de-produtos)
{% endcontent-ref %}
# Categorização
Agora para a conexão de itens se faz necessário o envio da categorização no corpo da requisição do produto. Nesta seção, traremos informações relacionadas a como você deverá categorizar os produtos.
A obrigatoriedade de preenchimento ou não ocorrerá de acordo com as configurações das regras nas Americanas. O mesmo ocorrerá para as Marcas.\
\
Para isso, será necessário antes de conectar os produtos, **consultar a lista de categorias**, **consultar as marcas** e também realizar a **consulta por atributos de categorias**. Preparamos um seção para cada consulta:
{% content-ref url="/pages/kp4v2QwIFUATPgAI4Hc2" %}
[Consultar Categorias](/produtos/categorizacao/consultar-categorias)
{% endcontent-ref %}
{% content-ref url="/pages/EoPEomzLALPmd94hLzE2" %}
[Consultar atributos por categoria](/produtos/categorizacao/consultar-atributos-por-categoria)
{% endcontent-ref %}
#### Você pode também saber mais sobre Marcas:
{% content-ref url="/pages/tBFjsMyZAgV9oaM1N5qo" %}
[Consultar Marcas](/produtos/consultar-marcas)
{% endcontent-ref %}
# Consultar Categorias
Nesta seção indicaremos como realizar a consulta na lista de categorias da Americanas.
Ao consultar a lista de Categorias, será possível consultar o ID de uma determinada e assim incluí-lo no JSON de produtos, também obrigatoriedade de atributos nelas.
## GET - Consulta lista de categorias
```
https://api.skyhub.com.br/categories
```
{% hint style="info" %}
A consulta trará 5 categorias, mas é possível utilizar o **limit** para trazer mais conforme necessidade (Máx. 100). Também é possível aplicar a paginação através do parâmetro ***offset**.*
{% endhint %}
#### Request headers:
| Key | Value |
|---|---|
| X-User-Email | email_de_usuario |
| X-Api-Key | token_de_integracao de sua conta SkyHub |
| X-Accountmanager-key | token_account único de cada Plataforma/ERP |
| Accept | application/json |
| Content-Type | application/json |
{
"total": 1000,
"limit": 10,
"offset": 2,
"values": [
{
"tenant": "TALD00776574000660",
"operator": "TALD00776574000660",
"account": null,
"createDate": "2025-01-01T08:42:00.627000",
"lastUpdate": "2025-01-01T08:42:41.454000",
"lastEvent": null,
"id": "3",
"channel": "TALD00776574000660",
"eanRequired": false,
"categoryData": {
"tag": "x-x-x",
"id": "x",
"name": "Nome",
"id1": "x",
"name1": "Nome 1",
"id2": "x",
"name2": "Nome 2",
"id3": "x",
"name3": "Nome 3"
},
"attributes": [
{
"marketplace": "TALD00776574000660",
"name": "x",
"nameId": "x",
"value": "",
"valueId": "",
"group": "Grupo",
"grupId": "x",
"type": "Texto",
"typeId": "1",
"descriptionValue": "",
"toSKU": false,
"variant": false,
"binary": false,
"active": true,
"required": false
}
]
}
]
}
| key | value |
|---|---|
| X-User-Email | email_de_usuario |
| X-Api-Key | token_de_integracao de sua conta SkyHub |
| X-Accountmanager-key | token_account único de cada Plataforma/ERP |
| Accept | application/json |
| Content-Type | application/json |
# Consultar atributos por categoria Nesta seção indicaremos como realizar a consulta nos atributos de categorias da Americanas. Consultando os atributos por categorias, será possível identificar aqueles que serão obrigatórios a presença no JSON do produto. ## Como funciona? Haverá atributos com os seguintes tipos: * Text * Multi-Line Text * Number * Indexed Text * Indexed Multi-Line Text * Combo * Radio * Checkbox Atributos em verde são conhecidos como "atributos de preenchimento livre", já os atributos em vermelho vão precisar seguir um padrão já determinado pela Americanas. Isso significa que ao criar um produto na Americanas, será necessário identificar o tipo do atributo. Sendo um atributo de preenchimento livre, haverá a possibilidade de ser enviado um texto livre no atributo, já os atributos "combo, radio e checkbox", serão preenchidos com valores já pré-determinados pelo Marketplace. Detalharemos mais na documentação de [**Criação de Produtos**](/produtos/criacao-de-produto).
## GET - Consultar atributos por Categoria ``` https://api.skyhub.com.br/categories/{id}/attributes ``` {% hint style="info" %} Atributos ajudam na filtragem e visibilidade do produto no e-commerce, além de serem essenciais para a integração com o marketplace. Porém, não serão todos os atributos de categorias obrigatórios, será necessário atentar-se ao valor do atributo **required**. {% endhint %} {% hint style="warning" %} A consulta de atributos por categoria retornará um campo chamado "**toSKU**", onde este define se o atributo deve ser enviado no produto ***PAI*** ou na sua ***variação***.\ \ Caso o "**toSKU**" seja false, o atributo deve ser enviado nas especificações do produto pai. Caso true, deverá ser enviado nas especificações do produto filho.\ \ Porém, se por acaso o "**toSKU**" seja true e o produto se tratar de um produto simples, o atributo deverá ser enviado no "**specifications"** do produto normalmente. {% endhint %} #### Request headers:
| Key | Value |
|---|---|
| X-User-Email | email_de_usuario |
| X-Api-Key | token_de_integracao de sua conta SkyHub |
| X-Accountmanager-key | token_account único de cada Plataforma/ERP |
| Accept | application/json |
| Content-Type | application/json |
| Key | Value |
|---|---|
| X-User-Email | email_de_usuario |
| X-Api-Key | token_de_integracao de sua conta SkyHub |
| X-Accountmanager-key | token_account único de cada Plataforma/ERP |
| Accept | application/json |
| Content-Type | application/json |
### Como declarar atributos de categoria Os atributos de categoria devem ser declarados dentro de "specifications", mas com distinções dependendo do tipo de atributo.\ \ Conforme explicado em [**Consultar atributos por categoria**](/produtos/categorizacao/consultar-atributos-por-categoria), há diferenças entre os tipos de atributos:
* Atributos de Livre preenchimento:\ \ Em "specifications" a key “value” e “key” ainda são obrigatórias. * Atributos com valores já pré-determinados:\ \ Caso a categoria da especificação seja uma do tipo que receba “idValue”, ainda sera necessário enviar “value”, com o valor correspondente e “key” com o atributo em si. Exemplo: Imagine que o "idValue" represente “Sim”, então o payload seria: ```json { “key”: “is_kit”, "id": "1", "idValue": "2", "value": "Sim" } ``` #### Atenção ao campo "toSKU" A consulta de atributos por categoria retornará um campo chamado "**toSKU**", onde este define se o atributo deve ser enviado no produto ***PAI*** ou na sua ***variação***.\ \ Caso o "**toSKU**" seja false, o atributo deverá ser enviado nas especificações do produto pai. Caso true, deverá ser enviado nas especificações do produto filho. Porém, se por acaso o "**toSKU**" seja true e o produto se tratar de um produto simples, o atributo deverá ser enviado no "**specifications"** do produto normalmente. {% hint style="info" %} Atributos com o '**required**' igual a *True* ao consultar os atributos da categoria, deverão obrigatoriamente constar no JSON do produto. Os demais, são opcionais o envio porém importantes para enriquecimento de cadastro. {% endhint %} ## POST - Cadastrando um produto simples Para realizar o cadastro de um produto via API deverá ser utilizado o método POST para o seguinte endpoint: ``` https://api.skyhub.com.br/products ``` #### Request headers:
| Key | Value |
|---|---|
| X-User-Email | email_de_usuario |
| X-Api-Key | token_de_integracao de sua conta SkyHub |
| X-Accountmanager-key | token_account único de cada Plataforma/ERP |
| Accept | application/json |
| Content-Type | application/json |
* Atributos de Livre Preenchimento:\ \ Em '**specifications**' deve ser declarado ***id*** (identificador do atributo), ***value*** (texto livre e não tem um dado estruturado, ou seja, não há idValue para ser enviado), **key** (atributo) e **value** (valor em texto livre do atributo).
* Atributos com valores já pré-determinados:\ \ Em '**specifications**' deve ser declarado ***id*** (identificador do atributo), ***idValue*** (identificador do valor escolhido dentro do array *valueData*), **key** (atributo) e **value** (valor em texto livre do atributo). #### Atenção ao campo "toSKU" A consulta de atributos por categoria retornará um campo chamado "**toSKU**", onde este define se o atributo deve ser enviado no produto ***PAI*** ou na sua ***variação***.\ \ Caso o "**toSKU**" seja false, o atributo deve ser enviado nas especificações do produto pai. Caso true, deverá ser enviado nas especificações do produto filho. Porém, se por acaso o "**toSKU**" seja true e o produto se tratar de um produto simples, o atributo deverá ser enviado no "**specifications"** do produto normalmente. {% hint style="info" %} Atributos com o '**required**' igual a *True* ao consultar os atributos da categoria, deverão obrigatoriamente constar no JSON do produto. Os demais, são opcionais o envio. {% endhint %} {% hint style="warning" %} Atributos de categoria são diferentes de atributos de produtos. Atributos de categoria possuem o padrão "id" e "idValue"/"value", já os atributos de produto possuem o padrão "key" e "value". {% endhint %} ## **POST - Cadastrando um produto variável** Para realizar o cadastro de um produto variável via API deverá ser utilizado o método POST para o seguinte endpoint: ``` https://api.skyhub.com.br/products ``` **Request headers:** | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | X-Api-Key | token\_de\_integracao de sua conta SkyHub | | X-Accountmanager-key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | A diferença para o JSON do produto simples é que no cadastro da variação é informado o array variations com as informações dos SKUs agrupados, seus atributos diferenciadores e outras especificações. Dentro de 'specifications' deverá ser declarado o(s) atributo(s) de variação(ões) preenchido(s), de acordo com consulta prévia no endpoint de atributos de categoria. \ \ Como informado mais acima, atributos que possuírem o campo "**toSKU**" como true, tratam-se de atributos de variação e devem ser enviados dentro das especificações das variações. #### Request body: ```json { "product": { "sku": "CodigoSKU_agrupador", "name": "Título", "brand": "Código da Marca", // Obtido realizando o GET em Marcas "categoryId": "Id da Categoria", // Obtido realizando o GET na lista de Categorias "description": "Descrição detalhada do produto criado", "status": "enabled", // Status (ativo/enabled ou inativo/disabled) "price": 0.0, // Preço "promotional_price": 0.0, // Preço promocional "cost": 0, // Custo do produto para o seller "weight": 0, // Peso "height": 0, // Altura "width": 0, // Largura "length": 0, // Comprimento "crossdocking": "3", // Crossdocking "nbm": "NBM/NCM", "images": [ "" ], "specifications": [ // Objeto responsável pela inclusão de atributos { // Atributo de categoria - preenchimento livre "id": "id do atributo", "value": "Texto livre", "key": "atributo" }, { // Atributo de categoria - valores pré-determinados "id": "id do atributo", "idValue": "id da opção selecionável", "key": "atributo", "value": "valor do atributo" } ], "variations": [ { "sku": "CodigoSKU_variacao", "qty": 0, // Estoque "ean": "EAN (European Article Number ou Numeração Europeia de Artigos, o código de barras do item)", "price": 0.00, // Preço "status": "enabled", "promotional_price": 0.00, // Preço promocional "weight": 0, // Peso "height": 0, // Altura "width": 0, // Largura "length": 0, // Comprimento "crossdocking": "3", // Crossdocking "images": [ "https:// URL da imagem" // Imagem da variação ], "specifications": [ // Objeto responsável pela inclusão de atributos // Somente atributos com "toSKU" igual a True { // Atributo de categoria - preenchimento livre "id": "id do atributo", "key": "atributo", "value": "Texto livre" }, { // Atributo de categoria - valores pré-determinados "id": "id do atributo", "key": "atributo", "value": "valor do atributo", "idValue": "id da opção selecionável" } ] } ] } } ``` {% hint style="warning" %} Há um **limite** de **100 variações** que podem ser inclusas na estrutura de um produto, sendo necessário respeitar tal limitação para não haverem reprovas ao encaminhar o SKU variável para a API. {% endhint %} #### **Exemplo de request:** Veja abaixo o JSON de criação de um produto com variações, sendo o SKU P2022 o ID do produto "pai" e os SKUs F2023 e F2024 os IDs das variações: ```json curl --location --request POST 'https: //api.skyhub.com.br/products' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "product": { "sku": "P2022", "name": "Identificador de cédula falsa", "brand": "Skyhub", "categoryId": "24", "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.", "status": "enabled", "price": 100.00, "promotional_price": 99.00, "cost": 0.0, "weight": 0.100, "height": 20, "width": 30, "length": 20, "nbm": "98769898", "images": [ "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "id": "id_do_atributo", "value": "Texto livre", "key": "atributo" }, { "id": "id_do_atributo", "key": "atributo", "value": "Texto livre", "idValue": "id_da_opcao_selecionavel" } ], "variations": [ { //Price e promotional price herdados do pai "sku": "F2023", "status": "enabled", "qty": 10, "ean": "9876543210987", "weight": 0.100, "height": 20, "width": 30, "length": 20, "crossdocking": "3", "images": [ "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "id": "29229", // ID referente a voltagem "key": "atributo", "value": "Texto livre", "idValue": "49105" } ] }, { //Price herdado do pai "sku": "F2024", "promotional_price": 89.99, "status": "enabled", "qty": 10, "ean": "9876543210985", "weight": 0.100, "height": 20, "width": 30, "length": 20, "crossdocking": "3", "images": [ "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "id": "29229", // ID referente a voltagem "key": "voltagem", "value": "220v", "idValue": "49106" } ] } ] } }' ``` **Response esperado:** {% hint style="success" %} 201 \[Sucess] - Created {% endhint %} Exemplo de produto criado com sucesso da requisição: ```json { "name": "Identificador de cédula falsa", "nbm": null, "ncm": null, "sku": "P2022", "brand": "Skyhub", "status": "enabled", "ean": null, "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.", "product_condition": null, "qty": 0, "crossdocking": 0, "price": 0.0, "promotional_price": 0.0, "height": 20.0, "width": 30.0, "length": 20.0, "weight": 0.1, "cost": 0.0, "images": [ "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg", "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "variation_attributes": [], "variations": [ { "ean": "9876543210987", "sku": "F2023", "name": "Identificador de cédula falsa", "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.", "nbm": "98769898", "ncm": null, "status": "enabled", "product_condition": null, "crossdocking": 3, "qty": 10, "price": 100.0, "cost": 0.0, "promotional_price": 99.0, "height": 20.0, "width": 30.0, "length": 20.0, "weight": 0.1, "images": [ "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "id": "29229", "key": "atributo", "idValue": "49105", "value": "Texto livre" } ] }, { "ean": "9876543210985", "sku": "F2024", "name": "Identificador de cédula falsa", "description": "Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.", "nbm": "98769898", "ncm": null, "status": "enabled", "product_condition": null, "crossdocking": 3, "qty": 10, "price": 100.0, "cost": 0.0, "promotional_price": 89.99, "height": 20.0, "width": 30.0, "length": 20.0, "weight": 0.1, "images": [ "https://a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "id": "29229", "key": "voltagem", "idValue": "49106", "value": "220v" } ] } ], "specifications": [ { "id": "id_do_atributo", "key": "atributo", "idValue": "id_da_opcao_selecionavel", "value": "Texto livre" } ], "categories": [ { "code": "24", "name": "Automação comercial" } ] } ``` **Exemplo de resposta caso o preço do pai e o preço promocional do pai sejam enviados com 0 ou nulo.** {% hint style="danger" %} 422 \[Error] - Unprocessable Entity {% endhint %} **Response body:** ```json { "error": "Os seguintes SKUs possuem preços inválidos: F2023, F2024. O preço não pode ser nulo ou igual a zero." } ``` # Copy of Produto Variável O produto variável é aquele onde há um agrupamento de dois ou mais SKUs tendo um atributo diferenciador para distingui-los. Nesta seção temos a estrutura para a criação desse tipo de produto {% hint style="danger" %} **Não estão ainda em produção alterações a respeito de Categorização, Marcas e atributos de categorias.** {% endhint %} Produto variável é aquele em que um ou mais SKUs são agrupados; estes SKUs serão diferenciados através de atributos específicos, como tamanho ou cor, por exemplo. Atributos como cor, tamanho e voltagem podem ser definidos tanto a nível de produto quanto a nível de SKU (variações). Será necessário consultar a lista de atributos da categoria e identificar se a categoria aceita esses atributos, porém detalhamos mais abaixo. Mesmo para produtos variáveis é necessário haver atributos e informações que fortaleçam a identidade do item, como um título claro e características bem definidas em sua ficha técnica. Acompanhe o exemplo abaixo: Quando tratamos uma camiseta é necessário fornecer uma breve descrição de suas características dentro do título, a fim de chamar a atenção de um potencial cliente (por exemplo, Título: Camiseta Branca Lisa). Além disso, também faz-se necessário incluir atributos de ficha técnica, como material, fabricante, marca, dentre outros para enriquecer o cadastro do item quando anunciado. Esses atributos de ficha técnica favorecem a localização do produto na realização de filtros nos sites de e-commerce e o título destaca a escolha do cliente final ao realizar as buscas. Mas não é só isso, existem vários outros requisitos necessários para a integração com o marketplace, como o correto preenchimento do peso, dimensões, status, indexação de imagens, além da inclusão em sua correta estrutura mercadológica. {% hint style="info" %} A seção [Integração: Produto](/produtos/integracao-produtos#pre-requisitos) desta documentação é capaz de fornecer maiores detalhes sobre os pré-requisitos necessários para a integração de produtos com o marketplace {% endhint %} A seguir confira a estrutura esperada para a criação de um produto variável via API. ## Estrutura do JSON {% hint style="danger" %} **A estrutura básica para a criação de um produto variável contém campos que devem ser preenchidos com os ****formatos de dados determinados pela API****.** A seguir são apresentados os campos que constituem a estrutura de um produto variável e o formato a ser utilizado para inclusão dos dados. A não utilização dos formatos corretos para preenchimento dos dados pode acarretar em reprova proveniente do marketplace, impossibilitando a publicação da oferta. {% endhint %} {% hint style="info" %} **Dentro de "specifications", somente ****atributos de categoria****.** A partir de Março/2025, no array specifications deverá constar somente atributos de categoria. Mais abaixo explicamos o funcionamento destes atributos. {% endhint %} ``` { "product": { // Object "sku": "CodigoSKU_agrupador", // String "name": "Título", // String "brand": "CodigoMarca", // String "categoryId": "IdCategoria", // String "description": "Descrição", // String "status": "enabled", // String "price": 0.0, // Double "promotional_price": 0.0, // Double "cost": 0, // Double "weight": 0, // Double "height": 0, // Double "width": 0, // Double "length": 0, // Double "brand": "Marca", // String "nbm": "NCM (Nomenclatura Comum do Mercosul)", // String "images": [ // Array "URL da imagem" // String ], "specifications": [ // Array { // Object "key": "Atributo", // String "value": "Valor do atributo" // String }, { // Object "id": "Valor", // String "idValue" // String }, { // Object "id": "valor", // String "value": "valor" // String } ], "variations": [ // Array { // Object } ], "variation_attributes":[ // Array "atributo1", "atributo2", "atributo3" ] } } ``` ### Como declarar a categoria Será necessário realizar a consulta na lista de categorias para obter o **categoryId** e preencher no body do JSON. Para isso, seguir a documentação [**Consultar lista de categorias**](/produtos/categorizacao/consultar-categorias). Haverá os IDs disponíveis **'id'**, 'id1', 'id2' e 'id3'. Os IDs enumerados representam os níveis de categorias, enquanto o ID em verde representa toda a estrutura. Qualquer um desses IDs disponíveis deve constar em **categoryId**, vai depender do nível em que o lojista deseja catalogar seu produto. ### Como declarar a marca Será necessário realizar a consulta das marcas para obter o **brand** e preencher no body do JSON. \ \ Para isso, seguir a documentação [**Consultar Marcas**](/produtos/consultar-marcas). ### Como declarar atributos de categoria Os atributos de categoria devem ser declarados dentro de '**specifications**', porém com distinção em relação aos demais atributos.\ \ Como visto em [**Consultar atributos por categoria**](/produtos/categorizacao/consultar-atributos-por-categoria), há diferenças entre os tipos de atributos:
* Se for um atributo de livre preenchimento:\ \ Em '**specifications**' deve ser declarado ***id*** (id do atributo) e ***value*** (texto livre e não tem um dado estruturado, ou seja, não há idValue para ser enviado).\
* Se for um atributo com valores já pré-determinados:\ \ Em '**specifications**' deve ser declarado ***id*** (id do atributo) e ***idValue*** (id do valor de uma das opções presente no array *valueData*). #### Atenção ao campo "toSKU" A consulta de atributos por categoria retornará um campo chamado "**toSKU**", onde este define se o atributo deve ser enviado no produto ***PAI*** ou na sua ***variação***.\ \ Caso o "**toSKU**" seja false, o atributo deve ser enviado nas especificações do produto pai. Caso true, deverá ser enviado nas especificações do produto filho. Porém, se por acaso o "**toSKU**" seja true e o produto se tratar de um produto simples, o atributo deverá ser enviado no "**specifications"** do produto normalmente. {% hint style="info" %} Atributos com o '**required**' igual a *True* ao consultar os atributos da categoria, deverão obrigatoriamente constar no JSON do produto. Os demais, são opcionais o envio. {% endhint %} {% hint style="warning" %} Atributos de categoria são diferentes de atributos de produtos. Atributos de categoria possuem o padrão "id" e "idValue"/"value", já os atributos de produto possuem o padrão "key" e "value". {% endhint %} ## **POST - Cadastrando um produto variável** Para realizar o cadastro de um produto variável via API deverá ser utilizado o método POST para o seguinte endpoint: ``` https://api.skyhub.com.br/products ``` **Request headers:** | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | X-Api-Key | token\_de\_integracao de sua conta SkyHub | | X-Accountmanager-key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | A diferença para o JSON do produto simples é que no cadastro da variação é informado o array variations com as informações dos SKUs agrupados, seus atributos diferenciadores e outras especificações. Dentro de 'specifications' deverá ser declarado o atributo de variação preenchido, de acordo com consulta prévia no endpoint de atributos de categoria. {% hint style="danger" %} Todo produto variável deve contar com o *array **variation\_attributes***, onde deverão ser informados os atributos responsáveis pela diferenciação das variações. Por exemplo, ao cadastrar uma camiseta e preencher para os SKUs filhos - aqueles vinculados a um SKU agrupador/pai - o atributo "Tamanho" para diferenciar uma variação da outra, é esperado que o mesmo atributo ("Tamanho") seja informado no *array **variation\_attributes***. {% endhint %} #### Request body: ``` { "product": { "sku": "CodigoSKU_agrupador", "name": "Título", "brand": "Código da Marca", // Obtido realizando o GET em Marcas "categoryId": "Id da Categoria", // Obtido realizando o GET na lista de Categorias "description": "Descrição detalhada do produto criado", "status": "enabled", // Status (ativo/enabled ou inativo/disabled) "price": 0.0, // Preço "promotional_price": 0.0, // Preço promocional "cost": 0, // Custo do produto para o seller "weight": 0, // Peso "height": 0, // Altura "width": 0, // Largura "length": 0, // Comprimento "brand": "Marca", "nbm": "NBM/NCM", "images": [ "" ], "specifications": [ // Objeto responsável pela inclusão de atributos { "key": "Atributo", "value": "Valor do atributo" }, { // Atributo de categoria - preenchimento livre "id": "id do atributo", "value": "Texto livre" }, { // Atributo de categoria - valores pré-determinados "id": "id do atributo", "idValue": "id da opção selecionável" } ], "variations": [ { "sku": "CodigoSKU_variacao", "qty": 0, // Estoque "ean": "EAN (European Article Number ou Numeração Europeia de Artigos, o código de barras do item)", "images": [ "https:// URL da imagem" // Imagem da variação ], "specifications": [ // Objeto responsável pela inclusão de atributos { "key": "Atributo", "value": "Valor do atributo" }, { "key": "Atributo", "value": "Valor do atributo" }, { "key": "price", "value": "0.0" // Preço da variação }, { "key": "promotional_price", "value": "0.0" // Preço promocional da variação } ] } ], "variation_attributes": [ // Objeto responsável pela inclusão do atributo diferenciador "Atributo_diferenciador_1", "Atributo_diferenciador_2" ] } } ``` {% hint style="warning" %} Há um **limite** de **100 variações** que podem ser inclusas na estrutura de um produto, sendo necessário respeitar tal limitação para não haverem reprovas ao encaminhar o SKU variável para a API. {% endhint %} #### **Example request:** Veja abaixo o JSON de criação de um produto com variações, sendo o SKU P2022 o ID do produto "pai" e os SKUs F2023 e F2024 os IDs das variações: ``` curl --location --request POST 'https: //api.skyhub.com.br/products' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "product": { "sku": "P2022", "name": "Identificador de cédula falsa", "brand": "1739052110001030", // id de uma marca "categoryId": "24" // id referente a categoria de Identificador de cédula falsa "description": "[A descrição deve trazer detalhes do produto, com a finalidade de atrair o consumidor final] Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.", "status": "enabled", "price": 00.00, "promotional_price": 00.00, "cost": 0.0, "weight": 0.100, "height": 20, "width": 30, "length": 20, "brand": "Skyhub", "nbm": "98769898", "images": [ ""https: //a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "key": "Especicações do Produto PAI", "value": "Especificações do Produto PAI" }, { // Atributo de categoria - preenchimento livre "id": "id do atributo", "value": "Texto livre" }, { // Atributo de categoria - valores pré-determinados "id": "id do atributo", "idValue": "id da opção selecionável" } ], "variations": [ { "sku": "F2023", "price": 00.00, // Alteração ainda não está em vigor "promotional_price": 00.00, // Alteração ainda não está em vigor "qty": 10, "ean": "9876543210987", "images": [ ""https: //a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "key": "Cor", "value": "Branca" }, { "key": "Tamanho", "value": "P" }, { "key": "price", "value": "50.00" }, { "key": "promotional_price", "value": "40.00" }, { "id": "29229", // id referente a voltagem "idValue": "49105" // id referente ao valor 220 V } ] }, { "sku": "F2024", "price": 00.00, // Alteração ainda não está em vigor "promotional_price": 00.00, // Alteração ainda não está em vigor "qty": 10, "ean": "9876543210985", "images": [ ""https: //a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "key": "Cor", "value": "Branca" }, { "key": "Tamanho", "value": "M" }, { "key": "price", "value": "50.00" }, { "key": "promotional_price", "value": "40.00" }, { "id": "29229", // id referente a voltagem "idValue": "49106" // id referente ao valor 220 V } ] } ], "variation_attributes": [ "Cor", "Tamanho" ] } }' ``` # Copy of Produto Variável O produto variável é aquele onde há um agrupamento de dois ou mais SKUs tendo um atributo diferenciador para distingui-los. Nesta seção temos a estrutura para a criação desse tipo de produto {% hint style="danger" %} **Não estão ainda em produção alterações a respeito de Categorização, Marcas e atributos de categorias.** {% endhint %} Produto variável é aquele em que um ou mais SKUs são agrupados; estes SKUs serão diferenciados através de atributos específicos, como tamanho ou cor, por exemplo. Atributos como cor, tamanho e voltagem podem ser definidos tanto a nível de produto quanto a nível de SKU (variações). Será necessário consultar a lista de atributos da categoria e identificar se a categoria aceita esses atributos, porém detalhamos mais abaixo. Mesmo para produtos variáveis é necessário haver atributos e informações que fortaleçam a identidade do item, como um título claro e características bem definidas em sua ficha técnica. Acompanhe o exemplo abaixo: Quando tratamos uma camiseta é necessário fornecer uma breve descrição de suas características dentro do título, a fim de chamar a atenção de um potencial cliente (por exemplo, Título: Camiseta Branca Lisa). Além disso, também faz-se necessário incluir atributos de ficha técnica, como material, fabricante, marca, dentre outros para enriquecer o cadastro do item quando anunciado. Esses atributos de ficha técnica favorecem a localização do produto na realização de filtros nos sites de e-commerce e o título destaca a escolha do cliente final ao realizar as buscas. Mas não é só isso, existem vários outros requisitos necessários para a integração com o marketplace, como o correto preenchimento do peso, dimensões, status, indexação de imagens, além da inclusão em sua correta estrutura mercadológica. {% hint style="info" %} A seção [Integração: Produto](/produtos/integracao-produtos#pre-requisitos) desta documentação é capaz de fornecer maiores detalhes sobre os pré-requisitos necessários para a integração de produtos com o marketplace {% endhint %} A seguir confira a estrutura esperada para a criação de um produto variável via API. ## Estrutura do JSON {% hint style="danger" %} **A estrutura básica para a criação de um produto variável contém campos que devem ser preenchidos com os ****formatos de dados determinados pela API****.** A seguir são apresentados os campos que constituem a estrutura de um produto variável e o formato a ser utilizado para inclusão dos dados. A não utilização dos formatos corretos para preenchimento dos dados pode acarretar em reprova proveniente do marketplace, impossibilitando a publicação da oferta. {% endhint %} {% hint style="info" %} **Dentro de "specifications", somente ****atributos de categoria****.** A partir de Março/2025, no array specifications deverá constar somente atributos de categoria. Mais abaixo explicamos o funcionamento destes atributos. {% endhint %} ``` { "product": { // Object "sku": "CodigoSKU_agrupador", // String "name": "Título", // String "brand": "CodigoMarca", // String "categoryId": "IdCategoria", // String "description": "Descrição", // String "status": "enabled", // String "price": 0.0, // Double "promotional_price": 0.0, // Double "cost": 0, // Double "weight": 0, // Double "height": 0, // Double "width": 0, // Double "length": 0, // Double "brand": "Marca", // String "nbm": "NCM (Nomenclatura Comum do Mercosul)", // String "images": [ // Array "URL da imagem" // String ], "specifications": [ // Array { // Object "key": "Atributo", // String "value": "Valor do atributo" // String }, { // Object "id": "Valor", // String "idValue" // String }, { // Object "id": "valor", // String "value": "valor" // String } ], "variations": [ // Array { // Object } ], "variation_attributes":[ // Array "atributo1", "atributo2", "atributo3" ] } } ``` ### Como declarar a categoria Será necessário realizar a consulta na lista de categorias para obter o **categoryId** e preencher no body do JSON. Para isso, seguir a documentação [**Consultar lista de categorias**](/produtos/categorizacao/consultar-categorias). Haverá os IDs disponíveis **'id'**, 'id1', 'id2' e 'id3'. Os IDs enumerados representam os níveis de categorias, enquanto o ID em verde representa toda a estrutura. Qualquer um desses IDs disponíveis deve constar em **categoryId**, vai depender do nível em que o lojista deseja catalogar seu produto. ### Como declarar a marca Será necessário realizar a consulta das marcas para obter o **brand** e preencher no body do JSON. \ \ Para isso, seguir a documentação [**Consultar Marcas**](/produtos/consultar-marcas). ### Como declarar atributos de categoria Os atributos de categoria devem ser declarados dentro de '**specifications**', porém com distinção em relação aos demais atributos.\ \ Como visto em [**Consultar atributos por categoria**](/produtos/categorizacao/consultar-atributos-por-categoria), há diferenças entre os tipos de atributos:
* Se for um atributo de livre preenchimento:\ \ Em '**specifications**' deve ser declarado ***id*** (id do atributo) e ***value*** (texto livre e não tem um dado estruturado, ou seja, não há idValue para ser enviado).\
* Se for um atributo com valores já pré-determinados:\ \ Em '**specifications**' deve ser declarado ***id*** (id do atributo) e ***idValue*** (id do valor de uma das opções presente no array *valueData*). #### Atenção ao campo "toSKU" A consulta de atributos por categoria retornará um campo chamado "**toSKU**", onde este define se o atributo deve ser enviado no produto ***PAI*** ou na sua ***variação***.\ \ Caso o "**toSKU**" seja false, o atributo deve ser enviado nas especificações do produto pai. Caso true, deverá ser enviado nas especificações do produto filho. Porém, se por acaso o "**toSKU**" seja true e o produto se tratar de um produto simples, o atributo deverá ser enviado no "**specifications"** do produto normalmente. {% hint style="info" %} Atributos com o '**required**' igual a *True* ao consultar os atributos da categoria, deverão obrigatoriamente constar no JSON do produto. Os demais, são opcionais o envio. {% endhint %} {% hint style="warning" %} Atributos de categoria são diferentes de atributos de produtos. Atributos de categoria possuem o padrão "id" e "idValue"/"value", já os atributos de produto possuem o padrão "key" e "value". {% endhint %} ## **POST - Cadastrando um produto variável** Para realizar o cadastro de um produto variável via API deverá ser utilizado o método POST para o seguinte endpoint: ``` https://api.skyhub.com.br/products ``` **Request headers:** | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | X-Api-Key | token\_de\_integracao de sua conta SkyHub | | X-Accountmanager-key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | A diferença para o JSON do produto simples é que no cadastro da variação é informado o array variations com as informações dos SKUs agrupados, seus atributos diferenciadores e outras especificações. Dentro de 'specifications' deverá ser declarado o atributo de variação preenchido, de acordo com consulta prévia no endpoint de atributos de categoria. {% hint style="danger" %} Todo produto variável deve contar com o *array **variation\_attributes***, onde deverão ser informados os atributos responsáveis pela diferenciação das variações. Por exemplo, ao cadastrar uma camiseta e preencher para os SKUs filhos - aqueles vinculados a um SKU agrupador/pai - o atributo "Tamanho" para diferenciar uma variação da outra, é esperado que o mesmo atributo ("Tamanho") seja informado no *array **variation\_attributes***. {% endhint %} #### Request body: ``` { "product": { "sku": "CodigoSKU_agrupador", "name": "Título", "brand": "Código da Marca", // Obtido realizando o GET em Marcas "categoryId": "Id da Categoria", // Obtido realizando o GET na lista de Categorias "description": "Descrição detalhada do produto criado", "status": "enabled", // Status (ativo/enabled ou inativo/disabled) "price": 0.0, // Preço "promotional_price": 0.0, // Preço promocional "cost": 0, // Custo do produto para o seller "weight": 0, // Peso "height": 0, // Altura "width": 0, // Largura "length": 0, // Comprimento "brand": "Marca", "nbm": "NBM/NCM", "images": [ "" ], "specifications": [ // Objeto responsável pela inclusão de atributos { "key": "Atributo", "value": "Valor do atributo" }, { // Atributo de categoria - preenchimento livre "id": "id do atributo", "value": "Texto livre" }, { // Atributo de categoria - valores pré-determinados "id": "id do atributo", "idValue": "id da opção selecionável" } ], "variations": [ { "sku": "CodigoSKU_variacao", "qty": 0, // Estoque "ean": "EAN (European Article Number ou Numeração Europeia de Artigos, o código de barras do item)", "images": [ "https:// URL da imagem" // Imagem da variação ], "specifications": [ // Objeto responsável pela inclusão de atributos { "key": "Atributo", "value": "Valor do atributo" }, { "key": "Atributo", "value": "Valor do atributo" }, { "key": "price", "value": "0.0" // Preço da variação }, { "key": "promotional_price", "value": "0.0" // Preço promocional da variação } ] } ], "variation_attributes": [ // Objeto responsável pela inclusão do atributo diferenciador "Atributo_diferenciador_1", "Atributo_diferenciador_2" ] } } ``` {% hint style="warning" %} Há um **limite** de **100 variações** que podem ser inclusas na estrutura de um produto, sendo necessário respeitar tal limitação para não haverem reprovas ao encaminhar o SKU variável para a API. {% endhint %} #### **Example request:** Veja abaixo o JSON de criação de um produto com variações, sendo o SKU P2022 o ID do produto "pai" e os SKUs F2023 e F2024 os IDs das variações: ``` curl --location --request POST 'https: //api.skyhub.com.br/products' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "product": { "sku": "P2022", "name": "Identificador de cédula falsa", "brand": "1739052110001030", // id de uma marca "categoryId": "24" // id referente a categoria de Identificador de cédula falsa "description": "[A descrição deve trazer detalhes do produto, com a finalidade de atrair o consumidor final] Camiseta polo masculina, disponível na cor branca e em 2 tamanhos diferentes.", "status": "enabled", "price": 00.00, "promotional_price": 00.00, "cost": 0.0, "weight": 0.100, "height": 20, "width": 30, "length": 20, "brand": "Skyhub", "nbm": "98769898", "images": [ ""https: //a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "key": "Especicações do Produto PAI", "value": "Especificações do Produto PAI" }, { // Atributo de categoria - preenchimento livre "id": "id do atributo", "value": "Texto livre" }, { // Atributo de categoria - valores pré-determinados "id": "id do atributo", "idValue": "id da opção selecionável" } ], "variations": [ { "sku": "F2023", "price": 00.00, // Alteração ainda não está em vigor "promotional_price": 00.00, // Alteração ainda não está em vigor "qty": 10, "ean": "9876543210987", "images": [ ""https: //a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "key": "Cor", "value": "Branca" }, { "key": "Tamanho", "value": "P" }, { "key": "price", "value": "50.00" }, { "key": "promotional_price", "value": "40.00" }, { "id": "29229", // id referente a voltagem "idValue": "49105" // id referente ao valor 220 V } ] }, { "sku": "F2024", "price": 00.00, // Alteração ainda não está em vigor "promotional_price": 00.00, // Alteração ainda não está em vigor "qty": 10, "ean": "9876543210985", "images": [ ""https: //a-static.mlcdn.com.br/800x560/camiseta-masculina-gola-polo-branca-piquet-com-elastano-basica-lisa-ixoria/gdmstore/11100354223/39945a2c0162febe1ae663fb7019d5ca.jpeg" ], "specifications": [ { "key": "Cor", "value": "Branca" }, { "key": "Tamanho", "value": "M" }, { "key": "price", "value": "50.00" }, { "key": "promotional_price", "value": "40.00" }, { "id": "29229", // id referente a voltagem "idValue": "49106" // id referente ao valor 220 V } ] } ], "variation_attributes": [ "Cor", "Tamanho" ] } }' ``` # Atualização de Produto Nesta guia mostraremos a estrutura e exemplos de requisições para atualização de produtos simples e variáveis Acompanhe o detalhamento de cada tipo navegando pelas guias abaixo: {% content-ref url="/pages/-MG4KPBq5uok2O\_k4FyI" %} [Produto Simples](/produtos/atualizacao-produto/produto-simples) {% endcontent-ref %} {% content-ref url="/pages/yz0sKB22NqyFGFBEnMsf" %} [Produto Variável](/produtos/atualizacao-produto/produto-variavel-1) {% endcontent-ref %} # Produto Simples Existem algumas diferenças na atualização de produtos simples e variáveis, nesta página mostraremos como alterar produtos simples ## PUT - Atualizando um produto simples A atualização de informações é realizada através do método PUT, mantendo o mesmo header e conservando o atributo que deverá ser alterado. Para realizar a atualização, é preciso utilizar o método PUT no mesmo endpoint de produtos acrescido do código SKU do produto simples conforme abaixo: ``` https://api.skyhub.com.br/products/{SKU} ``` #### **Request headers:** | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | X-Api-Key | token\_de\_integracao de sua conta SkyHub | | X-Accountmanager-key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | #### **Request body:** ``` { "product": { "Atributo": "Novo Valor" } } ``` {% hint style="danger" %} O objeto ***product*** deve ser preservado na request, caso contrário um erro será retornado na tentativa de atualizar o produto. {% endhint %} #### **Example request:** No exemplo abaixo, estamos alterando somente o nome do produto, então todos os demais atributos foram retirados da requisição, para facilitar o entendimento. ``` curl --location --request PUT 'https://api.skyhub.com.br/products/{SKU}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "product": { "name": "Nome Atualizado do Produto" } }' ``` #### Response esperado: {% hint style="success" %} 204 \[Success] - No content {% endhint %} {% hint style="danger" %} Para a atualização de **imagens** é necessário atentar-se a **URL** indexada: Para realizar alterações nas imagens de um produto é preciso encaminhar uma **nova URL**, ou seja, **não é possível reutilizar a URL previamente enviada**; somente com URLs diferentes a nova imagem será refletida pelo marketplace. \[Ver Comunicado: [Envio de Imagens para o Marketplace](/comunicados/comunicados-2021/envio-de-imagens-para-o-mktp-b2w)] {% endhint %} ### Como atualizar preço e estoque Assim como quaisquer atualizações em produtos, para alterações nos campos de preço (*price* e *promotional\_price*) e estoque deve ser utilizado o método **PUT** no */products/{SKU}*. A seguir temos exemplos de requisições para as atualizações de preço e estoque para produtos simples: #### Atualização de preço: ``` curl --location -g --request PUT 'https://api.skyhub.com.br/products/{SKU}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "product": { "price": 100.00, "promotional_price": 80.00 } }' ``` #### Atualização de estoque: ``` curl --location -g --request PUT 'https://api.skyhub.com.br/products/{SKU}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "product": { "qty": 1000 } }' ``` #### Atualização de preço e estoque: ``` curl --location -g --request PUT 'https://api.skyhub.com.br/products/{SKU}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "product": { "qty": 1000, "price": 100.00, "promotional_price": 80.00 } }' ``` {% hint style="info" %} Nas atualizações de preço e estoque **não deve ser enviada a estrutura completa do produto**, ou seja, é preciso enviar apenas os respectivos campos (***qty***, ***price*** e ***promotional\_price***). {% endhint %} ### Como atualizar o atributo crossdocking O *crossdocking* é o atributo responsável pela definição do prazo do item, isto é, ele representa o tempo que o *seller* leva para fabricar o produto após o pagamento do pedido ter sido aprovado. O atributo *crossdocking* deve vir na raiz do produto, assim como preço, estoque e outros. {% hint style="info" %} Apesar de passar número, o atributo é uma *string*. {% endhint %} A seguir temos um exemplo de requisição para atualização do atributo *crossdocking*: ``` curl --location --request PUT 'https://api.skyhub.com.br/products/{SKU}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "product": { "crossdocking": "3" } }' ``` ### **Criação de variação em produtos simples** Quando desejar tornar um Produto Simples em Produto Variável, é necessário enviar no body a estrutura de um Produto Variável, com o Array '**variations**' especificando as variações a serem criadas e também o '**variation\_attributes**' especificando os atributos variantes. {% hint style="danger" %} **IMPORTANTE:** Só indicamos a criação de variações em produtos simples enquanto o SKU não tiver conectado ao Marketplace. **E se o produto já estiver conectado?** Se um produto simples já estiver conectado e uma nova variação é enviada no produto, automaticamente será excluída a oferta do produto simples no Marketplace. O produto só será criado novamente no Marketplace desta vez como variável, quando o parceiro realizar uma nova conexão do produto. {% endhint %} ``` curl --location -g --request PUT 'https://api.skyhub.com.br/products/{SKU}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "product": { "sku": "foo", // String "name": "foo", // String "description": "foo", // String "status": "enabled", // String "price": 0.0, // Integer "promotional_price": 0.0, // Integer "crossdocking": '0" // String "cost": 0, // Integer "brand": "foo", // String "weight": 0, // Integer "height": 0, // Integer "width": 0, // Integer "length": 0, // Integer "variations": [ //Exemplo de Variação { "sku": "foo-1", "qty": 0, "crossdocking": '0" // String "status": "enabled" // String "ean": "foo", // String "specifications": [ { // Atributo de categoria - preenchimento livre "id": "id do atributo", "value": "Texto livre" }, { // Atributo de categoria - valores pré-determinados "id": "id do atributo", "idValue": "id da opção selecionável" } ] } ] } }' ``` # Copy of Produto Variável Nesta página mostraremos como realizar atualizações em variações previamente criadas ## PUT - Atualizando a variação de um produto Será necessário o método PUT com os mesmos headers para realizar a atualização da variação, porém o endpoint utilizado é o */variations* seguido do SKU da variação conforme abaixo: ``` https://api.skyhub.com.br/variations/{SKU_VARIACAO} ``` #### **Request headers:** | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | x-Api-Key | token\_de\_integracao de sua conta SkyHub | | x-accountmanager-key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | #### **Request body:** ``` { "variation": { "price": 158, "promotional_price": 126.4, "images": [ "https://foo" ], "ean": "0000000000000", "qty": "10", "specifications": [ { "value": "Atributo", "key": "Valor" } ] } } ``` {% hint style="danger" %} O objeto ***product*** deve ser substituído pelo ***variation*** e não pode ser retirado da requisição, caso contrário um erro será retornado na tentativa de atualizar a variação. {% endhint %} #### **Example request:** ``` curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "variation": { "price": 158, "promotional_price": 126.4 "images": [ "https://images-americanas.b2w.io/produtos/2638788562/imagens/regata-basic-feminina-canelada-branca/2638788562_1_xlarge.jpg" ], "ean": "0123456789012", "qty": "5", "specifications": [ { "value": "crossdocking", "key": "3" } ] } }' ``` #### **Response esperado:** {% hint style="success" %} 204 \[Success] - No content {% endhint %} {% hint style="danger" %} Para a atualização de **imagens** é necessário atentar-se a **URL** indexada: Para realizar alterações nas imagens de um produto é preciso encaminhar uma **nova URL**, ou seja, **não é possível reutilizar a URL previamente enviada**; somente com URLs diferentes a nova imagem será refletida pelo marketplace. \[Ver Comunicado: [Envio de Imagens para o Marketplace](/comunicados/comunicados-2021/envio-de-imagens-para-o-mktp-b2w)] {% endhint %} ### Como atualizar preço e estoque Assim como quaisquer atualizações em variações, para alterações nos campos de preço (*price* e *promotional\_price*) e estoque deve ser utilizado o método **PUT** no */variations/{SKU\_VARIACAO}*. {% hint style="info" %} Deve ser realizado um PUT por variação. {% endhint %} A seguir temos exemplos de requisições para as atualizações de preço e estoque para variações: #### Atualização de preço por variação: ``` curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "variation": { "price": 158, "promotional_price": 126.4 "specifications": [ { "key": "price", "value": "50.00" }, { "key": "promotional_price", "value": "45.00" } ] } }' ``` #### Atualização de estoque por variação: ``` curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "variation": { "qty": 1 } }' ``` #### Atualização de preço e estoque: ``` curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "variation": { "qty": 5, "price": 158, "promotional_price": 126.4 "specifications": [ { "key": "price", "value": "185.90" }, { "key": "promotional_price", "value": "180.90" } ] } }' ``` {% hint style="info" %} Caso deseje realizar alterações no SKU agrupador é possível seguir as orientações da guia Atualização de Produto > [Produto Simples](/produtos/atualizacao-produto/produto-simples#put-atualizando-um-produto-simples). {% endhint %} # Produto Variável Nesta página mostraremos como realizar atualizações em variações previamente criadas ## PUT - Atualizando a variação de um produto Será necessário o método PUT com os mesmos headers para realizar a atualização da variação, porém o endpoint utilizado é o */variations* seguido do SKU da variação conforme abaixo: ``` https://api.skyhub.com.br/variations/{SKU_VARIACAO} ``` #### **Request headers:** | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | x-Api-Key | token\_de\_integracao de sua conta SkyHub | | x-accountmanager-key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | #### **Request body:** ``` { "variation": { "price": 0.0, // Double "promotional_price": 0.0, // Double "status": "enabled", // String "images": [ "https://foo" ], "ean": "0000000000000", // String "qty": 10, // Integer "crossdocking": "3" // String "specifications": [ { // Atributo de categoria - preenchimento livre "id": "id do atributo", // String "value": "Texto livre" // String }, { // Atributo de categoria - valores pré-determinados "id": "id do atributo", // String "idValue": "id da opção selecionável" // String } ] } } ``` {% hint style="danger" %} O objeto ***product*** deve ser substituído pelo ***variation*** e não pode ser retirado da requisição, caso contrário um erro será retornado na tentativa de atualizar a variação. {% endhint %} #### **Example request:** ``` curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "variation": { "price": 158, "promotional_price": 126.4, "status": "enabled", "images": [ "https://images-americanas.b2w.io/produtos/2638788562/imagens/regata-basic-feminina-canelada-branca/2638788562_1_xlarge.jpg" ], "ean": "0123456789012", "qty": "5", "crossdocking": "3", "weight": 0.100, "height": 20, "width": 30, "length": 20, "specifications": [ { "id": "29229", "idValue": "49106" } ] } }' ``` #### **Response esperado:** {% hint style="success" %} 204 \[Success] - No content {% endhint %} {% hint style="danger" %} Para a atualização de **imagens** é necessário atentar-se a **URL** indexada: Para realizar alterações nas imagens de um produto é preciso encaminhar uma **nova URL**, ou seja, **não é possível reutilizar a URL previamente enviada**; somente com URLs diferentes a nova imagem será refletida pelo marketplace. \[Ver Comunicado: [Envio de Imagens para o Marketplace](/comunicados/comunicados-2021/envio-de-imagens-para-o-mktp-b2w)] {% endhint %} ### Como atualizar preço e estoque Assim como quaisquer atualizações em variações, para alterações nos campos de preço (*price* e *promotional\_price*) e estoque deve ser utilizado o método **PUT** no */variations/{SKU\_VARIACAO}*. {% hint style="info" %} Deve ser realizado um PUT por variação. {% endhint %} A seguir temos exemplos de requisições para as atualizações de preço e estoque para variações: #### Atualização de preço por variação: ``` curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "variation": { "price": 158, "promotional_price": 126.4 } }' ``` #### Atualização de estoque por variação: ``` curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "variation": { "qty": 1 } }' ``` #### Atualização de preço, estoque e crossdocking: ``` curl --location -g --request PUT 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \ --header 'X-User-Email: email_de_usuario' \ --header 'x-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'x-accountmanager-key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "variation": { "qty": 5, "price": 158, "promotional_price": 126.4, "crossdocking": "3" } }' ``` {% hint style="info" %} Caso deseje realizar alterações no SKU agrupador é possível seguir as orientações da guia Atualização de Produto > [Produto Simples](/produtos/atualizacao-produto/produto-simples#put-atualizando-um-produto-simples). {% endhint %} # Consulta de Produto Nesta guia mostraremos como realizar a consulta da estrutura de produtos simples e variáveis. Além disso, será possível validar como realizar a pesquisa por variação Acompanhe o detalhamento de cada tipo navegando pelas guias abaixo: {% content-ref url="/pages/-MGQ0NOaaITTcCOceErG" %} [Produto Simples e Variável](/produtos/consulta-produto/produto-simples) {% endcontent-ref %} {% content-ref url="/pages/-MGQ0OEevgG03KeUfKjK" %} [Variação de Produto](/produtos/consulta-produto/produto-variavel) {% endcontent-ref %} # Produto Simples e Variável Mostraremos nesta página como consultar produtos simples e variáveis via API ## GET - Consultando um produto {% hint style="info" %} **Desde Março/2025, o array associations foi retirado do JSON do produto.** {% endhint %} Para realizar uma consulta na API devemos utilizar o método GET, preenchendo os devidos headers no endpoint abaixo: ``` https://api.skyhub.com.br/products/{SKU} ``` #### **Request headers:** | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | X-Api-Key | token\_de\_integracao de sua conta SkyHub | | X-Accountmanager-Key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | #### **Example request:** ``` curl --location -g --request GET 'https://api.skyhub.com.br/products/{SKU}' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' ``` #### **Response esperado:** {% hint style="success" %} 200 \[Success] - OK: Haverá um response body com a estrutura do SKU consultado: {% endhint %} ``` { "sku": "SKU do produto", "name": "Título", "description": "Descrição detalhada", "status": "disabled", "removed": false, "qty": 5, "price": 100.0, "promotional_price": 80.0, "cost": 49.0, "weight": 3.0, "height": 1.0, "width": 1.0, "length": 1.0, "condition_type": null, "brand": "Marca", "ean": "1234567890123", "nbm": "11223344", "categories": [ { "code": "01", "name": "SKYHUB" } ], "images": [ "https://images-americanas.b2w.io/produtos/2638788562/imagens/regata-basic-feminina-canelada-branca/2638788562_1_xlarge.jpg" ], "specifications": [ { "key": "Tamanho", "value": "Único" }, { "key": "Crossdocking", "value": "3" } ], } ``` ### Consultando todos os produtos Além da consulta individual, também é possível listar todos os produtos criados na conta. Para isto, basta utilizar o GET no endpoint */products* sem informar um SKU, conforme abaixo: ``` https://api.skyhub.com.br/products ``` #### **Example request:** ``` curl --location --request GET 'https://api.skyhub.com.br/products' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' ``` #### **Response esperado:** {% hint style="success" %} 200 \[Success] - OK: O retorno é semelhante ao da pesquisa anterior, porém serão visualizados todos os SKUs não conectados da conta e abaixo temos um exemplo resumido do retorno esperado: {% endhint %} ``` { "products": [ { "sku": "SKU_01", "name": "Título 01", "description": "Descrição 01", "status": "disabled", (...) }, { "sku": "SKU_02", "name": "Título 02", "description": "Descrição 02", "status": "enabled", (...) }, { "sku": "SKU_03", "name": "Título 03", "description": "Descrição 03", "status": "enabled", (...) } ], "total": 101, "next": "https://api.skyhub.com.br/products?cursor=cXVlcnlUa..........wOw==" } ``` #### Filtros da consulta Por padrão, o GET em /products retornará todos os produtos não conectados ao Marketplace.\ \ Para retornar os produtos conectados ao Marketplace, devemos filtrar com o parâmetro type **"/products?filters\[type]=link"**. Produtos conectados são aqueles que o lojista decide por habilitar a vender. Quando conectado, o produto fica disponível (caso estoque positivo), já desconectado o lojista desabilita o produto para a venda. ### Como paginar a consulta de produtos A listagem de produtos retornará 25 itens por página. Caso a conta tenha mais que 25 produtos, será necessário fazer a paginação através do **cursor**, que deve ser inserido no endpoint em forma de query string. #### Como montar a query? Ao realizar o GET no */products*, ao final da consulta será apresentado o campo **next** que trará como parâmetro o **cursor**, como visualizado a seguir: ``` "total": 101, "next": "https://api.skyhub.com.br/products?cursor=cXVlcnlUa..........wOw==" ``` Ao localizar o **cursor**, basta inseri-lo no endpoint para que seja possível alcançar a próxima página. Abaixo temos um exemplo de utilização da paginação: ``` curl --location -g --request GET 'https://api.skyhub.com.br/products?cursor=cXVlcnlUa..........wOw==" }' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' ``` A cada página o cursor será alterado até que chegue na última, quando a requisição retornará sucesso, porém trará um *array* vazio: ``` { "products": [], "total": 101, "next": "https://api.skyhub.com.br/products?cursor=cXVlcnlUa..........swOw==" } ``` {% content-ref url="/pages/-MG4KvGq5WV\_\_nP8pZK3" %} [Filtros de Consultas](/produtos/outros-recursos-de-produtos/filtros-produtos) {% endcontent-ref %} # Variação de Produto Nesta seção explicaremos como realizar a consulta de uma variação através da API ## GET - Consultando a variação de um produto {% hint style="info" %} **Desde Março/2025, o array associations foi retirado do JSON do produto.** {% endhint %} É possível utilizar o método GET e os mesmos headers das ações anteriores para consultar diretamente uma variação previamente criada. Para tal consulta, é necessário utilizar o endpoint: ``` https://api.skyhub.com.br/variations/{SKU_VARIACAO} ``` #### **Request headers:** | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | X-Api-Key | token\_de\_integracao de sua conta SkyHub | | X-Accountmanager-Key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | #### **Example request:** ``` curl --location -g --request GET 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' ``` #### **Response esperado:** {% hint style="success" %} 200 \[Success] - OK: Será retornada a estrutura da variação referenciada no endpoint: {% endhint %} ``` { "variation": { "sku": "SKU da Variação", "qty": 10, "price": 199.0, "ean": "9876543210987", "weight": 0.100, "height": 20, "width": 30, "length": 20, "images": [ "https://foo" ], "status": enabled, "specifications": [ { "key": "price", "value": "199.0" }, { "key": "promotional_price", "value": "149.0" } ] }, "product": { "sku": "SKU Agrupador" } } ``` Note que ao final do resultado é exibido o SKU do ***product***, que é o SKU pai/agrupador da variação consultada. Este SKU só poderá ser consultado no endpoint */products* conforme descrito na seção anterior ([Consulta de Produto > Produto Simples e Variável](/produtos/consulta-produto/produto-simples)). ### # Exclusão de Produto Nesta seção será fornecida a orientação para exclusão de itens Uma vez cadastrados, é possível realizar via API a exclusão de produtos. Importante se atentar que antes da exclusão de um item já conectado ao marketplace a sua venda deve ser pausada/inativada, processo que se dá através da [desconexão](/rehub/rehub-acoes-de-produto#desconectar-produto-no-marketplace). Pelas guias abaixo é possível obter informações sobre a exclusão de produtos e variações: {% content-ref url="/pages/-MG4Kk5o5FZzSUEItuz0" %} [Produto Simples e Variável](/produtos/excluir-produto/produto-simples) {% endcontent-ref %} {% content-ref url="/pages/-MG4Kn15dUpIRW3oISKj" %} [Variação de Produto](/produtos/excluir-produto/produto-variavel) {% endcontent-ref %} # Produto Simples e Variável Neste guia iremos entender como excluir um produto simples ou variável ## DELETE - Excluindo um produto Ao se tratar de um item em venda, a exclusão deve ser realizada apenas após a inativação do anúncio que se dá através do processo de [desconexão](/rehub/rehub-acoes-de-produto#desconectar-produto-no-marketplace). Outro ponto a ser validado antes da exclusão é se existem pedidos pendentes para o item; caso haja um pedido pendente no marketplace e o SKU seja removido, a entrega não será integrada a API e não poderá ser consumida pela plataforma/ERP. Para seguir com a exclusão é preciso realizar um DELETE na seguinte URL, referenciando o SKU a ser excluído: ``` https://api.skyhub.com.br/products/{SKU} ``` {% hint style="info" %} Para a exclusão será informado o SKU. Em caso de produtos que possuem variações, o código a ser utilizado na URI */products/{SKU}* é o do SKU pai/agrupador, consequentemente, serão excluídas também as variações dependentes daquele agrupador. {% endhint %} #### **Request headers:** | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | X-Api-Key | token\_de\_integracao de sua conta SkyHub | | X-Accountmanager-Key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | #### **Example request:** ``` curl --location -g --request DELETE 'https://api.skyhub.com.br/products/{SKU}' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' ``` {% hint style="success" %} 204 \[Success] - No content {% endhint %} {% hint style="warning" %} **Não é possível excluir itens via batch.** {% endhint %} # Variação de Produto Neste guia iremos entender como excluir a variação de um produto ## DELETE - Excluindo uma variação Ao optar pela exclusão de uma variação de item publicado no marketplace é necessário verificar se não existem pedidos pendentes de integração com a API; caso haja um pedido pendente no marketplace e o SKU seja removido, a entrega não será integrada a API e não poderá ser consumida pela plataforma/ERP. Para seguir com a exclusão é preciso realizar um DELETE na seguinte URL, referenciando o SKU da variação a ser excluída: ``` https://api.skyhub.com.br/variations/{SKU_VARIACAO} ``` #### **Request headers:** | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | X-Api-Key | token\_de\_integracao de sua conta SkyHub | | X-Accountmanager-Key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | #### **Example request:** ``` curl --location -g --request DELETE 'https://api.skyhub.com.br/variations/{SKU_VARIACAO}' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' ``` #### **Response esperado:** {% hint style="success" %} 204 \[Success] - No content {% endhint %} {% hint style="warning" %} **Não é possível a exclusão via batch.** {% endhint %} # Outros Recursos de Produtos Nesta seção são apresentados outros recursos pertinentes a API de produtos, como filtros a serem aplicados, criação de atributos e consulta de URLs Navegue nas opções a seguir para consultar os recursos da API de produtos: {% content-ref url="/pages/-MG4KvGq5WV\_\_nP8pZK3" %} [Filtros de Consultas](/produtos/outros-recursos-de-produtos/filtros-produtos) {% endcontent-ref %} {% content-ref url="/pages/-LUBfH9eC31xZ2XKHkIS" %} [Endpoint Atributos](/produtos/outros-recursos-de-produtos/endpoint-atributos) {% endcontent-ref %} {% content-ref url="/pages/-MG4L0\_8UE4IG4ydU67Q" %} [Consulta URL](/produtos/outros-recursos-de-produtos/consulta-url) {% endcontent-ref %} # Filtros de Consultas A API oferece a possibilidade de informar a query para filtrar a listagem de produtos Para aplicar filtros por produtos com queries específicas é necessário utilizar a URL base disponibilizada a seguir: ``` http://api.skyhub.com.br/products ``` #### **Request headers:** | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | X-Api-Key | token\_de\_integracao de sua conta SkyHub | | X-Accountmanager-Key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | Através da URL e dos headers informados é possível realizar os filtros por: * Status; * Nome; * Quantidade em estoque; * Campos específicos no retorno. ### Como filtrar por status É possível realizar a listagem de produtos através de seus status, onde deverá ser informada a query ***?filters\[status]=*** no endpoint */products*, referenciando o status a ser consultado, conforme exemplo a seguir: ``` https://api.skyhub.com.br/products?filters[status]={enabled ou disabled} ``` Ao informar o parâmetro ***?filters\[status]=enabled*** serão retornados todos os produtos **ativos** (enabled); caso selecione o parâmetro ***?filters\[status]=disabled*** serão retornados os produtos **inativos** (disabled). #### **Example request:** Segue um exemplo de requisição para listagem de produtos com status disabled: ``` curl --location -g --request GET 'https://api.skyhub.com.br/products?filters[status]=disabled' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' ``` #### **Response esperado:** {% hint style="success" %} 200 \[Success] - OK: No retorno para a consulta acima serão visualizados todos os SKUs da conta que possuírem o *status* disabled como vemos a seguir: {% endhint %} ``` { "products": [ { "sku": "SKU_01", "name": "Título 01", "description": "Descrição 01", "status": "disabled", (...) } ], "total": 1, "next": "https://api.skyhub.com.br/products?cursor=cXVlcnlUa..........wOw==" } ``` ### Como filtrar por nome Para realizar a listagem de produtos através de um nome específico deverá ser informada a query ***?filters\[name]=*** no endpoint */products*, referenciando o nome a ser consultado, conforme exemplo a seguir: ``` https://api.skyhub.com.br/products?filters[name]={nome_do_item} ``` #### **Example request:** Segue um exemplo de requisição para listagem de SKUs com o termo "produto" no título: ``` curl --location -g --request GET 'https://api.skyhub.com.br/products?filters[name]=produto' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' ``` #### **Response esperado:** {% hint style="success" %} 200 \[Success] - OK: No retorno para a consulta acima serão visualizados todos os SKUs da conta que possuírem no campo *name* a *string* "produto" como vemos a seguir: {% endhint %} ``` { "products": [ { "sku": "SKU_01", "name": "Produto teste", "description": "Descrição 01", "status": "enabled", (...) }, { "sku": "SKU_02", "name": "PRODUTO SIMPLES", "description": "Descrição 02", "status": "enabled", (...) }, { "sku": "SKU_03", "name": "PRODUTO SIMPLES ESPECIAL", "description": "Descrição 03", "status": "enabled", (...) } (...) ], "total": 43, "next": "https://api.skyhub.com.br/products?cursor=cXVlcnlUaGVu...........wOw==" } ``` ### Como filtrar por quantidade em estoque O filtro por quantidade (*qty*) permite a consulta de produtos com determinados estoques, sendo: #### Consulta de produtos com quantidade em estoque **maior ou igual** ao valor especificado Para realizar a listagem de produtos cujo estoque seja maior ou igual a um valor definido na busca deverá ser informada a query ***?filters\[qty\_from]=*** no endpoint */products*, referenciando a quantidade desejada, conforme exemplo a seguir: ``` https://api.skyhub.com.br/products?filters[qty_from]={qty} ``` #### **Example request:** Segue um exemplo de requisição para listagem de produtos com estoque maior ou igual a 50 unidades: ``` curl --location -g --request GET 'https://api.skyhub.com.br/products?filters[qty_from]=50' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' ``` #### **Response esperado:** {% hint style="success" %} 200 \[Success] - OK: No retorno para a consulta acima serão visualizados todos os SKUs da conta que possuírem o valor maior ou igual a 50 unidades no campo *qty*, como vemos a seguir: {% endhint %} ``` { "products": [ { "sku": "SKU_01", "name": "Título 01", "description": "Descrição 01", "status": "enabled", "qty": 10000, (...) }, { "sku": "SKU_02", "name": "Título 02", "description": "Descrição 02", "status": "enabled", "qty": 100, (...) }, { "sku": "SKU_03", "name": "Título 03", "description": "Descrição 03", "status": "enabled", "qty": 400, (...) } (...) ], "total": 15, "next": "https://api.skyhub.com.br/products?cursor=cXVlcnlUa............swOw==" ``` #### Consulta de produtos com quantidade em estoque **menor ou igual** ao valor especificado Para realizar a listagem de produtos cujo estoque seja menor ou igual a um valor definido na busca deverá ser informada a query ***?filters\[qty\_to]=*** no endpoint */products* referenciando a quantidade desejada, conforme exemplo a seguir: ``` https://api.skyhub.com.br/products?filters[qty_to]={qty} ``` #### **Example request:** Segue um exemplo de requisição para listagem de produtos com estoque menor ou igual a 50 unidades: ``` curl --location -g --request GET 'https://api.skyhub.com.br/products?filters[qty_to]=50' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' ``` #### **Response esperado:** {% hint style="success" %} 200 \[Success] - OK: No retorno para a consulta acima serão visualizados todos os SKUs da conta que possuírem o valor menor ou igual a 50 unidades para o campo *qty*, como vemos a seguir: {% endhint %} ``` { "products": [ { "sku": "SKU_01", "name": "Título 01", "description": "Descrição 01", "status": "disabled", "qty": 5, (...) }, { "sku": "SKU_02", "name": "Título 02", "description": "Descrição 03", "status": "enabled", "qty": 3, (...) }, { "sku": "SKU_03", "name": "Título 03", "description": "Descrição 03", "status": "enabled", "qty": 49, (...) } (...) ], "total": 86, "next": "https://api.skyhub.com.br/products?cursor=cXVlcnlUaG...........swOw==" } ``` {% hint style="info" %} É possível combinar os parâmetros ***filters\[qty\_from]*** e ***filters\[qty\_to]*** para listar produtos cujos estoques se encontram dentro de uma faixa específica, por exemplo: * Desejo consultar apenas os SKUs que possuem estoque entre 5 e 10 unidades: Para isso basta adicionar ao GET no endpoint */products* o filtro **?filters\[qty\_from]=5\&filters\[qty\_to]=10**; * Desejo consultar apenas os produtos que possuem 5 unidades em estoque: Para essa listagem basta incluir na pesquisa o **?filters\[qty\_from]=5\&filters\[qty\_to]=5**. {% endhint %} ### **Como consultar campos específicos** Na estrutura de um produto são definidos diversos campos, como SKU, imagens, EAN, entre outros. Através da API é possível restringir a consulta para que o retorno mostre apenas determinados atributos. Para isto, deverá ser informada a query ***?only\[]=*** no endpoint */products* referenciando o atributo que deseja visualizar, conforme descrito a seguir: ``` https://api.skyhub.com.br/products?only[]={atributo} ``` #### **Example request:** Segue um exemplo de requisição para listagem de todos os produtos, filtrando no retorno apenas os campos SKU, imagem e custo: ``` curl --location -g --request GET 'https://api.skyhub.com.br/products?only[]=sku&only[]=images&only[]=cost' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' ``` #### **Response esperado:** {% hint style="success" %} 200 \[Success] - OK: No retorno para a consulta acima serão visualizados os campos *sku*, *images* e *cost* de todos os produtos da conta, como vemos a seguir: {% endhint %} ``` { "products": [ { "sku": "SKU_01", "cost": 1374.45, "images": [ "https://images-americanas.b2w.io/produtos/1234567890/imagens/camiseta-branca-tam-un/1234567890_1_xlarge.jpg" ] }, { "sku": "SKU_02", "cost": 49.0, "images": [ "https://images-americanas.b2w.io/produtos/1122334455/imagens/camiseta-preta/1122334455_1_xlarge.jpg" ] }, { "sku": "SKU_03", "cost": 49.0, "images": [ "https://images-americanas.b2w.io/produtos/0123456789/imagens/livro-para-colorir/0123456789_1_xlarge.jpg" ] } (...) ], "total": 101, "next": "https://api.skyhub.com.br/products?only[]=sku&only[]=images&only[]=cost&cursor=cXVlcnlUa........swOw==" ``` # Endpoint Atributos Os atributos são elementos que ajudam a diferenciar ou descrever características de especificação técnica do produto criado {% hint style="danger" %} **Esse endpoint foi descontinuado em Março/2025.** {% endhint %} ### Por que algo simples é tão importante para o produto? Os atributos são informações importantes para os filtros de categorias e para diferenciar os SKUs de um produto; quanto mais atributos/composição o produto tiver, mais chances terá de aparecer no filtro de categorias. Abaixo temos alguns exemplos de atributos que são obrigatórios no marketplace (mktp) por categoria: | Atributos | Categoria | | -------------- | -------------------- | | **Cor** | Moda | | **Sabor** | Nutrição/Suplementos | | **Tamanho** | Moda | | **Voltagem** | Eletrodomésticos | | **Volumetria** | Perfumes | Os produtos não devem se limitar apenas aos atributos mencionados acima, por exemplo, no seguimento de moda temos outros atributos/composição do produto, tais como marca, fabricante, dentre outros. Para melhor compreensão de atributos obrigatórios, imagine uma loja do seguimento de **moda** vendendo no marketplace, o mktp precisa ter a informação de **cor** e **tamanho** de uma camiseta, pois estes são atributos de diferenciação para cada SKU do produto; através destes atributos será possível que o marketplace disponibilize as opções disponíveis para venda. Agora que mencionamos a importância dessas informações, vamos à prática! A API disponibiliza um endpoint para a criação de atributos que poderão ser utilizados para a caracterização dos produtos, assim como através do mesmo também é possível realizar a consulta dos atributos existentes na conta. ### POST - Criando um atributo A criação de atributos se dá a partir de um POST no endpoint a seguir: ``` https://api.skyhub.com.br/attributes ``` #### Request headers: | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | X-Api-Key | token\_de\_integracao de sua conta SkyHub | | X-Accountmanager-Key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | #### Request body: ``` { "attribute": { "name": "att_name", // [String] Identificador interno do atributo "label": "Atributo Exemplo", // [String] Label que será visualizada no front da API "options": [ // [Array] Campo opcional. Lista as opções do atributo caso ele seja do tipo 'select' (por exemplo, cor: azul, branca, vermelha) "foo", "foo", "foo" ] } } ``` #### Example request: ``` curl --location --request POST 'https://api.skyhub.com.br/attributes' \ --header 'X-User-Email: email_de_usuario' \ --header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \ --header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "attribute": { "name": "Cor_Exemplo", "label": "Cor - Exemplo", "options": [ "Azul", "Branco", "Vermelho" ] } }' ``` #### Response esperado: {% hint style="success" %} 201 - Created {% endhint %} Para visualizar o atributo diretamente no front da API, deve ser acessado o menu SkyHub > Atributos. A seguir temos a visualização retirada do front atual da API:
