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.
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).
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: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.
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.
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:
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 suid (acc_*) o por tu propio internalCode.
Actualizar una cuenta
Cambia una cuenta conPATCH /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.
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:
Regenerar una API key
Rota la API key de una cuenta conPOST /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.