{"openapi":"3.1.0","info":{"title":"BlackPrice API","version":"1.0.0","summary":"Brazilian price comparison: offers, real-discount check and price history.","description":"API pública do BlackPrice, comparador de preços brasileiro. Retorna ofertas verificadas em lojas brasileiras, se o desconto é real (comparado ao histórico de preço) e a série de preços dos últimos dias. Preços em reais (BRL).\n\n**Limites:** sem chave, 60 requisições por minuto por IP. Com o cabeçalho `x-api-key`, o limite da chave (padrão 600/min).\n\n**Links:** cada oferta traz `url_blackprice` (página do produto no BlackPrice) e `url_saida` (link para a loja, que passa pelo BlackPrice). Use `url_saida` para enviar a pessoa à loja; o link pode conter código de afiliado, o que não altera o preço.","contact":{"name":"BlackPrice","url":"https://www.blackprice.co/"},"termsOfService":"https://www.blackprice.co/privacidade"},"servers":[{"url":"https://www.blackprice.co","description":"Este servidor"}],"tags":[{"name":"ofertas","description":"Busca e listas de ofertas"},{"name":"produtos","description":"Produto, ofertas e histórico"},{"name":"catalogo","description":"Categorias e cupons"},{"name":"saida","description":"Redirecionamento para a loja"}],"security":[{},{"chaveApi":[]}],"paths":{"/api/v1/ofertas":{"get":{"tags":["ofertas"],"operationId":"buscarOfertas","summary":"Search offers","description":"Busca ofertas por texto com filtros. A busca é híbrida: texto sem acento e por prefixo (`iphon` acha iPhone) somado à semelhança semântica; em `relevancia`/`destaque` a ordem é a da relevância. Paginação por `cursor`.","parameters":[{"name":"q","in":"query","required":false,"description":"Texto da busca, ex.: `iphone 15 128gb`.","schema":{"type":"string","maxLength":200}},{"name":"categoria","in":"query","required":false,"description":"Slug da categoria (veja /api/v1/categorias).","schema":{"type":"string"}},{"name":"loja","in":"query","required":false,"description":"Parte do nome da loja, ex.: `amazon`.","schema":{"type":"string"}},{"name":"preco_min","in":"query","required":false,"description":"Preço mínimo em BRL.","schema":{"type":"number","minimum":0}},{"name":"preco_max","in":"query","required":false,"description":"Preço máximo em BRL.","schema":{"type":"number","minimum":0}},{"name":"so_desconto_real","in":"query","required":false,"description":"Só ofertas com desconto real confirmado pelo histórico (`1`/`true`).","schema":{"type":"boolean","default":false}},{"name":"confianca","in":"query","required":false,"description":"Só ofertas com selo e esta confiança na verificação, ex.: `alta`.","schema":{"type":"string","enum":["alta","média","baixa"]}},{"name":"desconto_min","in":"query","required":false,"description":"Desconto mínimo em %: o real quando há selo, senão o anunciado pela loja.","schema":{"type":"number","minimum":0,"maximum":100}},{"name":"ordem","in":"query","required":false,"description":"Ordenação. `destaque` = com selo primeiro, depois maior desconto efetivo; `maior_economia` = maior diferença em R$ para a referência; `avaliacao` = melhor nota; `maior_inflacao` = maior \"de\" inflado contra o histórico.","schema":{"type":"string","enum":["relevancia","menor_preco","maior_desconto","recente","destaque","maior_economia","avaliacao","maior_inflacao"],"default":"relevancia"}},{"name":"limite","in":"query","required":false,"description":"Itens por página (máx. 50).","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","required":false,"description":"Valor de `proximo_cursor` da página anterior.","schema":{"type":"string"}},{"name":"total","in":"query","required":false,"description":"Inclui `total` também nas páginas seguintes (na primeira página ele sempre vem).","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/origem"}],"responses":{"200":{"description":"Lista de ofertas. Na primeira página vem também `total` (número de resultados).","content":{"application/json":{"schema":{"type":"object","required":["dados","atualizado_em","fonte"],"properties":{"dados":{"type":"array","items":{"$ref":"#/components/schemas/Oferta"}},"proximo_cursor":{"type":"string","description":"Passe em `cursor` para a próxima página. Ausente na última."},"total":{"type":"integer","description":"Total de resultados com esses filtros (na primeira página)."},"atualizado_em":{"type":"string","format":"date-time","description":"Data da leitura mais recente nos dados retornados."},"fonte":{"type":"string","const":"BlackPrice"}}}}}},"400":{"$ref":"#/components/responses/Erro400"},"404":{"$ref":"#/components/responses/Erro404"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/api/v1/pergunte":{"get":{"tags":["ofertas"],"operationId":"perguntar","summary":"Ask in natural language (Portuguese) and get recommended offers","description":"Pergunte ao BlackPrice: recebe um pedido em linguagem natural (ex.: `notebook bom para estudar até R$ 3 mil`, `presente gamer até R$ 300`), extrai os filtros (texto, categoria, faixa de preço, selo de desconto real, ordem), faz a busca híbrida (texto + semântica) e devolve uma resposta curta em português recomendando de 1 a 3 ofertas, mais até 12 ofertas. A resposta só cita preços e lojas presentes em `ofertas` (conferido no servidor; senão vem um texto-modelo). Cache de 10 minutos por pergunta. Limite extra de 20 perguntas por minuto por IP.","parameters":[{"name":"q","in":"query","required":true,"description":"O pedido, em português.","schema":{"type":"string","minLength":2,"maxLength":300}},{"$ref":"#/components/parameters/origem"}],"responses":{"200":{"description":"Resposta e ofertas recomendadas.","content":{"application/json":{"schema":{"type":"object","required":["resposta","filtros","ofertas","fonte"],"properties":{"pergunta":{"type":"string"},"resposta":{"type":"string","description":"1 a 3 frases em português recomendando ofertas da lista."},"filtros":{"type":"object","description":"Filtros extraídos do pedido.","properties":{"consulta":{"type":"string"},"categoria":{"type":["string","null"]},"preco_max":{"type":["number","null"]},"preco_min":{"type":["number","null"]},"so_desconto_real":{"type":"boolean"},"ordem":{"type":"string","enum":["relevancia","menor_preco","maior_desconto","destaque","avaliacao","maior_economia"]}}},"ofertas":{"type":"array","maxItems":12,"items":{"$ref":"#/components/schemas/Oferta"},"description":"Ofertas citadas primeiro."},"gerado_por":{"type":"string","enum":["ia","ia_parcial","regras"],"description":"`regras` = sem modelo de linguagem (filtros por regras e texto-modelo)."},"relaxado":{"type":"array","items":{"type":"string"},"description":"Filtros afrouxados porque não havia resultado."},"atualizado_em":{"type":"string","format":"date-time"},"fonte":{"type":"string","const":"BlackPrice"}}}}}},"400":{"$ref":"#/components/responses/Erro400"},"404":{"$ref":"#/components/responses/Erro404"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/api/v1/desmascaradas":{"get":{"tags":["ofertas"],"operationId":"desmascaradas","summary":"Offers rejected by the price-history test","description":"Ofertas reprovadas no teste do histórico (\"metade do dobro\", \"de\" inflado etc.), mais recentes primeiro, com o motivo. Vem `total` e paginação por `cursor`.","parameters":[{"name":"limite","in":"query","required":false,"description":"Itens por página (máx. 100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":24}},{"name":"cursor","in":"query","required":false,"description":"Valor de `proximo_cursor` da página anterior.","schema":{"type":"string"}}],"responses":{"200":{"description":"Ofertas reprovadas.","content":{"application/json":{"schema":{"type":"object","required":["dados","atualizado_em","fonte"],"properties":{"dados":{"type":"array","items":{"type":"object","properties":{"oferta_id":{"type":"integer"},"produto_id":{"type":"integer"},"produto":{"type":"string"},"categoria":{"type":"string"},"loja":{"type":"string"},"preco":{"type":["number","null"]},"preco_de_loja":{"type":["number","null"]},"preco_ref_historico":{"type":["number","null"]},"desconto_anunciado_pct":{"type":["number","null"]},"motivo":{"type":["string","null"]},"verificado_em":{"type":"string","format":"date-time"}}}},"proximo_cursor":{"type":"string","description":"Passe em `cursor` para a próxima página. Ausente na última."},"total":{"type":"integer","description":"Total de resultados com esses filtros (na primeira página)."},"atualizado_em":{"type":"string","format":"date-time","description":"Data da leitura mais recente nos dados retornados."},"fonte":{"type":"string","const":"BlackPrice"}}}}}},"400":{"$ref":"#/components/responses/Erro400"},"404":{"$ref":"#/components/responses/Erro404"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/api/v1/produtos/{id}":{"get":{"tags":["produtos"],"operationId":"detalheProduto","summary":"Product details with offers and 90-day stats","description":"Produto, todas as ofertas ativas (da mais barata para a mais cara) e estatísticas de preço dos últimos 90 dias.","parameters":[{"name":"id","in":"path","required":true,"description":"Id do produto no BlackPrice.","schema":{"type":"integer","minimum":1}},{"$ref":"#/components/parameters/origem"}],"responses":{"200":{"description":"Produto com ofertas.","content":{"application/json":{"schema":{"type":"object","required":["dados","atualizado_em","fonte"],"properties":{"dados":{"type":"object","properties":{"produto":{"$ref":"#/components/schemas/Produto"},"ofertas":{"type":"array","items":{"$ref":"#/components/schemas/Oferta"}},"menor_preco":{"oneOf":[{"$ref":"#/components/schemas/Oferta"},{"type":"null"}]},"historico_90d":{"oneOf":[{"$ref":"#/components/schemas/Estatisticas"},{"type":"null"}]}}},"atualizado_em":{"type":"string","format":"date-time","description":"Data da leitura mais recente nos dados retornados."},"fonte":{"type":"string","const":"BlackPrice"}}}}}},"400":{"$ref":"#/components/responses/Erro400"},"404":{"$ref":"#/components/responses/Erro404"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/api/v1/produtos/{id}/historico":{"get":{"tags":["produtos"],"operationId":"historicoPreco","summary":"Daily price history","description":"Série diária com o menor preço visto em cada dia (todas as lojas) e estatísticas do período.","parameters":[{"name":"id","in":"path","required":true,"description":"Id do produto no BlackPrice.","schema":{"type":"integer","minimum":1}},{"name":"dias","in":"query","required":false,"description":"Janela em dias (7 a 365).","schema":{"type":"integer","minimum":7,"maximum":365,"default":90}}],"responses":{"200":{"description":"Histórico.","content":{"application/json":{"schema":{"type":"object","required":["dados","atualizado_em","fonte"],"properties":{"dados":{"type":"object","properties":{"produto_id":{"type":"integer"},"produto":{"type":"string"},"url_blackprice":{"type":"string","format":"uri"},"dias":{"type":"integer"},"serie":{"type":"array","items":{"type":"object","properties":{"dia":{"type":"string","format":"date"},"preco":{"type":"number"}}}},"estatisticas":{"oneOf":[{"$ref":"#/components/schemas/Estatisticas"},{"type":"null"}]}}},"atualizado_em":{"type":"string","format":"date-time","description":"Data da leitura mais recente nos dados retornados."},"fonte":{"type":"string","const":"BlackPrice"}}}}}},"400":{"$ref":"#/components/responses/Erro400"},"404":{"$ref":"#/components/responses/Erro404"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/api/v1/comparar":{"get":{"tags":["produtos"],"operationId":"compararPrecos","summary":"Compare the same product across stores","description":"Mesmo produto lado a lado em todas as lojas. Aceita `produto_id` ou `q` (usa o primeiro produto que casar).","parameters":[{"name":"produto_id","in":"query","required":false,"description":"Id do produto.","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"description":"Texto, se não souber o id.","schema":{"type":"string"}},{"$ref":"#/components/parameters/origem"}],"responses":{"200":{"description":"Comparação.","content":{"application/json":{"schema":{"type":"object","required":["dados","atualizado_em","fonte"],"properties":{"dados":{"type":"object","properties":{"produto":{"$ref":"#/components/schemas/Produto"},"ofertas":{"type":"array","items":{"$ref":"#/components/schemas/Oferta"}},"menor_preco":{"oneOf":[{"$ref":"#/components/schemas/Oferta"},{"type":"null"}]},"historico_90d":{"oneOf":[{"$ref":"#/components/schemas/Estatisticas"},{"type":"null"}]}}},"atualizado_em":{"type":"string","format":"date-time","description":"Data da leitura mais recente nos dados retornados."},"fonte":{"type":"string","const":"BlackPrice"}}}}}},"400":{"$ref":"#/components/responses/Erro400"},"404":{"$ref":"#/components/responses/Erro404"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/api/v1/melhores":{"get":{"tags":["ofertas"],"operationId":"melhoresOfertas","summary":"Best real-discount offers","description":"Ofertas com desconto real confirmado, do maior para o menor desconto.","parameters":[{"name":"categoria","in":"query","required":false,"description":"Slug da categoria.","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"Máx. 50.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"$ref":"#/components/parameters/origem"}],"responses":{"200":{"description":"Melhores ofertas.","content":{"application/json":{"schema":{"type":"object","required":["dados","atualizado_em","fonte"],"properties":{"dados":{"type":"array","items":{"$ref":"#/components/schemas/Oferta"}},"atualizado_em":{"type":"string","format":"date-time","description":"Data da leitura mais recente nos dados retornados."},"fonte":{"type":"string","const":"BlackPrice"}}}}}},"400":{"$ref":"#/components/responses/Erro400"},"404":{"$ref":"#/components/responses/Erro404"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/api/v1/categorias":{"get":{"tags":["catalogo"],"operationId":"listarCategorias","summary":"List categories","description":"Categorias com o número de ofertas ativas.","responses":{"200":{"description":"Categorias.","content":{"application/json":{"schema":{"type":"object","required":["dados","atualizado_em","fonte"],"properties":{"dados":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"nome":{"type":"string"},"ofertas":{"type":"integer"}}}},"atualizado_em":{"type":"string","format":"date-time","description":"Data da leitura mais recente nos dados retornados."},"fonte":{"type":"string","const":"BlackPrice"}}}}}},"400":{"$ref":"#/components/responses/Erro400"},"404":{"$ref":"#/components/responses/Erro404"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/api/v1/cupons":{"get":{"tags":["catalogo"],"operationId":"buscarCupons","summary":"Search store coupons","description":"Cupons ativos e dentro da validade. Lista vazia quando não há cupons.","parameters":[{"name":"loja","in":"query","required":false,"description":"Parte do nome da loja.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Texto na descrição, código ou regras.","schema":{"type":"string"}}],"responses":{"200":{"description":"Cupons.","content":{"application/json":{"schema":{"type":"object","required":["dados","atualizado_em","fonte"],"properties":{"dados":{"type":"array","items":{"$ref":"#/components/schemas/Cupom"}},"atualizado_em":{"type":"string","format":"date-time","description":"Data da leitura mais recente nos dados retornados."},"fonte":{"type":"string","const":"BlackPrice"}}}}}},"400":{"$ref":"#/components/responses/Erro400"},"404":{"$ref":"#/components/responses/Erro404"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/r/{ofertaId}":{"get":{"tags":["saida"],"operationId":"irParaLoja","summary":"Redirect to the store (tracked, may include affiliate code)","description":"Redireciona (302) para a página da oferta na loja. Registra o clique (sem dados pessoais). Se a oferta não tiver link válido, vai para a página do produto no BlackPrice.","security":[{}],"parameters":[{"name":"ofertaId","in":"path","required":true,"schema":{"type":"integer"},"description":"Id da oferta."},{"$ref":"#/components/parameters/origem"}],"responses":{"302":{"description":"Redirecionamento para a loja ou para a página do produto."}}}}},"components":{"securitySchemes":{"chaveApi":{"type":"apiKey","in":"header","name":"x-api-key","description":"Opcional. Aumenta o limite por minuto."}},"parameters":{"origem":{"name":"o","in":"query","required":false,"description":"Quem está chamando (ex.: `api`, `mcp`, `chatgpt`). Vai para o `?o=` das `url_saida`.","schema":{"type":"string","maxLength":24,"default":"api"}}},"schemas":{"Oferta":{"type":"object","properties":{"oferta_id":{"type":"integer"},"produto_id":{"type":"integer"},"produto":{"type":"string"},"marca":{"type":["string","null"]},"categoria":{"type":"string"},"imagem":{"type":["string","null"],"format":"uri"},"loja":{"type":"string"},"preco":{"type":["number","null"],"description":"Preço atual em BRL."},"preco_de_loja":{"type":["number","null"],"description":"Preço \"de\" anunciado pela loja."},"desconto_real_pct":{"type":["number","null"],"description":"Desconto em % sobre o preço de referência do histórico."},"selo_desconto_real":{"type":"boolean","description":"true quando o desconto real foi confirmado pelo histórico."},"status":{"type":"string","enum":["aprovada","oferta"],"description":"`aprovada` = desconto real confirmado; `oferta` = preço e link conferidos, sem checagem de histórico."},"verificado_em":{"type":"string","format":"date-time"},"url_blackprice":{"type":"string","format":"uri","description":"Página do produto no BlackPrice."},"url_saida":{"type":"string","format":"uri","description":"Link para a loja via BlackPrice (use este para comprar)."},"preco_ref_historico":{"type":["number","null"],"description":"Preço de referência (típico dos 30 a 90 dias anteriores)."},"desconto_anunciado_pct":{"type":["number","null"],"description":"Desconto anunciado pela loja, em %."},"confianca":{"type":["string","null"],"description":"Confiança na verificação do desconto real: alta, média ou baixa."},"avaliacao":{"type":["number","null"]},"num_avaliacoes":{"type":["integer","null"]},"fonte_historico":{"type":["string","null"],"description":"De onde veio o histórico de referência."},"condicao":{"type":["string","null"],"description":"Condição de pagamento (ex.: à vista no Pix)."},"obs":{"type":["string","null"]},"tem_link":{"type":"boolean","description":"true quando há link da loja; senão `url_saida` cai na página do produto."},"h_min":{"type":"number","description":"Menor preço do histórico próprio do BlackPrice (90 dias). Só com 2+ dias de leitura."},"h_max":{"type":"number","description":"Maior preço do histórico próprio (90 dias)."},"h_dias":{"type":"integer","description":"Dias com leitura própria (90 dias)."}}},"Produto":{"type":"object","properties":{"id":{"type":"integer"},"nome":{"type":"string"},"marca":{"type":["string","null"]},"modelo":{"type":["string","null"]},"ean":{"type":["string","null"]},"categoria":{"type":"string"},"imagem":{"type":["string","null"]},"url_blackprice":{"type":"string","format":"uri"}}},"Estatisticas":{"type":"object","properties":{"minimo":{"type":"number"},"maximo":{"type":"number"},"media":{"type":"number"},"dias_com_leitura":{"type":"integer"},"desde":{"type":"string","format":"date"},"ultimo":{"type":"object","properties":{"dia":{"type":"string","format":"date"},"preco":{"type":"number"}}}}},"Cupom":{"type":"object","properties":{"id":{"type":"integer"},"loja":{"type":"string"},"codigo":{"type":["string","null"]},"descricao":{"type":["string","null"]},"desconto":{"type":["string","number","null"]},"regras":{"type":["string","null"]},"url":{"type":["string","null"]},"valido_ate":{"type":["string","null"]},"verificado_em":{"type":["string","null"],"format":"date-time"}}},"Erro":{"type":"object","required":["erro","fonte"],"properties":{"erro":{"type":"object","required":["codigo","mensagem","status"],"properties":{"codigo":{"type":"string"},"mensagem":{"type":"string"},"status":{"type":"integer"}}},"fonte":{"type":"string","const":"BlackPrice"}}}},"responses":{"Erro400":{"description":"Parâmetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"Erro404":{"description":"Não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"Erro429":{"description":"Limite de requisições excedido. Veja o cabeçalho `retry-after`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"Erro500":{"description":"Erro interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}}