API docs by Redocly

4klyft API (1.0.0)

Download OpenAPI specification:

4klyft API Support: support@4klyft.com License: Proprietary

Logistics operations API for the 4klyft platform.

Overview

This API provides comprehensive endpoints for managing:

  • Routes & Execution: Create, manage, and execute delivery routes
  • Shipments & Loads: Track shipments from pickup to delivery
  • Fleet Management: Manage carriers, vehicles, and drivers
  • Proof of Delivery: Capture signatures, photos, and delivery confirmations
  • Settings: Configure system-wide and tenant-specific settings
  • Webhooks: Subscribe to real-time event notifications
  • Analytics: Access delivery performance metrics and reports

Authentication

All API endpoints (except /api/docs and /api/v1/iam/auth/*) require JWT Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Rate Limiting

API requests are rate-limited to ensure fair usage. Standard limits are:

  • 1000 requests per minute for read operations
  • 100 requests per minute for write operations

Error Handling

The API uses RFC 7807 Problem Details for error responses.

Partners

Represents a partner — a unified business entity the tenant transacts with.

Partners have no knowledge of roles (carrier, principal, supplier, customer). Roles are emergent, determined by which modules reference this PartnerId.

List all partners

Retrieve a paginated list of partners with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "pending_approval" "active" "suspended" "closed"
Example: status=active

Filter by partner status

search
string
Example: search=Acme

Search by name

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a partner

Create a new partner.

Authorizations:
Bearer
Request Body schema: application/json
required

Partner creation data

name
required
string [ 1 .. 255 ] characters
email
string or null <email>
phone
string or null <= 50 characters
website
string or null <url>
taxId
string or null
registrationNumber
string or null
netDays
integer or null
currency
string or null
paymentMethod
string or null

Responses

Request samples

Content type
application/json
{
  • "name": "Acme Logistics Inc.",
  • "email": "user@example.com",
  • "phone": "string",
  • "website": "string",
  • "taxId": "string",
  • "registrationNumber": "string",
  • "netDays": 30,
  • "currency": "EUR",
  • "paymentMethod": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get a partner

Retrieve a single partner by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Partner UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Activate a partner

Activate a pending or suspended partner.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Partner UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Close a partner

Close an active or suspended partner.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Partner UUID

Request Body schema:
required

The new Partner resource

reason
required
string

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Suspend a partner

Suspend an active partner.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Partner UUID

Request Body schema:
required

The new Partner resource

reason
required
string

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Update a partner

Update partner details. Only provided fields will be updated.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Partner UUID

Request Body schema:
required

The new Partner resource

name
string or null [ 1 .. 255 ] characters
ContactInput (object) or null
AddressInput (object) or null
taxId
string or null
taxExempt
boolean or null
registrationNumber
string or null
PaymentTermsInput (object) or null

Responses

Request samples

Content type
{
  • "name": "string",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "string",
  • "taxExempt": true,
  • "registrationNumber": "string",
  • "paymentTerms": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Partner Roles

Represents a role attached to a partner.

Exposed through GET /partners/{id}/roles. Mutation endpoints (add / update status / remove) live on PartnerResource because roles are owned by the partner aggregate.

List partner roles

Retrieve all roles attached to the partner.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Partner UUID

type
required
string

PartnerRole identifier

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Add a role to a partner

Add a new role (carrier, principal, customer, supplier) to the partner.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Partner UUID

Request Body schema:
required

The new Partner resource

type
required
string
Enum: "carrier" "principal" "customer" "supplier"
ref
required
string
label
string or null

Responses

Request samples

Content type
{
  • "type": "carrier",
  • "ref": "string",
  • "label": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Remove a role from a partner

Remove an existing role from the partner.

Authorizations:
Bearer
path Parameters
partnerId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Partner UUID

roleType
required
string
Enum: "carrier" "principal" "customer" "supplier"
Example: carrier

Role type

Responses

Update a role status

Update the status of an existing partner role.

Authorizations:
Bearer
path Parameters
partnerId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Partner UUID

roleType
required
string
Enum: "carrier" "principal" "customer" "supplier"
Example: carrier

Role type

Request Body schema:
required

The new Partner resource

status
required
string
Enum: "active" "inactive"

Responses

Request samples

Content type
{
  • "status": "active"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}