# 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](/developer/portal-partner-v1.postman.json) 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](/developer/portal-partner-v1.reference.html) y la [especificación OpenAPI](/developer/portal-partner-v1.openapi.json). Los documentos anteriores que requieren identificadores de proveedor describen otro contrato y no sirven para las cuentas actuales.