API Documentation - Satisfacao.app

Autenticação

A API utiliza chaves de acesso (API Keys) geradas exclusivamente pelo administrador da plataforma. Envie sua chave no header de todas as requisições autenticadas.

● Como obter sua API Key

Crie uma conta em satisfacao.app e confirme seu e-mail
Solicite a ativação do acesso à API abrindo um chamado interno pelo painel administrativo
O administrador gera uma chave exclusiva para voce no painel administrativo
Utilize a chave no header X-API-Key de todas as requisições

● Exemplo de requisicao

cURL

curl -X GET https://satisfacao.app/api/v1/surveys \
  -H "X-API-Key: sua_chave_aqui" \
  -H "Accept: application/json"

● Erros de autenticacao

Sem chave401

{
  "message": "API key required. Use header X-API-Key."
}

Chave invalida401

{
  "message": "Invalid or expired API key."
}

Importante: A API Key está vinculada à sua conta. Todas as operações (criar pesquisas, ver respostas) sao executadas no contexto do seu usuário. Não compartilhe sua chave. Caso suspeite de vazamento, solicite ao administrador a revogação e geração de uma nova chave.

Headers obrigatórios

Header	Valor		Descrição
X-API-Key	string	obrigatório	Sua chave de API (48 caracteres)
Accept	string	recomendado	`application/json`
Content-Type	string	POST/PUT	`application/json`

Pesquisas

Gerencie pesquisas de satisfação. Todas as rotas requerem X-API-Key. Pesquisas são identificadas por UUID.

GET /api/v1/surveys API Key Listar pesquisas ▶

Retorna todas as pesquisas do usuário autenticado.

Resposta

JSON200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-...",
      "title": "Satisfacao no Atendimento",
      "status": "published",
      "url": "https://satisfacao.app/s/a1b2c3d4",
      "questions_count": 8,
      "responses_count": 342,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

GET /api/v1/surveys/{uuid} API Key Detalhes da pesquisa ▶

Retorna detalhes de uma pesquisa específica com questões.

POST /api/v1/surveys API Key Criar pesquisa ▶

Cria uma nova pesquisa. Requer assinatura ativa e limite de pesquisas não atingido.

Parâmetros

Campo	Tipo		Descrição
title	string	obrigatório	Título da pesquisa (max 255)
welcome_message	string	opcional	Mensagem de boas-vindas
goodbye_text	string	opcional	Mensagem de agradecimento
visibility	boolean	opcional	Publicar imediatamente (default: false)

PUT /api/v1/surveys/{uuid} API Key Atualizar pesquisa ▶

Atualiza uma pesquisa existente. Apenas o dono pode atualizar.

DEL /api/v1/surveys/{uuid} API Key Deletar pesquisa ▶

Remove permanentemente uma pesquisa e todas as suas questões e respostas.

POST /api/v1/surveys/{uuid}/duplicate API Key Duplicar pesquisa ▶

Cria uma copia da pesquisa com todas as questões. A copia inicia como rascunho com zero respostas.

Questoes

Gerencie questões dentro de uma pesquisa. Tipos disponíveis: multiple-choices, yes-no, rating, dropdown, short-text, long-text, email, phone, date, number, slider, nps, csat, ces

GET /api/v1/surveys/{uuid}/questions API Key Listar questões ▶

Retorna todas as questões da pesquisa ordenadas por posição.

Resposta

JSON200 OK

{
  "data": [
    {
      "id": 1,
      "type": "nps",
      "text": "De 0 a 10, quanto voce recomendaria?",
      "position": 1,
      "is_required": true,
      "attributes": { "scale": 10 }
    }
  ]
}

POST /api/v1/surveys/{uuid}/questions API Key Criar questão ▶

Adiciona uma questão à pesquisa. Requer limite de questões não atingido.

Parâmetros

Campo	Tipo		Descrição
text	string	obrigatório	Texto da questão
type	string	obrigatório	Tipo (ver lista acima)
position	integer	opcional	Ordem de exibicao
is_required	boolean	opcional	Resposta obrigatoria (default: false)
attributes	object	opcional	Configuracoes especificas do tipo (choices, scale, etc.)

PUT /api/v1/surveys/{uuid}/questions/{id} API Key Atualizar questão ▶

Atualiza uma questão existente.

DEL /api/v1/surveys/{uuid}/questions/{id} API Key Deletar questão ▶

Remove uma questão e todas as respostas associadas.

Respostas

Colete e consulte respostas de pesquisas. A submissao e publica (nao requer autenticacao).

GET /api/v1/surveys/{uuid}/responses API Key Listar respostas ▶

Retorna todas as respostas de uma pesquisa agrupadas por respondente.

POST /api/v1/surveys/{uuid}/responses Público Submeter respostas ▶

Submete respostas para uma pesquisa. Rate limit: 10 requisições/minuto por IP.

Parâmetros

Campo	Tipo		Descrição
responses	object	obrigatório	Mapa question_id → resposta

Exemplo

Request Body

{
  "responses": {
    "1": "9",
    "2": "Atendimento excelente!",
    "3": "Sim"
  }
}

Analytics & Planos

Dados analíticos das pesquisas e planos disponíveis.

GET /api/v1/surveys/{uuid}/analytics API Key Dados analíticos ▶

Retorna métricas da pesquisa: taxa de conclusão, NPS, CSAT, CES e distribuição de respostas por questão.

Resposta

JSON200 OK

{
  "completion_rate": 84.5,
  "total_responses": 342,
  "total_attendees": 405,
  "scores": {
    "nps": { "score": 72, "promoters": 218, "passives": 64, "detractors": 60 },
    "csat": { "score": 88.2 },
    "ces": null
  },
  "questions": [ "..." ]
}

GET /api/v1/plans Público Listar planos ▶

Retorna todos os planos disponíveis com preços e limites.

Resposta

JSON200 OK

{
  "data": [
    {
      "id": 1,
      "title": "Gratuito",
      "price": 0,
      "interval": "monthly",
      "is_free": true,
      "limits": {
        "survey_count": 3,
        "question_count_per_survey": 10,
        "response_count_per_survey": 100
      }
    },
    {
      "id": 2,
      "title": "Starter",
      "price": 49.00,
      "is_free": false,
      "limits": { "..." }
    }
  ]
}

Limites e Erros

Informações sobre rate limiting e códigos de erro.

Rate Limits

Com API Key	60 req/min por chave
Submissão pública	10 req/min por IP
Sem API Key	60 req/min por IP

Códigos de Erro

200 Sucesso

201 Recurso criado

401 Não autenticado

403 Sem permissão

404 Não encontrado

422 Validação falhou

429 Rate limit excedido

Plano Escala

Endpoints exclusivos para assinantes do plano Escala (enterprise). Requerem X-API-Key de um usuário com plano Escala ativo.

Plano Escala — Estes endpoints retornam 403 para usuários em outros planos. Fazer upgrade →

TAGS Tags Dinamicas Personalize pesquisas com dados do seu sistema ▶

Tags dinamicas permitem personalizar o texto da pesquisa para cada destinatario. Use placeholders no formato {{NOME_DA_TAG}} nos campos da pesquisa, e envie os valores correspondentes no campo context da API.

Como Funciona

1

Configure a pesquisa

No painel, crie uma Pesquisa API e use tags nos campos de boas-vindas e perguntas:

Mensagem de boas-vindas: {{NOME_CLIENTE}} - Pesquisa de Satisfacao - Televendas 📦
Pedido: {{NRO_PEDIDO}} 📝

2

Envie via API com o context

No campo context, passe os valores das tags:

Request Body

{
  "channel": "email",
  "recipient": {
    "name": "Joao Silva",
    "email": "joao@email.com"
  },
  "context": {
    "NOME_CLIENTE": "Joao Silva",
    "NRO_PEDIDO": "PED-2026-00142"
  },
  "subject": "{{NOME_CLIENTE}}, como foi seu pedido {{NRO_PEDIDO}}?"
}

3

O destinatario ve a pesquisa personalizada

As tags sao substituidas em todos os lugares:

Joao Silva - Pesquisa de Satisfacao - Televendas 📦
Pedido: PED-2026-00142 📝

Onde as tags funcionam

Campo	Descricao
welcome_message	Mensagem de boas-vindas exibida ao abrir a pesquisa
Texto das perguntas	O texto de cada pergunta da pesquisa
subject	Assunto do e-mail de convite (passado no envio via API)

Regras

Tags usam o formato {{NOME_TAG}} — letras maiusculas e underscores
As tags sao livres: voce pode usar qualquer nome que quiser
Se uma tag nao tiver valor no context, ela sera removida do texto
As tags sao case-sensitive: NOME e nome sao tags diferentes
Cada destinatario recebe um link unico com seus dados personalizados

Tags no Envio em Massa

No endpoint de envio em massa (POST /send/bulk), cada destinatario pode ter seu proprio context:

Bulk com tags individuais

{
  "channel": "email",
  "subject": "{{NOME_CLIENTE}}, avalie seu pedido",
  "recipients": [
    {
      "name": "Joao Silva",
      "email": "joao@email.com",
      "context": {
        "NOME_CLIENTE": "Joao Silva",
        "NRO_PEDIDO": "PED-001"
      }
    },
    {
      "name": "Maria Santos",
      "email": "maria@email.com",
      "context": {
        "NOME_CLIENTE": "Maria Santos",
        "NRO_PEDIDO": "PED-002"
      }
    }
  ]
}

Painel de Acompanhamento

Todos os envios via API sao rastreados e podem ser acompanhados no painel API do dashboard, incluindo:

Status de cada envio (pendente, enviado, entregue, falha)
Dados do context enviado para cada destinatario
Taxa de conclusao (quem abriu e respondeu a pesquisa)
Possibilidade de reenvio para envios que falharam

POST /api/v1/surveys/{uuid}/send Escala Enviar pesquisa ▶

Envia uma pesquisa para um destinatário por e-mail ou WhatsApp. Use o campo context para passar valores das tags dinamicas configuradas na pesquisa. O envio é síncrono.

Parâmetros

Campo	Tipo		Descrição
channel	string	obrigatório	`email` ou `whatsapp`
recipient.name	string	obrigatório	Nome do destinatário
recipient.email	string	se email	E-mail do destinatário
recipient.phone	string	se whatsapp	Telefone internacional (ex: +5511999999999)
context	object	opcional	Dados contextuais livres (chave-valor) para personalizar a mensagem
subject	string	opcional	Assunto do e-mail (ignorado para WhatsApp)

Exemplo

Request Body

{
  "channel": "email",
  "recipient": {
    "name": "Carlos Eduardo",
    "email": "carlos@email.com"
  },
  "context": {
    "NOME_CLIENTE": "Carlos Eduardo",
    "NRO_PEDIDO": "PED-2026-00142"
  },
  "subject": "{{NOME_CLIENTE}}, como foi seu pedido {{NRO_PEDIDO}}?"
}

Resposta

JSON201 Created

{
  "data": {
    "id": 123,
    "channel": "email",
    "recipient": "carlos@email.com",
    "status": "sent",
    "sent_at": "2026-03-18T14:30:00Z",
    "attendee_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Status

201 403 422

POST /api/v1/surveys/{uuid}/send/bulk Escala Envio em massa ▶

Envia pesquisas para múltiplos destinatários de uma vez. Os envios são enfileirados e processados em background. Máximo de 500 destinatários por requisição. Um canal por request.

Parâmetros

Campo	Tipo		Descrição
channel	string	obrigatório	`email` ou `whatsapp`
subject	string	opcional	Assunto do e-mail (aplicado a todos)
recipients	array	obrigatório	Lista de destinatários (max 500)
recipients[].name	string	obrigatório	Nome do destinatário
recipients[].email	string	se email	E-mail do destinatário
recipients[].phone	string	se whatsapp	Telefone internacional
recipients[].context	object	opcional	Dados contextuais por destinatário

Exemplo

Request Body

{
  "channel": "email",
  "subject": "Como foi sua experiência?",
  "recipients": [
    {
      "name": "Carlos Eduardo",
      "email": "carlos@email.com",
      "context": { "NOME_CLIENTE": "Carlos Eduardo", "NRO_PEDIDO": "PED-001" }
    },
    {
      "name": "Maria Silva",
      "email": "maria@email.com",
      "context": { "NOME_CLIENTE": "Maria Silva", "NRO_PEDIDO": "PED-002" }
    }
  ]
}

Resposta

JSON202 Accepted

{
  "data": {
    "batch_id": "batch_abc123xyz456",
    "channel": "email",
    "total": 2,
    "status": "queued",
    "message": "2 envios foram enfileirados para processamento."
  }
}

Status

202 403 422

GET /api/v1/surveys/{uuid}/qrcode Escala QR Code da pesquisa ▶

Retorna o QR Code da pesquisa em formato PNG (base64) ou SVG.

Query Params

Param	Tipo		Descrição
format	string	opcional	`png` (default) ou `svg`
size	integer	opcional	100-1000 pixels (default: 300)

Exemplo

cURL

curl -X GET https://satisfacao.app/api/v1/surveys/{uuid}/qrcode?format=png&size=400 \
  -H "X-API-Key: sua_chave_aqui" \
  -H "Accept: application/json"

Resposta

JSON200 OK

{
  "data": {
    "survey_id": "a1b2c3d4-e5f6-...",
    "survey_url": "https://satisfacao.app/s/a1b2c3d4",
    "format": "png",
    "size": 400,
    "qrcode": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Status

200 403 422

Satisfacao.app API

Autenticação

● Como obter sua API Key

● Exemplo de requisicao

● Erros de autenticacao

Headers obrigatórios

Pesquisas

Resposta

Parâmetros

Questoes

Resposta

Parâmetros

Respostas

Parâmetros

Exemplo

Analytics & Planos

Resposta

Resposta

Limites e Erros

Rate Limits

Códigos de Erro

Plano Escala

Como Funciona

Onde as tags funcionam

Regras

Tags no Envio em Massa

Painel de Acompanhamento

Parâmetros

Exemplo

Resposta

Status

Parâmetros

Exemplo

Resposta

Status

Query Params

Exemplo

Resposta

Status