Integration model — data, schema, and security
Single-core endpoint
Use the single operational endpoint POST https://packem.tcs-innovations.com/pack for all production packing requests. Packem returns the packing solution in JSON. There is also POST /pack.png which returns a rendered image of the layout for debugging/visual validation — do not use that in production (rendering is slow).
Canonical request structure
All requests should be a single JSON document containing required arrays (see demo). Keep payloads as compact as possible: only fields Packem needs for the decision (dimensions, quantity, objectives, etc).
{
"bins": [
{"id": "B-001", "length": 8.0, "width": 6.0, "height": 8.0},
{"id": "B-002", "length": 8.0, "width": 8.0, "height": 4.0}
],
"items": [
{"id": "I-001", "length": 8.0, "width": 2.0, "height": 1.0},
{"id": "I-002", "length": 3.0, "width": 4.0, "height": 5.0},
{"id": "I-003", "length": 2.0, "width": 4.0, "height": 4.0},
{"id": "I-004", "length": 6.0, "width": 4.0, "height": 5.0},
{"id": "I-005", "length": 8.0, "width": 4.0, "height": 2.0},
{"id": "I-006", "length": 4.0, "width": 4.0, "height": 1.0},
{"id": "I-007", "length": 7.0, "width": 4.0, "height": 2.0},
{"id": "I-008", "length": 3.0, "width": 6.0, "height": 5.0}
],
"objective": "minimise_bins",
"constraints": {"rotation": false}
}Typical response
Packem returns a JSON document containing status,objective_score, and a list of bins (id + placed items with coordinates/orientations).
{
"solution": {
"bins": [{"id": "B-001", "length": 8, "width": 6, "height": 8,
"items": [{"id": "I-005", "origin_dims": [8,4,2], "rotation_instruction": "no_rotation", "rotated_dims": [8,4,2], "position": [0,0,5]},
{"id": "I-003", "origin_dims": [2,4,4], "rotation_instruction": "no_rotation", "rotated_dims": [2,4,4], "position": [6,0,0]},
{"id": "I-002", "origin_dims": [3,4,5], "rotation_instruction": "no_rotation", "rotated_dims": [3,4,5], "position": [0,0,0]},
{"id": "I-008", "origin_dims": [3,6,5], "rotation_instruction": "no_rotation", "rotated_dims": [3,6,5], "position": [3,0,0]}]},
{"id": "B-002", "length": 8, "width": 8, "height": 4,
"items": [{"id": "I-007", "origin_dims": [7,4,2], "rotation_instruction": "no_rotation", "rotated_dims": [7,4,2], "position": [0,0,0]},
{"id": "I-001", "origin_dims": [8,2,1], "rotation_instruction": "no_rotation", "rotated_dims": [8,2,1], "position": [0,4,0]},
{"id": "I-006", "origin_dims": [4,4,1], "rotation_instruction": "no_rotation", "rotated_dims": [4,4,1], "position": [0,4,1]}]}],
"objective_score": 2,
"num_bins_used": 2,
"num_items_packed": 7,
"num_items_unpacked": 1,
"missing_items": ["I-004"]
}
}Authentication & transport security
Packem uses Bearer tokens. Every request must include:
Authorization: Bearer <PACKEM_API_KEY>
Content-Type: application/json
Security best practices:
- Store API keys in a secrets manager (e.g., AWS Secrets Manager, GCP Secret Manager, Vault) — do not hard-code in source.
- Use TLS (HTTPS) with strict certificate validation for all outbound calls.
- Rotate keys periodically and support key revocation in your operational process.
- Limit IPs or use egress controls if your security policy requires (Packem supports static egress allow-listing on request).
Integration Scenarios — practical recipes
Below are common real-world patterns. Each includes where to trigger the call, desired sync/async behavior, and sample code snippets.
1) ERP → Packem → WMS (Warehouse pre-assign)
Use case: when an order is released for picking, the ERP (or its integration middleware) calls Packem to determine cartonization. The WMS consumes the returned placements to generate pick packs and printing labels.
Trigger: Order status transitions to "Ready for Fulfilment".
Behavior: Sync call acceptable if the ERP can wait < 3s; else orchestrate async job and push result back to the ERP/WMS record.
Example (curl)
curl -X POST https://packem.tcs-innovations.com/pack -H "Authorization: Bearer {PACKEM_API_KEY}" -H "Content-Type: application/json" -d '{ "items":[{"id":"I-001","length":10,"width":10,"height":5}, {"id":"I-002","length":5,"width":4,"height":5}], "bins":[{"id":"Bin-A","length":50,"width":40,"height":40}] }'Processing notes
- Record Packem
request_id and Packem response status on the ERP/WMS order record. - If using synchronous calls, implement a client timeout and a graceful fallback (e.g., default cartonization) if Packem fails.
- For auditability, log both outbound payload and Packem response in your integration logs (redact sensitive data such as API keys).
2) OMS Checkout Recommendation (real-time)
Use case: show the best carton selection or shipping box at checkout or in the carrier selection page to help select best shipping option or display shipping cost savings.
Trigger: Cart confirmation or checkout event.
Behavior: Synchronous call — must be low-latency. Reduce input to only items in the checkout cart.
Example (Node.js / axios)
// axios example
const axios = require('axios');
const payload = { items: [ /* ... */ ], bins: [ /* ... */ ] };
axios.post('https://packem.tcs-innovations.com/pack', payload, {
headers: { Authorization: 'Bearer ' + process.env.PACKEM_API_KEY }
}).then(res => {
// show suggestions to user
}).catch(err => {
// fallback: show generic shipping options
});Operational tips
- Cache common results (e.g., standard item groups) where acceptable to reduce calls.
- Keep payloads small for checkout (only current cart items, not the full order history).
3) Batch & scheduled optimizations (cloud job)
Use case: nightly or scheduled optimization of large fulfillment batches (e.g., pick waves, scheduled shipments). Best for large volumes where packing can be done asynchronously.
Trigger: Cron job or scheduler (e.g., Cloud Scheduler → Cloud Function / Lambda).
Behavior: Asynchronous; chunk large batches into smaller requests and run in parallel, respecting rate limits.
Processing recommendations
- Chunk jobs by region/warehouse or order group to limit request size.
- Persist Packem
request_id and result; report exceptions to an errors queue for manual review. - Consider eventual consistency: WMS should accept Packem results and apply them to shipment records when ready.
Note on /pack.png
Use POST /pack.png for visual validation in development only. The PNG endpoint renders images and is intentionally slower — avoid using it in production traffic or synchronous workflows.
