> For the complete documentation index, see [llms.txt](https://skyhub-english.gitbook.io/skyhub-api-english/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://skyhub-english.gitbook.io/skyhub-api-english/skyhub-api-guides/order-integration.md).
# 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
|
{% hint style="warning" %}
**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.
{% endhint %}
## 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
{% hint style="warning" %}
**Note:** Marketplace can set the order status to "canceled" if the customer gives up the purchase or in other similar cases.
{% endhint %}
The statuses below are updated from the merchant to the marketplace
* Delivered to carrier
* Delivered to the customer
* Canceled
{% hint style="warning" %}
Note: The merchant can cancel the order when it can\`t be fulfilld.
{% endhint %}
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.
{% hint style="warning" %}
Note: Skyhub already creates the required statuses for your order integration, however if you need to, you can create new statuses.
{% endhint %}
## 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:
\
{% hint style="warning" %}
**Note:** The key field must contain the 44 digits of the NFE.
{% endhint %}
### 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.
{% hint style="danger" %}
These operations are not available in accounts in production.
{% endhint %}
#### 1 - Create test request (NEW status)
```aspnet
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.
{% hint style="info" %}
**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.
{% endhint %}
###
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://skyhub-english.gitbook.io/skyhub-api-english/skyhub-api-guides/order-integration.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.