> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telepatia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pacientes

> Crie, liste e consulte pacientes pelo seu id público estável

Pacientes são as pessoas sobre as quais tratam suas sessões de scribe. Crie um paciente uma vez e reutilize seu id público estável (`sp_...`) em todas as consultas, em vez de reenviar os campos de identidade toda vez.

Os campos de identidade (`name`, `idCountry`, `idType`, `idValue`) são os mesmos usados por [set-consultation-context](/pt-BR/scribe-api/consultations) e seguem as mesmas regras de validação — veja [Documentos aceitos por país](/pt-BR/scribe-api/consultations#accepted-documents-by-country).

<Note>
  Os pacientes são **limitados pelo papel da sua chave de API**: uma chave de médico vê apenas os próprios pacientes; uma chave institucional vê todos os pacientes da sua instituição. Você nunca precisa passar um id de conta ou instituição — o escopo é aplicado no servidor.
</Note>

## Criar um paciente

`POST /v1/patients` requer `name`, `idCountry`, `idType` e `idValue`. O `idType` deve ser válido para o `idCountry` informado (ex.: `CC` com `idCountry: BR` retorna `400`).

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/patients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "idCountry": "CO",
    "idType": "CC",
    "idValue": "1024567890"
  }'
```

**Resposta:**

```json theme={null}
{
  "id": "sp_a1b2c3d4e5f6g7h8",
  "name": "John Doe",
  "idCountry": "COLOMBIA",
  "idType": "CC",
  "idValue": "1024567890",
  "createdAt": "2026-07-01T12:00:00.000Z"
}
```

<Tip>
  Guarde o `id` (`sp_...`) — ele é estável e reutilizável. Criar um paciente com um documento de identidade que já existe retorna o paciente existente em vez de um duplicado.
</Tip>

## Listar pacientes

`GET /v1/patients` retorna os pacientes visíveis para sua chave, do mais recente ao mais antigo. Pagine com `page` (base 1) e `limit` (1–50, padrão 20).

```bash theme={null}
curl "https://scribe-api.telepatia.ai/v1/patients?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Resposta:**

```json theme={null}
{
  "items": [
    {
      "id": "sp_a1b2c3d4e5f6g7h8",
      "name": "John Doe",
      "idCountry": "COLOMBIA",
      "idType": "CC",
      "idValue": "1024567890",
      "createdAt": "2026-07-01T12:00:00.000Z"
    }
  ],
  "total": 137,
  "page": 1,
  "limit": 20,
  "totalPages": 7,
  "hasMore": true
}
```

<Note>
  `total` e `totalPages` são calculados apenas na **primeira página** — são `null` nas páginas seguintes para evitar uma varredura completa a cada clique. Use `hasMore` para paginar de forma confiável; ele é preciso em todas as páginas.
</Note>

## Consultar um paciente

`GET /v1/patients/{patient_id}` busca um único paciente pelo seu id público (`sp_...`). Retorna `404` se nenhum paciente com esse id for visível para sua chave.

```bash theme={null}
curl https://scribe-api.telepatia.ai/v1/patients/sp_a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Resposta:**

```json theme={null}
{
  "id": "sp_a1b2c3d4e5f6g7h8",
  "name": "John Doe",
  "idCountry": "COLOMBIA",
  "idType": "CC",
  "idValue": "1024567890",
  "createdAt": "2026-07-01T12:00:00.000Z"
}
```

<Note>
  `idCountry`, `idType` e `idValue` podem ser `null` para pacientes criados fora desta API que não possuem identificação.
</Note>