Integración

Esta guía te llevará a integrar con el servicio de eventos para comenzar a recibir eventos. El servicio de eventos actualmente solo admite Apache Kafka como el intermediario de mensajes de backend.

Asume familiaridad con Kafka y no cubrirá cómo configurar un clúster de Kafka.

Requisitos

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

Configuración

Primero, el productor de Kafka del servicio de eventos debe ser configurado utilizando la sección event.queue del archivo de configuración o configurando las variables de entorno. El siguiente es el conjunto de variables de entorno requeridas para configurar el productor de Kafka del servicio de eventos:

bash

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

YAML

# dev.services.yaml
events:
  enabled: true
  queue:
    type: kafka
    kafka:
      bootstrap_server: localhost:9092

Anchor Platform permite que se configure un subconjunto de la configuración del cliente del productor de Kafka. Consulta el [archivo de valores predeterminados][default-values-file] para más información sobre lo que está disponible. Para más información sobre la configuración del cliente del productor de Kafka, consulta la documentación de Kafka.

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

bash

# dev.env
EVENT_PROCESSOR_CLIENT_STATUS_CALLBACK_ENABLED=true
EVENT_PROCESSOR_CALLBACK_API_REQUEST_ENABLED=true

YAML

# dev.services.yaml
event_processor:
  client_status_callback:
    enabled: true
  callback_api_request:
    enabled: true

Esto permitirá que el procesador de eventos comience a procesar eventos del tema TRANSACTION. En este ejemplo, el procesador de eventos enviará eventos a los endpoints de retorno de llamada del cliente y del servidor empresarial.

Recibir Eventos

El servicio de eventos se puede utilizar para enviar eventos a los endpoints de retorno de llamada del cliente y del servidor empresarial. 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 y la información del cliente de sus usuarios. El esquema de los datos del evento dependerá del tipo de evento que se esté enviando.

Para recibir eventos como una aplicación cliente, necesitarás exponer URLs de retorno de llamada 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 esté enviando. Anchor Platform permite que se configuren endpoints únicos por tipo de evento.

Anchor Platform solo enviará eventos a los clientes listados en la configuración del cliente. Consulta la [documentación de configuración del cliente][clients-config] para más información.

Firma de Callback

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

• SEP-0006
• SEP-0012
• SEP-0024
• SEP-0031

Como Servidor Empresarial

Además de las actualizaciones del estado de transacciones SEP, los servidores empresariales pueden recibir eventos sobre la creación de cotizaciones SEP-31 o actualizaciones de información del cliente SEP-12. El esquema de los datos del evento dependerá del tipo de evento que se esté enviando. 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 empresarial, necesitarás exponer una URL de retorno de llamada 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 retorno de llamada del servicio de eventos se puede configurar utilizando la sección callback_api del archivo de configuración de Anchor Platform o configurando las variables de entorno.

advertencia

El --event-processor ignorará cualquier segmento de ruta especificado en callback_api.base_url y en su lugar enviará eventos a [scheme]://[host]:[port]/event. Este es un error, pero para no interrumpir a quienes utilizan el procesador de eventos, pospondremos la corrección que incluye segmentos de ruta en la versión 3 de Anchor Platform.

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

bash

# 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"

YAML

# dev.services.yaml
callback_api:
  base_url: http://localhost:8081/callback
  auth:
    type: jwt
    jwt:
      expiration_milliseconds: 30000
      http_header: Authorization

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

bash

# 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"

YAML

# dev.services.yaml
callback_api:
  base_url: http://localhost:8081/callback
  auth:
    type: api_key
    api_key:
      http_header: X-Api-Key

Esto configura la API de retorno de llamada del servicio de eventos que se utilizará para enviar eventos a los endpoints de retorno de llamada del cliente y del servidor empresarial. Las siguientes son las opciones de configuración admitidas:

• base_url: La URL base del endpoint de retorno de llamada del servidor empresarial.
• secret: El secreto que se utilizará al enviar eventos al endpoint de retorno de llamada del servidor empresarial. Esto se utiliza para firmar el cuerpo de la solicitud cuando la autenticación JWT está habilitada y es la clave API cuando la autenticación de clave API está habilitada.
• auth: El método de autenticación que se utilizará al enviar eventos al endpoint de retorno de llamada del servidor empresarial. Las siguientes son los métodos de autenticación admitidos:
  • JWT: El servicio de eventos enviará un JSON Web Token (JWT) en el encabezado Authorization de la solicitud. Las siguientes son las opciones de configuración admitidas:
    • expiration_milliseconds: El tiempo de caducidad del JWT en milisegundos.
    • http_header: El encabezado en el que se enviará el JWT.
  • API_KEY: El servicio de eventos enviará una clave API en el encabezado Authorization de la solicitud. Las siguientes son las opciones de configuración admitidas:
    • http_header: El encabezado en el que se enviará la clave API.