Enquetes · miCore

O que é

Enquetes são pesquisas rápidas: satisfação de clientes, NPS, opinião da equipe. Você monta as perguntas, escolhe quem responde (só a equipe ou qualquer pessoa com o link) e acompanha o resultado por pergunta.

Pela API, seu sistema cria enquetes, envia as respostas que coletou (do site, do app, de um bot) e lê o resultado consolidado, com as mesmas regras do painel.

O que dá para fazer hoje

Listar e consultar enquetes com as perguntas.
Criar uma enquete com as perguntas.
Configurar período, quem responde e as regras de resposta.
Ativar e desativar.
Enviar respostas pela chave de cada pergunta.
Ler o resultado e as respostas.

Situação de uma enquete

Situação	Significado
`open`	Recebendo respostas
`scheduled`	Ativa, mas antes da abertura (`starts_at`)
`closed`	Ativa, mas depois do encerramento (`ends_at`)
`disabled`	Desativada; não recebe respostas

Importante

Responda usando a key de cada pergunta, que não muda quando as perguntas são editadas no painel.
Criar enquete e enviar resposta exigem Idempotency-Key.
As perguntas são editadas pelo construtor de Formulários no painel; a API cria, mas não edita perguntas.
Leitura exige surveys:read; criar, configurar, ativar e desativar, surveys:write; responder, surveys:respond.

Disponibilidade na API

Endpoints de Enquetes

Crie enquetes com perguntas, receba respostas e leia o resultado consolidado. Os exemplos abaixo são gerados pelo contrato OpenAPI oficial.

GET /api/v1/surveys

Lista enquetes

Exige `surveys:read` e a permissão Enquetes (visualizar), do contrato de Ferramentas. Mais recentes primeiro. A situação (`state`) é calculada pelo status e pelo período: `disabled` (desativada), `scheduled` (antes da abertura), `closed` (depois do encerramento) ou `open`.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`state`query	string	Não	—
`audience`query	string	Não	team: só a equipe responde; link: qualquer pessoa com o link público também.
`search`query	string	Não	Busca no título.
`per_page`query	integer	Não	—

Exemplo de requisição

cURL

curl "$MICORE_BASE_URL/surveys" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Exemplo de resposta JSON

Resposta · 200

{
    "data": [
        {
            "id": 1,
            "name": "string",
            "description": null,
            "state": "open",
            "active": true,
            "audience": "team",
            "anonymous": true,
            "allow_multiple": true,
            "starts_at": "2026-10-20T10:00:00-03:00",
            "ends_at": "2026-10-20T10:00:00-03:00",
            "thank_you_message": null,
            "public_url": null,
            "responses_count": 1,
            "questions": [
                {
                    "key": "field_9b2f6c1e-3a4d-4b8e-a1c2-7d5e6f708192",
                    "name": "string",
                    "description": null,
                    "type": "radio",
                    "required": true,
                    "options": [
                        "string"
                    ]
                }
            ],
            "created_at": "2026-10-20T10:00:00-03:00",
            "updated_at": "2026-10-20T10:00:00-03:00"
        }
    ],
    "links": [],
    "meta": []
}

Respostas possíveis

200 Página de enquetes401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente422 Dados inválidos429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

POST /api/v1/surveys

Cria uma enquete com as perguntas

Exige `surveys:write` e a permissão Enquetes (criar). As perguntas nascem no motor de formulários do miCore; cada uma recebe uma chave (`key`) estável, usada para responder e para ler o resultado. Perguntas de escolha (`radio`, `checkbox`, `options`) precisam de ao menos duas opções diferentes. Depois de criadas, as perguntas são editadas pelo construtor de Formulários no painel (etapas e condicionais); esta API não edita perguntas. Sem `active`, a enquete nasce ativa.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`Idempotency-Key`header	string	Sim	Identificador único da mutação, com 8 a 100 caracteres. O resultado fica reutilizável por 24 horas e a chave não pode ser reutilizada depois de expirar.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Até 255 caracteres.
`description`	string \| null	Não	Até 20000 caracteres.
`starts_at`	string \| null (date-time)	Não	Sem abertura: aberta desde já.
`ends_at`	string \| null (date-time)	Não	Sem encerramento: aberta até ser desativada.
`audience`	string	Não	Valores: team, link. Padrão: "team".
`anonymous`	boolean	Não	Padrão: false.
`allow_multiple`	boolean	Não	Padrão: false.
`thank_you_message`	string \| null	Não	Até 2000 caracteres.
`active`	boolean	Não	Padrão: true.
`questions`	array<object>	Sim	—

Exemplo de requisição

cURL

curl -X POST "$MICORE_BASE_URL/surveys" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: board-request-0001" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","description":null,"starts_at":"2026-10-20T10:00:00-03:00","ends_at":"2026-10-20T10:00:00-03:00","audience":"team","anonymous":true,"allow_multiple":true,"thank_you_message":null,"active":true,"questions":[{"name":"string","description":null,"type":"radio","required":true,"options":["string"]}]}'

Exemplo de resposta JSON

Resposta · 201

{
    "data": {
        "id": 1,
        "name": "string",
        "description": null,
        "state": "open",
        "active": true,
        "audience": "team",
        "anonymous": true,
        "allow_multiple": true,
        "starts_at": "2026-10-20T10:00:00-03:00",
        "ends_at": "2026-10-20T10:00:00-03:00",
        "thank_you_message": null,
        "public_url": null,
        "responses_count": 1,
        "questions": [
            {
                "key": "field_9b2f6c1e-3a4d-4b8e-a1c2-7d5e6f708192",
                "name": "string",
                "description": null,
                "type": "radio",
                "required": true,
                "options": [
                    "string"
                ]
            }
        ],
        "created_at": "2026-10-20T10:00:00-03:00",
        "updated_at": "2026-10-20T10:00:00-03:00"
    }
}

Respostas possíveis

201 Enquete criada ou reapresentada pela mesma chave idempotente401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente409 Chave em processamento ou reutilizada com outro conteúdo422 Dados inválidos429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

GET /api/v1/surveys/{survey}

Consulta uma enquete com as perguntas

Exige `surveys:read`. Traz as perguntas da versão atual do formulário, com a chave (`key`) de cada uma.

Exemplo de requisição

cURL

curl "$MICORE_BASE_URL/surveys/{survey}" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 1,
        "name": "string",
        "description": null,
        "state": "open",
        "active": true,
        "audience": "team",
        "anonymous": true,
        "allow_multiple": true,
        "starts_at": "2026-10-20T10:00:00-03:00",
        "ends_at": "2026-10-20T10:00:00-03:00",
        "thank_you_message": null,
        "public_url": null,
        "responses_count": 1,
        "questions": [
            {
                "key": "field_9b2f6c1e-3a4d-4b8e-a1c2-7d5e6f708192",
                "name": "string",
                "description": null,
                "type": "radio",
                "required": true,
                "options": [
                    "string"
                ]
            }
        ],
        "created_at": "2026-10-20T10:00:00-03:00",
        "updated_at": "2026-10-20T10:00:00-03:00"
    }
}

Respostas possíveis

200 Enquete401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

PATCH /api/v1/surveys/{survey}

Edita as configurações de uma enquete

Exige `surveys:write` e a permissão Enquetes (editar). Edição parcial: só os campos enviados mudam. `null` em `starts_at` ou `ends_at` deixa o lado do período em aberto. O encerramento precisa ser depois da abertura (422 em `ends_at`). Perguntas e situação não mudam aqui: perguntas pelo construtor de Formulários no painel, situação por /enable e /disable.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Não	Até 255 caracteres.
`description`	string \| null	Não	Até 20000 caracteres.
`starts_at`	string \| null (date-time)	Não	—
`ends_at`	string \| null (date-time)	Não	—
`audience`	string	Não	Valores: team, link.
`anonymous`	boolean	Não	—
`allow_multiple`	boolean	Não	—
`thank_you_message`	string \| null	Não	Até 2000 caracteres.

Exemplo de requisição

cURL

curl -X PATCH "$MICORE_BASE_URL/surveys/{survey}" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","description":null,"starts_at":"2026-10-20T10:00:00-03:00","ends_at":"2026-10-20T10:00:00-03:00","audience":"team","anonymous":true,"allow_multiple":true,"thank_you_message":null}'

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 1,
        "name": "string",
        "description": null,
        "state": "open",
        "active": true,
        "audience": "team",
        "anonymous": true,
        "allow_multiple": true,
        "starts_at": "2026-10-20T10:00:00-03:00",
        "ends_at": "2026-10-20T10:00:00-03:00",
        "thank_you_message": null,
        "public_url": null,
        "responses_count": 1,
        "questions": [
            {
                "key": "field_9b2f6c1e-3a4d-4b8e-a1c2-7d5e6f708192",
                "name": "string",
                "description": null,
                "type": "radio",
                "required": true,
                "options": [
                    "string"
                ]
            }
        ],
        "created_at": "2026-10-20T10:00:00-03:00",
        "updated_at": "2026-10-20T10:00:00-03:00"
    }
}

Respostas possíveis

200 Enquete atualizada401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado422 Dados inválidos429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

POST /api/v1/surveys/{survey}/enable

Reativa uma enquete desativada

Exige `surveys:write` e a permissão Enquetes (desabilitar). Volta a receber respostas dentro do período. Enquete já ativa responde 409 `invalid_transition`.

Exemplo de requisição

cURL

curl -X POST "$MICORE_BASE_URL/surveys/{survey}/enable" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 1,
        "name": "string",
        "description": null,
        "state": "open",
        "active": true,
        "audience": "team",
        "anonymous": true,
        "allow_multiple": true,
        "starts_at": "2026-10-20T10:00:00-03:00",
        "ends_at": "2026-10-20T10:00:00-03:00",
        "thank_you_message": null,
        "public_url": null,
        "responses_count": 1,
        "questions": [
            {
                "key": "field_9b2f6c1e-3a4d-4b8e-a1c2-7d5e6f708192",
                "name": "string",
                "description": null,
                "type": "radio",
                "required": true,
                "options": [
                    "string"
                ]
            }
        ],
        "created_at": "2026-10-20T10:00:00-03:00",
        "updated_at": "2026-10-20T10:00:00-03:00"
    }
}

Respostas possíveis

200 Enquete reativada401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado409 Chave em processamento ou reutilizada com outro conteúdo, ou ação não permitida no estado atual do recurso (`invalid_transition`)429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

POST /api/v1/surveys/{survey}/disable

Desativa uma enquete

Exige `surveys:write` e a permissão Enquetes (desabilitar). Para de receber respostas, inclusive pelo link público; o que já foi respondido continua no resultado. Enquete já desativada responde 409 `invalid_transition`.

Exemplo de requisição

cURL

curl -X POST "$MICORE_BASE_URL/surveys/{survey}/disable" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 1,
        "name": "string",
        "description": null,
        "state": "open",
        "active": true,
        "audience": "team",
        "anonymous": true,
        "allow_multiple": true,
        "starts_at": "2026-10-20T10:00:00-03:00",
        "ends_at": "2026-10-20T10:00:00-03:00",
        "thank_you_message": null,
        "public_url": null,
        "responses_count": 1,
        "questions": [
            {
                "key": "field_9b2f6c1e-3a4d-4b8e-a1c2-7d5e6f708192",
                "name": "string",
                "description": null,
                "type": "radio",
                "required": true,
                "options": [
                    "string"
                ]
            }
        ],
        "created_at": "2026-10-20T10:00:00-03:00",
        "updated_at": "2026-10-20T10:00:00-03:00"
    }
}

Respostas possíveis

200 Enquete desativada401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado409 Chave em processamento ou reutilizada com outro conteúdo, ou ação não permitida no estado atual do recurso (`invalid_transition`)429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

GET /api/v1/surveys/{survey}/results

Resultado consolidado da enquete

Exige `surveys:read`. Para cada pergunta da versão atual: quantos responderam, total e percentual de cada opção (sobre quem respondeu a pergunta) e os textos mais recentes. Respostas dadas em versões anteriores do formulário contam na mesma pergunta pela chave; opções que saíram do formulário aparecem no fim com `removed: true`.

Exemplo de requisição

cURL

curl "$MICORE_BASE_URL/surveys/{survey}/results" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "survey_id": 4,
        "total": 2,
        "questions": [
            {
                "id": 51,
                "key": "field_9b2f6c1e-3a4d-4b8e-a1c2-7d5e6f708192",
                "name": "Você recomendaria a loja?",
                "type": "radio",
                "required": true,
                "answered": 2,
                "options": [
                    {
                        "name": "Sim",
                        "count": 1,
                        "percent": 50,
                        "removed": false
                    },
                    {
                        "name": "Não",
                        "count": 1,
                        "percent": 50,
                        "removed": false
                    },
                    {
                        "name": "Talvez",
                        "count": 0,
                        "percent": 0,
                        "removed": false
                    }
                ],
                "texts": []
            },
            {
                "id": 52,
                "key": "field_1c3e5a7b-9d0f-4e2a-8b6c-4d2e0f1a3b5c",
                "name": "O que podemos melhorar?",
                "type": "textarea",
                "required": false,
                "answered": 1,
                "options": [],
                "texts": [
                    "Atendimento rápido e educado."
                ]
            }
        ]
    }
}

Respostas possíveis

200 Resultado401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

GET /api/v1/surveys/{survey}/responses

Lista as respostas da enquete

Exige `surveys:read`. Mais recentes primeiro, cada uma com os valores pergunta a pergunta, na versão do formulário em que foi respondida. Em enquete anônima, `respondent` vem vazio.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`per_page`query	integer	Não	—

Exemplo de requisição

cURL

curl "$MICORE_BASE_URL/surveys/{survey}/responses" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Exemplo de resposta JSON

Resposta · 200

{
    "data": [
        {
            "id": 1,
            "survey_id": 1,
            "channel": "panel",
            "respondent": {
                "name": null,
                "email": null,
                "phone": null
            },
            "answers": [
                {
                    "key": "string",
                    "name": "string",
                    "type": "string",
                    "values": [
                        "string"
                    ]
                }
            ],
            "created_at": "2026-10-20T10:00:00-03:00"
        }
    ],
    "links": [],
    "meta": []
}

Respostas possíveis

200 Página de respostas401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

POST /api/v1/surveys/{survey}/responses

Envia uma resposta para a enquete

Exige `surveys:respond` e a permissão Enquetes (visualizar). `answers` usa a chave de cada pergunta (veja GET /surveys/{survey}); escolha única e texto aceitam um texto, múltipla escolha aceita uma lista. Valem as mesmas regras do painel e do link: obrigatórias, condicionais e opções existentes (422 em `answers.{key}`). Enquete desativada, agendada ou encerrada responde 409 `invalid_transition`. Quando a enquete aceita uma resposta por pessoa, `respondent.reference` (seu identificador do cliente, por exemplo) barra a segunda resposta com 409; sem referência, não há como barrar repetição. Perguntas de arquivo não são respondidas pela API.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`Idempotency-Key`header	string	Sim	Identificador único da mutação, com 8 a 100 caracteres. O resultado fica reutilizável por 24 horas e a chave não pode ser reutilizada depois de expirar.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`answers`	object	Sim	Chave da pergunta => texto (escolha única, lista e texto) ou lista de textos (múltipla escolha).
`respondent`	object	Não	—

Exemplo de requisição

cURL

curl -X POST "$MICORE_BASE_URL/surveys/{survey}/responses" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: board-request-0001" \
  -H "Content-Type: application/json" \
  -d '{"answers":[],"respondent":{"name":null,"email":null,"phone":null,"reference":null}}'

Exemplo de resposta JSON

Resposta · 201

{
    "data": {
        "id": 1,
        "survey_id": 1,
        "channel": "panel",
        "respondent": {
            "name": null,
            "email": null,
            "phone": null
        },
        "answers": [
            {
                "key": "string",
                "name": "string",
                "type": "string",
                "values": [
                    "string"
                ]
            }
        ],
        "created_at": "2026-10-20T10:00:00-03:00"
    }
}

Respostas possíveis

201 Resposta gravada ou reapresentada pela mesma chave idempotente401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado409 Chave em processamento ou reutilizada com outro conteúdo, ou ação não permitida no estado atual do recurso (`invalid_transition`)422 Dados inválidos429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

GET /api/v1/surveys/{survey}/responses/{response}

Consulta uma resposta da enquete

Exige `surveys:read`. Resposta de outra enquete responde 404.

Exemplo de requisição

cURL

curl "$MICORE_BASE_URL/surveys/{survey}/responses/{response}" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 1,
        "survey_id": 1,
        "channel": "panel",
        "respondent": {
            "name": null,
            "email": null,
            "phone": null
        },
        "answers": [
            {
                "key": "string",
                "name": "string",
                "type": "string",
                "values": [
                    "string"
                ]
            }
        ],
        "created_at": "2026-10-20T10:00:00-03:00"
    }
}

Respostas possíveis

200 Resposta401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant