Contas

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

curl -X POST https://scribe-api.telepatia.ai/v1/institutional/accounts \
  -H "Authorization: Bearer SUA_CHAVE_API_INSTITUCIONAL" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dr.juan@clinica.com",
    "doctorSpecialties": ["cardiology"],
    "nameFull": "Dr. Juan Pérez",
    "internalCode": "DOC-001",
    "apiKeyConfig": { "validForDays": 365 }
  }'

Resposta:

{
  "id": "acc_a1b2c3d4e5f6g7h8",
  "email": "dr.juan@clinica.com",
  "apiKey": "<shown-once-store-securely>",
  "publishableApiKey": "<shown-once-store-securely>",
  "internalCode": "DOC-001",
  "expiresAt": "2027-06-17T00:00:00Z",
  "apiKeyExpiresInDays": 365
}

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.

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.

curl -X POST https://scribe-api.telepatia.ai/v1/institutional/accounts/batch \
  -H "Authorization: Bearer SUA_CHAVE_API_INSTITUCIONAL" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [
      { "email": "dr.juan@clinica.com", "doctorSpecialties": ["cardiology"], "internalCode": "DOC-001" },
      { "email": "dra.ana@clinica.com", "doctorSpecialties": ["pediatrics"], "internalCode": "DOC-002" }
    ]
  }'

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. Resposta:

{
  "results": [
    {
      "index": 0,
      "email": "dr.juan@clinica.com",
      "status": "created",
      "account": {
        "id": "acc_a1b2c3d4e5f6g7h8",
        "email": "dr.juan@clinica.com",
        "apiKey": "<shown-once-store-securely>",
        "publishableApiKey": "<shown-once-store-securely>",
        "internalCode": "DOC-001",
        "expiresAt": "2027-06-17T00:00:00Z",
        "apiKeyExpiresInDays": 365
      },
      "error": null
    },
    {
      "index": 1,
      "email": "dra.ana@clinica.com",
      "status": "error",
      "account": null,
      "error": {
        "type": "invalid_request_error",
        "code": "resource_conflict",
        "message": "An account with this internalCode already exists for this institution.",
        "param": "internalCode"
      }
    }
  ],
  "createdCount": 1,
  "failedCount": 1
}

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.

curl https://scribe-api.telepatia.ai/v1/institutional/accounts/acc_a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer SUA_CHAVE_API_INSTITUCIONAL"

Resposta:

{
  "id": "acc_a1b2c3d4e5f6g7h8",
  "email": "dr.juan@clinica.com",
  "nameFull": "Dr. Juan Pérez",
  "doctorSpecialties": ["CARDIOLOGY"],
  "enabled": true,
  "internalCode": "DOC-001",
  "createdAt": "2024-01-15T10:30:00Z"
}

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.

curl -X POST https://scribe-api.telepatia.ai/v1/institutional/accounts/acc_a1b2c3d4e5f6g7h8/api-keys/regenerate \
  -H "Authorization: Bearer SUA_CHAVE_API_INSTITUCIONAL" \
  -H "Content-Type: application/json" \
  -d '{ "validForDays": 365 }'

Resposta:

{
  "accountId": "acc_a1b2c3d4e5f6g7h8",
  "apiKey": "<shown-once-store-securely>",
  "id": "ak_a1b2c3d4e5f6g7h8",
  "prefix": "sk_prod_a1b2c3d4...e5f6",
  "mode": "prod",
  "expiresAt": "2027-01-15T10:30:00Z"
}

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 regeneração é limitada a uma por conta a cada 2 minutos; exceder esse limite retorna 429 rate_limit_exceeded. Veja Tratamento de erros.

Primeiros passos

Conceitos principais

Contas e pacientes

Referência

Criar uma conta

Criar contas em lote

Recuperar uma conta

Regenerar uma chave de API

​Criar uma conta

​Criar contas em lote

​Recuperar uma conta

​Regenerar uma chave de API

Criar uma conta

Criar contas em lote

Recuperar uma conta

Regenerar uma chave de API