> For the complete documentation index, see [llms.txt](https://docs.voa.health/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voa.health/integracao/rnds/endpoints.md).

# Endpoints

### Base URL <a href="#base-url" id="base-url"></a>

```
https://integration.voa.health/v1
```

Todos os endpoints RNDS exigem autenticação via token Bearer JWT, da mesma forma que os demais endpoints da API Voa.

```sh
Authorization: Bearer <seu_token_jwt>
```

***

## Enviar registro clínico à RNDS

<mark style="color:green;">`POST`</mark> `/ehrs/{ehr_id}/rnds/submit`

Envia os dados clínicos de uma consulta à RNDS no padrão FHIR R4. A Voa monta automaticamente o Bundle FHIR com todos os recursos necessários (Composition, Encounter, Condition, Procedure, MedicationRequest, etc.) a partir dos documentos e dados da consulta.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| Name               | Type   | Description                                                                       |
| ------------------ | ------ | --------------------------------------------------------------------------------- |
| `document_type`    | string | Tipo do documento RNDS: `RAC`, `RPM`, `REL` (default: `RAC`)                      |
| `patient_cpf`      | string | CPF do paciente (obrigatório)                                                     |
| `patient_cns`      | string | CNS do paciente (opcional, usado quando disponível)                               |
| `practitioner_cns` | string | CNS do profissional de saúde responsável (obrigatório)                            |
| `cnes`             | string | Código CNES do estabelecimento (obrigatório na primeira vez, depois é memorizado) |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": "submitted",
  "rnds_record_id": "rnds_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "document_type": "RAC",
  "submitted_at": "2026-02-18T15:00:00Z",
  "ehr_id": "ehr_123456"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "validation_error",
  "message": "O campo patient_cpf é obrigatório para envio à RNDS",
  "details": [
    {
      "field": "patient_cpf",
      "issue": "required"
    }
  ]
}
```

{% endtab %}

{% tab title="422" %}

```json
{
  "error": "rnds_rejected",
  "message": "O registro foi rejeitado pela RNDS",
  "details": [
    {
      "severity": "error",
      "code": "processing",
      "diagnostics": "Identificador do paciente não encontrado no cadastro nacional"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

***

## Consultar status de envio

<mark style="color:green;">`GET`</mark> `/ehrs/{ehr_id}/rnds/status`

Retorna o status do último envio à RNDS para uma consulta específica.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "ehr_id": "ehr_123456",
  "rnds_record_id": "rnds_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "accepted",
  "document_type": "RAC",
  "submitted_at": "2026-02-18T15:00:00Z",
  "last_updated_at": "2026-02-18T15:00:02Z"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "error": "not_found",
  "message": "Nenhum envio à RNDS encontrado para esta consulta"
}
```

{% endtab %}
{% endtabs %}

**Status possíveis**

| Status     | Descrição                                            |
| ---------- | ---------------------------------------------------- |
| `pending`  | Envio em processamento                               |
| `accepted` | Registro aceito pela RNDS                            |
| `rejected` | Registro rejeitado — verifique os detalhes do erro   |
| `replaced` | Registro foi substituído por uma versão mais recente |
| `deleted`  | Registro foi excluído da RNDS                        |

***

## Substituir registro na RNDS

<mark style="color:green;">`PUT`</mark> `/ehrs/{ehr_id}/rnds/replace`

Substitui um registro previamente enviado à RNDS. Útil quando o profissional faz correções no documento clínico após o envio inicial.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| Name               | Type   | Description                                   |
| ------------------ | ------ | --------------------------------------------- |
| `practitioner_cns` | string | CNS do profissional responsável pela correção |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": "replaced",
  "rnds_record_id": "rnds_new-uuid-after-replacement",
  "previous_record_id": "rnds_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "replaced_at": "2026-02-18T16:30:00Z"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "no_previous_submission",
  "message": "Não existe registro anterior na RNDS para esta consulta"
}
```

{% endtab %}
{% endtabs %}

***

## Excluir registro da RNDS

<mark style="color:red;">`DELETE`</mark> `/ehrs/{ehr_id}/rnds`

Remove um registro previamente enviado à RNDS. Esta ação é irreversível no barramento nacional.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| Name               | Type   | Description                                 |
| ------------------ | ------ | ------------------------------------------- |
| `practitioner_cns` | string | CNS do profissional que autoriza a exclusão |
| `reason`           | string | Motivo da exclusão (obrigatório)            |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": "deleted",
  "rnds_record_id": "rnds_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "deleted_at": "2026-02-18T17:00:00Z"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "no_previous_submission",
  "message": "Não existe registro na RNDS para esta consulta"
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
A exclusão de registros na RNDS é uma operação sensível e irreversível. Certifique-se de que a exclusão é realmente necessária antes de executá-la.
{% endhint %}

***

## Consultar paciente na RNDS

<mark style="color:green;">`GET`</mark> `/rnds/patient`

Consulta dados de um paciente no barramento nacional da RNDS.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Query Parameters**

| Name  | Type   | Description                                       |
| ----- | ------ | ------------------------------------------------- |
| `cpf` | string | CPF do paciente (obrigatório se não informar CNS) |
| `cns` | string | CNS do paciente (obrigatório se não informar CPF) |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "patient": {
    "cpf": "123.456.789-00",
    "cns": "700000000000000",
    "name": "Nome do Paciente",
    "birth_date": "1990-05-15",
    "gender": "female"
  }
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "error": "patient_not_found",
  "message": "Paciente não encontrado no cadastro nacional"
}
```

{% endtab %}
{% endtabs %}

***

## Consultar profissional na RNDS

<mark style="color:green;">`GET`</mark> `/rnds/practitioner`

Consulta dados de um profissional de saúde no barramento nacional.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Query Parameters**

| Name  | Type   | Description                                |
| ----- | ------ | ------------------------------------------ |
| `cns` | string | CNS do profissional de saúde (obrigatório) |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "practitioner": {
    "cns": "700000000000001",
    "name": "Dr. Nome do Profissional",
    "specialty": "Clínica Médica",
    "council": "CRM",
    "council_number": "123456",
    "council_state": "MG"
  }
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "error": "practitioner_not_found",
  "message": "Profissional não encontrado no cadastro nacional"
}
```

{% endtab %}
{% endtabs %}

***

### Rate limits <a href="#rate-limit" id="rate-limit"></a>

Os endpoints RNDS seguem os mesmos limites da API Voa:

* 1000 requisições por hora por token
* 10 requisições por segundo por token

{% hint style="info" %}
O envio à RNDS envolve comunicação com o barramento nacional, o que pode adicionar latência de 2 a 5 segundos na resposta. Recomendamos implementar chamadas assíncronas para não bloquear a experiência do usuário.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.voa.health/integracao/rnds/endpoints.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.