A Netshoes disponibiliza a possibilidade de requisitar o romaneio/etiquetas via API, para sellers que utilizam o serviço de entrega Magalu Entregas, e assim unificar os processos junto as integradoras.
Para isso, disponibilizamos através do POST /api/v1/orders/shipping-tags, com a possibilidade de teste em ambiente SANDBOX.
Descrição API
Headers:
{
"client_id": "client_id"
"access_token":"access_token"
}
Onde:
client_id:
O APP Token usado para autenticar.
access_token:
O Access Token usado para autenticar.
Payload request exemplo:
{
"documentType": "ZEBRA",
"shippingCodes": [
860858200
]
}
Onde:
documentType:
Tipo de arquivo solicitado (A4 OU ZEBRA).
shippingCodes:
Lista de Shipping Code para serem geradas etiquetas.
Payload sucesso response exemplo:
[
{
"trackingGroupNumber": "62cc2fdd0ee9d64a1e2221b2",
"trackingGroupStatus": "GENERATED",
"labelStatus": "NOT_VIEWED",
"createdDate": "2022-07-11T11:12:45.155",
"tag": {
"url": "http://mocked"
},
"trackings": [
{
"shippingCode": 860858200,
"trackingCode": "E95C18003DB9457A",
"trackingStatus": "GENERATED",
"labelStatus": "NOT_VIEWED",
"trackingLink": "http://mocked"
}
]
}
]
Onde:
trackingGroupNumber:
Código agrupador de etiquetas.
trackingGroupStatus:
Status do Código agrupador de etiquetas, que pode ser: PROCESSING, GENERATED, ERROR, DISCARDED, SHIPPED, DELIVERED, EXTERNALLY_SENT.
labelStatus:
Status de visualização do Código agrupador de etiquetas.
createdDate:
Data de criação do Código agrupador de etiquetas.
tag.url:
URL do arquivo contendo as etiquetas do agrupamento (lote) de etiquetas para o formato solicitado.
trackings.shippingCode:
Shipping Code solicitado.
trackings.trackingCode:
Código de rastreio.
trackings.trackingStatus:
Status do tracking.
trackings.labelStatus:
Status de visualização do rastreio.
trackings.trackingLink:
Link de rastreio.
Payload erro response exemplo:
{
"errors": [
{
"code": 2,
"description": "It is only possible to request a pickup label for invoiced orders",
"informationCodes": [
2,
3
]
}
]
}
Onde:
Code:
Código de erro relativo a validação feita (conforme a tabela abaixo) e não a um tipo de erro HTTP.
description:
Descrição do erro.
informationCodes:
Lista de shippingCode que apresentaram algum tipo de erro. Não retorna em todos os casos.
| Code | Retorno PT_BR | Retorno EN_US |
| 1 - Não é Magalu Entregas | Pedido com serviço de envio diferente de Magalu Entregas. Somente é possível requisitar etiquetas para pedidos com serviço de envio via Magalu Entregas. | There are Orders with shipping gateway different from Magalu Entregas. It is only possible to request pickup labels for orders with shipping gateway service as Magalu Entregas. |
| 2 - Status Inválido | Somente é possível solicitar etiqueta para pedido com status faturado. | It is only possible to request a pickup label for invoiced orders. |
| 3 - Não Integrado ao Magalu Pagamentos | Pedido em processo de integração. Por favor, tente novamente dentro de alguns minutos. | Order has been integrated. Please try again in a few minutes. |
| 4 - Não Implementado | Funcionalidade desabilitada. | Feature disabled. |
| 5 - Em Processamento | Etiqueta já solicitada, por favor, aguarde o processamento. | Pickup label already requested. Please wait for processing. |
| 6 - Entidade Não Processável | Erro na geração. Tente novamente. | Generation error. Try again. |
| 7 - Pedido não encontrado | Pedido não localizado no serviço de geração de etiquetas. | Order not found in pickup label service. |
| 8 - Formato Inválido | Tipo de documento solicitado não existe | File format does not exists |
| 9 - Nenhuma entrega encontrada | Pedido não localizado para o lojista em referência. | Order not found for the seller in question. |
| 10 - Pedidos com estorno automático | Pedido(s) com solicitação de estorno já realizada. | There are orders with automatic refund already requested. |
Regras do Processo de Validação de Etiquetas:
Critérios para solicitação de etiquetas:
- ● Pedidos Magalu Entregas;
- ● Pedidos Faturados;
- ● Pedidos com integração de faturamento completos;
- ● Pedidos sem uma prévia solicitação de etiquetas;
- ● Pedidos com prévia solicitação de etiquetas que tenha retornado um status de erro de geração;
- ● Pedidos com prévia solicitação com sucesso na geração porém ainda com status FATURADOS;
- ● Pedidos sem solicitação de estorno já realizada.
Respostas:
| 200 | Success | Entregas solicitadas foram encontradas na base e suas respectivas etiquetas foram geradas e payload com links de acesso das etiquetas solicitadas será retornado (link etiqueta + link romaneio/rastreio) / "Delivery ids found and pickup sent to Logistics." |
| 400 | Request invalid or malformed | Erro ao não respeitar alguns dos critérios citados na seção anterior; |
| 401 | Unauthorized | Credenciais de autenticação fornecidas são inválidas. |
| 403 | Forbidden | Não foi possível validar as credenciais de autenticação fornecidas. |
| 404 | Not Found | ○ Pedido não encontrado no serviço de solicitação de etiquetas. ○ Nenhum pedido encontrato com os parâmetros passados; |
| 409 | Conflict | Erro de conflito para solicitações simultâneas contendo pelo menos um shippingCode em comum entre elas; |
| 422 | Unprocessable Entity | Erro na Geração de etiquetas. |
| 423 | Locked | Funcionalidade desabilitada. |
| 500 | Internal Server Error | Erro de disponibilidade do serviço. |
Importante salientar que:
Em caso de erro em pelo menos uma entrega/pedido, o endpoint irá retornar uma mensagem de erro e as etiquetas solicitadas poderão ser solicitadas novamente. OBS: Podem existir casos de solicitação em que o lote pode ser devolvido parcialmente, vide Cenário 11.
Cenários de solicitação de etiquetas
Cenário 01:
Input: shippingCodes 1,2,3 válidos e requisição realizada com sucesso
{
"documentType": "A4",
"shippingCodes": [
1,
2,
3
]
}
Output: Status 200
{
"pickupTrackingGroupResponses": [
{
"createdDate": "2022-08-01T00:44:38.525Z",
"labelStatus": "labelStatus",
"tag": {
"url": "href"
},
"trackingGroupNumber": "trackingGroupNumber",
"trackingGroupStatus": "trackingGroupStatus",
"trackings": [
{
"externalTrackingCode": "externalTrackingCode",
"labelStatus": "labelStatus",
"shippingCode": 1,
"trackingCode": "trackingCode",
"trackingLink": "trackingLink",
"trackingStatus": "trackingStatus"
},
{
"externalTrackingCode": "externalTrackingCode",
"labelStatus": "labelStatus",
"shippingCode": 2,
"trackingCode": "trackingCode",
"trackingLink": "trackingLink",
"trackingStatus": "trackingStatus"
},
{
"externalTrackingCode": "externalTrackingCode",
"labelStatus": "labelStatus",
"shippingCode": 3,
"trackingCode": "trackingCode",
"trackingLink": "trackingLink",
"trackingStatus": "trackingStatus"
}
]
}
]
}
Cenário 02:
Input: shippingCodes 1 válido, 2 e 3 com erro (pedidos com serviço de envio diferente de Magalu Entregas)
{
"documentType": "A4",
"shippingCodes": [
1,
2,
3
]
}
Output: Status 400
{
"errors": [
{
"code": 1,
"description": "There are Orders with shipping gateway different from Magalu Entregas. It is only possible to request pickup labels for orders with shipping gateway service as Magalu Entregas.",
"informationCodes": [
2,
3
]
}
]
}
Cenário 03:
Input: shippingCodes 1 válido, 2 e 3 com erro (pedidos com status diferentes de faturado)
{
"documentType": "A4",
"shippingCodes": [
1,
2,
3
]
}
Output: Status 400
{
"errors": [
{
"code": 2,
"description": "It is only possible to request a pickup label for invoiced orders",
"informationCodes": [
2,
3
]
}
]
}
Cenário 04:
Input: shippingCodes 1 válido, 2 e 3 com erro (pedidos faturados, porém ainda não finalizaram a integração com o ecossistema do Magalu Entregas, para assim permitir emissão de etiqueta)
{
"documentType": "A4",
"shippingCodes": [
1,
2,
3
]
}
Output: Status 400
{
"errors": [
{
"code": 3,
"description": "Order has been integrated. Please try again in a few minutes.",
"informationCodes": [
2,
3
]
}
]
}
Cenário 05:
Input: shippingCodes 1 válido, 2 e 3 com erro (mais de uma requisição simultânea para o mesmo Shipping Code em processamento).
{
"documentType": "A4",
"shippingCodes": [
1,
2,
3
]
}
Output: Status 400/409
{
"errors": [
{
"code": 5,
"description": "Pickup label already requested. Please wait for processing."
}
]
}
Cenário 06:
Input: shippingCodes 1, 2 e 3 válidos, porém erro de integração com o serviço do Magalu Entregas.
{
"documentType": "A4",
"shippingCodes": [
1,
2,
3
]
}
Output: Status 422
{
"errors": [
{
"code": 6,
"description": "Generation error. Try again."
}
]
}
Cenário 07:
Input: shippingCodes 1, 2 e 3 não existentes para o lojista requisitante
{
"documentType": "A4",
"shippingCodes": [
1,
2,
3
]
}
Output: Status 404
{
"errors": [
{
"code": 9,
"description": "Order not found for the seller in question."
}
]
}
Cenário 08:
Input: shippingCodes 1, 2 e 3 válidos porém com retorno NOT_FOUND do Magalu Entregas.
{
"documentType": "A4",
"shippingCodes": [
1,
2,
3
]
}
Output: Status 404
{
"errors": [
{
"code": 7,
"description": "Order not found in pickup label service."
}
]
}
Cenário 09:
Input: shippingCodes:
| shippingCode | Magalu Entregas | Faturado | Processado |
| 1 | N | N | N |
| 2 | S | N | N |
| 3 | S | S | N |
| 4 | S | S | S |
| 5 | N | S | S |
{
"documentType": "A4",
"shippingCodes": [
1,
2,
3,
4,
5,
]
}
Output: Status 400
{
"errors": [
{
"code": 1,
"description": "There are Orders with shipping gateway different from Magalu Entregas. It is only possible to request pickup labels for orders with shipping gateway service as Magalu Entregas.",
"informationCodes": [
1,
5
]
},
{
"code": 2,
"description": "It is only possible to request a pickup label for invoiced orders",
"informationCodes": [
2,
]
},
{
"code": 3,
"description": "Order has been integrated. Please try again in a few minutes.",
"informationCodes": [
3
]
}
]
}
Cenário 10:
Input: shippingCodes 1, 2 e 3 válidos porém o tipo de etiqueta solicitado não é A4 ou ZEBRA
{
"documentType": "X8",
"shippingCodes": [
1,
2,
3
]
}
Output: Status 400
{
"errors": [
{
"code": 8,
"description": "File format does not exists."
}
]
}
Cenário 11:
Input: shippingCodes 1 válido, 2 e 3 não existentes para o lojista requisitante.
{
"documentType": "A4",
"shippingCodes": [
1,
2,
3
]
}
Output: Status 200
{
"pickupTrackingGroupResponses": [
{
"createdDate": "2022-08-01T00:44:38.525Z",
"labelStatus": "labelStatus",
"tag": {
"url": "href"
},
"trackingGroupNumber": "trackingGroupNumber",
"trackingGroupStatus": "trackingGroupStatus",
"trackings": [
{
"externalTrackingCode": "externalTrackingCode",
"labelStatus": "labelStatus",
"shippingCode": 1,
"trackingCode": "trackingCode",
"trackingLink": "trackingLink",
"trackingStatus": "trackingStatus"
}
]
}
]
}
Cenário 12:
Input: shippingCodes 9.
{
"documentType": "X8",
"shippingCodes": [9]
}
Output: Status 200
{
"pickupTrackingGroupResponses": [
{
"createdDate": "2022-08-01T00:44:38.525Z",
"labelStatus": "labelStatus",
"tag": {
"url": "href"
},
"trackingGroupNumber": "trackingGroupNumber",
"trackingGroupStatus": "trackingGroupStatus",
"trackings": [
{
"externalTrackingCode": "externalTrackingCode",
"labelStatus": "labelStatus",
"shippingCode": 1,
"trackingCode": "trackingCode",
"trackingLink": "trackingLink",
"trackingStatus": "trackingStatus"
}
]
}
]
}
Simulação em ambiente sandbox
Para simular os possíveis retornos da API em sandbox usar a tabela abaixo:
| Cenário | Shipping Code final | Retorno PT_BR | Retorno EN_US |
| Cenário 01 | 1 | Cenário de sucesso | Success scenario |
| Cenário 02 | 2 | Pedido com serviço de envio diferente de Magalu Entregas. Somente é possível requisitar etiquetas para pedidos com serviço de envio via Magalu Entregas. | There are Orders with shipping gateway different from Magalu Entregas. It is only possible to request pickup labels for orders with shipping gateway service as Magalu Entregas. |
| Cenário 03 | 3 | Somente é possível solicitar etiqueta para pedido com status faturado. | It is only possible to request a pickup label for invoiced orders. |
| Cenário 04 | 4 | Pedido em processo de integração. Por favor, tente novamente dentro de alguns minutos. | Order has been integrated. Please try again in a few minutes |
| Cenário 05 | 5 | Etiqueta já solicitada, por favor, aguarde o processamento. | Pickup label already requested. Please wait for processing. |
| Cenário 06 | 6 | Erro na geração. Tente novamente. | Generation error. Try again. |
| Cenário 07 | 7 | Pedido não localizado para o lojista em referência. | Order not found for the seller in question. |
| Cenário 08 | 8 | Pedido não localizado no serviço de geração de etiquetas. | Order not found in pickup label service. |
| Cenário 09 | envie uma lista de shippingCodes com finais 2,3 e 4 na mesma requisição | Pedido com serviço de envio diferente de Magalu Entregas. Somente é possível requisitar etiquetas para pedidos com serviço de envio via Magalu Entregas.; Somente é possível solicitar etiqueta para pedido com status faturado; Pedido em processo de integração. Por favor, tente novamente dentro de alguns minutos. | There are Orders with shipping gateway different from Magalu Entregas. It is only possible to request pickup labels for orders with shipping gateway service as Magalu Entregas; It is only possible to request a pickup label for invoiced orders; Order has been integrated. Please try again in a few minutes |
| Cenário 10 | envie uma requisição com final 1 e um documentType invalido | Tipo de documento solicitado não existe. | File format does not exists. |
| Cenário 11 | envie uma lista de shippingCodes que tenha final 1 e um ou mais shipping code inexistentes | Shipping Codes encontrados e etiquetas enviadas a Logística. | Shipping Codes found and pickup sent to Logistics. |
| Cenário 12 | 9 | Pedido(s) com solicitação de estorno já realizada. | There are orders with automatic refund already requested. |
Para outros cenários:
Cenário onde se envia um payload vazio:
Input:
{
}
Output: Status 400
{
"errors": [
"shippingCodes:Number of values allowed in request must be between 1 and 50.",
"shippingCodes:Field can not be null.",
"shippingCodes:Field can not be empty.",
"documentType:Field can not be empty."
]
}
Cenário número de shippingCodes maior do que o suportado pela API (máx: 50 etiquetas):
Input:
{
"documentType": "ZEBRA",
"shippingCodes": [
860858200, ... , 160858200
]
}
Output: Status 400
{
"errors": [
"shippingCodes:Number of values allowed in request must be between 1 and 50."
]
}
Cenário onde o fluxo está desabilitado:
Input: shippingCodes 1, 2 e 3 válidos, mas o fluxo está desabilitado.
{
"documentType": "A4",
"shippingCodes": [
1,
2,
3
]
}
Output: Status 423
{
"errors": [
{
"code": 4,
"description": "Locked."
}
]
}
Informações adicionais
Idioma da descrição do retorno de erro:
As mensagens de erro sempre serão exibidas de acordo com o locale do serviço que está fazendo a requisição, se for português (pt_BR), retornará em português (pt_BR), caso contrário o retorno padrão é em inglês (en_US).
Atenção
Caso tenha alguma dúvida e/ou problema, entre em contato conosco através do Suporte Netshoes
