Responda.me API v1 — Documentação

Status: Em produção — https://responda.me/api/v1. Última atualização: 15/05/2026

Este documento descreve o contrato da API v1 do Responda.me, voltada a integrações externas (server-to-server) que precisam listar fluxos e enviar respostas em nome de um usuário do Responda.me. O shape é estável; adições compatíveis (campos novos opcionais) podem acontecer sem aviso, mudanças incompatíveis viram /v2/.

1. Conceitos

2. Autenticação

Toda request precisa de um header:

Authorization: Bearer <api_key_do_usuario>

• O usuário gera a api_key em https://responda.me/profile → aba API e cola no painel da sua integração.
• A chave identifica qual usuário do Responda.me a request está afetando e dá acesso aos fluxos dele.
• É pessoal e secreta. Quem tiver acesso a ela pode listar fluxos e enviar respostas em nome do usuário.

Sem o header → 401 Unauthorized. API key revogada / usuário bloqueado / plano insuficiente → 403 Forbidden.

3. Base URL e versionamento

https://responda.me/api/v1

• Todas as rotas estão sob /api/v1/.
• Mudanças de contrato incompatíveis viram /api/v2/. Você pode continuar em v1 até a data de sunset (mínimo 6 meses de aviso).
• Adições compatíveis (campos novos opcionais) acontecem em v1 sem aviso.

4. Endpoints

4.1. GET /fluxos

Lista os fluxos do usuário identificado pela api_key.

Request:

GET /api/v1/fluxos HTTP/1.1
Authorization: Bearer rs_live_xxx

200 OK:

{
  "fluxos": [
    {
      "id": "flx_a1b2c3",
      "titulo": "Qualificação - Imóveis",
      "publicado": true,
      "criado_em": "2026-04-12T14:33:00Z",
      "total_perguntas": 7
    },
    {
      "id": "flx_d4e5f6",
      "titulo": "Pré-venda Curso",
      "publicado": false,
      "criado_em": "2026-05-01T09:10:00Z",
      "total_perguntas": 12
    }
  ]
}

Apenas fluxos publicado: true aceitam respostas via POST /respostas. Os outros podem ser exibidos como rascunho.

4.2. GET /fluxos/{id}

Retorna o schema completo do fluxo: perguntas, opções, lógica, tema.

Request:

GET /api/v1/fluxos/flx_a1b2c3 HTTP/1.1
Authorization: Bearer rs_live_xxx

200 OK:

{
  "id": "flx_a1b2c3",
  "titulo": "Qualificação - Imóveis",
  "publicado": true,
  "tema": {
    "accent_color": "#0369a1",
    "alignment": "center"
  },
  "perguntas": [
    {
      "id": "q_001",
      "ordem": 0,
      "type": "single_choice",
      "title": "Qual seu orçamento?",
      "description": null,
      "required": true,
      "variable_name": "orcamento",
      "properties": {
        "options": [
          { "id": "opt_a", "label": "Até 300k", "score": 5 },
          { "id": "opt_b", "label": "300k - 600k", "score": 10 },
          { "id": "opt_c", "label": "600k+", "score": 20 }
        ]
      },
      "logic": null
    },
    {
      "id": "q_002",
      "ordem": 1,
      "type": "textarea",
      "title": "Conte sua necessidade",
      "required": false,
      "variable_name": "necessidade",
      "properties": null,
      "logic": null
    }
  ]
}

404 Not Found se o fluxo não pertencer ao usuário da api_key.

4.3. POST /respostas

Envia uma resposta completa do lead. O Responda.me valida, persiste, calcula lead_score, dispara webhooks/automações configurados.

Request:

POST /api/v1/respostas HTTP/1.1
Authorization: Bearer rs_live_xxx
Content-Type: application/json
Idempotency-Key: ig_event_98765

Body:

{
  "fluxo_id": "flx_a1b2c3",
  "source": {
    "canal": "instagram_direct",
    "ig_username": "fulano",
    "ig_user_id": "17841400000",
    "ig_profile_pic_url": "https://...",
    "ig_name": "Fulano da Silva"
  },
  "respostas": [
    { "pergunta_id": "q_001", "valor": "opt_b" },
    { "pergunta_id": "q_002", "valor": "Procuro 3 quartos perto da praia" }
  ],
  "started_at": "2026-05-15T10:00:00Z",
  "completed_at": "2026-05-15T10:03:45Z"
}

201 Created:

{
  "status": "ok",
  "resposta_id": "rsp_x9y8z7",
  "lead_score": 35,
  "qualificado": true
}

Observações sobre valor:

Idempotency-Key: se vier o mesmo Idempotency-Key duas vezes em ≤24h, a segunda chamada retorna o mesmo resposta_id (cacheado), sem duplicar lead. Recomendado usar o ID do evento da Meta.

5. Tipos de pergunta — schema completo

Todos os 20 tipos abaixo podem aparecer no GET /fluxos/{id}. Os marcados como display-only não esperam resposta — a integração pode pular ou renderizar como mensagem informativa, dependendo do canal.

Inputs (espera resposta)

text

Texto curto, 1 linha.

{ "type": "text", "properties": { "placeholder": "Digite aqui", "numeric_only": false } }

textarea

Texto longo, multilinha.

{ "type": "textarea", "properties": { "placeholder": "..." } }

email

Texto com validação de e-mail server-side.

{ "type": "email", "properties": { "placeholder": "voce@email.com" } }

phone

Texto com validação de telefone BR.

{ "type": "phone", "properties": { "placeholder": "(11) 99999-9999" } }

cep (PRO)

Texto com validação de CEP BR + lookup ViaCEP.

{ "type": "cep", "properties": { "placeholder": "00000-000" } }

date

Seletor de data.

{ "type": "date", "properties": null }

single_choice

Escolha única entre opções. Pode ter score por opção.

{
  "type": "single_choice",
  "properties": {
    "options": [
      { "id": "opt_a", "label": "Opção A", "icon": "🚀", "description": "Texto secundário", "score": 10 }
    ],
    "auto_advance": true
  }
}

multiple_choice

Escolha múltipla. valor é array de ids.

{
  "type": "multiple_choice",
  "properties": {
    "options": [
      { "id": "opt_a", "label": "A", "score": 5 },
      { "id": "opt_b", "label": "B", "score": 5 }
    ]
  }
}

image_choice

Como single_choice, mas cada opção tem imagem.

{
  "type": "image_choice",
  "properties": {
    "options": [
      { "id": "opt_a", "label": "Opção A", "image_url": "https://...", "score": 10 }
    ]
  }
}

rating

Escala numérica (1..maxRating). valor é número.

{
  "type": "rating",
  "properties": {
    "max_rating": 5,
    "rating_icon": "star"
  }
}

yes_no

Booleano. valor é true ou false.

{ "type": "yes_no", "properties": null }

dropdown (PRO)

Selector dropdown. Mesma estrutura de single_choice, mas UX de combo.

{
  "type": "dropdown",
  "properties": {
    "options": [
      { "id": "opt_a", "label": "Opção A", "score": 5 }
    ]
  }
}

file_upload (PRO)

Upload de arquivo. Como o upload acontece no seu lado (você hospeda o anexo), basta enviar a URL pública e o nome no shape esperado.

{
  "type": "file_upload",
  "properties": {
    "max_file_size": 10,
    "allowed_file_types": ["image/*", "application/pdf"],
    "max_files": 3
  }
}

Display-only (não espera resposta)

Renderize como mensagem informativa e avance pra próxima pergunta. Não inclua no array respostas do POST.

welcome

Tela de boas-vindas.

{
  "type": "welcome",
  "title": "Bem-vindo!",
  "description": "Vamos te qualificar em 2 minutos.",
  "properties": {
    "button_text": "Começar",
    "media_url": "https://...",
    "media_type": "image"
  }
}

testimonial (PRO)

Depoimentos.

{
  "type": "testimonial",
  "properties": {
    "testimonials": [
      { "id": "t1", "name": "Maria", "rating": 5, "text": "Mudou minha vida." }
    ],
    "button_text": "Próximo"
  }
}

percentage_bars (PRO)

Barras de % (típico em quiz "veja seu perfil").

{
  "type": "percentage_bars",
  "properties": {
    "percentage_bars": [
      { "id": "b1", "label": "Você é introvertido", "percentage": 78 }
    ]
  }
}

list (PRO)

Lista com ícone + título + descrição (benefícios).

{
  "type": "list",
  "properties": {
    "list_items": [
      { "id": "i1", "icon": "✨", "title": "Item 1", "description": "Descrição" }
    ]
  }
}

before_after (PRO)

Comparativo antes/depois.

{
  "type": "before_after",
  "properties": {
    "before_after": {
      "before_image": "https://...",
      "after_image": "https://...",
      "before_title": "Antes",
      "after_title": "Depois",
      "before_percentage": 30,
      "after_percentage": 95
    }
  }
}

wildcard (PRO)

Botão de ação livre (link externo, step, obrigado).

{
  "type": "wildcard",
  "properties": {
    "button_text": "Garantir vaga",
    "destination_type": "url",
    "destination_url": "https://...",
    "offer": {
      "title": "Plano PRO",
      "price": "R$ 19,90",
      "price_suffix": "/mês",
      "features": ["Recurso 1", "Recurso 2"]
    }
  }
}

loading (PRO)

Tela de carregamento simulada com auto-avanço.

{
  "type": "loading",
  "properties": {
    "loading_duration": 5,
    "loading_style": "bar",
    "loading_show_percentage": true
  }
}

6. Lógica condicional (logic)

Cada pergunta pode ter logic opcional com regras de salto:

{
  "logic": {
    "type": "answer",
    "rules": [
      {
        "id": "rule_1",
        "condition": "equals",
        "value": "opt_a",
        "target_id": "q_005"
      },
      {
        "id": "rule_2",
        "condition": "equals",
        "value": "opt_b",
        "target_id": "end"
      }
    ]
  }
}

• type: "answer" → avalia a resposta da pergunta atual.
• type: "score" → avalia o lead_score acumulado.
• condition: equals, not_equals, contains, greater_than, less_than, between.
• target_id: id da próxima pergunta, ou "end" pra encerrar o fluxo.

Se a sua integração não for suportar lógica no MVP, ignore logic e renderize as perguntas em ordem (ordem ascendente). A lógica também é avaliada server-side no POST /respostas, mas a UX de pular perguntas só funciona se o cliente respeitar.

7. Idempotência

Use Idempotency-Key em todo POST /respostas. Recomendação: ID do evento Meta da DM, ou ${ig_user_id}:${fluxo_id}:${started_at_unix}.

A chave é válida por 24h. Após expirar, uma nova request com mesma chave cria uma resposta nova.

8. Erros — formato padrão

Toda resposta de erro segue:

{
  "error": {
    "code": "invalid_question_type",
    "message": "A pergunta q_003 não aceita resposta (é display-only).",
    "details": { "pergunta_id": "q_003", "type": "testimonial" }
  }
}

Códigos comuns

9. Contato

Dúvidas técnicas: contato@responda.me