Integração de Pedidos

Toda conta criada na SkyHub possuem 7 status por padrã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.
  • 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.

Obs: 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: https://skyhub.gelato.io/guides/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):

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:

{
  "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/order 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 entrar 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/order (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)

Neste 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":"payment_received","invoice":{"key":"99999999999999999999999999999999999999999999"}}'

Atualizar para entregue a transportadora (SHIPPED)

Nessa operação é informado 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": "teste002-azul","qty": 1,"original_price": 55.22,"special_price": 55.22 }],"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.0}}'

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 pendente, pra que os produtos sejam empenhados em seus estoque.

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.

Vale lembrar que: Para a Skyhub deve ser enviado apenas o estoque disponível.