Skip to content

Pesquisas ​

Endpoints para consulta de pesquisas disponíveis.

Listar Pesquisas ​

GET /api/searches

Retorna a lista de pesquisas vinculadas ao token do usuário.

Casos de uso:

  • Obter IDs de pesquisas para integração
  • Popular seletores de pesquisa
  • Validar pesquisas disponíveis para disparo

Exemplo de Requisição ​

bash
curl -X GET "https://api-b2s.experienciab2s.com/api/searches" \
     -H "Authorization: Bearer SEU_TOKEN"

Resposta de Sucesso (200) ​

json
[
  {
    "id": "103a525c-0ce3-4182-a504-aad595425233",
    "name": "Pesquisa de Satisfação - Restaurante",
    "company_id": "603a525c-0ce3-4182-a504-aad595425233"
  },
  {
    "id": "203a525c-0ce3-4182-a504-aad595425233",
    "name": "Pesquisa de Satisfação - Delivery",
    "company_id": "503a525c-0ce3-4182-a504-aad595425233"
  }
]

Estrutura da Resposta ​

CampoTipoDescrição
idstringID único da pesquisa (UUID)
namestringNome da pesquisa
company_idstringID da empresa vinculada (UUID)

Códigos de Resposta ​

CódigoDescrição
200Pesquisas encontradas
401Token ausente ou inválido
403Token inválido ou usuário não autorizado
404Token de integração não encontrado

Obter Pesquisa com Questões ​

GET /api/searches/:id

Retorna os detalhes completos de uma pesquisa, incluindo todas as questões com suporte a múltiplos idiomas. A estrutura da resposta varia conforme o valor de has_page:

  • has_page: false: As questões são retornadas diretamente no campo questions
  • has_page: true: As questões são organizadas dentro de páginas no campo pages

Casos de uso:

  • Renderizar formulário de pesquisa customizado
  • Obter estrutura completa de questões para integração
  • Carregar traduções das questões para sistemas multilíngue
  • Validar tipos e formatos de questões antes do envio

Parâmetros de URL ​

ParâmetroTipoObrigatórioDescrição
idstringSimID único da pesquisa (UUID)

Exemplo de Requisição ​

bash
curl -X GET "https://api-b2s.experienciab2s.com/api/searches/103a525c-0ce3-4182-a504-aad595425233" \
     -H "Authorization: Bearer SEU_TOKEN"

Resposta de Sucesso (200) - Sem Páginas ​

Quando has_page é false, as questões são retornadas diretamente:

json
{
  "has_page": false,
  "translations": [
    {
      "language_code": "pt-BR",
      "nps": "Como você avalia sua experiência?",
      "discursive_question": "Deixe seu comentário",
      "question_page": "Em qual salão você se encontra?"
    },
    {
      "language_code": "en-US",
      "nps": "How do you rate your experience?",
      "discursive_question": "Leave your comment",
      "question_page": "Which salon are you at?"
    }
  ],
  "questions": [
    {
      "id": "q1-uuid-example",
      "required": true,
      "others": false,
      "unknown": false,
      "type": "Resposta curta",
      "format": "default",
      "options": [],
      "translations": [
        {
          "language_code": "pt-BR",
          "name": "Qual seu nome completo?",
          "description": "Informe seu nome para identificação"
        },
        {
          "language_code": "en-US",
          "name": "What is your full name?",
          "description": "Enter your name for identification"
        }
      ]
    },
    {
      "id": "q2-uuid-example",
      "required": false,
      "others": false,
      "unknown": false,
      "type": "Rating",
      "format": "default",
      "options": [
        {
          "id": "opt1-uuid",
          "translations": [
            {
              "language_code": "pt-BR",
              "name": "Excelente"
            },
            {
              "language_code": "en-US",
              "name": "Excellent"
            }
          ]
        },
        {
          "id": "opt2-uuid",
          "translations": [
            {
              "language_code": "pt-BR",
              "name": "Bom"
            },
            {
              "language_code": "en-US",
              "name": "Good"
            }
          ]
        }
      ],
      "translations": [
        {
          "language_code": "pt-BR",
          "name": "Como você avalia o atendimento?",
          "description": "Avalie a qualidade do atendimento recebido",
          "detractor_replica": "Lamentamos pela sua experiência",
          "neutral_replica": "Obrigado pelo feedback",
          "promoter_replica": "Ficamos felizes com sua avaliação!"
        },
        {
          "language_code": "en-US",
          "name": "How do you rate the service?",
          "description": "Rate the quality of the service received",
          "detractor_replica": "We're sorry for your experience",
          "neutral_replica": "Thank you for your feedback",
          "promoter_replica": "We're happy with your rating!"
        }
      ]
    }
  ]
}

Resposta de Sucesso (200) - Com Páginas ​

Quando has_page é true, as questões são organizadas em páginas:

json
{
  "has_page": true,
  "translations": [
    {
      "language_code": "pt-BR",
      "nps": "Como você avalia sua experiência?",
      "discursive_question": "Deixe seu comentário",
      "question_page": "Em qual salão você se encontra?"
    },
    {
      "language_code": "en-US",
      "nps": "How do you rate your experience?",
      "discursive_question": "Leave your comment",
      "question_page": "Which salon are you at?"
    }
  ],
  "pages": [
    {
      "id": "page1-uuid-example",
      "translations": [
        {
          "language_code": "pt-BR",
          "name": "Dados Pessoais"
        },
        {
          "language_code": "en-US",
          "name": "Personal Data"
        }
      ],
      "questions": [
        {
          "id": "q1-uuid-example",
          "required": true,
          "others": false,
          "unknown": false,
          "type": "Resposta curta",
          "format": "default",
          "options": [],
          "translations": [
            {
              "language_code": "pt-BR",
              "name": "Qual seu nome completo?",
              "description": "Informe seu nome para identificação"
            },
            {
              "language_code": "en-US",
              "name": "What is your full name?",
              "description": "Enter your name for identification"
            }
          ]
        }
      ]
    },
    {
      "id": "page2-uuid-example",
      "translations": [
        {
          "language_code": "pt-BR",
          "name": "Avaliação do Atendimento"
        },
        {
          "language_code": "en-US",
          "name": "Service Evaluation"
        }
      ],
      "questions": [
        {
          "id": "q2-uuid-example",
          "required": true,
          "others": false,
          "unknown": false,
          "type": "Rating",
          "format": "default",
          "options": [
            {
              "id": "opt1-uuid",
              "translations": [
                {
                  "language_code": "pt-BR",
                  "name": "Excelente"
                },
                {
                  "language_code": "en-US",
                  "name": "Excellent"
                }
              ]
            },
            {
              "id": "opt2-uuid",
              "translations": [
                {
                  "language_code": "pt-BR",
                  "name": "Bom"
                },
                {
                  "language_code": "en-US",
                  "name": "Good"
                }
              ]
            }
          ],
          "translations": [
            {
              "language_code": "pt-BR",
              "name": "Como você avalia o atendimento?",
              "description": "Avalie a qualidade do atendimento recebido",
              "detractor_replica": "Lamentamos pela sua experiência",
              "neutral_replica": "Obrigado pelo feedback",
              "promoter_replica": "Ficamos felizes com sua avaliação!"
            },
            {
              "language_code": "en-US",
              "name": "How do you rate the service?",
              "description": "Rate the quality of the service received",
              "detractor_replica": "We're sorry for your experience",
              "neutral_replica": "Thank you for your feedback",
              "promoter_replica": "We're happy with your rating!"
            }
          ]
        }
      ]
    }
  ]
}

Estrutura da Resposta ​

CampoTipoDescrição
has_pagebooleanIndica se a pesquisa possui múltiplas páginas
translationsarrayTraduções dos textos principais da pesquisa
questionsarrayLista de questões (apenas quando has_page: false)
pagesarrayLista de páginas com questões (apenas quando has_page: true)

Objeto translations (da pesquisa) ​

CampoTipoDescrição
language_codestringCódigo do idioma (ex: "pt-BR", "en-US", "es-ES")
npsstringTexto da pergunta NPS principal
discursive_questionstringTexto da pergunta discursiva/comentário
question_pagestringTexto da pergunta para seleção de página

Estrutura de Page ​

CampoTipoDescrição
idstringID único da página (UUID)
translationsarrayTraduções do nome da página
questionsarrayLista de questões da página

Objeto translations (da página) ​

CampoTipoDescrição
language_codestringCódigo do idioma (ex: "pt-BR", "en-US")
namestringNome/título da página

Estrutura de Question ​

CampoTipoDescrição
idstringID único da questão (UUID)
requiredbooleanSe a questão é obrigatória
othersbooleanSe permite opção "Outros"
unknownbooleanSe permite opção "Não sei/Desconhecido"
typestringTipo da questão (ver tabela abaixo)
formatstringFormato de exibição (ver tabela abaixo)
optionsarrayOpções de resposta disponíveis
translationsarrayTraduções da questão em diferentes idiomas

Tipos de Questão (type) ​

TipoDescrição
AtendenteSeleção de atendente/funcionário
Caixa de seleçãoMúltipla escolha com checkboxes
CSATCustomer Satisfaction Score (1-5)
DataCampo de seleção de data
EmoticonAvaliação por emoticons/emojis
Like/DislikeAvaliação binária (gostei/não gostei)
Multipla escolhaSeleção entre múltiplas opções
NPSNet Promoter Score (0-10)
RatingAvaliação por estrelas/nota
Resposta curtaCampo de texto livre

Formatos de Exibição (format) ​

FormatoDescriçãoDisponível em
defaultExibição padrão (botões/cards)Todos os tipos
selectMenu suspenso (dropdown)Atendente, Múltipla escolha
checkboxCaixa de seleção múltiplaAtendente

Objeto translations (da questão) ​

CampoTipoDescrição
language_codestringCódigo do idioma (ex: "pt-BR", "en-US")
namestringTexto traduzido da questão
descriptionstringDescrição traduzida (opcional)
promoter_replicastringResposta para notas altas (opcional)
neutral_replicastringResposta para notas médias (opcional)
detractor_replicastringResposta para notas baixas (opcional)
criteriastringCritério traduzido (opcional)

Estrutura de Option ​

CampoTipoDescrição
idstringID único da opção (UUID)
translationsarrayTraduções da opção em outros idiomas

Objeto translations (da opção) ​

CampoTipoDescrição
language_codestringCódigo do idioma (ex: "pt-BR", "en-US")
namestringTexto traduzido da opção

Códigos de Resposta ​

CódigoDescrição
200Pesquisa encontrada com sucesso
401Token ausente ou inválido
403Token inválido ou usuário não autorizado
404Pesquisa não encontrada

Fluxo Recomendado para Integração ​

  1. Buscar pesquisa: GET /api/searches/:id
  2. Selecionar idioma: Filtrar traduções pelo language_code desejado
  3. Verificar has_page:
    • Se false: Iterar diretamente sobre questions
    • Se true: Exibir seleção de página e iterar sobre pages[].questions
  4. Renderizar questões: Usar translations para exibir no idioma correto

Documentação oficial de integrações da plataforma Falaê.