API – Pedidos

Home » API – Pedidos

Status de pedidos

A SkyHub – API oferece a possibilidade de criar status para os pedidos de acordo com a necessidade do cliente/usuário. Entretanto, cada status criado está ligado a um dos tipos definidos pela API – recurso ‘status_types’.

Além de filtrar os pedidos, os status criados são utilizados na atualização dos pedidos, por exemplo, cancelamento, envio, entrega, etc. Contudo, cada atualização depende da validade da transição do status (e seus tipos), ou seja, antes da mudança, avalia-se a possibilidade de um pedido sair de um determinado tipo de status para outro. A figura abaixo mostra as transições de (tipos de) status possíveis:

Transições dos (tipos de) status dos pedidos

Transições dos (tipos de) status dos pedidos

Consulta de pedidos

Para tornar a consulta de pedidos mais eficiente, a SkyHub – API oferece um método para marcar um pedido como exportado

PUT https://in.skyhub.com.br/orders/{order_id}/exported

Dessa maneira, os pedidos já consultados anteriormente podem ser filtrados, otimizando a comunicação com a API.

Integração de Pedidos

A integração dos pedidos segue o fluxo de informações descrito na figura abaixo.

fluxo_integracao_pedidos

Integração – Criar status de pedidos

De acordo com necessidade do cliente/usuário, deve-se criar os status dos pedidos utilizando os tipos de status disponibilizados na SkyHub – API.

GET https://in.skyhub.com.br/status_types
  ["NEW","CANCELED","APPROVED","SHIPPED","DELIVERED"]

Passo 1 – Recuperar os tipos de status (exemplo).

Recomenda-se criar ao menos um status para cada tipo descrito, exemplo:

{
  "status":
    {
      "code":"pending",
      "label":"Pagamento pendente",
      "type":"NEW"
    }
}
{
  "status":
    {
      "code":"confirmed",
      "label":"Pagamento aprovado",
      "type":"APPROVED"
    }
}
{
  "status":
    {
      "code":"shipped",
      "label":"Entregue à transportadora",
      "type":"SHIPPED"
    }
}
{
  "status":
    {
      "code":"completed",
      "label":"Pedido entregue",
      "type":"DELIVERED"
    }
}
{
  "status":
    {
      "code":"canceled",
      "label":"Cancelado",
      "type":"CANCELED"
    }
}

Passo 2 – Criar status para cada tipo.

Integração – Marcar pedido como exportado

Cenário de exemplo para marcar pedido como exportado:

GET https://in.skyhub.com.br/orders?filters[sync_status][]=NOT_SYNCED

Passo 1 – Recuperar pedidos não exportados ‘NOT_SYNCED’.

Resposta:

{
  "orders":[
    {
      "code":"Pedido-000000001",
      "placed_at":"2015-01-01T10:10:00-03:00",
      "updated_at":"2015-01-01T10:10:00-03:00",
      "total_ordered":12.9,
      "interest":0.0,
      "shipping_cost":5.0,
      "shipping_method":"Transportadora",
      "estimated_delivery":"2015-01-10T10:10:10-03:00",
      "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":"90000-000"
        },
      "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":"90000-000"
        },
      "customer":
        {
          "name":"Nome do comprador",
          "email":"[email protected]",
          "vat_number":12312312309,
          "phones":[
            "(99) 9999-9999"
          ]
        },
      "items":[
        {
          "id":"teste001",
          "name":"Produto simples de teste",
          "qty":10,
          "original_price":0.79,
          "special_price":0.79
        }
      ],
      "status":
        {
          "code":"pending",
          "label":"Pagamento pendente",
          "type":"NEW"
        },
      "invoices":[],
      "shipments":[]
    },
    {
      "code":"Pedido-000000002",
      "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",
      "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":"90000-000"
        },
      "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":"90000-000"
        },
      "customer":
        {
          "name":"Nome do comprador",
          "email":"[email protected]",
          "vat_number":12312312309,
          "phones":[
            "(99) 9999-9999"
          ]
        },
      "items":[
        {
          "id":"teste002-azul",
          "name":"Produto de teste com varia\u00e7\u00e3o",
          "qty":1,
          "original_price":0.85,
          "special_price":0.85
        }
      ],
      "status":
        {
          "code":"confirmed",
          "label":"Pagamento aprovado",
          "type":"APPROVED"
        },
      "invoices":[],
      "shipments":[]
    }
  ],
  "total":2
}

Marcar como exportado:

PUT https://in.skyhub.com.br/orders/Pedido-000000001/exported
{
  "exported":true
}

Passo 2 – Marcar pedido como exportado.

GET https://in.skyhub.com.br/orders?filters[sync_status][]=NOT_SYNCED

Passo 3 – Recuperar pedidos não exportados.

Resposta:

{
  "orders":[
    {
      "code":"Marketplace-000000002",
      "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",
      "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":"90000-000"
        },
      "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":"90000-000"
        },
      "customer":
        {
          "name":"Nome do comprador",
          "email":"[email protected]",
          "vat_number":12312312309,
          "phones":[
            "(99) 9999-9999"
          ]
        },
      "items":[
        {
          "id":"teste002-azul",
          "name":"Produto de teste com varia\u00e7\u00e3o",
          "qty":1,
          "original_price":0.85,
          "special_price":0.85
        }
      ],
      "status":
        {
          "code":"confirmed",
          "label":"Pagamento aprovado",
          "type":"APPROVED"
        },
      "invoices":[],
      "shipments":[]
    }
  ],
  "total":1
}

Integração – Processamento de pedido

Nesse cenário, será mostrado o fluxo de processamento de um pedido: APPROVED -> SHIPPED -> DELIVERED.

GET https://in.skyhub.com.br/orders?filters[statuses][]=confirmed

Passo 1 – Recuperar pedidos com pagamento aprovado.

Resposta:

{
  "orders":[
    {
      "code":"Pedido-000000002",
      "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",
      "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":"90000-000"
        },
      "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":"90000-000"
        },
      "customer":
        {
          "name":"Nome do comprador",
          "email":"[email protected]",
          "vat_number":12312312309,
          "phones":[
            "(99) 9999-9999"
          ]
        },
      "items":[
        {
          "id":"teste002-azul",
          "name":"Produto de teste com varia\u00e7\u00e3o",
          "qty":1,
          "original_price":0.85,
          "special_price":0.85
        }
      ],
      "status":
        {
          "code":"confirmed",
          "label":"Pagamento aprovado",
          "type":"APPROVED"
        },
      "invoices":[],
      "shipments":[]
    }
  ],
  "total":1
}

Notificação de envio:

POST https://in.skyhub.com.br/orders/Pedido-000000002/shipments
{
  "status": "shipped",
  "shipment": {
    "code": "ship001",
    "items": [
      {
        "sku": "teste002-azul",
        "qty": 1
      }
    ],
    "track": {
      "code": "AA123456789BR",
      "carrier": "Transportadora",
      "method": "Normal",
      "url": "http://tracking.dominiotransportadora.com.br/track.php?remessaId=123456"
    }
  },
  "invoice": {
    "key": "12345678901234567890123456789012345678901234"
  }
}

Passo 2 – Criar notificação de envio do pedido.

Notificação de entrega:

POST https://in.skyhub.com.br/orders/Pedido-000000002/delivery
{
  "status": "complete"
}

Passo 3 – Criar notificação de entrega do pedido.

GET https://in.skyhub.com.br/orders/Pedido-000000002

Passo 4 – Recuperar pedido atualizado.

Resposta:

{
  "orders":[
    {
      "code":"Pedido-000000002",
      "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",
      "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":"90000-000"
        },
      "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":"90000-000"
        },
      "customer":
        {
          "name":"Nome do comprador",
          "email":"[email protected]",
          "vat_number":12312312309,
          "phones":[
            "(99) 9999-9999"
          ]
        },
      "items":[
        {
          "id":"teste002-azul",
          "name":"Produto de teste com varia\u00e7\u00e3o",
          "qty":1,
          "original_price":0.85,
          "special_price":0.85
        }
      ],
      "status":
        {
          "code":"complete",
          "label":"Pedido entregue",
          "type":"DELIVERED"
        },
      "invoices":[
        {
          "key":"12345678901234567890123456789012345678901234",
          "number":"678901234",
          "line":"345",
          "issue_date":"2015-01-02T10:10:00-03:00"}
      ],
      "shipments":[
        {
          "code":"ship001",
          "items":[
            {
              "sku":"teste002-azul",
              "qty":1
            }
          ],
          "tracks":[
            {
              "code":"AA123456789BR",
              "carrier":"Transportadora",
              "method":"Normal"
            }
          ]
        }
      ]
    }
  ],
  "total":1
}

Integração – Cancelamento de pedido

Cenário de cancelamento de pedido:

POST https://in.skyhub.com.br/orders/Pedido-000000001/cancel
{
  "status": "canceled"
}

Passo 1 – Cancelar pedido.

GET https://in.skyhub.com.br/orders/Pedido-000000001

Passo 2 – Recuperar pedido atualizado.

Resposta:

{
  "orders":[
    {
      "code":"Pedido-000000001",
      "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",
      "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":"90000-000"
        },
      "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":"90000-000"
        },
      "customer":
        {
          "name":"Nome do comprador",
          "email":"[email protected]",
          "vat_number":12312312309,
          "phones":[
            "(99) 9999-9999"
          ]
        },
      "items":[
        {
          "id":"teste001",
          "name":"Produto simples de teste",
          "qty":10,
          "original_price":0.79,
          "special_price":0.79
        }
      ],
      "status":
        {
          "code":"canceled",
          "label":"Cancelado",
          "type":"CANCELED"
        },
      "invoices":[],
      "shipments":[]
    }
  ],
  "total":1
}