# App Store

The Transportial App Store lets you extend your platform with integrations, automations, and third-party tools. Apps connect external systems (telematics, ERP, accounting, board computers) to your transport operations.

## How It Works

1. **Browse** the app store for available integrations
2. **Install** an app to your platform
3. **Configure** the app with your credentials and settings
4. The app receives an **access token** scoped to the permissions it needs


## Browsing Apps

Fetch available apps with optional category filtering:


```bash
curl -X GET "https://api.otms.transportial.com/api/app-store/browse/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Filter by category:


```bash
curl -X GET "https://api.otms.transportial.com/api/app-store/browse/0/20?categoryId=CATEGORY_UUID" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**


```json
{
  "success": true,
  "message": "OK",
  "totalResults": 42,
  "apps": [
    {
      "id": "app-uuid",
      "name": "Fleet Tracker Pro",
      "description": "Real-time GPS tracking for your entire fleet",
      "logo": { "url": "https://..." },
      "publisher": {
        "name": "Telematics Corp"
      },
      "lastVersion": {
        "version": "2.1.0",
        "releaseNotes": "Added geofencing support"
      },
      "category": {
        "id": "category-uuid",
        "name": "Telematics"
      }
    }
  ]
}
```

## Installing an App


```bash
curl -X POST "https://api.otms.transportial.com/api/app/{appId}/install" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

When you install an app:

1. An **AppInstallation** record is created for your platform
2. An **AppAccessToken** is generated with the permissions the app requires
3. The installation status transitions from `INSTALLING` to `ACTIVE`
4. You can configure app-specific settings through **AppInstallationSettings**


## Managing Installed Apps

List all apps installed on your platform:


```bash
curl -X GET "https://api.otms.transportial.com/api/apps/installed" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## App Lifecycle

| Status | Description |
|  --- | --- |
| `INSTALLING` | Installation in progress |
| `ACTIVE` | Running and connected |
| `UNINSTALLED` | Removed from platform |


## Integration Types

Apps can power different integration types on your platform:

### Configured Integrations

Data transformation pipelines with filters and data sources. Process events automatically when transport entities change (e.g., sync a new transport order to your ERP).

### Manual Integrations

Pre-built connectors for specific platforms — board computers (Transics), payment processors (Stripe), GPS providers (EvoGPS, FleetAccess), and more.

### File Template Integrations

File-based data exchange for systems that use EDI, CSV, or XML formats. Upload and download files on a schedule.

### Message Automations

Automated notifications triggered by transport events — send status updates to customers, alert drivers, or notify your team when exceptions occur.

### API Access Integrations

Expose API endpoints for external platforms to push or pull data from your Transportial environment.

## How Integrations Process Data

Integrations use an event-driven queue:

1. A transport entity changes (order created, status updated, etc.)
2. An **IntegrationObject** is added to the processing queue
3. The integration scheduler (runs every ~10 seconds) picks it up
4. Filters are applied to decide if the event should be processed
5. Data sources transform and route the data
6. Status is updated: `SUCCESS`, `ERROR`, or `RETRY`



```
Entity Change → IntegrationObject (QUEUE)
    → Scheduler picks up
    → Apply filters
    → Execute data sources
    → SUCCESS / ERROR / RETRY
```

## Permissions

| Permission | Description |
|  --- | --- |
| `browse:app-store` | View available apps |
| `install:app` | Install apps to your platform |
| `get:apps` | View installed apps |