/admin/integrations

Path: /admin/integrations
Namespace: admin
Resource: integrations

Overview

The Integration resource represents external system integrations (e.g., Shopify, payment gateways, shipping providers). Integrations manage connection settings, authentication, and synchronization.

Relationships

Integration connects to:

• Domain (host_id) - Tenant domain

Key Features

• External System Integration: Connect to external services and platforms
• Configuration Management: Store integration settings and credentials
• Sync Management: Manage data synchronization with external systems
• Status Tracking: Track integration status and health

Available Operations

List Integrations (GET)

Endpoint: GET /admin/integrations.json

Query Parameters:

• q[field_predicate]=value - Ransack query filters for advanced filtering
• page=N - Page number for pagination
• per_page=N - Items per page (default: 25)

Request Examples:

curl -X GET "https://your-company.erpax.com/admin/integrations.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

curl -X GET "https://your-company.erpax.com/admin/integrations.json?q[type_eq]=Shopify&q[status_eq]=active" \
  -H "Accept: application/json"

JavaScript Example:

const response = await fetch('/admin/integrations.json', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
});
const data = await response.json();

Response (200 OK):

{
  "integrations": [
    {
      "id": 1,
      "name": "Shopify Store",
      "type": "Shopify",
      "status": "active",
      "last_sync_at": "2024-01-15T10:00:00Z",
      "created_at": "2024-01-10T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 1,
    "total_count": 3
  }
}

Show Integration (GET /:id)

Endpoint: GET /admin/integrations/:id.json

Request Example:

curl -X GET "https://your-company.erpax.com/admin/integrations/1.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

Response (200 OK):

{
  "integration": {
    "id": 1,
    "name": "Shopify Store",
    "type": "Shopify",
    "status": "active",
    "configuration": {...},
    "last_sync_at": "2024-01-15T10:00:00Z",
    "created_at": "2024-01-10T10:00:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}

Create Integration (POST)

Endpoint: POST /admin/integrations.json

Request Example:

curl -X POST "https://your-company.erpax.com/admin/integrations.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "integration": {
      "name": "Payment Gateway",
      "type": "Stripe",
      "status": "active",
      "configuration": {
        "api_key": "sk_test_...",
        "webhook_secret": "whsec_..."
      }
    }
  }'

JavaScript Example:

const response = await fetch('/admin/integrations.json', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    integration: {
      name: 'Payment Gateway',
      type: 'Stripe',
      status: 'active',
      configuration: {
        api_key: 'sk_test_...',
        webhook_secret: 'whsec_...'
      }
    }
  })
});
const integration = await response.json();

Response (201 Created):

{
  "integration": {
    "id": 2,
    "name": "Payment Gateway",
    "type": "Stripe",
    "status": "active",
    "created_at": "2024-01-15T14:30:00Z"
  }
}

Update Integration (PATCH /:id)

Endpoint: PATCH /admin/integrations/:id.json

Request Example:

curl -X PATCH "https://your-company.erpax.com/admin/integrations/1.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "integration": {
      "status": "inactive"
    }
  }'

JavaScript Example:

const response = await fetch('/admin/integrations/1.json', {
  method: 'PATCH',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    integration: {
      status: 'inactive'
    }
  })
});
const data = await response.json();

Response (200 OK):

{
  "integration": {
    "id": 1,
    "status": "inactive",
    "updated_at": "2024-01-15T15:00:00Z"
  }
}

Delete Integration (DELETE /:id)

Endpoint: DELETE /admin/integrations/:id.json

Request Example:

curl -X DELETE "https://your-company.erpax.com/admin/integrations/1.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

Response (204 No Content):

(empty response)

Member Actions

Custom actions available on individual integrations via API:

Sync Integration

Endpoint: POST /admin/integrations/:id/sync

Description: Trigger synchronization with external system.

Request Example:

curl -X POST "https://your-company.erpax.com/admin/integrations/1/sync" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

Response (200 OK):

{
  "message": "Synchronization started",
  "integration": {
    "id": 1,
    "last_sync_at": "2024-01-15T15:00:00Z"
  }
}

Test Connection

Endpoint: POST /admin/integrations/:id/test_connection

Description: Test integration connection.

Request Example:

curl -X POST "https://your-company.erpax.com/admin/integrations/1/test_connection" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

Response (200 OK):

{
  "status": "success",
  "message": "Connection successful"
}

Enable Integration

Endpoint: POST /admin/integrations/:id/enable

Description: Enable integration.

Request Example:

curl -X POST "https://your-company.erpax.com/admin/integrations/1/enable" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

Response (200 OK):

{
  "integration": {
    "id": 1,
    "status": "active",
    "updated_at": "2024-01-15T15:00:00Z"
  }
}

Disable Integration

Endpoint: POST /admin/integrations/:id/disable

Description: Disable integration.

Request Example:

curl -X POST "https://your-company.erpax.com/admin/integrations/1/disable" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

Response (200 OK):

{
  "integration": {
    "id": 1,
    "status": "inactive",
    "updated_at": "2024-01-15T15:00:00Z"
  }
}

Scopes

No custom scopes are configured (uses default 'all' scope).

Filters

Available filters for searching and filtering integrations:

• name_cont - Text filter - Search by integration name (contains)
• type - Select filter - Filter by integration type
• status - Select filter - Filter by status (active, inactive, error)
• created_at - Date filter - Filter by creation date
• updated_at - Date filter - Filter by update date

Filtering Examples:

# Filter by type and status
GET /admin/integrations.json?q[type_eq]=Shopify&q[status_eq]=active

# Search by name
GET /admin/integrations.json?q[name_cont]=Payment

Business Rules

• Type Validation: Integration type must be a supported integration type
• Configuration Security: Integration credentials are encrypted
• Status Management: Integrations can be enabled/disabled
• Sync Management: Synchronization can be triggered manually or scheduled

Related Resources

• Addresses - Addresses may have integration settings
• Items - Items may be synced with external systems