Webhooks (eventos) en Stockcrowd.

Explicamos aquí como puedes usar nuestro servicio de eventos que permita mandar información desde nuestro backoffice a terceros.

Expliquemos primero ?

¿Qué son los webhooks?

En pocas palabras, los webhooks son eventos que desencadenan acciones. Su nombre se debe a que funcionan como «ganchos» de los programas en Internet y casi siempre se utilizan para la comunicación entre sistemas. Son la manera más sencilla de obtener un aviso cuando algo ocurre en otro sistema.

A continuación, te dejamos con una introducción y explicación a dónde están y como puedes usarlos dentro de Stockcrowd.

Esta guía incluye los distintos tipos de eventos que dispara StockCrowd y que sirven para integrarse con servicios web que recuperen los datos asociados a cada uno de los eventos

Eventos - Stockcrowd

Tipos de eventos

A continuación, se listan los tipos de eventos disponibles en el sistema:

Solicitud de pago confirmada -> Este evento se dispara cuando la donación se ha confirmado
Inscripción confirmada -> Este evento se dispara cuando la inscripción, a través de un formulario de firmas, se ha confirmado
Recompensa comprada -> Este evento se dispara cuando la recompensa se ha comprado

Back-Office de Eventos

El back-office de gestión de eventos se encuentra dentro del menú de ‘Eventos, en el apartado de ‘Organización’ del back-office de StockCrowd.

Los pasos para definir un evento son los siguientes:

Seleccionar el tipo de evento a configurar
Configurar la notificación, a través de una url o de un correo electrónico
Activar la notificación

Una vez la notificación esté activada el software de StockCrowd lanzará un evento colocando los datos de dicho evento en la url o en el correo electrónico configurados.

Tipo de datos

El tipo de codificación para cualquier evento es UTF-8

Para un evento de Solicitud de Pago confirmada los campos asociados son los siguientes:

Nombre del campo	Descripción	Longitud	Formato	Ejemplo	Obligatorio
EVENT	Tipo de evento	100	Char	INVERSOR_PAYMENT_SUCCEEDED	S
EVENT_ID	Identificador único del evento disparado	255	Char	be4fceab-1ff8-4ab8-ad5b-4e711be88766	S
FECHA	Fecha del registro en que se ha efectuado el pago	20	Date	2016-04-31 13:00:14	S
EMAIL	Cuenta de correo del donante	255	varChar	user1@domain1.com	S
NOMBRE	Nombre del donante	255	Char	Pedro	S
APELLIDOS	Apellidos del donante (en caso de que el formulario no pida el 2º apellido)	255	Char	Duque	S
CAMPAIGN_TITULO	Título de la campaña	255	Char	Cohete a la luna	S
PRIMER_APELLIDO	Primer apellido del donante	255	Char	Duque	S
SEGUNDO_APELLIDO	Segundo apellido del donante (necesario activar el segundo apellido en los formularios)	255	Char	Pérez	N
PREFIJO_TELEFONO	Prefijo telefónico del país del donante	5	Char	+34	N
ID_SOLICITUD	Identificado de la donación	20	Num	456	S
PASARELA_PAGO	Pasarela de pago usada	100	Varchar	Stripe	S
TRANSACTION_ID	Identificador de la transacción (facilitado por la pasarela de pagos)	255	Varchar	ch_1C9uu3BLADaPkItAiAGS1jCI	S
ORDER_ID	Número de orden solicitud de pago de StockCrowd (único). En caso de peticiones sucesivas se debería controlar que no se haya procesado con anterioridad. Esto puede ocurrir cuando una aportación pasa de anónima a usuario registrado	100	Varchar	879a9792-2b2f-49ca-bf03-1ab6d299e424	S
IMPORTE	Importe de la donación	20	Num	49.95	S
DIVISA	Divisa de la donación	3	Varchar	EUR	S
CAMPAIG_ID	Identificador de la campaña	12	Num	1234	S
DOCUMENTO	Número de documento del donante	20	Num	41125179Y	N
TELEFONO	Número de teléfono del donante	25	Num	612123123	N
DIRECCION	Dirección del donante	255	Varchar	C/ Bruc	N
CODIGO_POSTAL	Código postal del donante	10	Varchar	08037	N
CIUDAD	Ciudad del donante	100	Varchar	Barcelona	N
PROVINCIA	Provincia del donante	50	Varchar	Barcelona	N
ID_PROVINCIA	Código de provincia del donante (Disponible en donaciones de más de 100€ o si se solicita el certificado)	10	Varchar	08	N
PAIS	País del donante	105	Varchar	España	N
ID_PAIS	Código de país del donante Disponible en donaciones de más de 100€ o si se solicita el certificado)	2	Varchar	ES	N
TIPO_DOCUMENTO	Tipo de documento identificativo del donante	25	Varchar	DNI / CIF / NIE / OTRO	N
TIPO_PERSONA	Naturaleza jurídica del donante	805	Varchar	F,N,P = Persona Física J,E = Persona jurídica	N
RAZON_SOCIAL	Razón social (Disponible para personas jurídicas en donaciones de más de 100€ o si se solicita el certificado)	255	Varchar	StockCrowd Fanraising S.L.	N
ACEPTA_PUBLICIDAD	Aceptación del check del formulario	805	Varchar	S= Sí N= No	S
POLITICA_PRIVACIDAD	Aceptación del check del formulario	805	Varchar	S= Sí N= No	S
USUARIO_REGISTRADO_PAYPAL	Cuenta de Paypal del donante (Se usa en recurrencia con cuenta de Paypal)	35	Varchar	S= Sí N= No	S
NUMERO_PISO_LETRA	Número, piso y letra de la dirección del donante	150	Varchar	145, Entresuelo 2ª	N
IBAN	IBAN (disponible para formularios con la opción datos CRM activada)	150	Varchar	ES55 1251 4161 1165 5165 7323	N
IBAN_TITULAR	Titular IBAN (disponible para formularios con la opción datos CRM activada)	150	Varchar	Pedro Duque	N
PERIODICIDAD	Tipo de donación confirmada	30	Varchar	PUNTUAL, MENSUAL, TRIMESTRAL, ANUAL	N
UTM_SOURCE	UTM_SOURCE	200	Varchar	Google	N
UTM_MEDIUM	UTM_MEDIUM	200	Varchar	cpc	N
UTM_CAMPAIGN	UTM_CAMPAIGN	200	Varchar	spring_sale	N
UTM_TERM	UTM_TERM	200	Varchar	running+shoes	N
UTM_CONTENT	UTM_CONTENT	200	Varchar	logolink	N
EXTERNAL_ID	Valor del campo identificador externo de datos generales de la campaña	200	Varchar	SC45X22	N
ATEGORIA	Valor del selector de categorías de datos generales de la campaña	200	Varchar	Ventas	N
SUB_CATEGORIA	Valor del campo sub-categoría de datos generales de la campaña	200	Varchar	Electrodomésticos	N
SUBCUENTA_DEBE	Valor del campo sub-cuenta debe de datos generales de la campaña	200	Varchar	45600	N
SUBCUENTA_HABER	Valor del campo sub-cuenta haber de datos generales de la campaña	200	Varchar	45700	N
TPV	Valor del campo TPV de datos generales de la campaña	200	Varchar	45700	N
PAGO_RECURRENTE	S = Si \| N = No. Si se corresponde a un cargo recurrente	200	Varchar	S	N
PAGO_RECURRENTE_FCH_ALTA	Fecha en que se realizó el pago incial	200	Date	2016-04-31 13:00:14	N
PAGO_RECURRENTE_ORDER_ID	ORDER_ID referente al pago inicial	80	Varchar	879a9792-2b2f-49ca-bf03-1ab6d299e123	N
PAYMENT_TOKEN	Token de pago para operaciones Stripe, Paypal, Sepa, Sofort	150	Varchar	tok_1CuGtMHCXJNKLeGQWDNzgDuG	N
SOLICITA_CERTIFICADO_DONACION	S = Sí \| N = No. Si ha solicitado certificado de donación	805	Varchar	S	N
LOCALE	Idioma del usuario en formato IETF BCP 47	10	Varchar	es-ES	N
FUNDRAISER_NOMBRE	Nombre del creador de la campaña p2p	255	Varchar	Jhon Doe	N

Para un evento de Inscripción confirmada los campos asociados son los siguientes:

Nombre del campo	Descripción	Longitud	Formato	Ejemplo	Obligatorio
EVENT	Tipo de evento	100	Char	INVERSOR_PAYMENT_SUCCEEDED	S
EVENT_ID	Identificador único del evento disparado	255	Char	be4fceab-1ff8-4ab8-ad5b-4e711be88766	S
FECHA	Fecha del registro en que se ha efectuado el pago	20	Date	2016-04-31 13:00:14	S
EMAIL	Cuenta de correo del donante	255	varChar	user1@domain1.com	S
NOMBRE	Nombre del donante	255	Char	Pedro	S
APELLIDOS	Apellidos del donante (en caso de que el formulario no pida el 2º apellido)	255	Char	Duque	S
CAMPAIGN_TITULO	Título de la campaña	255	Char	Cohete a la luna	S
PRIMER_APELLIDO	Primer apellido del donante	255	Char	Duque	S
SEGUNDO_APELLIDO	Segundo apellido del donante (necesario activar el segundo apellido en los formularios)	255	Char	Pérez	N
PREFIJO_TELEFONO	Prefijo telefónico del país del donante	5	Char	+34	N
ID_SIGNATURE	Identificado de la inscripción	20	Num	456	S
CAMPAIG_ID	Identificador de la campaña	12	Num	1234	S
DOCUMENTO	Número de documento del donante	20	Num	41125179Y	N
TELEFONO	Número de teléfono del donante	25	Num	612123123	N
DIRECCION	Dirección del donante	255	Varchar	C/ Bruc	N
CODIGO_POSTAL	Código postal del donante	10	Varchar	08037	N
CIUDAD	Ciudad del donante	100	Varchar	Barcelona	N
PROVINCIA	Provincia del donante	50	Varchar	Barcelona	N
ID_PROVINCIA	Código de provincia del donante (Disponible en donaciones de más de 100€ o si se solicita el certificado)	10	Varchar	08	N
PAIS	País del donante	105	Varchar	España	N
ID_PAIS	Código de país del donante Disponible en donaciones de más de 100€ o si se solicita el certificado)	2	Varchar	ES	N
TIPO_DOCUMENTO	Tipo de documento identificativo del donante	25	Varchar	DNI / CIF / NIE / OTRO	N
TIPO_PERSONA	Naturaleza jurídica del donante	805	Varchar	F,N,P = Persona Física J,E = Persona jurídica	N
RAZON_SOCIAL	Razón social (Disponible para personas jurídicas en donaciones de más de 100€ o si se solicita el certificado)	255	Varchar	StockCrowd Fanraising S.L.	N
ACEPTA_PUBLICIDAD	Aceptación del check del formulario	805	Varchar	S= Sí N= No	S
POLITICA_PRIVACIDAD	Aceptación del check del formulario	805	Varchar	S= Sí N= No	S
NUMERO_PISO_LETRA	Número, piso y letra de la dirección del donante	150	Varchar	145, Entresuelo 2ª	N
ACEPTA_PUBLICACION_DATOS	S = Si \| N = No	805	Varchar	S	S
DESCRIPCION	En algunos casos se indicará la descripción asociada a una recogida de firmas.	255	Varchar	Carrer del Bruc 145	N

Para un evento de Recompensa comprada los campos asociados son los siguientes:

Nombre del campo	Descripción	Longitud	Formato	Ejemplo	Obligatorio
CHARSET	formato de codificación de caracteres		Char	UTF-8	S
EVENT	Tipo de evento	100	Char	RECOMPENSA_SOLD	S
EVENT_ID	Identificador único del evento disparado	255	Char	be4fceab-1ff8-4ab8-ad5b-4e711be88766	S
FECHA	Fecha registro de información asociada a la recompensa desde BOFAN	20	Date	2016-04-31 13:00:14	S
ID_SOLICITUD_RECOMPENSA	Identificador de recompensa asociada a la solicitud	12	Num	121	S
ID_RECOMPENSA_DETALLE	Identificador del detalle de recompensa que se ha cumplimentado	12	Num	206	S
EMAIL	Cuenta de correo del usuario que ha adquirido y completado la recompensa	255	Varchar	user1@domain1.com	S
NOMBRE	Nombre del usuario que inicia el proceso de pago	255	Char	Pedro o Pedro Duque	S
ID_CAMPAIGN_RECOMPENSA	ID Recompensa solicitada	255	Num	805	S
TITULO_RECOMPENSA	Título de la recompensa	50	Varchar	Camiseta personalizada	S
DIRECCION_RECOGIDA_ENTREGA	Dirección de recogida o entrega	50	Varchar	Paseo de la castellana	N
ORDER_ID	Número de orden correspondiente al pago	36	Varchar	33a86073-ab05-4b1e-81b4-7bbcfdca31ed	S
CANTIDAD	Cantidad de unidades a entregar	10	Num	3	S

Configuración del servicio de web de recuperación de datos

Descripción del proceso de captura y validación de evento mediante URL:

Validación del evento.

Los eventos se validan enviando una petición de vuelta a StockCrowd con todos los parámetros recibidos en el POST. Posteriormente, StockCrowd compara los parámetros originales del evento con los recibidos para garantizar que la información sea correcta. Si el proceso de validación es correcto el sistema retorna un "OK" en el cuerpo de la solicitud y si, por el contrario, la validación no es correcta se retorna ERROR en el cuerpo de la solicitud.

2. Comprobación de la respuesta de StockCrowd.

Si la respuesta es correcta significa los datos son validaos y estarían listos para ser tratados por el sistema que este gestionando el servicio web

3. Confirmación a StockCrowd de que se ha procesado el evento correctamente.

Esto se consigue enviando un "OK" como parte del cuerpo de la respuesta. Cuando StockCrowd envía un evento a la URL configurada en las notificaciones, se comprueba la respuesta para asegurarse que dicha URL esta realmente gestionada por el propietario del dominio. Si la respuesta es correcta el evento no se vuelve a enviar, en cambio, si no es correcta, el sistema volverá a reprocesar el evento realizando dos peticiones más con un intervalo de tiempo de 24 horas.

URLs de validación en función del entorno:

Entorno de pruebas (sandbox): https://sandbox.stockcrowd.com/api/events/confirm
Entorno de producción: https://www.stockcrowd.com/api/events/confirm

Código de muestra para la validación del evento

// *** PASO 1 ***

// endpoint de validación StockCrowd

$url = 'https://sandbox.stockcrowd.com/api/events/confirm'; // entorno de pruebas

// $url = 'https://www.stockcrowd.com/api/events/confirm'; // entorno de producción

// POST de vuelta a StockCrowd con todos los parámetros recibidos

$context = stream_context_create(array(

'http' => array(

'method' => 'POST',

'header' => 'Content-type: application/x-www-form-urlencoded',

'content' => http_build_query( $_POST )

)

, 'timeout' => 60

));

// *** PASO 2 ***

$resp = file_get_contents($url, FALSE, $context);

// si la respuesta a la validación por parte de StockCrowd es correcta

if ($resp=='OK'){

// código de integración propio del cliente (integración con otros sistemas del tipo CRM...)

} else {

// log para investigar peticiones que no han sido enviadas por StockCrowd

}

// *** PASO 3 ***

print_r('OK'); // indicar a StockCrowd que se ha procesado el evento

ezgif-2-58003a74353f

Categorias

Categorias