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.
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.
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.
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
/v1/addresses- 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
/v1/rates- 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.)
/v1/labels- 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
/v1/tracking- Actualizaciones de estado en tiempo real
- Notificaciones por webhook para cada evento
- Confirmación de entrega
- Alertas de excepciones
Transportistas
carrier: "usps"- 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
carrier: "ups"- 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
carrier: "fedex"- Ground — 1 a 5 días
- Express Saver — 3 días
- 2Day — 2 días
- Home Delivery — Residencial
Cuenta y facturación
/v1/wallet/balance- Modelo de pago por uso
- Sin cuotas mensuales ni mínimos
- Recarga automática disponible
- Historial de transacciones en el panel
/v1/labels/{id}/void- 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
Dashboard → Channels- Shopify — Sincronización de pedidos en tiempo real
- eBay — Integración con el marketplace
- Amazon — Integración con SP-API
- WooCommerce — Plugin de WordPress
/v1/webhooks- Actualizaciones del estado de rastreo
- Eventos de etiqueta creada/anulada
- Confirmaciones de entrega
- URLs de endpoint personalizadas
Juntando todo
// 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.