Hacer peticiones

Los servicios detrás de la API

Wiselook es un conjunto de servicios independientes detrás de un único API gateway. Cada uno es dueño de un dominio y expone una superficie HTTP:

Servicio	Es dueño de
Catálogo	Metodologías y competencias: la propiedad intelectual de la evaluación.
Assessment	Una evaluación (una evaluation) y sus puntuaciones.
Servicio de IA	Claire, el agente de IA: conduce la conversación (texto + voz) y es dueño de las transcripciones.
Tenancy	Organizaciones (tenants), miembros, etiquetas, códigos de invitación, widgets, federaciones.
Identity	Las cuentas de usuario canónicas; el destino del callback OIDC.

Todo se alcanza a través del gateway. Hay dos superficies de API:

• Pública (/v1/{resource}): lo que alcanzan los llamantes externos (los backends de los integradores, con un token OAuth2 client-credentials, y el widget en el navegador de un visitante, con un JWT de visitante de corta duración emitido por el backend del integrador).
• Interna (/internal/v1/{resource}): solo de servicio a servicio; no se puede emitir para credenciales de clientes.

Esta documentación cubre la superficie pública. Consulta la Referencia de la API para el detalle de los endpoints de cada servicio.

URL base y versionado

Todos los endpoints públicos están bajo /v1/:

https://<WISELOOK_HOST>/v1/{resource}

La versión está en la raíz de la ruta. Un cambio incompatible en el contrato de un recurso se publica bajo /v2/; los cambios aditivos (campos opcionales nuevos, endpoints nuevos) se quedan en /v1/.

Recursos

Recurso	Servicio	Ejemplo
/v1/methodologies	Catálogo	Listar / leer metodologías
/v1/competencies	Catálogo	Listar competencias
/v1/evaluations	Assessment	Crear / leer evaluaciones
/v1/members/{tenant_user_id}/evaluations	Assessment	Iniciar una evaluación para un miembro
/v1/chat/messages	Servicio de IA	Recibir en streaming un turno de Claire, el agente de IA (SSE)
/v1/transcripts/{id}	Servicio de IA	Leer una transcripción completada
/v1/tenant-users	Tenancy	Listar / leer miembros y sus etiquetas
/v1/access-codes	Tenancy	Crear / listar / revocar códigos de invitación
/v1/tags	Tenancy	Listar tus etiquetas
/v1/adopted-methodologies	Tenancy	Listar tus metodologías adoptadas
/v1/widgets/{id}	Tenancy	Arranque (bootstrap) del widget (JWT de visitante)
/v1/widgets/{id}/sessions	Tenancy	Emitir un JWT de visitante para el widget

La Referencia de la API tiene la forma completa de petición y respuesta de cada endpoint.

Respuestas de error

Todos los errores tienen la misma forma:

{
  "code": "snake_case_machine_readable",
  "detail": "Human-readable explanation.",
  "extra": { "any": "structured context" }
}

Ramifica según code; es estable entre versiones. detail es para personas y puede cambiar de redacción. extra lleva contexto estructurado opcional (el campo que falla, la clave en conflicto, el estado actual).

Códigos habituales:

HTTP	code	Significado
401	http_401	Falta el bearer token o no es válido.
403	invalid_scope	Al token le falta el scope que exige este endpoint.
404	http_404	Recurso no encontrado (o no visible para tu scope).
422	http_422	El cuerpo de la petición no superó la validación.

Idempotencia

Los endpoints de escritura aceptan una cabecera Idempotency-Key. Reutilizar la misma clave con el mismo cuerpo devuelve el resultado original en lugar de crear un duplicado.