API de Tarifas de Envío

API de Tarifas de Envío

Obtén tarifas de envío en tiempo real de USPS, UPS, FedEx y otros transportistas con una sola llamada a la API.

Descripción general

Endpoint de tarifas:

POST https://api.atoship.com/v1/rates

Devuelve opciones de envío con precios, tiempos de tránsito y detalles del servicio.

Formato de la solicitud

Solicitud básica:

{
  "from": {
    "zip": "10001",
    "country": "US"
  },
  "to": {
    "zip": "90210",
    "country": "US"
  },
  "package": {
    "weight": 16,
    "length": 10,
    "width": 8,
    "height": 4
  }
}

Campos de dirección

Objeto From/To:

*Obligatorio para algunos transportistas

Campos del paquete

Objeto Package:

Tipos de paquete

Tipos disponibles:

package (default)
envelope
flat_rate_envelope
flat_rate_box_small
flat_rate_box_medium
flat_rate_box_large
regional_rate_box_a
regional_rate_box_b

Formato de la respuesta

Respuesta exitosa:

{
  "success": true,
  "rates": [
    {
      "id": "rate_abc123",
      "carrier": "USPS",
      "service": "Priority Mail",
      "price": 8.95,
      "currency": "USD",
      "delivery_days": 2,
      "delivery_date": "2024-01-17"
    },
    {
      "id": "rate_def456",
      "carrier": "UPS",
      "service": "Ground",
      "price": 12.50,
      "currency": "USD",
      "delivery_days": 5
    }
  ]
}

Filtrar por transportista

Transportistas específicos:

{
  "carriers": ["USPS", "UPS"],
  "from": { ... },
  "to": { ... },
  "package": { ... }
}

Filtros de servicio

Filtrar por servicio:

{
  "services": ["Priority Mail", "Ground"],
  "from": { ... },
  "to": { ... },
  "package": { ... }
}

Varios paquetes

Solicitud con varios paquetes:

{
  "from": { ... },
  "to": { ... },
  "packages": [
    { "weight": 16, "length": 10, "width": 8, "height": 4 },
    { "weight": 32, "length": 12, "width": 10, "height": 6 }
  ]
}

Tarifas internacionales

Información de aduana:

{
  "from": {
    "zip": "10001",
    "country": "US"
  },
  "to": {
    "zip": "M5V 2H1",
    "country": "CA"
  },
  "package": { ... },
  "customs": {
    "contents_type": "merchandise",
    "value": 50.00,
    "currency": "USD"
  }
}

Residencial vs. comercial

Tipo de dirección:

{
  "to": {
    "zip": "90210",
    "country": "US",
    "is_residential": true
  }
}

Opciones de firma

Confirmación de entrega:

{
  "options": {
    "signature": "adult",
    "saturday_delivery": false
  }
}

Valores de firma:

• none (sin firma)
• standard (firma estándar)
• adult (firma de un adulto)
• indirect (firma indirecta)

Seguro

Agregar seguro:

{
  "options": {
    "insurance_amount": 100.00
  }
}

Ejemplo de código

Solicitud completa:

const response = await fetch('https://api.atoship.com/v1/rates', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: { zip: '10001', country: 'US' },
    to: { zip: '90210', country: 'US' },
    package: { weight: 16 }
  })
});

const { rates } = await response.json();
const cheapest = rates.sort((a, b) => a.price - b.price)[0];

Manejo de errores

Respuesta de error:

{
  "success": false,
  "error": {
    "code": "invalid_address",
    "message": "Destination zip code is invalid",
    "field": "to.zip"
  }
}

Almacenamiento en caché de tarifas

Buenas prácticas:

• Las tarifas son válidas ~15 minutos
• Almacena en caché por origen/destino
• Vuelve a consultar antes de comprar
• Gestiona los cambios de precio

Consejos de rendimiento

Optimiza las solicitudes:

1. Incluye las dimensiones para mayor precisión
2. Especifica los transportistas para reducir llamadas
3. Usa webhooks para cotizaciones masivas
4. Almacena en caché las rutas frecuentes