VivIAM REST API

Comenzar

La API de VivIAM es una API RESTful que utiliza JSON para serialización de datos. Todas las solicitudes deben realizarse sobre HTTPS con TLS 1.3+. La URL base es:

https://api.viviam.health/v1

Características Principales

Primera Solicitud

Ejemplo de una solicitud GET básica para obtener información del usuario autenticado:

curl -X GET https://api.viviam.health/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Autenticación

VivIAM API soporta dos métodos de autenticación:

1. API Keys (Recomendado para server-to-server)

Las API Keys se generan desde el panel de administración. Incluye el API key en el header Authorization:

Authorization: Bearer viv_live_sk_1a2b3c4d5e6f7g8h9i0j

2. OAuth 2.0 (Para aplicaciones de terceros)

Para aplicaciones que requieren acceso en nombre de usuarios, implementamos OAuth 2.0 con los siguientes flujos:

// 1. Redirigir al usuario para autorización
https://auth.viviam.health/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=patients:read appointments:write

// 2. Intercambiar código por token de acceso
POST https://auth.viviam.health/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=https://yourapp.com/callback

Scopes Disponibles

Los scopes limitan el acceso de la aplicación a recursos específicos:

• patients:read - Leer información de pacientes
• patients:write - Crear y actualizar pacientes
• appointments:read - Leer citas médicas
• appointments:write - Crear y gestionar citas
• encounters:read - Leer encuentros clínicos
• encounters:write - Crear y actualizar encuentros
• documents:read - Leer documentos médicos
• imaging:read - Acceder a imágenes DICOM

Endpoints Principales

Estos son los endpoints más utilizados de la API de VivIAM:

Pacientes

// Crear un nuevo paciente
const response = await fetch('https://api.viviam.health/v1/patients', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: 'Juan',
    lastName: 'Pérez',
    dateOfBirth: '1985-03-15',
    gender: 'male',
    email: '[email protected]',
    phone: '+54 9 11 1234-5678',
    address: {
      street: 'Av. Corrientes 1234',
      city: 'Buenos Aires',
      state: 'CABA',
      zipCode: '1043',
      country: 'Argentina'
    }
  })
});

const patient = await response.json();
console.log('Paciente creado:', patient.id);

Citas Médicas

import requests
from datetime import datetime, timedelta

# Crear una cita
appointment_data = {
    'patient_id': 'pat_abc123',
    'practitioner_id': 'prac_xyz789',
    'start': (datetime.now() + timedelta(days=7)).isoformat(),
    'duration_minutes': 30,
    'type': 'checkup',
    'status': 'scheduled',
    'notes': 'Control anual'
}

response = requests.post(
    'https://api.viviam.health/v1/appointments',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=appointment_data
)

appointment = response.json()
print(f'Cita creada: {appointment["id"]}')

Encuentros Clínicos

Imágenes Médicas (DICOM)

Recursos FHIR

VivIAM soporta FHIR R4. Todos los recursos FHIR están disponibles en:

https://api.viviam.health/fhir/r4/

Soportamos Patient, Practitioner, Encounter, Observation, DiagnosticReport, MedicationRequest, Condition, AllergyIntolerance y más.

Webhooks

Los webhooks permiten recibir notificaciones en tiempo real cuando ocurren eventos en VivIAM. Configura webhooks desde el panel de administración.

Eventos Disponibles

• patient.created - Nuevo paciente registrado
• patient.updated - Información de paciente actualizada
• appointment.scheduled - Nueva cita agendada
• appointment.cancelled - Cita cancelada
• encounter.completed - Encuentro clínico finalizado
• document.uploaded - Nuevo documento subido
• imaging.available - Nuevas imágenes disponibles

Payload de Webhook

{
  "id": "evt_1a2b3c4d",
  "type": "appointment.scheduled",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "object": {
      "id": "appt_xyz789",
      "patient_id": "pat_abc123",
      "practitioner_id": "prac_def456",
      "start": "2024-01-22T14:00:00Z",
      "duration_minutes": 30,
      "type": "checkup",
      "status": "scheduled"
    }
  }
}

Verificación de Firma

Todos los webhooks incluyen una firma HMAC SHA-256 en el header X-VivIAM-Signature:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Límites de Tasa

Para garantizar la estabilidad del servicio, implementamos rate limiting:

Headers de Rate Limit

Cada respuesta incluye headers informativos sobre tu uso actual:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4850
X-RateLimit-Reset: 1705327200

Códigos de Error

VivIAM utiliza códigos de estado HTTP estándar y retorna errores en formato JSON:

{
  "error": {
    "type": "invalid_request_error",
    "code": "patient_not_found",
    "message": "El paciente con ID 'pat_invalid' no existe",
    "param": "patient_id",
    "request_id": "req_abc123xyz"
  }
}

Códigos HTTP Comunes

• 200 OK - Solicitud exitosa
• 201 Created - Recurso creado exitosamente
• 400 Bad Request - Parámetros inválidos
• 401 Unauthorized - API key inválida o ausente
• 403 Forbidden - Sin permisos para este recurso
• 404 Not Found - Recurso no encontrado
• 429 Too Many Requests - Rate limit excedido
• 500 Internal Server Error - Error del servidor

Manejo de Errores

try {
  const patient = await viviam.patients.get('pat_abc123');
} catch (error) {
  if (error.type === 'invalid_request_error') {
    console.error('Solicitud inválida:', error.message);
  } else if (error.code === 'rate_limit_exceeded') {
    console.error('Rate limit excedido. Reintentar en:', error.resetAt);
  } else {
    console.error('Error:', error.message);
  }
}