> ## 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.

# Consultas

> Configurar o contexto do paciente antes de uma sessão de scribe

A chamada de contexto de consulta envia a identidade e informações clínicas do paciente pra Telepatia antes de uma sessão começar. A Telepatia usa esses dados pra pré-preencher o registro do paciente na interface do scribe e vincular a sessão concluída de volta ao seu sistema.

Chame esse endpoint **antes** de gerar um link de login. Se omitir, a sessão de scribe iniciará sem contexto do paciente.

## Campos principais

| Campo                          | Obrigatório | Descrição                                                                                                                                                                                                       |
| ------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `consultationInternalId`       | Não         | Seu ID interno pra essa consulta. Se omitido, a Telepatia gera um. Usado pra recuperar a sessão depois.                                                                                                         |
| `name`                         | Condicional | Nome completo do paciente. Obrigatório a menos que `patientId` seja enviado.                                                                                                                                    |
| `idCountry`                    | Condicional | País do documento de identidade (ISO alfa-2, alfa-3 ou nome completo). Obrigatório a menos que `patientId` seja enviado.                                                                                        |
| `idType`                       | Condicional | Tipo de documento de identidade (veja tabela abaixo). Obrigatório a menos que `patientId` seja enviado.                                                                                                         |
| `idValue`                      | Condicional | Número do documento. Obrigatório a menos que `patientId` seja enviado.                                                                                                                                          |
| `patientId`                    | Condicional | ID público de um paciente existente (`sp_...`, de [Pacientes](/pt-BR/scribe-api/patients)). Use no lugar dos campos de identidade inline. Mutuamente exclusivo com `name` / `idCountry` / `idType` / `idValue`. |
| `medicalRecordConfiguration`   | Não         | **Smart Template inline (recomendado).** JSON completo; o servidor deduplica por hash de conteúdo. Veja [Smart Templates](/pt-BR/scribe-api/smart-templates).                                                   |
| `medicalRecordConfigurationId` | Não         | Smart Template por id (de `/v1/medical-record-configurations`).                                                                                                                                                 |
| `scribeSessionConfigurationId` | Não         | ID de Template de Sessão legado (de `/v1/scribe-session-configurations`).                                                                                                                                       |
| `scribeSessionModality`        | Não         | `IN_PERSON` ou `TELEMEDICINE`                                                                                                                                                                                   |
| `notes`                        | Não         | Notas clínicas em texto livre visíveis pro médico                                                                                                                                                               |
| `pastMedicalHistory`           | Não         | Histórico médico do paciente                                                                                                                                                                                    |

<Note>
  Identifique o paciente **ou** com os campos inline (`name`, `idCountry`, `idType`, `idValue`) **ou** com `patientId` — nunca ambos. Referenciar um paciente existente por `patientId` reutiliza a identidade armazenada, então você evita reenviá-la e nunca cria um duplicado. Enviar ambos, ou uma identidade inline incompleta sem `patientId`, retorna um erro `400`.
</Note>

## Documentos aceitos por país

| País          | `idCountry`               | Documento             | `idType`    | Formato                   |
| ------------- | ------------------------- | --------------------- | ----------- | ------------------------- |
| Colômbia      | `CO` / `COL` / `COLOMBIA` | Cédula de Ciudadanía  | `CC`        | 8–10 dígitos              |
| Colômbia      |                           | Tarjeta de Identidad  | `TI`        | 10–11 dígitos             |
| Colômbia      |                           | Cédula de Extranjería | `CE`        | 6–7 dígitos               |
| Colômbia      |                           | Registro Civil        | `RC`        | 1–11 dígitos              |
| Brasil        | `BR` / `BRA` / `BRAZIL`   | Registro Geral        | `RG`        | 7–9 alfanumérico          |
| Brasil        |                           | CPF                   | `CPF`       | XXX.XXX.XXX-XX            |
| Qualquer país | —                         | Passaporte            | `PASSPORT`  | 6–9 alfanumérico          |
| Qualquer país | —                         | Outro                 | `OTHER_DOC` | Qualquer string não vazia |

<Note>
  O `idType` precisa ser válido pro `idCountry` informado. Por exemplo, enviar `CC` com `idCountry: BR` retorna um erro `400`.
</Note>

## Templates: passe exatamente um

`medicalRecordConfiguration`, `medicalRecordConfigurationId` e `scribeSessionConfigurationId` são **mutuamente exclusivos** — passe no máximo um. Recomendamos a forma inline `medicalRecordConfiguration`: é reproduzível, permite versionar o template junto com o seu código, e o servidor deduplica por hash de conteúdo para você não acumular duplicatas.

## Exemplo de requisição — Smart Template inline (recomendado)

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/set-consultation-context \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "consultationInternalId": "CONSULT-12345",
    "name": "John Doe",
    "idCountry": "CO",
    "idType": "CC",
    "idValue": "123456789",
    "notes": "Paciente relata dor de cabeça recorrente",
    "pastMedicalHistory": "Hipertensão diagnosticada em 2020",
    "scribeSessionModality": "IN_PERSON",
    "medicalRecordConfiguration": {
      "chiefComplaint": {
        "instructionSet": { "telepatiaPromptId": "CHIEF_COMPLAINT" },
        "schema": {
          "type": "object",
          "instructions": "Chief complaint",
          "properties": {
            "chiefComplaint": { "type": "string", "instructions": "Patient words" }
          }
        }
      }
    }
  }'
```

## Exemplo de requisição — Smart Template por id

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/set-consultation-context \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "consultationInternalId": "CONSULT-12345",
    "name": "John Doe",
    "idCountry": "CO",
    "idType": "CC",
    "idValue": "123456789",
    "scribeSessionModality": "IN_PERSON",
    "medicalRecordConfigurationId": "mrc_a1b2c3d4e5f6g7h8"
  }'
```

## Exemplo de requisição — referenciar um paciente existente

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/set-consultation-context \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "consultationInternalId": "CONSULT-12345",
    "patientId": "sp_a1b2c3d4e5f6g7h8",
    "scribeSessionModality": "IN_PERSON"
  }'
```

**Resposta:**

```json theme={null}
{
  "success": true,
  "consultationInternalId": "CONSULT-12345"
}
```

<Tip>
  Guarde o `consultationInternalId` — você vai precisar dele pra gerar o link de login e recuperar os resultados da sessão.
</Tip>