Cuentas

La gestión de cuentas solo está disponible con una clave API institucional. Las claves API de nivel médico no tienen acceso a estos endpoints.

Las claves API institucionales pueden crear y recuperar 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 su integración. Crear una cuenta genera dos claves para esa cuenta — una clave secreta (sk_…) para las llamadas API del lado del servidor y una clave publicable (pk_…) para el embed de navegador (vea Tipos de clave). Puede rotar la clave secreta más adelante.

Crear una cuenta

POST /v1/institutional/accounts requiere email y doctorSpecialties. Opcionalmente, envíe apiKeyConfig.validForDays (1–365) para controlar cuánto tiempo permanece válida la clave API generada; omítalo para usar el valor predeterminado de 365 días (1 año).

curl -X POST https://scribe-api.telepatia.ai/v1/institutional/accounts \
  -H "Authorization: Bearer SU_CLAVE_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 }
  }'

Respuesta:

{
  "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) y publishableApiKey (publicable) se devuelven solo una vez — guárdelas de forma segura. expiresAt es la marca de tiempo UTC en que las claves dejan de funcionar, y apiKeyExpiresInDays refleja la vigencia que se aplicó. Use la clave secreta para las llamadas API del lado del servidor; la clave publicable es para el embed de navegador y no puede llamar directamente a la API.

Guarde el id (o su internalCode) — puede usar cualquiera de los dos para recuperar la cuenta más adelante.

Crear cuentas en lote

POST /v1/institutional/accounts/batch crea varias cuentas de médicos en una sola llamada. Envíe un arreglo accounts. Cada elemento toma los mismos campos que una creación individual. El lote admite un máximo de 10 cuentas. El endpoint rechaza toda la solicitud con 400 antes de crear cualquier cuenta cuando el lote repite un email o un internalCode.

curl -X POST https://scribe-api.telepatia.ai/v1/institutional/accounts/batch \
  -H "Authorization: Bearer SU_CLAVE_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" }
    ]
  }'

El endpoint crea cada cuenta por separado. Una cuenta puede tener éxito mientras otra falla. El endpoint no revierte. Devuelve 200 con un arreglo results. Cada entrada informa el resultado de una cuenta, en el orden en que las envió. Respuesta:

{
  "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 cuenta creada devuelve su apiKey y su publishableApiKey solo una vez. Guarde las claves de cada entrada created antes de leer la siguiente respuesta.

Lea createdCount y failedCount para un total rápido. Use status en cada entrada para encontrar las cuentas que fallaron.

Recuperar una cuenta

Busque una cuenta por su id (acc_*) o por su propio internalCode.

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

Respuesta:

{
  "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 una clave API

Rote la clave API de una cuenta con POST /v1/institutional/accounts/{account_id}/api-keys/regenerate, identificando la cuenta por su id (acc_*) o internalCode. Opcionalmente, envíe validForDays (1–365) para definir la vigencia de la nueva clave; omítalo para mantener el valor predeterminado de la cuenta.

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

Respuesta:

{
  "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 revoca la clave anterior (tras un breve período de gracia) y devuelve la nueva apiKey sin cifrar una sola vez — actualice su integración antes de que termine el período de gracia. La regeneración está limitada a una por cuenta cada 2 minutos; excederla devuelve 429 rate_limit_exceeded. Consulte Manejo de errores.

Primeros pasos

Conceptos básicos

Cuentas y pacientes

Referencia

Crear una cuenta

Crear cuentas en lote

Recuperar una cuenta

Regenerar una clave API

​Crear una cuenta

​Crear cuentas en lote

​Recuperar una cuenta

​Regenerar una clave API

Crear una cuenta

Crear cuentas en lote

Recuperar una cuenta

Regenerar una clave API