Integra tu aplicación con la API de Portal

Ofrece evaluaciones desde tu interfaz y conserva los clientes, informes y créditos en tu cuenta de Portal. La conexión se realiza entre servidores: guarda la clave en tu servidor, nunca en el código del navegador ni de una aplicación móvil. Utiliza la dirección del backend asignada a tu entorno, seguida de /partner/v1. Portal v2 es la versión del producto; /partner/v1 identifica la versión de la API.

Configura el acceso

En Ajustes → Desarrollador, ponle un nombre a la clave y créala. Las claves nuevas permiten usar la integración completa y comprobar la conexión. Las claves antiguas de solo conexión conservan sus permisos: crea una nueva si necesitas trabajar con evaluaciones e informes.

Una clave de integración permite actualizar clientes, gestionar evaluaciones creadas por API, leer todos los informes completos disponibles para la cuenta y consumir sus créditos. Puedes tener cinco claves activas y cada una caduca a los 90 días. Revócala para cortar el acceso. También deja de funcionar si el titular que la creó o su cuenta pierden el acceso.

Incluye Authorization: Bearer YOUR_KEY en cada solicitud. No hace falta un identificador de proveedor. El límite es de 60 solicitudes por clave y minuto. Si recibes 429, espera el intervalo indicado en Retry-After.

De la evaluación al informe

1. Comprueba la conexión y los permisos con GET /status.
2. Envía PUT /participants con fullName, email, locale y, si lo necesitas, externalId. Guarda participant.id. Si el correo ya existe en tu cuenta, se actualiza ese cliente. No se pueden actualizar clientes archivados; un correo distinto crea otro cliente.
3. Envía POST /assessments con participantId, locale y expiresAt, además de una cabecera Idempotency-Key única. La fecha de vencimiento debe ser futura y no superar los 180 días. Guarda assessment.id.
4. Obtén GET /assessments/{assessmentId}/questions y presenta el texto y las opciones en el orden recibido. Son 120 preguntas, disponibles en español, inglés y árabe.
5. Guarda las respuestas reales mediante PUT /assessments/{assessmentId}/answers. El cuerpo contiene un arreglo answers de objetos con questionId y value, un entero del 1 al 5. Puedes enviar de 1 a 120 respuestas sin repetir identificadores en la misma solicitud. Una respuesta enviada de nuevo actualiza la anterior.
6. Cuando estén guardadas las 120 respuestas, envía POST /assessments/{assessmentId}/complete con un objeto JSON vacío. Guarda result.id. También puedes recuperarlo mediante GET /assessments/{assessmentId} después de finalizar.
7. Consulta GET /credits y envía POST /reports con assessmentResultId y otro Idempotency-Key. Guarda report.id. Generar un informe permanente nuevo consume 1 crédito. Crear y completar evaluaciones no consume créditos.
8. Lee GET /reports/{reportId}. Añade ?locale=es, ?locale=en o ?locale=ar para elegir el idioma de la vista. La lectura no consume créditos ni modifica el idioma guardado. Devuelve el mismo contenido y presentación aprobados del informe del titular; no se promete un número fijo de métricas.

Las rutas de evaluaciones gestionan sesiones creadas mediante esta API. La lectura de informes permite acceder a todos los informes completos disponibles para la cuenta, incluidos los generados desde Portal.

Reintentos y cargos

Usa un Idempotency-Key de 8 a 128 letras latinas, dígitos, dos puntos, guiones o guiones bajos. Reutiliza el mismo identificador y cuerpo si falla la creación de una evaluación o un informe. Cada operación distinta necesita su propio identificador. Cambiar los datos con el mismo identificador devuelve 409. Guarda estos valores junto con los identificadores de cliente, evaluación, resultado e informe.

Repetir la finalización devuelve el resultado guardado. Pedir un informe que ya existe lo devuelve sin otro cargo, incluso con un nuevo identificador de solicitud. Si falla la generación, se libera el crédito reservado. Corrige el problema y reintenta con el identificador original: un error de respuesta puede ocurrir después de haberse guardado el informe.

Una evaluación incompleta devuelve 409; un saldo insuficiente, 402; una evaluación vencida, 410. Los registros inexistentes o de otra cuenta devuelven 404. Una clave no válida devuelve 401 y la falta de permisos, 403. El cuerpo JSON no puede superar 32 KiB y se rechazan campos inesperados. Todas las respuestas incluyen Cache-Control: no-store.

Datos y uso compartido

Los clientes y sus informes aparecen en el espacio de trabajo habitual, y los cargos se muestran en Créditos. externalId es una referencia de integración de tu cuenta: omitirla conserva el valor anterior; enviarla puede actualizarlo. No se incluye en informes de destinatarios, correos ni PDF. El idioma de la evaluación determina las preguntas y el informe original; el idioma de lectura solo afecta a la respuesta.

Este flujo no envía invitaciones ni informes por correo y no crea enlaces públicos. Compartir el informe sigue siendo una acción independiente del titular. No uses estas rutas para eludir el flujo de invitación o entrega automática de Portal.

Ejemplos y descargas

La página de desarrollador muestra ejemplos Bash/cURL. Configura PORTAL_API_BASE y PORTAL_API_KEY, y asigna los identificadores recibidos a las variables de entorno correspondientes. Indica la fecha de vencimiento y los identificadores de creación, y prepara answers.json con las respuestas reales.

Importa la colección de Postman y configura baseUrl, terminado en /partner/v1, y apiKey localmente. Completa expiresAt y answersJson. La colección guarda los identificadores recibidos e inicializa los de los pedidos si están vacíos. Consérvalos para reintentar y bórralos al iniciar una evaluación o informe nuevo. Ejecutar la generación del informe consume un crédito. No compartas exportaciones que contengan la clave o datos de clientes.

Consulta los campos en la referencia de la API en inglés y la especificación OpenAPI. Los documentos anteriores que requieren identificadores de proveedor describen otro contrato y no sirven para las cuentas actuales.