REST API

Documentación API

Integra etiquetas de envío en tu aplicación con nuestra potente API REST. Obtén tarifas en tiempo real, crea etiquetas y rastrea envíos programáticamente.

Autenticación

Todas las solicitudes API requieren autenticación usando tu clave y secreto API. Incluye estos encabezados en cada solicitud:

headers

X-API-Key: your_api_key
X-API-Secret: your_api_secret

Aviso de Seguridad

Mantén tu secreto API seguro. Nunca lo expongas en código del lado del cliente o repositorios públicos.

Ejemplo de Solicitud

bash

curl -X GET https://uspostage.io/api/v1/account/balance \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Saldo de Cuenta

Consulta los saldos de tu billetera crypto y el historial de transacciones. La API utiliza tu billetera crypto (BTC, LTC, LTCT) para pagos.

GET

/api/v1/account/balance

Obtener saldos e historial de transacciones

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
includeTransactions	`boolean`	Opcional	Incluir historial de transacciones
currency	`string`	Opcional	Filtrar transacciones por moneda (BTC, LTC, LTCT)
limit	`number`	Opcional	Número de transacciones (por defecto: 20, máx: 100)

Ejemplo de Solicitud

bash

curl -X GET "https://uspostage.io/api/v1/account/balance?includeTransactions=true&limit=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Respuesta

json

{
  "success": true,
  "data": {
    "balances": [
      { "currency": "BTC", "balance": 0.00125000 },
      { "currency": "LTC", "balance": 0.50000000 },
      { "currency": "LTCT", "balance": 0.00000000 }
    ],
    "supportedCurrencies": ["BTC", "LTC", "LTCT"],
    "transactions": [
      {
        "id": "txn_abc123",
        "currency": "BTC",
        "type": "deposit",
        "amount": 0.00100000,
        "balanceAfter": 0.00125000,
        "description": "Deposit via CoinPayments",
        "createdAt": "2024-01-10T12:00:00Z"
      },
      {
        "id": "txn_def456",
        "currency": "BTC",
        "type": "label_purchase",
        "amount": -0.00015000,
        "balanceAfter": 0.00025000,
        "description": "API labels purchase for order USP-12345678",
        "createdAt": "2024-01-09T15:30:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 25,
      "hasMore": true
    }
  }
}

Agregar Fondos

Para agregar fondos a tu billetera, visita la página Mi Billetera y deposita usando BTC, LTC o LTCT (testnet).

Verificación de Dirección

Verifica y estandariza direcciones de envío para asegurar la entregabilidad.

POST

/api/v1/shipping/verify-address

Verificar y corregir una dirección de envío

Cuerpo de Solicitud

Parámetro	Tipo	Requerido	Descripción
address	`Address`	Requerido	Dirección a verificar
strict	`boolean`	Opcional	Habilitar modo de verificación estricta

Ejemplo de Solicitud

bash

curl -X POST https://uspostage.io/api/v1/shipping/verify-address \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "address": {
      "name": "John Doe",
      "street1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  }'

Respuesta

json

{
  "success": true,
  "data": {
    "verified": true,
    "addressId": "adr_abc123",
    "verifiedAddress": {
      "name": "JOHN DOE",
      "street1": "123 MAIN ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip": "94102-1234",
      "country": "US"
    },
    "verification": {
      "success": true,
      "errors": []
    }
  }
}

Tarifas de Envío

Obtén tarifas de envío en tiempo real de múltiples transportistas incluyendo USPS, UPS, FedEx y DHL.

POST

/api/v1/shipping/rates

Calcular tarifas de envío para un paquete

Cuerpo de Solicitud

Parámetro	Tipo	Requerido	Descripción
fromAddress	`Address`	Requerido	Objeto de dirección del remitente
toAddress	`Address`	Requerido	Objeto de dirección del destinatario
packageDetails	`Package`	Requerido	Dimensiones y peso del paquete
carriers	`string[]`	Opcional	Filtrar por transportistas específicos (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Opcional	Requerido para envíos internacionales

Objeto de Dirección

Parámetro	Tipo	Requerido	Descripción
name	`string`	Requerido	Nombre completo
company	`string`	Opcional	Nombre de empresa
street1	`string`	Requerido	Línea de dirección 1
street2	`string`	Opcional	Línea de dirección 2
city	`string`	Requerido	Ciudad
state	`string`	Requerido	Código de estado/provincia
zip	`string`	Requerido	Código postal
country	`string`	Requerido	Código de país (US, CA, etc.)
phone	`string`	Opcional	Número de teléfono
email	`string`	Opcional	Correo electrónico

Objeto de Paquete

Parámetro	Tipo	Requerido	Descripción
length	`number`	Requerido	Largo en pulgadas
width	`number`	Requerido	Ancho en pulgadas
height	`number`	Requerido	Alto en pulgadas
weight	`number`	Requerido	Peso en onzas

Objeto CustomsInfo

Envíos Internacionales

Requerido al enviar internacionalmente (cuando fromAddress.country difiere de toAddress.country).

Parámetro	Tipo	Requerido	Descripción
contents_type	`string`	Requerido	Tipo de contenido: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Opcional	Requerido cuando contents_type es 'other'
customs_certify	`boolean`	Requerido	Debe ser true - certifica la exactitud de la declaración
customs_signer	`string`	Requerido	Nombre de la persona que certifica la declaración aduanera
eel_pfc	`string`	Requerido	Código de exención de exportación (usar 'NOEEI 30.37(a)' para envíos menores a $2,500)
non_delivery_option	`string`	Requerido	Qué hacer si no se puede entregar: 'return' o 'abandon'
restriction_type	`string`	Requerido	Tipo de restricción: 'none', 'other', 'quarantine', o 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Opcional	Requerido cuando restriction_type no es 'none'
customs_items	`CustomsItem[]`	Requerido	Array de artículos a enviar (1-100 artículos)

Objeto CustomsItem

Parámetro	Tipo	Requerido	Descripción
description	`string`	Requerido	Descripción detallada del artículo
quantity	`number`	Requerido	Cantidad de artículos (mínimo: 1)
value	`number`	Requerido	Valor en USD (debe ser mayor a 0)
weight	`number`	Requerido	Peso en onzas (debe ser mayor a 0)
origin_country	`string`	Requerido	Código de país de 2 letras (ej., 'US', 'CN')
hs_tariff_number	`string`	Requerido	Código arancelario HS de 6-10 dígitos

Ejemplo de Solicitud

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "US"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    }
  }'

Respuesta

json

{
  "success": true,
  "data": {
    "shipmentId": "shp_abc123",
    "rates": [
      {
        "id": "rate_xyz789",
        "carrier": "USPS",
        "service": "Priority Mail",
        "rate": 8.95,
        "currency": "USD",
        "delivery_days": 2,
        "delivery_date": "2024-01-15"
      },
      {
        "id": "rate_def456",
        "carrier": "UPS",
        "service": "Ground",
        "rate": 12.50,
        "currency": "USD",
        "delivery_days": 5,
        "delivery_date": "2024-01-18"
      }
    ]
  }
}

Ejemplo de Envío Internacional

Para envíos internacionales, incluye el objeto customsInfo con declaraciones de artículos:

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "phone": "4155551234"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Queen St W",
      "city": "Toronto",
      "state": "ON",
      "zip": "M5V 2A8",
      "country": "CA",
      "phone": "4165551234"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    },
    "customsInfo": {
      "contents_type": "merchandise",
      "customs_certify": true,
      "customs_signer": "John Doe",
      "eel_pfc": "NOEEI 30.37(a)",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "customs_items": [
        {
          "description": "Cotton T-Shirt",
          "quantity": 2,
          "value": 25.00,
          "weight": 8,
          "origin_country": "US",
          "hs_tariff_number": "6109100010"
        }
      ]
    }
  }'

Crear Pedido

Crea y gestiona pedidos de envío. Los pedidos contienen uno o más artículos de etiquetas de envío.

GET

/api/v1/orders

Listar todos los pedidos

POST

/api/v1/orders

Crear un nuevo pedido

GET

/api/v1/orders/{id}

Obtener detalles del pedido

Listar Pedidos - Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
limit	`number`	Opcional	Número de resultados (por defecto: 50, máx: 100)
offset	`number`	Opcional	Desplazamiento de paginación

Crear Pedido - Cuerpo de Solicitud

Parámetro	Tipo	Requerido	Descripción
items	`OrderItem[]`	Requerido	Array de artículos del pedido
email	`string`	Opcional	Email del cliente
externalReference	`string`	Opcional	Tu ID de referencia

Objeto OrderItem

API Simplificada

Solo se requieren shipmentId y rateId. Las direcciones, detalles del paquete e información aduanera se extraen automáticamente del envío.

Parámetro	Tipo	Requerido	Descripción
shipmentId	`string`	Requerido	ID de envío del endpoint de tarifas
rateId	`string`	Requerido	ID de tarifa del endpoint de tarifas

Ejemplo: Crear Pedido

bash

curl -X POST https://uspostage.io/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "items": [
      {
        "shipmentId": "shp_abc123",
        "rateId": "rate_xyz789"
      }
    ],
    "externalReference": "ORDER-12345"
  }'

Respuesta

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "trackingId": "USP-12345678",
    "totalAmount": 8.95,
    "paymentStatus": "pending",
    "items": [
      {
        "orderItemId": "item_xyz789",
        "rateId": "rate_xyz789"
      }
    ]
  }
}

Comprar Etiquetas

Compra etiquetas de envío para todos los artículos de un pedido. Las etiquetas se compran usando el saldo de tu billetera crypto (BTC, LTC o LTCT).

POST

/api/v1/labels/purchase

Comprar etiquetas de envío para un pedido

Cuerpo de Solicitud

Pago Crypto

La API convertirá el costo de la etiqueta en USD a crypto a las tasas actuales. Debes tener saldo suficiente (incluyendo 10% de margen para fluctuaciones de precio).

Parámetro	Tipo	Requerido	Descripción
orderId	`string`	Requerido	ID del pedido para comprar etiquetas
currency	`string`	Opcional	Moneda crypto para pagar (BTC, LTC, LTCT). Si no se especifica, selecciona automáticamente la primera moneda con saldo suficiente.

Ejemplo de Solicitud

bash

curl -X POST https://uspostage.io/api/v1/labels/purchase \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "orderId": "ord_abc123",
    "currency": "BTC"
  }'

Respuesta

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "externalReference": "ORDER-12345",
    "totalLabels": 2,
    "successCount": 2,
    "failCount": 0,
    "labels": [
      {
        "orderItemId": "item_xyz789",
        "success": true,
        "trackingCode": "9400111899223456789012",
        "labelUrl": "https://easypost.com/labels/lbl_abc123.pdf",
        "carrier": "USPS",
        "service": "Priority Mail",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_abc123.pdf",
          "png": "https://easypost.com/labels/lbl_abc123.png"
        }
      },
      {
        "orderItemId": "item_def456",
        "success": true,
        "trackingCode": "9400111899223456789013",
        "labelUrl": "https://easypost.com/labels/lbl_def456.pdf",
        "carrier": "FedEx",
        "service": "Ground",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_def456.pdf"
        }
      }
    ]
  }
}

402 Saldo Insuficiente

Si el saldo de tu billetera es muy bajo, la API devuelve un estado 402 con la cantidad de crypto requerida.

Respuesta de Saldo Insuficiente

json

{
  "success": false,
  "error": "Insufficient balance",
  "message": "Need 0.00011000 BTC (includes 10% buffer), have 0.00005000",
  "currency": "BTC",
  "required": 0.00011000,
  "requiredUsd": 5.50,
  "available": 0.00005000,
  "balanceEndpoint": "/api/v1/account/balance"
}

Seguimiento

Rastrea envíos usando el código de seguimiento de las etiquetas compradas.

GET

/api/v1/tracking/{code}

Obtener información de seguimiento

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	`string`	Requerido	Código de seguimiento

Ejemplo de Solicitud

bash

curl -X GET https://uspostage.io/api/v1/tracking/9400111899223456789012 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Respuesta

json

{
  "success": true,
  "data": {
    "trackingCode": "9400111899223456789012",
    "carrier": "USPS",
    "status": "in_transit",
    "statusDetail": "In Transit to Next Facility",
    "estDeliveryDate": "2024-01-15T00:00:00Z",
    "publicUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
    "trackingDetails": [
      {
        "status": "in_transit",
        "message": "In Transit to Next Facility",
        "datetime": "2024-01-12T14:30:00Z",
        "location": "San Francisco, CA"
      },
      {
        "status": "accepted",
        "message": "Accepted at USPS Origin Facility",
        "datetime": "2024-01-11T09:15:00Z",
        "location": "San Francisco, CA"
      }
    ],
    "updatedAt": "2024-01-12T14:30:00Z"
  }
}

Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos, como creación de etiquetas o actualizaciones de seguimiento.

GET

/api/v1/webhooks

Listar webhooks registrados

POST

/api/v1/webhooks

Registrar un nuevo webhook

GET

/api/v1/webhooks/{id}

Obtener detalles del webhook

DELETE

/api/v1/webhooks/{id}

Eliminar un webhook

Eventos Disponibles

label.created

Cuando una etiqueta se compra exitosamente

label.failed

Cuando falla la generación de etiqueta

Registrar Webhook - Cuerpo de Solicitud

Parámetro	Tipo	Requerido	Descripción
webhookUrl	`string`	Requerido	URL para recibir eventos webhook
events	`string[]`	Requerido	Array de tipos de eventos a suscribir

Ejemplo: Registrar Webhook

bash

curl -X POST https://uspostage.io/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"]
  }'

Respuesta

json

{
  "success": true,
  "data": {
    "id": "whk_abc123",
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"],
    "secret": "whsec_abc123xyz789..."
  }
}

Verificación de Firma de Webhook

Cada webhook incluye un encabezado de firma para verificación. Verifica la firma usando HMAC-SHA256:

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Ejemplo de Payload de Webhook

json

{
  "event": "label.created",
  "timestamp": "2024-01-12T14:30:00Z",
  "data": {
    "orderId": "ord_abc123",
    "orderItemId": "item_xyz789",
    "externalReference": "ORDER-12345",
    "label": {
      "trackingCode": "9400111899223456789012",
      "carrier": "USPS",
      "service": "Priority Mail",
      "labelUrl": "https://uspostage.io/labels/lbl_abc123.pdf"
    }
  }
}

REST API

Documentación API

Integra etiquetas de envío en tu aplicación con nuestra potente API REST. Obtén tarifas en tiempo real, crea etiquetas y rastrea envíos programáticamente.

Autenticación

Todas las solicitudes API requieren autenticación usando tu clave y secreto API. Incluye estos encabezados en cada solicitud:

headers

X-API-Key: your_api_key
X-API-Secret: your_api_secret

Aviso de Seguridad

Mantén tu secreto API seguro. Nunca lo expongas en código del lado del cliente o repositorios públicos.

Ejemplo de Solicitud

bash

curl -X GET https://uspostage.io/api/v1/account/balance \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Saldo de Cuenta

Consulta los saldos de tu billetera crypto y el historial de transacciones. La API utiliza tu billetera crypto (BTC, LTC, LTCT) para pagos.

GET

/api/v1/account/balance

Obtener saldos e historial de transacciones

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
includeTransactions	`boolean`	Opcional	Incluir historial de transacciones
currency	`string`	Opcional	Filtrar transacciones por moneda (BTC, LTC, LTCT)
limit	`number`	Opcional	Número de transacciones (por defecto: 20, máx: 100)

Ejemplo de Solicitud

bash

curl -X GET "https://uspostage.io/api/v1/account/balance?includeTransactions=true&limit=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Respuesta

json

{
  "success": true,
  "data": {
    "balances": [
      { "currency": "BTC", "balance": 0.00125000 },
      { "currency": "LTC", "balance": 0.50000000 },
      { "currency": "LTCT", "balance": 0.00000000 }
    ],
    "supportedCurrencies": ["BTC", "LTC", "LTCT"],
    "transactions": [
      {
        "id": "txn_abc123",
        "currency": "BTC",
        "type": "deposit",
        "amount": 0.00100000,
        "balanceAfter": 0.00125000,
        "description": "Deposit via CoinPayments",
        "createdAt": "2024-01-10T12:00:00Z"
      },
      {
        "id": "txn_def456",
        "currency": "BTC",
        "type": "label_purchase",
        "amount": -0.00015000,
        "balanceAfter": 0.00025000,
        "description": "API labels purchase for order USP-12345678",
        "createdAt": "2024-01-09T15:30:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 25,
      "hasMore": true
    }
  }
}

Agregar Fondos

Para agregar fondos a tu billetera, visita la página Mi Billetera y deposita usando BTC, LTC o LTCT (testnet).

Verificación de Dirección

Verifica y estandariza direcciones de envío para asegurar la entregabilidad.

POST

/api/v1/shipping/verify-address

Verificar y corregir una dirección de envío

Cuerpo de Solicitud

Parámetro	Tipo	Requerido	Descripción
address	`Address`	Requerido	Dirección a verificar
strict	`boolean`	Opcional	Habilitar modo de verificación estricta

Ejemplo de Solicitud

bash

curl -X POST https://uspostage.io/api/v1/shipping/verify-address \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "address": {
      "name": "John Doe",
      "street1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  }'

Respuesta

json

{
  "success": true,
  "data": {
    "verified": true,
    "addressId": "adr_abc123",
    "verifiedAddress": {
      "name": "JOHN DOE",
      "street1": "123 MAIN ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip": "94102-1234",
      "country": "US"
    },
    "verification": {
      "success": true,
      "errors": []
    }
  }
}

Tarifas de Envío

Obtén tarifas de envío en tiempo real de múltiples transportistas incluyendo USPS, UPS, FedEx y DHL.

POST

/api/v1/shipping/rates

Calcular tarifas de envío para un paquete

Cuerpo de Solicitud

Parámetro	Tipo	Requerido	Descripción
fromAddress	`Address`	Requerido	Objeto de dirección del remitente
toAddress	`Address`	Requerido	Objeto de dirección del destinatario
packageDetails	`Package`	Requerido	Dimensiones y peso del paquete
carriers	`string[]`	Opcional	Filtrar por transportistas específicos (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Opcional	Requerido para envíos internacionales

Objeto de Dirección

Parámetro	Tipo	Requerido	Descripción
name	`string`	Requerido	Nombre completo
company	`string`	Opcional	Nombre de empresa
street1	`string`	Requerido	Línea de dirección 1
street2	`string`	Opcional	Línea de dirección 2
city	`string`	Requerido	Ciudad
state	`string`	Requerido	Código de estado/provincia
zip	`string`	Requerido	Código postal
country	`string`	Requerido	Código de país (US, CA, etc.)
phone	`string`	Opcional	Número de teléfono
email	`string`	Opcional	Correo electrónico

Objeto de Paquete

Parámetro	Tipo	Requerido	Descripción
length	`number`	Requerido	Largo en pulgadas
width	`number`	Requerido	Ancho en pulgadas
height	`number`	Requerido	Alto en pulgadas
weight	`number`	Requerido	Peso en onzas

Objeto CustomsInfo

Envíos Internacionales

Requerido al enviar internacionalmente (cuando fromAddress.country difiere de toAddress.country).

Parámetro	Tipo	Requerido	Descripción
contents_type	`string`	Requerido	Tipo de contenido: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Opcional	Requerido cuando contents_type es 'other'
customs_certify	`boolean`	Requerido	Debe ser true - certifica la exactitud de la declaración
customs_signer	`string`	Requerido	Nombre de la persona que certifica la declaración aduanera
eel_pfc	`string`	Requerido	Código de exención de exportación (usar 'NOEEI 30.37(a)' para envíos menores a $2,500)
non_delivery_option	`string`	Requerido	Qué hacer si no se puede entregar: 'return' o 'abandon'
restriction_type	`string`	Requerido	Tipo de restricción: 'none', 'other', 'quarantine', o 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Opcional	Requerido cuando restriction_type no es 'none'
customs_items	`CustomsItem[]`	Requerido	Array de artículos a enviar (1-100 artículos)

Objeto CustomsItem

Parámetro	Tipo	Requerido	Descripción
description	`string`	Requerido	Descripción detallada del artículo
quantity	`number`	Requerido	Cantidad de artículos (mínimo: 1)
value	`number`	Requerido	Valor en USD (debe ser mayor a 0)
weight	`number`	Requerido	Peso en onzas (debe ser mayor a 0)
origin_country	`string`	Requerido	Código de país de 2 letras (ej., 'US', 'CN')
hs_tariff_number	`string`	Requerido	Código arancelario HS de 6-10 dígitos

Ejemplo de Solicitud

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "US"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    }
  }'

Respuesta

json

{
  "success": true,
  "data": {
    "shipmentId": "shp_abc123",
    "rates": [
      {
        "id": "rate_xyz789",
        "carrier": "USPS",
        "service": "Priority Mail",
        "rate": 8.95,
        "currency": "USD",
        "delivery_days": 2,
        "delivery_date": "2024-01-15"
      },
      {
        "id": "rate_def456",
        "carrier": "UPS",
        "service": "Ground",
        "rate": 12.50,
        "currency": "USD",
        "delivery_days": 5,
        "delivery_date": "2024-01-18"
      }
    ]
  }
}

Ejemplo de Envío Internacional

Para envíos internacionales, incluye el objeto customsInfo con declaraciones de artículos:

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "phone": "4155551234"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Queen St W",
      "city": "Toronto",
      "state": "ON",
      "zip": "M5V 2A8",
      "country": "CA",
      "phone": "4165551234"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    },
    "customsInfo": {
      "contents_type": "merchandise",
      "customs_certify": true,
      "customs_signer": "John Doe",
      "eel_pfc": "NOEEI 30.37(a)",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "customs_items": [
        {
          "description": "Cotton T-Shirt",
          "quantity": 2,
          "value": 25.00,
          "weight": 8,
          "origin_country": "US",
          "hs_tariff_number": "6109100010"
        }
      ]
    }
  }'

Crear Pedido

Crea y gestiona pedidos de envío. Los pedidos contienen uno o más artículos de etiquetas de envío.

GET

/api/v1/orders

Listar todos los pedidos

POST

/api/v1/orders

Crear un nuevo pedido

GET

/api/v1/orders/{id}

Obtener detalles del pedido

Listar Pedidos - Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
limit	`number`	Opcional	Número de resultados (por defecto: 50, máx: 100)
offset	`number`	Opcional	Desplazamiento de paginación

Crear Pedido - Cuerpo de Solicitud

Parámetro	Tipo	Requerido	Descripción
items	`OrderItem[]`	Requerido	Array de artículos del pedido
email	`string`	Opcional	Email del cliente
externalReference	`string`	Opcional	Tu ID de referencia

Objeto OrderItem

API Simplificada

Solo se requieren shipmentId y rateId. Las direcciones, detalles del paquete e información aduanera se extraen automáticamente del envío.

Parámetro	Tipo	Requerido	Descripción
shipmentId	`string`	Requerido	ID de envío del endpoint de tarifas
rateId	`string`	Requerido	ID de tarifa del endpoint de tarifas

Ejemplo: Crear Pedido

bash

curl -X POST https://uspostage.io/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "items": [
      {
        "shipmentId": "shp_abc123",
        "rateId": "rate_xyz789"
      }
    ],
    "externalReference": "ORDER-12345"
  }'

Respuesta

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "trackingId": "USP-12345678",
    "totalAmount": 8.95,
    "paymentStatus": "pending",
    "items": [
      {
        "orderItemId": "item_xyz789",
        "rateId": "rate_xyz789"
      }
    ]
  }
}

Comprar Etiquetas

Compra etiquetas de envío para todos los artículos de un pedido. Las etiquetas se compran usando el saldo de tu billetera crypto (BTC, LTC o LTCT).

POST

/api/v1/labels/purchase

Comprar etiquetas de envío para un pedido

Cuerpo de Solicitud

Pago Crypto

La API convertirá el costo de la etiqueta en USD a crypto a las tasas actuales. Debes tener saldo suficiente (incluyendo 10% de margen para fluctuaciones de precio).

Parámetro	Tipo	Requerido	Descripción
orderId	`string`	Requerido	ID del pedido para comprar etiquetas
currency	`string`	Opcional	Moneda crypto para pagar (BTC, LTC, LTCT). Si no se especifica, selecciona automáticamente la primera moneda con saldo suficiente.

Ejemplo de Solicitud

bash

curl -X POST https://uspostage.io/api/v1/labels/purchase \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "orderId": "ord_abc123",
    "currency": "BTC"
  }'

Respuesta

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "externalReference": "ORDER-12345",
    "totalLabels": 2,
    "successCount": 2,
    "failCount": 0,
    "labels": [
      {
        "orderItemId": "item_xyz789",
        "success": true,
        "trackingCode": "9400111899223456789012",
        "labelUrl": "https://easypost.com/labels/lbl_abc123.pdf",
        "carrier": "USPS",
        "service": "Priority Mail",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_abc123.pdf",
          "png": "https://easypost.com/labels/lbl_abc123.png"
        }
      },
      {
        "orderItemId": "item_def456",
        "success": true,
        "trackingCode": "9400111899223456789013",
        "labelUrl": "https://easypost.com/labels/lbl_def456.pdf",
        "carrier": "FedEx",
        "service": "Ground",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_def456.pdf"
        }
      }
    ]
  }
}

402 Saldo Insuficiente

Si el saldo de tu billetera es muy bajo, la API devuelve un estado 402 con la cantidad de crypto requerida.

Respuesta de Saldo Insuficiente

json

{
  "success": false,
  "error": "Insufficient balance",
  "message": "Need 0.00011000 BTC (includes 10% buffer), have 0.00005000",
  "currency": "BTC",
  "required": 0.00011000,
  "requiredUsd": 5.50,
  "available": 0.00005000,
  "balanceEndpoint": "/api/v1/account/balance"
}

Seguimiento

Rastrea envíos usando el código de seguimiento de las etiquetas compradas.

GET

/api/v1/tracking/{code}

Obtener información de seguimiento

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	`string`	Requerido	Código de seguimiento

Ejemplo de Solicitud

bash

curl -X GET https://uspostage.io/api/v1/tracking/9400111899223456789012 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Respuesta

json

{
  "success": true,
  "data": {
    "trackingCode": "9400111899223456789012",
    "carrier": "USPS",
    "status": "in_transit",
    "statusDetail": "In Transit to Next Facility",
    "estDeliveryDate": "2024-01-15T00:00:00Z",
    "publicUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
    "trackingDetails": [
      {
        "status": "in_transit",
        "message": "In Transit to Next Facility",
        "datetime": "2024-01-12T14:30:00Z",
        "location": "San Francisco, CA"
      },
      {
        "status": "accepted",
        "message": "Accepted at USPS Origin Facility",
        "datetime": "2024-01-11T09:15:00Z",
        "location": "San Francisco, CA"
      }
    ],
    "updatedAt": "2024-01-12T14:30:00Z"
  }
}

Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos, como creación de etiquetas o actualizaciones de seguimiento.

GET

/api/v1/webhooks

Listar webhooks registrados

POST

/api/v1/webhooks

Registrar un nuevo webhook

GET

/api/v1/webhooks/{id}

Obtener detalles del webhook

DELETE

/api/v1/webhooks/{id}

Eliminar un webhook

Eventos Disponibles

label.created

Cuando una etiqueta se compra exitosamente

label.failed

Cuando falla la generación de etiqueta

Registrar Webhook - Cuerpo de Solicitud

Parámetro	Tipo	Requerido	Descripción
webhookUrl	`string`	Requerido	URL para recibir eventos webhook
events	`string[]`	Requerido	Array de tipos de eventos a suscribir

Ejemplo: Registrar Webhook

bash

curl -X POST https://uspostage.io/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"]
  }'

Respuesta

json

{
  "success": true,
  "data": {
    "id": "whk_abc123",
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"],
    "secret": "whsec_abc123xyz789..."
  }
}

Verificación de Firma de Webhook

Cada webhook incluye un encabezado de firma para verificación. Verifica la firma usando HMAC-SHA256:

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Ejemplo de Payload de Webhook

json

{
  "event": "label.created",
  "timestamp": "2024-01-12T14:30:00Z",
  "data": {
    "orderId": "ord_abc123",
    "orderItemId": "item_xyz789",
    "externalReference": "ORDER-12345",
    "label": {
      "trackingCode": "9400111899223456789012",
      "carrier": "USPS",
      "service": "Priority Mail",
      "labelUrl": "https://uspostage.io/labels/lbl_abc123.pdf"
    }
  }
}

Documentación API

Autenticación

Ejemplo de Solicitud

Saldo de Cuenta

Parámetros de Consulta

Ejemplo de Solicitud

Respuesta

Verificación de Dirección

Cuerpo de Solicitud

Ejemplo de Solicitud

Respuesta

Tarifas de Envío

Cuerpo de Solicitud

Objeto de Dirección

Objeto de Paquete

Objeto CustomsInfo

Objeto CustomsItem

Ejemplo de Solicitud

Respuesta

Ejemplo de Envío Internacional

Crear Pedido

Listar Pedidos - Parámetros de Consulta

Crear Pedido - Cuerpo de Solicitud

Objeto OrderItem

Ejemplo: Crear Pedido

Respuesta

Comprar Etiquetas

Cuerpo de Solicitud

Ejemplo de Solicitud

Respuesta

Respuesta de Saldo Insuficiente

Seguimiento

Parámetros de Ruta

Ejemplo de Solicitud

Respuesta

Webhooks

Eventos Disponibles

Registrar Webhook - Cuerpo de Solicitud

Ejemplo: Registrar Webhook

Respuesta

Verificación de Firma de Webhook

Ejemplo de Payload de Webhook

Carrito de Compras

Su carrito está vacío

Documentación API

Autenticación

Ejemplo de Solicitud

Saldo de Cuenta

Parámetros de Consulta

Ejemplo de Solicitud

Respuesta

Verificación de Dirección

Cuerpo de Solicitud

Ejemplo de Solicitud

Respuesta

Tarifas de Envío

Cuerpo de Solicitud

Objeto de Dirección

Objeto de Paquete

Objeto CustomsInfo

Objeto CustomsItem

Ejemplo de Solicitud

Respuesta

Ejemplo de Envío Internacional

Crear Pedido

Listar Pedidos - Parámetros de Consulta

Crear Pedido - Cuerpo de Solicitud

Objeto OrderItem

Ejemplo: Crear Pedido

Respuesta

Comprar Etiquetas

Cuerpo de Solicitud

Ejemplo de Solicitud

Respuesta

Respuesta de Saldo Insuficiente

Seguimiento

Parámetros de Ruta

Ejemplo de Solicitud

Respuesta

Webhooks