Catálogo APIs

Appearance

Registro de Encuestas de Satisfacción - scraping-v1-satisfactionsurvey ​

Información del Servicio

Endpoint:  /api/scraping/v1/satisfactionsurvey
Método:  POST
Versión: v1
Categoría: Integraciones Externas

1. Documentación del Servicio ​

Descripción general ​

Este servicio permite registrar las respuestas de una encuesta de satisfacción asociada a un caso o interacción de cliente gestionada por canales digitales. Su objetivo es almacenar las respuestas, auditar el proceso, controlar intentos de respuesta y notificar automáticamente a áreas responsables si se detectan respuestas críticas (por ejemplo, insatisfacción).
Pertenece a la categoría de Scraping y gestión de feedback de clientes.
Casos de uso principales:

  • Registrar la satisfacción del cliente tras una atención digital.
  • Auditar y controlar la cantidad de respuestas por caso.
  • Notificar automáticamente respuestas negativas para seguimiento.

Especificación técnica ​

  • Endpoint: /api/scraping/v1/satisfactionsurvey
  • Método HTTP: POST
  • Capas involucradas:
    • Controlador: ScrapingController (método SatisfactionSurvey_v1)
    • Lógica de negocio: ScrapingBusiness.SatisfactionSurvey_v1
    • Acceso a datos: Utilidades de persistencia y auditoría (CRUD_MDM_INTERACCION_CD, AuditUtil, NotifyUtil)
  • Flujo de procesamiento:
    1. El controlador recibe la petición y extrae la IP del cliente.
    2. Se construye un objeto de request estándar y se envía a la capa de negocio.
    3. Se audita la entrada.
    4. Se valida la estructura y datos del request.
    5. Se obtiene el origen y tipologías de la operación.
    6. Se valida si el endpoint está habilitado.
    7. Se consulta o crea la interacción asociada al caso.
    8. Se actualizan o insertan las respuestas de la encuesta.
    9. Si alguna respuesta es crítica, se notifica automáticamente.
    10. Se audita la salida y se registra en BAM.
    11. Se retorna la respuesta estándar.
  • Dependencias principales:
    • Modelos: BaseRequestSatisfactionSurvey, SatisfactionSurveyRequest, SatisfactionSurveyCustomerRequest, SatisfactionSurveyItemRequest
    • Utilidades: AuditUtil, NotifyUtil, CRUD_MDM_INTERACCION_CD
    • Seguridad: [Authorize] en el controlador
  • Seguridad y autenticación:
    • Requiere autenticación (atributo [Authorize]).
    • Valida cabecera de sistema y canal.
    • Control de intentos por caso.

Parámetros de entrada (Request) ​

Headers ​

CampoTipoObligatorioDescripción
System.NamestringSíNombre del sistema que realiza la petición
System.CorrelationIDstringSíIdentificador único de la transacción
System.ProcessingServerstringSíServidor de procesamiento
PropertyarrayNo*Propiedades adicionales de la petición

*Opcional, pero puede ser requerido según integración.

Body ​

CampoTipoObligatorioDescripción
AuditobjetoSíInformación de auditoría de la operación
Case_NumberstringSíNúmero de caso asociado a la encuesta
CustomerobjetoSíInformación del cliente
SurveyarraySíLista de preguntas y respuestas de la encuesta

Detalle de objetos anidados:

  • Customer

    CampoTipoObligatorioDescripción
    Document_NumberstringSíNúmero de identificación del cliente
    Document_TypestringSíTipo de identificación

  • Survey (array de objetos)

    CampoTipoObligatorioDescripción
    QuestionstringSíPregunta de la encuesta
    AnswerstringSíRespuesta dada por el cliente

Respuesta esperada (Response) ​

Headers ​

CampoTipoObligatorioDescripción
System.NamestringSíNombre del sistema que responde
System.CorrelationIDstringSíIdentificador único de la transacción
System.ProcessingServerstringSíServidor de procesamiento
Service.StatusstringSíEstado de la ejecución (OK/ERROR)
Service.ResponseDatedatetimeSíFecha de la respuesta
Service.ProcessingServerstringSíServidor de procesamiento
Service.StatusDetailarraySíDetalles de estado y errores
PropertyarrayNoPropiedades adicionales

  • StatusDetail (array de objetos)

    CampoTipoObligatorioDescripción
    ErrorCodestringSíCódigo de error o estado
    ErrorDetailCodestringNoDetalle funcional del error
    ErrorMessagestringNoMensaje técnico
    ErrorMessageUserstringNoMensaje para el usuario

Body ​

CampoTipoObligatorioDescripción
WSResponseHeaderobjetoSíCabecera estándar de respuesta

Manejo de errores ​

CódigoDescripciónEjemplo
ERROR_04Request nulo o mal formado"El request es nulo"
ERROR_06Error al insertar la interacción"No fue posible registrar la encuesta"
ERROR_07Intento de respuesta no permitido"Ya existe una respuesta para este caso"
BOTERRORExcepción no controlada"se ha generado una excepcion no controlada"

2. Análisis de Componentes ​

Modelos y componentes ​

  • Modelos base utilizados:
    • BaseRequestSatisfactionSurvey
    • SatisfactionSurveyRequest
    • SatisfactionSurveyCustomerRequest
    • SatisfactionSurveyItemRequest
    • BaseResponseSatisfactionSurvey
    • BotBaseRequestHeader, BotBaseResponseHeader
  • Utilidades y servicios comunes:
    • AuditUtil (auditoría de entrada/salida)
    • NotifyUtil (notificación automática de respuestas críticas)
    • CRUD_MDM_INTERACCION_CD (persistencia de interacciones)
  • Patrones de diseño:
    • Singleton para utilidades de negocio y auditoría.
    • Separación de capas (controlador, negocio, datos).
  • Componentes reutilizados:
    • Modelos de request/response estándar en otros endpoints de Scraping.
    • Utilidades de auditoría y notificación.
  • Referencias cruzadas:
    • Endpoint /api/scraping/v1/validatesurvey para validación de encuestas.
    • Otros endpoints de Scraping para inserción y consulta de interacciones.

Ejemplos de Request/Response ​

Solicitud (request) ​

json
{
  "WSRequestHeader": {
    "System": {
      "name": "LUZ",
      "correlationID": "LUZ-CC-79657111-222527",
      "processingServer": null
    },
    "Property": [
      {
        "name": "MotivoContacto",
        "value": "Reconexion_por_pago"
      },
      {
        "name": "NumeroCaso",
        "value": "23221521"
      }
    ]
  },
  "WSRequestBody": {
    "Customer": {
      "Document_Number": "79657111",
      "Document_Type": "CC"
    },
    "Survey": [
      {
        "Question": "Origen",
        "Answer": "ENCUESTA_BOT"
      },
      {
        "Question": "MotivoContacto",
        "Answer": "Reconexion_por_pago"
      },
      {
        "Question": "NumeroCaso",
        "Answer": "23221521"
      },
      {
        "Question": "Tecnologia",
        "Answer": "FTTH"
      },
      {
        "Question": "Pasillo",
        "Answer": "Atención"
      },
      {
        "Question": "SegmentoUEN",
        "Answer": "Hogares"
      }
    ],
    "Audit": {
      "Canal": "directline",
      "Date": "{au_fecha}",
      "Hour": "{au_hora}"
    }
  }
}

Respuesta exitosa ​

json
{
  "WSResponseHeader": {
    "System": {
      "name": "LUZ",
      "correlationID": "LUZ-CC-79657805-222527",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-04-16T22:25:28.3273172Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "La solicitud fue exitosa",
          "errorMessage": "La solicitud LUZ-CC-79657805-222527 fue exitosa",
          "errorMessageUser": null
        }
      ]
    },
    "Property": [
      {
        "name": "MotivoContacto",
        "value": "Reconexion_por_pago"
      },
      {
        "name": "NumeroCaso",
        "value": "23221521"
      }
    ]
  }
}

Respuesta de error ​

json
{
  "WSResponseHeader": {
    "System": {
      "Name": "MDM-SCRAPING",
      "CorrelationID": "123e4567-e89b-12d3-a456-426614174000",
      "ProcessingServer": "server-01"
    },
    "Service": {
      "Status": "ERROR",
      "ResponseDate": "2024-06-01T12:35:00Z",
      "ProcessingServer": "server-01",
      "StatusDetail": [
        {
          "ErrorCode": "ERROR_07",
          "ErrorDetailCode": "Ya existe una respuesta para este caso",
          "ErrorMessage": "Intento de respuesta duplicado",
          "ErrorMessageUser": "Ya has respondido esta encuesta anteriormente."
        }
      ]
    },
    "Property": []
  }
}

3. Diagramas Técnicos ​

3.1 Flujo de datos ​

mermaid
graph TD
  A["Cliente/API Consumer"] --> B["ScrapingController"]
  B --> C["ScrapingBusiness"]
  C --> D["CRUD_MDM_INTERACCION_CD (Persistencia)"]
  C --> E["AuditUtil (Auditoría)"]
  C --> F["NotifyUtil (Notificación)"]
  D --> G["Base de datos"]
  F --> H["Correo/Alerta"]

3.2 Arquitectura de clases ​

mermaid
classDiagram
  class ScrapingController {
    +SatisfactionSurvey_v1(request)
  }
  class ScrapingBusiness {
    +SatisfactionSurvey_v1(request, name)
  }
  class BaseRequestSatisfactionSurvey
  class SatisfactionSurveyRequest
  class SatisfactionSurveyCustomerRequest
  class SatisfactionSurveyItemRequest
  class BaseResponseSatisfactionSurvey
  class BotBaseRequestHeader
  class BotBaseResponseHeader

  ScrapingController --> ScrapingBusiness
  ScrapingController --> BaseRequestSatisfactionSurvey
  BaseRequestSatisfactionSurvey --> SatisfactionSurveyRequest
  SatisfactionSurveyRequest --> SatisfactionSurveyCustomerRequest
  SatisfactionSurveyRequest --> SatisfactionSurveyItemRequest
  ScrapingBusiness --> BaseResponseSatisfactionSurvey
  BaseResponseSatisfactionSurvey --> BotBaseResponseHeader
  BotBaseRequestHeader <.. BaseRequestSatisfactionSurvey

3.3 Secuencia de ejecución ​

mermaid
sequenceDiagram
  participant Cliente
  participant API as ScrapingController
  participant Negocio as ScrapingBusiness
  participant Persistencia as CRUD_MDM_INTERACCION_CD
  participant Auditoria as AuditUtil
  participant Notificacion as NotifyUtil

  Cliente->>API: POST /api/scraping/v1/satisfactionsurvey
  API->>Negocio: SatisfactionSurvey_v1(request)
  Negocio->>Auditoria: Save_Request(entrada)
  Negocio->>Persistencia: Get/Insert Interacción
  Negocio->>Notificacion: Satisfaction_Survey (si aplica)
  Negocio->>Auditoria: Save_Request(salida)
  Negocio-->>API: BaseResponseSatisfactionSurvey
  API-->>Cliente: WSResponseHeader

4. Políticas y Consideraciones ​

Políticas de seguridad ​

  • Autenticación: Requiere autenticación mediante [Authorize] en el controlador.
  • Validaciones: Se valida la estructura del request, la existencia de la interacción y el control de intentos.
  • Notificación: Respuestas críticas (insatisfacción) generan notificación automática.
  • Auditoría: Todas las operaciones son auditadas (entrada y salida).
  • Rate limits: No explícitos en el código, pero el control de intentos por caso actúa como limitador.
  • SLA: No especificado en el código fuente, depende de la política de la plataforma.

Recomendaciones y mejores prácticas ​

  • Validar exhaustivamente los datos de entrada para evitar requests nulos o mal formados.
  • Centralizar la gestión de errores para mensajes más claros y homogéneos.
  • Implementar rate limits explícitos si se detectan abusos o automatizaciones no deseadas.
  • Monitorear las notificaciones automáticas para asegurar que los casos críticos sean gestionados oportunamente.
  • Mantener actualizada la documentación de los modelos y flujos, ya que el endpoint depende de varios componentes reutilizables.
  • Revisar y actualizar las tipologías de error para alinearlas con la experiencia de usuario y necesidades de negocio.