1. Casa
  2. Docs
  3. Documentación del desarrollador
  4. SDK de XcooBee
  5. PHP SDK

PHP SDK

Descarga y fuente

https://github.com/XcooBee/xcoobee-php-sdk

Compositor / Packagist:

https://packagist.org/packages/xcoobee/xcoobee-sdk

Licencia

Publicado en: Apache v 2.0

SDK

El SDK de XcooBee PHP es una instalación para abstraer llamadas de nivel inferior e implementar comportamientos estándar.
El equipo de XcooBee está proporcionando esto para mejorar la velocidad de implementación y mostrar las mejores prácticas mientras interactúa con XcooBee.

En general, toda la comunicación con XcooBee se encripta por cable ya que ninguno de los sistemas XcooBee aceptará tráfico simple. Todos los datos enviados a XcooBee por usted y viceversa también se firman utilizando protocolos PGP. Los paquetes de datos que recibirá están firmados con su clave pública y los paquetes que envíe están firmados con su clave privada.

Si necesita generar nuevas claves PGP, puede iniciar sesión en su cuenta XcooBee e ir a la página de configuración para hacerlo.

Los sistemas XcooBee operan globalmente pero con conexiones regionales. El SDK lo conectará a su punto final regional automáticamente.

Hay documentación de API más detallada y extensa disponible en nuestro sitio de documentación.

Límites de llamadas

Si está utilizando cuentas de desarrollador, tenga en cuenta que hay un límite de llamadas. Esto es normalmente 120 llamadas por hora o 600 llamadas por período de 24 horas.

Para las cuentas de suscripción, sus límites de llamadas se determinan según su cuenta y contrato. Si alcanza sus límites de llamadas, deberá comunicarse con su gerente de cuenta o soporte para aumentarlos.

Una vez que haya excedido sus límites de llamada, su llamada devolverá el estado 429 Demasiadas solicitudes.

Registros

Como todas las transacciones estándar, las llamadas a la API se registran en la red XcooBee. Tienen las mismas restricciones de tiempo de vida (TTL).

Empezando

Punto final API

Para usar el punto final de la API de prueba, configure una variable de entorno XBEE_STATE = prueba.

ejemplo:






exportar XBEE_STATE = prueba

o si estás en Windows:






establecer XBEE_STATE = prueba

usando PHP:






putenv ('XBEE_STATE = prueba');

El objeto config

El objeto config contiene toda la información de configuración básica para su configuración y uso específicos. Puede ser manejado de manera transparente por el SDK o específicamente pasado a cada función.
La información básica en la configuración es:

  • su clave de API de XcooBee
  • tu api-secreto de XcooBee
  • tu pgp-secret / passphrase ya sea de ti o de XcooBee
  • su ID de campaña predeterminada de XcooBee

El SDK intentará determinar el objeto de configuración en función del siguiente esquema:

1.) Use el objeto de configuración pasado a la función.

2.) Use la información establecida por la llamada setConfig.

3.) Verifique el sistema de archivos para el archivo de configuración (.xcoobee / config)

Sobre PGP Secret y contraseña

Todos los datos PGP son opcionales para el objeto de configuración. Si no lo proporciona, el SDK omitirá los pasos de descifrado / cifrado. Tendrá que hacer esto fuera del SDK y suministrar o procesar los datos usted mismo.

Actualmente todos eventos a la que se suscribe desde la red XcooBee se comunicará con una capa adicional de cifrado PGP. Deberá descifrar la carga utilizando su clave privada PGP.

Si proporciona la clave privada PGP y su frase de contraseña al SDK, el SDK descifrará automáticamente la carga útil y proporcionará contenido para su posterior procesamiento.

setConfig (configModel)

los setConfig La llamada es el mecanismo para crear el objeto de configuración inicial. Puedes usarlo varias veces. Cada vez que llame, anulará los datos existentes. Los datos una vez establecidos persistirán hasta que la biblioteca se descarte o clearConfig se llama.






apiKey => la clave api proporcionada por la cuenta XcooBee apiSecret => el secreto api (descargado cuando se creó la clave api en XcooBee) pgpSecret => la clave secreta pgp generada por XcooBee o suministrada por usted pgpPassword => el pgp -contraseña suministrada por ID de campaña => el ID de campaña predeterminado de su campaña en XcooBee pageSize => límite de paginación (registros por página), predeterminado basado en el conjunto de registros, el máximo posible es 100

clearConfig ()

Elimina todos los datos de configuración en el objeto de configuración.

config en el sistema de archivos

XcooBee SDK buscará en el sistema de archivos la información de configuración como último mecanismo. Debe asegurarse de que el acceso a los archivos de configuración no sea público y esté debidamente protegido. Una vez encontrada, la información se almacena en caché y no se realizan más búsquedas. Si cambia su configuración, deberá reiniciar el proceso que está utilizando el SDK para recoger los cambios.

Le recomendamos que también busque cómo cifrar el contenido de estos archivos con un cifrado específico del sistema operativo para usar solo en el proceso que usa el SDK de XcooBee.

Los archivos se ubicarán dentro de su hogar directorio en el .xcoobee subdirectorio. Por lo tanto, la ruta completa a la configuración son:

/[homefont>/.xcoobee/config => las opciones de configuración

/[homefont>/.xcoobee/pgp.secret => la clave secreta pgp en un archivo separado

en Windows está en la raíz de su directorio de usuario

/Users/MyUserDir/.xcoobee/config => la opción de configuración

/Users/MyUserDir/.xcoobee/pgp.secret => la clave secreta pgp en un archivo separado

El contenido inicial del archivo de configuración es texto sin formato, con cada opción en una línea separada.

archivo de ejemplo:






apiKey = 8sihfsd89f7 apiSecret = 8937438hf campaignId = ifddb4cd9-d6ea-4005-9c7a-aeb104bc30be pgpPassword = somethingsecret pageSize = 10

opciones:






apiKey => la api-key apiSecret => el api-secret campaignId => el id. de campaña predeterminado pgpPassword => la contraseña para su clave pgp pageSize => límite de paginación

Respuestas estándar

El sistema XcooBee tiene dos modos de respuesta. Uno, basado en llamadas web estándar API REST HTTP, y dos basado en webhooks asíncronos (HTTP POST) cuando ocurren eventos.

El paquete de respuesta está estructurado en sobre y detalles. El sobre contiene resultados operativos como error o éxito y marcas de tiempo. El detalle contiene datos de devolución asociados para su llamada. XcooBee SDK siempre devolverá un valor, incluso si es un objeto de error. En resumen, siempre hay un retorno. La ausencia de una devolución debe tratarse como un error en las respuestas estándar.

Las respuestas de Webhook (HTTP POST) se basan en prácticas asincrónicas. El sistema XcooBee se comunicará con usted y le informará sobre el evento. Estos están cubiertos más abajo en este documento.

Paquete de éxito

Estructura del objeto para la respuesta:

  • hora
  • código (código de respuesta 200-299)
  • request_id (la referencia de solicitud asociada)
  • resultado (objeto de datos)
    • el objeto resultante se firma con su clave PGP pública si se trata de un evento respuesta.

Paquete de error

Estructura de objeto para respuesta de error:

  • hora
  • código (código de respuesta: 300-500)
  • request_id (la referencia de solicitud asociada)
  • errores (matriz de objetos de error con datos: mensaje, detalle)

Webhook Events (HTTP POST)

A través del SDK, puede suscribirse a muchos eventos que están disponibles en la red XcooBee. Como esto ocurre en diferentes momentos, deberá poder aceptar la comunicación de XcooBee a través de HTTP POST a un sitio de destino que esté disponible a través de Internet.

Como alternativa a un sitio público, puede utilizar el mecanismo de sondeo de eventos como se describe más adelante en este documento para recibir esta comunicación.

Metodología

Si hay una respuesta retrasada, se aceptará la llamada y se devolverá la respuesta a través de la configuración del evento HTTP POST. Su sistema debe tener un punto final web al que pueda acceder el sistema XcooBee para las respuestas del evento. Un webhook no es un punto final REST (basado en verbo HTTP).

El sistema webhook usa HTTPS ENVIAR llama para enviarle información en respuesta al evento en el procesamiento de XcooBee. Te suscribes a eventos llamando al Sistema-> addEventSubscription () método. Más información y ejemplos disponibles en examples / addEventSubscription.php en este proyecto.

Los sistemas de llamadas deben tener en cuenta que puede haber demoras y que las respuestas pueden devolverse en un orden diferente al de la llamada.

Firma de entrega de Webhook

Las cargas útiles HTTP POST que se entregan al punto final de URL configurado de su webhook contendrán varios encabezados especiales:

Encabezamiento Descripción
EVENTO XBEE Tipo de evento que desencadenó la entrega. Por ejemplo, consentimiento aprobado
XBEE-TRANS-ID Un GUID que identifica este evento
FIRMA XBEE El resumen hexadecimal HMAC del cuerpo de respuesta *
XBEE-HANDLER Nombre de una función que se configuró como controlador para el tipo de evento actual
  • los FIRMA XBEE el encabezado se enviará si el webhook está configurado con un secreto. El resumen hexadecimal HMAC se genera utilizando la función hash sha1 y el secreto como la clave HMAC.

Implementación de la aceptación de Webhook

Puede implementar su propio aceptador de webhook y manejar toda la información que se le pase de esa manera. Github tiene una buena revisión estándar de este proceso. Ejemplos de Webhook de Github

Use las herramientas del SDK para el manejo de eventos

El SDK ofrece una metodología para aceptar webhooks (HTTP POSTS) que:

  • valida el contenido y las firmas
  • maneja el cifrado / descifrado
  • gestiona los controladores de eventos

Este es un proceso de varios pasos que en realidad es simple en la implementación final. Involucra tres partes:

a) determine cómo desea recibir eventos

b) registre su suscripción de evento y pares de controladores

c) procesar eventos entrantes

una Determinar cómo recibir eventos

Tiene dos opciones sobre cómo recibir eventos de la red XcooBee. Publicación HTTP de evento (webhook) o sondeo de evento.

HTTP POST

Cuando opta por utilizar HTTP POST, debe proporcionar un sistema o punto final accesible desde la web con el que la red XcooBee pueda comunicarse directamente. Esto ocurre normalmente a través del puerto 443 (HTTPS / TLS). Cuando ocurre un evento en la red XcooBee, por ejemplo, un usuario cambia su acuerdo de consentimiento, la red XcooBee activará un evento en este punto final.

Usted especifica su URL de destino durante la configuración de su campaña de consentimiento en la interfaz de usuario de XcooBee. No puede cambiarlo ni configurarlo a través del SDK.

Encuesta de eventos

Como alternativa, puede sondear eventos desde su sistema en un intervalo regular. Esto es útil cuando no tiene un sistema accesible desde la web o está en modo de desarrollo. El SDK tiene un método de apoyo. getEvents que le permite recuperar todos los eventos a los que se ha suscrito y que ocurrieron durante las últimas 72 horas.

Para fines de prueba, también encontrará una aplicación de página única (SPA) en encuestador directorio de este proyecto. Sondeará y volverá a enviar eventos a los puntos finales de la red interna.

si Registre su suscripción a eventos y pares de controladores

Esta es una de las partes más simples. A medida que se suscribe a eventos utilizando el addEventSubscription () también proporciona la función PHP que desea invocar cuando dicho evento se devuelve como argumento de función. Vea la definición de la función para más información.

C Procesar eventos entrantes

La forma más fácil de procesar eventos entrantes es invocar el handleEvents ([evento]) método de la Sistema clase.

Normalmente esto se incluye en el punto final de su sitio (página) que recibe la POST HTTP de XcooBee. Si realiza un sondeo de eventos, puede pasar el cuerpo POST completo como evento a la función.

Esta manejar eventos validará la llamada y llamará a sus controladores que ha declarado en el paso si

Punto final estándar (URL de destino)

Si elige aceptar eventos a través de webhook (HTTP POST), le recomendamos que cree un punto final estándar para manejar toda la comunicación. Durante el procesamiento de esta página, puede llamar al handleEvents () método.

El punto final estándar para crear sería / xbee / webhook

Si su sitio se ejecuta en localhost la URL de destino del webhook completamente formada sería http://localhost/xbee/webhook.

Dependiendo de su marco y biblioteca de sintaxis, esto también puede ser:

  • /xbee/webhook.php
  • /xbee/webhook.jsp
  • /xbee/webhook.cfm
  • /xbee/webhook.aspx

Llamadas al sistema

ping ([config])

Se puede llamar para ver si la configuración actual se conectará al sistema XcooBee. Esto devolverá un error si su usuario de API no tiene una clave PGP pública en su perfil.

opciones:






config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si el éxito
  • estado 400 si error

addEventSubscription (arrayOfEventAndHandlerPairs [, campaignId, config])

Puede registrar suscripciones en ganchos llamando a la función addEventSubscription y proporcionando el evento (como se especifica en este documento) y pares de controladores eventname => handler.

No hay suscripción de evento comodín, sin embargo, puede agregar muchos controladores a la vez.

Ejemplo:






$xcoobee-> system-> addEventSubscription (['ConsentDeclined' => 'declinedHandler'], 'ifddb4cd9-d6ea-4005-9c7a-aeb104bc30be', $config);

Esto lo suscribirá en el sistema XcooBee para recibir Consentimiento Rechazado eventos para el ifddb4cd9-d6ea-4005-9c7a-aeb104bc30be campaña y llame a su controlador llamado declinedHandler (evento) cuando ocurre tal evento.

Todos los datos del evento se adjuntan al eventos objeto en la función llama.

No se espera respuesta directa de ninguno de los controladores de eventos, por lo que las devoluciones son nulas / nulas.

opciones:






arrayOfEventAndHandlerPairs => matriz con evento y mapas de controlador campaignId => opcional: el ID de la campaña que se usará si no es la configuración predeterminada => opcional: el objeto de configuración

respuesta

objeto de respuesta JSON estándar

  • estado 200 si el éxito
  • estado 400 si error

listEventSubscriptions ([campaignId, config])

enumerar suscripciones actuales.

opciones:






campaignId => opcional: solo obtiene suscripciones para el id de campaña config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • los datos contendrán el conjunto de datos de suscripciones actuales: tipo, campaña, último
  • estado 400 si error

deleteEventSubscription (arrayOfEventNames [, campaignId, config])

Eliminar suscripciones existentes.
Si no proporciona una ID de campaña, se eliminará el evento para la ID de campaña predeterminada. Si la suscripción no existe, aún le devolveremos el éxito.

opciones:






arrayOfEventNames => matriz con nombres de eventos para cancelar la suscripción campaignId => opcional: el ID de la campaña que se usará si no es el predeterminado config => opcional: el objeto de configuración

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • los datos contendrán el número de suscripciones eliminadas
  • estado 400 si error

triggerEvent (tipo [, config])

Activa el evento de prueba para el webhook de campaña configurado. La estructura será la misma que la del evento real (con carga útil cifrada y firma HMAC).
También recibirás XBEE-TEST-EVENT encabezado, que indica que el evento es prueba. Si el webhook de la campaña no está configurado, recibirá un error.

opciones:






tipo => nombre del evento config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • los datos contendrán datos de eventos de prueba
  • estado 400 si error

handleEvents (eventos)

Esta función no requiere una llamada a la API XcooBee. Es más bien el controlador de llamadas que recibe de XcooBee a través de webhooks como se describe anteriormente.

Debe incrustar esta función en el procesador de ruta / punto final que se invoca cuando XcooBee le devuelve uno de los eventos para los que se ha registrado anteriormente. Puede averiguar qué eventos son estos llamando al listEventSubscriptions método.

La publicación webhook se validará en este método y, si la publicación es válida, analizaremos los eventos registrados e invocaremos la función de marcador de posición asignada para cada evento que se creó con el addEventSubscription () método.

Opcionalmente, el objeto de datos de eventos se puede pasar junto con los datos del encabezado HTTP y la llamada POST.

Hay dos modos de operación para handleEvents ().

a) Sin parámetro de función eventos:

Cuando usted llama handleEvents () sin un eventos argumento de función, el método buscará los datos del evento en la secuencia de webhook (HTTP POST). Verifique las firmas HTTP con las firmas esperadas y luego procese el evento.

b) Con parámetro de función eventos:

En caso de que encuesta por eventos de XcooBee por separado, puede llamar handleEvents (eventos) directamente con los eventos. Si proporciona los eventos específicamente, el método no buscará variables de encabezado HTTP POST para la verificación y en su lugar procesará directamente los eventos según lo previsto.

opciones:






eventos => opcional: matriz de objetos con datos de publicación HTTP

respuesta

  • sin respuesta, ya que esta es una llamada interna a los controladores de eventos asignados

getEvents ([config])

En los casos en que no pueda usar publicaciones directas de webhook en sus sitios, por ejemplo, esté en desarrollo o no se pueda acceder a su sistema directamente a través de Internet, puede extraer sus eventos de XcooBee.

Si está utilizando el acceso basado en extracción, asegúrese de no tener un Endpoint definido en su campaña, ya que XcooBee intentará publicar en el endpoint y registrará un error. Sin un punto final de campaña, XcooBee guardará los eventos a los que se suscriba y responderá a sus solicitudes de extracción.

Tienes 72 horas para recoger los eventos guardados. Una vez extraídos, los eventos se eliminarán. Por lo tanto, asegúrese de guardarlos si necesita reproducirlos.

Su intervalo de extracción no debe ser más de 1 getEvents () llamada por minuto, de lo contrario, se devolverá el error HTTP 429. Recomendamos cada 62 segundos para evitar problemas con el temporizador.

opciones:






config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • los datos contendrán una variedad de eventos desde la última llamada
  • estado 400 si error

Consentimiento La Administración Pide Consentimiento

getCampaignInfo ([campaignId, config])

Obtenga información básica sobre la campaña (configuración, tipos de datos y opciones). La información no devolverá a los usuarios registrados en la campaña.

opciones:






campaignId => opcional: el ID de la campaña que se usará si no es la configuración predeterminada => opcional: el objeto de configuración

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • los datos contendrán el objeto de datos de la campaña
  • estado 400 si error

listCampaigns ([config])

obtener todas las campañas de usuario

opciones:






config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • los datos contendrán una variedad de objetos de campaña
  • estado 400 si error

getDataPackage (packagePointer [, config])

A SER IMPLEMENTADO:

Cuando los datos están alojados para usted en XcooBee, puede solicitar el paquete de datos cada vez que necesite usarlos. Deberá proporcionar packagePointer. Esta llamada solo responderá a la fuente de llamada autorizada.

opciones:






packagePointer => el packagePointer para los datos que desea recibir config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • los datos contendrán el objeto de datos solicitado
      El SDK lo descifrará si tiene acceso a las claves PGP; de lo contrario, tendrá que descifrar este objeto.
  • estado 400 si error

listConsents ([statusIds, config])

Consulta la lista de consentimientos para una campaña determinada. La empresa puede obtener un ID de consentimiento general para cualquier consentimiento que se haya creado como parte de una campaña. Este es un conjunto de registros de varias páginas. Datos devueltos: consentId, fecha de creación, fecha de vencimiento, xcoobeeId

posible respuesta / filtro para el estado:

0 = pendiente, 1 = activo, 2 = actualización, 3 = oferta, 4 = cancelado, 5 = expirado, 6 = rechazado

opciones:






statusIds => opcional: conjunto de números, uno de los estados de consentimiento válidos, si no se especifica, todos serán devueltos config => opcional: el objeto de configuración

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • el objeto de datos contendrá el objeto de datos de consentimiento: consent_id, status_id, date_c, date_e, xcoobee_id
  • estado 400 si error

getConsentData (consentId [, config])

Consulta por un consentimiento específico otorgado. La empresa puede obtener una definición de consentimiento para cualquier consentimiento que se haya creado. Los datos normalmente tienen tres áreas: quién, qué tipos de datos, cuáles son los usos, cuánto tiempo.

opciones:






consentId => el Id. de consentimiento para el cual recuperar información config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • objeto de datos contendrá objeto de datos de consentimiento: usuario, tipos de datos, tipos de consentimiento, caducidad
  • estado 400 si error

getCookieConsent (xid [, campaignId, config])

Este es un mecanismo de acceso directo para consultar el sistema XcooBee para obtener el consentimiento del usuario existente para el tipo de consentimiento Seguimiento de sitios web (1400), seguimiento de aplicaciones web (1410) para tipos de datos de uso específico (cookie de aplicación (1600), cookie de uso (1610) y cookie de publicidad (1620)) Solo recuperaremos el consentimiento activo para las cookies en el sitio web identificado en el ID de la campaña y devolveremos si el usuario ha aceptado alguna cookie.

Nota:

  • Su sitio en su campaña debe coincidir con el origen de la llamada, ya que no utilizamos el cifrado PGP en esta llamada para mayor velocidad.
  • El usuario debe iniciar sesión en XcooBee

El regreso es una lista CSV como esta:

  • aplicación, uso, publicidad

opciones:






xid => XcooBee Id del usuario para verificar el consentimiento campaignId => opcional: el id. de campaña que se usará si no es el predeterminado config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • el objeto de datos contendrá el consentimiento de cookies del sitio web CSV: aplicación, uso, publicidad
  • estado 400 si error

requestConsent (xid [, refId, campaignId, config])

Envía el consentimiento o solicitud de consentimiento y datos a un usuario específico que utiliza los datos de la campaña. La definición de campaña determina qué datos (solo consentimiento o consentimiento + datos) le pediremos al usuario.

opciones:






xid => XcooBee Id del usuario para verificar el consentimiento refId => opcional: Id de referencia generado por usted que le identifica esta solicitud. Máx. 64 caracteres. Esto se le devolverá en respuesta al evento campaignId => opcional: la identificación de la campaña que se usará si no es predeterminada config => opcional: el objeto de configuración

Cuando el usuario responde a la solicitud de consentimiento, un webhook se disparará desde XcooBee al punto final identificado en la campaña. El SDK no permite que se creen o cambien puntos finales. Por favor use la GUI.

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • objeto de datos contendrá verdadero
  • estado 400 si error

confirmConsentChange (consentId [, config])

Use esta llamada para confirmar que los datos han cambiado en los sistemas de la compañía de acuerdo con los cambios solicitados por el usuario.

opciones:






consentId => el consentimiento para el que se deben confirmar los datos config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • objeto de datos contendrá verdadero
  • estado 400 si error

confirmDataDelete (consentId [, config])

Enviar por empresa para confirmar que los datos se han purgado de los sistemas de la empresa.

opciones:






consentId => el consentimiento para el que se han eliminado los datos config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • objeto de datos contendrá verdadero
  • estado 400 si error

setUserDataResponse (message, consentId [, requestRef, filename, config])

Las empresas pueden responder a los datos del usuario solicitados a través de esta llamada. Los puntos de contratación estándar se deducirán por esto. La llamada enviará un mensaje al centro de comunicación del usuario. También debe enviar un archivo con los datos del usuario para cerrar la solicitud de datos.

opciones:






mensaje => el texto que se enviará al usuario como consentimiento de datos de usuario Id => el consentimiento para el que se han eliminado los datos requestRef => opcional: identificador único de la solicitud de datos, recibirá esto en el evento `UserDataRequest` nombre de archivo => opcional : puntero al archivo que contiene los datos del usuario config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • objeto de datos contendrá verdadero
  • estado 400 si error

Estos son eventos devueltos a su punto final como parte del usuario que trabaja con su centro de consentimiento. Todos los puntos finales se determinan dentro de cada campaña de consentimiento.

Consentimiento aprobado

Se activa cuando se aprueba una solicitud de consentimiento. Se devuelve el objeto de consentimiento.
Contiene:

  • referencia de consentimiento
  • tipos de datos
  • tipos de consentimiento
  • vencimiento

Consentimiento Rechazado

Se activa cuando se rechaza una solicitud de consentimiento. Debe eliminar los datos del usuario y enviar una confirmación de XcooBee a través de confirmDataDelete ().
Los datos enviados contienen:

  • referencia de consentimiento

Consentimiento modificado

Se dispara cuando se cambia el consentimiento. Se devuelve un objeto de consentimiento estándar.
Contiene:

  • referencia de consentimiento
  • tipos de datos
  • tipos de consentimiento
  • vencimiento

Consentimiento Cerca de Vencimiento

Se activa cuando un consentimiento activo está a punto de caducar (dentro de los 30 días). Esto no es exactamente 30 días ya que los procesos del sistema XcooBee pueden impulsar esto ligeramente. Debe planear solicitar la renovación del consentimiento si desea utilizar los datos del usuario por más tiempo.
Contiene:

  • referencia de consentimiento
  • vencimiento

Consentimiento expirado

Se dispara cuando expira el consentimiento. Debe eliminar los datos del usuario y enviar la confirmación de XcooBee a través de confirmDataDelete ().
Contiene:

  • referencia de consentimiento

UserDataRequest

Se activa cuando el usuario realiza una solicitud para extraer sus datos actuales de sus sistemas. Esto es para cumplir con la portabilidad de datos de GDPR. Debe crear un extracto de datos y enviarlo al cuadro XcooBee del usuario. Puedes hacerlo contratando el xcoobee-data-response abeja con la referencia GUID de la solicitud.
Contiene:

  • referencia de consentimiento
  • xcoobeeId

UserMessage

Se activa cuando el usuario le envía un mensaje con respecto a una solicitud de consentimiento.
Su campaña puede habilitar / deshabilitar esta función en opciones de campaña. Puede responder a esto usando un sendUserMessage () llamada.
Contiene:

  • referencia de consentimiento
  • xcoobeeId
  • mensaje

La Administración de Consentimiento Pide Datos

Esta sección cubre los eventos que se utilizan en relación con la recopilación de datos y el consentimiento al mismo tiempo.

Eventos de datos (webhooks)

Eventos enviados por XooBee a su sistema.

Datos aprobados

Se activa cuando se otorga el consentimiento y el usuario ha proporcionado los datos. Se devuelve un objeto de consentimiento estándar.
Contiene:

  • referencia de consentimiento
  • tipos de datos con datos
  • tipos de consentimiento
  • vencimiento

Datos rechazados

Se activa cuando el usuario se niega a proporcionar datos y consentimiento. Debe eliminar los datos del usuario y enviar la confirmación de XcooBee a través de confirmDataDelete ().
Contiene:

  • referencia de consentimiento

DataChanged

Se activa cuando se modifican los datos o el consentimiento. Se devuelve un objeto de consentimiento estándar.
Contiene:

  • referencia de consentimiento
  • tipos de datos con datos
  • tipos de consentimiento
  • vencimiento

DataNearExpiration

Se activa cuando un consentimiento activo está a punto de caducar (dentro de los 30 días).
Esto no es exactamente 30 días ya que los procesos del sistema XcooBee pueden impulsar esto ligeramente.
Debe planear solicitar la renovación del consentimiento si desea utilizar los datos del usuario por más tiempo.
Contiene:

  • referencia de consentimiento
  • vencimiento

Datos expirados

Se dispara cuando los datos han expirado. Debe eliminar los datos del usuario y enviar la confirmación de XcooBee a través de confirmDataDelete ().
Contiene:

  • referencia de consentimiento

UserDataRequest

Se activa cuando el usuario realiza una solicitud para extraer sus datos actuales de sus sistemas.
Esto es para cumplir con la portabilidad de datos de GDPR.
Debe crear un extracto de datos y enviarlo al cuadro XcooBee del usuario.
Puedes hacerlo contratando el xcoobee-data-response abeja con la referencia GUID de la solicitud.
Contiene:

  • referencia de consentimiento
  • xcoobeeId

UserMessage

Se activa cuando el usuario le envía un mensaje con respecto a una solicitud de consentimiento.
Su campaña puede habilitar / deshabilitar esta función en opciones de campaña. Puede responder a esto usando el sendUserMessage () función.
Contiene:

  • referencia de consentimiento
  • xcoobeeId
  • mensaje

Mensaje

sendUserMessage (mensaje, consentimiento, [breachid], [config])

Esta función le permite enviar un mensaje a los usuarios. Puede comunicar problemas relacionados con incumplimiento, consentimiento y datos de esta manera. Creará una discusión entrelazada para el usuario y para usted y le agregará este mensaje.

opciones:






mensaje => el texto que se enviará al usuario como datos de usuario, se puede formatear en html. Máx.2000 caracteres consentId => el Id. De consentimiento que activa la notificación breachId => opcional: incumplimiento relacionado, el usuario recibirá un mensaje con las acciones propuestas declaradas en un incumplimiento config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • objeto de datos contendrá verdadero
  • estado 400 si error

getConversations ([config])

Esta función le permite obtener una lista de discusiones con los usuarios sobre infracciones, consentimientos, etc.

opciones:






config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • objeto de datos contendrá verdadero
  • estado 400 si error

getConversation (userId [, config])

Esta función le permite tener una discusión completa con el usuario seleccionado.

opciones:






userId => id de usuario config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • objeto de datos contendrá verdadero
  • estado 400 si error

Incumplimiento

La API de incumplimiento es la forma principal de interactuar con los usuarios durante el incumplimiento. La declaración de incumplimiento y las notificaciones iniciales se producen en la interfaz de usuario.

Eventos de incumplimiento (webhooks)

Infracción Presentado

Se activa cuando el usuario ha abierto un aviso de incumplimiento.
Contiene:

  • referencia de consentimiento

IncumplimientoAbejaUsado

Se activa cuando el usuario ha utilizado una abeja que ha identificado en el aviso de incumplimiento.
Contiene:

  • referencia de consentimiento
  • referencia de abeja

UserMessage

Se activa cuando el usuario le envía un mensaje con respecto a una solicitud de consentimiento.
Su campaña puede habilitar / deshabilitar esta función en opciones de campaña. Puede responder a esto usando el sendUserMessage () función.
Contiene:

  • referencia de consentimiento
  • xcoobeeId
  • mensaje

API de abeja

La API de abeja es la interfaz principal para contratar abejas. La mayoría de las veces esto se logrará en dos pasos. En el primer paso, carga sus archivos para que sean procesados por las abejas usando subir archivos() llamada. Si no especificó un punto final de la bandeja de salida, también deberá llamar al quitarse() funcionar con los parámetros de procesamiento para la abeja.

La respuesta inmediata solo cubrirá problemas con los archivos de la primera abeja. Si desea estar informado sobre el progreso del procesamiento, deberá suscribirse a los eventos.

listBees (searchText [, config])

Esta función lo ayudará a buscar entre las abejas en el sistema que su cuenta puede contratar. Esta es una interfaz de búsqueda de palabras clave simple.

opciones:






searchtext => cadena de palabras clave para buscar en el nombre del sistema de abejas o etiqueta en el idioma de su cuenta config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • El objeto de datos contendrá datos básicos de la abeja: nombre del sistema de la abeja, etiqueta de la abeja, costo de la abeja, tipo de costo
  • estado 400 si error

uploadFiles (archivos [, punto final, config])

Utiliza la función uploadFiles para cargar archivos desde tu servidor a XcooBee. Puede cargar varios archivos y, opcionalmente, puede proporcionar un punto final de salida. Si tiene un punto final de salida no necesita llamar al quitarse funcionar como el punto final ya especifica todos los parámetros de procesamiento. Si su suscripción lo permite, puede configurar los puntos finales de la bandeja de salida en la interfaz de usuario de XcooBee.

opciones:






files => conjunto de cadenas con punteros de archivo al almacén de archivos, por ejemplo: `c: \ temp \ mypic.jpg` o` / home / mypic.jpg` endpoint => opcional: el punto final de la bandeja de salida, por ejemplo, `datos de marketing` o `POS drop point` config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • objeto de datos contendrá verdadero
  • estado 400 si error

takeOff (abejas, opciones [, suscripciones, config])

Normalmente usa esto como llamada de seguimiento a subir archivos(). Esto comenzará su procesamiento. Usted especifica las abejas que desea contratar y los parámetros necesarios para que la abeja funcione en sus archivos. Si desea mantenerse actualizado, puede proporcionar suscripciones. Tenga en cuenta que las suscripciones deducirán puntos de su saldo y causarán errores cuando su saldo sea insuficiente.

Esta es la llamada de función más compleja en la API de Bee y tiene múltiples opciones y partes.

a) parámetros
b) suscripciones
c) eventos de suscripción

opciones:






abejas => matriz de nombres de sistemas de abejas (por ejemplo, "xcoobee_digital_signature_detection") como clave y sus parámetros como valor opciones => opciones generales suscripciones => opcional: la matriz de suscripciones. Especifica las suscripciones config => opcional: la matriz de configuración

una Parámetros

Los parámetros pueden ser específicos de la abeja o aplicarse al trabajo general.

Ejemplo de parámetros específicos de la abeja:






$bees ['xcoobee_testbee'] = ['altura' => 599, 'ancho' => 1200,];

Los parámetros generales del trabajo que se utilizarán para la contratación se especifican con proceso prefijo que incluye los destinos (destinatarios) a los que desea enviar la salida del procesamiento.

Ejemplo de parámetros generales del proceso:






$options ['process'] ['userReference'] = 'myownreference'; $options ['proceso'] ['destinos'] = ['email @ null mysite.com', '~ jonny']; $options ['process'] ['fileNames] = [' filename.png '];

Los parámetros de abeja que se especifican requieren el prefijo de nombre de abeja. Si el nombre de la abeja es xcoobee_testbee y requiere dos parámetros altura y anchura entonces deberá agregarlos a una matriz asociativa dentro de la matriz de parámetros con una clave de nombre de abeja.

si Suscripciones

Las suscripciones se pueden adjuntar al proceso general. Deberá especificar un objetivo, un eventos y un manipulador argumento como mínimo. los objetivo El sistema XcooBee debe alcanzar el punto final a través de HTTP / S POST. los eventos determina a qué eventos se está suscribiendo.

Por lo tanto, las tres claves para cada suscripción son:

  • target => cadena con URL de punto final de destino
  • eventos => matriz con eventos de ciclo de vida para suscribirse
  • controlador => requerido: la función PHP que se llamará cuando tengamos eventos API de abejas

La firma HMAC asumirá su Id. XcooBee como clave secreta compartida y utilizará la clave pública PGP para cifrar la carga útil. Sin esto, todavía está utilizando el cifrado SSL para la transferencia.

Para suscribirse a eventos de proceso generales, la palabra clave proceso necesita ser usado. Los detalles de la suscripción deben adjuntarse como subclaves.

Recuerde que las suscripciones deducen puntos de su saldo incluso si no tienen éxito, por lo tanto, valide que los puntos finales que especifique en objetivo son validos.

Ejemplo de suscripción en el proceso general.

ejemplo de suscripciones:






Procesar suscripciones: $subscriptions ['target'] = "https://mysite.com/beehire/notification/" $subscriptions ['events'] = ["error", "éxito", "entregar", "presentar", "descargar "," delete "," reroute "] $subscriptions ['handler] =" myBeeEventHandler "

C Eventos de suscripción

El sistema de eventos para las abejas utiliza eventos a nivel de proceso.

Eventos de nivel de proceso

  • error
    • Hubo un error en el procesamiento de la transacción. Si hay varios errores, cada uno de ellos se envía en una publicación separada.
    • Tipo de evento enviado en el encabezado POST - ProcessError
  • éxito
    • La transacción general se completó con éxito.
    • Tipo de evento enviado en el encabezado POST - Proceso de éxito
  • entregar
    • Si hubo una transferencia de un archivo, el archivo se entregó a la bandeja de entrada del destinatario
    • Tipo de evento enviado en el encabezado POST - ProcessFileDelivered
  • presente
    • Si hubo una transferencia de un archivo, el usuario vio el archivo
    • Tipo de evento enviado en el encabezado POST - ProcessFilePresented
  • descargar
    • Si hubo una transferencia de un archivo y el usuario descargó el archivo
    • Tipo de evento enviado en el encabezado POST - ProcessFileDownloaded
  • Eliminar
    • Este evento ocurre cuando el usuario elimina el archivo
    • Tipo de evento enviado en el encabezado POST - ProcessFileDeleted
  • desviar a
    • Cuando el usuario ha automatizado las reglas de la bandeja de entrada y el documento se ha enviado a un lugar diferente, se desencadena un evento de redireccionamiento
    • Tipo de evento enviado en el encabezado POST - ProcessReroute

Ejemplos de carga útil de eventos:

  • ejemplo de evento de éxito:





{"fecha": "2017-12-04T16: 50: 40.698Z", "archivo": "myImage.jpg", "userReference": "88jenr", "destinatario": "~ john873", "evento": " success "," eventLevel ":" bee "," source ":" Block4-post "," beeName ":" xcoobee_image_resizer "," transactionName ":" 9SDd8ccb "}
  • ejemplo de evento de error:





{"fecha": "2017-10-24T15: 22: 39.209Z", "archivo": "myhome2.jpg", "userReference": "sin referencia", "destinatario": "sin destinatario", "evento ":" error "," eventLevel ":" bee "," source ":" Block4-post "," beeName ":" xcoobee_image_converter "," message ":" Error de tiempo de espera en proceso de contenedor "," transacciónName ":" 0P4bbee "}

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • objeto de datos contendrá verdadero
  • estado 400 si error

API de bandeja de entrada

La API de la bandeja de entrada rige el acceso a su bandeja de entrada. Puede enumerar, descargar y eliminar elementos de su bandeja de entrada.

listInbox ([config])

Este método presentará una lista paginada de elementos de la bandeja de entrada que puede descargar. La lista será para el usuario conectado a su clave API. No puede verificar la bandeja de entrada de ningún otro usuario utilizando este método. Puede devolver hasta 100 artículos en una llamada.
Llamar a este método más de una vez por minuto dará como resultado un error HTTP 429 (que excede los límites de llamadas).

Tendrás los siguientes puntos de datos:

  • ID de mensaje
  • remitente
  • nombre del archivo
  • fileSize (en bytes)
  • fecha de recepción
  • fecha de caducidad
  • downloadDate

Los artículos de la bandeja de entrada se enumeran en orden de llegada con los artículos más recientes primero.

opciones:






config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • El objeto de datos contendrá una lista de elementos de la bandeja de entrada en la matriz: messageId, remitente, fileName, fileSize, reciboDate, expirationDate, downloadDate
  • estado 400 si error

getInboxItem (messageId [, config])

Este método devolverá un archivo y metaetiquetas de archivo. Una vez descargado por primera vez, el downloadDate para el artículo será poblado.

opciones:






messageId => el id del mensaje para el archivo que se descargará config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • el objeto de datos contendrá el archivo y el objeto file_meta (userRef, fileType, fileTags)
  • estado 400 si error

deleteInboxItem (messageId [, config])

Este método eliminará un archivo que corresponda a su ID de mensaje. Si el archivo no existe, se devolverá un error.

opciones:






messageId => el Id del mensaje para el archivo que se va a eliminar config => opcional: el objeto config

respuesta

objeto de respuesta JSON estándar

  • estado 200 si tiene éxito:
    • objeto de datos contendrá verdadero
  • estado 400 si error

API de usuario

getUserPublicKey (xid [, config])

Recupera la clave PGP pública de un usuario tal como se publicó en su perfil público. Si el usuario eligió ocultarlo o el usuario no es conocido, devuelve nulo.

ejemplo:






getUserPublicKey ('~ XcooBeeId');

opciones:






xid => XcooBee Id del usuario para obtener su clave pública PGP config => opcional: el objeto config

respuesta

PGP público o nulo

Solución de problemas

Error 401

Ciertas llamadas SDK requieren orígenes autorizados.

Puede recibir 401 respuestas de error de XcooBee si su llamada a la API se origina en un dominio o IP no autorizado. Asegúrese de haber registrado su dominio en su campaña XcooBee URL de devolución de llamada opción.

Error 429

Una vez que haya excedido sus límites de llamada, su llamada devolverá el estado 429 Demasiadas solicitudes. Actualice su suscripción o póngase en contacto con el servicio de asistencia.

¿Te ayudó este artículo? si No

¿Cómo podemos ayudar?