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:

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

*Hay dos eventos que estarán disponibles durante 2021:

  1. Carrito abandonado -> Este evento se dispara cuando un donante no ha completado la donación, pero tenemos sus datos
  2. Recurrencia confirmada -> Este evento se dispara cuando el sistema confirma la cuota de una donación recurrente



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:

  1. Seleccionar el tipo de evento a configurar
  2. Configurar la notificación, a través de una url o de un correo electrónico
  3. 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

1

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

1

Varchar

S= Sí

N= No

S

POLITICA_PRIVACIDAD

Aceptación del check del formulario

1

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

1

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

1

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

1

Varchar

S= Sí

N= No

S

POLITICA_PRIVACIDAD

Aceptación del check del formulario

1

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

1

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

1

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:

  1. 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