Purchase Records API

Endpoints

Required Headers

GET /api/purchase-records

Query Parameters

1# All purchase records
2curl http://localhost:8080/api/purchase-records \
3  -H "X-API-Key: your-api-key"
4
5# Only records currently in transit
6curl "http://localhost:8080/api/purchase-records?purchase_status=IN_TRANSIT" \
7  -H "X-API-Key: your-api-key"

1const records = await fetch(
2  '/api/purchase-records?purchase_status=IN_TRANSIT',
3  { headers: { 'X-API-Key': 'your-api-key' } }
4).then(r => r.json());

POST /api/purchase-records

Creates a new purchase record. CO₂ emissions are calculated automatically when transport_mode, distance_km, and weight_kg are all provided. A PurchaseStatusChangeLog entry is created automatically when the status transitions.

Request Body

1curl -X POST http://localhost:8080/api/purchase-records \
2  -H "Content-Type: application/json" \
3  -H "X-User-Id: 1" \
4  -H "X-API-Key: your-api-key" \
5  -d '{
6    "supplier_id": 1,
7    "supplier_product_id": 5,
8    "purchase_date": "2025-09-15T09:00:00",
9    "quantity_kg": 500.0,
10    "transport_mode": "SEA",
11    "distance_km": 8500,
12    "weight_kg": 600,
13    "purchase_order_number": "PO-2025-001",
14    "invoice_number": "INV-2025-4521",
15    "batch_number": "BATCH-2025-09-A",
16    "purchase_status": "ORDERED"
17  }'

1const resp = await fetch('/api/purchase-records', {
2  method: 'POST',
3  headers: {
4    'Content-Type': 'application/json',
5    'X-User-Id': '1',
6    'X-API-Key': 'your-api-key'
7  },
8  body: JSON.stringify({
9    supplier_id: 1,
10    supplier_product_id: 5,
11    purchase_date: '2025-09-15T09:00:00',
12    quantity_kg: 500.0,
13    transport_mode: 'SEA',
14    distance_km: 8500,
15    weight_kg: 600,
16    purchase_order_number: 'PO-2025-001',
17    batch_number: 'BATCH-2025-09-A'
18  })
19});
20const record = await resp.json();
21console.log(`Status: ${record.purchase_status}, CO₂: ${record.co2_emissions_kg} kg`);

1import requests
2
3resp = requests.post(
4    'http://localhost:8080/api/purchase-records',
5    headers={'X-User-Id': '1', 'X-API-Key': 'your-api-key'},
6    json={
7        'supplier_id': 1,
8        'purchase_date': '2025-09-15T09:00:00',
9        'quantity_kg': 500.0,
10        'transport_mode': 'SEA',
11        'distance_km': 8500,
12        'weight_kg': 600,
13        'purchase_order_number': 'PO-2025-001',
14    }
15)
16record = resp.json()
17print(f"CO₂: {record['co2_emissions_kg']} kg, Status: {record['purchase_status']}")

Response 201 Created

1{
2  "id": 101,
3  "supplier_id": 1,
4  "supplier_product_id": 5,
5  "purchase_date": "2025-09-15T09:00:00",
6  "quantity_kg": 500.0,
7  "transport_mode": "SEA",
8  "distance_km": 8500.0,
9  "weight_kg": 600.0,
10  "co2_emissions_kg": 0.0561,
11  "purchase_order_number": "PO-2025-001",
12  "invoice_number": "INV-2025-4521",
13  "batch_number": "BATCH-2025-09-A",
14  "purchase_status": "ORDERED",
15  "delivery_date": null,
16  "expected_delivery_date": null,
17  "delivery_notes": null,
18  "created_at": "2025-09-15T09:12:00",
19  "updated_at": "2025-09-15T09:12:00"
20}

Purchase Status Lifecycle

Every purchase record has a purchase_status field that tracks its lifecycle. Valid transitions:

ORDERED → IN_TRANSIT → DELIVERED
       ↘              ↗
        CANCELLED ←──

Every status change is automatically recorded in the PurchaseStatusChangeLog table with the changed_by_user_id from the X-User-Id header. This provides a full audit trail.

To update the status, use PATCH /api/purchase-records/{id}:

1curl -X PATCH http://localhost:8080/api/purchase-records/101 \
2  -H "Content-Type: application/json" \
3  -H "X-User-Id: 1" \
4  -H "X-API-Key: your-api-key" \
5  -d '{
6    "purchase_status": "IN_TRANSIT",
7    "expected_delivery_date": "2025-10-05T08:00:00"
8  }'

Document Tracking Fields

The following reference fields allow matching a purchase record to physical documents:

All five fields share the same validation pattern: must start with an alphanumeric character and can contain letters, digits, spaces, ., /, _, -.

Migration: purchase_year → purchase_date

{
  "purchase_date": "2025-09-15T09:00:00"
}

{
  "purchase_year": 2025
}

If you need to preserve only the year from your existing data, use midnight on January 1st:

2025 → "2025-01-01T00:00:00"

The DB migration V2__replace_purchase_year_with_purchase_date.sql handles the column transformation automatically on deploy.

Emission Factor Reference

Formula: CO₂ = factor × distance_km × (weight_kg / 1000)

POST /api/purchase-records/bulk

Upserts by the combination of (supplier_id, batch_number) when batch_number is provided, otherwise by (supplier_id, supplier_product_id, purchase_date).

1{
2  "items": [
3    {
4      "supplier_id": 1,
5      "supplier_product_id": 5,
6      "purchase_date": "2025-09-15T09:00:00",
7      "quantity_kg": 500.0,
8      "purchase_order_number": "PO-2025-001",
9      "batch_number": "BATCH-2025-09-A"
10    },
11    {
12      "supplier_id": 2,
13      "purchase_date": "2025-09-15T09:00:00",
14      "quantity_kg": 200.0,
15      "transport_mode": "AIR",
16      "distance_km": 1200,
17      "weight_kg": 50
18    }
19  ]
20}