API Admin › Recursos

Pedidos

Os pedidos da loja: a lista para o ERP sincronizar, as mudanças de situação (pago, em separação, enviado, entregue, cancelado) e a nota fiscal que o ERP emite.

As regras são as mesmas do painel: a mudança que o painel recusa, a API recusa; quem comprou recebe os mesmos e-mails (pagamento confirmado, pedido enviado, pedido cancelado, estorno). Os pedidos nascem no checkout da vitrine: a API não cria pedido.

Dados pessoais: cada pedido traz o nome, o e-mail, o telefone, o CPF e o endereço de quem comprou. Com read_orders, a integração passa a responder por esses dados na LGPD. Quando a loja anonimiza um pedido (anonymized_at deixa de ser null), apague os dados dele também na sua cópia. O webhook order.anonymized avisa na hora (ver Webhooks).

O objeto pedido

{
  "id": "6c1d0a52-...",
  "number": 1021,
  "status": "shipped",
  "customer": {
    "id": "3f6b2c1e-...",
    "name": "Helena Souza",
    "email": "helena@exemplo.com",
    "phone": "41999990000",
    "cpf": "52998224725"
  },
  "shipping_address": {
    "zip": "80000000",
    "street": "Rua XV de Novembro",
    "number": "100",
    "complement": "Sala 2",
    "neighborhood": "Centro",
    "city": "Curitiba",
    "state": "PR"
  },
  "line_items": [
    {
      "id": "0c41...",
      "key": "pX3b2kL9qRtY7mNa",
      "parent_line_id": null,
      "group": null,
      "properties": {},
      "inventory_tracked": true,
      "eyes": null,
      "variant_id": "5e2a...",
      "title": "Camiseta Básica",
      "options": ["M"],
      "sku": "CB-M",
      "price": 4990,
      "quantity": 2,
      "line_price": 9980,
      "promotion": null
    }
  ],
  "subtotal_price": 9980,
  "shipping_price": 2190,
  "total_discounts": 998,
  "coupon_code": "BEMVINDA",
  "pix_discount": 559,
  "total_price": 10613,
  "shipping_line": {
    "title": "SEDEX",
    "carrier": "Correios",
    "delivery_days": 2,
    "pickup": null
  },
  "tracking_code": "AA123456789BR",
  "payment": {
    "method": "pix",
    "status": "approved",
    "amount": 10613,
    "installments": null,
    "refunded_at": null,
    "created_at": "2026-10-03T18:01:00.000Z"
  },
  "invoice": {
    "key": "35261011222333000181550010000012341000000017",
    "number": "1234",
    "series": "1",
    "url": "https://erp.exemplo.com/danfe/1234",
    "informed_at": "2026-10-03T19:30:00.000Z"
  },
  "paid_at": "2026-10-03T18:02:10.000Z",
  "test": false,
  "anonymized_at": null,
  "created_at": "2026-10-03T18:00:00.000Z",
  "updated_at": "2026-10-03T19:30:00.000Z"
}

• number: o número que o comprador e o painel veem (#1021), único na loja. O id é o que as rotas usam.
• status: pending_payment (aguardando pagamento), paid, preparing (em separação), shipped, delivered ou cancelled. Na retirada na loja, shipped é o pedido pronto para retirar, e delivered, o retirado.
• customer e shipping_address: como o checkout recebeu (o telefone, o CPF e o CEP só com os números). Na retirada na loja, o endereço é o de quem comprou, e onde retirar vem em shipping_line.pickup.
• customer.id: a conta do comprador na área do cliente da loja, ligada pelo e-mail verificado (o pedido feito com a conta aberta, ou o pedido antigo do mesmo e-mail quando o comprador entra pela primeira vez). Com read_customers, GET /customers/{id} traz a conta, com os endereços salvos (ver Clientes). null no pedido sem conta, no anonimizado e depois que a conta é excluída.
• line_items: uma cópia do que foi comprado. Mudar o catálogo depois não muda o pedido, e a variante pode já ter saído dele. price é o da unidade na compra, já com a promoção automática (promotion diz qual).
• Item composto (a armação com a lente e os tratamentos, ver montagens): o item pai vem seguido dos filhos, e cada filho traz parent_line_id (o id do pai) e group ({ code, name }, o grupo da montagem em que ele entrou, como se chamava na compra). O filho tem a quantidade do pai, e o line_price de cada item é só o dele: o conjunto é a soma do pai com os filhos, e o subtotal_price soma todos. key é a chave da linha do carrinho (null nos filhos e nos pedidos de antes de outubro de 2026). properties são as propriedades da linha escritas pelo comprador (a gravação, por exemplo), com as ocultas, cujo nome começa com _. inventory_tracked falso: o item é sob encomenda, não saiu do estoque, e o cancelamento não devolve nada.
• Lente de contato (o produto com prescription_type: "contact_lens"): eyes traz as caixas de cada olho, { "right": 2, "left": 1 } (OD e OE), e quantity é a soma; o olho com zero caixas fica sem lente. null nos outros itens. A receita do item é a de lente de contato (ver Receitas).
• files: os arquivos enviados por quem comprou para o item (a foto ou o PDF da receita, uma arte para personalizar), só no GET /orders/{id}; a lista de pedidos e o corpo dos webhooks não trazem o campo. Cada um com id, name, content_type (image/jpeg, image/png, image/webp ou application/pdf), size em bytes, purpose (general ou prescription) e url, um endereço assinado que vale 15 minutos (url_expires_at) e baixa o arquivo como anexo. Para baixar depois, peça o pedido de novo. O arquivo é dado pessoal: some quando o pedido é anonimizado.

json "files": [ { "id": "7d10...", "name": "receita.jpg", "content_type": "image/jpeg", "size": 482113, "purpose": "general", "url": "https://...amazonaws.com/pedidos/...?X-Amz-Signature=...", "url_expires_at": "2026-10-07T18:15:00.000Z" } ]

• prescription: a receita oftalmológica do item que pede receita (a armação com lente de grau, ou a lente sozinha); null nos outros e nos filhos. A situação (pending, provided, checked) e as datas vêm sempre; os valores (o grau de cada olho, a DP, o médico) só no GET /orders/{id}, como os arquivos. Ver Receitas, com a rota que informa a receita que chegou por outro canal.
• Valores em centavos: total_price = subtotal_price + shipping_price − total_discounts − pix_discount. total_discounts é o desconto do cupom (nos itens e no frete), e pix_discount, o de quem escolheu Pix.
• shipping_line: o frete escolhido no checkout, com o prazo em dias úteis a partir da postagem. null: o frete ficou combinado com a loja.
• payment: a última cobrança, que é a que vale. method: pix, credit_card, debit_card ou boleto; status: pending, approved, expired, cancelled, declined (o cartão recusado), refunded ou authorized. installments só no cartão de crédito. null enquanto o comprador não gerou nenhuma.
  • authorized é o cartão aprovado pelo banco e à espera da análise de risco ("Em análise" no painel). O pedido continua pending_payment e nada foi cobrado ainda. Aprovado na análise, o pagamento passa a approved e o pedido a paid. Recusado, ou sem resposta em 3 dias, o pagamento passa a declined ou cancelled, o pedido é cancelado (order.cancelled) e a reserva no cartão é desfeita. Não separe nem envie um pedido com o pagamento authorized.
• invoice: a nota fiscal informada pelo ERP (ver abaixo). null enquanto não informada.
• paid_at: quando passou a pago, pelo gateway ou pela loja. Fica mesmo que o pedido seja cancelado depois.
• test: true no pedido feito numa loja de teste, em que nenhum pagamento é real (o pagamento simulado ou uma conta de teste do gateway). Vem da loja quando o pedido é criado e não muda depois, nem quando a loja deixa de ser de teste. Use para separar os pedidos de teste dos de verdade no seu sistema.
• anonymized_at: quando os dados de quem comprou foram apagados (LGPD). No pedido anonimizado, customer.name é "Comprador anonimizado", o e-mail, o telefone e o CPF ficam vazios, o endereço guarda só a cidade e a UF, e o link da nota (invoice.url) sai. Os itens, os valores, a situação e a chave da nota ficam.

A lista

GET /orders

Os pedidos, na ordem da última mudança, da mais antiga à mais nova (o id desempata). É a lista da sincronização: guarde o updated_at do último pedido que leu e, na próxima vez, peça updated_at_min com ele (a data entra na lista: o último lido vem de novo).

Toda mudança do pedido muda o updated_at: o pagamento confirmado pelo gateway, cada mudança de situação (pelo painel, pela API ou pela etiqueta postada), o rastreio, a nota fiscal, a conta do cliente (customer.id) e a anonimização.

A resposta é { "data": [pedido...], "next_cursor": "..." }; com mais páginas, o cabeçalho Link leva à próxima (rel="next"). Ver Listas.

GET /orders/count

Quantos pedidos casam com os mesmos filtros da lista: { "count": 37 }.

GET /orders/{id}

Um pedido.

As mudanças de situação

Cada ação é um POST sem corpo (o ship aceita o rastreio) e responde 200 com o pedido. A ordem é a do painel:

pending_payment → paid → preparing → shipped → delivered
        ↓           ↓         ↓
     cancelled   cancelled  cancelled

A ação fora da vez é 409 invalid_status_transition (por exemplo, ship num pedido pago que ainda não foi separado), e nada muda.

POST /orders/{id}/mark_paid

Marca como pago o pedido que aguarda pagamento: para o pagamento recebido fora da plataforma (depósito, dinheiro na retirada). Quem comprou recebe o e-mail de pagamento confirmado. O pagamento feito no checkout já chega pago, pelo gateway: não é preciso marcar.

POST /orders/{id}/prepare

Começa a separar o pedido pago.

POST /orders/{id}/ship

Marca como enviado o pedido em separação. O código de rastreio é opcional (entrega em mãos, motoboy):

{ "tracking_code": "AA123456789BR" }

O código fica em maiúsculas, sem espaços (de 4 a 40 letras, números e hífen). Quem comprou recebe o e-mail de pedido enviado, com o rastreio. A etiqueta do Melhor Envio comprada no painel marca o pedido como enviado sozinha, quando é postada.

POST /orders/{id}/deliver

Marca como entregue o pedido enviado.

POST /orders/{id}/cancel

Cancela o pedido que ainda não foi enviado. Os itens voltam ao estoque, e a cobrança em aberto (um boleto, um Pix) deixa de valer, também no gateway.

O pedido já pago tem o dinheiro devolvido a quem comprou, pelo gateway que cobrou, antes de qualquer outra coisa: cancelá-lo pede também o escopo refund_orders (sem ele, 403 missing_scope, e nada muda). Se o gateway recusar o estorno, o pedido continua pago.

A nota fiscal

A plataforma não emite nota fiscal: quem emite é o ERP da loja, que informa a nota no pedido. A nota aparece no pedido no painel, e a compra da etiqueta do Melhor Envio, numa loja que envia com nota, usa a chave dela sem o lojista digitar.

PUT /orders/{id}/invoice

{
  "key": "35261011222333000181550010000012341000000017",
  "url": "https://erp.exemplo.com/danfe/1234"
}

• key: a chave de acesso da NF-e ou da NFC-e, os 44 números (espaços e pontos são ignorados). O último número confere os outros: a chave copiada pela metade é recusada (400, com o campo em fields).
• number e series: opcionais, só com números. Eles estão dentro da chave; sem eles, saem dela, e, com eles, têm de bater (400).
• url: opcional, o link da nota (a DANFE) no ERP, https://, até 500 caracteres.

Responde 200 com o pedido. Informar de novo troca a nota anterior (o ERP que cancela a nota e emite outra manda a nova). A nota é aceita em qualquer situação do pedido: quem decide quando emitir é o ERP.