Pular para o conteúdo principal

Criar Protocolo

Introdução​

Esta seção detalha como criar e consultar um protocolo no ambiente de sandbox e como testar cenários de erro.

Pré-requisitos para Criação de Protocolos​

Para criar um protocolo no ambiente de sandbox é necessário utilizar um pedido com dados simulados. Qualquer pedido pode ser usado para criar um protocolo, desde que os campos atendam às tipagens requeridas pelo endpoint.

Exemplo de pedido que pode ser utilizado para criar um protocolo:

{
  "order": {
    "id": "195a8e41-afcc-455b-907a-475137106f84",
    "code": "987654",
    "delivery": {
      "id": "195a8e41-afcc-455b-907a-475137106f84",
      "items": [
        {
          "description": "Livro infantil a Bela e a Fera com encartes em 3D.",
          "external_sku": "livro-seller-01",
          "id": "63c54b4a-ea19-4c52-90a8-bd38cd1a3157",
          "image": "https://imagem.do.livro/foto.jpg",
          "name": "A Bela e a Fera em 3D",
          "quantity": 1,
          "sku": "livro-01"
        }
      ],
      "seller": {
        "id": "c85be697-7b14-4460-a5c7-3e58b4a364f9",
        "name": "Lojinha de Livros Infantis"
      }
    }
  }
}
info

Observe que esse pedido não precisa ser criada no ambiente de sandbox de pedidos, e esse ambiente de sandbox está completamente separado de todos os demais.

atenção

Observe que o protocolo deve ser criado no canal de sandbox, conforme explicitado na documentação do sandbox.

Cenários de Erros Imediatos​

Estes são erros retornados imediatamente como resposta à requisição.

CenárioCódigo de RespostaCondições para emular o cenário
"Unprocessable entity"422Tente criar um protocolo informando valores com tipos de dados inválidos nos campos da requisição.
"channel_id "{channel_id}" isn't allowed in sandbox environment."422Tente criar um protocolo utilizando um canal inválido para o ambiente de sandbox.
"tenant_id: "{tenant_id}" has no permission to access channel_id: "{channel_id}"."422Tente criar um protocolo no ambiente de sandbox sem que o tenant esteja previamente cadastrado no canal correspondente.

Tabela de Cenários de Erro Assíncronos​

São erros assíncronos encontrados ao consultar a transação referente ao transaction_id retornado como resposta da requisição.

Abaixo estão descritos os possíveis cenários de erro que podem ser testados. Observe que muitos deles requerem a existência de outro protocolo; esse protocolo precisa ser criado, e os ids utilizados nele serão usados para efetuar buscas no banco de sandbox e encontrar possíveis conflitos.

CenáriocodetypeCondições para emular cenário
"Pedido com ID: {ID do Pedido} não encontrado."invalid_ordercancellation, shippingNão é possível executar esse cenário sem utilizar o campo code
"Não é possível abrir um protocolo de cancelamento para um item que já possui um protocolo de cancelamento aberto."cancellationTente abrir protocolo de cancelamento com uma mesma combinação de order.id e item.id existente em um protocolo aberto
"Não é possível abrir um protocolo de cancelamento sem especificar os itens do pedido."cancellationTente abrir protocolo de cancelamento sem especificar um item
"Não é possível abrir protocolo de entrega para um pacote com protocolo de cancelamento aberto."shippingTente abrir protocolo de entrega com mesma combinação de order.id e item.id existente em um protocolo aberto
"Não é possível abrir protocolo de entrega para um pacote com protocolo de entrega aberto."shippingTente abrir protocolo de entrega com mesma combinação de order.id e delivery.id existente em um protocolo aberto
info

No ambiente de produção, o campo code é um identificador customizado opcional destinado ao uso do parceiro. Já no ambiente de sandbox, além de manter essa funcionalidade, o campo também pode ser utilizado para forçar a ocorrência de erros assíncronos específicos durante os testes.

Exemplo de Criação de Protocolo​

Abaixo está um exemplo de como criar um protocolo utilizando CURL. O exemplo em questão geraria o primeiro cenário descrito na Tabela de Cenários de Erro Assíncronos por ter definido o campo code como invalid_order.

curl -L 'https://api-sandbox.magalu.com/seller/v0/tickets' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "reason": "missing_parts",
    "type": "shipping",
    "code": "invalid_order",
    "channel": {
        "alias": "sandbox",
        "id": "5f62650a-0039-4d65-9b96-266d498c03bd"
    },
    "order": {
        "id": "195a8e41-afcc-455b-907a-475137106f84",
        "code": "987654",
        "delivery": {
            "id": "195a8e41-afcc-455b-907a-475137106f84",
            "items": [
                {
                    "description": "Livro infantil a Bela e a Fera com encartes em 3D.",
                    "external_sku": "livro-seller-01",
                    "id": "63c54b4a-ea19-4c52-90a8-bd38cd1a3157",
                    "image": "https://imagem.do.livro/foto.jpg",
                    "name": "A Bela e a Fera em 3D",
                    "quantity": 1,
                    "sku": "livro-01"
                }
            ],
            "seller": {
                "id": "c85be697-7b14-4460-a5c7-3e58b4a364f9",
                "name": "Lojinha de Livros Infantis"
            }
        },
    }
}'

Para mais detalhes, consulte a documentação do endpoint.

Consultar Protocolo

Pré-requisitos para Consulta de Protocolo​

Os endpoints de consulta estão disponíveis no ambiente de sandbox e funcionam da mesma forma que no ambiente de produção. Importante ressaltar:

  • Nenhum dado é pré-carregado no ambiente de sandbox
  • Os endpoints retornarão apenas os dados criados pelo próprio usuário durante os testes

Exemplo de Consulta de Protocolos​

curl -L 'https://api.magalu.com/seller/v0/tickets' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'

Para mais detalhes, consulte a documentação do endpoint.

Exemplo de Consulta de Protocolo por ID​

curl -L 'https://api-sandbox.magalu.com/seller/v0/tickets/{id}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'

Para mais detalhes, consulte a documentação do endpoint.