Skip to content

Consulta um produto na loja virtual, com SKUs, preço e estoque em tempo real

Request

Busca um produto diretamente na plataforma de e-commerce integrada (via conector), retornando suas variações (SKUs), preços e disponibilidade no momento da consulta.

Para que serve

É o endpoint que viabiliza a troca por outra variação. Numa devolução basta saber o que foi comprado; numa troca é preciso saber o que está disponível agora: a grade de tamanhos/cores, quais SKUs têm estoque e a que preço. Consultar a plataforma direto pela Genius evita que sua integração precise de credenciais próprias da loja e replicar as particularidades de cada plataforma (VTEX, Shopify, Magento, AnyMarket…).

Como o front Genius usa

Quando o consumidor escolhe "trocar por outro tamanho/cor", o front chama este endpoint com o produtoId do item devolvido e o mainSkuId comprado originalmente, e monta o seletor de variações apenas com SKUs disponíveis. Informando zipCodeTo, o estoque é avaliado para a região de entrega do consumidor — evitando oferecer uma variação que não pode ser entregue no CEP dele.

Observações

  • conectorId deve pertencer à conta autenticada; caso contrário retorna 401. Obtenha-o em /v2/pvt/ecommerce/obter-conector.
  • Produto indisponível na plataforma retorna 500 com erroTipo de integração — trate como "variação não disponível para troca", não como falha da API.
  • A plataforma de origem pode aplicar rate limit; nesse caso a resposta traz o código 429 em erroCodigo.
Security
BearerAuth
Bodyapplication/jsonrequired
ConectorIdinteger, (int64)required

Id do conector de e-commerce da conta, obtido em /v2/pvt/ecommerce/obter-conector. Deve pertencer à conta autenticada.

ProdutoIdstringrequired

Id do produto na loja virtual (o mesmo ProdutoId do item do pedido).

MainSkuIdstring or null

Id do SKU originalmente comprado. Permite à Genius destacar a variação de origem e aplicar regras de troca pelo mesmo seller.

ZipCodeTostring or null

CEP de entrega do consumidor. Opcional, porém necessário para estoque em tempo real por região — sem ele, o estoque retornado é o geral.

LojaVirtualUrlstring or null

URL da loja virtual, quando a conta opera múltiplas lojas.

SellerIdstring or null

Id do seller, em cenários de marketplace.

curl -i -X POST \
  https://apidocs.geniusreturns.com.br/_mock/openapi/v1/pvt/pedido/obter-produto-do-conector \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "ConectorId": 42,
    "ProdutoId": "P-1",
    "MainSkuId": "SKU-1",
    "ZipCodeTo": "01310-100",
    "LojaVirtualUrl": "https://lojaoficial.com.br",
    "SellerId": "1"
  }'

Responses

Produto localizado.

Bodyapplication/json
dataHoraRespostastring, (date-time)

Data e hora da resposta, em UTC.

registrosinteger, (int32)

Quantidade de registros retornados em entidade.

httpStatusstring

Código HTTP da resposta, em texto.

erroCodigostring or null

Código do erro, quando houver.

erroDescricaostring or null

Mensagem do erro, quando houver.

erroDetalhadostring or null

Detalhamento técnico do erro, quando houver.

erroTipostring or null

Classificação do erro. Útil para distinguir falha de integração com a plataforma de e-commerce (04) de erro de domínio ou erro comum (00).

entidadeobject(ProdutoConectorModel)

Produto consultado diretamente na plataforma de e-commerce.

Response
{
  "dataHoraResposta": "2026-09-18T13:48:30.115Z",
  "registros": 1,
  "httpStatus": "200",
  "entidade": {
    "id": "P-1",
    "nome": "Camiseta Preta",
    "referencia": "CAM-PRETA",
    "detalheUrl": "https://lojaoficial.com.br/camiseta-preta/p",
    "skus": [ … ],
    "especificacoes": [ … ]
  }
}