Skip to main content

​
Fulfillment Overview

The order fulfillment process consists of three main stages:
  1. Label Generation: Create shipping labels through Venndelo integration
  2. Pickup Request: Schedule carrier pickup for ready orders
  3. Tracking & Delivery: Monitor shipment status until delivered
All fulfillment operations integrate with Venndelo’s API. Ensure your VENNDELO_API_KEY is configured.

​
Order Processing Workflow

1

Identify New Orders

Filter by Por Procesar (DETAILS) status to see orders needing labels:
Eligible Statuses
['PENDING', 'APPROVED', 'PREPARING', 'PROCESSING', 'CONFIRMED']
These orders show a Generate Label button (printer icon).
2

Verify Order Details

Check each order for:
  • Complete shipping address (address_1, city, phone)
  • Valid product line items
  • Correct payment status
  • Customer contact info (email/phone for notifications)
3

Generate Shipping Label

Click the printer button on the order row. This triggers:Backend Process (/api/admin/generate-label):
Label Generation Process
// 1. Resolve Venndelo External ID
const dbOrders = await prisma.order.findMany({
  where: { id: { in: orderIds } },
  select: { externalId: true, status: true }
});

// 2. Create Shipment (if not exists)
await fetch('https://api.venndelo.com/v1/admin/shipping/create-shipments', {
  method: 'POST',
  headers: { 'X-Venndelo-Api-Key': VENNDELO_API_KEY },
  body: JSON.stringify({ order_ids: venndeloIds })
});

// 3. Poll for Label (max 20 attempts, 1.5s delay)
const labelRes = await fetch('https://api.venndelo.com/v1/admin/shipping/generate-labels', {
  method: 'POST',
  body: JSON.stringify({
    order_ids: venndeloIds,
    format: "LABEL_10x15",
    output: "URL"
  })
});

// 4. Send Email Notification
if (labelRes.status === 'SUCCESS') {
  sendShippingConfirmation(order, trackingNumber, pdfUrl);
}
4

Download/Print Label

  • Label PDF opens in new tab automatically
  • Toast notification provides manual link if popup blocked
  • Print 10x15cm thermal label or standard paper
5

Update Order Status

Order automatically moves to READY_TO_SHIP status after successful label generation.
Labels can be regenerated/reprinted at any time by clicking the printer icon on READY_TO_SHIP or SHIPPED orders.

​
Requesting Carrier Pickup

Once labels are generated, schedule pickup:
1

Filter Ready Orders

Click Por Recoger (READY_TO_SHIP) in the status sidebar.
2

Click Request Pickup

Yellow Solicitar Recogida button appears on READY_TO_SHIP orders.Confirm the action when prompted.
3

Backend Processing

Calls /api/admin/request-pickup:
Pickup Request
// Notify carrier
await fetch('https://api.venndelo.com/v1/admin/shipping/request-pickup', {
  method: 'POST',
  headers: { 'X-Venndelo-Api-Key': VENNDELO_API_KEY },
  body: JSON.stringify({ order_ids: venndeloIds })
});

// Update local status
await prisma.order.updateMany({
  where: { externalId: { in: venndeloIds } },
  data: { status: 'PICKUP_REQUESTED', updatedAt: new Date() }
});
4

Confirmation

  • Status changes to PICKUP_REQUESTED (orange badge)
  • Badge shows “Esperando Recogida”
  • Carrier receives pickup notification
Do not request pickup until packages are physically ready. Carriers may charge fees for failed pickup attempts.

​
Label Generation Statuses

​
Success Response

{
  "status": "SUCCESS",
  "data": "https://venndelo.com/labels/abc123.pdf"
}
Action: Open PDF in new window, send shipping confirmation email.

​
Processing Response

{
  "status": "PROCESSING",
  "message": "La guía se está generando..."
}
Action: Wait 10 seconds and retry (handled automatically up to 20 times).

​
Error Response

{
  "status": "ERROR",
  "items": [{
    "status": "ERROR",
    "errors": [{
      "message": "Insufficient balance"
    }]
  }]
}
Common errors:
  • Insufficient balance: Prepaid account needs funding
  • Invalid address: Missing or incorrect shipping details
  • Shipment already exists: Safe to ignore, proceed to generate label

​
Email Notifications

When labels are generated successfully, customers receive automated emails: Email Content:
  • Order confirmation with readable ID (PIN)
  • Tracking number
  • Carrier name
  • PDF label attachment (optional)
  • Link to tracking page: https://kaiu.com.co/rastreo?guide={trackingNumber}
Implementation:
Email Trigger (generate-label.js:136-182)
// Fetch order details from Venndelo
const orderRes = await fetch(`https://api.venndelo.com/v1/admin/orders/${venndeloOrderId}`);
const order = await orderRes.json();

// Extract tracking info
if (order.shipments && order.shipments.length > 0) {
  const trackingNumber = order.shipments[0].tracking_number;
  
  // Enrich with readable ID from DB
  const dbOrder = await prisma.order.findFirst({
    where: { externalId: String(venndeloOrderId) }
  });
  
  const enrichedOrder = {
    ...order,
    readableId: dbOrder?.readableId
  };
  
  // Send async (non-blocking)
  sendShippingConfirmation(enrichedOrder, trackingNumber, pdfUrl);
}
Email sending is async/non-blocking to prevent label generation delays. Check logs for email delivery status.

​
Tracking & Monitoring

​
Shipment Sync

Manually sync tracking updates:
1

Click Sincronizar

Located in the shipments tab top bar.
2

Backend Sync Process

Endpoint: /api/admin/sync-shipmentsQueries Venndelo for updated shipment statuses and tracking events.
3

Review Results

Toast shows:
  • Procesadas: Number of orders checked
  • Actualizadas: Number of status changes applied

​
Tracking Number Display

In the order table, the Rastreo column shows:
Tracking Display
{
  carrier_name: "Servientrega",        // Carrier
  tracking_number: "SER123456789"      // Clickable guide number
}
Clicking the tracking number opens the public tracking page.

​
Fulfillment Best Practices

Morning Batch Processing

Process all new orders first thing each day. Generate labels in batch for efficiency.

Verify Addresses

Double-check addresses for COD orders before generating labels to avoid failed deliveries.

Coordinate Pickups

Request pickups only when packages are ready. Group multiple orders for same-day pickup.

Monitor Transit Times

Sync tracking daily. Follow up on shipments in transit > 5 days.

​
Handling Special Cases

​
Reprint Lost Labels

If a label is lost or damaged:
  1. Find the order (use search or filter by READY_TO_SHIP)
  2. Click the printer icon (now shows as “Reimprimir Guía”)
  3. Same PDF will be regenerated from Venndelo
Labels can be reprinted unlimited times without creating duplicate shipments.

​
Cancel a Shipment

To cancel after label generation:
  1. Contact Venndelo support (no API endpoint yet)
  2. Manually update order status to CANCELLED in database
  3. Release inventory if needed

​
Failed Deliveries

If carrier marks delivery as failed:
  1. Check tracking for reason (address issue, customer unavailable)
  2. Contact customer to verify/update address
  3. Coordinate re-delivery with carrier
  4. Sync shipments to update status

​
COD Order Workflow

Cash on Delivery orders require special handling:
1

Filter COD Orders

Use payment filter: Contra Entrega
2

Generate Labels Normally

COD orders generate labels the same way as prepaid orders.
3

Track Collection

After delivery, carrier collects payment and remits to your account.
4

Reconcile Payments

Check carrier’s COD reports to match collected amounts with order totals.
COD orders have higher return rates. Consider phone verification before shipping high-value COD orders.

​
Troubleshooting

​
Label Generation Fails

Symptom: Error message after clicking generate label. Solutions:
  • Check Venndelo account balance (prepaid carriers)
  • Verify shipping address is complete and valid
  • Ensure product dimensions/weight are configured
  • Check backend logs for API error details

​
Pickup Not Requested

Symptom: Button disabled or missing. Solutions:
  • Verify order status is exactly READY_TO_SHIP
  • Ensure label was generated successfully first
  • Check that shipment exists in Venndelo

​
Tracking Not Updating

Symptom: Tracking number shows but status stale. Solutions:
  • Click Sincronizar to force update from Venndelo
  • Check carrier’s website directly with tracking number
  • Allow 24-48 hours for carrier to scan packages

​
Email Not Received

Symptom: Customer didn’t get shipping notification. Solutions:
  • Check backend logs for email sending errors
  • Verify customer email in order shipping_info
  • Check spam/junk folder
  • Ensure email service credentials are configured

​
Next Steps

Admin Portal

Return to admin portal overview

Payment Integration

Learn about payment processing and webhooks

Build docs developers (and LLMs) love

Get started for freeTalk to us