Busca de Produtos

Conecte a API de catálogo de um provedor externo para que o Mercado Eletrônico busque produtos e ofertas em tempo real.

---

O template Busca de Produtos liga o ME à API REST de um provedor de catálogo, como um distribuidor, fabricante ou marketplace. Quando um usuário busca produtos no ME, o iPaaS chama a API do provedor, converte a resposta para o formato de catálogo do ME e devolve o resultado na hora (resposta síncrona).

Nenhum produto é copiado para o ME: os dados vêm do provedor a cada busca.

Quando usar

• Você quer que os compradores vejam no ME os produtos, preços e disponibilidade de um provedor externo, sempre atualizados.
• O provedor oferece uma API REST de busca de produtos, detalhe de produto e, opcionalmente, ofertas.

Pré-requisito: conector

Este template exige um conector cadastrado para o provedor, com:

• a URL base e a autenticação da API do provedor;
• um recurso para cada endpoint usado: busca/listagem, detalhe do produto e, se houver, ofertas;
• se necessário, o mapeamento de requisição de cada recurso, para adaptar os parâmetros do ME ao formato do provedor.

Operações

Operação	Obrigatória	O que faz	Parâmetros de entrada
Buscar todos (getAll)	Sim	Retorna a lista de produtos do provedor para um termo de busca, com paginação.	searchTerm, pageNumber, pageSize
Buscar por ID (getById)	Sim	Retorna o detalhe de um produto, com a oferta em destaque e as demais ofertas.	productId
Buscar ofertas (getOffers)	Não	Retorna as ofertas de preço de um produto.	productId

Configurando

Crie a integração em Integrações > Templates > Product Search > Usar Template e siga as etapas do assistente:

1. Parâmetros:
   • Connector: o conector do provedor. Se ainda não existir, use Criar novo connector.
   • ME Supplier ID: o identificador do fornecedor no ME ao qual os produtos deste provedor ficam vinculados.
   • Operações: escolha o Recurso do conector que atende cada operação.
2. Estrutura do documento: para cada operação configurada, carregue a resposta real do provedor. O iPaaS detecta os campos disponíveis a partir dela.
3. Dados do Mapeamento: para cada operação, ligue os campos da resposta do provedor (Origem) aos campos de catálogo do ME (Destino), com a ajuda da IA. Veja Mapeamento com IA.
4. Teste: execute cada operação contra o provedor, informando um Termo de busca (getAll) ou um ID do produto (getById e getOffers), e confira a Resposta. As operações obrigatórias precisam passar para você continuar.
5. Revisar e publicar: confira as Operações e estrutura e o resultado do Teste, e publique.

📘 Nota

Neste template você pode testar quantas vezes precisar, inclusive depois que a integração ficar Validada. Assim você ajusta o mapeamento e testa de novo antes de publicar.

Formato de catálogo do ME (destino)

O resultado de cada operação é sempre convertido para o formato abaixo. Os campos marcados como obrigatórios precisam estar mapeados.

getAll

Campo	Tipo	Obrigatório
items	lista	Sim
items.productId	texto	Sim
items.description	texto	Sim
items.currency	texto	Sim
items.complement	texto
items.clientGroupDescription	texto
items.manufacturer	texto
items.additionalFields.brand	texto
items.additionalFields.url	texto
items.additionalFields.picture	lista de { url }
items.additionalFields.featuredOffer.price	número	Sim, se houver featuredOffer
items.additionalFields.featuredOffer.availability	texto	Sim, se houver featuredOffer
totalItems	número inteiro	Sim

getById

Os mesmos campos de um item do getAll (productId, description e currency obrigatórios), mais:

Campo	Tipo
additionalFields.featuredOffer.seller	texto
additionalFields.featuredOffer.condition	texto
additionalFields.offers	lista de { id, price, currency, availability, seller }

getOffers

Campo	Tipo	Obrigatório
additionalFields.featuredOffer.id	texto	Sim
additionalFields.featuredOffer.price	número	Sim
additionalFields.featuredOffer.currency	texto	Sim
additionalFields.featuredOffer.availability	texto	Sim
additionalFields.featuredOffer.seller	texto
additionalFields.featuredOffer.condition	texto
additionalFields.offers	lista de { id, price, currency, availability, seller }

Executando

Quem chama a integração é o próprio ME, durante a busca de produtos. Por isso, este template não tem tela de credencial: ao publicar, o portal mostra uma confirmação e volta para Minhas Integrações. Para testar, use a etapa Teste do assistente.

A cada busca, o ME envia a operação e os parâmetros abaixo, que chegam ao provedor conforme o mapeamento de requisição do conector:

Operação	Parâmetros
getAll	searchTerm (termo buscado), pageNumber (página, a partir de 1) e pageSize (itens por página)
getById e getOffers	productId (código do produto no provedor)

Se o provedor numera as páginas a partir de 0, use pageNumber - 1 no mapeamento de requisição. O iPaaS não impõe um valor máximo de pageSize.

Retorno

A resposta é síncrona, e o resultado convertido vem no campo mePayload, no formato de catálogo da operação:

200 OK

{
  "correlationId": "{correlationId}",
  "mePayload": {
    "items": [ { "productId": "{...}", "description": "{...}", "currency": "{...}" } ],
    "totalItems": {total de produtos}
  }
}

No getAll, a resposta sempre vem no formato { items, totalItems }. Se o mapeamento devolver só a lista de produtos, o iPaaS monta esse formato e preenche totalItems com a quantidade de itens recebida do provedor. Para a paginação do ME funcionar, mapeie totalItems a partir do total de resultados informado pelo provedor. Se o provedor devolver mais itens que o pageSize pedido, o iPaaS corta a lista na página pedida.

Erros do provedor aparecem com failedAtStep = API_REQUEST: um erro 4xx do provedor é devolvido com o mesmo status e, quando houver, os detalhes do erro; um erro 5xx do provedor vira 502 (The provider API returned an error.); e, se o provedor não responder a tempo, o retorno é 504 (The provider API timed out.). Veja Execuções.

Limitações

• Exige conector. Sem um conector com os recursos configurados, a integração não pode ser testada nem publicada.
• Três operações fixas: getAll, getById e getOffers. Não é possível criar operações novas.
• Parâmetros fixos do ME: as buscas enviam apenas searchTerm, pageNumber, pageSize e productId. Outros filtros do provedor só podem ser enviados como valor fixo no mapeamento de requisição.
• Formato de destino fixo: o resultado precisa caber no formato de catálogo do ME descrito acima.
• Tempo real: cada busca depende da disponibilidade e do tempo de resposta do provedor. Se o provedor estiver fora do ar, a busca falha.
• Gerar Purchase Order aparece na tela, mas ainda não está disponível (em breve).
• APIs REST com JSON apenas. Veja as limitações dos conectores.