Remessas

A API de remessas permite gerenciar as remessas dos pedidos da sua loja. Uma remessa é o registro de que uma parte do pedido, ou o pedido inteiro, foi entregue a uma transportadora, em geral com um código de rastreamento. Você pode criar remessas, atualizar as existentes e acompanhar o status de cada uma.

Todas as chamadas usam as credenciais HTTP Basic de um administrador ($EMAIL:$API_KEY) e o endereço da sua loja ($BASE_URL).

Como funciona

Uma remessa começa em processamento, é entregue à transportadora e termina como entregue, ou como falha/devolvida.

Códigos de status da remessa

Conceitos principais

Listar remessas

O GET /api/shipments/ retorna uma lista de todas as remessas. O endpoint aceita paginação e filtros, para ajudar você a encontrar remessas específicas.

A resposta de exemplo da listagem:

{
  "shipments": [
    {
      "shipment_id": "12",
      "order_id": "145",
      "shipping_method": "Standard Shipping",
      "tracking_number": "1Z999AA10123456784",
      "status": "S",
      "timestamp": "1649851200"
    },
    {
      "shipment_id": "13",
      "order_id": "146",
      "shipping_method": "Express Shipping",
      "tracking_number": "1Z999AA10123456785",
      "status": "P",
      "timestamp": "1649937600"
    }
  ],
  "params": {
    "page": 1,
    "items_per_page": 10,
    "total_items": 2
  }
}

Consultar uma remessa

O GET /api/shipments/{shipment_id}/ retorna os detalhes de uma remessa específica, pelo id. Além dos dados da listagem, a resposta traz a transportadora, os itens e os comentários.

{
  "shipment_id": "12",
  "order_id": "145",
  "shipping_method": "Standard Shipping",
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "status": "S",
  "timestamp": "1649851200",
  "items": [
    {
      "item_id": "458",
      "product_id": "123",
      "product_name": "Premium Widget",
      "amount": "2"
    },
    {
      "item_id": "459",
      "product_id": "124",
      "product_name": "Widget Accessories",
      "amount": "1"
    }
  ],
  "comments": "Handle with care"
}

Criar uma remessa

O POST /api/shipments/ cria uma remessa nova para um pedido. O corpo da requisição tem estes parâmetros.

Um exemplo de requisição:

{
  "order_id": "145",
  "shipping_method": "Standard Shipping",
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "items": [
    {
      "item_id": "458",
      "amount": "2"
    },
    {
      "item_id": "459",
      "amount": "1"
    }
  ],
  "comments": "Handle with care"
}

Atualizar uma remessa

O PUT /api/shipments/{shipment_id}/ atualiza uma remessa existente. Um exemplo de requisição que registra o novo código de rastreamento, marca a remessa como entregue e acrescenta um comentário:

{
  "tracking_number": "1Z999AA10123456789",
  "status": "D",
  "comments": "Delivered to front door"
}

Endpoints

Erros comuns

• Criar uma remessa com itens que não fazem parte do pedido. A página de campos diz que todos os produtos citados na remessa precisam fazer parte do pedido informado.
• Deixar o código de rastreamento de fora. Ele é opcional, mas a página de campos recomenda sempre informá-lo, para que você e seus clientes acompanhem a entrega.
• Tratar a exclusão como cancelamento. Ela só remove o registro da remessa, e a entrega em si precisa ser cancelada com a transportadora.
• Enviar um campo que não está na tabela de campos. Ele é ignorado.

Próximos passos