# Integrations

Integrations connect external systems to your Transportial platform. They process data automatically when transport entities change — syncing with your ERP, telematics provider, accounting software, or any external system.

## Integration Types

### Configured Integrations

Data transformation pipelines with filters and data sources. They 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.

## Creating an Integration


```bash
curl -X POST https://api.otms.transportial.com/api/integration \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "ERP Order Sync",
    "type": "configured",
    "description": "Sync transport orders to our ERP when status changes",
    "enabled": true
  }'
```

**Response:**


```json
{
  "success": true,
  "message": "OK",
  "integration": {
    "id": "integration-uuid",
    "name": "ERP Order Sync",
    "type": "configured",
    "enabled": true,
    "createdAt": "2026-03-22T10:00:00Z"
  }
}
```

## How Integrations Process Data

Integrations use an event-driven queue:


```
1. Entity changes (order created, status updated, etc.)
2. IntegrationObject added to the processing queue
3. Scheduler picks up (~every 10 seconds)
4. Filters applied (should this event be processed?)
5. Data sources transform and route the data
6. Result: SUCCESS / ERROR / RETRY
```

## Managing Integrations

### List Integrations


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

### Search Integrations


```bash
curl -X POST "https://api.otms.transportial.com/api/integrations/0/20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "type": "configured",
    "enabled": true
  }'
```

### Update an Integration


```bash
curl -X PUT https://api.otms.transportial.com/api/integration \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": "integration-uuid",
    "enabled": false
  }'
```

### Delete an Integration


```bash
curl -X DELETE "https://api.otms.transportial.com/api/integration/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Authentication for Integrations

### Generate Credentials

Create OAuth credentials for an integration:


```bash
curl -X POST "https://api.otms.transportial.com/api/integration/generate/credentials" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "integrationId": "integration-uuid"
  }'
```

### Set OpenID Token

Configure OpenID Connect authentication:


```bash
curl -X PUT "https://api.otms.transportial.com/api/integration/{id}/openId" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "token": "openid-token-value"
  }'
```

## Importing Data

Bulk import data through an integration:


```bash
curl -X POST "https://api.otms.transportial.com/api/integration/import/data" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "integrationId": "integration-uuid",
    "data": [...]
  }'
```

## Email Integration

Handle incoming emails to create entities automatically:


```bash
curl -X POST "https://api.otms.transportial.com/api/integration/email" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "from": "customer@example.com",
    "subject": "New transport request",
    "body": "Please arrange pickup..."
  }'
```

## Testing Mappings

Validate your data mappings before deploying:


```bash
# Test data source mapping
curl -X POST "https://api.otms.transportial.com/api/integration/dataSource/mapping:test" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "mapping": { ... },
    "testData": { ... }
  }'

# Test file template mapping
curl -X POST "https://api.otms.transportial.com/api/integration/fileTemplate/mapping:test" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "mapping": { ... },
    "testData": { ... }
  }'
```

## Monitoring

### Integration Logs


```bash
curl -X GET "https://api.otms.transportial.com/api/integration/{id}/logs/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Processing Queue


```bash
curl -X GET "https://api.otms.transportial.com/api/integration/{id}/objects/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Request Logs


```bash
curl -X GET "https://api.otms.transportial.com/api/integration/{id}/requestLogs/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Tasks


```bash
curl -X GET "https://api.otms.transportial.com/api/integration/{id}/tasks/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Next Steps

- Install pre-built integrations from the [App Store](/guides/app-store)
- Set up [webhooks and event notifications](/guides/webhooks-and-events)
- See the full [API Reference](/apis) for all integration endpoints