Pular para o conteúdo principal
O gerenciamento de contas só está disponível com uma chave API institucional. Chaves API de nível médico não têm acesso a esses endpoints.
Chaves API institucionais podem criar e recuperar contas de médicos dentro da sua organização. Cada conta representa um médico que pode usar o scribe da Telepatia através da sua integração. Criar uma conta gera duas chaves pra essa conta — uma chave secreta (sk_…) para as chamadas de API do lado do servidor e uma chave publicável (pk_…) para o embed de navegador (veja Tipos de chave). Você pode rotacionar a chave secreta depois.

Criar uma conta

POST /v1/institutional/accounts exige email e doctorSpecialties. Opcionalmente, envie apiKeyConfig.validForDays (1–365) pra controlar por quanto tempo a chave API gerada permanece válida; omita pra usar o padrão de 365 dias (1 ano).
Resposta:
apiKey (secreta) e publishableApiKey (publicável) são retornadas apenas uma vez — guarde-as com segurança. expiresAt é o timestamp UTC em que as chaves param de funcionar, e apiKeyExpiresInDays reflete a validade que foi aplicada. Use a chave secreta para as chamadas de API do lado do servidor; a chave publicável é para o embed de navegador e não pode chamar a API diretamente.
Guarde o id (ou o seu internalCode) — você pode usar qualquer um dos dois pra recuperar a conta depois.

Atribuir uma filial

Para colocar o médico em uma filial, envie um destes campos ao criar a conta:
Se você enviar os dois campos, eles precisam identificar a mesma filial. Se identificarem filiais diferentes, a requisição falha com 400 parameter_invalid e param é institutionalBranchId. Um institutionalBranchId que não seja o id de uma filial da sua instituição falha da mesma forma. Obtenha os ids e os nomes com GET /v1/institutional/branches. Este endpoint exige uma chave de API institucional; uma chave de API de médico recebe 403 permission_denied.
Resposta:
Cada item tem apenas o id e o name da filial. A lista inclui as filiais ocultas. A lista é paginada com page e limit (1–100); total é o número de filiais que você pode referenciar (uma filial antiga sem nome não é contada). O id não muda quando a filial é renomeada, e é o id que POST /v1/institutional/branches retorna. Use o id de uma filial como institutionalBranchId ao criar uma conta ou ao definir o contexto da consulta. Uma filial antiga, criada antes de existirem ids de filial, tem id: null. Refira-se a essa filial pelo seu name. Para adicionar uma filial, use POST /v1/institutional/branches.

Criar contas em lote

POST /v1/institutional/accounts/batch cria várias contas de médicos em uma única chamada. Envie um arranjo accounts. Cada item usa os mesmos campos de uma criação individual. O lote aceita no máximo 10 contas. O endpoint rejeita a requisição inteira com 400 antes de criar qualquer conta quando o lote repete um email ou um internalCode.
O endpoint cria cada conta separadamente. Uma conta pode ter sucesso enquanto outra falha. O endpoint não desfaz. Ele retorna 200 com um arranjo results. Cada entrada informa o resultado de uma conta, na ordem em que você as enviou. Se um item tiver um institutionalBranchId que não identifica uma filial da sua instituição, somente esse item falha; os demais continuam. Resposta:
Cada conta criada retorna a sua apiKey e a sua publishableApiKey apenas uma vez. Guarde as chaves de cada entrada created antes de ler a próxima resposta.
Leia createdCount e failedCount para um total rápido. Use status em cada entrada para encontrar as contas que falharam.

Recuperar uma conta

Busque uma conta pelo seu id (acc_*) ou pelo seu próprio internalCode.
Resposta:

Atualizar uma conta

Altere uma conta com PATCH /v1/institutional/accounts/{account_id}, identificando-a pelo seu id (acc_*) ou internalCode. Envie apenas os campos que deseja alterar:
  • nameFull: o nome completo do médico.
  • doctorSpecialties: a nova lista de especialidades. Ela substitui a lista salva.
  • internalCode: o código da sua instituição para a conta.
Qualquer outro campo, como email, é rejeitado com 400. O endpoint requer uma chave de API institucional com permissão de escrita. Use-o para adicionar o seu internalCode às contas que não têm um, por exemplo médicos que entraram por convite antes da sua integração. Encontre o id da conta com GET /v1/institutional/accounts e depois defina o código:
Resposta: a conta atualizada, no mesmo formato de Recuperar uma conta.
O internalCode é definido uma única vez. A Telepatia o usa para encontrar o médico nos seus sistemas, por isso ele não pode ser alterado nem removido pela API. Enviar novamente o valor salvo não altera nada. Um valor diferente retorna 409 resource_conflict com param: "internalCode"; entre em contato com o suporte da Telepatia para alterar um código salvo. Um código que outra conta ou um convite pendente da sua instituição já usa também retorna 409. Um convite pendente não aparece em GET /v1/institutional/accounts até o médico aceitá-lo.

Regenerar uma chave de API

Rotacione a chave API de uma conta com POST /v1/institutional/accounts/{account_id}/api-keys/regenerate, identificando a conta pelo seu id (acc_*) ou internalCode. Opcionalmente, envie validForDays (1–365) pra definir a validade da nova chave; omita pra manter o padrão da conta.
Resposta:
Regenerar revoga a chave anterior (após um breve período de carência) e retorna a nova apiKey sem criptografia uma única vez — atualize sua integração antes que o período de carência termine. A chave publicável também é rotacionada: a chave pk_ anterior é revogada da mesma forma e a nova é retornada uma única vez como publishableApiKey. A regeneração é limitada a uma por conta a cada 2 minutos; exceder esse limite retorna 429 rate_limit_exceeded. Veja Tratamento de erros.