Manual do SDK de autocomplete para prescrição

O SDK adiciona sugestões de medicamentos da base Anvisa + CMED dentro de qualquer campo de texto, textarea ou receituário multilinhas do seu sistema. É um arquivo único de ~8 KB, em JavaScript puro, sem dependências — funciona com React, Vue, Angular, PHP ou HTML estático. Exclusivo para assinantes (planos pagos).

1. Instalação

Inclua o script e chame MedAutocomplete.attach(seletor, opções). O seletor aceita qualquer seletor CSS (id, classe ou atributo) e pode ser usado em vários campos de uma vez.

<script src="https://SEU-DOMINIO/sdk/autocomplete.js"></script>
<script>
  MedAutocomplete.attach('#prescricao', {
    apiKey: 'sua_chave_aqui', // chave de plano pago (Starter ou superior)
    onSelect: function (item) {
      console.log('Selecionado:', item.id, item.titulo);
    }
  });
</script>

Substitua SEU-DOMINIO pelo domínio da API informado no painel do assinante. A área de teste na página para desenvolvedores funciona sem chave, apenas dentro do nosso site.

2. Opções

Opção	Tipo	Padrão	Descrição
apiKey	string	—	Chave de plano pago (obrigatória fora do nosso site). Sem ela, a API responde 401/403.
limit	number	8	Quantidade de sugestões exibidas (1 a 15).
minChars	number	2	Mínimo de caracteres digitados para disparar a busca.
debounce	number	250	Espera em milissegundos após a última tecla antes de buscar. Evita uma requisição por letra.
types	array	todos	Tipos retornados: `apresentacao`, `principio_ativo` e/ou `fabricante`.
sort	string	relevancia	`popularidade` coloca primeiro os medicamentos mais usados (cliques + visitas dos últimos 90 dias). `relevancia` mantém a ordem por similaridade com o texto digitado.
fields	array	principio_ativo_dose, subtitulo, descricao	Campos exibidos na linha secundária de cada sugestão. Repetidos são removidos automaticamente.
format	string \| function	padrão do SDK	Texto gravado no campo ao escolher. Aceita placeholders como `{titulo}` e `{principio_ativo_dose}`, ou uma função que recebe o item.
showPrice	boolean	true	Mostra o menor preço CMED (PMC) na sugestão, quando disponível.
showFooter	boolean	true	Mostra o rodapé de crédito da base de dados.
theme	object	—	Personalização visual: `accent` (cor de destaque) e `fontSize`.
renderItem	function	—	Renderização totalmente customizada de cada sugestão (ver seção 5).
onSelect	function	—	Chamado ao escolher uma sugestão: recebe `(item, elemento)`.
onError	function	—	Chamado em falhas de rede, chave inválida ou cota excedida.
baseUrl	string	domínio oficial	Endpoint alternativo da API (uso interno/homologação).

MedAutocomplete.attach('#prescricao', {
  apiKey: 'sua_chave_aqui',
  limit: 8,                    // quantidade de sugestões (1 a 15)
  minChars: 2,                 // mínimo de caracteres para buscar
  debounce: 250,               // espera em ms após parar de digitar
  types: ['apresentacao'],     // apresentacao | principio_ativo | fabricante
  sort: 'popularidade',        // 'popularidade' ou 'relevancia' (padrão)
  fields: ['principio_ativo_dose', 'subtitulo', 'descricao'],
  format: '{titulo} — {principio_ativo_dose}',
  showPrice: true,
  theme: { accent: '#2563eb', fontSize: '14px' },
  onSelect: function (item, el) {},
  onError: function (err) {}
});

3. O objeto do item selecionado

Cada sugestão carrega os dados completos do registro, disponíveis no onSelect:

Campo	Conteúdo
tipo	apresentacao, principio_ativo ou fabricante
id / slug	Identificador estável para gravar no seu banco
titulo	Nome principal exibido (ex.: nome comercial ou princípio ativo)
subtitulo	Complemento (ex.: fabricante ou forma farmacêutica)
nome_comercial	Nome de marca, quando houver
principio_ativo_dose	Princípio ativo com concentração (ex.: dipirona monoidratada 1g)
descricao	Descrição regulatória da apresentação
forma_farmaceutica	Comprimido, solução oral, cápsula etc.
categoria_regulatoria	Genérico, Similar, Referência, Biológico etc.
menor_pmc	Menor Preço Máximo ao Consumidor vigente (número)
url	Link da ficha completa no site

4. Eventos

Além do callback onSelect, o SDK dispara o evento DOM medautocomplete:select no campo — útil para formulários que já escutam eventos:

document.querySelector('#prescricao').addEventListener('medautocomplete:select', function (e) {
  var item = e.detail;
  // preencher campos ocultos do formulário, por exemplo:
  document.querySelector('#medicamento_id').value = item.id;
  document.querySelector('#medicamento_ean').value = item.ean || '';
});

5. Layout customizado das sugestões

Com renderItem você controla o HTML de cada linha. O segundo argumento traz utilitários: highlight(texto) marca o termo buscado e escape(texto) protege contra HTML injetado.

MedAutocomplete.attach('#prescricao', {
  apiKey: 'sua_chave_aqui',
  renderItem: function (item, h) {
    return '<strong>' + h.highlight(item.titulo) + '</strong>' +
      '<small>' + h.escape(item.subtitulo || '') + '</small>';
  }
});

6. Navegação por teclado e comportamento

Setas ↑ / ↓: percorrem as sugestões.
Tab ou Enter: completam o campo com a sugestão ativa.
Esc: fecha a lista.
Textarea multilinhas: apenas a linha do cursor é substituída — o restante do receituário fica intacto.
Cache no navegador: termos repetidos não geram nova requisição, economizando a cota do plano.
Requisições concorrentes: buscas antigas são canceladas automaticamente quando a digitação continua.

7. Erros e cota

Cada busca feita pelo SDK fora do nosso site consome 1 requisição da cota mensal do plano. Em caso de erro, o callback onError recebe o objeto devolvido pela API:

HTTP	Código	Significado
401	invalid_key	Chave ausente ou inválida
403	plan_required	O SDK exige plano pago (Starter ou superior)
429	quota_exceeded	Cota mensal esgotada — renova no próximo ciclo ou faça upgrade

Pronto para testar?

Experimente o playground ao vivo com personalizador visual e gere o código de instalação automaticamente.

Abrir o playground do SDK →