Status de Pedidos

Nesta seção temos o descritivo dos status padronizados nas contas da API da Americanas, assim como a forma de consultá-los e como seguir ao optar por utilizar um status não padrão

Status padrão

Na API da Americanas o pedido possui diversos status em seu ciclo de vida, como, por exemplo, faturado, expedido, entregue, entre outros.

Esses status são criados por padrão nas contas da SkyHub, sem a necessidade de cadastrá-los, e podem ser utilizados para executar as requisições para atualização dos pedidos na comunicação entre a plataforma e a API.

A seguir temos a relação dos status padronizados na API:

Status	Código	Descrição
NEW	book_product	Pedidos feitos no marketplace e que ainda não tiveram o pagamento confirmado. A atualização para essa status é feita pelo marketplace.
APPROVED	payment_received	Pedidos feitos no marketplace e que já tiveram o pagamento confirmado. A atualização para esse status é feita pelo marketplace.
INVOICED	order_invoiced	Pedidos que o lojista já faturou. A atualização para esse status é feita pelo lojista.
SHIPPED	order_shipped	Pedidos que o lojista já entregou a transportadora. A atualização para esse status é feita pelo lojista.
DELIVERED	complete	Pedidos que já foram entregues ao cliente final. A atualização para esse status é feita pelo lojista.
CANCELED	order_canceled	Pedidos que foram cancelados. A atualização para esse status pode ser feita pelo lojista ou pelo marketplace.
SHIPMENT_EXCEPTION	shipment_exception	É o status que o pedido recebe quando, por algum motivo, a entrega não foi realizada.
OVERDUE	payment_overdue	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 seller não tenha mais o item em 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.

Caso não seja possível atender, é de responsabilidade do seller encaminhar a atualização com status de cancelado para a API.

Para o marketplace Americanas, a atualização de cancelado é consumida como INDISPONÍVEL, onde o seller terá um prazo para verificar se realmente não poderá atender ao pedido. Caso o prazo definido pelo marketplace venha a expirar, o pedido será efetivamente atualizado para CANCELADO.

Endpoint /statuses

Acima informamos a listagem padrão de status criados nas contas da API da Americanas, porém eventualmente o parceiro pode optar por um nome diferente para os seus status. Por exemplo, ao invés de order_invoiced é possível definir e utilizar somente invoiced; esse novo status deverá ser criado pelo endpoint /statuses antes de sua utilização, caso contrário retornará erro na request.

GET - Consultando os status existentes na conta

Se a conta na API existe há algum tempo, pode ser que alguma outra plataforma tenha criado status de pedidos diferenciados para ela. Sendo assim, é importante consultar o que está cadastrado na conta para seguir com o mesmo padrão e/ou para evitar a criação de algum status duplicado.

Para realizar a consulta dos status cadastrados em conta deverá ser realizado um GET no endpoint descrito abaixo:

https://api.skyhub.com.br/statuses

Request headers:

Key	Value
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/statuses' \
--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:

200 [Success] - OK: O response body trará informações dos status cadastrados na conta:

[
    {
        "code": "book_product",
        "label": "Pagamento Pendente (new) (SkyHub)",
        "type": "NEW"
    },
    {
        "code": "order_canceled",
        "label": "Cancelado (SkyHub)",
        "type": "CANCELED"
    },
    {
        "code": "payment_received",
        "label": "Aprovado (SkyHub)",
        "type": "APPROVED"
    },
    {
        "code": "order_shipped",
        "label": "Pedido Enviado (SkyHub)",
        "type": "SHIPPED"
    },
    {
        "code": "complete",
        "label": "Completo (entregue) (SkyHub)",
        "type": "DELIVERED"
    },
    {
        "code": "shipment_exception",
        "label": "Exceção de Entrega (SkyHub)",
        "type": "SHIPMENT_EXCEPTION"
    },
    {
        "code": "order_invoiced",
        "label": "Pagamento Faturado (SkyHub)",
        "type": "INVOICED"
    }
]

POST - Criando um novo status

Se houver a necessidade, é possível utilizar os headers descritos acima e realizar um POST no endpoint:

https://api.skyhub.com.br/statuses

Request body:

{
  "status": {
    "code": "codigo_do_status",
    "label": "label_do_status",
    "type": "tipo_do_status"
  }
}

O campo "code" se refere ao nome do status e será utilizado nas requisições para atualização do pedido. O mesmo (code) não poderá ser alterado após a sua criação.

Em "type" esperamos o tipo de status que será representado pela nova label criada, como, por exemplo, CANCELED, NEW e COMPLETE.

Example request:

curl --location --request POST 'https://api.skyhub.com.br/statuses' \
--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' \
--data-raw '{
  "status": {
    "code": "new_order",
    "label": "Novo Pedido Recebido",
    "type": "NEW"
  }
}'

Note que no request body informamos que deve ser incluso o type, isto é, o tipo de status que está sendo criado.

Como saber qual type deve ser utilizado?

O payload retornado ao realizar a consulta de todos os status presentes na conta traz as informações sobre o código (code), a label e o tipo (type) do status, porém também é possível utilizar os headers padronizados em nossa API para realizar um GET no endpoint https://api.skyhub.com.br/status_types. O retorno será uma listagem simples apenas dos types presentes na conta.

Response esperado:

201 [Success] - Created

PUT - Atualizando um status

Após a criação de um status é possível realizar alterações em sua label, ou seja, o código (code) não poderá ser atualizado, porém a "legenda" com a qual o status será identificado poderá ser modificada a qualquer momento.

Para realizar a atualização de um status, basta utilizar os headers descritos e realizar um PUT no endpoint:

https://api.skyhub.com.br/statuses/{code}

Para a atualização, o {code} visualizado na URL deverá ser substituído pelo código do status que será alterado.

Request body:

{
  "status": {
    "label": "label_do_status",
    "type": "tipo_do_status"
  }
}

Example request:

curl --location --request PUT 'https://api.skyhub.com.br/statuses/new_order' \
--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' \
--data-raw '{
  "status": {
    "label": "Novo Pedido (Aguardando Pagamento)",
    "type": "NEW"
  }
}'

Response esperado:

204 [Success] - No content