Pedidos
Ciclo de vida, status e o fluxo de reembolso que de fato aciona o provedor de pagamento.
Um pedido é criado a partir de um carrinho no checkout. A partir daí ele vive de forma independente: variantes podem ser excluídas, preços podem mudar, e o pedido guarda o que foi vendido e por quanto em um snapshot JSON de cada item.
Status
pending → paid → fulfilled → delivered
↓
refunded- pending: o pedido existe, a intenção de pagamento foi emitida, mas o dinheiro ainda não entrou. O estoque fica reservado.
- paid: o provedor de pagamento confirmou (via webhook ou ajuste manual no painel). O estoque passa de reservado para consumido.
- fulfilled: etiqueta de envio gerada ou pedido pronto para retirada.
- delivered: estado final de sucesso.
- cancelled: estado final de falha. As reservas são liberadas.
- refunded: pagamento totalmente estornado no provedor. Veja abaixo.
O enum status também tem draft, confirmed, processing e
shipped, e pode ganhar novos valores. Trate um status que você não
reconhece como "em andamento" em vez de falhar (veja
Convenções da API).
Endpoints
Os caminhos são relativos a https://api.mobiari.com/v1.
| Método | Caminho | Finalidade |
|---|---|---|
GET | /stores/{store_id}/orders | Lista. Filtros: status, customer_id, search, include_test. |
POST | /stores/{store_id}/orders | Cria um pedido (criado pelo painel). |
POST | /stores/{store_id}/orders/manual | Registra uma venda manual. |
GET | /stores/{store_id}/orders/{order_id} | Um pedido com itens, pagamento e envio. |
PATCH | /stores/{store_id}/orders/{order_id}/status | Altera o status, por exemplo {"status": "fulfilled"}. |
POST | /stores/{store_id}/orders/{order_id}/refund | Reembolsa pelo provedor de pagamento. |
Migração para o envelope Page
A listagem de pedidos está sendo migrada para a resposta padrão
Page com paginação por cursor.
Até Pedidos aparecer na referência da API, ela responde
com um array simples, ou {"orders": [...], "total", "limit", "offset"}
quando você envia limit, offset ou search.
O fluxo de reembolso
O botão Reembolsar no painel (e o POST .../refund na API) não se
limita a mudar uma coluna no banco de dados: ele de fato aciona o provedor
de pagamento. Hoje, esse provedor é o Mercado Pago. O handler:
- Carrega a intenção de pagamento aprovada mais recente do pedido.
- Chama a API de reembolso do Mercado Pago. Corpo vazio = reembolso total;
{"amount_cents": 1234}= reembolso parcial de R$ 12,34 (limitado ao valor pago). - Somente com uma resposta de sucesso do provedor ele altera o estado
local. Um reembolso total marca o pedido como
refunded, libera as reservas de estoque, cancela os jobs de produção pendentes e emiteorders.refunded. Um reembolso parcial mantém o status do pedido e define o status do pagamento comopartially_refunded.
Se a chamada ao provedor falhar (erro de rede, recusa, reembolso já feito),
o estado local não é alterado e você recebe um 502 bad_gateway, ou um 422
quando não há nada a reembolsar.
Envie um Idempotency-Key
Cada chamada de reembolso gera um novo reembolso no provedor. Se um
reembolso parcial expirar por timeout e você repetir a chamada às cegas,
o cliente pode ser reembolsado duas vezes. Envie um header
Idempotency-Key e reutilize o mesmo valor na nova tentativa: um
reembolso que já foi concluído é reproduzido em vez de repetido. Veja
Idempotência.
# Full refund:
curl -X POST \
"https://api.mobiari.com/v1/stores/$STORE_ID/orders/$ORDER_ID/refund" \
-H "Authorization: Bearer $BP_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: refund-$ORDER_ID-full" \
-d '{}'
# Partial refund of R$ 30,00:
curl -X POST \
"https://api.mobiari.com/v1/stores/$STORE_ID/orders/$ORDER_ID/refund" \
-H "Authorization: Bearer $BP_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8d4b0c1e-5a8f-4f7e-b1a2-6c3d9e0f1a2b" \
-d '{"amount_cents": 3000}'Pedidos com retirada
Se no checkout o comprador escolheu Retirar pedido na loja em vez de
envio, o pedido carrega um pickup_location_snapshot_json e a seção de
frete fica oculta. O snapshot é, de propósito, uma cópia do local no
momento da compra: depois você pode editar ou excluir o local físico sem
alterar o endereço de retirada do pedido.
O fulfillment_method do pedido é "shipping" ou "pickup" e indica ao
painel qual card exibir.
Resumo de permissões
| Ação | Permissão |
|---|---|
| Listar, consultar | orders.read |
| Criar (pelo painel) | orders.write |
| Atualizar status, processar envio | orders.edit / orders.fulfill |
| Cancelar | orders.cancel |
| Reembolsar | orders.refund |