Pular para o conteúdo principal

Search HS codes by term

GET 
/company/categories/find

Procura correspondências em códigos e descrições de posições (6 dígitos) e subposições (8-10 dígitos) do Sistema Harmonizado. Permite busca livre sem necessidade de conhecer a hierarquia completa.

Objetivo​

Facilitar a busca rápida de códigos HS quando se conhece o nome do produto ou parcialmente o código, sem navegar pela estrutura hierárquica completa.

Casos de uso​

  • Busca por produto: Encontrar o código HS para atum, maquinaria, têxteis
  • Validação de códigos: Verificar se um código existe e obter sua descrição
  • Autocompletar: Sugerir códigos enquanto o usuário digita o nome de um produto
  • Classificação rápida: Encontrar categorias sem explorar toda a hierarquia
  • Integração com inventário: Classificar produtos existentes em um catálogo

Características da busca​

  • Case-insensitive: Não diferencia maiúsculas/minúsculas
  • Correspondência parcial: Procura em títulos (códigos) e descrições (labels)
  • Limite de 40 resultados: 20 posições + 20 subposições
  • Ordenação alfabética: Resultados ordenados por código
  • Múltiplas origens: Procura em coleções de posições e subposições

Fluxo da busca​

flowchart TD
  A[Receber termo] --> B{termo válido?}
  B -->|Não| C[404 USER_NOT_FOUND]
  B -->|Sim| D[Procurar em posições - máx 20]
  D --> E[Procurar em subposições - máx 20]
  E --> F[Combinar resultados]
  F --> G[Ordenar alfabeticamente]
  G --> H[Retornar array]

Notas importantes​

  • Requer autenticação com token JWT de empresa
  • O termo pode vir de query param, path param ou body (extrai-se de todos)
  • O termo é limpo de aspas simples antes de procurar
  • Mínimo de

Request​

Responses​

Códigos HS correspondentes à pesquisa

Response Headers