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:
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:
Example request:
Response esperado:
200 [Success] - OK: Em resposta serão apresentados os detalhes do pedido consultado, conforme exemplo abaixo:
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:
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:
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:
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 exemplificar, abaixo temos a aplicação de filtros utilizando alguns status padronizados na API:
- Listagem de novos pedidos (pagamento pendente):
- Listagem de pedidos aprovados:
- Listagem de pedidos faturados (nota fiscal emitida):
- Listagem de pedidos enviados para a transportadora:
- Listagem de pedidos entregues ao cliente:
- Listagem de pedidos cancelados:
No exemplo prático disponibilizado abaixo, será utilizada a listagem de pedidos cancelados:
Example request:
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:
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
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:
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:
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.
Example request:
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:
Limite para consulta
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.
{
"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
}
https://api.skyhub.com.br/orders/{code}
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'
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'
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'
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'
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'
