> For the complete documentation index, see [llms.txt](https://desenvolvedores.skyhub.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://desenvolvedores.skyhub.com.br/pedidos/status-de-pedidos.md). # Status de Pedidos ## 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. | {% hint style="info" %} **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. {% endhint %} ## 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: {% hint style="success" %} 200 \[Success] - OK: O response body trará informações dos status cadastrados na conta: {% endhint %} ``` [ { "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](#request-headers) 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" } } ``` {% hint style="warning" %} 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. {% endhint %} #### **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" } }' ``` {% hint style="info" %} 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](#request-headers) 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. {% endhint %} #### Response esperado: {% hint style="success" %} 201 \[Success] - Created {% endhint %} ### 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](#request-headers) e realizar um PUT no endpoint: ``` https://api.skyhub.com.br/statuses/{code} ``` {% hint style="info" %} Para a atualização, o **{code}** visualizado na URL deverá ser substituído pelo código do status que será alterado. {% endhint %} #### **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: {% hint style="success" %} 204 \[Success] - No content {% endhint %}