# 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:


```bash
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:**


```json
{
  "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


```bash
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:


```bash
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:


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

**Response:**


```json
{
  "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


```bash
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:


```bash
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:


```bash
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:


```bash
# 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:


```bash
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:


```bash
# 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