Consulta de pedidos

Rota responsável por devolver os dados de pedidos para a Troque e Devolva

Consulta de pedidos

Você deverá disponibilizar um endpoint para que a API da Troque & Devolva consulte os pedidos informados pelo cliente.

Método: POST

Payload (um dos campos será enviado por vez):

{
  "order_number": 66901,
  "buyer_email": "[email protected]",
  "buyer_document": "00000000000"
}

Apenas um dos parâmetros será enviado por requisição.

Requisitos da resposta:

• A resposta deve ser sempre um array com os pedidos encontrados

• Caso não encontre nenhum, retornar array vazio

• Esse comportamento é necessário para exibir ao cliente uma lista de pedidos elegíveis para troca ou devolução, com base nos prazos calculados por nossa API

Exemplo de resposta com resultado:

HTTP Code: 200

{
  "success": true,
  "message": "Pedidos encontrados.",
  "data": [
    {
      //... json demononstrado nas instruções a seguir
    }
  ]
}

Sem pedidos encontrados:

HTTP Code: 400

{
  "success": false,
  "message": "Nenhum pedido encontrado.",
  "data": []
}

Modelo do JSON de pedido

A resposta do endpoint de consulta de pedidos deve retornar os dados completos do pedido no formato abaixo. Todos os campos listados são obrigatórios.

Caso algum campo não exista na sua plataforma ou não possua valor, ele ainda assim deve ser enviado com valor vazio ("", null ou [], conforme o tipo).

Se qualquer campo obrigatório for omitido, a Troque & Devolva retornará um erro 400, informando qual campo está ausente.

Abaixo, um exemplo do JSON de pedido com explicações das chaves:

{
  "name": {
    "first": "Cliente",                  // Primeiro nome do cliente
    "all": "Cliente De Teste"            // Nome completo do cliente
  },
  "items": [
    {
      "product_id": "1",                 // ID do produto na sua base
      "reference": "1234567891",         // Referência do produto
      "sku": "SKU1",                     // SKU do produto
      "image": "https://troqueedevolva.com.br/test-store/sandalia.webp", // URL da imagem do produto
      "link": "link",                    // Link para o produto no site da loja
      "name": "Sandália de salto Anabela 36", // Nome do produto com variação
      "quantity": 1,                     // Quantidade adquirida
      "total_price": 209.9,             // Valor total unitário sem descontos
      "discount": 10,                    // Valor de desconto aplicado diretamente ao item em moeda
      "price": 199.9,                    // Preço unitário de venda, já aplicados os descontos
      "length": 10,                      // Comprimento (cm) do produto
      "width": 10,                       // Largura (cm) do produto
      "height": 10,                      // Altura (cm) do produto
      "weight": 10                       // Peso (gramas) do produto
    },
    {
      "product_id": "2",
      "reference": "1234567892",
      "sku": "SKU2",
      "image": "https://troqueedevolva.com.br/test-store/vestido.webp",
      "link": "link",
      "name": "Vestido com cinto elegante",
      "quantity": 2,
      "total_price": 129,
      "discount": 0,
      "discount_percentage": 0,
      "price": 129,
      "length": 0,
      "width": 0,
      "height": 0,
      "weight": 0
    },
    {
      "product_id": "3",
      "reference": "1234567893",
      "sku": "SKU3",
      "image": "https://troqueedevolva.com.br/test-store/blazer.webp",
      "link": "link",
      "name": "Blazer longo alfaiataria bege",
      "quantity": 1,
      "total_price": 219,
      "discount": 0,
      "discount_percentage": 0,
      "shared_discount": 3.58,
      "price": 219,
      "length": 0,
      "width": 0,
      "height": 0,
      "weight": 0
    }
  ],
  "order": {
    "created_at": "2021-06-22T22:41:46-03:00", // Data e hora da criação do pedido TZ America/Sao_Paulo
    "order_id": 1154854545,                  // ID interno do pedido
    "order_number": 1040506,              // Número do pedido visível ao cliente
    "total_products": 374.7,              // Soma dos produtos (sem considerar frete)
    "total_shipping": 18.7,               // Valor total do frete
    "tax": 0,                             // Valor de impostos
    "total": 355.96,                      // Total pago (após descontos e frete)
    "free_shipping": false,              // Frete grátis?
    "discount_voucher": "",              // Código do cupom de desconto, se houver
    "discount": 0,                        // Valor total de desconto aplicado do cupom + forma de pagamento (ex: desconto no PIX)
    "invoice": {
      "number": "1234",                       // Número da NF
      "series": "1",                       // Série da NF
      "key": "11445588445549875165465498465465494654",// Chave de acesso da NF
      "link": ""                          // Link para download/visualização da NF
    },

    "buyer": {
      "id": 38011876,                     // ID do comprador na loja
      "name": "Cliente de Teste",         // Nome completo
      "email": "[email protected]",        // E-mail do cliente
      "mobile": "41984564355",            // Telefone com DDD
      "document": {
        "number": "00011122244",          // CPF ou CNPJ do cliente
        "type": "cpf"                     // Tipo do documento ("cpf" ou "cnpj")
      },
      "address": {
        "address": "Praça da Sé",         // Rua
        "number": "200",                  // Número
        "address2": "andar 5",            // Complemento
        "postal_code": "01001000",        // CEP
        "neighborhood": "Centro",         // Bairro
        "city": "São Paulo",              // Cidade
        "state": "SP",                    // Estado (UF)
        "country": "Brasil"                // País 
      }
    },

    "payment": [
      {
        "paid_at": "2021-06-22T22:41:46-03:00", // Data e hora do pagamento
        "method": "PayPalPlus",           // Meio de pagamento
        "amount": 355.96,               // Valor pago
        "detail": "Parcelas: 4"           // Detalhes adicionais (ex: número de parcelas)
      }
    ],

    "shippment": {
      "first_shipped_at": "2025-03-29T00:00:00-03:00", // Data do primeiro envio
      "last_delivered": true,                         // Pedido já foi entregue?
      "last_delivered_at": "2025-04-04T00:00:00-03:00", // Data da última entrega

      "destination": {
        "address": "Praça da Sé",
        "number": "200",
        "address2": "andar 5",
        "postal_code": "01001000",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "country": "Brasil" 
      },

      "packages": [
        {
          "carrier": "pac - Frete Grátis",   // Nome da transportadora
          "tracking_number": "QF651779785BR",// Código de rastreio
          "tracking_url": "https://www.linkderastreio.com.br/tn=QF651779785BR",// URL de rastreamento (se houver)
          "cost": 18.7,                    // Custo do frete
          "shipped_at": "2021-07-15T11:05:40-03:00", // Data de envio
          "delivered": false,                // Pacote entregue?
          "delivered_at": ""                 // Data da entrega (se houver)
        }
      ]
    }
  },

  "integration_order": {
    // Objeto livre com os dados brutos do pedido na estrutura original da plataforma, para debug ou futuras melhorias
  }
}

Considerando o formato esperado, o resultado seria:

{
  "success": true,
  "message": "Pedidos encontrados.",
  "data": [
    {
      "name": {
        "first": "Cliente",
        "all": "Cliente De Teste"
      },
      "items": [
        {
          "product_id": "1",
          "reference": "1234567891",
          "sku": "SKU1",
          "image": "https://troqueedevolva.com.br/test-store/sandalia.webp",
          "link": "link",
          "name": "Sandália de salto Anabela 36",
          "quantity": 1,
          "total_price": 209.9,
          "discount": 10,
          "price": 199.9,
          "length": 10,
          "width": 10,
          "height": 10,
          "weight": 10
        },
        {
          "product_id": "2",
          "reference": "1234567892",
          "sku": "SKU2",
          "image": "https://troqueedevolva.com.br/test-store/vestido.webp",
          "link": "link",
          "name": "Vestido com cinto elegante",
          "quantity": 2,
          "total_price": 129,
          "discount": 0,
          "discount_percentage": 0,
          "price": 129,
          "length": 0,
          "width": 0,
          "height": 0,
          "weight": 0
        },
        {
          "product_id": "3",
          "reference": "1234567893",
          "sku": "SKU3",
          "image": "https://troqueedevolva.com.br/test-store/blazer.webp",
          "link": "link",
          "name": "Blazer longo alfaiataria bege",
          "quantity": 1,
          "total_price": 219,
          "discount": 0,
          "discount_percentage": 0,
          "shared_discount": 3.58,
          "price": 219,
          "length": 0,
          "width": 0,
          "height": 0,
          "weight": 0
        }
      ],
      "order": {
        "created_at": "2021-06-22T22:41:46-03:00",
        "order_id": 1154854545,
        "order_number": 1040506,
        "total_products": 374.7,
        "total_shipping": 18.7,
        "tax": 0,
        "total": 355.96,
        "free_shipping": false,
        "discount_voucher": "",
        "discount": 0,
        "invoice": {
          "number": "1234",
          "series": "1",
          "key": "11445588445549875165465498465465494654",
          "link": ""
        },
        "buyer": {
          "id": 38011876,
          "name": "Cliente de Teste",
          "email": "[email protected]",
          "mobile": "41984564355",
          "document": {
            "number": "00011122244",
            "type": "cpf"
          },
          "address": {
            "address": "Praça da Sé",
            "number": "200",
            "address2": "andar 5",
            "postal_code": "01001000",
            "neighborhood": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "country": "Brasil"
          }
        },
        "payment": [
          {
            "paid_at": "2021-06-22T22:41:46-03:00",
            "method": "PayPalPlus",
            "amount": 355.96,
            "detail": "Parcelas: 4"
          }
        ],
        "shippment": {
          "first_shipped_at": "2025-03-29T00:00:00-03:00",
          "last_delivered": true,
          "last_delivered_at": "2025-04-04T00:00:00-03:00",
          "destination": {
            "address": "Praça da Sé",
            "number": "200",
            "address2": "andar 5",
            "postal_code": "01001000",
            "neighborhood": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "country": "Brasil"
          },
          "packages": [
            {
              "carrier": "pac - Frete Grátis",
              "tracking_number": "QF651779785BR",
              "tracking_url": "https://www.linkderastreio.com.br/tn=QF651779785BR",
              "cost": 18.7,
              "shipped_at": "2021-07-15T11:05:40-03:00",
              "delivered": false,
              "delivered_at": ""
            }
          ]
        }
      },
      "integration_order": {}
    }
  ]
}