--- title: "Buscar produto por código de barras ou nome" url: "https://devcenter.stone.com.br/apis/stone-catalog/versions/502db258-cb08-4b38-8af1-b96a688b9a9e/operations/getProduct" --- > Full API specification: https://devcenter.stone.com.br/apis/stone-catalog/versions/502db258-cb08-4b38-8af1-b96a688b9a9e.md # Buscar produto por código de barras ou nome `GET` `/products` Operation ID: `getProduct` Busca informações detalhadas de um produto por código de barras (EAN-8, EAN-12, EAN-13 e EAN-14) ou nome. Consulta o cache L2 (PostgreSQL) antes de acionar o pipeline de discovery via agentes de IA. Máximo de 20 produtos por requisição. **Busca por nome:** consulta apenas o cache — se não encontrado, retorna 404 sem acionar discovery. **Códigos de teste (SDX):** - `7898486077400` — produto não encontrado (404) - `7898486077417` — produto em fila de retry (404) - `7898486077424` — produto em discovery (422) ## Query parameters - `barcode` (string, optional) - Código de barras EAN-13 do produto (12 ou 13 dígitos numéricos). - `name` (string, optional) - Nome do produto para busca. A busca por nome retorna produtos fictícios em ambiente sandbox. **Comportamento de busca**: - Consulta apenas o cache L2 (PostgreSQL) - Se nenhum produto for encontrado, retorna 404 imediatamente (sem discovery). ## Header parameters - `x-merchant-document` (string, required) - CNPJ ou CPF do merchant (obrigatório). Aceita CPF numérico (11 dígitos), CNPJ numérico legado (14 dígitos) e CNPJ alfanumérico (12 caracteres alfanuméricos + 2 dígitos verificadores). Em caso de erro de validação, o campo `details[].message` pode retornar mensagens específicas como tamanho inválido, formato inválido, dígitos verificadores inválidos ou tipo não suportado. ## Responses - `200` - Produtos encontrados com sucesso - `400` - Parâmetros inválidos - `401` - Não autenticado ou credenciais inválidas - `404` - Produto não encontrado - `422` - Conflito de processamento - `429` - Limite de requisições excedido - `500` - Erro interno do servidor ## OpenAPI definition ```yaml openapi: 3.0.3 info: title: Stone Catalog API version: 1.0.0 servers: - url: https://sdx.api.stone.com.br/v1/catalog description: Ambiente de Desenvolvimento (SDX) - url: https://api.stone.com.br/v1/catalog description: Ambiente de Produção (PRD) paths: /products: get: tags: - Products summary: Buscar produto por código de barras ou nome description: >- Busca informações detalhadas de um produto por código de barras (EAN-8, EAN-12, EAN-13 e EAN-14) ou nome. Consulta o cache L2 (PostgreSQL) antes de acionar o pipeline de discovery via agentes de IA. Máximo de 20 produtos por requisição. **Busca por nome:** consulta apenas o cache — se não encontrado, retorna 404 sem acionar discovery. **Códigos de teste (SDX):** - `7898486077400` — produto não encontrado (404) - `7898486077417` — produto em fila de retry (404) - `7898486077424` — produto em discovery (422) operationId: getProduct parameters: - name: barcode in: query description: Código de barras EAN-13 do produto (12 ou 13 dígitos numéricos). required: false schema: type: string pattern: ^\d{12,13}$ example: "7891000100103" - name: name in: query description: >- Nome do produto para busca. A busca por nome retorna produtos fictícios em ambiente sandbox. **Comportamento de busca**: - Consulta apenas o cache L2 (PostgreSQL) - Se nenhum produto for encontrado, retorna 404 imediatamente (sem discovery). required: false schema: type: string pattern: ^[a-zA-ZÀ-ÿ\s\d./-]+$ example: Coca-Cola 2L - name: x-merchant-document in: header description: CNPJ ou CPF do merchant (obrigatório). Aceita CPF numérico (11 dígitos), CNPJ numérico legado (14 dígitos) e CNPJ alfanumérico (12 caracteres alfanuméricos + 2 dígitos verificadores). Em caso de erro de validação, o campo `details[].message` pode retornar mensagens específicas como tamanho inválido, formato inválido, dígitos verificadores inválidos ou tipo não suportado. required: true schema: type: string pattern: ^(\d{11}|\d{14}|[A-Za-z0-9]{12}\d{2})$ example: 12345678901234, 12345678901 ou 12ABC34501DE35 security: - BearerAuth: [] responses: "200": description: Produtos encontrados com sucesso content: application/json: schema: type: array items: $ref: "#/components/schemas/ProductResponse" example: - id: 550e8400-e29b-41d4-a716-446655440000 barcode: "7891000100103" name: Coca-Cola 2L shortDescription: Refrigerante Coca-Cola 2 Litros longDescription: Refrigerante Coca-Cola sabor original em garrafa PET de 2 litros. Produto ideal para toda a família. brand: Coca-Cola manufacturer: Coca-Cola Brasil categoryPath: Alimentos e Bebidas > Bebidas > Refrigerantes images: - https://s3.amazonaws.com/stone-catalog/products/550e8400-e29b-41d4-a716-446655440000/image1.jpg - https://s3.amazonaws.com/stone-catalog/products/550e8400-e29b-41d4-a716-446655440000/image2.jpg price: R$ 7.99 - R$ 11.59 attributes: volume: 2L sabor: Original tipo: Refrigerante weightKg: 2.1 heightCm: 32.5 widthCm: 10.5 depthCm: 10.5 metadata: version: 1 confidenceScore: 0.95 discoveredAt: 2024-01-15T10:30:00Z updatedAt: 2024-01-15T10:30:00Z lastScrapedAt: 2024-01-15T10:30:00Z "400": description: Parâmetros inválidos content: application/json: schema: $ref: "#/components/schemas/ValidationError" examples: missing-params: summary: Nenhum parâmetro fornecido value: error: Invalid parameters details: - field: query message: "Exactly one parameter must be provided: barcode OR name" invalid-barcode: summary: Código de barras inválido value: error: Invalid parameters details: - field: barcode message: Barcode must contain exactly 12 or 13 numeric digits invalid-name: summary: Nome do produto inválido value: error: Invalid parameters details: - field: name message: Name must have at least 3 characters "401": description: Não autenticado ou credenciais inválidas content: application/json: schema: $ref: "#/components/schemas/Error" example: error: Unauthorized message: Invalid or missing API credentials "404": description: Produto não encontrado content: application/json: schema: type: object required: - error properties: errorCode: type: string enum: - ErrProductNotFoundTemporarily - ErrProductNotFound error: type: string examples: product-not-found-temporary: summary: Produto não encontrado - busca em andamento description: O produto não foi encontrado, mas o sistema continuará procurando. Tente novamente mais tarde. value: errorCode: ErrProductNotFoundTemporarily error: Product not found right now. We will continue to search for it. Try again later. product-not-found-permanent: summary: Produto não encontrado - sem resultados description: O produto não foi encontrado e não há resultados disponíveis. value: errorCode: ErrProductNotFound error: Product not found. "422": description: Conflito de processamento content: application/json: schema: type: object properties: errorCode: type: string error: type: string extraData: type: object nullable: true examples: product-in-discovery: summary: Produto em processo de descoberta value: errorCode: ErrProductInDiscovery error: Product is already in discovery process. Try again later. "429": description: Limite de requisições excedido content: application/json: schema: $ref: "#/components/schemas/Error" example: error: Too Many Requests message: Rate limit exceeded. Please try again later. "500": description: Erro interno do servidor content: application/json: schema: $ref: "#/components/schemas/Error" example: error: Internal server error security: - BearerAuth: [] components: schemas: ProductResponse: type: object required: - id - name - categoryPath - images - metadata properties: id: type: string format: uuid description: Identificador único do produto example: 550e8400-e29b-41d4-a716-446655440000 barcode: type: string nullable: true description: Código de barras EAN-13 pattern: ^\d{12,13}$ example: "7891000100103" name: type: string description: Nome do produto example: Coca-Cola 2L shortDescription: type: string nullable: true description: Descrição curta do produto example: Refrigerante Coca-Cola 2 Litros longDescription: type: string nullable: true description: Descrição detalhada do produto example: Refrigerante Coca-Cola sabor original em garrafa PET de 2 litros. Produto ideal para toda a família. brand: type: string nullable: true description: Marca do produto example: Coca-Cola manufacturer: type: string nullable: true description: Fabricante do produto example: Coca-Cola Brasil categoryPath: type: string description: Caminho completo da categoria example: Alimentos e Bebidas > Bebidas > Refrigerantes images: type: array description: Lista de URLs das imagens do produto items: type: string format: uri example: https://s3.amazonaws.com/stone-catalog/products/550e8400-e29b-41d4-a716-446655440000/image1.jpg attributes: type: object nullable: true description: Atributos específicos do produto (pares chave-valor) additionalProperties: type: string example: volume: 2L sabor: Original tipo: Refrigerante weightKg: type: number nullable: true format: float description: Peso do produto em quilogramas example: 2.1 heightCm: type: number nullable: true format: float description: Altura do produto em centímetros example: 32.5 widthCm: type: number nullable: true format: float description: Largura do produto em centímetros example: 10.5 depthCm: type: number nullable: true format: float description: Profundidade do produto em centímetros example: 10.5 price: type: string nullable: true format: string description: Faixa de preço do produto em reais. Retorna null quando não disponível. example: R$ 7.50 metadata: type: object required: - version - confidenceScore - discoveredAt - updatedAt - lastScrapedAt properties: version: type: integer description: Versão do registro do produto example: 1 confidenceScore: type: number format: float minimum: 0 maximum: 1 description: Score de confiança dos dados (0.00 - 1.00) example: 0.95 discoveredAt: type: string format: date-time description: Data/hora em que o produto foi descoberto example: 2024-01-15T10:30:00Z updatedAt: type: string format: date-time description: Data/hora da última atualização example: 2024-01-15T10:30:00Z lastScrapedAt: type: string format: date-time description: Data/hora do último scraping example: 2024-01-15T10:30:00Z ValidationError: type: object required: - error - details properties: error: type: string description: Mensagem de erro example: Invalid parameters details: type: array description: Lista de erros de validação items: type: object properties: field: type: string description: Campo com erro example: barcode message: type: string description: Mensagem de erro específica example: Barcode must contain exactly 12 or 13 numeric digits Error: type: object required: - error properties: error: type: string description: Mensagem de erro example: Internal server error securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Autenticação via Bearer token. Para aplicações legadas, obtenha um JWT através do endpoint /auth/generate-token usando Basic Auth. Para integrações novas, envie o access token emitido pelo IDP externo com o escopo usr_type/partner_stone_catalog. ```