Códigos promocionales
Gestione listas de códigos promocionales y vincúlelos a encuestas
Códigos promocionales de encuesta
El módulo de códigos promocionales le permite restringir el acceso a una encuesta, realizar promociones y rastrear conversiones mediante listas de códigos vinculadas a encuestas específicas.
Prefijo base para la mayoría de los endpoints: /api/v3/service/quiz/{id}/promo y /api/v3/service/promo.
Descargue la versión en markdown de la sección «Códigos Promocionales» para usar en ChatGPT / otros LLMs:
Todos los endpoints
| HTTP | Endpoint | Propósito |
|---|---|---|
| GET | /quiz/{id}/promo/list | Obtener listas de códigos promocionales del espacio de trabajo |
| POST | /quiz/{id}/promo/list | Crear una lista de códigos promocionales |
| POST | /quiz/{id}/promo/list/{list_id} | Renombrar una lista |
| DELETE | /quiz/{id}/promo/list/{list_id} | Eliminar una lista de códigos promocionales |
| GET | /promo/codes | Obtener códigos de la lista seleccionada (global) |
| POST | /promo/codes | Agregar códigos a una lista |
| DELETE | /promo/codes/{code_id} | Eliminar un código |
| POST | /promo/list | Crear una lista (vía /promo/list) |
| POST | /promo/import-file | Importar códigos desde archivo |
| POST | /promo/attach/{list_id} | Vincular una lista a encuestas |
| POST | /promo/detach | Desvincular una lista de encuestas |
| POST | /quiz/{id}/promo/sync | Sincronizar vínculos de lista |
| GET | /quiz/{id}/promo/codes/quiz | Códigos de la lista vinculada a una encuesta |
| GET | /quiz/{id}/promo/pinned | Encuestas para la pantalla de vinculación |
Obtener listas de códigos promocionales GET /api/v3/service/quiz/{id}/promo/list
Devuelve una lista paginada de listas de códigos promocionales del espacio de trabajo con el número de códigos y encuestas vinculadas.
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
| search | string | — | Buscar por nombre de lista |
| limit | integer | 20 | Cantidad (máx. 500) |
| offset | integer | 0 | Desplazamiento |
| sort | string | updated_at | id, updated_at, name |
| order | string | desc | asc or desc |
curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/promo/list?limit=20&offset=0" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"Crear una lista de códigos promocionales POST /api/v3/service/promo/list
Crea una nueva lista con un conjunto de códigos (hasta 1000 a la vez).
| Parámetro | Req. | Descripción |
|---|---|---|
| name | Sí | Nombre de la lista |
| codes[] | Sí | Arreglo de cadenas de códigos promocionales (hasta 1000) |
curl -X POST "https://api.surveyninja.io/api/v3/service/promo/list" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "January Sale", "codes": ["PROMO001", "PROMO002", "PROMO003"] }'Renombrar una lista POST /api/v3/service/quiz/{id}/promo/list/{list_id}
| Parámetro | Req. | Descripción |
|---|---|---|
| name | Sí | Nuevo nombre de la lista |
curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/promo/list/45" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "February Sale" }'Eliminar una lista DELETE /api/v3/service/quiz/{id}/promo/list/{list_id}
Elimina una lista de códigos promocionales junto con todos sus códigos. No se requiere cuerpo de solicitud.
curl -X DELETE "https://api.surveyninja.io/api/v3/service/quiz/123/promo/list/45" \ -H "Authorization: Bearer YOUR_API_TOKEN"Obtener códigos de la lista GET /api/v3/service/promo/codes
Devuelve los códigos de la lista especificada con filtrado y paginación. La respuesta incluye los campos stats y quizzes[].
| Parámetro | Req. | Predeterminado | Descripción |
|---|---|---|---|
| list_id | Sí | — | ID de la lista de códigos promocionales |
| search | No | — | Buscar por código |
| used | No | — | 1 — usados, 0 — sin usar |
| limit | No | 20 | Cantidad (máx. 500) |
| offset | No | 0 | Desplazamiento |
| sort | No | id | id, updated_at, name |
| order | No | desc | asc or desc |
curl -X GET "https://api.surveyninja.io/api/v3/service/promo/codes?list_id=45&limit=20" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"Agregar códigos a una lista POST /api/v3/service/promo/codes
| Parámetro | Req. | Descripción |
|---|---|---|
| list_id | Sí | ID de la lista |
| codes[] | Sí | Arreglo de cadenas de códigos promocionales |
curl -X POST "https://api.surveyninja.io/api/v3/service/promo/codes" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "list_id": 45, "codes": ["NEW001", "NEW002"] }'Eliminar un código DELETE /api/v3/service/promo/codes/{code_id}
Elimina un código promocional individual de la lista. No se requiere cuerpo de solicitud.
curl -X DELETE "https://api.surveyninja.io/api/v3/service/promo/codes/789" \ -H "Authorization: Bearer YOUR_API_TOKEN"Importar códigos desde archivo POST /api/v3/service/promo/import-file
Sube códigos promocionales desde un archivo. Formato de la solicitud: multipart/form-data.
| Parámetro | Req. | Descripción |
|---|---|---|
| file | Sí | Archivo en formato txt, csv, xlsx, xls. Máximo 1 MB |
Respuesta: {"imported_count": 50, "codes": ["CODE1", ...]}
curl -X POST "https://api.surveyninja.io/api/v3/service/promo/import-file" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -F "file=@/path/to/codes.csv"Vincular / desvincular una lista de encuestas
Gestione la vinculación de una lista de códigos promocionales a múltiples encuestas a la vez.
| Parámetro | Req. | Descripción |
|---|---|---|
| quize_ids[] | Sí | Arreglo de IDs de encuestas |
curl -X POST "https://api.surveyninja.io/api/v3/service/promo/attach/45" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "quize_ids": [123, 456] }'curl -X POST "https://api.surveyninja.io/api/v3/service/promo/detach" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "quize_ids": [123] }'Sincronizar vínculos POST /api/v3/service/quiz/{id}/promo/sync
Actualiza atómicamente los vínculos de la lista: vincula las encuestas especificadas y desvincula todas las demás. Devuelve listas de cambios.
| Parámetro | Req. | Descripción |
|---|---|---|
| list_id | Sí | ID de la lista de códigos promocionales |
| quize_ids[] | Sí | Lista final de IDs de encuestas a vincular |
curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/promo/sync" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "list_id": 45, "quize_ids": [123, 456, 789] }'Ejemplo de respuesta:
{ "attached": [456, 789], "detached": [100, 101] }Códigos de la lista vinculada GET /api/v3/service/quiz/{id}/promo/codes/quiz
Devuelve los códigos promocionales de la lista vinculada a la encuesta especificada. Similar a GET /promo/codes, pero sin necesidad de especificar list_id.
curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/promo/codes/quiz" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"Encuestas para la pantalla de vinculación GET /api/v3/service/quiz/{id}/promo/pinned
Devuelve una lista de encuestas con un indicador que muestra si la lista de códigos promocionales especificada está vinculada a ellas.
| Parámetro | Req. | Predeterminado | Descripción |
|---|---|---|---|
| list_id | Sí | — | ID de la lista de códigos promocionales |
| search | No | — | Buscar por nombre de encuesta |
| limit | No | 20 | Cantidad |
| offset | No | 0 | Desplazamiento |
Respuesta: {"total": N, "data": [{"id": 123, "name": "My Survey", "attach": true, "current": false}, ...]}
curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/promo/pinned?list_id=45&limit=20" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"