Integrations API

The Integrations API provides endpoints for managing e-commerce and external system integrations.

Endpoints Overview

Method	Endpoint	Description
POST	/api/integrations/provider/configure	Configure integration
GET	/api/integrations/provider/disable/{id}	Disable integration
DELETE	/api/integrations/providers/ecommerce/remove/{id}	Remove integration
POST	/api/integrations/save-vapid-subscription	Save push subscription
GET	/api/workflows/triggers/{entityType}	Get workflow triggers
GET	/api/workflows/{entityType}/configured	Get configured workflows
POST	/api/workflows/configure	Configure workflow
GET	/api/workflows/configured/{guid}/toggle	Toggle workflow
DELETE	/api/workflows/configured/{guid}	Delete workflow

Configure Integration Provider

Set up an integration with an external platform.

POST /api/integrations/provider/configure

Request Body

{
  "providerId": "provider-uuid",
  "providerType": "ecommerce",
  "credentials": {
    "apiKey": "your-api-key",
    "apiSecret": "your-api-secret",
    "storeUrl": "https://yourstore.example.com"
  },
  "settings": {
    "autoImportOrders": true,
    "syncProducts": true,
    "pushTracking": true
  }
}

Response

{
  "data": {
    "guid": "integration-uuid",
    "provider": "provider-name",
    "status": "active",
    "connectedAt": "2024-01-16T10:00:00Z"
  },
  "success": true
}

Disable Integration

Temporarily disable an integration.

GET /api/integrations/provider/disable/{businessProviderId}

Path Parameters

Parameter	Type	Description
businessProviderId	uuid	Integration identifier

Response

{
  "data": {
    "guid": "integration-uuid",
    "status": "disabled"
  },
  "success": true
}

Remove Integration

Permanently remove an integration.

DELETE /api/integrations/providers/ecommerce/remove/{businessProviderId}

Response

{
  "success": true
}

Save Push Notification Subscription

Register for push notifications.

POST /api/integrations/save-vapid-subscription

Request Body

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/...",
  "keys": {
    "p256dh": "public-key-string",
    "auth": "auth-secret-string"
  }
}

Response

{
  "success": true
}

Get Workflow Triggers

Get available triggers for an entity type.

GET /api/workflows/triggers/{entityType}

Path Parameters

Parameter	Type	Description
entityType	string	Entity type (Order, Shipment, Customer)

Response

{
  "data": [
    {
      "guid": "trigger-uuid",
      "name": "Order Created",
      "code": "order_created",
      "description": "Fires when a new order is created"
    },
    {
      "guid": "trigger-uuid-2",
      "name": "Order Status Changed",
      "code": "order_status_changed",
      "description": "Fires when order status changes"
    }
  ],
  "success": true
}

Get Configured Workflows

Get workflows configured for an entity type.

GET /api/workflows/{entityType}/configured

Query Parameters

Parameter	Type	Description
managed	boolean	Include managed workflows

Response

{
  "data": [
    {
      "guid": "workflow-uuid",
      "name": "Notify on Delivery",
      "entityType": "Shipment",
      "trigger": "shipment_delivered",
      "action": "send_email",
      "isActive": true,
      "isManaged": false
    }
  ],
  "success": true
}

Configure Workflow

Create or update a workflow.

POST /api/workflows/configure

Request Body

{
  "name": "Customer Delivery Notification",
  "entityType": "Shipment",
  "triggerId": "trigger-uuid",
  "action": {
    "type": "send_email",
    "recipient": "customer",
    "template": "delivery_confirmation"
  },
  "conditions": {
    "status": "delivered"
  }
}

Response

{
  "data": {
    "guid": "workflow-uuid",
    "name": "Customer Delivery Notification",
    "isActive": true
  },
  "success": true
}

Toggle Workflow

Enable or disable a workflow.

GET /api/workflows/configured/{guid}/toggle

Response

{
  "data": {
    "guid": "workflow-uuid",
    "isActive": false
  },
  "success": true
}

Delete Workflow

Remove a configured workflow.

DELETE /api/workflows/configured/{guid}

Response

{
  "success": true
}

Resume Workflow

Resume a paused workflow execution.

GET /api/workflows/resume-workflow?workflowId={workflowId}

Response

{
  "success": true
}

Entity Types

Available entity types for workflows:

Type	Description
Order	Order-related events
Shipment	Shipment-related events
Customer	Customer-related events
Product	Product-related events

Action Types

Available workflow actions:

Action	Description
send_email	Send email notification
send_push	Send push notification
webhook	Call external webhook
update_status	Update entity status

Error Responses

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Integration not found"
  }
}

400 Bad Request

{
  "success": false,
  "error": {
    "code": "CONFIGURATION_ERROR",
    "message": "Invalid credentials"
  }
}

409 Conflict

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Integration already configured"
  }
}