Encuestas

Endpoints para consulta de encuestas disponibles.

Listar Encuestas

GET /api/searches

Retorna la lista de encuestas vinculadas al token del usuario.

Casos de uso:

Obtener IDs de encuestas para integración
Popular selectores de encuesta
Validar encuestas disponibles para disparo

Ejemplo de Solicitud

bash

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

Respuesta Exitosa (200)

json

[
  {
    "id": "103a525c-0ce3-4182-a504-aad595425233",
    "name": "Encuesta de Satisfacción - Restaurante",
    "company_id": "603a525c-0ce3-4182-a504-aad595425233"
  },
  {
    "id": "203a525c-0ce3-4182-a504-aad595425233",
    "name": "Encuesta de Satisfacción - Delivery",
    "company_id": "503a525c-0ce3-4182-a504-aad595425233"
  }
]

Estructura de la Respuesta

Campo	Tipo	Descripción
`id`	string	ID único de la encuesta (UUID)
`name`	string	Nombre de la encuesta
`company_id`	string	ID de la empresa vinculada (UUID)

Códigos de Respuesta

Código	Descripción
200	Encuestas encontradas
401	Token ausente o inválido
403	Token inválido o usuario no autorizado
404	Token de integración no encontrado

Obtener Encuesta con Preguntas

GET /api/searches/:id

Retorna los detalles completos de una encuesta, incluyendo todas las preguntas con soporte multiidioma. La estructura de la respuesta varía según el valor de has_page:

has_page: false: Las preguntas se retornan directamente en el campo questions
has_page: true: Las preguntas están organizadas dentro de páginas en el campo pages

Casos de uso:

Renderizar formulario de encuesta personalizado
Obtener estructura completa de preguntas para integración
Cargar traducciones de las preguntas para sistemas multilingües
Validar tipos y formatos de preguntas antes del envío

Parámetros de URL

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID único de la encuesta (UUID)

Ejemplo de Solicitud

bash

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

Respuesta Exitosa (200) - Sin Páginas

Cuando has_page es false, las preguntas se retornan directamente:

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": "es-ES",
      "nps": "¿Cómo califica su experiencia?",
      "discursive_question": "Deje su comentario",
      "question_page": "¿En qué salón se encuentra?"
    }
  ],
  "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": "es-ES",
          "name": "¿Cuál es su nombre completo?",
          "description": "Ingrese su nombre para identificación"
        }
      ]
    },
    {
      "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": "es-ES",
              "name": "Excelente"
            }
          ]
        },
        {
          "id": "opt2-uuid",
          "translations": [
            {
              "language_code": "pt-BR",
              "name": "Bom"
            },
            {
              "language_code": "es-ES",
              "name": "Bueno"
            }
          ]
        }
      ],
      "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": "es-ES",
          "name": "¿Cómo califica la atención?",
          "description": "Evalúe la calidad de la atención recibida",
          "detractor_replica": "Lamentamos su experiencia",
          "neutral_replica": "Gracias por su feedback",
          "promoter_replica": "¡Estamos felices con su calificación!"
        }
      ]
    }
  ]
}

Respuesta Exitosa (200) - Con Páginas

Cuando has_page es true, las preguntas están organizadas en 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": "es-ES",
      "nps": "¿Cómo califica su experiencia?",
      "discursive_question": "Deje su comentario",
      "question_page": "¿En qué salón se encuentra?"
    }
  ],
  "pages": [
    {
      "id": "page1-uuid-example",
      "translations": [
        {
          "language_code": "pt-BR",
          "name": "Dados Pessoais"
        },
        {
          "language_code": "es-ES",
          "name": "Datos Personales"
        }
      ],
      "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": "es-ES",
              "name": "¿Cuál es su nombre completo?",
              "description": "Ingrese su nombre para identificación"
            }
          ]
        }
      ]
    },
    {
      "id": "page2-uuid-example",
      "translations": [
        {
          "language_code": "pt-BR",
          "name": "Avaliação do Atendimento"
        },
        {
          "language_code": "es-ES",
          "name": "Evaluación del Servicio"
        }
      ],
      "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": "es-ES",
                  "name": "Excelente"
                }
              ]
            },
            {
              "id": "opt2-uuid",
              "translations": [
                {
                  "language_code": "pt-BR",
                  "name": "Bom"
                },
                {
                  "language_code": "es-ES",
                  "name": "Bueno"
                }
              ]
            }
          ],
          "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": "es-ES",
              "name": "¿Cómo califica la atención?",
              "description": "Evalúe la calidad de la atención recibida",
              "detractor_replica": "Lamentamos su experiencia",
              "neutral_replica": "Gracias por su feedback",
              "promoter_replica": "¡Estamos felices con su calificación!"
            }
          ]
        }
      ]
    }
  ]
}

Estructura de la Respuesta

Campo	Tipo	Descripción
`has_page`	boolean	Indica si la encuesta tiene múltiples páginas
`translations`	array	Traducciones de los textos principales de la encuesta
`questions`	array	Lista de preguntas (solo cuando `has_page: false`)
`pages`	array	Lista de páginas con preguntas (solo cuando `has_page: true`)

Objeto `translations` (de la encuesta)

Campo	Tipo	Descripción
`language_code`	string	Código del idioma (ej: "pt-BR", "en-US", "es-ES")
`nps`	string	Texto de la pregunta NPS principal
`discursive_question`	string	Texto de la pregunta discursiva/comentario
`question_page`	string	Texto de la pregunta para selección de página

Estructura de Page

Campo	Tipo	Descripción
`id`	string	ID único de la página (UUID)
`translations`	array	Traducciones del nombre de la página
`questions`	array	Lista de preguntas de la página

Objeto `translations` (de la página)

Campo	Tipo	Descripción
`language_code`	string	Código del idioma (ej: "pt-BR", "es-ES")
`name`	string	Nombre/título de la página

Estructura de Question

Campo	Tipo	Descripción
`id`	string	ID único de la pregunta (UUID)
`required`	boolean	Si la pregunta es obligatoria
`others`	boolean	Si permite opción "Otros"
`unknown`	boolean	Si permite opción "No sé/Desconocido"
`type`	string	Tipo de pregunta (ver tabla abajo)
`format`	string	Formato de visualización (ver tabla abajo)
`options`	array	Opciones de respuesta disponibles
`translations`	array	Traducciones de la pregunta en diferentes idiomas

Tipos de Pregunta (type)

Tipo	Descripción
`Atendente`	Selección de empleado/funcionario
`Caixa de seleção`	Opción múltiple con checkboxes
`CSAT`	Customer Satisfaction Score (1-5)
`Data`	Campo de selección de fecha
`Emoticon`	Evaluación por emoticones/emojis
`Like/Dislike`	Evaluación binaria (me gusta/no me gusta)
`Multipla escolha`	Selección entre múltiples opciones
`NPS`	Net Promoter Score (0-10)
`Rating`	Evaluación por estrellas/puntuación
`Resposta curta`	Campo de texto libre

Formatos de Visualización (format)

Formato	Descripción	Disponible en
`default`	Visualización estándar (botones)	Todos los tipos
`select`	Menú desplegable (dropdown)	Atendente, Multipla escolha
`checkbox`	Casilla de selección múltiple	Atendente

Objeto `translations` (de la pregunta)

Campo	Tipo	Descripción
`language_code`	string	Código del idioma (ej: "pt-BR", "es-ES")
`name`	string	Texto traducido de la pregunta
`description`	string	Descripción traducida (opcional)
`promoter_replica`	string	Respuesta para notas altas (opcional)
`neutral_replica`	string	Respuesta para notas medias (opcional)
`detractor_replica`	string	Respuesta para notas bajas (opcional)
`criteria`	string	Criterio traducido (opcional)

Estructura de Option

Campo	Tipo	Descripción
`id`	string	ID único de la opción (UUID)
`translations`	array	Traducciones de la opción en otros idiomas

Objeto `translations` (de la opción)

Campo	Tipo	Descripción
`language_code`	string	Código del idioma (ej: "pt-BR", "es-ES")
`name`	string	Texto traducido de la opción

Códigos de Respuesta

Código	Descripción
200	Encuesta encontrada exitosamente
401	Token ausente o inválido
403	Token inválido o usuario no autorizado
404	Encuesta no encontrada

Flujo Recomendado para Integración

Buscar encuesta: GET /api/searches/:id
Seleccionar idioma: Filtrar traducciones por el language_code deseado
Verificar has_page:
- Si es false: Iterar directamente sobre questions
- Si es true: Mostrar selección de página e iterar sobre pages[].questions
Renderizar preguntas: Usar translations para mostrar en el idioma correcto

Encuestas ​

Listar Encuestas ​

Ejemplo de Solicitud ​

Respuesta Exitosa (200) ​

Estructura de la Respuesta ​

Códigos de Respuesta ​

Obtener Encuesta con Preguntas ​

Parámetros de URL ​

Ejemplo de Solicitud ​

Respuesta Exitosa (200) - Sin Páginas ​

Respuesta Exitosa (200) - Con Páginas ​

Estructura de la Respuesta ​

Objeto translations (de la encuesta) ​

Estructura de Page ​

Objeto translations (de la página) ​

Estructura de Question ​

Tipos de Pregunta (type) ​

Formatos de Visualización (format) ​

Objeto translations (de la pregunta) ​

Estructura de Option ​

Objeto translations (de la opción) ​

Códigos de Respuesta ​

Flujo Recomendado para Integración ​

Encuestas

Listar Encuestas

Ejemplo de Solicitud

Respuesta Exitosa (200)

Estructura de la Respuesta

Códigos de Respuesta

Obtener Encuesta con Preguntas

Parámetros de URL

Ejemplo de Solicitud

Respuesta Exitosa (200) - Sin Páginas

Respuesta Exitosa (200) - Con Páginas

Estructura de la Respuesta

Objeto `translations` (de la encuesta)

Estructura de Page

Objeto `translations` (de la página)

Estructura de Question

Tipos de Pregunta (type)

Formatos de Visualización (format)

Objeto `translations` (de la pregunta)

Estructura de Option

Objeto `translations` (de la opción)

Códigos de Respuesta

Flujo Recomendado para Integración