Integração de Pedidos

Toda conta criada na SkyHub possuem 7 status por padrão:

Status

Descrição

NEW

Pedidos feitos no marketplace e que ainda não tiveram o pagamento confirmado. A atualização para essa status é feito pelo marketplace.

APPROVED

Pedidos feitos no marketplace e que já tiveram o pagamento confirmado. A atualização para esse status é feito pelo marketplace.

INVOICED

Pedidos que o lojista já faturou. A atualização para esse status é feito pelo lojista.

SHIPPED

Pedidos que o lojista já entregou a transportadora. A atualização para esse status é feito pelo lojista.

DELIVERED

Pedidos que já foram entregues ao cliente final. A atualização para esse status é feito pelo o lojista.

CANCELED

Pedidos que foram cancelados. A atualização para esse status pode ser feito pelo o lojista ou pelo o marketplace.

SHIPMENT_EXCEPTION

É o status que o pedido recebe quando por algum motivo a entrega não foi realizada.

PAYMENT_OVERDUE

É o status que o pedido recebe ao ter o boleto com a data de pagamento vencido.

Observação: Caso o cliente efetue o pagamento e o lojista não tiver mais o estoque, o lojista pode decidir se vai ou não atender aquele pedido, caso deseje atender o mesmo deve incluir estoque para o item do pedido.

Cada status descrito acima está associado a um recurso chamado "tipo de status" (status type) . O status type existe para que as integrações consigam criar novos status na plataforma da SkyHub. para saber mais acesse o Guia de Status de Pedidos.

Passos para integração de pedidos

Os passos para integração de pedidos são:

  1. Baixar pedidos pela fila de integração (Queues)

  2. Confirmar a baixa do pedido

  3. Notificar o andamento do pedido

Baixar pedidos (fila de integração)

Quando um pedido é realizado ou tem o status atualizado pelo o marketplace, o pedido é colocado em uma fila de integração e fica disponível no recurso GET /queues/orders.

Para baixar um pedido (ou atualização):

Exemplo de Solicitação no Endpoint "/queues/orders"
curl --request GET \
--url https://api.skyhub.com.br/queues/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-User-Email: seu@email.com' \
--header 'X-Api-Key: YOUR API KEY HERE' \
--header 'X-Accountmanager-Key: token_account'

Será retornado o json de um pedido como no exemplo abaixo:

Exemplo de Resposta do Endpoint "/queues/orders"
{
"updated_at": "2019-08-06T18:39:07-03:00",
"total_ordered": 734.45,
"tags": [],
"sync_status": "SYNCED",
"status": {
"type": "NEW",
"label": "NEW",
"code": "new"
},
"shipping_method": "Courier",
"shipping_cost": 0.0,
"shipping_carrier": "Courier",
"shipping_address": {
"street": "Rua de teste",
"secondary_phone": null,
"region": "RJ",
"reference": "próximo",
"postcode": "00000000",
"phone": "00 00000000",
"number": "00",
"neighborhood": "Braga",
"full_name": "Nome do recebedor",
"detail": "apartamento 304 - Ponto de referência teste",
"country": "BR",
"complement": "apartamento 00",
"city": "Cabo Frio"
},
"shipped_date": "",
"shipments": [],
"placed_at": "2019-08-06T18:39:04-03:00",
"payments": [{
"value": 734.45,
"transaction_date": null,
"status": null,
"sefaz": {
"type_integration": "1",
"payment_indicator": "1",
"name_payment": "Cartão de Crédito",
"name_card_issuer": "Visa",
"id_payment": "3",
"id_card_issuer": "01"
},
"parcels": 8,
"method": "CREDIT_CARD",
"description": "No valor de: 734.45",
"card_issuer": "null",
"autorization_id": "null"
}],
"items": [{
"special_price": 734.45,
"shipping_cost": 0.0,
"qty": 1,
"product_id": "716",
"original_price": 734.45,
"name": "Nome do Item",
"id": "000",
"gift_wrap": null,
"detail": null
}],
"invoices": [],
"interest": 0.0,
"import_info": {
"ss_name": "Lojas Americanas",
"remote_id": "00-000000000",
"remote_code": "000000000000"
},
"estimated_delivery_shift": null,
"estimated_delivery": "2019-08-19T00:00:00-03:00",
"discount": 0.0,
"delivery_contract_type": "B2WENDIREC",
"delivered_date": null,
"customer": {
"vat_number": "00000000000",
"phones": ["00 00000000"],
"name": "Nome do comprador",
"gender": "",
"email": "123456@email.com.br",
"date_of_birth": "0000-00-00"
},
"code": "Lojas Americanas-000000000000",
"channel": "Lojas Americanas",
"calculation_type": "b2wentregadirect",
"billing_address": {
"street": "Rua de teste",
"secondary_phone": null,
"region": "RJ",
"reference": "próximo ao hospital",
"postcode": "00000000",
"phone": "00 00000000",
"number": "000",
"neighborhood": "Braga",
"full_name": "Nome do compradors",
"detail": "apartamento 304 - próximo ao hospital",
"country": "BR",
"complement": "apartamento 000",
"city": "Cabo Frio"
},
"approved_date": ""
}

Dicas sobre a fila de integração de pedidos

Verificar o campo status[code]

Ao recuperar um pedido da fila de integração, 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).

GET queues/orders sempre retorna o status atual do pedido

O pedido entra na fila sempre que houver uma atualização, e a integração terá a informação do pedido na situação da ultima atualização.

Imagine o seguinte cenário:

  1. O pedido é realizado no marketplace (status NEW) e entra na fila queues/orders

  2. A integração não consome o recurso queues/orders

  3. O pedido tem o pagamento confirmado no marketplace (status APPROVED) e entra novamente na fila queues/orders

  4. 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 inves do status "NEW" (status que o pedido tinha quando entrou na fila pela primeira vez). Como o pedido entrou duas vezes na fila, se repetir a chamada GET queues/orders (sem que haja atualização do marketplace), a integração receberá o mesmo json novamente.

Marcar pedido como processado

Ao consumir o recurso GET queues/orders, o pedido sai da fila de integração e fica "aguardando" por 5 minutos a notificação de processado por parte da integração: DELETE queues/orders.

Se a SkyHub não receber a confirmação de que a integração conseguiu processar o pedido com sucesso, o pedido voltará para a fila depois de 5 minutos. Para confirmar que o evento foi processo com sucesso, é preciso fazer uma requisição como no exemplo abaixo.

curl --request DELETE \
--url https://api.skyhub.com.br/queues/orders/Marketplace-000000002 \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-User-Email: seu@email.com' \
--header 'X-Api-Key: YOUR-API-KEY-HERE' \
--header 'X-Accountmanager-Key: token_account'

Notificar o andamento do pedido

Após a aprovação do pedido por parte do marketplace, chega o momento do lojista dar andamento ao pedido: informando os dados de fatura (NFe); dados de rastreio da entrega; e notificação da entrega ao cliente final.

Atualizar para faturado (INVOICED)

Nesta operação é informado a chave da NFe, ou seja, os 44 digitos da NFe.

Para pedidos que utilizam a estratégia de frete B2W Entregas Direct, é possivel informar a quantidade de etiquetas a serem emitidas através do: "volume_qty"

curl --request POST \
--url https://api.skyhub.com.br/orders/Marketplace-000000001/invoice \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-accountmanager-key: foo' \
--header 'x-api-key: YOUR API KEY HERE' \
--header 'x-user-email: MUDAR@SEU_EMAIL.COM' \
--data '{ "status": "order_invoiced","invoice": {"key": "99999999999999999999999999999999999999999999","volume_qty": 1}}'

Fica a ressalva que, não deve ser solicitado mais etiquetas do que o necessário.

Por exemplo:

Um pedido possui 1 item com 1 unidade. Obrigatoriamente deve ser informado 1 em "volume_qty".

Atualizar para entregue a transportadora (SHIPPED)

Nessa operação são informados os dados de rastreamento da entrega (tipo de envio, código de rastreio, url de rastreio, etc.).

curl --request POST \
--url https://api.skyhub.com.br/orders/Marketplace-000000002/shipments \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-User-Email: seu@email.com' \
--header 'X-Api-Key: YOUR API KEY HERE' \
--header 'X-Accountmanager-Key: token_account' \
--data '{"status":"order_shipped","shipment":{"code":"Submarino-1493069158776","items":[{"sku":"1001","qty":1}],"track":{"code":"BR1321830198302DR","carrier":"Correios","method":"SEDEX","url":"www.correios.com.br"}}}'

Atualizar para entregue ao cliente (DELIVERED)

curl --request POST \
--url https://api.skyhub.com.br/orders/Marketplace-000000002/delivery \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-User-Email: seu@email.com' \
--header 'X-Api-Key: YOUR API KEY HERE' \
--header 'X-Accountmanager-Key: token_account' \
--data '{"status":"complete"}'

Cancelar pedido

curl --request POST \
--url https://api.skyhub.com.br/orders/Marketplace-000000002/cancel \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-User-Email: seu@email.com' \
--header 'X-Api-Key: YOUR API KEY HERE' \
--header 'X-Accountmanager-Key: token_account' \
--data '{"status":"order_canceled"}'

Criando/aprovando pedidos teste

Para contas de desenvolvimento/homologação é possível criar e aprovar pedidos.

Essas operações não estão disponíveis em contas em produção.

1 - Criar pedido teste (status NEW)

curl --request POST \
--url https://api.skyhub.com.br/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-User-Email: seu@email.com' \
--header 'X-Api-Key: YOUR API KEY HERE' \
--header 'X-Accountmanager-Key: token_account' \
--data '{"order": {"channel": "Marketplace","items": [{"id": "10200487","qty": 1,"original_price": 8.45,"special_price": 8.45}],"customer": {"name": "Nome do comprador","email": "comprador@exemplo.com.br","date_of_birth": "1995-01-01","gender": "male","vat_number": "12312312309","phones": ["8899999999"]},"billing_address": {"street": "Rua de teste","number": 1234,"detail": "Ponto de referência teste","neighborhood": "Bairro teste","city": "Cidade de teste","region": "UF","country": "BR","postcode": "90000000"},"shipping_address": {"street": "Rua de teste","number": 1234,"detail": "Ponto de referência teste","neighborhood": "Bairro teste","city": "Cidade de teste","region": "UF","country": "BR","postcode": "90000000"},"shipping_method": "Transportadora","estimated_delivery": "2015-01-10","shipping_cost": 5.0,"interest": 0.0,"discount": 0.00}}'

2 - Aprovar pedido teste (status APPROVED)

curl --request POST \
--url https://api.skyhub.com.br/orders/Marketplace-000000001/approval \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-User-Email: seu@email.com' \
--header 'X-Api-Key: YOUR API KEY HERE' \
--header 'X-Accountmanager-Key: token_account' \
--data '{"status":"payment_received"}'

Para aprovação, atentar para o código gerado para o pedido criado e substituir na url do exemplo.

É obrigatório consumir todos os pedidos da fila de integração (Queues) com status NEW, pra que os produtos sejam empenhados em seus estoques.

Porque é obrigatório?

Para não ter divergência de estoque Disponível X estoque Empenhado

Se não consumir os pedidos o que pode acontecer? Podemos vender produtos sem estoque, uma vez que o empenho não existe na plataforma receberemos o estoque como Estoque Disponível, consequentemente disponibilizaremos o estoque errado para o Marketplace.

Vale Lembrar:

  • As plataformas que não se adequarem a essa regra de negócios podem arcar com prejuízo do seller.

  • Para a Skyhub, deve ser enviado apenas o estoque disponível.