# Generar un enlace de encuesta

Genera con la API de Pristo un enlace de encuesta de un solo uso o reutilizable, define cuándo caduca y agrega campos personalizados a la respuesta.

`POST https://api.pristo.io/v1/links/generate/{prjId}` crea un enlace personal a un cuestionario de Pristo CX y devuelve su URL. Envías la URL a un encuestado por tu propio canal, como un chat o un recibo, y sus respuestas llegan junto con las demás respuestas del cuestionario.

## Antes de empezar

- Clave API: una clave del programa, con el plan Estándar o Pro. Consulta [Autenticarse con una clave API](https://docs.pristo.io/es/cx/api/authentication).
- Cuestionario: publicado y con el estado **En vivo** en su pestaña **Compartir**. Consulta [Compartir un cuestionario](https://docs.pristo.io/es/cx/questionnaires/share-a-questionnaire).
- ID del cuestionario: el `prjId` del cuestionario, un ID corto de 22 caracteres.

## Pasos

1. Selecciona **Gestión** > **Cuestionarios** y abre el cuestionario.

2. Selecciona **Compartir**.

3. En **API para desarrolladores**, copia el ID del cuestionario. El mismo ID aparece en la barra de direcciones del navegador, después de `/manage/projects/`.

4. Envía una solicitud `POST` a `https://api.pristo.io/v1/links/generate/` seguida del ID, con los encabezados `X-API-Key` y `Content-Type: application/json` y un cuerpo JSON. Envía `{}` para usar todos los valores predeterminados.

5. Envía al encuestado la `url` de la respuesta.

```bash
curl -X POST "https://api.pristo.io/v1/links/generate/QUESTIONNAIRE_ID" \
  -H "X-API-Key: $PRISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresInMinutes": 10080,
    "language": "en",
    "isReusable": false,
    "title": "Order 1042",
    "customFields": { "order_id": "1042", "channel": "chat" }
  }'
```

## Cuerpo de la solicitud

Todos los campos son opcionales, pero el cuerpo en sí es obligatorio.

| Campo | Tipo | Valor predeterminado | Qué hace |
|---|---|---|---|
| `expiresInMinutes` | integer | Sin caducidad | Los minutos que faltan para que caduque el enlace, de 1 a 1 576 800 (3 años) |
| `isReusable` | boolean | `false` | `false` crea un enlace de un solo uso. `true` permite que el enlace recopile una respuesta nueva cada vez que alguien lo abre |
| `language` | string | `he` | Un código ISO 639-1 de dos letras. Pristo CX lo guarda con el enlace, lo muestra en la respuesta y lo usa para la página que ve un encuestado cuando el enlace caducó o ya se usó |
| `title` | string | Ninguno | Una etiqueta para el enlace, de hasta 50 caracteres |
| `customFields` | object | Ninguno | Tus propios valores, como un número de pedido. Las claves y los valores son cadenas de hasta 50 caracteres |

> **Nota**
>
> El cuestionario se abre en su propio idioma predeterminado, diga lo que diga `language`. Para ofrecer otros idiomas a los encuestados, consulta [Traducir un cuestionario](https://docs.pristo.io/es/cx/form-builder/translate-a-questionnaire).

## Resultado

La API responde `200 OK`:

```json
{
  "linkId": "11111111-2222-3333-4444-555555555555",
  "url": "https://go.pristo.io/l/AbCdEfGhIjKlMnOpQrStUv"
}
```

`linkId` es un UUID. `url` abre el cuestionario. El enlace no está vinculado a ningún contacto de la población.

- Un enlace de un solo uso pertenece a una sola respuesta. Si se vuelve a abrir, continúa esa respuesta. Cuando el encuestado envía el cuestionario, el enlace abre una página de agradecimiento en lugar del cuestionario.
- Un enlace reutilizable inicia una respuesta nueva cada vez que se abre, hasta que caduca.
- Cuando pasan los minutos de `expiresInMinutes`, el enlace abre una página que indica que la encuesta caducó.

Los administradores de la cuenta y los administradores del programa ven el `title`, el `language` y cada campo personalizado en los detalles de la respuesta, en **Información del enlace**. Los enlaces creados con la API no aparecen en la lista de enlaces de la pestaña **Compartir**.

## Límites

- `expiresInMinutes`: de 1 a 1 576 800.
- `language`: exactamente 2 letras, y un código ISO 639-1 que exista.
- `title`: hasta 50 caracteres.
- `customFields`: solo valores de tipo cadena; claves y valores de hasta 50 caracteres cada uno.
- El cuerpo de la solicitud puede tener como máximo 10 000 bytes.

## Solución de problemas

**La API devolvió 400 con `provided surveyId is not valid`.** La ruta no termina con el ID de 22 caracteres del cuestionario. Un UUID completo no funciona. Copia el ID desde **API para desarrolladores**.

**La API devolvió 404 con `project with id … not found`.** No existe ningún cuestionario con este ID en la cuenta de la clave API, o el cuestionario se eliminó.

**El enlace se abre, pero no muestra el cuestionario.** El cuestionario aún no está publicado, o su pestaña **Compartir** muestra **Pausada**.

**La API devolvió otro error 400.** El cuerpo en texto sin formato indica el campo. Consulta [Errores de la API](https://docs.pristo.io/es/cx/api/errors).

## Temas relacionados

- [Compartir un cuestionario](https://docs.pristo.io/es/cx/questionnaires/share-a-questionnaire)
- [Ver las respuestas](https://docs.pristo.io/es/cx/responses/view-responses)
- [Autenticarse con una clave API](https://docs.pristo.io/es/cx/api/authentication)
- [Errores de la API](https://docs.pristo.io/es/cx/api/errors)
- [Referencia de la API: Generar un enlace de encuesta (en inglés)](https://docs.pristo.io/cx/api/reference/operations/generatesurveylink)