Skip to content

Tasks for a publisher:

Base URLs : Environments

ERP must be onboarded on Aptean IAM with client credentials to request a bearer token. AIP request headers must contain the bearer token from IAM authentication. How to get a token

Authorization: bearer token

Refer to AIP Swagger for full API documentation (based on the environment).

Tasks API method
Register event definition POST to v2/event-definitions
Publish event POST to v2/events

Register Event Definition

Event definition is created and registered at the product/service level. It needs to be created only once at deployment. It is the base unit that describes the shape of the data that the product/service will publish. For example, ERP wants to publish its order data so another product/service can take action upon it like create a shipment. Here's basic example of the event that includes order number, order amount and order date in the payload:

{
    "productId": "guid-of-your-product",
    "productVersion": "1.0",
    "eventDefinitions": [
        {
            "name": "erp-order-created-v1",
            "description": "new order created",
            "type": "erp-order-created-v1",
            "payloadSchema": {
                "properties": {
                    "orderId": {
                        "type": "string"
                    },
                    "amount": {
                        "type": "integer"
                    },
                    "orderDate": {
                        "type": "string"
                    }
                },
                "additionalProperties": false
            }
        }
    ]
}

ProductID: You can get the unique product ID by querying the v2/products endpoint.

In the definition, "type" must be a unique identifier. Make it easily comprehensible. Property "payloadSchema" is in JSON schema format. Please refer to https://json-schema.org/ for all the supported schema elements.

Once the event definition is registered, the product is ready to publish events for specific tenants.

See for more schema samples: [Event Definition] (Aptean-Integration-Platform/Development-Guidelines/How-to-Publish-and-Consume-Events/Publisher/Event-Definition.md)

Publish Event

Events are published for a specific customer of the product or service that is identified by a unique Tenant ID. For example, to publish the erp-order-created-v1 event type as described in the sample above, the following HTTP post request should be created.

The example uses the curl syntax - convert to the structure of any HTTP client used in your programming language. Add bearer token as Authorization value.

curl --location 'https://appcentral-aip-dev.apteansharedservices.com/v2/events' --header 'Authorization: bearer' --header 'X-APTEAN-CORRELATION-ID: order-358' --header 'Content-Type: application/json' --data '{
    "eventDefinitionType": "erp-order-created-v1",
    "sourceTenantId": "ee117256-e78f-45f0-b1b5-46164fd049c0",
    "sourceProductId" : "7AF17029-C37D-4945-AC5F-88D72651FC9B",
    "configuration": "",
    "payload": {
        "orderId": "358",
        "amount": 618,
        "orderDate": "2024-03-14"
    }
 }
  • location: use the proper URL based on the environment
  • headers: besides the authorization headers, correlation ID must also be included as value of X-APTEAN-CORRELATION-ID header. This should be uniquely identifiable value based on the entity-like orders. It is used by AIP for group-related events.
  • data: request body
  • eventDefinitionType - specify the event type
  • sourceTenantId - specify the customer's ID
  • sourceProductId - specify the ID of the product publishing the event. Product IDs are constant values globally. Retrieve your product ID using the v2/products query
  • payload - this is the actual event payload. It must conform to the payload schema of the event definition.
  • configuration - refer to Configuration Elements