End-to-End Invoice Workflow

Objective

Walk through the complete invoicing workflow — from creating a quote, to converting it to an invoice, sending it, and tracking payment.

Step 1: Create a Quote

Start by sending a quote to your customer for a transport job:

curl -X POST https://api.otms.transportial.com/api/quote \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Quote #Q-2026-015",
    "direction": "OUT",
    "date": "2026-03-22",
    "dueAt": "2026-04-05T23:59:59Z",
    "subjectBusiness": { "id": "your-business-uuid" },
    "targetBusiness": { "id": "customer-business-uuid" },
    "lines": [
      {
        "description": "FTL Transport Rotterdam → Berlin",
        "quantity": 1,
        "unitPrice": 1200.00,
        "taxPercentage": 21
      },
      {
        "description": "Fuel surcharge (15%)",
        "quantity": 1,
        "unitPrice": 180.00,
        "taxPercentage": 21
      }
    ]
  }'

Response:

{
  "success": true,
  "message": "OK",
  "quote": {
    "id": "quote-uuid",
    "number": "Q-2026-015",
    "status": "concept",
    "subTotal": 1380.00,
    "tax": 289.80,
    "total": 1669.80
  }
}

Step 2: Send the Quote

curl -X POST "https://api.otms.transportial.com/api/quote/{quote-uuid}/send" \
  -H "Authorization: Bearer YOUR_TOKEN"

The customer receives an email with a link to view, accept, or decline the quote.

Step 3: Customer Accepts (via Public Link)

The customer can accept without logging in using the shared link:

POST /api/quote:public/{quote-uuid}/accept/{shareCode}

Or you can record acceptance manually:

curl -X POST "https://api.otms.transportial.com/api/quote/{quote-uuid}/accept" \
  -H "Authorization: Bearer YOUR_TOKEN"

Step 4: Convert Quote to Invoice

Once accepted, convert the quote directly into an invoice:

curl -X POST "https://api.otms.transportial.com/api/quote/{quote-uuid}/create:invoice" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "success": true,
  "message": "OK",
  "invoice": {
    "id": "invoice-uuid",
    "number": "2026-042",
    "status": "concept",
    "direction": "OUT",
    "subTotal": 1380.00,
    "tax": 289.80,
    "total": 1669.80,
    "totalOpen": 1669.80
  }
}

Step 5: Send the Invoice

curl -X POST "https://api.otms.transportial.com/api/invoice/{invoice-uuid}/send" \
  -H "Authorization: Bearer YOUR_TOKEN"

Step 6: Track Payment Status

Check the invoice status:

curl -X GET "https://api.otms.transportial.com/api/invoice/{invoice-uuid}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Key fields to monitor:

status — concept, sent, paid, overdue, cancelled
totalOpen — remaining amount to be paid
dueAt — payment due date
reminderCount — number of reminders sent

Step 7: Send a Payment Reminder

If payment is overdue:

curl -X POST "https://api.otms.transportial.com/api/invoice/{invoice-uuid}/send:reminder" \
  -H "Authorization: Bearer YOUR_TOKEN"

Step 8: View Financial Overview

Get a summary of all invoicing activity:

# List all outgoing invoices
curl -X POST "https://api.otms.transportial.com/api/invoices/{administrationId}/0/20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "direction": "OUT",
    "status": "sent"
  }'

# Financial management overview
curl -X GET "https://api.otms.transportial.com/api/management/financial/{administrationId}/2026-03-01/2026-03-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

Alternative: Create Invoice Directly

You can also skip the quote step and create an invoice directly:

curl -X POST https://api.otms.transportial.com/api/invoice \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Invoice #2026-043",
    "direction": "OUT",
    "date": "2026-03-22",
    "dueAt": "2026-04-22T23:59:59Z",
    "subjectBusiness": { "id": "your-business-uuid" },
    "targetBusiness": { "id": "customer-business-uuid" },
    "lines": [
      {
        "description": "Transport Rotterdam → Amsterdam",
        "quantity": 1,
        "unitPrice": 450.00,
        "taxPercentage": 21
      }
    ]
  }'

Processing Incoming Invoices

Handle invoices from your suppliers:

# Create from email
curl -X PUT "https://api.otms.transportial.com/api/invoice/mail/receiver" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "from": "billing@supplier.com",
    "subject": "Invoice #SUP-2026-100"
  }'

# Or create directly
curl -X POST https://api.otms.transportial.com/api/invoice \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "direction": "IN",
    "subjectBusiness": { "id": "supplier-business-uuid" },
    "targetBusiness": { "id": "your-business-uuid" },
    "lines": [...]
  }'

Key Takeaways

The full workflow: Quote → Accept → Invoice → Send → Payment → Reminder
Quotes support public sharing for customer self-service
Invoices support both directions: outgoing (you bill) and incoming (you pay)
Ledger entries provide a complete audit trail for all financial activity