Listar Pedidos

Retorna uma lista paginada dos seus pedidos com suporte a filtros e busca.

GET /sellers/orders/

Headers

Header	Valor	Obrigatório
Authorization	Bearer mk_<env>_<token>	Sim

Parâmetros de Query

Parâmetro	Tipo	Padrão	Descrição
page	integer	1	Número da página
page_size	integer	25	Itens por página (máximo: 100)
status	string	—	Filtrar por status: PROCESSING, PENDING, PAID, REFUSED, REFUNDED, CANCELED, EXPIRED, MED, CHARGEBACK
payment_method	string	—	Filtrar por método: PIX, CARD, BOLETO
start_date	datetime	—	Pedidos criados a partir desta data
end_date	datetime	—	Pedidos criados até esta data
q	string	—	Busca por nome, CPF/email do cliente, nome do produto ou UUID
ordering	string	-created_at	Ordenação: created_at, gross_amount (prefixe com - para descendente)

Exemplo de Requisição

cURL

curl -X GET "https://api.somosmarcha.com/api/v1/sellers/orders/?page=1&page_size=10&status=PAID" \
  -H "Authorization: Bearer $API_KEY"

Python

import os
import requests

BASE_URL = "https://api.somosmarcha.com/api/v1"

headers = {
    "Authorization": f"Bearer {os.environ['API_KEY']}",
}

params = {
    "page": 1,
    "page_size": 10,
    "status": "PAID",
}

response = requests.get(f"{BASE_URL}/sellers/orders/", headers=headers, params=params)
print(response.json())

Node.js

const BASE_URL = "https://api.somosmarcha.com/api/v1";

const params = new URLSearchParams({
  page: "1",
  page_size: "10",
  status: "PAID",
});

const response = await fetch(`${BASE_URL}/sellers/orders/?${params}`, {
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
  },
});

const data = await response.json();
console.log(data);

Resposta de Sucesso

Status: 200 OK

{
  "message": "Sucesso!",
  "metadata": {
    "count": 42,
    "next": "https://api.somosmarcha.com/api/v1/sellers/orders/?page=2&page_size=10",
    "previous": null,
    "page": 1,
    "total_pages": 5,
    "total_results": 10,
    "total_gross_amount": 150000
  },
  "data": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "seller": {
        "name": "Joao Silva"
      },
      "items": [
        {
          "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "name": "Plano Premium",
          "quantity": 1
        }
      ],
      "amount": {
        "subtotal_amount": 15000,
        "shipping_amount": 0,
        "discount_amount": 0,
        "commission_amount": 1500,
        "gross_amount": 15000
      },
      "method": "PIX",
      "status": "PAID",
      "tracking": {
        "tracking_code": "BR123456789",
        "shipping_status": "SHIPPED"
      },
      "timestamps": {
        "created_at": "2026-01-29T10:00:00Z",
        "paid_at": "2026-01-29T14:30:00Z"
      }
    }
  ]
}

Campos da Resposta

Notação financeira

Todo campo que termina em _amount é um inteiro, em centavos. Exemplo: 15000 = R$ 150,00.

Campo	Tipo	Descrição
uuid	string	UUID do pedido
seller.name	string	Nome do vendedor
items[].uuid	string	UUID do produto
items[].name	string	Nome do produto
items[].quantity	integer	Quantidade do item
amount.subtotal_amount	integer	Subtotal em centavos
amount.shipping_amount	integer	Frete em centavos
amount.discount_amount	integer	Desconto em centavos
amount.commission_amount	integer	Comissão em centavos
amount.gross_amount	integer	Valor bruto total em centavos
method	string	Método de pagamento (PIX, CARD, BOLETO)
status	string	Status do pedido (PROCESSING, PENDING, PAID, REFUSED, REFUNDED, CANCELED, EXPIRED, MED, CHARGEBACK)
tracking.tracking_code	string | null	Código de rastreio
tracking.shipping_status	string | null	Status do envio
timestamps.created_at	datetime	Data/hora de criação
timestamps.paid_at	datetime | null	Data/hora do pagamento
metadata.total_gross_amount	integer	Soma do valor bruto de todos os pedidos filtrados, em centavos

Paginação

Utilize os campos metadata.next e metadata.previous para navegar entre as páginas. O campo metadata.count indica o total de registros.