REST API

Documentação API

Integre etiquetas de envio em sua aplicação com nossa poderosa API REST. Obtenha tarifas em tempo real, crie etiquetas e rastreie envios programaticamente.

Autenticação

Todas as requisições API requerem autenticação usando sua chave e segredo API. Inclua estes cabeçalhos em cada requisição:

headers

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

Aviso de Segurança

Mantenha seu segredo API seguro. Nunca o exponha em código do lado do cliente ou repositórios públicos.

Exemplo de Requisição

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 da Conta

Verifique seus saldos de carteira crypto e histórico de transações. A API usa sua carteira crypto (BTC, LTC, LTCT) para pagamentos.

GET

/api/v1/account/balance

Obter saldos e transações da carteira crypto

Parâmetros de Consulta

Parâmetro	Tipo	Obrigatório	Descrição
includeTransactions	`boolean`	Opcional	Incluir histórico de transações
currency	`string`	Opcional	Filtrar transações por moeda (BTC, LTC, LTCT)
limit	`number`	Opcional	Número de transações (padrão: 20, máx: 100)

Exemplo de Requisição

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"

Resposta

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
    }
  }
}

Adicionar Fundos

Para adicionar fundos à sua carteira, visite a página Minha Carteira e deposite usando BTC, LTC ou LTCT (testnet).

Verificação de Endereço

Verifique e padronize endereços de envio para garantir a entregabilidade.

POST

/api/v1/shipping/verify-address

Verificar e corrigir um endereço de envio

Corpo da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
address	`Address`	Obrigatório	Endereço a verificar
strict	`boolean`	Opcional	Ativar modo de verificação estrita

Exemplo de Requisição

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"
    }
  }'

Resposta

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 Envio

Obtenha tarifas de envio em tempo real de múltiplas transportadoras incluindo USPS, UPS, FedEx e DHL.

POST

/api/v1/shipping/rates

Calcular tarifas de envio para um pacote

Corpo da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
fromAddress	`Address`	Obrigatório	Objeto de endereço do remetente
toAddress	`Address`	Obrigatório	Objeto de endereço do destinatário
packageDetails	`Package`	Obrigatório	Dimensões e peso do pacote
carriers	`string[]`	Opcional	Filtrar por transportadoras específicas (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Opcional	Obrigatório para envios internacionais

Objeto de Endereço

Parâmetro	Tipo	Obrigatório	Descrição
name	`string`	Obrigatório	Nome completo
company	`string`	Opcional	Nome da empresa
street1	`string`	Obrigatório	Linha de endereço 1
street2	`string`	Opcional	Linha de endereço 2
city	`string`	Obrigatório	Cidade
state	`string`	Obrigatório	Código de estado/província
zip	`string`	Obrigatório	CEP/Código postal
country	`string`	Obrigatório	Código do país (US, CA, etc.)
phone	`string`	Opcional	Número de telefone
email	`string`	Opcional	Endereço de e-mail

Objeto de Pacote

Parâmetro	Tipo	Obrigatório	Descrição
length	`number`	Obrigatório	Comprimento em polegadas
width	`number`	Obrigatório	Largura em polegadas
height	`number`	Obrigatório	Altura em polegadas
weight	`number`	Obrigatório	Peso em onças

Objeto CustomsInfo

Envios Internacionais

Obrigatório ao enviar internacionalmente (quando fromAddress.country difere de toAddress.country).

Parâmetro	Tipo	Obrigatório	Descrição
contents_type	`string`	Obrigatório	Tipo de conteúdo: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Opcional	Obrigatório quando contents_type é 'other'
customs_certify	`boolean`	Obrigatório	Deve ser true - certifica a precisão da declaração
customs_signer	`string`	Obrigatório	Nome da pessoa certificando a declaração aduaneira
eel_pfc	`string`	Obrigatório	Código de isenção de exportação (use 'NOEEI 30.37(a)' para envios abaixo de $2.500)
non_delivery_option	`string`	Obrigatório	O que fazer se não entregue: 'return' ou 'abandon'
restriction_type	`string`	Obrigatório	Tipo de restrição: 'none', 'other', 'quarantine', ou 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Opcional	Obrigatório quando restriction_type não é 'none'
customs_items	`CustomsItem[]`	Obrigatório	Array de itens sendo enviados (1-100 itens)

Objeto CustomsItem

Parâmetro	Tipo	Obrigatório	Descrição
description	`string`	Obrigatório	Descrição detalhada do item
quantity	`number`	Obrigatório	Quantidade de itens (mínimo: 1)
value	`number`	Obrigatório	Valor em USD (deve ser maior que 0)
weight	`number`	Obrigatório	Peso em onças (deve ser maior que 0)
origin_country	`string`	Obrigatório	Código de país de 2 letras (ex.: 'US', 'CN')
hs_tariff_number	`string`	Obrigatório	Código tarifário HS de 6-10 dígitos

Exemplo de Requisição

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
    }
  }'

Resposta

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"
      }
    ]
  }
}

Exemplo de Envio Internacional

Para envios internacionais, inclua o objeto customsInfo com declarações de itens:

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"
        }
      ]
    }
  }'

Criar Pedido

Crie e gerencie pedidos de envio. Pedidos contêm um ou mais itens de etiquetas de envio.

GET

/api/v1/orders

Listar todos os pedidos

POST

/api/v1/orders

Criar um novo pedido

GET

/api/v1/orders/{id}

Obter detalhes do pedido

Listar Pedidos - Parâmetros de Consulta

Parâmetro	Tipo	Obrigatório	Descrição
limit	`number`	Opcional	Número de resultados (padrão: 50, máx: 100)
offset	`number`	Opcional	Deslocamento de paginação

Criar Pedido - Corpo da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
items	`OrderItem[]`	Obrigatório	Array de itens do pedido
email	`string`	Opcional	E-mail do cliente
externalReference	`string`	Opcional	Seu ID de referência

Objeto OrderItem

API Simplificada

Apenas shipmentId e rateId são obrigatórios. Endereços, detalhes do pacote e informações aduaneiras são automaticamente extraídos do envio.

Parâmetro	Tipo	Obrigatório	Descrição
shipmentId	`string`	Obrigatório	ID de envio do endpoint de tarifas
rateId	`string`	Obrigatório	ID de tarifa do endpoint de tarifas

Exemplo: Criar 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"
  }'

Resposta

json

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

Comprar Etiquetas

Compre etiquetas de envio para todos os itens de um pedido. Etiquetas são compradas usando seu saldo de carteira crypto (BTC, LTC ou LTCT).

POST

/api/v1/labels/purchase

Comprar etiquetas de envio para um pedido

Corpo da Requisição

Pagamento Crypto

A API converterá o custo da etiqueta em USD para crypto nas taxas atuais. Você deve ter saldo suficiente (incluindo 10% de margem para flutuações de preço).

Parâmetro	Tipo	Obrigatório	Descrição
orderId	`string`	Obrigatório	ID do pedido para comprar etiquetas
currency	`string`	Opcional	Moeda crypto para pagamento (BTC, LTC, LTCT). Se não especificado, seleciona automaticamente a primeira moeda com saldo suficiente.

Exemplo de Requisição

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"
  }'

Resposta

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

Se o saldo da sua carteira estiver muito baixo, a API retorna um status 402 com a quantidade de crypto necessária.

Resposta 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"
}

Rastreamento

Rastreie envios usando o código de rastreamento das etiquetas compradas.

GET

/api/v1/tracking/{code}

Obter informações de rastreamento

Parâmetros de Caminho

Parâmetro	Tipo	Obrigatório	Descrição
code	`string`	Obrigatório	Código de rastreamento

Exemplo de Requisição

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"

Resposta

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

Receba notificações em tempo real quando eventos ocorrerem, como criação de etiquetas ou atualizações de rastreamento.

GET

/api/v1/webhooks

Listar webhooks registrados

POST

/api/v1/webhooks

Registrar um novo webhook

GET

/api/v1/webhooks/{id}

Obter detalhes do webhook

DELETE

/api/v1/webhooks/{id}

Excluir um webhook

Eventos Disponíveis

label.created

Quando uma etiqueta é comprada com sucesso

label.failed

Quando a geração de etiqueta falha

Registrar Webhook - Corpo da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
webhookUrl	`string`	Obrigatório	URL para receber eventos webhook
events	`string[]`	Obrigatório	Array de tipos de eventos para assinar

Exemplo: 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"]
  }'

Resposta

json

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

Verificação de Assinatura de Webhook

Cada webhook inclui um cabeçalho de assinatura para verificação. Verifique a assinatura 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)
  );
}

Exemplo 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

Documentação API

Integre etiquetas de envio em sua aplicação com nossa poderosa API REST. Obtenha tarifas em tempo real, crie etiquetas e rastreie envios programaticamente.

Autenticação

Todas as requisições API requerem autenticação usando sua chave e segredo API. Inclua estes cabeçalhos em cada requisição:

headers

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

Aviso de Segurança

Mantenha seu segredo API seguro. Nunca o exponha em código do lado do cliente ou repositórios públicos.

Exemplo de Requisição

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 da Conta

Verifique seus saldos de carteira crypto e histórico de transações. A API usa sua carteira crypto (BTC, LTC, LTCT) para pagamentos.

GET

/api/v1/account/balance

Obter saldos e transações da carteira crypto

Parâmetros de Consulta

Parâmetro	Tipo	Obrigatório	Descrição
includeTransactions	`boolean`	Opcional	Incluir histórico de transações
currency	`string`	Opcional	Filtrar transações por moeda (BTC, LTC, LTCT)
limit	`number`	Opcional	Número de transações (padrão: 20, máx: 100)

Exemplo de Requisição

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"

Resposta

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
    }
  }
}

Adicionar Fundos

Para adicionar fundos à sua carteira, visite a página Minha Carteira e deposite usando BTC, LTC ou LTCT (testnet).

Verificação de Endereço

Verifique e padronize endereços de envio para garantir a entregabilidade.

POST

/api/v1/shipping/verify-address

Verificar e corrigir um endereço de envio

Corpo da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
address	`Address`	Obrigatório	Endereço a verificar
strict	`boolean`	Opcional	Ativar modo de verificação estrita

Exemplo de Requisição

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"
    }
  }'

Resposta

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 Envio

Obtenha tarifas de envio em tempo real de múltiplas transportadoras incluindo USPS, UPS, FedEx e DHL.

POST

/api/v1/shipping/rates

Calcular tarifas de envio para um pacote

Corpo da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
fromAddress	`Address`	Obrigatório	Objeto de endereço do remetente
toAddress	`Address`	Obrigatório	Objeto de endereço do destinatário
packageDetails	`Package`	Obrigatório	Dimensões e peso do pacote
carriers	`string[]`	Opcional	Filtrar por transportadoras específicas (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Opcional	Obrigatório para envios internacionais

Objeto de Endereço

Parâmetro	Tipo	Obrigatório	Descrição
name	`string`	Obrigatório	Nome completo
company	`string`	Opcional	Nome da empresa
street1	`string`	Obrigatório	Linha de endereço 1
street2	`string`	Opcional	Linha de endereço 2
city	`string`	Obrigatório	Cidade
state	`string`	Obrigatório	Código de estado/província
zip	`string`	Obrigatório	CEP/Código postal
country	`string`	Obrigatório	Código do país (US, CA, etc.)
phone	`string`	Opcional	Número de telefone
email	`string`	Opcional	Endereço de e-mail

Objeto de Pacote

Parâmetro	Tipo	Obrigatório	Descrição
length	`number`	Obrigatório	Comprimento em polegadas
width	`number`	Obrigatório	Largura em polegadas
height	`number`	Obrigatório	Altura em polegadas
weight	`number`	Obrigatório	Peso em onças

Objeto CustomsInfo

Envios Internacionais

Obrigatório ao enviar internacionalmente (quando fromAddress.country difere de toAddress.country).

Parâmetro	Tipo	Obrigatório	Descrição
contents_type	`string`	Obrigatório	Tipo de conteúdo: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Opcional	Obrigatório quando contents_type é 'other'
customs_certify	`boolean`	Obrigatório	Deve ser true - certifica a precisão da declaração
customs_signer	`string`	Obrigatório	Nome da pessoa certificando a declaração aduaneira
eel_pfc	`string`	Obrigatório	Código de isenção de exportação (use 'NOEEI 30.37(a)' para envios abaixo de $2.500)
non_delivery_option	`string`	Obrigatório	O que fazer se não entregue: 'return' ou 'abandon'
restriction_type	`string`	Obrigatório	Tipo de restrição: 'none', 'other', 'quarantine', ou 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Opcional	Obrigatório quando restriction_type não é 'none'
customs_items	`CustomsItem[]`	Obrigatório	Array de itens sendo enviados (1-100 itens)

Objeto CustomsItem

Parâmetro	Tipo	Obrigatório	Descrição
description	`string`	Obrigatório	Descrição detalhada do item
quantity	`number`	Obrigatório	Quantidade de itens (mínimo: 1)
value	`number`	Obrigatório	Valor em USD (deve ser maior que 0)
weight	`number`	Obrigatório	Peso em onças (deve ser maior que 0)
origin_country	`string`	Obrigatório	Código de país de 2 letras (ex.: 'US', 'CN')
hs_tariff_number	`string`	Obrigatório	Código tarifário HS de 6-10 dígitos

Exemplo de Requisição

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
    }
  }'

Resposta

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"
      }
    ]
  }
}

Exemplo de Envio Internacional

Para envios internacionais, inclua o objeto customsInfo com declarações de itens:

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"
        }
      ]
    }
  }'

Criar Pedido

Crie e gerencie pedidos de envio. Pedidos contêm um ou mais itens de etiquetas de envio.

GET

/api/v1/orders

Listar todos os pedidos

POST

/api/v1/orders

Criar um novo pedido

GET

/api/v1/orders/{id}

Obter detalhes do pedido

Listar Pedidos - Parâmetros de Consulta

Parâmetro	Tipo	Obrigatório	Descrição
limit	`number`	Opcional	Número de resultados (padrão: 50, máx: 100)
offset	`number`	Opcional	Deslocamento de paginação

Criar Pedido - Corpo da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
items	`OrderItem[]`	Obrigatório	Array de itens do pedido
email	`string`	Opcional	E-mail do cliente
externalReference	`string`	Opcional	Seu ID de referência

Objeto OrderItem

API Simplificada

Apenas shipmentId e rateId são obrigatórios. Endereços, detalhes do pacote e informações aduaneiras são automaticamente extraídos do envio.

Parâmetro	Tipo	Obrigatório	Descrição
shipmentId	`string`	Obrigatório	ID de envio do endpoint de tarifas
rateId	`string`	Obrigatório	ID de tarifa do endpoint de tarifas

Exemplo: Criar 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"
  }'

Resposta

json

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

Comprar Etiquetas

Compre etiquetas de envio para todos os itens de um pedido. Etiquetas são compradas usando seu saldo de carteira crypto (BTC, LTC ou LTCT).

POST

/api/v1/labels/purchase

Comprar etiquetas de envio para um pedido

Corpo da Requisição

Pagamento Crypto

A API converterá o custo da etiqueta em USD para crypto nas taxas atuais. Você deve ter saldo suficiente (incluindo 10% de margem para flutuações de preço).

Parâmetro	Tipo	Obrigatório	Descrição
orderId	`string`	Obrigatório	ID do pedido para comprar etiquetas
currency	`string`	Opcional	Moeda crypto para pagamento (BTC, LTC, LTCT). Se não especificado, seleciona automaticamente a primeira moeda com saldo suficiente.

Exemplo de Requisição

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"
  }'

Resposta

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

Se o saldo da sua carteira estiver muito baixo, a API retorna um status 402 com a quantidade de crypto necessária.

Resposta 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"
}

Rastreamento

Rastreie envios usando o código de rastreamento das etiquetas compradas.

GET

/api/v1/tracking/{code}

Obter informações de rastreamento

Parâmetros de Caminho

Parâmetro	Tipo	Obrigatório	Descrição
code	`string`	Obrigatório	Código de rastreamento

Exemplo de Requisição

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"

Resposta

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

Receba notificações em tempo real quando eventos ocorrerem, como criação de etiquetas ou atualizações de rastreamento.

GET

/api/v1/webhooks

Listar webhooks registrados

POST

/api/v1/webhooks

Registrar um novo webhook

GET

/api/v1/webhooks/{id}

Obter detalhes do webhook

DELETE

/api/v1/webhooks/{id}

Excluir um webhook

Eventos Disponíveis

label.created

Quando uma etiqueta é comprada com sucesso

label.failed

Quando a geração de etiqueta falha

Registrar Webhook - Corpo da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
webhookUrl	`string`	Obrigatório	URL para receber eventos webhook
events	`string[]`	Obrigatório	Array de tipos de eventos para assinar

Exemplo: 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"]
  }'

Resposta

json

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

Verificação de Assinatura de Webhook

Cada webhook inclui um cabeçalho de assinatura para verificação. Verifique a assinatura 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)
  );
}

Exemplo 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"
    }
  }
}

Documentação API

Autenticação

Exemplo de Requisição

Saldo da Conta

Parâmetros de Consulta

Exemplo de Requisição

Resposta

Verificação de Endereço

Corpo da Requisição

Exemplo de Requisição

Resposta

Tarifas de Envio

Corpo da Requisição

Objeto de Endereço

Objeto de Pacote

Objeto CustomsInfo

Objeto CustomsItem

Exemplo de Requisição

Resposta

Exemplo de Envio Internacional

Criar Pedido

Listar Pedidos - Parâmetros de Consulta

Criar Pedido - Corpo da Requisição

Objeto OrderItem

Exemplo: Criar Pedido

Resposta

Comprar Etiquetas

Corpo da Requisição

Exemplo de Requisição

Resposta

Resposta de Saldo Insuficiente

Rastreamento

Parâmetros de Caminho

Exemplo de Requisição

Resposta

Webhooks

Eventos Disponíveis

Registrar Webhook - Corpo da Requisição

Exemplo: Registrar Webhook

Resposta

Verificação de Assinatura de Webhook

Exemplo de Payload de Webhook

Carrinho de Compras

Seu carrinho está vazio

Documentação API

Autenticação

Exemplo de Requisição

Saldo da Conta

Parâmetros de Consulta

Exemplo de Requisição

Resposta

Verificação de Endereço

Corpo da Requisição

Exemplo de Requisição

Resposta

Tarifas de Envio

Corpo da Requisição

Objeto de Endereço

Objeto de Pacote

Objeto CustomsInfo

Objeto CustomsItem

Exemplo de Requisição

Resposta

Exemplo de Envio Internacional

Criar Pedido

Listar Pedidos - Parâmetros de Consulta

Criar Pedido - Corpo da Requisição

Objeto OrderItem

Exemplo: Criar Pedido

Resposta

Comprar Etiquetas

Corpo da Requisição

Exemplo de Requisição

Resposta

Resposta de Saldo Insuficiente

Rastreamento

Parâmetros de Caminho

Exemplo de Requisição

Resposta

Webhooks