# Atualização de Pedidos ## POST - Notificando o andamento do pedido Como citado na guia [Criação e Aprovação de Pedido Teste](/pedidos/criacao-de-pedido-teste.md), em ambiente de homologação a aprovação de um pedido deve ser realizada via API. Em ambiente de produção, a aprovação ocorre no marketplace e a atualização desse status é encaminhada para a API, para consumo da plataforma/ERP. Em ambos os casos (tanto para o ambiente de teste quanto para o de produção), após ocorrer a aprovação do pagamento é necessário prosseguir com o ciclo de vida do pedido, onde serão informados os dados de faturamento (NFe), dados de rastreamento da entrega e a notificação da entrega ao cliente final. Para todas as requisições apresentadas a seguir serão utilizados os headers padronizados na API e descritos abaixo: #### 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 | {% hint style="info" %} O **code** nas requisições apresentadas deverá ser substituído pelo **código completo do pedido**, visualizado após o [consumo](/pedidos/consumo-de-pedidos-queues.md). {% endhint %} {% hint style="danger" %} Os status utilizados nesta página para exemplificar a atualização de um pedido são aqueles padronizados na API. Os mesmos podem ser consultados na seção [Status de Pedidos](/pedidos/status-de-pedidos.md). Caso a conta tenha cadastrado outros status, é importante a utilização dos criados. A utilização de um status que não existe na conta retornará erro **422**. {% endhint %} ### **Atualizar para faturado (INVOICED)** A forma padrão de faturar um pedido é através do envio da chave da nota fiscal, ou seja, envio dos 44 dígitos da NFe. O faturamento através do envio da chave da NFe deve ser utilizado para pedidos **Correios** ou logística própria e sua requisição consiste em um POST contendo os [headers](#request-headers) apresentados acima para o endpoint: ``` https://api.skyhub.com.br/orders/{code}/invoice ``` {% hint style="danger" %} Pedidos gerados para o serviço Direct devem seguir as orientações do artigo [Faturamento Pedido - Americanas Entrega Direct](/pedidos/faturamento-pedido-americanas-entrega-direct.md). {% endhint %} #### Request body: ``` { "status": "order_invoiced", "invoice": { "key": "99999999999999999999999999999999999999999999", "issue_date": "AAAA-MM-DDTHH:MM:SS-03:00" } } ``` {% hint style="info" %} O campo `issue_date` é opcional na requisição apresentada. Caso opte por não enviá-lo, é importante estar ciente de que a API assumirá para este campo os seguintes valores: * **issue\_date:** Serão assumidos data e hora do momento em que a API enviar a requisição de faturamento ao marketplace; {% endhint %} {% hint style="warning" %} Será gerado uma etiqueta para cada entrega. {% endhint %} #### Example request: ``` curl --location --request POST 'https://api.skyhub.com.br/orders/Lojas Americanas-1000000000000/invoice' \ --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 '{ "status": "order_invoiced", "invoice": { "key": "99999999999999999999999999999999999999999999", "issue_date": "2023-03-10T12:30:00-03:00" } }' ``` #### Response esperado: {% hint style="success" %} 204 \[Success] - No content {% endhint %} ### Atualizar para enviado para a transportadora (SHIPPED) Após o faturamento, o pedido que for entregue para a transportadora deverá ter o seu status atualizado via API. Na operação de atualização para o status SHIPPED são informados os dados de rastreamento da entrega, como tipo de envio, código de rastreio, URL para rastreamento, dentre outros. A requisição para atualização do status SHIPPED consiste em um POST contendo os [headers](#request-headers) apresentados no início desta página para o endpoint: ``` https://api.skyhub.com.br/orders/{code}/shipments ``` #### Request body: ``` { "status": "order_shipped", "shipment": { "code": "{code}", "delivered_carrier_date": "AAAA-MM-DDTHH:MM:SS-03:00", "items": [ { "sku": "{sku}", "qty": 1 } ], "track": { "code": "{Código de rastreio}", "carrier": "Correios", "method": "SEDEX", "url": "www.correios.com.br" } } } ``` {% hint style="info" %} Para atualização do status "*shipped*" é necessário informar o **SKU adquirido na compra**. Isto é, caso o pedido tenha sido realizado para um produto que contém variações, a atualização para o *shipped* requer que seja informado o **SKU da variação** e não do produto pai/agrupador. {% endhint %} {% hint style="warning" %} Ao utilizar o endpoint **POST /orders/{CODIGO}/shipments**, o campo **shipment.track.code**, é obrigatório {% endhint %} #### Example request: ``` curl --location --request POST 'https://api.skyhub.com.br/orders/Lojas Americanas-1000000000000/shipments' \ --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 '{ "status": "order_shipped", "shipment": { "code": "Lojas Americanas-1000000000000", "delivered_carrier_date": "2023-03-10T17:00:00-03:00", "items": [ { "sku": "2023001", "qty": 1 } ], "track": { "code": "BR1122334455", "carrier": "Correios", "method": "SEDEX", "url": "www.correios.com.br" } } }' ``` #### Response esperado: {% hint style="success" %} 204 \[Success] - No content {% endhint %} ### Atualizar para entregue ao cliente (DELIVERED) Quando o pedido chega ao seu destino, o status da entrega deve ser enviado via API para que o fluxo seja finalizado. A atualização para o status DELIVERED consiste em um POST contendo os [headers](#request-headers) apresentados no início desta página para o endpoint: ``` https://api.skyhub.com.br/orders/{code}/delivery ``` #### Request body: ``` { "status": "complete", "delivered_date": "DD/MM/AAAA" } ``` {% hint style="warning" %} Importante encaminhar a data correta no campo **delivered\_date**. Uma vez que esta informação não for devidamente enviada, a entrega assumirá a data/hora em que a atualização do status for encaminhada da API para o marketplace. {% endhint %} #### Example request: ``` curl --location --request POST 'https://api.skyhub.com.br/orders/Lojas Americanas-1000000000000/delivery' \ --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 '{ "status": "complete", "delivered_date": "13/03/2023" }' ``` #### Response esperado: {% hint style="success" %} 204 \[Success] - No content {% endhint %} ## Outros status O ciclo de vida comum para um pedido consiste em sua **criação** (NEW), **aprovação** (APPROVED), **faturamento** (INVOICED), **envio** para a transportadora (SHIPPED) e **entrega** ao cliente (DELIVERED), porém podem ocorrer eventualidades durante o fluxo, como o **cancelamento** (CANCEL) ou um **atraso** na entrega (SHIPMENT\_EXCEPTION). ### Cancelar pedido (CANCEL) Em um ambiente de produção, o cancelamento de um pedido pode ser realizado pelo cliente responsável pela compra ou pelo *seller* (lojista). Em ambiente de teste, é possível simular o cancelamento e para isto deve ser executado um POST contendo os [headers](#request-headers) apresentados no início desta página para o endpoint: ``` https://api.skyhub.com.br/orders/{code}/cancel ``` #### Request body: ``` { "status": "order_canceled" } ``` #### Example request: ``` curl --location --request POST 'https://api.skyhub.com.br/orders/Lojas Americanas-1200000000002/cancel' \ --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 '{ "status": "order_canceled" }' ``` #### Response esperado: {% hint style="success" %} 204 \[Success] - No content {% endhint %} ### Exceção de entrega (SHIPMENT\_EXCEPTION) A exceção de entrega se refere a quando o transporte de uma mercadoria apresentou quaisquer problemas. A notificação deste problema via API é realizada através de um POST contendo os [headers](#request-headers) apresentados no início desta página para o endpoint: ``` https://api.skyhub.com.br/orders/{code}/shipment_exception ``` #### Request body: ``` { "shipment_exception": { "occurrence_date": "AAAA-MM-DDTHH:MM:SS+00:00", "observation": "Temporary delay" } } ``` #### Example request: ``` curl --location --request POST 'https://api.skyhub.com.br/orders/Lojas Americanas-1300000000003/shipment_exception' \ --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 '{ "shipment_exception": { "occurrence_date": "2023-03-10T19:30:00+00:00", "observation": "Problemas com a transportadora selecionada" } }' ``` #### 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/atualizacao-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.