Documentación de integración

Incrustación de accesorios

Inserte el complemento de servicio al cliente en su sitio web con solo un fragmento de código.

Obtener el código de inserción

Inicie sesión en el panel de administración del comerciante → Configuración del canal → Código de inserción, y copie el código de inserción exclusivo para usted:

<script>
  window.$aicrs = window.$aicrs || { q: [] };
</script>
<script async src="https://su-dominio-de-servicio/widget/loader.js" data-wk="su widget_key"></script>

Pegue este código antes de </body> en cada página de su sitio web. El complemento mostrará un globo de chat en la esquina inferior derecha de la página; los visitantes podrán hacer clic para comenzar a consultar.

Lista blanca de dominios

Para prevenir el robo del complemento, solo funcionará en los dominios que usted haya registrado. Vaya a Panel de administración del comerciante → Configuración del canal → Lista blanca de dominios y agregue los dominios de su sitio web (se admiten varios). Los dominios no registrados no cargarán el complemento, lo que no afectará su página.

Reinicio del widget_key

Si sospecha que el key ha sido comprometido, puede restablecerlo en la configuración del canal. Al restablecer, la clave anterior dejará de ser válida inmediatamente, y deberá actualizar el código de inserción en su sitio web.

Preguntas frecuentes

• ¿El complemento no se muestra? Verifique si el dominio actual está en la lista blanca, si el widget_key coincide con el del panel y si la cuenta está dentro del período de servicio.
• ¿Afecta a la velocidad del sitio web? El cargador tiene menos de 1KB y se carga de forma asíncrona, sin bloquear el rendimiento de su página.

identificar membresía

Después de que los visitantes inician sesión en su sitio web, llame a identify para pasar la información del miembro. El sistema de atención al cliente asignará la sesión de este navegador al miembro correspondiente: el agente podrá ver directamente la identidad del miembro, y las visitas desde múltiples dispositivos se combinarán en un mismo visitante.

Método de llamada

Llámelo en su página una vez que el usuario haya iniciado sesión:

$aicrs.identify({
  externalId: 'U10086',      // Obligatorio, identificador único del usuario en su sistema
  name: 'Sra. Li',             // Opcional, nombre de visualización
  phone: '138****0000',      // Opcional
  email: 'user@example.com', // Opcional
  hash: 'Firma HMAC calculada en el servidor',  // Obligatorio, para prevención de falsificación
  custom: { vip: 'gold' }     // Opcional, campos adicionales, visibles en el lado del agente
})

Algoritmo de firma

El hash debe calcularse en su servidor (el widget_secret no debe aparecer en el código前端):

hash = cadena hexadecimal en minúsculas de HMAC-SHA256(widget_secret, externalId)

widget_secret se puede ver en el panel del comerciante → Configuración del canal → Código de incrustación, y se restablece junto con el widget_key.

Ejemplo en Node.js:

const crypto = require('crypto')
const hash = crypto.createHmac('sha256', WIDGET_SECRET).update(externalId).digest('hex')

Resultado de verificación

Los visitantes cuya firma se verifique correctamente mostrarán un indicador de "Verificado" en el lado del agente; si falla la verificación, la llamada a identify se ignorará y se mantendrá su identidad anónima, sin errores que interrumpan su página.

Push de eventos de Webhook

El sistema le notifica eventos empresariales importantes mediante mensajes JSON enviados a la dirección de devolución de llamada que configure, facilitando la sincronización de los datos del servicio al cliente a su propio sistema.

Configuración

Panel del comerciante → Datos y sistema → Webhook: ingrese la URL de devolución de llamada (debe ser HTTPS) y la clave secreta de firma, elija los tipos de evento a suscribir. Después de guardar, puede hacer clic en "Enviar evento de prueba" para una integración inmediata.

Formato de solicitud

Cada notificación se envía como una solicitud POST:

POST a su URL de devolución de llamada
Content-Type: application/json
X-AICRS-Event: tipo de evento
X-AICRS-Signature: HMAC-SHA256(secret, cuerpo de la solicitud) en minúsculas hexadecimal

Estructura del cuerpo de la solicitud:

{
  "event": "message.created",
  "tenant_id": 129,
  "timestamp": 1784500000,
  "data": { "snapshots": "..." }
}

Tipos de evento

Verificación de la firma y reintento

Al recibir una notificación, calcule HMAC-SHA256 con la clave secreta del cuerpo de la solicitud original y compárelo con X-AICRS-Signature. Si no coinciden, descártelo.

Si su interfaz devuelve 2xx, se considera un éxito; en caso de fallo, se reintentará con intervalos de 1 minuto / 5 minutos / 15 minutos un total de 3 veces. Si aún falla, se marcará como estado fallido. Puede ver la causa del fallo y solucionarla manualmente en el registro de entrega en el panel de control.

API Abierta

API abierto para leer datos de atención al cliente desde su sistema, crear tickets y aislar por comerciante.

Autenticación

Configuración del comerciante → Datos y sistema para generar una clave API (con el formato ak_ al inicio, se muestra en texto plano solo una vez al generarse, guárdela con cuidado; al restablecerse, la clave anterior deja de ser válida inmediatamente).

Incluir en todos los pedidos el encabezado de solicitud:

Authorization: Bearer ak_YourKey

Limitación de frecuencia

Cada clave permite como máximo 120 solicitudes por 60 segundos, de lo contrario se devuelve 429.

Lista de interfaces

Ejemplo:

curl -H "Authorization: Bearer ak_xxx" \
  "https://su-dominio-de-atencion/api/open/v1/conversaciones?page=1"

Notas

• Todas las respuestas son en formato JSON, las interfaces de lista admiten el parámetro page para paginación.
• La versión actual no admite enviar mensajes a visitantes mediante API.
• Si el comerciante se desactiva o el servicio expira, la API también se detiene simultáneamente.

Códigos de error correspondientes

Todas las respuestas de error de las interfaces siguen una estructura JSON uniforme:

{ "code": "código de error", "message": "mensaje en chino" }

Relación entre el código HTTP y el código de error:

Recomendaciones para el manejo:

• 401/403: Verifique si la Key es válida y el estado del servicio de la cuenta.
• 429: Vuelva a intentarlo más tarde según Retry-After o la estrategia de retroceso.
• 5xx: En interfaces idempotentes, se puede volver a intentar con seguridad; para operaciones no idempotentes, consulte primero y luego vuelva a intentar.

Interfaz abierta de CRM

La lectura y escritura de datos de clientes y oportunidades se realizan a través de la API abierta (/api/open/v1, Bearer ak_ clave, generada en "Datos y sistema → API" del panel de administración del comerciante).

Clientes

Las reglas de deduplicación coinciden con las del panel de administración: external_id > número de teléfono > correo electrónico. Si se cumple alguna regla, se fusiona con el cliente existente en lugar de crear uno duplicado.

Límite de frecuencia: 120 llamadas por clave cada 60 segundos, si se excede, se devuelve 429.

Notificación de evento del cliente

Los eventos del ciclo de vida del cliente se envían a través del canal existente de Webhook (el comerciante puede suscribirse en el "Panel de administración → Datos y sistema → Webhook"), con el mismo mecanismo de firma y reintentos que los eventos de mensaje (X-AICRS-Signature HMAC-SHA256, reintentos con retroceso exponencial).

Formato de la carga útil: {"event":"customer.created","data":{...objeto del cliente...},"ts":1690000000}. Al recibirlo, devolver 2xx confirma la recepción; si se devuelve un código no 2xx o se produce un tiempo de espera, se reintentará según la estrategia de retroceso.