# Quickstart Guide

Get up and running with the Transportial OTMS API in minutes. This guide walks you through authentication, creating your first transport order, and understanding the response structure.

## Prerequisites

- A Transportial account — [register here](https://portal.otms.transportial.com/auth/register)
- For development access, use the [developer registration](https://portal.otms.transportial.com/auth/developer/register)


## Base URLs

| Environment | URL |
|  --- | --- |
| Production | `https://api.otms.transportial.com/api` |
| Test | `https://test.api.otms.transportial.com/api` |


## Step 1: Authenticate

All API requests require a Bearer token. Obtain one by logging in:


```bash
curl -X POST https://api.otms.transportial.com/api/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your@email.com",
    "password": "your-password"
  }'
```

**Response:**


```json
{
  "success": true,
  "message": "OK",
  "session": {
    "id": "session-uuid",
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "refresh-token-uuid",
    "expiresAt": "2026-03-23T12:00:00Z",
    "permissions": [
      { "name": "create:transportOrder" },
      { "name": "get:transportOrders" }
    ]
  }
}
```

Use the `access_token` in all subsequent requests:


```
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

## Step 2: Create a Business

Before creating transport orders, you need at least one business entity (your company or a customer):


```bash
curl -X POST https://api.otms.transportial.com/api/business \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Acme Logistics B.V.",
    "coc": "12345678",
    "vat": "NL123456789B01",
    "contactDetails": [
      {
        "type": "email",
        "value": "info@acme-logistics.com"
      }
    ]
  }'
```

## Step 3: Create a Transport Order

A transport order is the core entity — it represents a request to move goods from A to B.


```bash
curl -X POST https://api.otms.transportial.com/api/transportOrder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Shipment AMS-RTD #1042",
    "status": "requested",
    "consignments": [
      {
        "status": "requested",
        "goods": [
          {
            "type": "items",
            "description": "Electronics",
            "quantity": 120,
            "weight": { "value": 2400, "unit": "kg" }
          }
        ]
      }
    ]
  }'
```

**Response:**


```json
{
  "success": true,
  "message": "OK",
  "transportOrder": {
    "id": "transport-order-uuid",
    "name": "Shipment AMS-RTD #1042",
    "status": "requested",
    "consignments": [
      {
        "id": "consignment-uuid",
        "status": "requested",
        "goods": [ ... ]
      }
    ],
    "createdAt": "2026-03-22T10:30:00Z"
  }
}
```

## Step 4: Retrieve the Transport Order


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

## Response Format

All API responses follow a consistent structure:


```json
{
  "success": true,
  "message": "OK",
  "entity": { ... }
}
```

List endpoints include pagination:


```json
{
  "success": true,
  "message": "OK",
  "totalResults": 142,
  "items": [ ... ]
}
```

Errors return:


```json
{
  "success": false,
  "message": "Description of what went wrong",
  "statusCode": 400
}
```

## Next Steps

- Learn about the [core concepts](/guides/concepts) behind transport orders, consignments, and trips
- Browse and install apps from the [App Store](/guides/app-store)
- Explore the full [API Reference](/apis)