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
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:
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:
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.
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:
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
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:
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.
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:
Há um limitador no recurso que permite o retorno de - no máximo - 10.000registros 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.
