{"openapi":"3.0.3","info":{"title":"SysCatálogo","version":"1.0.0","description":"Cadastro de produto por código de barras (GTIN/EAN): descrição, marca, NCM, CEST e foto. O contrato desta v1 é permanente — campo novo entra sempre opcional, e campo em uso nunca é removido nem renomeado."},"servers":[{"url":"https://catalogo.wxdev.com.br"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"O token da sua licença."}},"schemas":{"Autopeca":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"versao":{"type":"integer"},"atualizado_em":{"type":"string","format":"date-time"},"publicado":{"type":"object","description":"Somente grupos revisados e publicados. Ausência de aplicação não significa incompatibilidade; listas podem ser parciais.","properties":{"identificacao":{"type":"object","properties":{"marca":{"type":"string","nullable":true},"fabricante":{"type":"string","nullable":true},"referencia":{"type":"string","nullable":true},"descricao":{"type":"string","nullable":true},"familia":{"type":"string","nullable":true},"linha":{"type":"string","nullable":true},"situacao_comercial":{"type":"string","nullable":true},"fonte":{"type":"string","nullable":true}}},"referencias":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"string","nullable":true},"empresa":{"type":"string","nullable":true},"codigo":{"type":"string","nullable":true},"peca_relacionada_id":{"type":"string","nullable":true},"condicoes":{"type":"string","nullable":true},"fonte":{"type":"string","nullable":true}}}},"aplicacoes":{"type":"array","items":{"type":"object","properties":{"montadora":{"type":"string","nullable":true},"modelo":{"type":"string","nullable":true},"geracao":{"type":"string","nullable":true},"versao":{"type":"string","nullable":true},"motor":{"type":"string","nullable":true},"codigo_motor":{"type":"string","nullable":true},"cilindrada":{"type":"string","nullable":true},"potencia":{"type":"string","nullable":true},"combustivel":{"type":"string","nullable":true},"transmissao":{"type":"string","nullable":true},"carroceria":{"type":"string","nullable":true},"ano_inicio":{"type":"number","nullable":true},"ano_fim":{"type":"number","nullable":true},"periodo_tipo":{"type":"string","nullable":true},"fabricacao_inicio":{"type":"string","nullable":true},"fabricacao_fim":{"type":"string","nullable":true},"chassi_inicio":{"type":"string","nullable":true},"chassi_fim":{"type":"string","nullable":true},"sistema":{"type":"string","nullable":true},"posicao":{"type":"string","nullable":true},"quantidade":{"type":"number","nullable":true},"restricoes":{"type":"string","nullable":true},"fonte":{"type":"string","nullable":true},"confirmada":{"type":"boolean"}}}},"montagem":{"type":"object","properties":{"eixo":{"type":"string","nullable":true},"posicao":{"type":"string","nullable":true},"lado":{"type":"string","nullable":true},"localizacao":{"type":"string","nullable":true},"quantidade":{"type":"number","nullable":true},"fonte":{"type":"string","nullable":true}}},"apresentacoes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"tipo":{"type":"string","nullable":true},"gtin":{"type":"string","nullable":true},"unidade_comercial":{"type":"string","nullable":true},"quantidade":{"type":"number","nullable":true},"conteudo":{"type":"string","nullable":true},"componentes":{"type":"array","items":{"type":"object","properties":{"peca_id":{"type":"string"},"referencia":{"type":"string"},"descricao":{"type":"string"},"quantidade":{"type":"number"}}}},"peso_peca_kg":{"type":"number","nullable":true},"peso_embalagem_kg":{"type":"number","nullable":true},"comprimento_embalagem_mm":{"type":"number","nullable":true},"largura_embalagem_mm":{"type":"number","nullable":true},"altura_embalagem_mm":{"type":"number","nullable":true},"fonte":{"type":"string","nullable":true}}}},"atributos":{"type":"array","items":{"type":"object","properties":{"chave":{"type":"string","nullable":true},"valor":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"unidade":{"type":"string","nullable":true},"fonte":{"type":"string","nullable":true}}}},"fiscal":{"type":"object","properties":{"ncm":{"type":"string","nullable":true},"cest":{"type":"string","nullable":true},"fonte":{"type":"string","nullable":true}}},"documentacao":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"string","nullable":true},"titulo":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"fonte":{"type":"string","nullable":true},"data":{"type":"string","nullable":true},"uso_permitido":{"type":"boolean"},"autorizacao":{"type":"string","nullable":true},"atribuicao":{"type":"string","nullable":true}}}}}}}},"Imagem":{"type":"object","properties":{"thumb":{"type":"string","format":"uri"},"media":{"type":"string","format":"uri"},"grande":{"type":"string","format":"uri"},"licenca":{"type":"string","nullable":true,"description":"Quando preenchido, exibir `atribuicao` é obrigatório."},"atribuicao":{"type":"string","nullable":true},"licenca_url":{"type":"string","format":"uri","nullable":true},"origem_url":{"type":"string","format":"uri","nullable":true},"fonte":{"type":"string","nullable":true},"alteracoes":{"type":"string"},"licenca_registrada":{"type":"string","description":"Rótulo histórico, quando corrigido na entrega."},"licenca_referencia":{"type":"string","format":"uri"},"revisao":{"type":"object","description":"Opcional. Procedência da revisão da imagem; ausente no acervo anterior.","properties":{"modo":{"type":"string","enum":["humano","automatico"]},"ressalva":{"type":"string"},"publicado_em":{"type":"string","format":"date-time"}}}}},"Produto":{"type":"object","properties":{"descricao":{"type":"string","nullable":true},"marca":{"type":"string","nullable":true},"categoria":{"type":"string","nullable":true},"ncm":{"type":"string","nullable":true},"cest":{"type":"string","nullable":true},"unidade":{"type":"string","nullable":true},"unidade_tipo":{"type":"string","enum":["comercial","apresentacao","nao_classificada"],"description":"Significado comprovado pela procedência do campo; apresentação ou não classificada não substituem UNIDADE do ERP."},"peso_liquido":{"type":"number","nullable":true},"fonte":{"type":"string","nullable":true},"confianca":{"type":"integer","nullable":true,"minimum":0,"maximum":100},"imagem":{"allOf":[{"$ref":"#/components/schemas/Imagem"}],"nullable":true}}},"Resposta":{"type":"object","properties":{"gtin":{"type":"string","description":"Normalizado para 14 dígitos."},"origem":{"type":"string","enum":["cache","fonte_externa","produto_sem_imagem","nao_encontrado","codigo_interno"]},"encontrado":{"type":"boolean"},"motivo":{"type":"string","nullable":true},"mensagem":{"type":"string","nullable":true},"produto":{"allOf":[{"$ref":"#/components/schemas/Produto"}],"nullable":true}}},"Erro":{"type":"object","properties":{"erro":{"type":"string"},"motivo":{"type":"string","nullable":true},"mensagem":{"type":"string","nullable":true}}}}},"paths":{"/v1/autopecas":{"get":{"summary":"Pesquisa autopeças publicadas por referência ou aplicação","parameters":[{"name":"busca","in":"query","schema":{"type":"string"}},{"name":"marca","in":"query","schema":{"type":"string"}},{"name":"referencia","in":"query","schema":{"type":"string"}},{"name":"familia","in":"query","schema":{"type":"string"}},{"name":"linha","in":"query","schema":{"type":"string"}},{"name":"montadora","in":"query","schema":{"type":"string"}},{"name":"modelo","in":"query","schema":{"type":"string"}},{"name":"motor","in":"query","schema":{"type":"string"}},{"name":"ano","in":"query","schema":{"type":"string"}},{"name":"pagina","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Página com itens publicados; recusados ficam separados de não encontrados.","content":{"application/json":{"schema":{"type":"object","properties":{"itens":{"type":"array","items":{"$ref":"#/components/schemas/Autopeca"}},"total":{"type":"integer"},"pagina":{"type":"integer"},"recusados":{"type":"array","items":{"type":"string"}}}}}}}}}},"/v1/autopecas/{id}":{"get":{"summary":"Ficha automotiva sem exigir GTIN","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Ficha liberada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Autopeca"}}}},"404":{"description":"Peça ausente ou identidade não publicada"}}}},"/v1/autopecas/sincronizar":{"post":{"summary":"Sincroniza fichas automotivas; somente leitura local","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":5000,"items":{"type":"string","format":"uuid"}},"desde":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Itens alterados, retirados da publicação, não encontrados e recusados separados","content":{"application/json":{"schema":{"type":"object","properties":{"sincronizado_em":{"type":"string","format":"date-time"},"itens":{"type":"array","items":{"$ref":"#/components/schemas/Autopeca"}},"retirados":{"type":"array","items":{"type":"string"}},"nao_encontrados":{"type":"array","items":{"type":"string"}},"recusados":{"type":"array","items":{"type":"string"}},"sem_alteracao":{"type":"integer"}}}}}}}}},"/v1/autopecas/{id}/exportar/{grupo}.csv":{"get":{"summary":"Exporta grupo da ficha por identificador","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"grupo","in":"path","required":true,"schema":{"type":"string","enum":["identificacao","referencias","aplicacoes","montagem","apresentacoes","atributos","fiscal","documentacao"]}}],"responses":{"200":{"description":"CSV ligado pelo identificador da peça","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/v1/produtos/{gtin}":{"get":{"summary":"Consulta um produto pelo código de barras","parameters":[{"name":"gtin","in":"path","required":true,"schema":{"type":"string"},"description":"EAN-8, UPC-12, EAN-13 ou GTIN-14, com ou sem zeros à esquerda."}],"responses":{"200":{"description":"Produto encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Resposta"}}}},"401":{"description":"Token inválido ou licença inativa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"402":{"description":"Teto de produtos do plano atingido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Não temos este produto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Resposta"}}}},"422":{"description":"Código interno da loja: não existe em base externa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Resposta"}}}},"429":{"description":"Limite diário ou de requisições atingido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/v1/produtos/lote":{"post":{"summary":"Consulta até 100 produtos de uma vez","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["gtins"],"properties":{"gtins":{"type":"array","maxItems":100,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Cada item responde por si; um código problemático não derruba os outros.","content":{"application/json":{"schema":{"type":"object","properties":{"itens":{"type":"array","items":{"$ref":"#/components/schemas/Resposta"}},"recusados":{"type":"integer","description":"Quantos não couberam no plano."}}}}}}}}},"/v1/sincronizar":{"post":{"summary":"Baixa o catálogo para a base local do ERP","description":"Sem `desde`, devolve tudo. Com `desde`, só o que mudou. NUNCA consulta fonte externa: lê apenas a base própria.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["gtins"],"properties":{"gtins":{"type":"array","maxItems":5000,"items":{"type":"string"}},"desde":{"type":"string","format":"date-time","nullable":true}}}}}},"responses":{"200":{"description":"Catálogo, com as quatro situações separadas.","content":{"application/json":{"schema":{"type":"object","properties":{"sincronizado_em":{"type":"string","format":"date-time"},"incremental":{"type":"boolean"},"itens":{"type":"array","items":{"type":"object"}},"nao_encontrados":{"type":"array","items":{"type":"string"},"description":"NÃO TEMOS o produto. Significa isto e só isto."},"recusados":{"type":"array","items":{"type":"string"},"description":"Temos, mas o plano acabou. NÃO apague do catálogo local."},"codigos_internos":{"type":"array","items":{"type":"object"}},"resumo":{"type":"object"}}}}}}}}},"/v1/privados/{codigo}":{"get":{"summary":"Produto privado da conta ou loja vinculada à credencial","description":"Separado da base compartilhada. A credencial de loja fixa o CNPJ; a credencial principal pode usar X-Cliente-CNPJ de loja cadastrada. Sem header, usa a conta principal.","parameters":[{"name":"codigo","in":"path","required":true,"schema":{"type":"string","maxLength":60}},{"name":"X-Cliente-CNPJ","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"Código, descrição, versão e foto_path autenticado","content":{"application/json":{"schema":{"type":"object","properties":{"codigo":{"type":"string"},"descricao":{"type":"string"},"tem_foto":{"type":"boolean"},"versao":{"type":"integer"},"origem":{"type":"string"},"foto_path":{"type":"string","nullable":true}}}}}},"401":{"description":"Credencial ausente ou inválida"},"403":{"description":"Loja não vinculada à credencial"},"404":{"description":"Produto privado não encontrado"}}}},"/v1/privados/{codigo}/foto":{"get":{"summary":"Foto privada autenticada em WebP","parameters":[{"name":"codigo","in":"path","required":true,"schema":{"type":"string","maxLength":60}},{"name":"X-Cliente-CNPJ","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"Foto privada; no-store, sem URL pública","content":{"image/webp":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Credencial ausente ou inválida"},"403":{"description":"Outra loja"},"404":{"description":"Foto não encontrada"}}}},"/v1/saude":{"get":{"summary":"Estado do serviço e tamanho do acervo","security":[],"responses":{"200":{"description":"ok"}}}}}}