Atualização de Pedidos

Nesta seção mostraremos a estrutura e exemplos de requisições para atualização de status de pedidos

POST - Notificando o andamento do pedido

Como citado na guia Criação e Aprovação de Pedido Teste, em ambiente de homologação a aprovação de um pedido deve ser realizada via API. Em ambiente de produção, a aprovação ocorre no marketplace e a atualização desse status é encaminhada para a API, para consumo da plataforma/ERP.

Em ambos os casos (tanto para o ambiente de teste quanto para o de produção), após ocorrer a aprovação do pagamento é necessário prosseguir com o ciclo de vida do pedido, onde serão informados os dados de faturamento (NFe), dados de rastreamento da entrega e a notificação da entrega ao cliente final.

Para todas as requisições apresentadas a seguir serão utilizados os headers padronizados na API e descritos abaixo:

Request headers:

Key	Value
X-User-Email	email_de_usuario
X-Api-Key	token_de_integracao de sua conta SkyHub
X-Accountmanager-Key	token_account único de cada Plataforma/ERP
Accept	application/json
Content-Type	application/json

O code nas requisições apresentadas deverá ser substituído pelo código completo do pedido, visualizado após o consumo.

Os status utilizados nesta página para exemplificar a atualização de um pedido são aqueles padronizados na API. Os mesmos podem ser consultados na seção Status de Pedidos.

Caso a conta tenha cadastrado outros status, é importante a utilização dos criados.

A utilização de um status que não existe na conta retornará erro 422.

Atualizar para faturado (INVOICED)

A forma padrão de faturar um pedido é através do envio da chave da nota fiscal, ou seja, envio dos 44 dígitos da NFe. O faturamento através do envio da chave da NFe deve ser utilizado para pedidos Correios e sua requisição consiste em um POST contendo os headers apresentados acima para o endpoint:

https://api.skyhub.com.br/orders/{code}/invoice

Pedidos gerados para o serviço Direct devem seguir as orientações do artigo Faturamento Pedido - Americanas Entrega Direct.

Request body:

{
    "status": "order_invoiced",
    "invoice": {
        "key": "99999999999999999999999999999999999999999999",
        "volume_qty": 1,
        "issue_date": "AAAA-MM-DDTHH:MM:SS-03:00"
    }
}

Os campos issue_date e volume_qty são opcionais na requisição apresentada.

Caso opte por não enviá-los, é importante estar ciente de que a API assumirá para estes campos os seguintes valores:

• issue_date: Serão assumidos data e hora do momento em que a API enviar a requisição de faturamento ao marketplace;

• volume_qty: Por padrão, se a API não receber este campo será assumido para o mesmo o valor igual a 1 (um).

Não devem ser solicitadas mais etiquetas do que as necessárias para a entrega.

Caso um pedido contenha 1 (uma) unidade, por exemplo, obrigatoriamente deverá ser informado o valor 1 para o campo volume_qty.

Example request:

curl --location --request POST 'https://api.skyhub.com.br/orders/Lojas Americanas-1000000000000/invoice' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "status": "order_invoiced",
    "invoice": {
        "key": "99999999999999999999999999999999999999999999",
        "volume_qty": 1,
        "issue_date": "2023-03-10T12:30:00-03:00"
    }
}'

Response esperado:

204 [Success] - No content

Atualizar para enviado para a transportadora (SHIPPED)

Após o faturamento, o pedido que for entregue para a transportadora deverá ter o seu status atualizado via API. Na operação de atualização para o status SHIPPED são informados os dados de rastreamento da entrega, como tipo de envio, código de rastreio, URL para rastreamento, dentre outros.

A requisição para atualização do status SHIPPED consiste em um POST contendo os headers apresentados no início desta página para o endpoint:

https://api.skyhub.com.br/orders/{code}/shipments

Request body:

{
  "status": "order_shipped",
  "shipment": {
    "code": "{code}",
    "delivered_carrier_date": "AAAA-MM-DDTHH:MM:SS-03:00",
    "items": [
      {
        "sku": "{sku}",
        "qty": 1
      }
    ],
    "track": {
      "code": "{Código de rastreio}",
      "carrier": "Correios",
      "method": "SEDEX",
      "url": "www.correios.com.br"
    }
  }
}

Para atualização do status "shipped" é necessário informar o SKU adquirido na compra. Isto é, caso o pedido tenha sido realizado para um produto que contém variações, a atualização para o shipped requer que seja informado o SKU da variação e não do produto pai/agrupador.

Example request:

curl --location --request POST 'https://api.skyhub.com.br/orders/Lojas Americanas-1000000000000/shipments' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "status": "order_shipped",
  "shipment": {
    "code": "Lojas Americanas-1000000000000",
    "delivered_carrier_date": "2023-03-10T17:00:00-03:00",
    "items": [
      {
        "sku": "2023001",
        "qty": 1
      }
    ],
    "track": {
      "code": "BR1122334455",
      "carrier": "Correios",
      "method": "SEDEX",
      "url": "www.correios.com.br"
    }
  }
}'

Response esperado:

204 [Success] - No content

Atualizar para entregue ao cliente (DELIVERED)

Quando o pedido chega ao seu destino, o status da entrega deve ser enviado via API para que o fluxo seja finalizado.

A atualização para o status DELIVERED consiste em um POST contendo os headers apresentados no início desta página para o endpoint:

https://api.skyhub.com.br/orders/{code}/delivery

Request body:

{
    "status": "complete",
    "delivered_date": "DD/MM/AAAA"
}

Importante encaminhar a data correta no campo delivered_date.

Uma vez que esta informação não for devidamente enviada, a entrega assumirá a data/hora em que a atualização do status for encaminhada da API para o marketplace.

Example request:

curl --location --request POST 'https://api.skyhub.com.br/orders/Lojas Americanas-1000000000000/delivery' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "status": "complete",
    "delivered_date": "13/03/2023"
}'

Response esperado:

204 [Success] - No content

Outros status

O ciclo de vida comum para um pedido consiste em sua criação (NEW), aprovação (APPROVED), faturamento (INVOICED), envio para a transportadora (SHIPPED) e entrega ao cliente (DELIVERED), porém podem ocorrer eventualidades durante o fluxo, como o cancelamento (CANCEL) ou um atraso na entrega (SHIPMENT_EXCEPTION).

Cancelar pedido (CANCEL)

Em um ambiente de produção, o cancelamento de um pedido pode ser realizado pelo cliente responsável pela compra ou pelo seller (lojista).

Em ambiente de teste, é possível simular o cancelamento e para isto deve ser executado um POST contendo os headers apresentados no início desta página para o endpoint:

https://api.skyhub.com.br/orders/{code}/cancel

Request body:

{
    "status": "order_canceled"
}

Example request:

curl --location --request POST 'https://api.skyhub.com.br/orders/Lojas Americanas-1200000000002/cancel' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "status": "order_canceled"
}'

Response esperado:

204 [Success] - No content

Exceção de entrega (SHIPMENT_EXCEPTION)

A exceção de entrega se refere a quando o transporte de uma mercadoria apresentou quaisquer problemas. A notificação deste problema via API é realizada através de um POST contendo os headers apresentados no início desta página para o endpoint:

https://api.skyhub.com.br/orders/{code}/shipment_exception

Request body:

{
    "shipment_exception": {
        "occurrence_date": "AAAA-MM-DDTHH:MM:SS+00:00",
        "observation": "Temporary delay"
    }
}

Example request:

curl --location --request POST 'https://api.skyhub.com.br/orders/Lojas Americanas-1300000000003/shipment_exception' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "shipment_exception": {
        "occurrence_date": "2023-03-10T19:30:00+00:00",
        "observation": "Problemas com a transportadora selecionada"
    }
}'

Response esperado:

204 [Success] - No content