# 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](/pedidos/consumo-de-pedidos-queues.md). 
{% 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](/pedidos/status-de-pedidos.md) 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 %}


---

# Agent Instructions: 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://desenvolvedores.skyhub.com.br/pedidos/consulta-de-pedidos.md?ask=<question>
```

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.