Saltar al contenido principal

Integración

Esta guía te mostrará cómo integrarte con el servicio de eventos para comenzar a recibir eventos. El servicio de eventos actualmente solo soporta Apache Kafka como el intermediario de mensajes backend.

Se asume que estás familiarizado con Kafka y no se cubrirá cómo configurar un clúster de Kafka.

Requisitos​

Anchor Platform enviará eventos al tema de Kafka TRANSACTION. El servicio de eventos consumirá eventos de este tema y los enviará a los endpoints apropiados.

Configuración​

Primero, el productor Kafka del servicio de eventos debe configurarse usando la sección event.queue del archivo de configuración o estableciendo las variables de entorno. A continuación se muestra el conjunto de variables de entorno requeridas para configurar el productor Kafka del servicio de eventos:

# dev.env
EVENTS_ENABLED=true
EVENTS_QUEUE_TYPE=kafka
EVENTS_QUEUE_KAFKA_BOOTSTRAP_SERVER=localhost:9092

Anchor Platform permite configurar un subconjunto de la configuración del cliente del productor Kafka. Consulta el archivo de valores por defecto para más información sobre lo que está disponible. Para más información sobre la configuración del cliente del productor Kafka, visita la documentación de Kafka.

Luego, el procesador de eventos debe configurarse en la sección event_processor del archivo de configuración de Anchor Platform o estableciendo las variables de entorno.

# dev.env
EVENT_PROCESSOR_CLIENT_STATUS_CALLBACK_ENABLED=true
EVENT_PROCESSOR_CALLBACK_API_REQUEST_ENABLED=true

Esto habilitará que el procesador de eventos comience a procesar eventos del tema TRANSACTION. En este ejemplo, el procesador de eventos enviará eventos a endpoints de callback de cliente y servidor de negocios.

Recibir Eventos​

El servicio de eventos puede usarse para enviar eventos a endpoints de callback de cliente y servidor de negocios. El servicio de eventos enviará eventos a estos endpoints como solicitudes HTTP POST con los datos del evento en el cuerpo de la solicitud.

Como aplicación cliente​

Las aplicaciones cliente pueden recibir actualizaciones sobre las transacciones de sus usuarios e información del cliente. El esquema de los datos del evento dependerá del tipo de evento que se envíe.

Para recibir eventos como aplicación cliente, necesitarás exponer URLs de callback a las que el servicio de eventos pueda enviar eventos. El servicio de eventos enviará una solicitud POST a este endpoint con los datos del evento en el cuerpo de la solicitud. El esquema de los datos del evento dependerá del tipo de evento que se envíe. Anchor Platform permite configurar endpoints únicos según el tipo de evento.

Anchor Platform solo enviará eventos a clientes listados en la configuración de clientes. Consulta la documentación de configuración de clientes para más información.

Firma de Callback​

Anchor Platform firma las solicitudes de callback que envía a las aplicaciones cliente. La firma se incluye en la cabecera Signature de la solicitud. La especificación de la firma de la URL de callback se puede encontrar en las especificaciones del protocolo SEP correspondientes.

Como servidor de negocios​

Además de las actualizaciones de estado de transacciones SEP, los servidores de negocios pueden recibir eventos sobre la creación de cotizaciones SEP-31 o actualizaciones de información de clientes SEP-12. El esquema de los datos del evento dependerá del tipo de evento que se envíe. Visita la documentación de la API de eventos para más información sobre el esquema de los datos del evento.

Para recibir eventos como servidor de negocios, necesitarás exponer una URL de callback a la que el servicio de eventos pueda enviar eventos. El servicio de eventos enviará una solicitud POST a este endpoint con los datos del evento en el cuerpo de la solicitud.

Configuración​

La API de callback del servicio de eventos puede configurarse usando la sección callback_api del archivo de configuración de Anchor Platform o estableciendo las variables de entorno.

El siguiente es un ejemplo de cómo configurar la API de callback del servicio de eventos con autenticación JWT:

# dev.env

# note `/callback` will not be used for event callbacks
# instead events will be sent to `http://localhost:8081/event`
# all other callbacks (rates, customer, etc.) will use the provided `/callback` root path
CALLBACK_API_BASE_URL=http://localhost:8081/callback
CALLBACK_API_AUTH_TYPE=jwt
CALLBACK_API_AUTH_JWT_EXPIRATION_MILLISECONDS=30000
CALLBACK_API_AUTH_JWT_HTTP_HEADER=Authorization
SECRET_CALLBACK_API_AUTH_SECRET="a secret for signing jwts"

El siguiente es un ejemplo de cómo configurar la API de callback del servicio de eventos con autenticación por clave API:

# dev.env
CALLBACK_API_BASE_URL=http://localhost:8081/callback
CALLBACK_API_AUTH_TYPE=api_key
CALLBACK_API_AUTH_API_KEY_HTTP_HEADER=X-Api-Key
SECRET_CALLBACK_API_AUTH_SECRET="your API key"

Esto configura la API de callback del servicio de eventos que se usará para enviar eventos a endpoints de callback de clientes y servidores de negocios. Las siguientes son las opciones de configuración soportadas:

  • base_url: La URL base del endpoint de callback del servidor de negocios.
  • secret: El secreto que se usará al enviar eventos al endpoint de callback del servidor de negocios. Se usa para firmar el cuerpo de la solicitud cuando la autenticación JWT está activada y es la clave API cuando la autenticación por clave API está habilitada.
  • auth: El método de autenticación que se usará al enviar eventos al endpoint de callback del servidor de negocios. Los siguientes métodos de autenticación son soportados:
    • JWT: El servicio de eventos enviará un JSON Web Token (JWT) en la cabecera Authorization de la solicitud. Las siguientes son las opciones de configuración soportadas:
      • expiration_milliseconds: El tiempo de expiración del JWT en milisegundos.
      • http_header: La cabecera en la cual se enviará el JWT.
    • API_KEY: El servicio de eventos enviará una clave API en la cabecera Authorization de la solicitud. Las siguientes son las opciones de configuración soportadas:
      • http_header: La cabecera en la cual se enviará la clave API.