Saltar al contenido principal
La gestión de cuentas solo está disponible con una API key institucional. Las API keys de médico no tienen acceso a estos endpoints.
Las API keys institucionales pueden crear y consultar cuentas de médicos dentro de su organización. Cada cuenta representa a un médico que puede usar el scribe de Telepatia a través de tu integración. Al crear una cuenta se generan dos claves para ella: una clave secreta (sk_…) para las llamadas a la API desde el servidor y una clave publicable (pk_…) para el embed en el navegador (consulta Tipos de clave). Más adelante puedes rotar la clave secreta.

Crear una cuenta

POST /v1/institutional/accounts requiere email y doctorSpecialties. Opcionalmente, envía apiKeyConfig.validForDays (1–365) para controlar cuánto tiempo es válida la API key generada; si lo omites, se usa el valor predeterminado de 365 días (1 año).
Respuesta:
apiKey (secreta) y publishableApiKey (publicable) se devuelven solo una vez: guárdalas de forma segura. expiresAt es la fecha y hora UTC en que las claves dejan de funcionar, y apiKeyExpiresInDays repite la vigencia que se aplicó. Usa la clave secreta para las llamadas a la API desde el servidor; la clave publicable es para el embed en el navegador y no puede llamar directamente a la API.
Guarda el id (o tu internalCode): puedes usar cualquiera de los dos para consultar la cuenta más adelante.

Asignar una sede

Para asignar al médico a una sede, envía uno de estos campos al crear la cuenta:
Si envías los dos campos, ambos deben identificar la misma sede. Si identifican sedes distintas, la solicitud falla con 400 parameter_invalid y param es institutionalBranchId. Un institutionalBranchId que no sea el id de una sede de tu institución falla de la misma forma. Obtén los ids y los nombres con GET /v1/institutional/branches. Este endpoint requiere una API key institucional; una API key de médico recibe 403 permission_denied.
Respuesta:
Cada elemento tiene solo el id y el name de la sede. La lista incluye las sedes ocultas. La lista está paginada con page y limit (1–100); total es el número de sedes que puedes referenciar (no cuenta las sedes heredadas sin nombre). El id no cambia cuando se renombra la sede, y es el id que devuelve POST /v1/institutional/branches. Usa el id de una sede como institutionalBranchId al crear una cuenta o al establecer el contexto de la consulta. Una sede heredada, creada antes de que existieran los ids de sede, tiene id: null. Refiérete a esa sede por su name. Para agregar una sede, usa POST /v1/institutional/branches.

Crear cuentas en lote

POST /v1/institutional/accounts/batch crea varias cuentas de médicos en una sola llamada. Envía un array accounts. Cada elemento acepta los mismos campos que una creación individual. El lote admite como máximo 10 cuentas. Si el lote repite un email o un internalCode, el endpoint rechaza toda la solicitud con 400 antes de crear ninguna cuenta.
El endpoint crea cada cuenta por separado. Una cuenta puede tener éxito mientras otra falla. El endpoint no revierte los cambios. Devuelve 200 con un array results. Cada entrada informa el resultado de una cuenta, en el orden en que las enviaste. Si un elemento tiene un institutionalBranchId que no identifica una sede de tu institución, solo ese elemento falla; los demás continúan. Respuesta:
Cada cuenta creada devuelve su apiKey y su publishableApiKey solo una vez. Guarda las claves de cada entrada created antes de leer la siguiente respuesta.
Lee createdCount y failedCount para ver los totales rápidamente. Usa status en cada entrada para encontrar las cuentas que fallaron.

Consultar una cuenta

Busca una cuenta por su id (acc_*) o por tu propio internalCode.
Respuesta:

Actualizar una cuenta

Cambia una cuenta con PATCH /v1/institutional/accounts/{account_id}, e identifícala por su id (acc_*) o su internalCode. Envía solo los campos que quieres cambiar:
  • nameFull: el nombre completo del médico.
  • doctorSpecialties: la nueva lista de especialidades. Reemplaza la lista guardada.
  • internalCode: el código de tu institución para la cuenta.
Cualquier otro campo, como email, se rechaza con 400. El endpoint requiere una API key institucional con permiso de escritura. Úsalo para agregar tu internalCode a las cuentas que no lo tienen, por ejemplo médicos que entraron por invitación antes de tu integración. Busca el id de la cuenta con GET /v1/institutional/accounts y luego define el código:
Respuesta: la cuenta actualizada, con la misma forma que en Consultar una cuenta.
El internalCode se define una sola vez. Telepatia lo usa para encontrar al médico en tus sistemas, por eso no se puede cambiar ni eliminar por la API. Enviar de nuevo el valor guardado no cambia nada. Un valor distinto devuelve 409 resource_conflict con param: "internalCode"; contacta al soporte de Telepatia para cambiar un código guardado. Un código que ya usa otra cuenta o una invitación pendiente de tu institución también devuelve 409. Una invitación pendiente no aparece en GET /v1/institutional/accounts hasta que el médico la acepta.

Regenerar una API key

Rota la API key de una cuenta con POST /v1/institutional/accounts/{account_id}/api-keys/regenerate, identificando la cuenta por su id (acc_*) o su internalCode. Opcionalmente, envía validForDays (1–365) para definir la vigencia de la nueva API key; si lo omites, se mantiene el valor predeterminado de la cuenta.
Respuesta:
Regenerar revoca la API key anterior (tras un breve período de gracia) y devuelve la nueva apiKey completa una sola vez: actualiza tu integración antes de que termine el período de gracia. La clave publicable también se rota: la clave pk_ anterior se revoca de la misma forma y la nueva se devuelve una sola vez como publishableApiKey. La regeneración está limitada a una por cuenta cada 2 minutos; excederla devuelve 429 rate_limit_exceeded. Consulta Manejo de errores.