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.
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).
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: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.
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.
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:
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 seuid (acc_*) ou pelo seu próprio internalCode.
Atualizar uma conta
Altere uma conta comPATCH /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.
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:
Regenerar uma chave de API
Rotacione a chave API de uma conta comPOST /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.