Référence API Ship-ify
Guide complet pour intégrer l'API d'optimisation d'emballage Ship-ify dans vos applications.
API Interactive (Swagger)Aperçu
L'API Ship-ify fournit une optimisation d'emballage 3D pour les expéditions e-commerce. À partir d'un ensemble de tailles de boîtes disponibles et d'articles à expédier, l'API calcule la configuration d'emballage optimale pour minimiser les coûts d'expédition tout en maximisant l'utilisation des boîtes.
Optimisation rapide
Résultats en millisecondes avec des algorithmes avancés
Emballage 3D
Véritable emballage 3D avec support de rotation
Contraintes de poids
Respecte les limites de poids pour chaque type de boîte
Visualisation
Visualisation HTML 3D (Pro & Entreprise)
Authentification
Toutes les requêtes API nécessitent une authentification à l'aide d'une clé API. Incluez votre clé API dans les en-têtes de requête :
Authorization: Bearer YOUR_API_KEYImportant: Gardez vos clés API en sécurité. Ne les exposez jamais dans le code côté client ou dans des dépôts publics.
Vous pouvez générer des clés API depuis votre tableau de bord.
Points de terminaison
/api/v1/shipping-optimizeOptimiser l'emballage d'un ensemble d'articles dans les boîtes disponibles.
Corps de la requête
Objet JSON contenant boxes, items et options (voir Format de requête)
/api/v1/shipping-optimizeRécupérer les capacités de l'API, les statistiques d'utilisation et des exemples de requêtes pour votre niveau.
Réponse
Objet JSON avec les capacités du niveau, les informations de quota et les statistiques d'utilisation
Ensembles de boîtes
Les ensembles de boîtes vous permettent de sauvegarder et de réutiliser des configurations de boîtes dans les requêtes API. Au lieu d'envoyer le tableau complet des boîtes à chaque requête, vous pouvez référencer un ensemble sauvegardé par sa clé unique.
Tip: Créez des ensembles de boîtes séparés pour différents scénarios d'expédition, comme les boîtes en carton standard vs les boîtes isolées pour les articles sensibles à la température.
Gestion des ensembles de boîtes
Créez et gérez vos ensembles de boîtes depuis le tableau de bord des ensembles de boîtes. Chaque ensemble reçoit une clé unique comme bs_abc123xyz456.
Utilisation des ensembles de boîtes dans les requêtes
Utilisez boxSetKey au lieu du tableau boxes :
{
"boxSetKey": "bs_abc123xyz456",
"items": [
{
"id": "item-001",
"name": "Product A",
"dimensions": { "length": 4, "width": 3, "height": 2 },
"weight": 1.5,
"quantity": 2
}
],
"options": {
"algorithm": "shipify-ultra"
}
}Limites d'ensembles de boîtes par niveau
| Niveau | Ensembles max |
|---|---|
| Free | 1 (max 10 boxes) |
| Basic | 2 (max 20 boxes each) |
| Pro | 5 (max 50 boxes each) |
| Enterprise | 50 (max 100 boxes each) |
Format de requête
Le corps de la requête POST doit inclure soit boxes soit boxSetKey, plus items, et optionnellement options.
Objet Box
| Champ | Type | Requis | Description |
|---|---|---|---|
| id | string | Yes | Identifiant unique pour le type de boîte |
| name | string | No | Nom lisible |
| dimensions | object | Yes | { length, width, height } dans votre unité préférée |
| weightCapacity | number | No | Limite de poids structurel de la boîte - poids maximum que le matériau de la boîte peut physiquement supporter |
| cost | number | No | Coût par boîte pour l'optimisation |
Objet Item
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Unique identifier for the item |
| name | string | No | Human-readable name |
| dimensions | object | Yes | { length, width, height } in your preferred unit |
| weight | number | No | Item weight for constraint checking |
| quantity | number | No | Number of this item to pack (default: 1) |
| fragile | boolean | No | Mark as fragile for special handling |
| keepUpright | boolean | No | Prevent vertical rotation |
| fragilityLevel | number | No | Niveau de fragilité de 0 (robuste) à 5 (extrêmement fragile). Utilisé par shipify-physics pour les décisions d'empilement. (Pro+ uniquement) |
| maxTopLoad | number | No | Poids maximum que cet article peut supporter dessus. Utilisé par shipify-physics pour appliquer les limites de capacité de charge. (Pro+ uniquement) |
Objet Options
| Champ | Type | Défaut | Description |
|---|---|---|---|
| algorithm | string | "shipify-ultra" | Packing algorithm (see Algorithms section) |
| allowRotation | boolean | true | Allow items to be rotated for better fit |
| prioritize | string | "space" | "space" | "cost" | "speed" | "consolidation" |
| enableVisualization | boolean | false | Include 3D HTML visualization (Basic+ only) |
| maxShipmentWeight | number | - | Carrier weight limit - shipments above this threshold incur overweight fees |
| oversizedItemHandling | string | "unpacked" | "custom-box" | "unpacked" - How to handle items larger than any available box |
| overweightItemHandling | string | "allow" | "allow" | "unpacked" - How to handle items heavier than maxShipmentWeight (defaults to "allow" when maxShipmentWeight is set) |
Understanding Weight Constraints
The API supports two distinct types of weight constraints:
Box Structural Limit (weightCapacity)
Set on each box type. This represents the maximum weight the box material can physically hold without breaking. The optimizer will not place items that would exceed this structural limit.
"boxes": [{ "id": "medium", "weightCapacity": 25, ... }]Carrier Shipment Limit (maxShipmentWeight)
Set in options. This represents the carrier threshold above which overweight fees apply. All shipments will be optimized to stay under this limit regardless of box capacity. When this option is set, all items must have a weight property defined.
"options": { "maxShipmentWeight": 50 }Overweight Item Handling (overweightItemHandling)
When a single item exceeds the maxShipmentWeight, this option controls how it's handled:
"allow"(default): Item is allowed to ship alone in a box, weight limit waived for this shipment"unpacked": Item is placed in the unpackedItems array with reason
"options": { "maxShipmentWeight": 50, "overweightItemHandling": "unpacked" }Both constraints are enforced simultaneously. A shipment must satisfy both the box structural capacity and the carrier weight limit.
Commandes par lots
Process multiple orders in a single API request. Instead of sending individual items, you can send an array of orders, each with its own items. The API will optimize packing for each order independently and return consolidated results.
Availability: All tiers
Batch order processing is available for all subscription tiers with the same limits.
Batch Limits
| Limit Type | Value |
|---|---|
| Max Orders per Batch | 50 |
| Max Items per Order | 100 |
| Max Total Items per Batch | 500 |
Batch Request Format
Use the orders array instead of items. Each order must have an orderId and its own items array.
{
"boxes": [
{ "id": "small", "name": "Small Box", "dimensions": { "length": 10, "width": 8, "height": 6 }, "cost": 2.50 },
{ "id": "medium", "name": "Medium Box", "dimensions": { "length": 14, "width": 12, "height": 10 }, "cost": 4.00 }
],
"orders": [
{
"orderId": "ORD-001",
"items": [
{ "id": "item-1", "name": "Book", "dimensions": { "length": 9, "width": 6, "height": 1.5 }, "weight": 1.2, "quantity": 2 }
]
},
{
"orderId": "ORD-002",
"items": [
{ "id": "item-2", "name": "Laptop", "dimensions": { "length": 14, "width": 10, "height": 2 }, "weight": 4.5, "quantity": 1 },
{ "id": "item-3", "name": "Charger", "dimensions": { "length": 4, "width": 3, "height": 2 }, "weight": 0.3, "quantity": 3 }
]
}
],
"options": {
"algorithm": "shipify-ultra"
}
}Batch Response Format
The response includes results for each order plus an overall summary.
{
"success": true,
"batch": true,
"results": [
{
"orderId": "ORD-001",
"success": true,
"data": {
"shipments": [...],
"unpackedItems": [],
"summary": { "totalShipments": 1, "totalCost": 2.50, ... }
}
},
{
"orderId": "ORD-002",
"success": true,
"data": {
"shipments": [...],
"unpackedItems": [],
"summary": { "totalShipments": 1, "totalCost": 4.00, ... }
}
}
],
"summary": {
"totalOrders": 2,
"successfulOrders": 2,
"failedOrders": 0,
"totalBoxesUsed": 2,
"totalCost": 6.50,
"averageUtilization": 42.5,
"totalItemsPacked": 3,
"totalItemsUnpacked": 0
},
"metadata": {
"algorithm": "shipify-ultra",
"executionTime": "45ms",
"timestamp": "2025-12-06T12:00:00.000Z"
}
}Backward Compatibility
The original single-order format using items array continues to work. Batch processing is only triggered when the orders array is present.
Format de réponse
Successful responses include shipment details, packing statistics, and metadata.
Response Structure
| Field | Description |
|---|---|
| success | Boolean indicating request success |
| data.shipments | Array of shipment objects with packed items |
| data.unpackedItems | Items that couldn't fit in any box |
| data.summary | Aggregated statistics (total cost, utilization, etc.) |
| data.suggestions | Optimization suggestions |
| metadata | Algorithm used, execution time, tier info |
| visualizationHtml | 3D HTML visualization (Pro+ only) |
Box Structure in Shipments
Each shipment contains a box object with the following fields:
| Field | Type | Description |
|---|---|---|
| id | string | Box ID (from your submitted boxes, or "custom-*" for oversized items) |
| name | string | Box name (or "Custom Box" for oversized items) |
| dimensions | object | { length, width, height } of the box |
| cost | number | Box cost (optional, 0 for custom boxes) |
| type | string | "custom" when oversizedItemHandling is "custom-box" (only present for custom boxes) |
Packed Items Structure
Each packed item in a shipment includes the following fields:
| Field | Type | Description |
|---|---|---|
| itemId | string | Original item ID as submitted in the request |
| itemIndex | number | Index within quantity expansion (0, 1, 2, ...). For items with quantity > 1, each instance gets a unique index. |
| position | object | { x, y, z } coordinates of item placement in the box |
| rotation | object | Axis mapping showing how item was rotated to fit |
| rotatedDimensions | object | { length, width, height } after rotation applied |
Rate Limit Headers
Every response includes rate limit information:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 985
X-RateLimit-Reset: 2025-11-30T00:00:00.000ZAlgorithmes
Choose the algorithm that best fits your use case. Algorithm availability depends on your subscription tier.
first-fitBasic+Fast, simple algorithm that places items in the first available space. Best for speed-critical applications.
best-fitBasic+Finds the best fitting space for each item, improving utilization over first-fit.
guillotineBasic+Divides space into rectangles for efficient 2D packing. Good balance of speed and utilization.
max-rectsPro+Advanced algorithm maintaining multiple free rectangles for optimal packing.
shipify-ultraAll Tiers (Default)Our smartest algorithm, optimized for both binning (grouping items into separate shipments) and packing (placing items into the smallest possible box). Uses look-ahead optimization, post-pack consolidation, and multi-pass refinement to minimize total boxes and maximize space utilization. Best for most use cases.
shipify-fitPro+Combines global box selection strategy with fast 3D placement. Uses O(items × boxes × positions) complexity for efficient packing with excellent results.
shipify-maxBasic+Weight-based grouping algorithm that groups items by order, splits bundles exceeding weight limits, consolidates small bundles, and validates each bundle with 3D packing. Ideal for multi-order shipments where weight-based grouping is preferred.
shipify-physicsAll TiersPhysics-aware packing algorithm that prioritizes heavier items at the bottom for stability, respects fragility levels (0-5), enforces load capacity limits, and validates center of gravity balance. Includes support area validation (70% minimum) and rotation constraints for fragile items. Advanced features (fragilityLevel, maxTopLoad) require Pro or Enterprise tier.
Niveaux d'abonnement
Choose the plan that fits your needs. FREE tier includes shipify-ultra and shipify-physics algorithms.
| Feature | Free ($0) | Basic ($5/mo) | Pro ($20/mo) | Enterprise ($80/mo) |
|---|---|---|---|---|
| Items/Month | 1,000 | 5,000 | 25,000 | 125,000 |
| Max Items per Request | 10 | 25 | 100 | 1,000 |
| Max Box Types per Request | 10 | 20 | 50 | 100 |
| API Keys | 1 | 1 | 5 | 10 |
| Batch Orders (max/items/total) | 50/100/500 | 50/100/500 | 50/100/500 | 50/100/500 |
| 3D Visualization | - | ✓ | ✓ | ✓ |
| Algorithms | 2 (shipify-ultra, physics) | 6 | 8 (+max-rects, shipify-fit) | All 8 |
| Overage Rate (per 1000 items) | $2.00 | $1.50 | $1.20 | $1.00 |
Algorithm Availability by Tier
- FREE: shipify-ultra, shipify-physics
- BASIC: FREE + first-fit, best-fit, guillotine, shipify-max
- PRO: All BASIC algorithms + max-rects, shipify-fit
- ENTERPRISE: All 8 algorithms
Limites de débit
Why We Count Items, Not API Requests
Batching multiple orders into a single API call is more efficient for everyone. Charging per item optimized aligns with our CPU costs and encourages you to batch orders for maximum efficiency. This means you can send 100 orders in one batch request and pay the same as 100 individual requests with one order each.
Usage limits are based on items processed per month (counting item quantities). Limits reset on the 1st of each month. When you exceed your limit, the API returns a 429 status code with details about your usage.
| Tier | Monthly Item Limit | Overage Rate |
|---|---|---|
| FREE | 1,000 items | $2.00 / 1,000 items |
| BASIC | 5,000 items | $1.50 / 1,000 items |
| PRO | 25,000 items | $1.20 / 1,000 items |
| ENTERPRISE | 125,000 items | $1.00 / 1,000 items |
Rate Limit Response
{
"error": "Monthly item limit exceeded",
"message": "This request would use 50 items, but you only have 25 items remaining in your monthly quota of 1000 items.",
"itemsRequested": 50,
"itemsRemaining": 25,
"monthlyLimit": 1000,
"resetAt": "2026-02-01T00:00:00.000Z"
}Response Headers
Every API response includes usage headers:
X-RateLimit-Limit: Your monthly item limitX-RateLimit-Remaining: Items remaining after this requestX-RateLimit-Reset: When your quota resets (1st of next month)X-Items-Used: Total items used this month
Codes d'erreur
| Status | Error | Description |
|---|---|---|
| 400 | Invalid request | Missing or malformed boxes/items |
| 401 | Authentication failed | Invalid or missing API key |
| 403 | Feature not available | Algorithm or feature not in your tier |
| 403 | Limit exceeded | Too many items or box types for your tier |
| 429 | Monthly item limit exceeded | Monthly item quota exhausted |
| 500 | Internal server error | Server-side error, please retry |
Exemples
Exemple de requête
{
"boxes": [
{
"id": "b1-box",
"name": "Box B1",
"dimensions": {
"length": 7,
"width": 7,
"height": 12
},
"weightCapacity": 25,
"cost": 1.18
},
{
"id": "b3-box",
"name": "Box B3",
"dimensions": {
"length": 11,
"width": 10,
"height": 14
},
"weightCapacity": 35,
"cost": 2.11
},
{
"id": "b7-box",
"name": "Box B7",
"dimensions": {
"length": 20,
"width": 16,
"height": 18
},
"weightCapacity": 55,
"cost": 3.98
}
],
"items": [
{
"id": "BOOK-001",
"name": "Hardcover Book",
"dimensions": {
"length": 9.5,
"width": 7.5,
"height": 1.5
},
"weight": 1.8,
"quantity": 2
},
{
"id": "LAPTOP-COMP",
"name": "Laptop Computer",
"dimensions": {
"length": 18,
"width": 11,
"height": 4.5
},
"weight": 6.8,
"quantity": 1
}
],
"options": {
"algorithm": "shipify-ultra",
"allowRotation": true,
"prioritize": "space",
"enableVisualization": true
}
}Exemple de réponse
{
"success": true,
"data": {
"shipments": [
{
"box": {
"id": "b7-box",
"name": "Box B7",
"dimensions": {
"length": 20,
"width": 16,
"height": 18
},
"cost": 3.98
},
"packedItems": [
{
"itemId": "BOOK-001",
"itemIndex": 0,
"position": {
"x": 0,
"y": 0,
"z": 0
},
"rotation": {
"lengthAxis": "x",
"widthAxis": "y",
"heightAxis": "z"
},
"rotatedDimensions": {
"length": 9.5,
"width": 7.5,
"height": 1.5
}
},
{
"itemId": "BOOK-001",
"itemIndex": 1,
"position": {
"x": 9.5,
"y": 0,
"z": 0
},
"rotation": {
"lengthAxis": "x",
"widthAxis": "y",
"heightAxis": "z"
},
"rotatedDimensions": {
"length": 9.5,
"width": 7.5,
"height": 1.5
}
},
{
"itemId": "LAPTOP-COMP",
"itemIndex": 0,
"position": {
"x": 0,
"y": 0,
"z": 1.5
},
"rotation": {
"lengthAxis": "x",
"widthAxis": "y",
"heightAxis": "z"
},
"rotatedDimensions": {
"length": 18,
"width": 11,
"height": 4.5
}
}
],
"utilization": {
"volume": 18.2,
"weight": 18.9
},
"totalWeight": 10.4
}
],
"unpackedItems": [],
"summary": {
"totalShipments": 1,
"totalCost": 3.98,
"averageUtilization": 18.2,
"packingEfficiency": 18,
"itemsSuccessfullyPacked": 3,
"itemsUnpacked": 0
},
"suggestions": [
"Shipify-Ultra algorithm: Enhanced with look-ahead and consolidation"
]
},
"metadata": {
"algorithm": "shipify-ultra",
"executionTime": "32ms",
"timestamp": "2025-12-06T12:00:00.000Z",
"tier": "FREE"
}
}Exemple cURL
curl -X POST https://ship-ify.com/api/v1/shipping-optimize \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"boxes": [
{
"id": "small-box",
"dimensions": { "length": 10, "width": 8, "height": 6 }
}
],
"items": [
{
"id": "item-1",
"dimensions": { "length": 4, "width": 3, "height": 2 },
"quantity": 1
}
]
}'