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.

INVOICE

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"
{
"code": "Marketplace-000000002",
"channel": "Marketplace",
"placed_at": "2015-01-01T10:10:00-03:00",
"updated_at": "2015-01-01T10:10:00-03:00",
"total_ordered": 5.85,
"interest": 0.0,
"shipping_cost": 5.0,
"shipping_method": "Transportadora",
"estimated_delivery": "2015-01-10T10:10:10-03:00",
"estimated_delivery_shift": null,
"shipping_address": {
"full_name": "Nome do recebedor",
"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"
},
"billing_address": {
"full_name": "Nome do comprador",
"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"
},
"customer": {
"name": "Nome do comprador",
"email": "comprador@exemplo.com.br",
"date_of_birth": null,
"gender": "",
"vat_number": 12312312309,
"phones": [
"8899999999"
]
},
"items": [
{
"id": "teste002-azul",
"product_id": "teste002",
"name": "Produto de teste com variação",
"qty": 1,
"original_price": 0.85,
"special_price": 0.85
}
],
"status": {
"code": "payment_received",
"label": "Pagamento aprovado",
"type": "APPROVED"
},
"sync_status": "NOT_SYNCED",
"invoices": [
],
"shipments": [
],
"payments": [
]
}

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 (INVOICE)

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

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"}}'

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.