Headless Salesforce Feedback Management: cómo usar Salesforce como motor de encuesta y construir el frontend por fuera

  ┌────────────────────────────────────────────────────────────────────┐
  │  Frontend  (React / Next.js / móvil)                               │
  └───────────────────────┬────────────────────────────────────────────┘
                          │  1. POST /survey-response         (start)
                          ▼
  ┌────────────────────────────────────────────────────────────────────┐
  │  Salesforce  ← devuelve Survey Description Output:                 │
  │    · responseId, invitationId, flowInterviewState                  │
  │    · surveyPage = Página 1 (label, name, surveyQuestions[])        │
  │    · navigationActions = ["Next"]                                  │
  └───────────────────────┬────────────────────────────────────────────┘
                          │  2. Renderiza Página 1 · usuario responde
                          │
                          │  3. PATCH /survey-response         (Next)
                          │     body: { navigationAction: "Next",      │
                          │             surveyPageResponses: {...} }   │
                          ▼
  ┌────────────────────────────────────────────────────────────────────┐
  │  Salesforce evalúa branching server-side según la respuesta        │
  │  ← devuelve Survey Response Output:                                │
  │    · flowInterviewState (nuevo)                                    │
  │    · surveyPage = Página 2 O Página 5 (según branching)            │
  │    · navigationActions = ["Next", "Back"]                          │
  └───────────────────────┬────────────────────────────────────────────┘
                          │  4. Repite PATCH por cada página
                          │
                          │  5. PATCH última página · Next
                          ▼
  ┌────────────────────────────────────────────────────────────────────┐
  │  Salesforce ← devuelve Survey Response Output con:                 │
  │    · surveyPage = Survey Thank You Page Output                     │
  │      (thankYouMessage, messageDescription, redirectUrl, urlButtons)│
  │    · navigationActions = []                                        │
  │  Persistencia:                                                     │
  │    · SurveyResponse.Status → Completed                             │
  │    · SurveyQuestionResponse por cada pregunta contestada           │
  └────────────────────────────────────────────────────────────────────┘

POST /services/data/v57.0/connect/surveys/0Kdxx0000000H46CAE/invitation/0Kixx0000004EsOCAU/survey-response
Host: yourInstance.my.salesforce.com
Authorization: Bearer <access_token>
Content-Type: application/json

{}

{
  "status": "Success",
  "responseId": "0Myxx0000004CYqCAM",
  "invitationId": "0Kixx0000004EsOCAU",
  "flowInterviewState": "state1",
  "languageCode": "en",
  "navigationActions": ["Next"],
  "surveyDetail": {
    "label": "Post-purchase feedback",
    "name": "Post_purchase_feedback",
    "versionNumber": 3,
    "surveyPage": {
      "label": "Página 1",
      "name": "p_d84a...",
      "surveyQuestions": [
        {
          "name": "q_856a...",
          "label": "¿Actualmente eres cliente?",
          "questionType": "RadioButton",
          "isResponseRequired": true,
          "questionChoices": [
            { "name": "c_yes", "label": "Sí" },
            { "name": "c_no",  "label": "No" }
          ]
        }
      ]
    }
  },
  "errors": [],
  "warnings": []
}

PATCH /services/data/v57.0/connect/surveys/0Kdxx.../invitation/0Kixx.../survey-response
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "flowInterviewState": "state1",
  "invitationId": "0Kixx0000004EsOCAU",
  "languageCode": "en",
  "navigationAction": "Next",
  "surveyPageResponses": {
    "questionResponses": [
      {
        "name": "q_856a...",
        "questionType": "RadioButton",
        "responses": [ { "name": "c_yes" } ]
      }
    ]
  }
}

{
  "status": "Success",
  "responseId": "0Myxx0000004CYqCAM",
  "invitationId": "0Kixx0000004EsOCAU",
  "flowInterviewState": "state2",
  "languageCode": "en",
  "navigationActions": ["Next", "Back"],
  "surveyPage": {
    "label": "Página 2 — datos de tu experiencia",
    "name": "p_c73e...",
    "surveyQuestions": [
      {
        "name": "q_ab12...",
        "label": "¿Qué productos usaste esta semana?",
        "questionType": "MultiChoice",
        "isResponseRequired": true,
        "questionChoices": [
          { "name": "c_p1", "label": "Producto A" },
          { "name": "c_p2", "label": "Producto B" },
          { "name": "c_p3", "label": "Producto C" }
        ]
      },
      {
        "name": "q_cd34...",
        "label": "Del 0 al 10, ¿qué tan probable es que nos recomiendes?",
        "questionType": "NPS",
        "isResponseRequired": true,
        "minScale": 0,
        "maxScale": 10
      }
    ]
  },
  "errors": []
}

{
  "status": "Success",
  "responseId": "0Myxx0000004CYqCAM",
  "flowInterviewState": "final",
  "navigationActions": [],
  "surveyPage": {
    "label": "Gracias",
    "name": "p_thanks",
    "thankYouMessage": "Gracias por tu tiempo.",
    "messageDescription": "Tu opinión fue registrada correctamente.",
    "redirectUrl": "https://miempresa.com/gracias",
    "urlButtons": [
      { "label": "Volver al inicio", "url": "https://miempresa.com" }
    ]
  }
}

SurveyContainer
    │  · guarda { invitationId, invitationUuid?, flowInterviewState, responseId }
    │  · maneja fetch a start / next / back
    │  · decide si render <SurveyPage /> o <ThankYouPage />
    │
    ├── SurveyPage
    │     │  · recibe surveyQuestions[]
    │     │  · valida required antes de habilitar 'Next'
    │     │  · muestra 'Back' cuando navigationActions incluye "Back"
    │     │
    │     └── QuestionRenderer   (por cada pregunta)
    │           │  switch(questionType)
    │           │
    │           ├── <SingleChoice />       questionType = "RadioButton"
    │           ├── <MultiChoice />        questionType = "MultiChoice"
    │           ├── <BooleanYesNo />       questionType = "Boolean"
    │           ├── <Rating />             questionType = "Rating"
    │           ├── <NPS />                questionType = "NPS"
    │           ├── <TextInput />          questionType = "ShortText"
    │           ├── <TextArea />           questionType = "FreeText"
    │           └── <Unsupported />        fallback + telemetría
    │
    └── ThankYouPage
          · label · thankYouMessage · messageDescription · redirectUrl · urlButtons[]

type Question = {
  name: string;
  label: string;
  questionType:
    | "RadioButton"
    | "MultiChoice"
    | "Boolean"
    | "Rating"
    | "NPS"
    | "ShortText"
    | "FreeText";
  isResponseRequired: boolean;
  questionChoices?: { name: string; label: string }[];
  minScale?: number;
  maxScale?: number;
};

export function QuestionRenderer({ question, value, onChange }: Props) {
  switch (question.questionType) {
    case "RadioButton":
      return <SingleChoice question={question} value={value} onChange={onChange} />;
    case "MultiChoice":
      return <MultiChoice   question={question} value={value} onChange={onChange} />;
    case "Boolean":
      return <BooleanYesNo  question={question} value={value} onChange={onChange} />;
    case "Rating":
      return <Rating        question={question} value={value} onChange={onChange} />;
    case "NPS":
      return <NPS           question={question} value={value} onChange={onChange} />;
    case "ShortText":
      return <TextInput     question={question} value={value} onChange={onChange} />;
    case "FreeText":
      return <TextArea      question={question} value={value} onChange={onChange} />;
    default:
      // Nunca falle silencioso: logueé el tipo y muestre un placeholder claro.
      return <Unsupported type={question.questionType} />;
  }
}

export function buildSurveyPageResponses(state: Record<string, any>, questions: Question[]) {
  return {
    questionResponses: questions.map((q) => {
      const raw = state[q.name];
      switch (q.questionType) {
        case "RadioButton":
        case "Boolean":
        case "Rating":
          return { name: q.name, questionType: q.questionType, responses: [{ name: raw }] };

        case "MultiChoice":
          return {
            name: q.name,
            questionType: q.questionType,
            responses: (raw as string[]).map((n) => ({ name: n })),
          };

        case "NPS":
          return { name: q.name, questionType: q.questionType, responseValue: Number(raw) };

        case "ShortText":
        case "FreeText":
          return { name: q.name, questionType: q.questionType, responseValue: String(raw) };
      }
    }),
  };
}

POST   /api/surveys/{surveyDeveloperName}/start
       ├─ crea la invitación (autenticada o unAuth según el flujo)
       ├─ traduce a Salesforce y guarda { invitationId, invitationUuid?, flowInterviewState }
       └─ devuelve al cliente { pageId, questions[], canGoBack, canGoNext }

PATCH  /api/surveys/{surveyDeveloperName}/next
       ├─ recibe answers[] del cliente
       ├─ arma el surveyPageResponses.questionResponses[] correcto
       ├─ PATCH a Salesforce con navigationAction: "Next"
       └─ devuelve { pageId, questions[], canGoBack, canGoNext }  · O  { finished: true, thankYou }

PATCH  /api/surveys/{surveyDeveloperName}/back
       └─ igual que /next pero con navigationAction: "Back"

GET    /api/surveys/{surveyDeveloperName}/state
       └─ (opcional) devuelve la página actual sin navegar — útil tras refresh del browser

Survey                        · plantilla del cuestionario
  │
  └── SurveyVersion           · versión publicada (cada publish crea una nueva)
        │
        ├── SurveyPage        · páginas de esa versión
        │     │
        │     └── SurveyQuestion       · preguntas de esa página
        │           │
        │           └── SurveyQuestionChoice
        │
        └── SurveyInvitation  · invitación a un Contact / Lead / User específico
              │
              └── SurveyResponse       · una fila por respuesta
                    │
                    └── SurveyQuestionResponse  · una fila por pregunta contestada

┌────────────────────────────────────────────────────────────────────────────────┐
│                                 SALESFORCE                                     │
│                        (Motor de encuesta · Sistema de registro)               │
│                                                                                │
│                            Survey Builder / Feedback Management                │
│                                        │                                       │
│         Survey → SurveyVersion → SurveyPage → SurveyQuestion → Choice          │
│                                        │                                       │
│                     Page branching  ·  Question display logic                  │
│                     Required flags  ·  Merge fields  ·  Traducciones           │
│                                        │                                       │
│                             SurveyInvitation                                   │
│                                        │                                       │
│                          Business API (Connect REST)                           │
│                     /connect/surveys/…/survey-response                         │
│                     salesforce-scrt.com/surveys/v1/…                           │
│                                        │                                       │
│                     SurveyResponse  ·  SurveyQuestionResponse                  │
│                                        │                                       │
│                     Data Mapper → Case, Task, Flow, Data Cloud                 │
└────────────────────────────────────┬───────────────────────────────────────────┘
                                     │  POST /survey-response  (start)
                                     │  PATCH /survey-response (Next / Back)
                                     ▼
┌────────────────────────────────────────────────────────────────────────────────┐
│                                 BACKEND / BFF                                  │
│                    (Broker seguro · Sesión · Observabilidad)                   │
│                                                                                │
│      OAuth 2.0 client-credentials / JWT bearer  ·  Token unAuth per-org        │
│      Sesión server-side (httpOnly cookie + Redis) con:                         │
│                    invitationId · invitationUuid · flowInterviewState          │
│                                                                                │
│      Endpoints públicos hacia el cliente:                                      │
│        POST   /api/surveys/{name}/start                                        │
│        PATCH  /api/surveys/{name}/next                                         │
│        PATCH  /api/surveys/{name}/back                                         │
│        GET    /api/surveys/{name}/state                                        │
│                                                                                │
│      Responsabilidades: normalización · retries · rate limit · logging         │
│      Prohibido: reinterpretar branching · cachear schema · validar negocio     │
└────────────────────────────────────┬───────────────────────────────────────────┘
                                     │  Payload normalizado (page + questions)
                                     ▼
┌────────────────────────────────────────────────────────────────────────────────┐
│                              CUSTOM FRONTEND                                   │
│                        (Look & feel · UX · Canal)                              │
│                                                                                │
│        SurveyContainer                                                         │
│          ├── SurveyPage                                                        │
│          │     └── QuestionRenderer                                            │
│          │           ├── SingleChoice   MultiChoice   BooleanYesNo             │
│          │           ├── Rating         NPS                                    │
│          │           └── TextInput      TextArea      (Unsupported fallback)   │
│          └── ThankYouPage                                                      │
│                                                                                │
│      Responsabilidades: rendering · validación required en UI · a11y · i18n    │
│      Prohibido: mantener el mapa de branching · mutar SurveyQuestion           │
└────────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│  Página 1 · Perfil                                                  │
│    Q1  Industria           · Single selection  · Requerida          │
│    Q2  Rol                 · Single selection  · Requerida          │
└─────────────────────────────────────────────────────────────────────┘
                                    │  Next
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Página 2 · Estado actual                                           │
│    Q3  ¿Ya usan Agentforce?  · Sí/No           · Requerida          │
│    Q4  Canales desplegados   · Multi-select    · Opcional           │
│    Q5  Satisfacción actual   · Rating 1-5      · Opcional           │
└─────────────────────────────────────────────────────────────────────┘
                                    │  Next
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Página 3 · Priorización                                            │
│    Q6  Probabilidad IA este año · NPS 0-10     · Requerida          │
│    Q7  ¿Qué te frena?           · Single sel.  · Requerida          │
│    Q8  Cuéntanos más            · Long text    · Opcional           │
└─────────────────────────────────────────────────────────────────────┘
                                    │  Next
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Página 4 · Contacto                                                │
│    Q9  ¿Sesión con arquitecto?  · Sí/No        · Requerida          │
│    Q10 Email                    · Short text   · Opcional           │
└─────────────────────────────────────────────────────────────────────┘
                                    │  Next
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Página 5 · Thank You                                               │
│    thankYouMessage: "Gracias por tu tiempo."                        │
│    redirectUrl:  /es/insights/headless-feedback-management-…        │
│    SurveyResponse.Status → Completed                                │
└─────────────────────────────────────────────────────────────────────┘