Consulta de Pedidos

Nesta seção é apresentada a consulta de pedidos, assim como os filtros de pesquisa que podem ser aplicados

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

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:

200 [Success] - OK: Como resposta haverá um body contendo todos os pedidos da conta:

{
    "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 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:

200 [Success] - OK: Em resposta serão apresentados os detalhes do pedido consultado, conforme exemplo abaixo:

{
    "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": "[email protected]",
        "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.

A aplicação de filtros não deve ser utilizada para o consumo de pedidos. Para tal, sempre utilize a fila de integração.

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

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:

Key

Value

page

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)

per_page

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

Os filtros de paginação são aplicados através dos 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:

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:

{
    "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 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.

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

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.

Para este filtro, os headers são os mesmos sinalizados acima e os status serão definidos como parâmetros no GET para o endpoint:

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:

- 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

No exemplo prático disponibilizado abaixo, será utilizada a listagem de pedidos cancelados:

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:

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:

{
    "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
        }
    ]
}

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:

Key

Value

start_date

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

end_date

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

Para aplicação deste filtro os headers são os mesmos sinalizados no início deste guia e as datas serão definidas como valores nos parâmetros do GET para o endpoint:

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

Os parâmetros start_date e end_date sempre estarão relacionados à data de criação do pedido, nunca de sua última atualização.

Para validação dos retornos das consultas, será necessário verificar a informação apresentada no campo placed_at.

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:

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 apenas na data estipulada:

{
    "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 Lojas Americanas, Shoptime e Submarino. 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 padrões da API para endpoint e parâmetro visualizados a seguir:

Atualmente, a Americanas Marketplace atua somente com a marca Lojas Americanas. Ainda é possível consultar pedidos antigos das demais marcas citadas acima.

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:

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:

{
    "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

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.

PreviousNotificação de Pedidos NextConsulta de Erros de Sincronização e Produção

Last updated 4 days ago