Saltar al contenido principal

Esquema compartido

Varios campos de petición y fragmentos de respuesta aparecen en más de un endpoint. Se documentan una sola vez en esta página y se referencian desde cada tutorial de endpoint.

Encabezado de autenticación​

Todos los endpoints excepto /login requieren un token bearer en el encabezado Authorization:

Authorization: Bearer <access_token>

Obtén el token del endpoint Login y vuelve a emitirlo antes de que transcurran los expires_in_minutes. Si un endpoint clínico devuelve un error de autenticación o autorización, trata lo como expiración del token y reintentar tras un nuevo login.

Envolvente de respuesta FHIR​

Todos los endpoints clínicos devuelven una envolvente DiagnosticReport FHIR al inicio de la respuesta:

{
  "resourceType": "DiagnosticReport",
  "identifier": {
    "use": "official",
    "value": "f426f15d-fcea-4bd0-942e-7528bf163c5d"
  },
  "status": "preliminary",
  "issued": "2026-02-13T14:58:27.466367",
  "analysisDuration": 1.11359
}
  • resourceType siempre "DiagnosticReport" (compatible con FHIR).
  • identifier.value UUID para este informe. Persiste el valor en tu lado para auditoría y trazabilidad.
  • status estado FHIR; "preliminary" indica un resultado generado por IA que no ha sido validado por un clínico.
  • issued marca de tiempo ISO-8601 en que se generó el informe.
  • analysisDuration número de segundos que la IA tardó en producir el informe.

/diagnosis-support adicionalmente lleva bloques category y code que describen el tipo de informe (Diagnostic Imaging, LOINC 100063-7 "Primary skin concern"); son estáticos para ese endpoint y pueden ignorarse en la mayoría de integraciones.

Adjunto de imagen (contentAttachment)​

Todos los endpoints que aceptan una imagen la llevan dentro de un objeto contentAttachment:

"contentAttachment": {
  "data": "<base64_encoded_image_data>",
  "title": "Lesion close-up",
  "contentType": "image/jpeg"
}
  • data (obligatorio) bytes de imagen, codificados en Base64.
  • title (opcional) etiqueta de texto libre preservada en la respuesta, útil para correlacionar imágenes con anatomía o contexto de captura.
  • contentType (opcional) tipo MIME. Por defecto image/png; establece image/jpeg para imágenes JPEG.

Evaluación de calidad de imagen: mediaValidity​

Todos los endpoints que aceptan una imagen devuelven un bloque mediaValidity que describe si la imagen es adecuada para análisis por IA.

"mediaValidity": {
  "quality": {
    "acceptable": true,
    "score": 93,
    "interpretation": "Excellent"
  },
  "domain": {
    "isDermatological": true,
    "additionalData": {
      "aiConfidence": {
        "code": {
          "coding": [
            {
              "systemDisplay": "Legit.Health",
              "code": "aiConfidence",
              "text": "AI model confidence in the image being dermatological"
            }
          ]
        },
        "value": 99.99999296
      }
    }
  },
  "modality": {
    "value": "Clinical",
    "additionalData": {
      "aiConfidenceClinical": { "value": 99.99998808 },
      "aiConfidenceDermoscopic": { "value": 0.0 }
    }
  },
  "isValid": true
}
  • quality.acceptable booleano. Si la imagen cumple con el umbral de calidad mínimo requerido para uso clínico.
  • quality.score entero 0–100. Puntuación de calidad de imagen, donde 0 es inutilizable y 100 es perfecto.
  • quality.interpretation categoría para quality.score. Cómo interpretar la puntuación: Bad, Poor, Fair, Good, Excellent.
  • domain.isDermatological booleano. Si la imagen contiene piel (es decir, está en el dominio dermatológico).
  • domain.additionalData.aiConfidence.value flotante 0–100. Confianza de IA (en porcentaje) de que la imagen es dermatológica.
  • modality.value clasificación de imagen: None, Clinical, o Dermoscopic.
  • modality.additionalData.aiConfidenceClinical.value / aiConfidenceDermoscopic.value confianza de IA (en porcentaje) para cada clasificación de modalidad.
  • isValid booleano. true solo cuando la imagen es dermatológica Y de calidad aceptable. Usa esta única bandera como puerta de paso para consumir la salida de IA con propósitos clínicos.
Usa isValid como puerta de paso de integración

Si mediaValidity.isValid es false, los campos posteriores (tales como conclusion[] o patientEvolution) pueden aún estar presentes pero no deben ser actuados clínicamente. Muestra la información de calidad al operador e invítalo a retomar la imagen.

Sitio corporal (bodySite)​

bodySite acepta cualquier código devuelto por GET /body-sites. No hardcodees la lista de sitios corporales el catálogo evoluciona conforme se agregan nuevos sitios. Consulta el ayudante Body sites para el uso.

Condición conocida (knownCondition)​

"knownCondition": {
  "conclusion": { "text": "<plain-text condition>" }
}
  • conclusion.text (obligatorio) nombre de condición en texto plano (por ejemplo, el texto de conclusión devuelto por /diagnosis-support, o una etiqueta proporcionada por clínico). La API resuelve el texto internamente a los códigos ICD-11 relevantes.

Sistema de puntuación (scoringSystem y questionnaireResponse)​

"scoringSystem": {
  "<scoring_system_code>": {
    "questionnaireResponse": {
      "item": { "<item_code>": "<answer_value>" }
    }
  }
}
  • scoringSystem.<code> (obligatorio) exactamente un código de sistema de puntuación devuelto por GET /questionnaires.
  • scoringSystem.<code>.questionnaireResponse.item insumos clínicos que la IA no puede inferir de la imagen (demografía del paciente, síntomas reportados por el paciente, porcentaje de área corporal de región). Los códigos de item requeridos y los rangos de valores aceptados dependen del sistema de puntuación elegido y son devueltos por GET /questionnaires?code=<scoring_system_code>.

No hardcodees ni la lista de sistemas de puntuación ni el esquema de items llama a los endpoints ayudantes en tiempo de integración de modo que los nuevos sistemas de puntuación e items agregados en el futuro no quiebren la integración. Enviar una petición sin los items requeridos devuelve un error de validación 422. Consulta el ayudante Questionnaires para el uso.