Documentación para desarrolladores
Referencia de la API
Elige la operación v1, los campos, el tipo de respuesta y el contrato legible por máquinas correctos.
- Dirigido a
- Todas las personas que integran la API
- Antes de empezar
- Una clave para servidor; consulta el catálogo antes de construir las entradas de generación
Operaciones v1
| Operación | Éxito | Salida | Consumo |
|---|---|---|---|
GET /api/public/v1/catalog | 200 | Arreglo JSON directo de grados y temas | Gratis |
POST /api/public/v1/worksheets | 200 | application/json | 1 crédito por ejercicio |
POST /api/public/v1/worksheets/pdf | 200 | application/pdf | 1 crédito por ejercicio |
POST /api/public/v1/worksheets/latex | 200 | JSON con data.latex | 1 crédito por ejercicio |
POST /api/public/v1/embeds | 201 | JSON con embedId y embedUrl | 1 crédito por ejercicio; vistas gratis |
Campos comunes de generación
| Campo | Requisito | Comportamiento |
|---|---|---|
entries | Obligatorio | Arreglo no vacío; máximo 150 problemas en total |
entries[].id | Cadena | Identificador elegido por el cliente y devuelto en orden. Usa valores únicos; los duplicados no forman parte del contrato compatible. |
grade / topic | Ids del catálogo | El tema debe tener implemented: true |
difficulty | easy | medium | hard | Debe aparecer en difficulties para el tema |
count | Entero 1–30 | Cantidad exacta de problemas para esa entrada |
locale | en | es | Opcional; en por defecto. Un valor no reconocido actualmente también cae a en, pero no dependas de esa tolerancia. |
seed | Entero opcional | La misma seed + entries + locale reproduce preguntas y respuestas; los UUID de problemas pueden cambiar. |
Formatos de respuesta
- El catálogo devuelve el arreglo directamente; no está envuelto en data.
- JSON, LaTeX e inserciones devuelven { data: ... }.
- PDF devuelve bytes application/pdf con Content-Disposition: attachment.
- Los errores controlados devuelven { error: { code, message } }. Un fallo de infraestructura no controlado puede devolver una respuesta 5xx genérica; no analices message como identificador estable.
Contratos y herramientas
El archivo OpenAPI es la referencia legible por máquinas para rutas, esquemas, estados y encabezados. La colección de Postman usa las mismas operaciones. Descárgalos en lugar de copiar una versión de esta página.
mock-partner es una consola sin dependencias que mantiene la clave en un servidor Node y permite probar las cinco operaciones y sus encabezados.