Order integration and its statuses

What are order statuses?

The status of orders represent the points through which orders pass through, from purchase to customer delivery.

Quais os status dos pedidos cadastrados na Skyhub?

Code

Label

Type

Description

book_product

NEW - Pagamento Pendente (SkyHub)

NEW

Marketplace orders without payment confirmation. This information is provided by the marketplace itself

payment_received

Aprovado (SkyHub)

APPROVED

Marketplace orders with payment confirmed. This information is provided by the marketplace itself

order_canceled

Cancelado (SkyHub)

CANCELED

Canceled is the status that the order receives when it has been canceled, either because the customer has given up the purchase or the merchant no longer has the inventory to meet the order.

order_shipped

Pedido Enviado (SkyHub)

SHIPPED

When the order was delivered to carrier. This information is provided by seller

complete

Completo (entregue) (SkyHub)

DELIVERED

Orders that have already been delivered to the end customer. This information is provided by seller

shipment_exception

Exceção de Entrega (SkyHub)

SHIPMENT_EXCEPTION

This status is applied to the order when for some reason the delivery was not performed.

order_invoiced

Pagamento Faturado (SkyHub)

INVOICED

Orders that have already been billed by the seller. This information is provided by the merchent

Note: If the customer makes the payment and the merchant no longer has the product in stock, the merchant can decide whether or not to fulfill that request, if you want to fulfill the request, you need to include inventory.

Is it possible to check statuses via API?

Yes it is, you just need to make a GET request to this endpoint: http://api.skyhub.com.br/statuses

What constitutes the order status?

The order status has 3 fields in the API:

Field

Description

Code

Status code used to update the order

Label

Skyhub status nomenclature

Type

Merchant status related to Skyhub status

Inside the Skyhub paltaform, "Skyhub" > "Order Status"

  • Code field = #

  • Label field = Status

  • Type field = Tipo

See bellow:

Order update

At the time the order is placed the first order status updates come from the marketplace, these statuses are:

  • Pending payment

  • Payment accept

  • canceled

Note: Marketplace can set the order status to "canceled" if the customer gives up the purchase or in other similar cases.

The statuses below are updated from the merchant to the marketplace

  • Delivered to carrier

  • Delivered to the customer

  • Canceled

Note: The merchant can cancel the order when it can`t be fulfilld.

The statuses can be checked on the Skyhub portal by following the path in the side menu "SkyHub" > "Status dos Pedidos"

Skyhub performs a correlation between "Status" and "Tipo" column

Example, "Status": Pagamento Pendente (Skyhub) => "Tipo": Pagamento Pendente

This feature exists because you can create order status within Skyhub. If you create an new order status, it is essencial to tell Skyhub what are meaning of each new status you have created.

Note: Skyhub already creates the required statuses for your order integration, however if you need to, you can create new statuses.

How do I change order status?

The endpoint used to perform a chance at the order status change according to the status you want to update, see examples.

Update status to INVOICED (Pagamento Faturado (SkyHub))

After the Marketplace confirms that the order had its payment confirmed the merchant need to issue the electronic invoice (NFE), below the sample request:

<FALTA A IMAGEM ... JÁ SOLICITEI PARA O HIDEAKI>

Note: The key field must contain the 44 digits of the NFE.

Update status to SHIPPED (Pedido Enviado (SkyHub))

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

Update status to DELIVERED (Completo (entregue) (SkyHub))

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

Update status to CANCELED (Cancelado (SkyHub))

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

Update status to SHIPMENT_EXCEPTION (Exceção de Entrega (SkyHub))

POST http://api.skyhub.com.br/orders/{order-id}/shiptment_exception

Creating / approving test requests

For development/sandbox accounts it is possible to create and approve orders.

These operations are not available in accounts in production.

1 - Create test request (NEW status)

curl --request POST \
--url https://api.skyhub.com.br/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-User-Email: your@email.com' \
--header 'X-Api-Key: YOUR API KEY HERE' \
--header 'X-Accountmanager-Key: token_account' \
--data '{"order": {"channel": "Marketplace","status": "book_product","items": [{"id": "teste002-azul","qty": 1}],"customer": {"name": "Nome do comprador","email": "comprador@exemplo.com.br","date_of_birth": "1995-01-01","gender": "male","vat_number": "12312312309","phones": ["8899999999"]},"billing_address": {"street": "Rua de teste","number": 1234,"detail": "Ponto de referência teste","neighborhood": "Bairro teste","city": "Cidade de teste","region": "UF","country": "BR","postcode": "90000000"},"shipping_address": {"street": "Rua de teste","number": 1234,"detail": "Ponto de referência teste","neighborhood": "Bairro teste","city": "Cidade de teste","region": "UF","country": "BR","postcode": "90000000"},"shipping_method": "Transportadora","estimated_delivery": "2015-01-10","shipping_cost": 5.0,"interest": 0.0}}'

2 - Approve test request (APPROVED status)

curl --request POST \
--url https://api.skyhub.com.br/orders/Marketplace-000000001/approval \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-User-Email: your@email.com' \
--header 'X-Api-Key: YOUR API KEY HERE' \
--header 'X-Accountmanager-Key: token_account' \
--data '{"status":"payment_received"}'

Pay attention to the generated code for the created order and replace in the example url.

You must consume all orders with NEW status, in order to reserve product and avoid stock breaks.

Why is it mandatory?

To avoid having stock divergence between "Available" and "Committed" stock.

If you do not consume the orders what can happen?

Selling products without inventory, since the stockpile functionality does not exist on the SkyHub platform, we always consider the quantity of stock received as the Available Stock.

So if you do not reserve the stock, the information sent to the Marketplace will be wrong.

Please note:

  • Platforms that do not conform to this business rule may bear the seller's prejudice.

  • Only the available stock should be sent to SkyHub.