Consumo de Pedidos - Queues
Nesta seção mostraremos como é realizado o consumo de pedidos criados e atualizados pelo marketplace
Quando criado no marketplace, o pedido tem suas informações encaminhadas para a API, cabendo a plataforma/ERP o consumo de seus dados. O mesmo ocorre para atualizações do pedido: A informação será disponibilizada na API para consumo da plataforma/ERP.
Tanto criação quanto atualização serão notificadas pelo marketplace e deverão ser consumidas no recurso /queues/orders.
GET - Baixando pedidos (fila de integração)
Quando um pedido é gerado ou tem o status atualizado pelo o marketplace ele (pedido) é colocado em uma fila de integração e fica disponível para a baixa, que deve ser realizada através de um GET no endpoint visto a seguir:
https://api.skyhub.com.br/queues/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/queues/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:
Dois possíveis retornos são esperados para o GET:
204 [Success] - No content: Retorno esperado caso não hajam pedidos novos/atualizados para consumo;
200 [Success] - OK: Caso existam pedidos novos/atualizados, será visualizado status 200 e o response body trará as informações da entrega, conforme exemplo:
{
"channel": "AMERICANAS",
"calculation_type": "b2wentregacorreios",
"shipping_carrier": "Courier",
"invoices": [],
"tags": [],
"expedition_limit_date": null,
"code": "Lojas Americanas-1000000000005",
"approved_date": "",
"delivered_date": null,
"shipping_cost": 0.0,
"shipped_date": "",
"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
}
],
"imported_at": "2023-03-27T16:48:07-03:00",
"import_info": {
"ss_name": "Lojas Americanas",
"remote_id": null,
"remote_code": "1000000000005",
"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": null,
"discount": 0.0,
"first_exported_at": null,
"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": [],
"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": "NOT_SYNCED",
"exported_at": null
}Através da queues não é possível consumir um pedido especificamente. A fila deverá ser consumida por completo com as informações disponibilizadas pelo marketplace.
Suponha-se que existam 20 pedidos gerados/atualizados pelo marketplace; as notificações cairão na fila aleatoriamente, porém visando aquelas mais recentes, sendo de responsabilidade da plataforma/ERP o consumo de todas as informações disponibilizadas.
Mantendo a fila de integração "limpa", isto é, consumindo sempre todos os pedidos, garante-se que todos os novos gerados e todas as alterações de status estarão atualizados na plataforma/ERP.
O consumo do pedido sempre trará o campo calculation_type, responsável por identificar o método de cálculo de frete.
Sempre que o calculation_type for preenchido com o valor b2wentregadirect, espera-se para o payload o array pick_ups contendo informações da warehouse (CD) e SKU de venda.
Por padrão, o array pick_ups é incluso apenas para pedidos b2wentregadirect, desta forma, para pedidos cujo calculation_type for b2wentregacorreios não haverá a inclusão do referido array (pick_ups).
Dicas sobre a fila de integração de pedidos
-> Verificar o campo status[code]
Ao recuperar um pedido da fila, a integração deve verificar o campo status[code] para saber qual foi o tipo de evento: pedido novo ou uma atualização (aprovação ou cancelamento).
-> O GET na /queues/orders sempre irá retornar o status atual do pedido
O pedido entra na fila sempre que receber alguma atualização proveniente do marketplace e para a plataforma/ERP será disponibilizada a informação da última alteração sofrida.
Imagine o seguinte cenário:
O pedido é gerado no marketplace (status NEW) e entra na fila (
/queues/orders);A plataforma/ERP não consome o recurso
/queues/orders;O pedido tem o pagamento confirmado no marketplace (status APPROVED) e esta atualização entra novamente na fila
/queues/orders;Nesse momento a integração faz uma chamada
GET/queues/orders. O JSON do pedido retornado conterá o status APPROVED (status atual do pedido) ao invés do status NEW (status que o pedido tinha quando entrou na fila pela primeira vez);Como o pedido entrou duas vezes na fila e não havia sido consumido, ao ser repetida a chamada
GET/queues/orders(sem que haja uma nova atualização do marketplace), a integração receberá o mesmo JSON novamente.
-> Estoque Disponível x Estoque Empenhado
É obrigatório consumir todos os pedidos da fila de integração (/queues) com status NEW para que os produtos sejam empenhados em seus estoques.
Esta obrigatoriedade se dá para que sejam evitadas divergências entre o estoque disponível e o estoque empenhado.
O que pode acontecer caso não consuma todos os status do pedido? Ao não consumir o status de NEW não haverá empenho de estoque na plataforma, assim a API receberá a informação de que há estoque disponível para venda, consequentemente, poderão haver vendas sem estoque.
DELETE - Confirmando o consumo do pedido
Após o GET na /queues/orders o pedido apresentado sairá da fila de integração e ficará aguardando por 5 minutos para que a plataforma/ERP confirme o seu processamento. Esta confirmação é realizada utilizando os headers padrões na API e aplicando um DELETE no endpoint:
https://api.skyhub.com.br/queues/orders/{code}Se em até 5 minutos a API não receber a confirmação de que a integração conseguiu processar o pedido com sucesso, o mesmo voltará para a fila, ou seja, após o GET na /queues/orders a plataforma/ERP tem até 5 minutos para realizar a confirmação do consumo da informação.
Caso o sistema tente confirmar o consumo (DELETE) após os 5 minutos sem que haja um novo GET na /queues/orders será retornado status 404.
Example request:
curl --location --request DELETE 'https://api.skyhub.com.br/queues/orders/Lojas Americanas-1000000000005' \
--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:
204 [Success] - No content
Last updated