Referência da API

Pedidos

Pedidos que geraram Pix (carrinhos sem Pix não aparecem). Situações: pending_payment, paid, delivered, expired e cancelled.

Rotas deste grupo3

GET/ordersListar pedidosorders:read
GET/orders/{number}Ver um pedidoorders:read
POST/orders/{number}/deliverMarcar como entregueorders:deliver

Listar pedidos

GET/api/v1/orders

Do mais novo para o mais antigo.

Permissão: orders:read

Parâmetros da URL

`status`	texto	Uma ou mais situações separadas por vírgula (ex.: paid,delivered).
`customer_id`	texto	Pedidos de um cliente (id da Zolvi).
`discord_id`	texto	Pedidos de um cliente pelo ID do Discord.
`created_from / created_to`	data ISO	Criados a partir de (inclusive) e antes de.
`paid_from / paid_to`	data ISO	Pagos a partir de (inclusive) e antes de.
`page`	inteiro	Página, a partir de 1. Padrão 1.
`per_page`	inteiro	Itens por página, de 1 a 100. Padrão 20.

Exemplo

curl

curl https://zolvibot.app/api/v1/orders \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "data": [
    {
      "id": "cmw8d6urw0001ssugmol9xqu2",
      "number": 1042,
      "status": "paid",
      "customer": {
        "id": "cmvrlovla0001ssvcuio6xvf7",
        "discord_id": "1390611228354809977",
        "username": "cliente"
      },
      "items": [
        {
          "id": "cmvrlovlp0005ssvc3yv6nmtz",
          "product_id": "cmvrllzcq000bssokqrrb39n8",
          "product_name": "Key Steam",
          "variant_id": "cmvrllzcq000cssokzx1yq2pa",
          "variant_name": "30D",
          "quantity": 2,
          "unit_price_cents": 1500,
          "total_cents": 3000,
          "answer": null
        }
      ],
      "subtotal_cents": 3000,
      "discount_cents": 300,
      "total_cents": 2700,
      "coupon_code": "BLACK10",
      "affiliate": null,
      "payment": {
        "provider": "mercadopago",
        "method": "gateway",
        "verified": true,
        "approved_by": null,
        "id": "123456789",
        "pix_copy_paste": null,
        "created_at": "2026-11-08T15:30:00.000Z",
        "expires_at": "2026-11-08T16:00:00.000Z",
        "paid_at": "2026-11-08T15:31:12.000Z",
        "gateway_fee_cents": 27
      },
      "delivery": {
        "delivered_at": null,
        "manual": false,
        "manual_reason": null
      },
      "review": null,
      "recovered_from_number": null,
      "created_at": "2026-11-08T15:29:40.000Z",
      "updated_at": "2026-11-08T15:31:12.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

Ver um pedido

GET/api/v1/orders/{number}

Pelo número (#1042) ou pelo id. O conteúdo entregue (as keys) nunca vem no pedido.

Permissão: orders:read

Exemplo

curl

curl https://zolvibot.app/api/v1/orders/1042 \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "id": "cmw8d6urw0001ssugmol9xqu2",
  "number": 1042,
  "status": "paid",
  "customer": {
    "id": "cmvrlovla0001ssvcuio6xvf7",
    "discord_id": "1390611228354809977",
    "username": "cliente"
  },
  "items": [
    {
      "id": "cmvrlovlp0005ssvc3yv6nmtz",
      "product_id": "cmvrllzcq000bssokqrrb39n8",
      "product_name": "Key Steam",
      "variant_id": "cmvrllzcq000cssokzx1yq2pa",
      "variant_name": "30D",
      "quantity": 2,
      "unit_price_cents": 1500,
      "total_cents": 3000,
      "answer": null
    }
  ],
  "subtotal_cents": 3000,
  "discount_cents": 300,
  "total_cents": 2700,
  "coupon_code": "BLACK10",
  "affiliate": null,
  "payment": {
    "provider": "mercadopago",
    "method": "gateway",
    "verified": true,
    "approved_by": null,
    "id": "123456789",
    "pix_copy_paste": null,
    "created_at": "2026-11-08T15:30:00.000Z",
    "expires_at": "2026-11-08T16:00:00.000Z",
    "paid_at": "2026-11-08T15:31:12.000Z",
    "gateway_fee_cents": 27
  },
  "delivery": {
    "delivered_at": null,
    "manual": false,
    "manual_reason": null
  },
  "review": null,
  "recovered_from_number": null,
  "created_at": "2026-11-08T15:29:40.000Z",
  "updated_at": "2026-11-08T15:31:12.000Z"
}

Marcar como entregue

POST/api/v1/orders/{number}/deliver

Para pedido pago que ficou na entrega manual e você entregou por fora (igual ao botão do painel). A Zolvi não manda nada ao cliente. Dispara ORDER_DELIVERED.

Permissão: orders:deliver

Exemplo

curl

curl -X POST https://zolvibot.app/api/v1/orders/1042/deliver \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "id": "cmw8d6urw0001ssugmol9xqu2",
  "number": 1042,
  "status": "delivered",
  "customer": {
    "id": "cmvrlovla0001ssvcuio6xvf7",
    "discord_id": "1390611228354809977",
    "username": "cliente"
  },
  "items": [
    {
      "id": "cmvrlovlp0005ssvc3yv6nmtz",
      "product_id": "cmvrllzcq000bssokqrrb39n8",
      "product_name": "Key Steam",
      "variant_id": "cmvrllzcq000cssokzx1yq2pa",
      "variant_name": "30D",
      "quantity": 2,
      "unit_price_cents": 1500,
      "total_cents": 3000,
      "answer": null
    }
  ],
  "subtotal_cents": 3000,
  "discount_cents": 300,
  "total_cents": 2700,
  "coupon_code": "BLACK10",
  "affiliate": null,
  "payment": {
    "provider": "mercadopago",
    "method": "gateway",
    "verified": true,
    "approved_by": null,
    "id": "123456789",
    "pix_copy_paste": null,
    "created_at": "2026-11-08T15:30:00.000Z",
    "expires_at": "2026-11-08T16:00:00.000Z",
    "paid_at": "2026-11-08T15:31:12.000Z",
    "gateway_fee_cents": 27
  },
  "delivery": {
    "delivered_at": "2026-11-08T16:00:00.000Z",
    "manual": false,
    "manual_reason": null
  },
  "review": null,
  "recovered_from_number": null,
  "created_at": "2026-11-08T15:29:40.000Z",
  "updated_at": "2026-11-08T15:31:12.000Z"
}