Centro de ayudaGitHub

Cómo funciona atoship

Comprende los conceptos clave detrás de la API de envíos de atoship. Aprende sobre tarifas, etiquetas, rastreo, transportistas y facturación.

El flujo de envío

Cada envío sigue este sencillo proceso de 3 pasos: obtener tarifas, crear una etiqueta y rastrear el paquete.

Paso 1

Obtén tarifas

Compara precios de USPS, UPS y FedEx en una sola llamada a la API

Envía las dimensiones del paquete y las direcciones para obtener tarifas en tiempo real y estimaciones de entrega de todos los transportistas.

Paso 2

Crea la etiqueta

Genera una etiqueta de envío con la tarifa seleccionada

Elige la mejor tarifa y crea una etiqueta lista para imprimir. El costo se descuenta del saldo de tu billetera.

Paso 3

Rastrea el paquete

Monitorea el estado de la entrega con actualizaciones en tiempo real

Rastrea paquetes de todos los transportistas con una API de rastreo unificada y notificaciones por webhook.

Recursos principales

Direcciones
/v1/addresses
Direcciones de origen y destino de los envíos. atoship valida y estandariza las direcciones para evitar fallos en la entrega.
  • La validación de direcciones garantiza la entregabilidad
  • Detección de dirección residencial o comercial
  • Formato estandarizado (normas de USPS)
  • Soporte para direcciones internacionales
Tarifas
/v1/rates
Precios de envío en tiempo real de varios transportistas. Compara al instante las tarifas de USPS, UPS y FedEx.
  • Comparación de tarifas multitransportista en una sola llamada
  • Incluye precios comerciales con descuento
  • Estimaciones de tiempo de entrega
  • Opciones de nivel de servicio (Express, Ground, etc.)
Etiquetas
/v1/labels
Etiquetas de envío con números de rastreo. Genera etiquetas listas para imprimir en formato PDF, PNG o ZPL.
  • Múltiples formatos: PDF, PNG, ZPL (térmica)
  • Número de rastreo generado automáticamente
  • Costo descontado de la billetera
  • Anulación/reembolso dentro de 30 días
Rastreo
/v1/tracking
Actualizaciones del estado de entrega del paquete. Rastrea envíos de todos los transportistas con una API unificada.
  • Actualizaciones de estado en tiempo real
  • Notificaciones por webhook para cada evento
  • Confirmación de entrega
  • Alertas de excepciones

Transportistas

USPS
carrier: "usps"
Servicio Postal de EE. UU.: ideal para paquetes ligeros y entregas residenciales.
  • Priority Mail — 1 a 3 días
  • Priority Mail Express — Entrega al día siguiente
  • Ground Advantage — 2 a 5 días
  • First Class Mail — Cartas y paquetes pequeños
UPS
carrier: "ups"
United Parcel Service: confiable para envíos comerciales y paquetes más pesados.
  • Ground — 1 a 5 días
  • 2nd Day Air — 2 días
  • Next Day Air — Entrega al día siguiente
  • 3 Day Select — 3 días
FedEx
carrier: "fedex"
Federal Express: excelente para envíos exprés y entregas internacionales.
  • Ground — 1 a 5 días
  • Express Saver — 3 días
  • 2Day — 2 días
  • Home Delivery — Residencial

Cuenta y facturación

Billetera
/v1/wallet/balance
Saldo prepagado para comprar etiquetas de envío. Agrega fondos con tarjeta de crédito o transferencia bancaria.
  • Modelo de pago por uso
  • Sin cuotas mensuales ni mínimos
  • Recarga automática disponible
  • Historial de transacciones en el panel
Reembolsos
/v1/labels/{id}/void
Anula etiquetas sin usar y recupera el crédito. La mayoría de las etiquetas se pueden reembolsar dentro de 30 días.
  • Anula etiquetas sin usar para un reembolso total
  • USPS: reembolso dentro de 30 días
  • UPS/FedEx: reembolso dentro de 30 días
  • Crédito devuelto a la billetera

Integraciones

Canales de e-commerce
Dashboard → Channels
Conecta tus tiendas en línea para importar pedidos automáticamente. Sincroniza con Shopify, eBay, Amazon y más.
  • Shopify — Sincronización de pedidos en tiempo real
  • eBay — Integración con el marketplace
  • Amazon — Integración con SP-API
  • WooCommerce — Plugin de WordPress
Webhooks
/v1/webhooks
Recibe notificaciones en tiempo real de actualizaciones de rastreo, creación de etiquetas y más.
  • Actualizaciones del estado de rastreo
  • Eventos de etiqueta creada/anulada
  • Confirmaciones de entrega
  • URLs de endpoint personalizadas

Juntando todo

Flujo de trabajo completo de la API
Así es como todos los conceptos trabajan juntos en una integración típica
// Flujo completo de envío
const API_KEY = 'your_api_key';
const BASE_URL = 'https://atoship.com/api/v1';

// 1. Obtén tarifas de todos los transportistas
const ratesResponse = await fetch(`${BASE_URL}/rates`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: {
      name: "Your Store",
      street1: "123 Store Street",
      city: "San Francisco",
      state: "CA",
      zip: "94102"
    },
    to: {
      name: "John Customer",
      street1: "456 Customer Ave",
      city: "Los Angeles",
      state: "CA",
      zip: "90210"
    },
    parcel: {
      weight: 16,  // onzas
      length: 12,
      width: 8,
      height: 6
    }
  })
});

const { rates } = await ratesResponse.json();
// rates = [{ id, carrier, service, rate, delivery_days }, ...]

// 2. Crea la etiqueta con la tarifa más barata
const labelResponse = await fetch(`${BASE_URL}/labels`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    rate_id: rates[0].id,
    label_format: 'PDF'
  })
});

const label = await labelResponse.json();
// label = { id, tracking_number, label_url, carrier, cost }

// 3. Rastrea el paquete
const trackingResponse = await fetch(
  `${BASE_URL}/tracking/${label.tracking_number}`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

const tracking = await trackingResponse.json();
// tracking = { status, events: [{ timestamp, description, location }] }

Consejo profesional

Usa el API Playground para probar estas llamadas de forma interactiva antes de integrarlas en tu aplicación.

Próximos pasos

atoship © 2026