# Normalização e resolução de nomes farmacêuticos

Integre POST /v1/resolve e trate resolved e unresolved com segurança, sem presumir uma variante única para qualquer nome.

Canonical: https://iabula.com/docs/resolve

## Resolva uma identidade, quando houver evidência

POST /v1/resolve recebe query como string obrigatória de 1 a 512 caracteres. O objetivo é identificar uma MedicationVariant canônica, não escolher um medicamento para um paciente. A API preserva a consulta original no campo query.

```bash
curl --fail-with-body "$IABULA_API_BASE/v1/resolve" \
  --header "X-API-Key: $IABULA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"query":"NATULAXE CAPSULA"}'
```

## Exemplo positivo verificado

NATULAXE CAPSULA foi confirmado como resolved no Hub RapidAPI. Os fatos confirmados são product_name = NATULAXE, entity_type = medication_variant e dosage_form = cápsula. Esta documentação mostra esses fatos sem inventar um UUID ou outros valores de resposta.

Quando status é resolved, resolved contém id, entity_type, product_name, brand_name, dosage_form e active_ingredient_text. brand_name e active_ingredient_text podem ser nulos. O texto de ingrediente não garante vínculo canônico com a tabela de ingredientes.

## Abstenção é um resultado válido

Quando não há evidência suficiente para uma identidade segura, status é unresolved e resolved é null. Ambos os resultados usam HTTP 200. Consultas curtas, ambíguas ou com erros de digitação não têm resolução positiva garantida. Scores, candidatos e motivos internos do gate não são campos públicos.

```javascript
const response = await fetch(`${process.env.IABULA_API_BASE}/v1/resolve`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.IABULA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "NATULAXE CAPSULA" }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.code}`);
if (result.status === "unresolved") {
  // Ask for more source information or route to manual review.
} else {
  console.log(result.resolved.product_name, result.resolved.dosage_form);
}
```

## Separe ausência de correspondência e falha

Um HTTP 503 representa indisponibilidade temporária, não unresolved. Não transforme erros de autenticação, quota ou serviço em ausência de identidade. Uma aplicação deve oferecer revisão manual ou pedir informações adicionais quando houver abstenção.

- [Erros da API](https://iabula.com/docs/errors)
- [Guia de normalização](https://iabula.com/docs/guides/normalizar-nome-de-medicamento)

## POST /v1/resolve

| Campo JSON | Tipo e limites | Obrigatório |
| --- | --- | --- |
| query | string; minLength=1, maxLength=512 | yes |

| HTTP | Content-Type | Schema |
| --- | --- | --- |
| 200 | application/json | ResolveSuccess \| ResolveUnresolved |
| 400 | application/problem+json | Problem |
| 401 | application/problem+json | Problem |
| 403 | application/problem+json | Problem |
| 500 | application/problem+json | Problem |
| 503 | application/problem+json | Problem |
| 429 | application/problem+json | Problem |
| 422 | application/json | HTTPValidationError |

## Campos do contrato OpenAPI

| Schema.campo | Tipo e limites | Obrigatório |
| --- | --- | --- |
| HTTPValidationError.detail | array<ValidationError> | no |
| Problem.type | string | yes |
| Problem.title | string | yes |
| Problem.status | integer | yes |
| Problem.code | string | yes |
| Problem.detail | string \| null | no |
| Problem.request_id | string | yes |
| ResolveRequest.query | string; minLength=1, maxLength=512 | yes |
| ResolveSuccess.status | string: resolved | yes |
| ResolveSuccess.query | string | yes |
| ResolveSuccess.resolved | ResolvedMedicationVariant | yes |
| ResolveUnresolved.status | string: unresolved | yes |
| ResolveUnresolved.query | string | yes |
| ResolveUnresolved.resolved | null | yes |
| ResolvedMedicationVariant.id | string (uuid) | yes |
| ResolvedMedicationVariant.entity_type | string: medication_variant | yes |
| ResolvedMedicationVariant.product_name | string | yes |
| ResolvedMedicationVariant.brand_name | string \| null | yes |
| ResolvedMedicationVariant.dosage_form | string | yes |
| ResolvedMedicationVariant.active_ingredient_text | string \| null | yes |
| ValidationError.loc | array<string \| integer> | yes |
| ValidationError.msg | string | yes |
| ValidationError.type | string | yes |
| ValidationError.input | object | no |
| ValidationError.ctx | object | no |

## Recursos

- [OpenAPI JSON](https://iabula.com/openapi.json)
- [Swagger](https://iabula.com/docs/swagger)
- [Documentation index](https://iabula.com/llms.txt)