Revision History

Version	Date	Summary of Changes
1.0	March 2026	Initial release. Documented Rate API, Create Shipment, Tracking, and Bill of Lading (metadata) endpoints.
2.0	July 2026	Added GET /piyovi_getBOLDocument (Carrier BOL PDF) and GET /piyovi_getShippingLabel (Carrier Shipping Label PDF). Restructured BOL section into three clearly separated sections. Updated Overview, Endpoint Summary, Integration Workflow, and Testing. All v1.0 endpoints preserved without modification.

What's New in Version 2.0

Version 2.0 introduces additive carrier document retrieval. Partners can now programmatically retrieve print-ready PDF documents for each shipment.

New Endpoints

Endpoint	Method	Purpose
/piyovi_getBOLDocument	GET	Retrieves the Carrier Bill of Lading as a PDF. Returns a persistent URL.
/piyovi_getShippingLabel	GET	Retrieves the Carrier Shipping Label as a PDF (one page per piece). Returns a persistent URL.

Restructured BOL Section

The former Bill of Lading section is now three clearly separated sections:

GET /piyovi_getBOL — BOL metadata in JSON (unchanged from v1.0).
GET /piyovi_getBOLDocument — Carrier BOL PDF (new in v2.0).
GET /piyovi_getShippingLabel — Carrier Shipping Label PDF (new in v2.0).

Backward Compatibility

✓ Fully Backward Compatible. Version 2.0 is fully backward compatible with Version 1.0. Existing integrations continue to function without modification. All v1.0 endpoints, request formats, and response formats remain unchanged. The new Carrier Document endpoints are additive capabilities.

1. Overview

The Octojan Piyovi LTL API enables authorized integration partners to programmatically interact with the Octojan Logistics LTL shipping platform. Through a single authenticated API surface, partners can:

Request Quotes — Obtain real-time LTL pricing.
Create Shipments — Book LTL shipments and receive a tracking number.
Track Shipments — Retrieve public tracking status and event history.
Retrieve BOL Metadata — Obtain shipment and BOL data in JSON format.
Retrieve Carrier BOL PDFs — Download a print-ready Carrier Bill of Lading PDF. (New in v2.0)
Retrieve Carrier Shipping Label PDFs — Download a print-ready Carrier Shipping Label PDF. (New in v2.0)

All endpoints are authenticated via a partner-specific API key and operate over HTTPS. All pricing is in Canadian Dollars (CAD).

2. Authentication

All API requests (except the public Tracking endpoint) require a partner-specific API key, provided by Octojan during onboarding:

x-api-key: <your-partner-api-key>

Property	Description
Required	Yes — for all endpoints except Track Shipment (public)
Scope	Partner-scoped: restricts access to shipments owned by the partner's linked company or customer
Rate Limit	Default 1,000 requests per hour (configurable per partner)

3. Base URL

https://api.octojan.com

Endpoint paths are appended to the base URL. The sandbox base URL is provided during partner onboarding; the production base URL is issued upon certification.

4. Endpoint Summary

Endpoints marked (v2.0) are new. All others are unchanged from Version 1.0.

#	Endpoint	Method	Auth	Description
1	`/piyovi_getQuote`	POST	Yes	Request an LTL rate quote.
2	`/piyovi_createShipment`	POST	Yes	Create (book) an LTL shipment. Returns a tracking number.
3	`/getPublicTracking`	POST	No	Retrieve public tracking status and event history.
4	`/piyovi_getBOL`	GET	Yes	Retrieve BOL metadata in JSON format.
5	`/piyovi_getBOLDocument` (v2.0)	GET	Yes	Retrieve Carrier BOL PDF. Returns a persistent PDF URL.
6	`/piyovi_getShippingLabel` (v2.0)	GET	Yes	Retrieve Carrier Shipping Label PDF. Returns a persistent PDF URL.

5. Rate API — Request Quote

POST /piyovi_getQuote

Request Body:

{ "origin": { "city": "St. Catharines", "province": "ON", "postal_code": "L2R7K4" }, "destination": { "city": "Toronto", "province": "ON", "postal_code": "M5V3A8" }, "commodities": [ { "description": "Building materials - drywall sheets", "quantity": 4, "weight_lbs": 1200, "length_in": 96, "width_in": 48, "height_in": 12, "package_type": "skid", "stackable": true } ], "accessorials": ["tailgate_pickup", "tailgate_delivery"], "hazmat": { "is_hazmat": false } }

Response (200 OK):

{ "success": true, "mode": "ZONAL_LTL", "lane": "Z1-Z2", "total_weight_lbs": 1200, "charges": { "linehaul": 84.00, "accessorials": [ { "code": "tailgate_pickup", "amount": 25.00 }, { "code": "tailgate_delivery", "amount": 25.00 } ], "fuel_surcharge": 13.02, "tax": 14.82 }, "total_before_tax": 114.00, "total_after_tax": 128.82, "currency": "CAD", "quote_id": "Q-20260706-4821", "valid_until": "2026-07-11T14:30:00.000Z", "metadata": { "origin_zone": "Z1", "destination_zone": "Z2", "partner": "Piyovi" } }

For out-of-network lanes, the API returns mode: "PARTNER_PRICING" indicating partner carrier pricing is required. Quotes are valid for 5 days.

6. Create Shipment

POST /piyovi_createShipment

Accepts the same body as the Rate API, plus the following optional fields:

Field	Description
`origin.company_name`	Origin company name (BOL and label display)
`origin.street`, `contact_name`, `phone`, `email`	Origin contact details (BOL display)
`destination.company_name`	Destination company name (BOL and label display)
`destination.street`, `contact_name`, `phone`, `email`	Destination contact details (BOL display)
`pickup_date`	Requested pickup date (YYYY-MM-DD). Defaults to current date.
`special_instructions`	Free-text handling instructions (BOL display)
`reference.customer_reference`	PO or reference number (BOL display as "PO Number")

Response (200 OK):

{ "success": true, "shipment_id": "a7f3c2e8-1234-5678-9abc-def012345678", "tracking_number": "OJ260708-0003", "mode": "ZONAL_LTL", "lane": "Z1-Z2", "total_weight_lbs": 1200, "total_before_tax": 114.00, "total_after_tax": 128.82, "currency": "CAD", "status": "booked", "pickup_date": "2026-07-08T00:00:00.000Z" }

7. Track Shipment

Returns sanitized public tracking information. No authentication required. No sensitive fields (email, phone, full address, pricing) are exposed.

POST /getPublicTracking

Request Body:

{ "tracking_number": "OJ260708-0003" }

Response (200 OK):

{ "success": true, "shipment": { "tracking_number": "OJ260708-0003", "status": "in_transit", "service_type": "ltl", "origin_city": "St. Catharines", "origin_province": "ON", "destination_city": "Toronto", "destination_province": "ON", "pickup_date": "2026-07-08T14:00:00.000Z", "estimated_delivery_date": "2026-07-09T18:00:00.000Z", "delivered_date": null, "tracking_updates": [ { "timestamp": "2026-07-08T14:05:00.000Z", "status": "picked_up", "location": "St. Catharines, ON", "notes": "Shipment picked up" }, { "timestamp": "2026-07-08T16:30:00.000Z", "status": "in_transit", "location": "Hamilton, ON", "notes": "In transit" } ], "pod_available": false } }

8. Retrieve BOL Metadata — GET /piyovi_getBOL

Returns shipment and Bill of Lading metadata in JSON format. This endpoint returns metadata only — it does not return a PDF. For the PDF, use Section 9.

GET /piyovi_getBOL?shipment_id=<id>

— or —

GET /piyovi_getBOL?tracking_number=<tracking_number>

Shipment Identification: shipment_id accepts the internal ID or the tracking number. tracking_number may also be used explicitly.

Response (200 OK):

{ "success": true, "shipment_id": "a7f3c2e8-1234-5678-9abc-def012345678", "tracking_number": "OJ260708-0003", "bol": { "tracking_number": "OJ260708-0003", "status": "booked", "service_type": "ltl", "origin_address": { "company_name": "Example Shipper Inc.", "address_line": "123 Industrial Parkway", "city": "St. Catharines", "state_province": "ON", "postal_code": "L2R7K4", "country": "CA", "contact_name": "John Smith", "phone": "905-555-0100", "email": "shipping@example-shipper.com" }, "destination_address": { "company_name": "Example Consignee Ltd.", "address_line": "456 Commerce Boulevard", "city": "Toronto", "state_province": "ON", "postal_code": "M5V3A8", "country": "CA", "contact_name": "Sarah Johnson", "phone": "416-555-0200", "email": "receiving@example-consignee.com" }, "commodities": [ { "description": "Building materials - drywall sheets", "quantity": 4, "weight": 1200, "length": 96, "width": 48, "height": 12, "item_type": "skid", "stackable": true } ], "estimated_cost": 114.00, "final_cost": 128.82, "special_instructions": "Deliver to loading dock B between 9am-12pm.", "po_number": "PO-2026-00482", "pickup_time": "2026-07-08T00:00:00.000Z", "documents": [] }, "metadata": { "partner": "Piyovi", "bol_format": "json_metadata" } }

Clarification: bol_format: "json_metadata" confirms this response is structured data, not a PDF. Use GET /piyovi_getBOLDocument for the PDF.

9. Retrieve Carrier BOL PDF — GET /piyovi_getBOLDocument (v2.0)

Returns the Carrier Bill of Lading as a print-ready PDF. The PDF includes a QR code, shipper/consignee blocks, commodity table, special instructions, hazmat table (if applicable), and signature blocks.

GET /piyovi_getBOLDocument?tracking_number=<tracking_number>

Response (200 OK):

{ "success": true, "tracking_number": "OJ260708-0003", "bol_pdf_url": "https://storage.octojan.com/documents/carrier-bol-OJ260708-0003.pdf" }

Behavior

Caching: If the document already exists, the existing document is returned. Otherwise, it is generated and returned.
QR Code: Encodes the public tracking URL for smartphone scanning.
Ownership Verification: Verifies the shipment belongs to the partner's scope before returning the document.
Persistence: The returned URL may be stored and reused for future retrieval unless otherwise communicated by Octojan. Subsequent calls return the same URL.

Usage Example

curl -X GET \ "https://api.octojan.com/piyovi_getBOLDocument?tracking_number=OJ260708-0003" \ -H "x-api-key: YOUR_PARTNER_API_KEY"

10. Retrieve Carrier Shipping Label PDF — GET /piyovi_getShippingLabel (v2.0)

Returns the Carrier Shipping Label as a print-ready PDF. Generates one label page per piece, with QR code, Code128 barcode, FROM/TO address blocks, weight/piece count, and destination city banner.

GET /piyovi_getShippingLabel?tracking_number=<tracking_number>

Response (200 OK):

{ "success": true, "tracking_number": "OJ260708-0003", "label_pdf_url": "https://storage.octojan.com/documents/carrier-label-OJ260708-0003.pdf" }

Behavior

Multi-Piece: One PDF page per piece (sum of commodity quantities). Each page labeled "X of Y".
Label Size: 4" × 6" — standard thermal label format.
Caching: If the document already exists, the existing document is returned. Otherwise, it is generated and returned.
Barcode: Code128 barcode of the tracking number. If the barcode service is unavailable, the label still generates with the QR code.
Persistence: The returned URL may be stored and reused for future retrieval unless otherwise communicated by Octojan.

Usage Example

curl -X GET \ "https://api.octojan.com/piyovi_getShippingLabel?tracking_number=OJ260708-0003" \ -H "x-api-key: YOUR_PARTNER_API_KEY"

11. Integration Workflow

Authenticate → Request Quote → Create Shipment → Receive Tracking Number → Track Shipment → Retrieve BOL Metadata → Retrieve Carrier BOL PDF → Retrieve Shipping Label PDF

Steps 1–4 are the minimum required flow for booking a shipment.
Step 5 (Tracking) can be called at any time after creation — unauthenticated, suitable for customer-facing polling.
Steps 6–8 (BOL Metadata, BOL PDF, Shipping Label) can be called in any order after Step 4. Document URLs are persistent — call once and store.

12. Testing — Sandbox

The sandbox is a full-featured replica of production using test data and sandbox-scoped API keys. Shipments created in sandbox are flagged as test shipments. Generated PDFs are real documents stored in sandbox storage.

Existing Scenarios (v1.0)

#	Scenario	Expected Result
1	Rate Quote — Standard Urban Lane	Success with `mode: "ZONAL_LTL"`, lane, and full charge breakdown
2	Rate Quote — Out-of-Network Lane	Success with `mode: "PARTNER_PRICING"` and `reason: "OUT_OF_NETWORK_LANE"`
3	Create Shipment — Full Booking	Success with `shipment_id`, `tracking_number` (OJYYMMDD-NNNN), and `status: "booked"`
4	Track Shipment	Success with status, origin/destination city, and tracking_updates. No sensitive fields exposed.
5	Retrieve BOL Metadata	Success with full `bol` object and `metadata.bol_format: "json_metadata"`
8	Authentication Error Handling	Verify MISSING_API_KEY (401), INVALID_API_KEY (401), FORBIDDEN (403), NOT_FOUND (404)

New Scenarios (v2.0)

#	Scenario	Expected Result
6	Retrieve Carrier BOL PDF	Success with `bol_pdf_url`. Download PDF and verify: Octojan header, tracking number, shipper/consignee blocks, commodity table, QR code, signature blocks. Call twice — verify same URL returned (cache).
7	Retrieve Carrier Shipping Label PDF	Success with `label_pdf_url`. Download PDF and verify: page count = total pieces, "X of Y" counter, QR code, barcode, FROM/TO blocks, weight/pieces, destination banner. Multi-piece test: 2 skids + 3 boxes = 5 pages. Call twice — verify same URL (cache).

13. Error Codes

Error Code	HTTP	Description
`MISSING_API_KEY`	401	`x-api-key` header not provided.
`INVALID_API_KEY`	401	API key does not match any registered partner.
`PARTNER_INACTIVE`	403	Partner integration has been deactivated.
`FORBIDDEN`	403	Shipment does not belong to partner's scope.
`VALIDATION_ERROR`	400	Required fields missing or malformed.
`NOT_FOUND`	404	No shipment found for the given ID or tracking number.
`UPLOAD_FAILED`	500	Generated PDF could not be stored. Retry.
`INTERNAL_ERROR`	500	Unexpected internal error. Contact support if persistent.

14. Support

Contact	Details
Support Email	orders.octojan@yahoo.com
Website	https://octojan.com
Phone	(647) 702-9405
Hours	Monday – Friday, 8:00 AM – 6:00 PM Eastern Time

Octojan is committed to maintaining backward compatibility. Breaking changes will be communicated to partners in advance. Additive changes may be introduced without prior notice and will be documented in the Revision History.

Document	Partner API Integration Guide
Product	Octojan Logistics
Integration	Piyovi LTL Sandbox
Version	2.0
Status	Released
Last Updated	July 2026
Audience	Partner Developers
Classification	Partner Confidential

Document Information

Revision History

What's New in Version 2.0

New Endpoints

Restructured BOL Section

Backward Compatibility

1. Overview

2. Authentication

3. Base URL

4. Endpoint Summary

5. Rate API — Request Quote

6. Create Shipment

7. Track Shipment

8. Retrieve BOL Metadata — GET /piyovi_getBOL

9. Retrieve Carrier BOL PDF — GET /piyovi_getBOLDocument (v2.0)

Behavior

Usage Example

10. Retrieve Carrier Shipping Label PDF — GET /piyovi_getShippingLabel (v2.0)

Behavior

Usage Example

11. Integration Workflow

12. Testing — Sandbox

Existing Scenarios (v1.0)

New Scenarios (v2.0)

13. Error Codes

14. Support