# Busca e registros de medicamentos

Busque medicamentos brasileiros por nome, filtre registros e consulte detalhes canônicos com paginação por cursor e evidência.

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

## Busca por nome e filtros

GET /v1/medications/search procura uma substring literal do nome oficial, sem distinção entre maiúsculas e minúsculas. Não é o Resolve: a busca retorna uma lista de registros, sem declarar que uma consulta identifica uma variante única. %, _ e ! não são curingas.

```bash
curl --fail-with-body --get "$IABULA_API_BASE/v1/medications/search" \
  --header "X-API-Key: $IABULA_API_KEY" \
  --data-urlencode 'q=dipirona' \
  --data-urlencode 'limit=20'
```

q aceita de 1 a 256 caracteres quando informado. limit aceita de 1 a 100, com padrão 20. ingredient_id e category_id são UUIDs canônicos. dosage_form é igualdade com a forma canônica, sem distinção de caixa. Filtros dependem de vínculos realmente existentes no catálogo.

## Paginação estável por cursor

Cada página contém data e next_cursor. Passe o cursor recebido sem decodificar ou alterá-lo. O cursor de busca está associado aos filtros; para mudar q ou outro filtro, recomece sem cursor. Cursor inválido ou usado com filtros diferentes resulta em HTTP 400.

```bash
curl --fail-with-body --get "$IABULA_API_BASE/v1/medications/search" \
  --header "X-API-Key: $IABULA_API_KEY" \
  --data-urlencode "q=dipirona" \
  --data-urlencode "cursor=$IABULA_CURSOR"
```

## Identificação exata

GET /v1/medications/lookup aceita scheme EAN, CMED_GGREM ou CMED_REGISTRO e value literal. matched identifica um candidato; ambiguous preserva candidatos separados; unresolved não cria correspondência por nome. Cada candidato traz IDs reutilizáveis e evidência da fonte.

```bash
curl --fail-with-body --get "$IABULA_API_BASE/v1/medications/lookup"   --header "X-API-Key: $IABULA_API_KEY"   --data-urlencode "scheme=EAN"   --data-urlencode "value=7891058021580"
```

## Detalhe pelo UUID retornado

Use um id retornado pela busca em GET /v1/medications/{id}. O detalhe inclui product_id e listas de apresentações, registros, empresas e categorias quando disponíveis. Não invente UUIDs nem deduza um UUID a partir de um nome. Um ID inexistente retorna HTTP 404.

```bash
curl --fail-with-body "$IABULA_API_BASE/v1/medications/$IABULA_MEDICATION_ID" \
  --header "X-API-Key: $IABULA_API_KEY"
```

## Interprete os campos com evidência

product_name, brand_name, dosage_form e active_ingredient_text têm semânticas distintas. Campos sem mapeamento podem ser nulos. active_ingredient_text conserva texto da fonte e não prova um vínculo a ActiveIngredient. Categorias regulatórias não são indicações clínicas.

- [Proveniência](https://iabula.com/docs/provenance)
- [Search versus Resolve](https://iabula.com/docs/resolve)
- [Guia de busca por nome](https://iabula.com/docs/guides/buscar-medicamento-por-nome)

## GET /v1/medications/search

| Parâmetro | Local | Obrigatório | Tipo e limites |
| --- | --- | --- | --- |
| q | query | no | string; minLength=1, maxLength=256 \| null |
| ingredient_id | query | no | string (uuid) \| null |
| dosage_form | query | no | string; minLength=1, maxLength=100 \| null |
| category_id | query | no | string (uuid) \| null |
| identifier_scheme | query | no | string: EAN, CMED_GGREM, CMED_REGISTRO \| null |
| identifier_value | query | no | string; minLength=1, maxLength=64 \| null |
| expand | query | no | string: catalog_context \| null |
| limit | query | no | integer; minimum=1, maximum=100, default=20 |
| cursor | query | no | string; maxLength=2048 \| null |

| HTTP | Content-Type | Schema |
| --- | --- | --- |
| 200 | application/json | MedicationPage |
| 400 | application/json | Problem |
| 401 | application/json | Problem |
| 403 | application/json | Problem |
| 429 | application/json | Problem |
| 500 | application/json | Problem |
| 503 | application/json | Problem |
| 422 | application/json | HTTPValidationError |

## GET /v1/medications/lookup

| Parâmetro | Local | Obrigatório | Tipo e limites |
| --- | --- | --- | --- |
| scheme | query | yes | string: EAN, CMED_GGREM, CMED_REGISTRO |
| value | query | yes | string; minLength=1, maxLength=64 |

| HTTP | Content-Type | Schema |
| --- | --- | --- |
| 200 | application/json | IdentifierLookup |
| 400 | application/json | Problem |
| 401 | application/json | Problem |
| 403 | application/json | Problem |
| 429 | application/json | Problem |
| 500 | application/json | Problem |
| 503 | application/json | Problem |
| 422 | application/json | HTTPValidationError |

## GET /v1/medications/{id}

| Parâmetro | Local | Obrigatório | Tipo e limites |
| --- | --- | --- | --- |
| id | path | yes | string (uuid) |

| HTTP | Content-Type | Schema |
| --- | --- | --- |
| 200 | application/json | MedicationDetail |
| 400 | application/json | Problem |
| 401 | application/json | Problem |
| 403 | application/json | Problem |
| 429 | application/json | Problem |
| 500 | application/json | Problem |
| 503 | application/json | Problem |
| 404 | application/json | Problem |
| 422 | application/json | HTTPValidationError |

## Campos do contrato OpenAPI

| Schema.campo | Tipo e limites | Obrigatório |
| --- | --- | --- |
| CatalogContext.source_substances | array<SupportedSourceValue> | yes |
| CatalogContext.source_laboratories | array<SupportedSourceValue> | yes |
| CatalogContext.source_identifiers | array<SupportedSourceIdentifier> | yes |
| CatalogContext.variants | array<CatalogVariant> | yes |
| CatalogIngredient.id | string (uuid) | yes |
| CatalogIngredient.name | string | yes |
| CatalogIngredient.role | string \| null | no |
| CatalogIngredient.amount_text | string \| null | no |
| CatalogIngredient.evidence | array<Evidence> | yes |
| CatalogPresentation.id | string (uuid) | yes |
| CatalogPresentation.strength | string \| null | no |
| CatalogPresentation.unit_count | integer \| null | no |
| CatalogPresentation.package_description | string \| null | no |
| CatalogPresentation.identifiers | array<SupportedSourceIdentifier> | yes |
| CatalogPresentation.evidence | array<Evidence> | yes |
| CatalogPreview.source_substances | array<string> | yes |
| CatalogPreview.source_laboratories | array<string> | yes |
| CatalogPreview.cmed_registrations | array<string> | yes |
| CatalogPreview.has_multiple_source_values | boolean | yes |
| CatalogPreview.source_values_truncated | boolean | yes |
| CatalogPreview.presentation_count | integer | yes |
| CatalogPreview.presentations | array<CatalogPreviewPresentation> | yes |
| CatalogPreviewPresentation.id | string (uuid) | yes |
| CatalogPreviewPresentation.variant_id | string (uuid) | yes |
| CatalogPreviewPresentation.dosage_form | string \| null | no |
| CatalogPreviewPresentation.strength | string \| null | no |
| CatalogPreviewPresentation.unit_count | integer \| null | no |
| CatalogPreviewPresentation.package_description | string \| null | no |
| CatalogPreviewPresentation.ggrem | array<string> | yes |
| CatalogPreviewPresentation.eans | array<string> | yes |
| CatalogPreviewPresentation.matches_identifier | boolean | yes |
| CatalogVariant.id | string (uuid) | yes |
| CatalogVariant.dosage_form | string \| null | no |
| CatalogVariant.evidence | array<Evidence> | yes |
| CatalogVariant.ingredients | array<CatalogIngredient> | yes |
| CatalogVariant.presentations | array<CatalogPresentation> | yes |
| CategoryDetail.id | string (uuid) | yes |
| CategoryDetail.vocabulary_name | string | yes |
| CategoryDetail.code | string \| null | no |
| CategoryDetail.name | string | yes |
| CategoryDetail.evidence | array<Evidence> | yes |
| CompanyDetail.id | string (uuid) | yes |
| CompanyDetail.official_name | string | yes |
| CompanyDetail.registry_identifier | string \| null | no |
| CompanyDetail.evidence | array<Evidence> | yes |
| Evidence.class | string | yes |
| Evidence.source | string \| null | no |
| Evidence.dataset | string \| null | no |
| Evidence.retrieved_at | string (date-time) \| null | no |
| Evidence.source_version | string \| null | no |
| Evidence.source_record_id | string \| null | no |
| Evidence.source_run_id | string \| null | no |
| Evidence.attribute | string \| null | no |
| Evidence.rule_version | string \| null | no |
| HTTPValidationError.detail | array<ValidationError> | no |
| IdentifierCandidate.product_id | string (uuid) | yes |
| IdentifierCandidate.product_name | string | yes |
| IdentifierCandidate.variant_id | string (uuid) \| null | no |
| IdentifierCandidate.dosage_form | string \| null | no |
| IdentifierCandidate.presentation_id | string (uuid) \| null | no |
| IdentifierCandidate.strength | string \| null | no |
| IdentifierCandidate.package_description | string \| null | no |
| IdentifierCandidate.evidence | array<Evidence> | yes |
| IdentifierLookup.status | string: matched, ambiguous, unresolved | yes |
| IdentifierLookup.scheme | string: EAN, CMED_GGREM, CMED_REGISTRO | yes |
| IdentifierLookup.value | string | yes |
| IdentifierLookup.candidates | array<IdentifierCandidate> | yes |
| IdentifierLookup.reason | string: no_exact_match, multiple_exact_matches \| null | no |
| MedicationDetail.id | string (uuid) | yes |
| MedicationDetail.product_name | string | yes |
| MedicationDetail.brand_name | string \| null | no |
| MedicationDetail.dosage_form | string \| null | no |
| MedicationDetail.active_ingredient_text | string \| null | no |
| MedicationDetail.evidence | array<Evidence> | yes |
| MedicationDetail.catalog_context | CatalogContext \| null | no |
| MedicationDetail.identity_preview | CatalogPreview \| null | no |
| MedicationDetail.product_id | string (uuid) | yes |
| MedicationDetail.presentations | array<PresentationDetail> | yes |
| MedicationDetail.registrations | array<RegistrationDetail> | yes |
| MedicationDetail.companies | array<CompanyDetail> | yes |
| MedicationDetail.categories | array<CategoryDetail> | yes |
| MedicationPage.data | array<MedicationSummary> | yes |
| MedicationPage.next_cursor | string \| null | yes |
| MedicationSummary.id | string (uuid) | yes |
| MedicationSummary.product_name | string | yes |
| MedicationSummary.brand_name | string \| null | no |
| MedicationSummary.dosage_form | string \| null | no |
| MedicationSummary.active_ingredient_text | string \| null | no |
| MedicationSummary.evidence | array<Evidence> | yes |
| MedicationSummary.catalog_context | CatalogContext \| null | no |
| MedicationSummary.identity_preview | CatalogPreview \| null | no |
| PresentationDetail.id | string (uuid) | yes |
| PresentationDetail.strength | string \| null | no |
| PresentationDetail.package_description | string \| null | no |
| PresentationDetail.evidence | array<Evidence> | yes |
| 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 |
| RegistrationDetail.id | string (uuid) | yes |
| RegistrationDetail.authority | string | yes |
| RegistrationDetail.registration_number | string | yes |
| RegistrationDetail.status | string \| null | no |
| RegistrationDetail.valid_from | string (date) \| null | no |
| RegistrationDetail.valid_to | string (date) \| null | no |
| RegistrationDetail.valid_to_month | string \| null | no |
| RegistrationDetail.evidence | array<Evidence> | yes |
| SupportedSourceIdentifier.value | string | yes |
| SupportedSourceIdentifier.evidence | array<Evidence> | yes |
| SupportedSourceIdentifier.scheme | string: CMED_REGISTRO, CMED_CNPJ, CMED_GGREM, EAN | yes |
| SupportedSourceValue.value | string | yes |
| SupportedSourceValue.evidence | array<Evidence> | 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)