Configuration

This guide covers how to configure integrations, use cases, and manage your ERP Toolkit setup.

Integration Management

Creating an Integration

curl -X POST 'https://erp-integration.sls.epilot.io/v2/integrations' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "SAP Integration",
    "description": "Main ERP integration for customer and contract data"
  }'

Listing Integrations

curl -X GET 'https://erp-integration.sls.epilot.io/v2/integrations' \
  -H 'Authorization: Bearer <token>'

Updating an Integration

curl -X PUT 'https://erp-integration.sls.epilot.io/v2/integrations/{integrationId}' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "SAP Production Integration",
    "description": "Updated description"
  }'

Deleting an Integration

warning

Deleting an integration also removes all associated use cases.

curl -X DELETE 'https://erp-integration.sls.epilot.io/v2/integrations/{integrationId}' \
  -H 'Authorization: Bearer <token>'

Use Case Configuration

Creating a Use Case

curl -X POST 'https://erp-integration.sls.epilot.io/v1/integrations/{integrationId}/use-cases' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Customer Sync",
    "type": "inbound",
    "enabled": true,
    "configuration": {
      "entities": [...]
    }
  }'

Use Case Properties

Property	Type	Required	Description
name	string	Yes	Display name for the use case
type	string	Yes	inbound, outbound, or file_proxy
enabled	boolean	Yes	Whether the use case is active
configuration	object	Yes	Mapping configuration (for inbound/outbound) or File Proxy configuration (for file_proxy)

info

The file_proxy type is used for on-demand file serving from external document systems. See the File Proxy guide for configuration details.

Enabling/Disabling a Use Case

curl -X PUT 'https://erp-integration.sls.epilot.io/v1/integrations/{integrationId}/use-cases/{useCaseId}' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": false
  }'

Use Case History

View the change history for a use case:

curl -X GET 'https://erp-integration.sls.epilot.io/v1/integrations/{integrationId}/use-cases/{useCaseId}/history' \
  -H 'Authorization: Bearer <token>'

Mapping Configuration Schema

Version 2.0 Structure

{
  "entities": [
    {
      "entity_schema": "string",
      "unique_ids": ["string"],
      "enabled": "boolean | string",
      "jsonataExpression": "string",
      "fields": [
        {
          "attribute": "string",
          "field": "string",
          "jsonataExpression": "string",
          "constant": "any",
          "_type": "email | phone",
          "enabled": "string",
          "relation": {
            "entity_schema": "string",
            "unique_ids": ["string"],
            "source_field": "string",
            "operation": "_set | _append",
            "enabled": "string"
          }
        }
      ],
      "post_actions": {
        "create_missing_relations": "boolean"
      }
    }
  ],
  "meter_readings": [
    {
      "jsonataExpression": "string",
      "meter": {
        "unique_ids": ["string"]
      },
      "fields": [...]
    }
  ]
}

Event Configuration

Event Message Structure

{
  "integration_id": "uuid",
  "meta": {
    "correlation_id": "string"
  },
  "events": [
    {
      "event_type": "CREATE | UPDATE | DELETE",
      "use_case_slug": "string (recommended, 1-255 chars, pattern: ^[a-z0-9][a-z0-9_-]*$, required if event_name is not provided)",
      "event_name": "string (legacy fallback, required if use_case_slug is not provided)",
      "timestamp": "ISO 8601 datetime",
      "format": "json | xml",
      "payload": "string (JSON or XML)",
      "deduplication_id": "string (optional)"
    }
  ]
}

For each event, include use_case_slug whenever possible. event_name is supported as a legacy fallback, and use_case_slug takes precedence if both are present.

use_case_slug format: ^[a-z0-9][a-z0-9_-]*$ with length 1..255 (must start with a lowercase letter or digit; then lowercase letters, digits, _, -).

Event Types

Type	Description
CREATE	Create a new entity (fails if exists)
UPDATE	Update existing or create new entity
DELETE	Mark entity as deleted

Payload Formats

JSON Format:

{
  "event_type": "UPDATE",
  "format": "json",
  "payload": "{\"customerId\":\"C001\",\"name\":\"John Doe\"}"
}

XML Format:

{
  "event_type": "UPDATE",
  "format": "xml",
  "payload": "<customer><id>C001</id><name>John Doe</name></customer>"
}

Deduplication

Deduplication ID

Prevent duplicate processing by including a unique deduplication ID:

{
  "events": [
    {
      "event_type": "UPDATE",
      "deduplication_id": "customer-C001-update-20240115-001",
      "payload": "..."
    }
  ]
}

Deduplication Window

• Events are deduplicated within a 24-hour window
• Same deduplication ID within 24 hours = skipped
• After 24 hours, the same ID can be processed again

Best Practices

# Good - includes version or timestamp
customer-C001-update-v3
customer-C001-update-20240115T103000

# Bad - no version control, may skip legitimate updates
customer-C001

Correlation Tracking

Correlation ID

Include a correlation ID to track related events:

{
  "meta": {
    "correlation_id": "<uuidv4()>"
  },
  "events": [...]
}

Using Correlation IDs

• Group related events for debugging
• Filter monitoring data by batch
• Trace event processing through the pipeline

Monitoring Configuration

Query Events

curl -X POST 'https://erp-integration.sls.epilot.io/v1/monitoring/events' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "integration_id": "<integration-id>",
    "from": "2024-01-15T00:00:00Z",
    "to": "2024-01-15T23:59:59Z",
    "status": ["error"],
    "limit": 100
  }'

Query Statistics

curl -X POST 'https://erp-integration.sls.epilot.io/v1/monitoring/stats' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "integration_id": "<integration-id>",
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-31T23:59:59Z"
  }'

Event Replay

Reprocess failed or specific events:

curl -X POST 'https://erp-integration.sls.epilot.io/v1/integrations/{integrationId}/events/replay' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "event_ids": ["evt-001", "evt-002", "evt-003"]
  }'

Rate Limits

Endpoint	Limit
Event submission	100 events per request
API requests	1000 requests per minute per organization

Security

Authentication

All API requests require a valid Bearer token:

curl -H 'Authorization: Bearer <your-token>' ...

Organization Isolation

Each organization's data is fully isolated. Integration IDs are scoped to organizations, and cross-organization access is not permitted.

Permissions

Action	Permission
Read integrations	erp:read
Create/Update integrations	erp:write
Send events	erp:events
View monitoring	erp:monitoring