API Dialect

Integración de Santillana con Dialect: que un alumno rinda el diagnóstico desde una plataforma externa, cargar colegios y alumnos, y leer resultados.

Inicio rápido

URL base: https://dialect.click/api

• Todo es JSON (Content-Type: application/json), UTF-8.
• Los endpoints del alumno (ingreso, iniciar, responder) son públicos: el alumno se identifica con su RUT.
• Los endpoints de integración de sistemas (colegios, alumnos, resultados) requieren API key.
• Los identificadores (alumnoId, pruebaDialectId, itemId) son UUID.
• Disponibilidad: GET /api/health responde {"status":"ok"}.

Antes de que un alumno pueda rendir, su colegio crea el diagnóstico en Dialect, asigna al alumno y lo habilita. La API no crea colegios, alumnos ni diagnósticos.

Flujo

1. Ingreso: con el RUT se obtiene el alumno y sus pruebas pendientes.
2. Iniciar: con el código de una prueba se obtienen sus preguntas y las de todas las pruebas que podrían seguir.
3. Responder: una llamada por pregunta, en orden. La respuesta indica si la prueba terminó.
4. Cuando una prueba termina, el servidor asigna las siguientes según el puntaje. Se vuelve al paso 1 para verlas, o se sigue directo con la tabla siguientesPorCorrectas.

RUT ──► POST /public/dialect/alumno ──► pruebas[].codigo
                                             │
codigo ──► POST /public/dialect/{codigo}/iniciar/{alumnoId} ──► prueba + items
                                             │
cada item ──► POST /public/dialect/alumno/{alumnoId}/prueba/{pruebaDialectId}/responder
                                             │
                                completado: true ──► siguiente prueba

1. Ingreso del alumno

curl -X POST https://dialect.click/api/public/dialect/alumno \
  -H "Content-Type: application/json" \
  -d '{"rut":"12.345.678-5"}'

Respuesta 200:

{
  "alumno": { "id": "6f1c2a9e-…", "nombre": "Martina R." },
  "pruebas": [
    { "codigo": "A3F09C", "nombre": "Comprensión lectora 1° Básico", "estado": "PENDIENTE" }
  ]
}

2. Iniciar una prueba

Sin cuerpo. Marca la prueba como iniciada y devuelve todo lo necesario para rendirla. Si el alumno ya había respondido preguntas, vienen en respondidas para continuar desde ahí.

curl -X POST https://dialect.click/api/public/dialect/A3F09C/iniciar/6f1c2a9e-…

Respuesta 201:

{
  "sesionId": "b2e4…",
  "prueba": {
    "id": "0d1f84bb-…",
    "tipo": "COMPRENSION",
    "subproceso": null,
    "nivel": "BASICO_1",
    "erroresParaCortar": 5,
    "ventanaParaCortar": 5
  },
  "items": [
    {
      "id": "5264b63a-…",
      "orden": 1,
      "pasaje": null,
      "stem": "",
      "imagen": "/items-dialect/d1-item1.jpg",
      "audio": null,
      "opcionA": "cantar",
      "opcionB": "ayudar",
      "opcionC": "ocultar",
      "opcionD": "dormir",
      "claveCorrecta": "B",
      "pruebaId": "0d1f84bb-…"
    }
  ],
  "respondidas": [
    { "itemId": "5264b63a-…", "orden": 1, "opcionSeleccionada": "B", "esCorrecta": true }
  ],
  "siguientesPorCorrectas": [["c129217b-…"], ["c129217b-…"], …, []],
  "siguientes": [
    { "prueba": { "id": "c129217b-…", "tipo": "SUBPROCESO", "subproceso": "RECONOCIMIENTO_PALABRAS", … },
      "items": [ … ],
      "siguientesPorCorrectas": [ … ] }
  ]
}

Prueba

Item (pregunta)

3. Responder una pregunta

curl -X POST https://dialect.click/api/public/dialect/alumno/6f1c2a9e-…/prueba/0d1f84bb-…/responder \
  -H "Content-Type: application/json" \
  -d '{"itemId":"5264b63a-…","opcionSeleccionada":"B"}'

Respuesta 201:

{ "esCorrecta": true, "completado": false, "totalRespondidas": 1 }

Al terminar la prueba (última pregunta o corte):

{ "esCorrecta": false, "completado": true, "totalRespondidas": 24, "hasPruebasPendientes": true }

• Enviar en orden y de a una: el corte depende de la secuencia.
• Reintentos seguros: reenviar una pregunta ya guardada devuelve el mismo resultado sin duplicarla. Ante un error de red, reintentar la misma llamada.

Corte y siguientes pruebas

Corte

La prueba termina antes de la última pregunta si, entre las últimas ventanaParaCortar respuestas, hay erroresParaCortar o más incorrectas. Ejemplo con 5 y 5: termina al quinto error seguido. SIN_RESPUESTA cuenta como incorrecta.

Siguientes pruebas

Según las correctas obtenidas, el servidor asigna subpruebas al terminar. Para seguir sin volver al ingreso (o sin conexión), siguientesPorCorrectas[n] lista los id de las pruebas que siguen si el alumno terminó con n correctas. Cada una viene completa en siguientes, con su propia tabla. Lista vacía: no sigue ninguna.

correctas = respuestas correctas de la prueba terminada
proximas  = siguientesPorCorrectas[correctas]

Las respuestas de esas pruebas se envían al mismo endpoint de responder, con el pruebaDialectId de cada una, después de que la prueba anterior quedó completado: true.

Audios e imágenes

Las rutas de imagen, audio y alternativas con imagen son relativas a https://dialect.click:

"/items-dialect/d1-item1.jpg"  →  https://dialect.click/items-dialect/d1-item1.jpg

Si audio es null en una prueba de dictado, el enunciado se lee con síntesis de voz en español.

Errores

Los errores responden { "statusCode", "message", "error" } con un mensaje que indica qué falló.

Límites

• 60 solicitudes por segundo por IP en /api/public (ráfagas de hasta 200).
• Una red se bloquea unos minutos tras 300 RUT o códigos inexistentes en 15 minutos.
• Si muchos alumnos salen por la misma IP pública (un colegio), conviene repartir las llamadas en el tiempo.

Integración de sistemas

Para que los sistemas de Santillana carguen colegios y alumnos y lean resultados, sin intervención de una persona.

• Autenticación: header X-API-Key con la clave entregada por Dialect. Es secreta: solo debe usarse desde servidores, nunca en una aplicación que corre en el navegador o el teléfono.
• Alcance: la clave solo opera sobre colegios vinculados a un ID Santillana.
• Identificadores: el colegio se identifica con su refId de Santillana (santillanaId, ej. 00000000-0000-1000-0000-000000001135) y el alumno con su RUT.
• URL base: https://dialect.click/api/integracion/santillana

curl https://dialect.click/api/integracion/santillana/colegios/00000000-0000-1000-0000-000000001135/resultados?anioEscolar=2026 \
  -H "X-API-Key: $DIALECT_API_KEY"

Crear o actualizar colegio

Si el colegio no existe en Dialect se crea; si existe se actualiza. Se puede llamar las veces que sea necesario.

curl -X PUT https://dialect.click/api/integracion/santillana/colegios/00000000-0000-1000-0000-000000001135 \
  -H "X-API-Key: $DIALECT_API_KEY" -H "Content-Type: application/json" \
  -d '{"nombre":"Colegio San Andrés","direccion":"Av. Principal 123, Santiago"}'

Respuesta 200:

{ "santillanaId": "00000000-0000-1000-0000-000000001135", "nombre": "Colegio San Andrés", "direccion": "Av. Principal 123, Santiago", "activo": true }

Cargar alumnos

• Un RUT nuevo se crea; un RUT existente en el colegio se actualiza (nombre y curso) y queda activo.
• Todo o nada: si alguna fila tiene error no se carga ninguna, y la respuesta lista cada error con su posición.
• Alumnos de Pre-Kínder se omiten (Dialect parte en Kinder).
• Un RUT que ya pertenece a otro colegio, o a un profesor, es un error.

curl -X PUT https://dialect.click/api/integracion/santillana/colegios/00000000-0000-1000-0000-000000001135/alumnos \
  -H "X-API-Key: $DIALECT_API_KEY" -H "Content-Type: application/json" \
  -d '{"alumnos":[{"rut":"12.345.678-5","nombre":"Ana Pérez Soto","curso":"1° Básico A"}]}'

Respuesta 200:

{ "creados": 1, "actualizados": 0, "omitidosPreKinder": 0, "cursos": [{ "curso": "1° Básico A", "alumnos": 1 }] }

Respuesta 400 con errores:

{
  "message": "El archivo tiene 2 errores; no se cargó ningún alumno",
  "errores": [
    { "ubicacion": "alumnos[1]", "motivo": "RUT \"1-1\" inválido" },
    { "ubicacion": "alumnos[1]", "motivo": "falta el nombre" }
  ]
}

Cargar alumnos no les asigna pruebas: el colegio crea los diagnósticos y habilita a los alumnos desde Dialect.

Leer resultados

Todos los alumnos del colegio con pruebas asignadas en ese año escolar, cada uno con sus pruebas en el orden en que se asignaron. Los alumnos sin RUT no se incluyen.

{
  "colegio": { "santillanaId": "00000000-0000-1000-0000-000000001135", "nombre": "Colegio San Andrés" },
  "anioEscolar": 2026,
  "alumnos": [
    {
      "rut": "12345678-5",
      "nombre": "Ana Pérez Soto",
      "curso": "1° Básico A",
      "pruebas": [
        { "nombre": "Dialect 1° Básico", "tipo": "COMPRENSION", "subproceso": null, "nivel": "BASICO_1",
          "estado": "COMPLETADO", "fechaInicio": "2026-11-02T12:51:37.533Z", "fechaFin": "2026-11-02T13:10:02.101Z",
          "correctas": 5, "totalRespondidas": 24, "nivelLexile": null, "derivarSubprocesos": true, "nivelSubtest": null },
        { "nombre": "Reconocimiento de palabras 1° Básico", "tipo": "SUBPROCESO", "subproceso": "RECONOCIMIENTO_PALABRAS", "nivel": "BASICO_1",
          "estado": "PENDIENTE", "fechaInicio": null, "fechaFin": null,
          "correctas": null, "totalRespondidas": null, "nivelLexile": null, "derivarSubprocesos": null, "nivelSubtest": null }
      ]
    }
  ]
}

Errores de integración