Códigos promocionais
Gerencie listas de códigos promocionais e vincule-os a pesquisas
Códigos promocionais de pesquisa
O módulo de códigos promocionais permite restringir o acesso a uma pesquisa, realizar promoções e acompanhar conversões usando listas de códigos vinculadas a pesquisas específicas.
Prefixo base para a maioria dos endpoints: /api/v3/service/quiz/{id}/promo e /api/v3/service/promo.
Baixe a versão em markdown da seção «Códigos Promocionais» para uso no ChatGPT / outros LLMs:
Todos os endpoints
| HTTP | Endpoint | Finalidade |
|---|---|---|
| GET | /quiz/{id}/promo/list | Obter listas de códigos promocionais do espaço de trabalho |
| POST | /quiz/{id}/promo/list | Criar uma lista de códigos promocionais |
| POST | /quiz/{id}/promo/list/{list_id} | Renomear uma lista |
| DELETE | /quiz/{id}/promo/list/{list_id} | Excluir uma lista de códigos promocionais |
| GET | /promo/codes | Obter códigos da lista selecionada (global) |
| POST | /promo/codes | Adicionar códigos a uma lista |
| DELETE | /promo/codes/{code_id} | Excluir um código |
| POST | /promo/list | Criar uma lista (via /promo/list) |
| POST | /promo/import-file | Importar códigos de arquivo |
| POST | /promo/attach/{list_id} | Vincular uma lista a pesquisas |
| POST | /promo/detach | Desvincular uma lista de pesquisas |
| POST | /quiz/{id}/promo/sync | Sincronizar vínculos de lista |
| GET | /quiz/{id}/promo/codes/quiz | Códigos da lista vinculada a uma pesquisa |
| GET | /quiz/{id}/promo/pinned | Pesquisas para a tela de vinculação |
Obter listas de códigos promocionais GET /api/v3/service/quiz/{id}/promo/list
Retorna uma lista paginada de listas de códigos promocionais do espaço de trabalho com o número de códigos e pesquisas vinculadas.
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| search | string | — | Pesquisar por nome da lista |
| limit | integer | 20 | Quantidade (máx. 500) |
| offset | integer | 0 | Deslocamento |
| 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"Criar uma lista de códigos promocionais POST /api/v3/service/promo/list
Cria uma nova lista com um conjunto de códigos (até 1000 de uma vez).
| Parâmetro | Obr. | Descrição |
|---|---|---|
| name | Sim | Nome da lista |
| codes[] | Sim | Array de strings de códigos promocionais (até 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"] }'Renomear uma lista POST /api/v3/service/quiz/{id}/promo/list/{list_id}
| Parâmetro | Obr. | Descrição |
|---|---|---|
| name | Sim | Novo nome da 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" }'Excluir uma lista DELETE /api/v3/service/quiz/{id}/promo/list/{list_id}
Exclui uma lista de códigos promocionais juntamente com todos os seus códigos. Nenhum corpo de requisição é necessário.
curl -X DELETE "https://api.surveyninja.io/api/v3/service/quiz/123/promo/list/45" \ -H "Authorization: Bearer YOUR_API_TOKEN"Obter códigos da lista GET /api/v3/service/promo/codes
Retorna os códigos da lista especificada com filtragem e paginação. A resposta inclui os campos stats e quizzes[].
| Parâmetro | Obr. | Padrão | Descrição |
|---|---|---|---|
| list_id | Sim | — | ID da lista de códigos promocionais |
| search | Não | — | Pesquisar por código |
| used | Não | — | 1 — usados, 0 — não usados |
| limit | Não | 20 | Quantidade (máx. 500) |
| offset | Não | 0 | Deslocamento |
| sort | Não | id | id, updated_at, name |
| order | Não | 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"Adicionar códigos a uma lista POST /api/v3/service/promo/codes
| Parâmetro | Obr. | Descrição |
|---|---|---|
| list_id | Sim | ID da lista |
| codes[] | Sim | Array de strings de códigos promocionais |
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"] }'Excluir um código DELETE /api/v3/service/promo/codes/{code_id}
Exclui um código promocional individual da lista. Nenhum corpo de requisição é necessário.
curl -X DELETE "https://api.surveyninja.io/api/v3/service/promo/codes/789" \ -H "Authorization: Bearer YOUR_API_TOKEN"Importar códigos de arquivo POST /api/v3/service/promo/import-file
Carrega códigos promocionais a partir de um arquivo. Formato da requisição: multipart/form-data.
| Parâmetro | Obr. | Descrição |
|---|---|---|
| file | Sim | Arquivo nos formatos txt, csv, xlsx, xls. Máximo 1 MB |
Resposta: {"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 uma lista de pesquisas
Gerencie a vinculação de uma lista de códigos promocionais a várias pesquisas de uma só vez.
| Parâmetro | Obr. | Descrição |
|---|---|---|
| quize_ids[] | Sim | Array de IDs de pesquisas |
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
Atualiza atomicamente os vínculos da lista: vincula as pesquisas especificadas e desvincula todas as outras. Retorna listas de alterações.
| Parâmetro | Obr. | Descrição |
|---|---|---|
| list_id | Sim | ID da lista de códigos promocionais |
| quize_ids[] | Sim | Lista final de IDs de pesquisas 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] }'Exemplo de resposta:
{ "attached": [456, 789], "detached": [100, 101] }Códigos da lista vinculada GET /api/v3/service/quiz/{id}/promo/codes/quiz
Retorna os códigos promocionais da lista vinculada à pesquisa especificada. Semelhante a GET /promo/codes, mas sem precisar 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"Pesquisas para a tela de vinculação GET /api/v3/service/quiz/{id}/promo/pinned
Retorna uma lista de pesquisas com um indicador que mostra se a lista de códigos promocionais especificada está vinculada a elas.
| Parâmetro | Obr. | Padrão | Descrição |
|---|---|---|---|
| list_id | Sim | — | ID da lista de códigos promocionais |
| search | Não | — | Pesquisar por nome da pesquisa |
| limit | Não | 20 | Quantidade |
| offset | Não | 0 | Deslocamento |
Resposta: {"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"