API atual/Referência completa/Mini-loja WhatsApp: pedidos

Ver e acompanhar o pedido

Abre um pedido com itens, endereço, pagamento, linha do tempo e código de rastreio, e consulta o rastreio na transportadora.

É a tela do pedido da mini-loja, aquela que o link da mensagem de WhatsApp abre. Ela reúne tudo o que o cliente precisa: o que comprou, onde vai chegar, como pagar (o Pix ainda pode ser pago se ele perdeu o código), em que etapa o pedido está e o que ele ainda pode fazer (cancelar, trocar o pagamento, avaliar).

Pedido de outra pessoa responde 404 order_not_found, igual a um pedido que não existe: ninguém descobre ids alheios.

Ver o pedido

GET/api/v1/storefront/wa-coex/order/{token}/{orderID}Pública

Detalhe completo de um pedido do cliente

Ao abrir um pedido com Pix ainda não pago, a rota gera o QR Code de novo se o cliente perdeu o código (a cobrança é registrada uma vez só). O mesmo vale para o boleto da Pagar.me. Em pedido com Pix manual, devolve a chave da loja em vez de um QR.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido (order_id).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/order/$TOKEN/9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33"

Resposta

200Pedido aguardando pagamento por Pix

json

{
  "order_id": "9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33",
  "order_number": "1042",
  "status": "P",
  "status_code": "pending",
  "status_name": "Aguardando pagamento",
  "status_color": "#f59e0b",
  "payment_status": "P",
  "total_cents": 16387,
  "shipping_cents": 0,
  "discount_cents": 6613,
  "shipping_label": "Entrega Padrão",
  "payment_name": "PIX",
  "payment_code": "pix",
  "customer_name": "Maria Souza",
  "created_at_unix": 1791744130,
  "items": [
    {
      "name": "Notebook Slim Rosa",
      "quantity": 2,
      "total_cents": 18400,
      "image_url": "/uploads/exemplo/notebook.png",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035"
    }
  ],
  "address": {
    "street": "Avenida Paulista",
    "number": "1000",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zip": "01310100"
  },
  "pix": {
    "brcode": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5913Loja Exemplo6009Sao Paulo62070503***6304ABCD",
    "qr_png_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "expires_at": "2026-10-12T15:30:00Z"
  },
  "can_cancel": true,
  "can_review": false,
  "reviewed": false,
  "cancel_needs_store": false,
  "cancel_requested": false,
  "stage": "incoming",
  "can_change_payment": true,
  "payment": { "state": "pending", "kind": "pix", "online_card": false },
  "status_trail": [
    { "code": "pending", "name": "Aguardando pagamento", "color": "#f59e0b", "at_unix": 1791744130, "done": true, "current": true }
  ]
}

Campos da resposta

order_iduuid

Id do pedido. order_number é o número para exibir.

statusstring

Letra do status do pedido. status_code, status_name e status_color vêm do cadastro de status da loja (cada loja tem o seu fluxo).

payment_statusstring

Status do pagamento em letra (P pendente, C pago, F recusado...). Para decidir, use payment.state.

total_centsinteger

Total em centavos. shipping_cents, tax_cents e discount_cents são as partes (as duas últimas omitidas quando 0).

shipping_labelstring

Nome da entrega escolhida.

payment_namestring

Nome da forma de pagamento. payment_code é o código.

customer_namestring

Nome do comprador. Vazio quando o pedido foi feito como convidado sem nome.

created_at_unixinteger

Quando foi criado, em segundos Unix.

itemsarray

Itens: name, quantity, total_cents, image_url, note (observação do cliente), product_id (para avaliar o produto) e variation_label (as escolhas da linha).

addressobject

Endereço de entrega: street, number, complement, district, city, state, zip. Omitido em retirada ou quando o pedido não tem endereço.

pixobject

Pix a pagar: brcode, qr_png_base64 e expires_at. Só quando o pedido é Pix e ainda não foi pago.

boletoobject

Boleto a pagar: barcode, line e url. Só quando o pedido é boleto bancário e não foi pago.

manual_pixobject

Pix manual: key, payee, instructions. Com ele, attachments traz os comprovantes já enviados (veja Anexos).

payment_link_urlstring

Link de pagamento externo ("Pagar agora"), quando a loja tem um.

paymentobject

Estado do pagamento lido do registro de pagamento, nunca deduzido do status do pedido.

statestring

paidpendinganalysisrefusedrefundedinvoicedon_delivery

Pago, aguardando, cartão em análise, recusado, estornado, faturado ou pagamento na entrega.

kindstring

pixcardboletoinvoicedoffline

Tipo da forma de pagamento. Ausente quando não se sabe.

paid_at_unixinteger

Quando foi pago, em segundos Unix.

due_at_unixinteger

Primeiro vencimento, no boleto faturado.

cardobject

Cobrança em análise: brand, last4, installments, amount_cents, action_url. Só com state: analysis.

online_cardboolean

O método é cartão online (cobrado agora). Só nele a tela oferece "Pagar com cartão".

stagestring

incomingpreparingoutdoneclosed

Etapa na régua da loja (não aceito, em preparo, enviado, entregue, encerrado).

can_cancelboolean

O cliente pode cancelar agora. Com cancel_needs_store: true, cancelar vira um pedido à loja, não um cancelamento imediato. cancel_requested diz que esse pedido já foi feito.

can_change_paymentboolean

O cliente pode trocar a forma de pagamento.

can_reviewboolean

O pedido foi entregue e pode ser avaliado. reviewed fica false: a avaliação é por produto, veja Avaliações.

shipmentobject

Rastreio: tracking_code, carrier e tracking_url. Presente quando existe um envio com código.

status_trailarray

Linha do tempo real do pedido: code, name, color, at_unix, done e current.

Erros

Status	Quando	Corpo
404	O pedido não existe ou não é deste cliente.	`{"error":"order_not_found"}`
500	Falha ao ler o banco.	`{"error":"db_unavailable"}`

Consultar o rastreio

GET/api/v1/storefront/wa-coex/track/{token}/{orderID}Pública

Rastreio do pedido na transportadora

Consulta o rastreio da transportadora do pedido. Só responde para pedido do cliente. Quando não há nada a mostrar, a resposta é 204 No Content sem corpo, e a tela fica com a linha do tempo local (status_trail).

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido.

Resposta

200Rastreio disponível

json

{
  "carrier": "Correios",
  "status": "Objeto em trânsito",
  "pin": "AB123456789BR",
  "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objeto=AB123456789BR"
}

Campos da resposta

carrierstring

Nome da transportadora.

statusstring

Situação atual informada por ela.

pinstring

Código de rastreio.

tracking_urlstring

Link para acompanhar no site da transportadora.

Erros

Status	Quando	Corpo
204	Sem rastreio: pedido sem transportadora, pedido de outra pessoa, ou falha na consulta.	Sem corpo

Veja também

Ver e acompanhar o pedido

Abre um pedido com itens, endereço, pagamento, linha do tempo e código de rastreio, e consulta o rastreio na transportadora.

Pedido de outra pessoa responde 404 order_not_found, igual a um pedido que não existe: ninguém descobre ids alheios.

Ver o pedido

GET/api/v1/storefront/wa-coex/order/{token}/{orderID}Pública

Detalhe completo de um pedido do cliente

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido (order_id).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/order/$TOKEN/9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33"

Resposta

200Pedido aguardando pagamento por Pix

json

{
  "order_id": "9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33",
  "order_number": "1042",
  "status": "P",
  "status_code": "pending",
  "status_name": "Aguardando pagamento",
  "status_color": "#f59e0b",
  "payment_status": "P",
  "total_cents": 16387,
  "shipping_cents": 0,
  "discount_cents": 6613,
  "shipping_label": "Entrega Padrão",
  "payment_name": "PIX",
  "payment_code": "pix",
  "customer_name": "Maria Souza",
  "created_at_unix": 1791744130,
  "items": [
    {
      "name": "Notebook Slim Rosa",
      "quantity": 2,
      "total_cents": 18400,
      "image_url": "/uploads/exemplo/notebook.png",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035"
    }
  ],
  "address": {
    "street": "Avenida Paulista",
    "number": "1000",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zip": "01310100"
  },
  "pix": {
    "brcode": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5913Loja Exemplo6009Sao Paulo62070503***6304ABCD",
    "qr_png_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "expires_at": "2026-10-12T15:30:00Z"
  },
  "can_cancel": true,
  "can_review": false,
  "reviewed": false,
  "cancel_needs_store": false,
  "cancel_requested": false,
  "stage": "incoming",
  "can_change_payment": true,
  "payment": { "state": "pending", "kind": "pix", "online_card": false },
  "status_trail": [
    { "code": "pending", "name": "Aguardando pagamento", "color": "#f59e0b", "at_unix": 1791744130, "done": true, "current": true }
  ]
}

Campos da resposta

order_iduuid

Id do pedido. order_number é o número para exibir.

statusstring

Letra do status do pedido. status_code, status_name e status_color vêm do cadastro de status da loja (cada loja tem o seu fluxo).

payment_statusstring

Status do pagamento em letra (P pendente, C pago, F recusado...). Para decidir, use payment.state.

total_centsinteger

Total em centavos. shipping_cents, tax_cents e discount_cents são as partes (as duas últimas omitidas quando 0).

shipping_labelstring

Nome da entrega escolhida.

payment_namestring

Nome da forma de pagamento. payment_code é o código.

customer_namestring

Nome do comprador. Vazio quando o pedido foi feito como convidado sem nome.

created_at_unixinteger

Quando foi criado, em segundos Unix.

itemsarray

Itens: name, quantity, total_cents, image_url, note (observação do cliente), product_id (para avaliar o produto) e variation_label (as escolhas da linha).

addressobject

Endereço de entrega: street, number, complement, district, city, state, zip. Omitido em retirada ou quando o pedido não tem endereço.

pixobject

Pix a pagar: brcode, qr_png_base64 e expires_at. Só quando o pedido é Pix e ainda não foi pago.

boletoobject

Boleto a pagar: barcode, line e url. Só quando o pedido é boleto bancário e não foi pago.

manual_pixobject

Pix manual: key, payee, instructions. Com ele, attachments traz os comprovantes já enviados (veja Anexos).

payment_link_urlstring

Link de pagamento externo ("Pagar agora"), quando a loja tem um.

paymentobject

Estado do pagamento lido do registro de pagamento, nunca deduzido do status do pedido.

statestring

paidpendinganalysisrefusedrefundedinvoicedon_delivery

Pago, aguardando, cartão em análise, recusado, estornado, faturado ou pagamento na entrega.

kindstring

pixcardboletoinvoicedoffline

Tipo da forma de pagamento. Ausente quando não se sabe.

paid_at_unixinteger

Quando foi pago, em segundos Unix.

due_at_unixinteger

Primeiro vencimento, no boleto faturado.

cardobject

Cobrança em análise: brand, last4, installments, amount_cents, action_url. Só com state: analysis.

online_cardboolean

O método é cartão online (cobrado agora). Só nele a tela oferece "Pagar com cartão".

stagestring

incomingpreparingoutdoneclosed

Etapa na régua da loja (não aceito, em preparo, enviado, entregue, encerrado).

can_cancelboolean

O cliente pode cancelar agora. Com cancel_needs_store: true, cancelar vira um pedido à loja, não um cancelamento imediato. cancel_requested diz que esse pedido já foi feito.

can_change_paymentboolean

O cliente pode trocar a forma de pagamento.

can_reviewboolean

O pedido foi entregue e pode ser avaliado. reviewed fica false: a avaliação é por produto, veja Avaliações.

shipmentobject

Rastreio: tracking_code, carrier e tracking_url. Presente quando existe um envio com código.

status_trailarray

Linha do tempo real do pedido: code, name, color, at_unix, done e current.

Erros

Status	Quando	Corpo
404	O pedido não existe ou não é deste cliente.	`{"error":"order_not_found"}`
500	Falha ao ler o banco.	`{"error":"db_unavailable"}`

Consultar o rastreio

GET/api/v1/storefront/wa-coex/track/{token}/{orderID}Pública

Rastreio do pedido na transportadora

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido.

Resposta

200Rastreio disponível

json

{
  "carrier": "Correios",
  "status": "Objeto em trânsito",
  "pin": "AB123456789BR",
  "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objeto=AB123456789BR"
}

Campos da resposta

carrierstring

Nome da transportadora.

statusstring

Situação atual informada por ela.

pinstring

Código de rastreio.

tracking_urlstring

Link para acompanhar no site da transportadora.

Erros

Status	Quando	Corpo
204	Sem rastreio: pedido sem transportadora, pedido de outra pessoa, ou falha na consulta.	Sem corpo