</Pedidos>
PEDIDOS (/api/Order)
São as informações de um pedido feito por um cliente para um marketplace integrado ao Magalu Marketplace, nele ficam as informações do cliente, das notas e dos status do pedido. Os status possíveis são:
- (-1) - NEW - Pedidos novos
- (0) - APPROVED - Pedido aprovado (pagamento OK)
- (1) - PROCESSING - Pedido aguardando emissão de nota fiscal
- (2) - INVOICED - Pedido aguardando expedição
- (3) - SHIPPED - Pedido aguardando entrega
- (4) - DELIVERED - Pedido entregue
- (5) - SHIPMENT_EXCEPTION - Pedido com exceção de transporte
- (6) - UNAVAILABLE - Pedido sem estoque
- (7) - CANCELED - Pedido cancelado
Fluxo normal de Status
Order
No Magalu Marketplace os 2 primeiros status de um pedido ocorrem dentro da plataforma. Um pedido entra como novo (NEW). Depois ele pode ser aprovado (APPROVED) ou cancelado (CANCELED) pelo marketplace. Após ser aprovado é necessário que o parceiro(ERP,Loja...etc) mude o status para processando(PROCESSING) para indicar que o pedido já encontra-se em separação e fica aguardando os próximos status que são: Nota Fiscal (INVOICED), Enviado (SHIPPED) ou Entregue (DELIVERED).
Os status de NEW para APPROVED são atualizados automaticamente no Integra, conforme o Marketplace informa esses novos status. No status NEW o pedido ainda não foi aprovado. Desta forma não há ainda movimentação em estoque, o Integra possui um sistema de reserva de estoque. Que pode ser configurado diretamente no painel quantos dias o produto ficará na reserva. Até que um pedido seja realmente pago. Só então o estoque é realmente descontado.
Caso o parceiro não possa trabalhar dessa forma. É necessário trabalhar apenas com pedidos APPROVED. Deixando os pedidos em Status NEW de lado. E inserir no ERP ou em outros sistemas, apenas quando os pedidos forem Aprovados.
Ao atualizar a informação de status do pedido, os seguintes Status devem ser utilizados: PROCESSING, INVOICED, SHIPPED, DELIVERED, SHIPMENT_EXCEPTION ou CANCELED. Cada Status atualizado deve seguir uma ordem crescente, ou seja, se o Status está em Shipped(Despachado) o mesmo não pode retornar para um status anterior, como Invoiced(Nota Fiscal Emitida).
SISTEMA DE FILAS API INTEGRA
O sistema de filas tem como objetivo facilitar a leitura de inserções e atualizações de itens da API Integra. Por exemplo, a atualização de um SKU, será disponibilidade na sua fila (SkuQueue). Sendo assim, após verificar que ocorreu a atualização deve-se consultar o SKU para ler os dados atualizados.
Como todo sistema de fila, o primeiro a chegar é o primeiro a sair, então considerando que as filas têm um limite de 100 itens, somente irão aparecer novos itens à medida que os itens da fila são confirmados (consumidos).
Para consumir os itens da fila é necessário enviar os Ids da OrderQueue. Deve ser atentar que não se trata do Id do SKU ou do ORDER. Todas as filas seguem o mesmo padrão de consumo através de uma chamada PUT, onde passa como parâmetro a lista de Ids, como no exemplo abaixo:
O retorno em caso de sucesso é 204 (No content), caso contrário é retornado apenas os itens que não foram possíveis a confirmação, os demais serão confirmados (consumidos).
Fila de pedidos (OrderQueue)
Nessa fila serão disponibilizados os novos pedidos (NEW) e as alterações de status de pedido que vieram do Marketplace (APPROVED, CANCELED).
Ao fazer o GET dos pedidos com status APPROVED e confirmar o consumo destes pedidos na OrderQueue, é necessário um novo PUT, mas desta vez em Orders atualizando o status do pedido de APPROVED para PROCESSING.
Chamada:/api/OrderQueue
Demais Status
O parceiro tambem pode enviar três tipos de exeções do status de pedido.
Cancelado (CANCELED): pode ser enviado a partir qualquer status do fluxo normal.
Exceção de Transporte (SHIPMENT_EXCEPTION): pode ser enviado a partir qualquer status do fluxo normal.
Pedido sem estoque (UNAVAILABLE): pode ser enviado a partir qualquer status do fluxo normal.
Campos Obrigatórios para cada Status
Nos pedidos a obrigatoriedade dos campos depende do status. A mudança do status do pedido para um atual , tem que corresponder a um status válido , ou seja ele não pode voltar para um status anterior.
| STATUS | CAMPO | DESCRIÇÃO | OBRIGATORIEDADE |
|---|---|---|---|
| processing | |||
| "IdOrder": "string" | Id do pedido | X | |
| "OrderStatus": "PROCESSING" | Status do pedido | X | |
| invoiced | |||
| "IdOrder": "string" | Id do pedido | X | |
| "OrderStatus": "INVOICED" | Status do pedido | X | |
| "InvoicedNumber": "string" | Numero da Nota Fiscal | X | |
| "InvoicedLine": 0 | Série da Nota Fiscal | X | |
| "InvoicedIssueDate": "2016-06-23T10:59:50.381Z" | Data de Emissão da Fatura | X | |
| "InvoicedKey": "string" | Chave da Nota Fiscal | X | |
| "InvoicedDanfeXml": "string" | Xml da Nota Fiscal | ||
| shipped | |||
| "IdOrder": "string" | Id do pedido | X | |
| "OrderStatus": "SHIPPED" | Status do pedido | X | |
| "ShippedTrackingUrl": "string" | Url de Rastreio | ||
| "ShippedTrackingProtocol": "string" | Código de Rastreio | X | |
| "ShippedEstimatedDelivery": "2016-06-23T10:59:50.381Z" | Data estimativa de Entrega | ||
| "ShippedCarrierDate": "2016-06-23T10:59:50.381Z" | Data Entrega a Transportadora | X | |
| "ShippedCarrierName": "string" | Nome da Transportadora | X | |
| delivered | |||
| "IdOrder": "string" | Id do pedido | X | |
| "OrderStatus": "DELIVERED" | Status do pedido | X | |
| "DeliveredDate": "2016-06-23T10:59:50.381Z" | Data da entrega ao cliente | X | |
| shipmentException | |||
| "IdOrder": "string" | Id do pedido | X | |
| "OrderStatus": "SHIPMENTEXCEPTION" | Status do pedido | X | |
| "ShipmentExceptionObservation": "string" | Observação em caso de falha | X | |
| "ShipmentExceptionOccurrenceDate": "2016-06-23T10:59:50.381Z" | Data em que houve falha | X |
Métodos
Order
Atualizar Pedido
Metodo: PUT
Endpoint:(/api/Order)
Verifique no Swagger o exemplo de json's para alteração de status
{
"IdOrder": "string", /*Obrigatório: Pedido deve existir */
"IdOrderMarketplace": "string", /* Id do Pedido no Marketplace */
"InsertedDate": "2016-06-23T10:59:50.381Z", /* Data de Insersão do pedido */
"PurchasedDate": "2016-06-23T10:59:50.381Z", /* Data da Compra */
"ApprovedDate": "2016-06-23T10:59:50.381Z", /* Data de Aprovação */
"UpdatedDate": "2016-06-23T10:59:50.381Z", /* Data do ultimo Update */
"MarketplaceName": "string", /* Nome do Marketplace: b2w | cnova | carrefour | vtex| mobly | magazineluiza | dafiti | tricae */
"StoreName": "string", /* Nome da Loja do Marketplace: (SHOPTIME, SUBMARINO, LOJASAMERICANAS) VTEX | MOBLY | magazineluiza | DAFITI | TRICAE */
"UpdatedMarketplaceStatus": true, /*Está atualizado no Marketplace? (true/false)*/
"InsertedErp": true, /*Está inserido no ERP? (true/false)*/
"EstimatedDeliveryDate": "2016-06-23T10:59:50.381Z", /* Data de Previsão de entrega*/
"CustomerPfCpf": "string", /* CPF do Consumidor */
"CustomerPfName": "string", /* Nome do Consumidor */
"CustomerPjCnpj": "string", /* CNPJ - Pessoa Juridica */
"CustomerPjCorporatename": "string", /* Nome da Empresa */
"DeliveryAddressStreet": "string", /* Rua de Entrega */
"DeliveryAddressAdditionalInfo": "string", /* Informações Adicionais de Entrega*/
"DeliveryAddressZipcode": "string", /* CEP */
"DeliveryAddressNeighborhood": "string", /* Bairro */
"DeliveryAddressCity": "string", /* Cidade */
"DeliveryAddressReference": "string", /* Ponto de Referencia */
"DeliveryAddressState": "string", /* Estado */
"DeliveryAddressNumber": "string", /* Numero do Endereço */
"TelephoneMainNumber": "string", /* Telefone Principal */
"TelephoneSecundaryNumber": "string", /* Telefone Secundario */
"TelephoneBusinessNumber": "string", /* Telefone Comercial */
"TotalAmount": "string", /* Total da Compra */
"TotalFreight": "string", /* Valor do Frete */
"TotalDiscount": "string", /* Desconto */
"CustomerBirthDate": "string", /* Data de Nascimento do Cliente */
"CustomerPjIe": "string", /* Inscrição Estadual*/
"OrderStatus": "string", /* Obrigatório: VER REGRAS ACIMA*/
"InvoicedNumber": "string", /* Numero da Nota Fiscal */
"InvoicedLine": 0, /* Série da Nota Fiscal */
"InvoicedIssueDate": "2016-06-23T10:59:50.381Z", /* Data de Emissão Faturamento */
"InvoicedKey": "string", /* Chave da Nota Fiscal */
"InvoicedDanfeXml": "string", /* Xml da Nota Fiscal */
"ShippedTrackingUrl": "string", /* Url de Rastreio */
"ShippedTrackingProtocol": "string", /* Código de Rastreio*/
"ShippedEstimatedDelivery": "2016-06-23T10:59:50.381Z", /* Data estimativa de Entrega */
"ShippedCarrierDate": "2016-06-23T10:59:50.381Z", /* Data Entrega a Transportadora */
"ShippedCarrierName": "string", /* Nome da Transportadora */
"ShipmentExceptionObservation": "string", /* Observação em caso de falha*/
"ShipmentExceptionOccurrenceDate": "2016-06-23T10:59:50.381Z", /* Data em que houve falha*/
"DeliveredDate": "2016-06-23T10:59:50.381Z", /* Data da Engrega ao cliente */
"Products": [
{ /* Lista de Produtos comprados */
"IdSku": "string",
"Quantity": 0,
"Price": "string",
"Freight": "string",
"Discount": "string"
}
],
"Payments": [
{
"Name": "string",
"Installments": 0,
"Amount": 0
}
]
}
Consultar vários Pedidos
Metodo: GET
Endpoint:(/api/Order)
Exemplo Response Body:
{
"Page": 1,
"PerPage": 1,
"Total": 16782,
"Orders": [
{
"IdOrder": "B2W-123456789",
"IdOrderMarketplace": "01-123456998",
"InsertedDate": "2016-06-09T13:00:05.057",
"PurchasedDate": "2016-06-09T12:46:26",
"ApprovedDate": "2016-06-09T13:04:28",
"UpdatedDate": "2016-06-09T12:54:25",
"MarketplaceName": "B2W",
"StoreName": "SHOPTIME",
"UpdatedMarketplaceStatus": true,
"InsertedErp": true,
"EstimatedDeliveryDate": "2016-06-22T00:00:00",
"CustomerPfCpf": "123456",
"CustomerPfName": "Pato Donalds da Silva Quack",
"CustomerPjCnpj": null,
"CustomerPjCorporatename": null,
"DeliveryAddressStreet": "Rua Patinhas Milinhoario",
"DeliveryAddressAdditionalInfo": "casa 1",
"DeliveryAddressZipcode": "112233",
"DeliveryAddressNeighborhood": "Bairro Cidade",
"DeliveryAddressCity": "Cidade",
"DeliveryAddressReference": null,
"DeliveryAddressState": "SP",
"DeliveryAddressNumber": "247",
"TelephoneMainNumber": "2233558899",
"TelephoneSecundaryNumber": "1122558855",
"TelephoneBusinessNumber": "22558899",
"TotalAmount": "82,11",
"TotalFreight": "47,34",
"TotalDiscount": "0,0",
"CustomerBirthDate": null,
"CustomerPjIe": null,
"OrderStatus": "DELIVERED",
"InvoicedNumber": "00111122",
"InvoicedLine": 1,
"InvoicedIssueDate": "2016-06-09T16:44:17.93",
"InvoicedKey": "1111111111111111111111111111111111111111111111",
"InvoicedDanfeXml": "",
"ShippedTrackingUrl": "",
"ShippedTrackingProtocol": "",
"ShippedEstimatedDelivery": "2016-06-22T00:00:00",
"ShippedCarrierDate": "2016-06-10T09:30:03.42",
"ShippedCarrierName": "Total",
"ShipmentExceptionObservation": null,
"ShipmentExceptionOccurrenceDate": null,
"DeliveredDate": "2016-06-14T23:29:15.08",
"Products": [
{
"IdSku": "1111111",
"Quantity": 1,
"Price": "13,31",
"Freight": "2,25",
"Discount": "0,0"
},
{
"IdSku": "2222222",
"Quantity": 1,
"Price": "10,73",
"Freight": "22,55",
"Discount": "0,0"
}
],
"Payments": [
{
"Name": "string",
"Installments": 0,
"Amount": 0
}
]
}
]
}
Consultar um pedido
Metodo: GET
Endpoint:(/api/Order/{id})
Exemplo Response Body:
{
"IdOrder": "B2W-123456789",
"IdOrderMarketplace": "01-123456998",
"InsertedDate": "2016-06-09T13:00:05.057",
"PurchasedDate": "2016-06-09T12:46:26",
"ApprovedDate": "2016-06-09T13:04:28",
"UpdatedDate": "2016-06-09T12:54:25",
"MarketplaceName": "B2W",
"StoreName": "SHOPTIME",
"UpdatedMarketplaceStatus": true,
"InsertedErp": true,
"EstimatedDeliveryDate": "2016-06-22T00:00:00",
"CustomerPfCpf": "123456",
"CustomerPfName": "Pato Donalds da Silva Quack",
"CustomerPjCnpj": null,
"CustomerPjCorporatename": null,
"DeliveryAddressStreet": "Rua Patinhas Milinhoario",
"DeliveryAddressAdditionalInfo": "casa 1",
"DeliveryAddressZipcode": "112233",
"DeliveryAddressNeighborhood": "Bairro Cidade",
"DeliveryAddressCity": "Cidade",
"DeliveryAddressReference": null,
"DeliveryAddressState": "SP",
"DeliveryAddressNumber": "247",
"TelephoneMainNumber": "2233558899",
"TelephoneSecundaryNumber": "1122558855",
"TelephoneBusinessNumber": "22558899",
"TotalAmount": "82,11",
"TotalFreight": "47,34",
"TotalDiscount": "0,0",
"CustomerBirthDate": null,
"CustomerPjIe": null,
"OrderStatus": "DELIVERED",
"InvoicedNumber": "00111122",
"InvoicedLine": 1,
"InvoicedIssueDate": "2016-06-09T16:44:17.93",
"InvoicedKey": "1111111111111111111111111111111111111111111111",
"InvoicedDanfeXml": "",
"ShippedTrackingUrl": "",
"ShippedTrackingProtocol": "",
"ShippedEstimatedDelivery": "2016-06-22T00:00:00",
"ShippedCarrierDate": "2016-06-10T09:30:03.42",
"ShippedCarrierName": "Total",
"ShipmentExceptionObservation": null,
"ShipmentExceptionOccurrenceDate": null,
"DeliveredDate": "2016-06-14T23:29:15.08",
"Products": [
{
"IdSku": "1111111",
"Quantity": 1,
"Price": "13,31",
"Freight": "2,25",
"Discount": "0,0"
},
{
"IdSku": "2222222",
"Quantity": 1,
"Price": "10,73",
"Freight": "22,55",
"Discount": "0,0"
}
],
"Payments": [
{
"Name": "string",
"Installments": 0,
"Amount": 0
}
]
}
OrderQueue
Recuperar novos pedidos e atualizações de status provenientes do Marketplace
Metodo: GET
Endpoint:(/api/OrderQueue})
Exemplo Response Body:
{
"Total": 0,
"OrderQueues": [
{
"Id": 0,
"IdOrder": "string",
"IdOrderMarketplace": "string",
"InsertedDate": "2017-05-17T20:09:59.426Z",
"OrderStatus": "string"
}
]
}
Este método insere os Pedidos que foram consumidos da fila.
Metodo: PUT
Endpoint:(/api/OrderQueue})
Exemplo do parametro ordersVm:
[
{
"Id": 0
},
{
"Id": 1
}
]