Shipping and Logistics

Sarah integrates with shipping and logistics services to calculate shipping costs, generate labels, and track packages.

Supported Providers

Correo Argentino

Complete integration with Correo Argentino for shipments within Argentina.

Features:

• Shipping cost calculation
• Label generation
• Package tracking
• Shipment import

Initial Configuration

1. Get Credentials

For Correo Argentino:

1. Contact Correo Argentino to get API credentials
2. Get:
   • Username
   • Password
   • Client code (if applicable)

2. Configure in Sarah

1. Log in to Sarah
2. Go to Settings > Integrations > Shipping
3. Select Correo Argentino
4. Enter your credentials
5. Configure environment (test or production)
6. Save configuration

API Endpoints

Calculate Shipping Cost

POST /api/shipping/rates

Body:

json
{
  "partner": "correo-argentino",
  "origin": {
    "postal_code": "C1000",
    "city": "Buenos Aires",
    "province": "CABA"
  },
  "destination": {
    "postal_code": "5000",
    "city": "Córdoba",
    "province": "Córdoba"
  },
  "package": {
    "weight": 1.5,
    "length": 30,
    "width": 20,
    "height": 15
  }
}

Response:

json
{
  "rates": [
    {
      "service": "standard",
      "name": "Standard Shipping",
      "cost": 2500.00,
      "estimated_days": 5
    },
    {
      "service": "express",
      "name": "Express Shipping",
      "cost": 4500.00,
      "estimated_days": 2
    }
  ]
}

Get Agencies

http
GET /api/shipping/agencies?partner=correo-argentino&postal_code=5000

Response:

json
{
  "agencies": [
    {
      "id": "AG001",
      "name": "Centro Agency",
      "address": "Main St. 123",
      "postal_code": "5000",
      "city": "Córdoba"
    }
  ]
}

Track Shipment

http
GET /api/shipping/tracking?partner=correo-argentino&tracking_number=AA123456789AR

Response:

json
{
  "tracking_number": "AA123456789AR",
  "status": "in_transit",
  "current_location": "Córdoba Distribution Center",
  "events": [
    {
      "date": "2025-01-26T10:00:00Z",
      "status": "picked_up",
      "location": "Buenos Aires"
    },
    {
      "date": "2025-01-27T14:30:00Z",
      "status": "in_transit",
      "location": "Córdoba Distribution Center"
    }
  ],
  "estimated_delivery": "2025-01-29"
}

Import Shipments

POST /api/shipping/import

Body:

json
{
  "partner": "correo-argentino",
  "shipments": [
    {
      "tracking_number": "AA123456789AR",
      "recipient": {
        "name": "Juan Pérez",
        "address": "Main St. 123",
        "postal_code": "5000",
        "city": "Córdoba"
      },
      "package": {
        "weight": 1.5
      }
    }
  ]
}

Integration in Sales Flow

1. Calculate Shipping in Checkout

When a customer enters their postal code in checkout:

javascript
const response = await fetch('/api/shipping/rates', {
  method: 'POST',
  body: JSON.stringify({
    partner: 'correo-argentino',
    origin: {
      postal_code: storePostalCode,
      city: storeCity,
      province: storeProvince
    },
    destination: {
      postal_code: customerPostalCode,
      city: customerCity,
      province: customerProvince
    },
    package: {
      weight: cartWeight,
      dimensions: cartDimensions
    }
  })
});

const { rates } = await response.json();
// Show shipping options to customer

2. Generate Label

After confirming sale:

javascript
// Label is generated automatically
// Or manually from order
const response = await fetch('/api/shipping/label', {
  method: 'POST',
  body: JSON.stringify({
    partner: 'correo-argentino',
    sale_id: 789,
    service: 'standard'
  })
});

3. Track Shipment

Customer can track their order:

javascript
const response = await fetch(
  `/api/shipping/tracking?partner=correo-argentino&tracking_number=${trackingNumber}`
);
const tracking = await response.json();
// Show shipment status

Service Types

Correo Argentino

Shipment States

Data Structure

Credentials

typescript
interface ShippingIntegrationCredentials {
  username: string;
  password: string;
  client_code?: string; // Optional
}

Package

typescript
interface Package {
  weight: number; // kg
  length?: number; // cm
  width?: number; // cm
  height?: number; // cm
  value?: number; // Declared value
}

Address

typescript
interface Address {
  postal_code: string;
  city: string;
  province: string;
  street?: string;
  number?: string;
  floor?: string;
  apartment?: string;
}

Factory Pattern

Sarah uses a factory pattern to support multiple providers:

typescript
import { getShippingService } from '@/lib/shipping/factory';

const service = getShippingService(
  'correo-argentino',
  credentials,
  'production'
);

const rates = await service.calculateRates(origin, destination, package);

Add New Provider

To add a new provider:

1. Create a class that extends BaseShippingService
2. Implement required methods
3. Add provider to factory
4. Update documentation

Best Practices

1. Validate addresses: Verify postal codes are valid
2. Calculate dimensions: Include dimensions for more accurate calculations
3. Handle errors: Implement error handling for API failures
4. Cache rates: Cache rates for common addresses
5. Track shipments: Update shipment status periodically
6. Notify customers: Send notifications when status changes

Troubleshooting

Error calculating rates

1. Verify credentials: Ensure they're correct
2. Verify addresses: Postal codes must be valid
3. Review logs: Look for errors in provider API
4. Verify environment: Ensure you use correct environment

Shipment doesn't track

1. Verify tracking number: Must be valid
2. Review provider: Ensure you use correct provider
3. Verify in provider: Check directly on provider website

Label doesn't generate

1. Verify data: All required fields must be present
2. Review logs: Look for errors in generation
3. Verify permissions: Ensure you have permissions to generate labels

Additional Resources

• Correo Argentino Documentation
• Correo Argentino API (if available)
• Shipping Guide - Shipping features in Sarah

Support

If you need help:

1. Review integration logs
2. Verify provider configuration
3. Contact Sarah support with error details