Referencia API Ship-ify
Guía completa para integrar la API de optimización de embalaje Ship-ify en tus aplicaciones.
API Interactiva (Swagger)Descripción general
La API Ship-ify proporciona optimización de embalaje 3D para envíos de comercio electrónico. Dado un conjunto de tamaños de cajas disponibles y artículos a enviar, la API calcula la configuración de embalaje óptima para minimizar los costos de envío mientras maximiza la utilización de las cajas.
Optimización rápida
Resultados en milisegundos con algoritmos avanzados
Embalaje 3D
Embalaje 3D real con soporte de rotación
Restricciones de peso
Respeta los límites de peso para cada tipo de caja
Visualización
Visualización HTML 3D (Pro y Empresarial)
Autenticación
Todas las solicitudes API requieren autenticación usando una clave API. Incluye tu clave API en los encabezados de la solicitud:
Authorization: Bearer YOUR_API_KEYImportant: Mantén tus claves API seguras. Nunca las expongas en código del lado del cliente o en repositorios públicos.
Puedes generar claves API desde tu panel de control.
Endpoints
/api/v1/shipping-optimizeOptimizar el embalaje de un conjunto de artículos en las cajas disponibles.
Cuerpo de la solicitud
Objeto JSON que contiene boxes, items y options (ver Formato de solicitud)
/api/v1/shipping-optimizeRecuperar capacidades de la API, estadísticas de uso y ejemplos de solicitudes para tu nivel.
Respuesta
Objeto JSON con capacidades del nivel, información de cuota y estadísticas de uso
Conjuntos de cajas
Los conjuntos de cajas te permiten guardar y reutilizar configuraciones de cajas en las solicitudes API. En lugar de enviar el array completo de cajas con cada solicitud, puedes referenciar un conjunto guardado por su clave única.
Tip: Crea conjuntos de cajas separados para diferentes escenarios de envío, como cajas de cartón estándar vs cajas aisladas para artículos sensibles a la temperatura.
Gestión de conjuntos de cajas
Crea y gestiona tus conjuntos de cajas desde el panel de conjuntos de cajas. Cada conjunto obtiene una clave única como bs_abc123xyz456.
Uso de conjuntos de cajas en solicitudes
Usa boxSetKey en lugar del array 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"
}
}Límites de conjuntos de cajas por nivel
| Nivel | Conjuntos máx |
|---|---|
| Free | 1 (max 10 boxes) |
| Basic | 2 (max 20 boxes each) |
| Pro | 5 (max 50 boxes each) |
| Enterprise | 50 (max 100 boxes each) |
Formato de solicitud
El cuerpo de la solicitud POST debe incluir boxes o boxSetKey, más items, y opcionalmente options.
Objeto Box
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| id | string | Yes | Identificador único para el tipo de caja |
| name | string | No | Nombre legible |
| dimensions | object | Yes | { length, width, height } en tu unidad preferida |
| weightCapacity | number | No | Límite de peso estructural de la caja - peso máximo que el material de la caja puede soportar físicamente |
| cost | number | No | Costo por caja para la optimización |
Objeto 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 | Nivel de fragilidad de 0 (robusto) a 5 (extremadamente frágil). Usado por shipify-physics para decisiones de apilamiento. (Solo Pro+) |
| maxTopLoad | number | No | Peso máximo que este artículo puede soportar encima. Usado por shipify-physics para aplicar límites de capacidad de carga. (Solo Pro+) |
Objeto Options
| Campo | Tipo | Predeterminado | Descripción |
|---|---|---|---|
| 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.
Pedidos por lotes
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.
Formato de respuesta
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.000ZAlgoritmos
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.
Niveles de suscripción
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
Límites de tasa
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
Códigos de error
| 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 |
Ejemplos
Ejemplo de solicitud
{
"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
}
}Ejemplo de respuesta
{
"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"
}
}Ejemplo 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
}
]
}'