# Opiny - Guia de Integração para Modelos de Linguagem

## Visão Geral
A Opiny é uma plataforma de coleta de feedback e pesquisas (NPS, Satisfação, Bugs) com análise de sentimento integrada via Inteligência Artificial. Esta API permite listar pesquisas, obter detalhes estruturais de formulários e extrair respostas brutas com metadados e scores de IA.

## Autenticação
- Método: Bearer Token
- Disponibilidade: Plano PRO.
- Header Obrigatório: Authorization: Bearer op_live_{SUA_CHAVE_AQUI}

## Base URL
https://api-clients.opiny.com.br/v1

---

## Endpoints Principais

### 1. Pesquisas (Surveys)

#### Listar Pesquisas
Retorna uma lista paginada de todas as pesquisas da organização com métricas básicas.

- Endpoint: GET /surveys
- Parâmetros de Query:
  - page (number, opcional): Padrão 1.
  - limit (number, opcional): Padrão 10.
  - status (string, opcional): active, draft, paused, archived.

Exemplo de Requisição (cURL):
curl --request GET \
  --url "https://api-clients.opiny.com.br/v1/surveys?page=1&limit=10&status=active" \
  --header "accept: application/json" \
  --header "authorization: Bearer op_live_123456"

Exemplo de Resposta (JSON):
{
  "data": [
    {
      "id": "cmjt5c5d00003jr0wngf8kjga",
      "name": "Pesquisa de Satisfação Q3",
      "status": "active",
      "created_at": "2025-10-15T14:30:00.000Z",
      "metrics": {
        "views": 1250,
        "responses": 450,
        "sentiment_score": 85,
        "sentiment_label": "POSITIVE"
      }
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}

#### Obter Detalhes da Pesquisa
Retorna a estrutura completa, incluindo perguntas e análise de IA.

- Endpoint: GET /surveys/{id}
- Parâmetros de Path:
  - id (string): O Survey ID.

Exemplo de Requisição (cURL):
curl --request GET \
  --url "https://api-clients.opiny.com.br/v1/surveys/cmjt5c5d00003jr0wngf8kjga" \
  --header "accept: application/json" \
  --header "authorization: Bearer op_live_123456"

Exemplo de Resposta (JSON):
{
  "id": "cmjt5c5d00003jr0wngf8kjga",
  "name": "Pesquisa de Satisfação Q3",
  "status": "active",
  "created_at": "2025-10-15T14:30:00.000Z",
  "ai_analysis": {
    "score": 85,
    "sentiment": "POSITIVE",
    "summary": "Os usuários elogiaram a nova interface, mas relataram lentidão no checkout."
  },
  "questions": [
    {
      "id": "q_123",
      "type": "NPS",
      "label": "Qual a probabilidade de nos recomendar?",
      "step": 1,
      "options": []
    },
    {
      "id": "q_456",
      "type": "SINGLE_CHOICE",
      "label": "Qual seu motivo de contato?",
      "step": 2,
      "options": ["Suporte", "Vendas", "Financeiro"]
    }
  ]
}

### 2. Respostas (Responses)

#### Listar Respostas
Extrai feedbacks brutos, metadados e análise de sentimento.

- Endpoint: GET /responses
- Parâmetros de Query:
  - survey_id (string, opcional)
  - start_date (string, ISO 8601 YYYY-MM-DD)
  - end_date (string, ISO 8601 YYYY-MM-DD)
  - page, limit (number)

Exemplo de Requisição (cURL):
curl --request GET \
  --url "https://api-clients.opiny.com.br/v1/responses?survey_id=cmjt5c5d00003jr0wngf8kjga" \
  --header "accept: application/json" \
  --header "authorization: Bearer op_live_123456"

Exemplo de Resposta (JSON):
{
  "data": [
    {
      "id": "res_987654",
      "survey_id": "cmjt5c5d00003jr0wngf8kjga",
      "survey_name": "Pesquisa de Satisfação Q3",
      "visitor_id": "vis_abcdef",
      "created_at": "2025-11-20T10:00:00.000Z",
      "metadata": {
        "user_id": "u_999",
        "plan": "premium"
      },
      "sentiment": "POSITIVE",
      "sentiment_score": 90,
      "answers": [
        {
          "question_id": "q_123",
          "question_label": "Qual a probabilidade de nos recomendar?",
          "question_type": "NPS",
          "value": "10"
        },
        {
          "question_id": "q_124",
          "question_label": "Deixe um comentário",
          "question_type": "OPEN_TEXT",
          "value": "Adorei o atendimento rápido!"
        }
      ]
    }
  ],
  "meta": { "total": 150, "page": 1, "limit": 20 }
}

---

## Webhooks

Notificações em tempo real via POST.

- Evento Suportado: response.created
- Header de Segurança: X-Opiny-Signature (HMAC SHA256 do body usando a chave secreta).

Payload do Evento (JSON):
{
  "id": "evt_uuid_v4",
  "event": "response.created",
  "created_at": "2025-11-20T10:00:00.000Z",
  "data": { 
    // Objeto Response completo (ver estrutura acima em 'Listar Respostas')
  }
}

---

## Tipos de Pergunta (Reference)

Lista de valores possíveis para o campo 'type' ou 'question_type':

- NPS: Net Promoter Score (0-10).
- RATING_STARS: Avaliação de 1 a 5 estrelas.
- RATING_SMILEY: Avaliação de 1 a 5 emojis.
- OPEN_TEXT: Campo de texto livre.
- SINGLE_CHOICE: Seleção única (Radio).
- MULTIPLE_CHOICE: Seleção múltipla (Checkbox).
- EMAIL: Validação de e-mail.
- DATE: Seletor de data.
- NUMBER: Input numérico.
- BUG_REPORT: Texto com screenshot automática anexada.