Farmabook API

Catalogo publico consistente entre API, web e busca.

A API continua simples: PostgreSQL como source of truth, Meilisearch como indice rebuildavel e contratos mais estaveis para descoberta, lookup exato e enriquecimento ANVISA.

Base canonica: /* Catalogo publico: cmedAtiva = true ANVISA publica: anvisaAtiva != false

Politica Publica

Os endpoints de descoberta usam sempre o mesmo recorte:

  • cmedAtiva = true
  • anvisaAtiva = true ou null
  • anvisaAtiva = null significa "nao confirmado ainda", nao "fora do catalogo"

Arquitetura Mantida

  • PostgreSQL segue como source of truth.
  • Meilisearch segue rebuildavel via reindex full + swap.
  • Bun + Hono + Drizzle seguem como stack principal.
  • O foco atual e consistencia e contrato, nao rewrite.

Endpoints Principais

GET /search

Busca full-text com filtros de primeira classe e semantica publica canonica.

GET /medications

Listagem paginada do catalogo publico com slugs estaveis para tipoProduto e tarja.

GET /medications/:ggrem

Lookup exato enriquecido com bloco registration quando existe correspondencia em anvisa_registrations.

GET /registrations/:numeroRegistro

Aceita 9 ou 13 digitos e normaliza internamente para o numero de registro ANVISA.

POST /bulk/ean

Lookup bulk com o mesmo DTO de medication usado no restante da API.

Search

Param Tipo Notas
q string Termo livre.
tipoProduto slug Ex.: generico, biologico.
tarja slug Ex.: tarja-vermelha, sem-tarja.
restricaoHospitalar boolean true ou false.
tarjaInferida boolean Filtra correcoes inferidas.
classeTerapeutica, formaFarmaceutica, viaAdministracao string Filtro exato no indice.
sort string Ex.: produto:asc, precoConsumidor:desc.
filter string Escape hatch avancado; campos internos como cmedAtiva nao sao aceitos. 
curl -H "Authorization: Bearer $API_KEY" \
"http://localhost:3333/search?q=dipirona&tipoProduto=generico&tarja=tarja-vermelha&sort=precoConsumidor:asc"

Slugs Estaveis

tipoProduto

novo, biologico, generico, similar, especifico, fitoterapico, terapia-avancada, radiofarmaco

tarja

sem-tarja, tarja-vermelha, tarja-vermelha-sob-restricao, tarja-preta

Erros

Formato padrao em toda a API:

{
  "error": "Human readable message",
  "code": "MACHINE_READABLE_CODE",
  "details": {}
}

Health e Operacao

/stats representa o catalogo publico. /health representa estado operacional bruto e paridade entre PostgreSQL e Meilisearch. 

{
  "status": "ok",
  "search": "available",
  "database": "available",
  "index": {
    "numberOfDocuments": 13447,
    "isIndexing": false
  },
  "postgres": {
    "medications": 13447
  }
}

O script scripts/verify-production-api.sh valida essa paridade e roda smoke checks leves apos deploy e sync.

First-Party Search

A UX instantanea do produto continua consultando Meilisearch direto no frontend, mas agora com o mesmo filtro publico da API. O esperado para NEXT_PUBLIC_MEILI_SEARCH_KEY e escopo estritamente search/read do indice publico.