# Consulta de pedidos
## 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):**
```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 demononstrado 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": {}
}
]
}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.troqueedevolva.com.br/integracao-de-plataformas/integracao-feita-por-terceiros/consulta-de-pedidos.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.