Empiece aquí

¡Bienvenido a la documentación de la API SoluCX! Esta guía te llevará desde cero hasta tu primera integración funcionando en pocos minutos.

¿Qué es la API SoluCX?

La API SoluCX es una API RESTful que permite integrar la plataforma de gestión de experiencia del cliente en tus sistemas. Con ella puedes:

  • Crear transacciones que representan interacciones de tus clientes con tu empresa
  • Gestionar clientes, unidades y colaboradores de forma programática
  • Disparar encuestas automáticamente basadas en eventos
  • Consultar datos e informes de satisfacción

URL Base

AmbienteURL
Producciónhttps://api.solucx.com.br/public
Preview (beta)https://api.preview.solucx.com.br/public

Conceptos Fundamentales

Antes de comenzar, es importante entender los principales conceptos de la plataforma:

Transacción - Una transacción representa una interacción del cliente con tu empresa. Puede ser una compra, una atención, una entrega, etc. Cada transacción puede disparar una encuesta automáticamente.

Jornada - Una jornada es un tipo de experiencia que quieres medir (ej: "post-compra", "post-atención"). Configuras jornadas en el panel SoluCX y las referencias vía journeySlug al crear transacciones.

Encuesta (Survey) - Una encuesta se envía automáticamente al cliente después de una transacción, basada en la jornada configurada. Puede ser NPS, CSAT, CES o personalizada.

Cliente (Customer) - Representa a la persona que recibirá la encuesta. Identificado por email, teléfono o ambos.

Unidad (Store) y Colaborador (Employee) - Entidades que permiten segmentar y analizar feedback por unidad de negocio y por atendente. Ejemplos de unidades: tiendas (retail), clínicas (salud), agencias (financiero).

Paso 1: Obtén tus credenciales de API

Para utilizar la API SoluCX, necesitarás dos claves de autenticación:

  • x-solucx-api-key: Clave de API de tu instancia
  • x-solucx-user-token: Token del usuario para autenticación

Para obtener tus credenciales, contacta con nuestro soporte a través del email [email protected].

Paso 2: Haz tu primera solicitud

Prueba tus credenciales consultando transacciones en la API:

cURL
JavaScript
Python
curl -X GET 'https://api.solucx.com.br/public/transaction?date_from=2024-01-01&date_to=2024-01-31&limit=1' \
  -H 'x-solucx-api-key: TU_API_KEY' \
  -H 'x-solucx-user-token: TU_USER_TOKEN'

Si todo está correcto, recibirás una respuesta 200 OK con los datos de las transacciones.

Paso 3: Configura la jornada en el panel

Para que la encuesta sea enviada, configura una jornada:

  1. Accede a Jornadas en el panel SoluCX
  2. Crea o edita una jornada con el slug post-compra (el mismo que será usado en journeySlug)
  3. Configura qué encuesta enviar y cuándo (inmediatamente, después de 1 día, etc.)
  4. Activa la jornada

Paso 4: Crea tu primera transacción

Ahora vamos a crear una transacción que disparará una encuesta. Usa el endpoint /v2/transactions:

cURL
JavaScript
Python
curl -X POST 'https://public-api.gke-prd.solucx.com.br/v2/transactions' \
  -H 'x-solucx-api-key: TU_API_KEY' \
  -H 'x-solucx-user-token: TU_USER_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "transaction": {
    "externalId": "pedido-12345",
    "journeySlug": "post-compra",
    "experienceDate": "2024-01-15T14:30:00Z"
  },
  "customer": {
    "name": "Juan García",
    "email": "[email protected]",
    "phone": "+5511999998888"
  },
  "store": {
    "externalId": "unidad-sp-centro",
    "name": "Unidad SP Centro"
  },
  "employee": {
    "externalId": "colaborador-123",
    "name": "María Santos"
  }
}'

Una respuesta exitosa se verá así:

{
  "success": true,
  "data": {
    "id": 12345,
    "externalId": "pedido-12345",
    "status": "pending",
    "createdAt": "2024-01-15T14:30:00Z"
  }
}

Paso 5: Verifica el resultado

Después de crear la transacción y configurar la jornada:

  • La encuesta será enviada automáticamente al cliente vía email/SMS
  • Puedes acompañar los resultados en el panel SoluCX en los informes NPS y Extracto

Para consultar una transacción específica vía API:

cURL
curl -X GET 'https://api.solucx.com.br/public/transaction?transactionId=pedido-12345' \
  -H 'x-solucx-api-key: TU_API_KEY' \
  -H 'x-solucx-user-token: TU_USER_TOKEN'

Ejemplo de respuesta:

{
  "id": "12345",
  "transaction_id": "pedido-12345",
  "external_id": "pedido-12345",
  "aval_complete": true,
  "journey": "post-compra",
  "rating": {
    "value": "9",
    "source": "email"
  },
  "customer": {
    "name": "Juan García",
    "email": "[email protected]"
  }
}

Próximos Pasos

Autenticación y Endpoints

Entiende todos los detalles sobre autenticación, seguridad y explora todos los endpoints disponibles.

Webhook para Chatbots

Endpoint para recibir respuestas de encuestas configuradas en ambientes conversacionales, como chatbots.

SDKs e Integraciones

Usa nuestros SDKs listos para Flutter, React Native o Web, y diversas integraciones.

Ejemplos Prácticos

Transacción de e-commerce

// Después de confirmación de pedido
await crearTransaccion({
  externalId: pedido.id,
  journeySlug: 'post-compra',
  customer: {
    name: pedido.cliente.nombre,
    email: pedido.cliente.email,
    phone: pedido.cliente.telefono
  },
  extras: {
    valor_pedido: pedido.valor,
    productos: pedido.items.map(i => i.nombre).join(', ')
  }
});

Transacción de atención

// Después de cierre de ticket de soporte
await crearTransaccion({
  externalId: ticket.id,
  journeySlug: 'post-atencion',
  customer: {
    name: ticket.cliente.nombre,
    email: ticket.cliente.email
  },
  employee: {
    externalId: ticket.atendente.id,
    name: ticket.atendente.nombre
  },
  extras: {
    categoria: ticket.categoria,
    tiempo_resolucion: ticket.tiempoResolucion
  }
});

Si tienes dudas, contacta con nuestro soporte a través del email [email protected].

Introducción