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

Authorization: Bearer TU_TOKEN_AQUI

​

¿Cómo obtener tu token?

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

Token de producción

Token de desarrollo

Para pruebas

Endpoints correspondientes

​

Seguridad del token

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.

---

​

Headers opcionales (recomendados)

​

Identificadores de doctor y paciente

Para trazabilidad y cumplimiento normativo:

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:

Límites de rate más relajados

No usar para datos reales de pacientes

Logs más verbosos para debugging

Sin garantías de SLA

Sin costes por petición

Uso recomendado:

Desarrollo e integración inicial

Pruebas de esquemas JSON

Validación de flujos

Testing automatizado

​

Producción

URL: Proporcionada tras el despliegue (personalizada por cliente)

Características:

Alta disponibilidad (99.9% SLA)

Procesamiento garantizado

Soporte 24/7

Métricas y monitorización

Uso recomendado:

Integración en sistemas HIS/EHR

Procesamiento de datos reales

Fluejos de producción

---

​

Configuración de cliente HTTP

​

Timeouts y reintentos

Para configuración de timeouts y estrategias de reintento con backoff exponencial, ver 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:

Content-Type: application/json

​

User-Agent (opcional)

Recomendado para identificar tu aplicación:

User-Agent: MiHIS/1.0 (Hospital XYZ)

---

​

Ejemplo completo de configuración

​

Python

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)

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

Usar variables de entorno para tokens

Hardcodear tokens en código fuente

Implementar timeouts apropiados

Exponer tokens en cliente (navegador)

Configurar reintentos automáticos

Compartir tokens entre ambientes

Usar HTTPS siempre

Deshabilitar validación de certificados SSL

Incluir identificadores doctor/patient para auditoría

Ignorar errores de autenticación

---

​

Próximos pasos

Estructura de petición/respuesta

Ver ejemplos

Manejo de errores