> For the complete documentation index, see [llms.txt](https://docs.troqueedevolva.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.troqueedevolva.com.br/integracao-de-plataformas/integracao-feita-por-terceiros/consulta-de-pedidos.md). # Consulta de pedidos Rota responsável por devolver os dados de pedidos para a Troque e Devolva 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):** ```json { "order_number": 66901, "buyer_email": "email@docliente.com.br", "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`** ```json { "success": true, "message": "Pedidos encontrados.", "data": [ { //... json demonstrado nas instruções a seguir } ] } ``` **Sem pedidos encontrados:** **HTTP Code: 400** ```json { "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: {% code fullWidth="false" %} ```json { "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": "meu@email.com.br", // 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 } } ``` {% endcode %} 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": "meu@email.com.br",
          "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": {}
    }
  ]
}