# 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 %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://desenvolvedores.skyhub.com.br/pedidos/status-de-pedidos.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.