Pedidos

Liste os pedidos da loja e consulte os detalhes de um pedido. Os dois endpoints exigem o escopo orders:read.

Listar pedidos#

GET/v1/orders

Retorna os pedidos da loja da chave, do mais novo para o mais antigo. A lista é paginada por cursor; veja Paginação.

Parâmetros de query

scopeactive | allopcionalPadrão: all: active retorna só pedidos em andamento (que não estão delivered, returned nem cancelled). all retorna todos.
qstringopcional: Busca em order_number, external_order_id e customer_name, sem diferenciar maiúsculas de minúsculas (acentos contam). Até 100 caracteres, sem caracteres de controle. Espaços nas pontas são removidos.
cursorstringopcional: Valor de next_cursor da página anterior. Até 200 caracteres; mais que isso responde 400 com parameter_invalid. Veja Paginação.
limitintegeropcionalPadrão: 25: Quantidade de pedidos por página, de 1 a 100.

Um parâmetro fora desta lista responde 400 com parameter_unknown.

Campos da resposta

dataarray: Pedidos da página, do mais novo para o mais antigo (created_at desc, id desc).
has_moreboolean: true quando existe uma próxima página. Igual a next_cursor != null.
next_cursorstring | null: Envie como cursor para buscar a próxima página. null na última página.

Campos de cada pedido em data

idstring (UUID): Identificador do pedido na Movvio.
order_numberstring | null: Número do pedido na plataforma de origem.
external_order_idstring | null: ID do pedido na plataforma de origem.
customer_namestring | null: Nome do cliente.
totalstring | null: Valor total do pedido. String decimal com 2 casas, como "129.90".
statusstring: Situação da entrega: pending, searching_driver, driver_assigned, picked_up, delivered, returned ou cancelled.
external_sourcestring | null: Plataforma de origem: nuvemshop, bagy, vtex, woocommerce, shopify, custom_api, bling ou null.
ordered_atstring | null: Data do pedido na plataforma de origem, no formato YYYY-MM-DD.
created_atstring: Quando o pedido entrou na Movvio. ISO 8601 em UTC.

GET/v1/orders?scope=active&limit=25

curl "https://api.movvio.com.br/v1/orders?scope=active&limit=25" \
  -H "Authorization: Bearer mvk_live_xxx"

Resposta200 OK

{
  "data": [
    {
      "id": "0b7e2a1c-4f5d-4c3e-9a8b-1d2e3f4a5b6c",
      "order_number": "1042",
      "external_order_id": "98765",
      "customer_name": "Cliente Exemplo",
      "total": "129.90",
      "status": "driver_assigned",
      "external_source": "bling",
      "ordered_at": "2026-10-30",
      "created_at": "2026-10-30T14:05:12.345Z"
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0xMC0zMFQxNDowNToxMi4zNDU2NzhafDBiN2Uy..."
}

Obter um pedido#

GET/v1/orders/{id}

Retorna um pedido com todos os campos da lista, mais os dados do cliente, os valores, o endereço de entrega e os itens.

Parâmetros de caminho

idstring (UUID)obrigatório: ID do pedido. Um valor que não seja UUID responde 400 com parameter_invalid. Um pedido de outra loja responde 404, como se não existisse.

Campos adicionais da resposta

customer_phonestring | null: Telefone do cliente.
customer_notestring | null: Observação do cliente.
shipping_methodstring | null: Forma de entrega escolhida na plataforma.
items_totalstring | null: Soma dos itens. String decimal com 2 casas.
discountstring | null: Desconto. String decimal com 2 casas.
shipping_feestring | null: Frete. String decimal com 2 casas.
delivery_streetstring | null: Rua do endereço de entrega.
delivery_numberstring | null: Número do endereço de entrega.
delivery_complementstring | null: Complemento do endereço de entrega.
delivery_neighborhoodstring | null: Bairro do endereço de entrega.
delivery_citystring | null: Cidade do endereço de entrega.
delivery_statestring | null: UF do endereço de entrega.
delivery_zip_codestring | null: CEP do endereço de entrega.
itemsarray: Itens do pedido, ordenados por id crescente. Sem paginação.
items.idstring (UUID): Identificador do item.
items.product_namestring | null: Nome do produto.
items.quantitystring | null: Quantidade. String decimal com até 4 casas, como "2" ou "0.5".
items.skustring | null: SKU do produto.
items.unit_pricestring | null: Preço unitário. String decimal com 2 casas.

GET/v1/orders/0b7e2a1c-4f5d-4c3e-9a8b-1d2e3f4a5b6c

curl "https://api.movvio.com.br/v1/orders/0b7e2a1c-4f5d-4c3e-9a8b-1d2e3f4a5b6c" \
  -H "Authorization: Bearer mvk_live_xxx"

Resposta200 OK

{
  "id": "0b7e2a1c-4f5d-4c3e-9a8b-1d2e3f4a5b6c",
  "order_number": "1042",
  "external_order_id": "98765",
  "customer_name": "Cliente Exemplo",
  "total": "129.90",
  "status": "driver_assigned",
  "external_source": "bling",
  "ordered_at": "2026-10-30",
  "created_at": "2026-10-30T14:05:12.345Z",
  "customer_phone": "+5511900000000",
  "customer_note": "Deixar na portaria",
  "shipping_method": "Motoboy",
  "items_total": "119.90",
  "discount": "0.00",
  "shipping_fee": "10.00",
  "delivery_street": "Rua Exemplo",
  "delivery_number": "100",
  "delivery_complement": "Apto 12",
  "delivery_neighborhood": "Centro",
  "delivery_city": "São Paulo",
  "delivery_state": "SP",
  "delivery_zip_code": "01000-000",
  "items": [
    { "id": "7f6e5d4c-3b2a-4190-8f7e-6d5c4b3a2910", "product_name": "Produto A", "quantity": "2", "sku": "SKU-A", "unit_price": "59.95" }
  ]
}