Shipping Service API

Centralized shipment management, FedEx label creation, tracking with caching, print queue, and Boothwyn webhook processing.

Overview

The Shipping Service manages the full shipment lifecycle: FedEx label creation for GMP-fulfilled orders, shipment status tracking with 30-minute caching, a print queue for pharmacy staff, and Boothwyn webhook processing for 3PL shipments.

When a prescription is approved and routed to GMP, the orchestrator calls this service to create a FedEx shipment label. The label is automatically added to the print queue. For Boothwyn-fulfilled orders, the Boothwyn webhook creates or updates shipment records when tracking information becomes available.

Base URL

https://api.yourera.com/shipping

How It Works

1. Caller submits a CreateShipment payload to POST /shipping/shipments
2. For GMP pharmacy, the service calls the FedEx Ship API to generate a label and tracking number
3. Shipment record is created in the database with status label_created
4. If a label was generated, it is automatically added to the print queue as pending
5. Pharmacy staff prints labels via the print queue endpoints
6. Status progresses: label_created → packed → shipped → delivered
7. Tracking info is fetched from FedEx with 30-minute caching for patient-facing display

Database Tables

Authentication

All /shipping/* endpoints (except /health and /shipping/webhooks/boothwyn) require HMAC-SHA256 authentication. Each API client is issued an API key (public identifier) and an API secret (used for signing).

Required Headers

Signature Formula

The signing string is the timestamp, a dot, and the JSON-stringified request body:

HMAC-SHA256(apiSecret, timestamp + '.' + JSON.stringify(body))

The result is encoded as a lowercase hex string.

Node.js Example

import crypto from 'node:crypto';

const API_KEY = 'your-api-key';
const API_SECRET = 'your-api-secret';

function signRequest(body) {
  const timestamp = new Date().toISOString();
  const bodyStr = JSON.stringify(body);
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(timestamp + '.' + bodyStr)
    .digest('hex');

  return { timestamp, signature };
}

// Usage: Create a shipment
const body = {
  patientId: 'patient-uuid-here',
  patientName: 'Jane Smith',
  address: {
    line1: '123 Main St',
    city: 'Austin',
    state: 'TX',
    zip: '78701',
  },
  medication: 'Semaglutide 2.5mg/mL',
  pharmacy: 'gmp',
};

const { timestamp, signature } = signRequest(body);

const response = await fetch('https://api.yourera.com/shipping/shipments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body: JSON.stringify(body),
});

Create Shipment

Request Headers

Request Body: CreateShipment

Top-level Fields

address Object

Example Request

{
  "patientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "patientName": "Jane Smith",
  "address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "Austin",
    "state": "TX",
    "zip": "78701"
  },
  "medication": "Semaglutide 2.5mg/mL",
  "pharmacy": "gmp",
  "weight": 1.5
}

Response

Success (201)

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "patientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "patientName": "Jane Smith",
  "addressLine1": "123 Main St",
  "addressLine2": "Apt 4B",
  "addressCity": "Austin",
  "addressState": "TX",
  "addressZip": "78701",
  "medication": "Semaglutide 2.5mg/mL",
  "pharmacy": "gmp",
  "trackingNumber": "794644790132",
  "carrier": "FedEx",
  "labelData": "JVBERi0xLjQK...",
  "status": "label_created",
  "weight": 1.5,
  "createdAt": "2026-03-20T14:30:00.000Z",
  "updatedAt": "2026-03-20T14:30:00.000Z"
}

Error Responses

Validation Error (400)

{
  "error": "Invalid request",
  "details": [
    {
      "code": "too_small",
      "minimum": 1,
      "type": "string",
      "inclusive": true,
      "message": "String must contain at least 1 character(s)",
      "path": ["patientId"]
    }
  ]
}

Get Shipment

Path Parameters

Request Headers

Response (200)

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "patientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "patientName": "Jane Smith",
  "addressLine1": "123 Main St",
  "addressLine2": "Apt 4B",
  "addressCity": "Austin",
  "addressState": "TX",
  "addressZip": "78701",
  "medication": "Semaglutide 2.5mg/mL",
  "pharmacy": "gmp",
  "trackingNumber": "794644790132",
  "carrier": "FedEx",
  "labelData": "JVBERi0xLjQK...",
  "status": "shipped",
  "weight": 1.5,
  "createdAt": "2026-03-20T14:30:00.000Z",
  "updatedAt": "2026-03-21T09:15:00.000Z"
}

Error Responses

Update Status

Path Parameters

Request Headers

Request Body

Example Request

{
  "status": "packed"
}

Response (200)

Returns the updated shipment object (same shape as Get Shipment).

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "packed",
  "updatedAt": "2026-03-20T15:00:00.000Z",
  // ... remaining shipment fields
}

Error Responses

Void Shipment

Path Parameters

Request Headers

Request Body

No request body required.

Response (200)

Returns the voided shipment object.

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "voided",
  "updatedAt": "2026-03-20T16:00:00.000Z",
  // ... remaining shipment fields
}

Error Responses

Tracking

Path Parameters

Request Headers

Response (200)

The source field indicates where the data came from.

Fresh Cache Hit

{
  "source": "cache",
  "data": {
    "trackingNumber": "794644790132",
    "statusDetail": "In transit",
    "estimatedDelivery": "2026-03-22T18:00:00.000Z",
    "events": [
      {
        "timestamp": "2026-03-20T10:00:00.000Z",
        "description": "Picked up",
        "city": "Dallas",
        "state": "TX"
      }
    ]
  }
}

Stale Fallback (FedEx Down)

{
  "source": "stale_cache",
  "data": { /* last cached tracking data, may be outdated */ }
}

Error Responses

Print Queue: List Pending

Request Headers

Response (200)

Returns an array of print queue items with embedded shipment data.

[
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "shipmentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "pending",
    "createdAt": "2026-03-20T14:30:00.000Z",
    "printedAt": null,
    "shipment": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "patientName": "Jane Smith",
      "medication": "Semaglutide 2.5mg/mL",
      "pharmacy": "gmp",
      "trackingNumber": "794644790132",
      "labelData": "JVBERi0xLjQK...",
      "status": "label_created"
    }
  }
]

Response Fields

Error Responses

Print Queue: Mark Printed

Path Parameters

Request Headers

Request Body

No request body required.

Response (200)

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "shipmentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "printed",
  "createdAt": "2026-03-20T14:30:00.000Z",
  "printedAt": "2026-03-20T15:10:00.000Z"
}

Error Responses

Boothwyn Webhook

Authentication

The Boothwyn webhook uses a shared secret instead of HMAC. The secret is validated against the BOOTHWYN_WEBHOOK_SECRET environment variable.

Request Body

Example Request

{
  "orderId": "BTW-ORD-12345",
  "trackingNumber": "9400111899223456789012",
  "carrier": "USPS",
  "status": "shipped"
}

Responses

Skipped -- No Tracking Number (200)

{
  "received": true,
  "action": "skipped",
  "reason": "Empty tracking number"
}

Updated Existing Shipment (200)

{
  "received": true,
  "action": "updated",
  "shipment": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "shipped",
    "carrier": "USPS",
    // ... remaining shipment fields
  }
}

Created New Shipment (200)

{
  "received": true,
  "action": "created",
  "shipment": {
    "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "patientId": "BTW-ORD-12345",
    "patientName": "Boothwyn Order",
    "pharmacy": "boothwyn",
    "trackingNumber": "9400111899223456789012",
    "carrier": "USPS",
    "status": "shipped",
    // ... remaining fields
  }
}

Error Responses

Shipment Status Flow

Shipments follow a strict forward-only status progression. Terminal states (delivered and voided) cannot transition to any other state.

Status Diagram

                    +------------------+
                    |  label_created   |
                    +--------+---------+
                             |
                    +--------v---------+
                    |      packed      |
                    +--------+---------+
                             |
                    +--------v---------+
                    |     shipped      |
                    +--------+---------+
                             |
                    +--------v---------+
                    |    delivered     |  (terminal)
                    +------------------+

  Void path (from label_created or packed only):

    label_created ----+
                      +----->  voided  (terminal)
    packed -----------+

Allowed Transitions

Print Queue Lifecycle

The print queue tracks FedEx label printing for pharmacy staff. Items are created automatically when a GMP shipment is created with a label.

Status Diagram

  +----------+     +-----------+     +-----------+
  | pending  +---->| printing  +---->|  printed  |
  +----+-----+     +-----+-----+     +-----------+
       |                 |
       |                 v
       |           +----------+
       |           |  error   |
       |           +----+-----+
       |                |
       +<---------------+  (retry: error -> pending)

  Auto-skip for voided shipments:

  pending ---> skipped  (if parent shipment is voided)

Print Queue Statuses

Transition Rules

Tracking Cache

Tracking data from FedEx is cached in the tracking_cache database table to minimize API calls and improve response times. Each tracking number has a single cache entry that is refreshed on access when expired.

Cache Behavior

Resolution Logic

1. Check tracking_cache for the tracking number
2. If cached and cachedAt is within 30 minutes, return { source: "cache", data }
3. If no cache or cache expired, call FedEx Track API (POST /track/v1/trackingnumbers)
4. If FedEx succeeds, upsert cache and return { source: "api", data }
5. If FedEx fails and stale cache exists, return { source: "stale_cache", data }
6. If FedEx fails and no cache exists, return 502 Tracking service unavailable

Health Check

Response (200)

{
  "status": "ok",
  "service": "shipping-service",
  "timestamp": "2026-03-20T14:30:00.000Z"
}

Shipment Data Model

The shipments table stores all shipment records. Below is the full column schema.