> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticación y configuración

> Configuración de API key, headers de autenticación y cliente HTTP para la API Codify de SofIA

## Token de autorización

Todas las llamadas a la API requieren un **token Bearer** en el header `Authorization`.

### Formato

```http theme={null}
Authorization: Bearer TU_TOKEN_AQUI
```

### ¿Cómo obtener tu token?

Tras la contratación del servicio, recibirás:

<Columns cols={3}>
  <Card title="Token de producción" />

  <Card title="Token de desarrollo">
    Para pruebas
  </Card>

  <Card title="Endpoints correspondientes" />
</Columns>

### Seguridad del token

<Warning>
  **Nunca** expongas tu token en código cliente (JavaScript en navegador). Guárdalo como variable de entorno o secreto, rótalo periódicamente y usa tokens diferentes para desarrollo y producción.
</Warning>

***

## Headers opcionales (recomendados)

### Identificadores de doctor y paciente

Para trazabilidad y cumplimiento normativo:

```http theme={null}
x-doctor: dr_123
x-patient: pt_456
```

**Uso:**

* Auditoría de accesos
* Debugging y soporte técnico
* Cumplimiento RGPD/HIPAA
* Análisis de uso

**Nota:** Estos identificadores se registran con fines de auditoría pero **no afectan** al procesamiento de la petición.

### Nota

Estos identificadores deben enviarse como headers HTTP, no en el cuerpo de la petición. La API Codify utiliza headers para metadatos de seguimiento, manteniendo el cuerpo de la petición enfocado en el contenido médico.

***

## Entornos disponibles

### Desarrollo

**URL:** Se proporciona bajo solicitud directa

**Características:**

<Columns cols={2}>
  <Card title="Límites de rate más relajados" icon="check" />

  <Card title="No usar para datos reales de pacientes" icon="xmark" />

  <Card title="Logs más verbosos para debugging" icon="check" />

  <Card title="Sin garantías de SLA" icon="xmark" />

  <Card title="Sin costes por petición" icon="check" />
</Columns>

**Uso recomendado:**

<Columns cols={4}>
  <Card title="Desarrollo e integración inicial" />

  <Card title="Pruebas de esquemas JSON" />

  <Card title="Validación de flujos" />

  <Card title="Testing automatizado" />
</Columns>

### Producción

**URL:** Proporcionada tras el despliegue (personalizada por cliente)

**Características:**

<Columns cols={2}>
  <Card title="Alta disponibilidad (99.9% SLA)" icon="check" />

  <Card title="Procesamiento garantizado" icon="check" />

  <Card title="Soporte 24/7" icon="check" />

  <Card title="Métricas y monitorización" icon="check" />
</Columns>

**Uso recomendado:**

<Columns cols={3}>
  <Card title="Integración en sistemas HIS/EHR" />

  <Card title="Procesamiento de datos reales" />

  <Card title="Fluejos de producción" />
</Columns>

***

## Configuración de cliente HTTP

### Timeouts y reintentos

Para configuración de timeouts y estrategias de reintento con backoff exponencial, ver [Estrategia de reintentos](/sofia/es/api/operations#estrategia-de-reintentos).

**Recomendaciones básicas:**

* Timeout: 600 segundos (10 minutos) para la API Codify
* Reintentos: 3 intentos para errores 5xx y 429
* Backoff exponencial: 1s, 2s, 4s...

***

## Headers adicionales

### Content-Type

Siempre debe ser `application/json`:

```http theme={null}
Content-Type: application/json
```

### User-Agent (opcional)

Recomendado para identificar tu aplicación:

```http theme={null}
User-Agent: MiHIS/1.0 (Hospital XYZ)
```

***

## Ejemplo completo de configuración

### Python

```python theme={null}
import os
import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

# Configuración
API_URL = os.getenv('OMNISCRIBE_API_URL')  # Proporcionado tras contratación
API_TOKEN = os.getenv('OMNISCRIBE_API_TOKEN')

# Cliente con reintentos
session = requests.Session()
retry = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[429, 500, 502, 503, 504]
)
adapter = HTTPAdapter(max_retries=retry)
session.mount('http://', adapter)
session.mount('https://', adapter)

# Headers por defecto
session.headers.update({
    'Authorization': f'Bearer {API_TOKEN}',
    'Content-Type': 'application/json',
    'User-Agent': 'MiHIS/1.0'
})

# Uso
def codify(medical_note, doctor_id=None, patient_id=None, model=None):
    payload = {
        'medical_note': medical_note
    }
    
    if model:
        payload['model'] = model
    
    headers = {}
    if doctor_id:
        headers['x-doctor'] = doctor_id
    if patient_id:
        headers['x-patient'] = patient_id
    
    response = session.post(
        f'{API_URL}/v1/codify',
        json=payload,
        headers=headers,
        timeout=600  # Timeout de 10 minutos para Codify
    )
    response.raise_for_status()
    return response.json()

# Ejemplo de uso
result = codify(
    medical_note="Paciente con Diabetes tipo 2...",
    doctor_id="dr_123",
    patient_id="pt_456",
    model="balanced"
)

print(f"Códigos encontrados: {len(result['final_code_assessments'])}")
for assessment in result['final_code_assessments']:
    print(f"  {assessment['code']}: {assessment['description']}")
```

### JavaScript (Node.js)

```javascript theme={null}
const axios = require('axios');
const axiosRetry = require('axios-retry');

// Configuración
const API_URL = process.env.OMNISCRIBE_API_URL;  // Proporcionado tras contratación
const API_TOKEN = process.env.OMNISCRIBE_API_TOKEN;

// Cliente con reintentos
const client = axios.create({
  baseURL: API_URL,
  timeout: 600000,  // Timeout de 10 minutos para Codify
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`,
    'Content-Type': 'application/json',
    'User-Agent': 'MiHIS/1.0'
  }
});

axiosRetry(client, {
  retries: 3,
  retryDelay: axiosRetry.exponentialDelay,
  retryCondition: (error) => {
    return axiosRetry.isNetworkOrIdempotentRequestError(error) ||
           error.response?.status === 429 ||
           error.response?.status >= 500;
  }
});

// Uso
async function codify(medicalNote, doctorId, patientId, model) {
  const headers = {};
  if (doctorId) headers['x-doctor'] = doctorId;
  if (patientId) headers['x-patient'] = patientId;

  const payload = {
    medical_note: medicalNote
  };
  
  if (model) payload.model = model;

  const response = await client.post('/v1/codify', payload, { headers });

  return response.data;
}

// Ejemplo de uso
const result = await codify(
  "Paciente con Diabetes tipo 2...",
  "dr_123",
  "pt_456",
  "balanced"
);

console.log(`Códigos encontrados: ${result.final_code_assessments.length}`);
result.final_code_assessments.forEach(assessment => {
  console.log(`  ${assessment.code}: ${assessment.description}`);
});

module.exports = { codify };
```

***

## Seguridad y mejores prácticas

<Columns cols={2}>
  <Card title="Usar variables de entorno para tokens" icon="check" />

  <Card title="Hardcodear tokens en código fuente" icon="xmark" />

  <Card title="Implementar timeouts apropiados" icon="check" />

  <Card title="Exponer tokens en cliente (navegador)" icon="xmark" />

  <Card title="Configurar reintentos automáticos" icon="check" />

  <Card title="Compartir tokens entre ambientes" icon="xmark" />

  <Card title="Usar HTTPS siempre" icon="check" />

  <Card title="Deshabilitar validación de certificados SSL" icon="xmark" />

  <Card title="Incluir identificadores doctor/patient para auditoría" icon="check" />

  <Card title="Ignorar errores de autenticación" icon="xmark" />
</Columns>

***

## Próximos pasos

<Columns cols={3}>
  <Card title="Estructura de petición/respuesta" icon="clipboard" href="/sofia/es/api/request-response" />

  <Card title="Ver ejemplos" icon="lightbulb" href="/sofia/es/api/examples" />

  <Card title="Manejo de errores" icon="gear" href="/sofia/es/api/operations" />
</Columns>