Pacientes

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 e seguem as mesmas regras de validação — veja Documentos aceitos por país.

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.

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). internalCode é opcional. É o seu próprio identificador para o paciente, único dentro da sua instituição. Envie-o ao criar e depois consulte o paciente ou liste suas sessões por esse código. Reenviar o mesmo documento nacional atualiza o paciente em vez de duplicá-lo. Omitir internalCode mantém qualquer valor já armazenado.

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",
    "internalCode": "EMR-12345"
  }'

Resposta:

{
  "id": "sp_a1b2c3d4e5f6g7h8",
  "name": "John Doe",
  "idCountry": "COLOMBIA",
  "idType": "CC",
  "idValue": "1024567890",
  "internalCode": "EMR-12345",
  "createdAt": "2026-07-01T12:00:00.000Z"
}

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.

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

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

Resposta:

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

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.

Consultar um paciente

GET /v1/patients/{patient_id} busca um único paciente. O {patient_id} pode ser o id público (sp_...) ou o internalCode que você definiu para a sua instituição. Retorna 404 se nenhum paciente com esse id for visível para sua chave.

curl https://scribe-api.telepatia.ai/v1/patients/sp_a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer YOUR_API_KEY"

Resposta:

{
  "id": "sp_a1b2c3d4e5f6g7h8",
  "name": "John Doe",
  "idCountry": "COLOMBIA",
  "idType": "CC",
  "idValue": "1024567890",
  "internalCode": "EMR-12345",
  "createdAt": "2026-07-01T12:00:00.000Z"
}

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

Atualizar um paciente

PATCH /v1/patients/{patient_id} atualiza o name ou o internalCode de um paciente, pelo seu id público (sp_...) ou internalCode. A identidade nacional (idCountry/idType/idValue) não é editável aqui. Omita um campo para deixá-lo sem alteração; envie internalCode como null para limpá-lo. Retorna 404 se nenhum paciente com esse id for visível para sua chave, e 409 se o internalCode já for usado por outro paciente da sua instituição.

curl -X PATCH https://scribe-api.telepatia.ai/v1/patients/sp_a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "internalCode": "EMR-99999"
  }'

Resposta:

{
  "id": "sp_a1b2c3d4e5f6g7h8",
  "name": "Jane Doe",
  "idCountry": "COLOMBIA",
  "idType": "CC",
  "idValue": "1024567890",
  "internalCode": "EMR-99999",
  "createdAt": "2026-07-01T12:00:00.000Z"
}

Excluir um paciente

DELETE /v1/patients/{patient_id} exclui um paciente pelo seu id público (sp_...) ou internalCode. Use para solicitações de direito ao esquecimento. Retorna 204 em caso de sucesso, e 404 se nenhum paciente com esse id for visível para sua chave.

curl -X DELETE https://scribe-api.telepatia.ai/v1/patients/sp_a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer YOUR_API_KEY"

Uma exclusão bem-sucedida retorna 204 com um corpo vazio. Um paciente excluído não aparece mais nos endpoints de lista ou consulta.

Primeiros passos

Conceitos principais

Contas e pacientes

Referência

Criar um paciente

Listar pacientes

Consultar um paciente

Atualizar um paciente

Excluir um paciente

​Criar um paciente

​Listar pacientes

​Consultar um paciente

​Atualizar um paciente

​Excluir um paciente

Criar um paciente

Listar pacientes

Consultar um paciente

Atualizar um paciente

Excluir um paciente