# Consulta de Pedidos

## GET - Consultando os pedidos

Assim como o recurso de produtos, a API oferece um endpoint para a consulta dos pedidos existentes na conta.

Para realizar a consulta de todos os pedidos via API é preciso utilizar o método **GET**, preenchendo os headers padronizados para o endpoint abaixo: 

```
https://api.skyhub.com.br/orders
```

#### **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                            |

#### **Example request:**

```
curl --location --request GET 'https://api.skyhub.com.br/orders' \
--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'
```

#### **Response esperado:**

{% hint style="success" %}
200 \[Success] - OK: Como resposta haverá um body contendo todos os pedidos da conta:
{% endhint %}

```
{
    "orders": [
        {
            "channel": "AMERICANAS",
            "calculation_type": "b2wentregadirect",
            "shipping_carrier": "Courier",
            "invoices": [...],
            (...)
            "tags": [],
            "expedition_limit_date": null,
            "code": "Lojas Americanas-1000000000000-01",
            (...)
            "sync_sale_system": "Teste",
            (...)
            "available_to_sync": true,
            (...)
            "status": {
                "type": "NEW",
                "label": "Pagamento Pendente (new) (SkyHub)",
                "code": "book_product"
            }
        }
    (...) /// Será disponibilizado o array com os detalhes de cada pedido da conta
    ],
"total": 122
}
```

### Consultando um pedido

A consulta de um pedido em específico se dá através da utilização dos [headers](#request-headers) padronizados na API a partir do **GET** para o endpoint:

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

#### **Example request:**

```
curl --location --request GET 'https://api.skyhub.com.br/orders/Lojas Americanas-1000000000000-01' \
--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'
```

#### **Response esperado:**

{% hint style="success" %}
200 \[Success] - OK: Em resposta serão apresentados os detalhes do pedido consultado, conforme exemplo abaixo:
{% endhint %}

```
{
    "channel": "Lojas Americanas",
    "calculation_type": "b2wentregadirect",
    "shipping_carrier": "Courier",
    "invoices": [],
    "tags": [],
    "expedition_limit_date": null,
    "code": "Lojas Americanas-1000000000000-01",
    "approved_date": "",
    "delivered_date": null,
    "shipping_cost": 0.0,
    "shipped_date": "",
    "imported_at": "2023-03-27T16:48:07-03:00",
    "import_info": {
        "ss_name": "Lojas Americanas",
        "remote_id": null,
        "remote_code": "1000000000000-01",
        "pack_id": null,
        "cart_id": null
    },
    "target_order": null,
    "shipping_method": "Courier",
    "shipping_address": {
        "street": "Avenida Paulista",
        "secondary_phone": "99 999999999",
        "region": "SP",
        "reference": null,
        "postcode": "90000000",
        "phone": "99 999999999",
        "number": "1000",
        "neighborhood": "Bela Vista",
        "full_name": "João dos Santos",
        "detail": "Ao lado da cafeteria",
        "country": "BR",
        "complement": null,
        "city": "São Paulo"
    },
    "sync_sale_system": "Teste",
    "discount": 0.0,
    "first_exported_at": "2023-03-28T10:55:41-03:00",
    "billing_address": {
        "street": "Avenida Paulista",
        "secondary_phone": "99 999999999",
        "region": "SP",
        "reference": null,
        "postcode": "90000000",
        "phone": "99 999999999",
        "number": "1234",
        "neighborhood": "Bela Vista",
        "full_name": "João dos Santos",
        "detail": "Próximo ao museu",
        "country": "BR",
        "complement": null,
        "city": "São Paulo"
    },
    "interest": 0.0,
    "available_to_sync": true,
    "payments": [
        {
            "value": 39.9,
            "type": null,
            "transaction_date": null,
            "status": null,
            "sefaz": {
                "type_integration": null,
                "payment_indicator": null,
                "name_payment": null,
                "name_card_issuer": null,
                "id_payment": null,
                "id_card_issuer": null
            },
            "parcels": 1,
            "method": "CREDIT_CARD",
            "description": "SkyHub",
            "card_issuer": null,
            "autorization_id": null
        }
    ],
    "placed_at": "2023-03-27T16:48:07-03:00",
    "delivery_contract_type": "",
    "shipping_estimate_id": "",
    "linked_order": null,
    "estimated_delivery_shift": null,
    "shipping_method_id": null,
    "estimated_delivery": "2023-03-30T00:00:00-03:00",
    "id": "6000f0f0d0ee0000000f0e00",
    "shipments": [],
    "items": [
        {
            "special_price": 39.9,
            "shipping_cost": null,
            "remote_store_id": null,
            "qty": 1,
            "product_id": "2023001",
            "original_price": 39.9,
            "name": "Camiseta Branca Tam. Único",
            "listing_type_id": null,
            "id": "2023001",
            "gift_wrap": null,
            "detail": null,
            "delivery_line_id": null
        }
    ],
    "total_ordered": 39.9,
    "updated_at": "2023-03-27T16:48:07-03:00",
    "status": {
        "type": "NEW",
        "label": "Pagamento Pendente (new) (SkyHub)",
        "code": "book_product"
    },
    "customer": {
        "vat_number": "23455567899",
        "phones": [
            "99 999999999"
        ],
        "name": "João dos Santos",
        "gender": "male",
        "email": "comprador@exemplo.com.br",
        "date_of_birth": "1989-01-01"
    },
    "delivery_token": {
        "takeout": null,
        "failure": null,
        "customer": null
    },
    "sync_status": "SYNCED",
    "exported_at": "2023-03-28T10:55:41-03:00"
}
```

## Filtros para consulta de pedidos

É possível limitar a listagem de pedidos retornados em uma consulta ao aplicar filtros às buscas. 

{% hint style="info" %}
A aplicação de filtros não deve ser utilizada para o consumo de pedidos. Para tal, sempre utilize a [fila de integração](https://desenvolvedores.skyhub.com.br/pedidos/consumo-de-pedidos-queues). 
{% endhint %}

Através da URL de pedidos e dos headers informados no início deste guia é possível realizar os filtros por:

* [Paginação e quantidade de registros na página](#paginacao-da-consulta);
* [Status](#filtro-de-pedidos-por-status);
* [Data inicial e final da criação do pedido](#filtro-de-pedidos-por-data);
* [Canal de venda](#filtro-de-pedidos-por-canal-de-venda)

### **Paginação da consulta**

Ao se tratar de uma conta com muitos pedidos pode ser necessário realizar a paginação dos resultados para visualização de todos os registros. 

Através do */orders* é possível utilizar os parâmetros **page** e **per\_page** para paginação da consulta de pedidos, sendo:

<table><thead><tr><th width="135">Key</th><th>Value</th></tr></thead><tbody><tr><td><strong>page</strong></td><td>Indica o número da página de registros que será retornada. Caso não seja especificado, sempre será retornada a primeira página (valor padrão 1)</td></tr><tr><td><strong>per_page</strong></td><td>Indica a quantidade de registros que serão visualizados na página. O valor padrão é de 100 registros; caso a conta possua mais de 100 pedidos faz-se necessário acessar a(s) próxima(s) página(s) para visualização dos demais registros</td></tr></tbody></table>

Os filtros de paginação são aplicados através dos [headers](#request-headers) padrões da API em um GET para o endpoint */orders*. A seguir temos um exemplo prático de aplicação dos parâmetros ***page*** e ***per\_page***:

#### **Example request:**

```
curl --location --request GET 'https://api.skyhub.com.br/orders?per_page=5&page=3' \
--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'
```

#### **Response esperado:**

{% hint style="success" %}
200 \[Success] - OK: Como resposta para a execução do cURL exemplificado acima haverá um body contendo todos os detalhes dos **5 registros** presentes na **página 3**. A seguir temos uma visualização resumida do retorno:
{% endhint %}

```
{
    "total": 122,
    "orders": [
        {
            "channel": "Lojas Americanas",
            "calculation_type": null,
            "shipping_carrier": "Correios PAC",
            "tags": [],
            "shipping_cost": 0.0,
            "code": "Lojas Americanas-1000000000007-01", (...)
            "first_exported_at": null,
            "import_info": {
                "ss_name": "Lojas Americanas",
                "remote_id": null,
                "remote_code": "1000000000007-01",
                "pack_id": null,
                "cart_id": null
            }, (...)
            "status": {
                "type": "NEW",
                "label": "Pagamento Pendente (new) (SkyHub)",
                "code": "book_product"
            }, (...)
        },
        {
            "channel": "Lojas Americanas",
            "calculation_type": "b2wentregadirect",
            "shipping_carrier": "Correios PAC",
            "tags": [],
            "shipping_cost": 0.0,
            "code": "Lojas Americanas-1000000000008-01", (...)
            "first_exported_at": null,
            "import_info": {
                "ss_name": "Lojas Americanas",
                "remote_id": null,
                "remote_code": "1000000000008-01",
                "pack_id": null,
                "cart_id": null
            }, (...)
            "status": {
                "type": "NEW",
                "label": "Pagamento Pendente (new) (SkyHub)",
                "code": "book_product"
            }, (...)
        },
        {
            "channel": "Submarino",
            "calculation_type": null,
            "shipping_carrier": "Correios PAC",
            "tags": [],
            "shipping_cost": 0.0,
            "code": "Submarino-1000000000009-01", (...)
            "first_exported_at": null,
            "import_info": {
                "ss_name": "Submarino",
                "remote_id": null,
                "remote_code": "1000000000009-01",
                "pack_id": null,
                "cart_id": null
            }, (...)
            "status": {
                "type": "NEW",
                "label": "Pagamento Pendente (new) (SkyHub)",
                "code": "book_product"
            }, (...)
        },
        {
            "channel": "Lojas Americanas",
            "calculation_type": null,
            "shipping_carrier": "Correios PAC",
            "tags": [],
            "shipping_cost": 0.0,
            "code": "Lojas Americanas-1000000000010-01", (...)
            "first_exported_at": null,
            "import_info": {
                "ss_name": "Lojas Americanas",
                "remote_id": null,
                "remote_code": "1000000000010-01",
                "pack_id": null,
                "cart_id": null
            }, (...)
            "status": {
                "type": "NEW",
                "label": "Pagamento Pendente (new) (SkyHub)",
                "code": "book_product"
            }, (...)
        },
        {
            "channel": "Shoptime",
            "calculation_type": null,
            "shipping_carrier": "Correios PAC",
            "tags": [],
            "shipping_cost": 0.0,
            "code": "Shoptime-1000000000000-01", (...)
            "first_exported_at": null,
            "import_info": {
                "ss_name": "Shoptime",
                "remote_id": null,
                "remote_code": "1000000000000-01",
                "pack_id": null,
                "cart_id": null
            }, (...)
            "status": {
                "type": "NEW",
                "label": "Pagamento Pendente (new) (SkyHub)",
                "code": "book_product"
            }, (...)
        }
    ]
}
```

### **Filtro de pedidos por status**

Na guia [Status de Pedidos](https://desenvolvedores.skyhub.com.br/pedidos/status-de-pedidos) são fornecidas as orientações para a consulta dos status de pedidos cadastrados na conta da API - ação realizada através do GET no endpoint `/statuses`.&#x20;

É possível utilizar os **códigos de status** recebidos na consulta ao `/statuses` para aplicar filtros na listagem de pedidos.

{% hint style="warning" %}
Para a aplicação de filtros serão utilizados os valores do campo **code** - que será descrito nos exemplos a seguir como **status\_code** - da consulta do `/statuses`.&#x20;
{% endhint %}

Para este filtro, os [headers são os mesmos sinalizados acima](#request-headers) e os status serão definidos como parâmetros no GET para o endpoint:&#x20;

```
https://api.skyhub.com.br/orders?filters[statuses][]={status_code}
```

Para exemplificar, abaixo temos a aplicação de filtros utilizando alguns status padronizados na API:&#x20;

#### - Listagem de novos pedidos (pagamento pendente):

```
https://api.skyhub.com.br/orders?filters[statuses][]=book_product
```

#### - Listagem de pedidos aprovados:

```
https://api.skyhub.com.br/orders?filters[statuses][]=payment_received
```

#### - Listagem de pedidos faturados (nota fiscal emitida):

```
https://api.skyhub.com.br/orders?filters[statuses][]=order_invoiced
```

#### - Listagem de pedidos enviados para a transportadora:

```
https://api.skyhub.com.br/orders?filters[statuses][]=order_shipped
```

#### - Listagem de pedidos entregues ao cliente:

```
https://api.skyhub.com.br/orders?filters[statuses][]=complete
```

#### - Listagem de pedidos cancelados:

```
https://api.skyhub.com.br/orders?filters[statuses][]=order_canceled
```

{% hint style="info" %}
No exemplo prático disponibilizado abaixo, será utilizada a listagem de pedidos cancelados:
{% endhint %}

#### **Example request:**

```
curl --location --globoff --request GET 'https://api.skyhub.com.br/orders?filters[statuses][]=order_canceled' \
--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'
```

#### **Response esperado:**

{% hint style="success" %}
200 \[Success] - OK: Novamente o retorno da requisição trará a consulta de pedidos cujo status foi definido como parâmetro; neste caso, é apresentado o pedido da conta que se encontra como **cancelado**:
{% endhint %}

```
{
    "total": 1,
    "orders": [
        {
            "channel": "Lojas Americanas",
            "calculation_type": "b2wentregadirect",
            "shipping_carrier": "Courier",
            "tags": [],
            "shipping_cost": 0.0,
            "code": "Lojas Americanas-1000000000011-01",
            "shipped_date": "",
            "linked_order": null,
            "imported_at": "2023-03-10T12:04:27-03:00", (...)
            "first_exported_at": "2023-03-10T12:05:03-03:00",
            "import_info": {
                "ss_name": "Lojas Americanas",
                "remote_id": null,
                "remote_code": "1000000000011-01",
                "pack_id": null,
                "cart_id": null
            }, (...)
            "updated_at": "2023-03-10T12:04:27-03:00",
            "status": {
                "type": "CANCELED",
                "label": "Cancelado (SkyHub)",
                "code": "order_canceled"
            },
            "approved_date": "2023-03-10T15:05:24", (...)
            "sync_status": "SYNCED",
            "delivery_token": {
                "takeout": null,
                "failure": null,
                "customer": null
            },
            "expedition_limit_date": null
        }
    ]
}
```

### &#x20;**Filtro de pedidos por data**

Através do */orders* também é possível aplicar filtros de datas para definir os prazos para os registros a serem listados, sendo:

<table><thead><tr><th width="143">Key</th><th>Value</th></tr></thead><tbody><tr><td><strong>start_date</strong></td><td>Data de início: Parâmetro utilizado para definir qual a menor data a ser aplicada na consulta, isto é, ao utilizar este filtro serão retornados os pedidos a partir da data selecionada</td></tr><tr><td><strong>end_date</strong></td><td>Data final: Parâmetro utilizado para definir qual a maior data a ser aplicada na consulta, isto é, ao utilizar este filtro serão retornados os pedidos recebidos até a data definida</td></tr></tbody></table>

Para aplicação deste filtro os [headers são os mesmos sinalizados no início deste guia](#request-headers) e as datas serão definidas como valores nos parâmetros do GET para o endpoint:&#x20;

```
https://api.skyhub.com.br/orders?filters[start_date/end_date]=DD/MM/AAAA
```

{% hint style="info" %}
Os parâmetros **start\_date** e **end\_date** sempre estarão relacionados à <mark style="color:green;">**data de criação**</mark> do pedido, nunca de sua última atualização.&#x20;

Para validação dos retornos das consultas, será necessário verificar a informação apresentada no campo <mark style="color:green;">**placed\_at**</mark>.
{% endhint %}

#### **Example request - start\_date e end\_date:**

```
curl --location --request GET 'https://api.skyhub.com.br/orders?filters[start_date]=09/03/2023&filters[end_date]=09/03/2023' \
--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'
```

#### **Response esperado:**

{% hint style="success" %}
200 \[Success] - OK: Note que para o exemplo foi aplicada uma data inicial e uma final, sendo que ambas são iguais. Neste caso o retorno trará todos os pedidos criados <mark style="color:green;">**apenas**</mark> na data estipulada:
{% endhint %}

```
{
    "total": 2,
    "orders": [
        {
            "channel": "Lojas Americanas",
            "calculation_type": "b2wentregadirect",
            "shipping_carrier": "B2W Fulfillment",
            "tags": [],
            "shipping_cost": 0.0,
            "code": "Lojas Americanas-1000000000011-01", (...)
            "first_exported_at": "2023-03-09T16:25:41-03:00",
            "import_info": {
                "ss_name": "Lojas Americanas",
                "remote_id": null,
                "remote_code": "1000000000011-01",
                "pack_id": null,
                "cart_id": null
            },
            "discount": 0.0,
            "shipping_method": "B2W Fulfillment", (...)
            "placed_at": "2023-03-09T16:04:57-03:00", (...) 
            "status": {
                "type": "NEW",
                "label": "Pagamento Pendente (new) (SkyHub)",
                "code": "book_product"
            }, (...)
        },
        {
            "channel": "Lojas Americanas",
            "calculation_type": null,
            "shipping_carrier": "PAC",
            "tags": [],
            "shipping_cost": 0.0,
            "code": "Lojas Americanas-1000000000012-01", (...)
            "first_exported_at": "2023-03-09T14:46:06-03:00",
            "import_info": {
                "ss_name": "Lojas Americanas",
                "remote_id": null,
                "remote_code": "1000000000012-01",
                "pack_id": null,
                "cart_id": null
            }, (...)
            "placed_at": "2023-03-09T14:19:29-03:00",
            "delivery_contract_type": "SHIPSTORE", (...)
            "status": {
                "type": "INVOICED",
                "label": "Pagamento Faturado (SkyHub)",
                "code": "order_invoiced"
            }, (...)
        }
    ]
}
```

### **Filtro de pedidos por canal de venda**

O marketplace Americanas englobava três canais de venda distintos, sendo <mark style="color:red;">Lojas Americanas</mark>, <mark style="color:orange;">Shoptime</mark> e <mark style="color:blue;">Submarino</mark>. Desta forma, é possível aplicar filtros para o parâmetro sale\_systems a fim de listar os pedidos por canal de venda do marketplace.

Para a listagem por canal de vendas será realizado um GET contendo os [headers](#request-headers) padrões da API para endpoint e parâmetro visualizados a seguir:

{% hint style="info" %}
Atualmente, a Americanas Marketplace atua somente com a marca <mark style="color:red;">**Lojas Americanas**</mark>. Ainda é possível consultar pedidos antigos das demais marcas citadas acima.
{% endhint %}

```
https://api.skyhub.com.br/orders?filters[sale_systems][]={channel}
```

#### **Example request:**

```
curl --location --request GET 'https://api.skyhub.com.br/orders?filters[sale_systems][]=Shoptime' \
--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'
```

#### **Response esperado:**

{% hint style="success" %}
200 \[Success] - OK: No cURL disponibilizado acima foi definido o canal de venda Shoptime. Sendo assim, o retorno da requisição será dos pedidos gerados para este canal de venda:
{% endhint %}

```
{
    "total": 1,
    "orders": [
        {
            "channel": "Shoptime",
            "calculation_type": "b2wentregadirect",
            "shipping_carrier": "Courier",
            "tags": [],
            "shipping_cost": 0.0,
            "code": "Shoptime-1600000000082-01", (...)
            "import_info": {
                "ss_name": "Shoptime",
                "remote_id": null,
                "remote_code": "1600000000082-01",
                "pack_id": null,
                "cart_id": null
            }, (...)
            "status": {
                "type": "NEW",
                "label": "Pagamento Pendente (new) (SkyHub)",
                "code": "book_product"
            }, (...)
        }
    ]
}
```

### Limite para consulta

{% hint style="warning" %}
Há um limitador no recurso que permite o retorno de - no máximo - **10.000** **registros** para a **consulta de pedidos**.

Caso a conta possua mais registros para serem exibidos, sugerimos que sejam aplicados filtros capazes de adequar a quantidade do retorno de acordo com o limite existente.
{% endhint %}