# Documents & Files

Manage documents, file uploads, and email processing. Documents track transport-related paperwork (CMR, proof of delivery, photos), while files handle the underlying storage.

## Documents

Documents are metadata records that wrap files and can be attached to transport entities.

### Create a Document


```bash
curl -X POST https://api.otms.transportial.com/api/document \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "CMR - Shipment RTD-AMS",
    "type": "CMR"
  }'
```

### Get a Document


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

### Verify / Unverify a Document

Mark documents as verified (e.g., after manual review):


```bash
# Verify
curl -X GET "https://api.otms.transportial.com/api/document/{id}/verify" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Unverify
curl -X GET "https://api.otms.transportial.com/api/document/{id}/unverify" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### List Documents


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

### Search Documents


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

### Attach Documents to Entities

Documents can be attached to trips and consignments:


```bash
# Attach to a trip
curl -X PUT "https://api.otms.transportial.com/api/trip/{tripId}/documents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "documents": [{ "id": "document-uuid" }]
  }'

# Attach to a consignment
curl -X PUT "https://api.otms.transportial.com/api/consignment/{consignmentId}/documents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "documents": [{ "id": "document-uuid" }]
  }'
```

## File Upload & Download

### Upload a File


```bash
curl -X POST https://api.otms.transportial.com/api/file/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/document.pdf"
```

### Get File Metadata


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

### Download a File


```bash
curl -X GET "https://api.otms.transportial.com/api/file/{id}/download" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o downloaded-file.pdf
```

### Convert File to HTML

Useful for previewing file contents in a browser:


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

### Convert File to Matrix

Extract structured data from files (CSV, Excel):


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

## Email (Mail) Management

Transportial can process incoming emails to create transport entities.

### Process an Email


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

### Convert Email to Transport Order


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

### Archive / Unarchive Emails


```bash
# Archive
curl -X GET "https://api.otms.transportial.com/api/mail/{id}/archive" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Unarchive
curl -X GET "https://api.otms.transportial.com/api/mail/{id}/unarchive" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### List Emails


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

## Document Types

| Type | Description |
|  --- | --- |
| `CMR` | International consignment note |
| `WAYBILL` | Waybill document |
| `INVOICE` | Invoice document |
| `QUOTE` | Quote document |
| `TRANSPORT_ORDER` | Transport order document |
| `TRIP` | Trip document |
| `CUSTOM` | Custom document type |
| `PDF` | Generic PDF file |
| `PHOTO` | Photo (proof of delivery, damage, etc.) |


## Next Steps

- Generate documents from transport entities with the [API Reference](/apis)
- Attach documents to consignments when [Managing Transport Orders](/examples/managing-transport-orders)
- See the full [API Reference](/apis) for all document and file endpoints