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/ordersRequest headers:
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:
200 [Success] - OK: Como resposta haverá um body contendo todos os pedidos da conta:
{
"total": 122,
"orders": [
{
"channel": "AMERICANAS",
"calculation_type": "b2wentregadirect",
"shipping_carrier": "Courier",
"invoices": [...],
(...)
"tags": [],
"expedition_limit_date": null,
"code": "Lojas Americanas-1000000000000",
(...)
"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
]
}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' \
--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",
"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",
"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.
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:
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", (...)
"first_exported_at": null,
"import_info": {
"ss_name": "Lojas Americanas",
"remote_id": null,
"remote_code": "1000000000007",
"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", (...)
"first_exported_at": null,
"import_info": {
"ss_name": "Lojas Americanas",
"remote_id": null,
"remote_code": "1000000000008",
"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", (...)
"first_exported_at": null,
"import_info": {
"ss_name": "Submarino",
"remote_id": null,
"remote_code": "1000000000009",
"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", (...)
"first_exported_at": null,
"import_info": {
"ss_name": "Lojas Americanas",
"remote_id": null,
"remote_code": "1000000000010",
"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", (...)
"first_exported_at": null,
"import_info": {
"ss_name": "Shoptime",
"remote_id": null,
"remote_code": "1000000000000",
"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_canceledExample 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",
"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",
"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:
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/AAAAExample 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", (...)
"first_exported_at": "2023-03-09T16:25:41-03:00",
"import_info": {
"ss_name": "Lojas Americanas",
"remote_id": null,
"remote_code": "1000000000011",
"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", (...)
"first_exported_at": "2023-03-09T14:46:06-03:00",
"import_info": {
"ss_name": "Lojas Americanas",
"remote_id": null,
"remote_code": "1000000000012",
"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:
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", (...)
"import_info": {
"ss_name": "Shoptime",
"remote_id": null,
"remote_code": "1600000000082",
"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.
Last updated