Saltar a contenido

MedTime - Estandares de API

Identificador: MTS-API-STD-001 Version: 1.0.0 Fecha: 2025-12-03 Autor: SpecQueen

1. Proposito

Este documento define los estandares tecnicos para todas las APIs de MedTime, asegurando consistencia, seguridad y facilidad de integracion.

2. Especificacion Base

Aspecto Valor
Formato de especificacion OpenAPI 3.0.3
Protocolo HTTPS (TLS 1.3 minimo)
Formato de datos JSON
Encoding UTF-8
Versionado URL path (/v1/, /v2/)

3. Base URLs

Ambiente URL
Produccion <https://api.medtime.app/v1>
Staging <https://api-staging.medtime.app/v1>
Desarrollo <https://api-dev.medtime.app/v1>

4. Headers Requeridos

4.1. Request Headers

Header Requerido Descripcion
Authorization Si* Bearer token JWT.*Excepto endpoints publicos
Content-Type Si application/json
Accept Si application/json
Accept-Language No Codigo de idioma (es-MX, en-US, pt-BR)
X-Request-ID No UUID para trazabilidad. Si no se envia, servidor genera
X-Device-ID Recomendado Identificador unico del dispositivo
X-App-Version Recomendado Version de la aplicacion cliente

4.2. Response Headers

Header Siempre Descripcion
X-Request-ID Si Echo del request o generado
X-RateLimit-Limit Si Limite de requests por ventana
X-RateLimit-Remaining Si Requests restantes
X-RateLimit-Reset Si Timestamp UTC de reset
Content-Language Si Idioma de la respuesta

5. Autenticacion

5.1. Metodos Soportados

Metodo Uso
Bearer JWT Autenticacion de usuarios
API Key Integraciones server-to-server (v2.0+)

5.2. Formato JWT

{
  "sub": "user_uuid",
  "iat": 1234567890,
  "exp": 1234571490,
  "iss": "medtime.app",
  "aud": "medtime-api",
  "tier": "pro",
  "roles": ["patient"],
  "device_id": "device_uuid"
}

5.3. Refresh Tokens

Aspecto Valor
Expiracion access token 15 minutos
Expiracion refresh token 30 dias
Rotacion Refresh token rota en cada uso
Revocacion Inmediata en logout o cambio de contrasena

6. Formato de Respuestas

6.1. Respuesta Exitosa

{
  "data": { ... },
  "meta": {
    "request_id": "uuid",
    "timestamp": "2025-12-03T10:30:00Z"
  }
}

6.2. Respuesta con Paginacion

{
  "data": [ ... ],
  "meta": {
    "request_id": "uuid",
    "timestamp": "2025-12-03T10:30:00Z",
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_pages": 5,
      "total_items": 100
    }
  }
}

6.3. Respuesta de Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Mensaje legible para usuario",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "El formato del email no es valido"
      }
    ]
  },
  "meta": {
    "request_id": "uuid",
    "timestamp": "2025-12-03T10:30:00Z"
  }
}

7. Codigos de Error

7.1. Codigos HTTP

Codigo Uso
200 OK - Operacion exitosa
201 Created - Recurso creado
204 No Content - Eliminacion exitosa
400 Bad Request - Error de validacion
401 Unauthorized - Token invalido o expirado
403 Forbidden - Sin permisos
404 Not Found - Recurso no existe
409 Conflict - Conflicto de estado
422 Unprocessable Entity - Error de negocio
429 Too Many Requests - Rate limit excedido
500 Internal Server Error - Error del servidor
503 Service Unavailable - Servicio no disponible

7.2. Codigos de Error de Negocio

Codigo Descripcion
AUTH_INVALID_CREDENTIALS Credenciales invalidas
AUTH_TOKEN_EXPIRED Token expirado
AUTH_MFA_REQUIRED Se requiere verificacion MFA
USER_NOT_FOUND Usuario no encontrado
USER_ALREADY_EXISTS Usuario ya registrado
TIER_LIMIT_EXCEEDED Limite del tier excedido
MEDICATION_INTERACTION Interaccion detectada
CONSENT_REQUIRED Consentimiento requerido
OFFLINE_CONFLICT Conflicto de sincronizacion
RATE_LIMIT_EXCEEDED Rate limit excedido

8. Rate Limiting

8.1. Limites por Tier

Tier General Busqueda Sync OCR IA
Free 60/min 30/min 10/min 3/dia 3/dia
Pro 120/min 60/min 30/min 10/dia 10/dia
Perfect 300/min 120/min 60/min 30/dia 30/dia

8.2. Respuesta 429

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Has excedido el limite de solicitudes",
    "details": {
      "limit": 60,
      "window": "1m",
      "retry_after": 45
    }
  }
}

Header adicional: Retry-After: 45

9. Paginacion

9.1. Parametros

Parametro Tipo Default Max
page integer 1 -
per_page integer 20 100
sort string -created_at -

9.2. Formato de Sort

  • Ascendente: sort=created_at
  • Descendente: sort=-created_at
  • Multiple: sort=-created_at,name

10. Filtrado

10.1. Operadores

Operador Ejemplo Descripcion
eq status=eq:active Igual a
ne status=ne:deleted Diferente de
gt date=gt:2025-01-01 Mayor que
gte date=gte:2025-01-01 Mayor o igual
lt date=lt:2025-12-31 Menor que
lte date=lte:2025-12-31 Menor o igual
in status=in:active,pending En lista
like name=like:paracet Contiene

11. Versionado de API

11.1. Estrategia

  • Version en URL path: /v1/, /v2/
  • Soporte minimo: 2 versiones activas
  • Deprecacion: 6 meses de aviso antes de retirar version

11.2. Headers de Deprecacion

Deprecation: true
Sunset: Sat, 01 Jun 2026 00:00:00 GMT
Link: </v2/medications>; rel="successor-version"

12. Seguridad

12.1. CORS

Origen Permitido
<https://app.medtime.app> Si
<https://*.medtime.app> Si (staging/dev)
Otros No

12.2. Headers de Seguridad

Header Valor
Strict-Transport-Security max-age=31536000; includeSubDomains
X-Content-Type-Options nosniff
X-Frame-Options DENY
Content-Security-Policy Restrictivo

13. Idempotencia

Para operaciones POST/PUT criticas, usar header Idempotency-Key:

POST /v1/medications
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
  • Keys validas por 24 horas
  • Respuestas cacheadas para misma key

14. Documentación Interactiva (Swagger UI)

Decisión del Director (Iteración 12): Incluir documentación interactiva como parte del estándar de API.

14.1. Portal de Documentación

Ambiente URL Autenticación
Producción <https://api.medtime.com/docs> Bearer token JWT
Staging <https://api-staging.medtime.com/docs> Bearer token JWT
Desarrollo <http://localhost:3000/docs> Sin auth

14.2. Herramientas

Herramienta Versión Uso
Swagger UI 5.x Documentación interactiva
Redoc 2.x Documentación estática
OpenAPI Generator 7.x SDKs cliente

14.3. Características

Característica Descripción
Try-it-out Pruebas con tokens de staging
Ejemplos Request/response por endpoint
Schemas Modelos con validaciones
Changelog Historial de versiones de API
Autenticación OAuth2 flow integrado

14.4. Especificación OpenAPI

openapi: 3.1.0
info:
  title: MedTime API
  version: 1.0.0
  description: API para gestión de medicamentos y adherencia
servers:
  - url: https://api.medtime.com/v1
    description: Producción
  - url: https://api-staging.medtime.com/v1
    description: Staging

15. Referencias

Documento generado por SpecQueen - La especificacion funcional ES el sistema.