Compra coletiva

Na compra coletiva o pedido nasce preso a uma campanha: o cliente paga, mas nada é preparado até a campanha encerrar: só então a produção/preparação começa. Se sua integração só conhece o fluxo padrão, esses pedidos parecem "travados depois do pago"; este guia explica essa espera e como ela se destrava. É o workflow collective.

Quando um pedido cai aqui

Pedido de compra coletiva nasce quando o cliente compra um item vinculado a uma campanha de compra coletiva ativa. Você reconhece pelo workflow_type:

{
  "order_number": "ORD-000901",              // identificador público do pedido
  "workflow_type": "collective",             // ← compra coletiva (label "Compra Coletiva")
  "status": "awaiting_campaign_conclusion",  // ← a espera: "Aguardando Campanha"
  "is_collective": true,                     // atalho booleano equivalente a workflow_type=collective
  "is_awaiting_campaign": true,              // atalho booleano equivalente a status=awaiting_campaign_conclusion
  "release_at": "2026-05-10T23:59:59-03:00"       // data prevista de liberação (fim da campanha)
}

release_at vem denormalizado da campanha no momento do checkout: é a data que o job de liberação usa, não precisa recalcular a partir de outra rota.

O caminho

Em palavras: o pagamento confirma (paid), o sistema move sozinho o pedido para awaiting_campaign_conclusion, e ali ele fica até release_at passar. Um processo agendado da plataforma varre periodicamente os pedidos represados vencidos e move cada um para preparing, de onde segue como qualquer entrega (ou retirada, se for o caso).

Não existe cancelamento automático por meta não atingida. Ao contrário do que se poderia supor de uma "compra coletiva" (campanha que só confirma se atingir um mínimo de participantes), a liberação automática de hoje sempre leva o pedido para preparing quando a campanha encerra: não há uma checagem de meta mínima que cancele o lote. Se sua operação depende de uma meta mínima, esse controle precisa acontecer fora da API (ex.: você decide manualmente cancelar os pedidos represados antes do encerramento).

Etapa a etapa

Liberação e cancelamento manuais

Diferente do backorder (onde o destravamento manual reflete uma reposição de estoque real), aqui a máquina de estados permite ao seller agir antes do fim da campanha, sem esperar o job:

GET/api/v1/sellers/orders/{id}/possible-statuses

{
  "data": {
    "current_status": "awaiting_campaign_conclusion",
    "workflow_type": "collective",
    "next_actions": [
      {
        "action": "paid",
        "target_status": "paid",
        "label": "Pago",
        "payload_schema": null
      },
      {
        "action": "mark-preparing",
        "target_status": "preparing",
        "label": "Preparando",
        "payload_schema": null
      },
      {
        "action": "cancel",
        "target_status": "cancelled",
        "label": "Cancelado",
        "payload_schema": {
          "type": "object",
          "required": ["reason"],
          "properties": {
            "reason": { "type": "string", "minLength": 10, "maxLength": 500 }
          }
        }
      }
    ]
  }
}

Ignore o item action: "paid". Ele aparece na lista porque a máquina de estados interna permite a transição de volta pra paid, mas essa transição não é aceita por POST /orders/{id}/status (retorna 422 Status inválido para transição direta). Trate como ruído da API atual, não como uma ação disponível.

Para liberar o pedido antes do fim da campanha (ex.: você já sabe que vai produzir de qualquer forma):

POST /api/v1/sellers/orders/ORD-000901/status
Content-Type: application/json

{ "status": "preparing" }

Para cancelar durante a espera:

{
  "status": "cancelled",
  "data": { "reason": "Campanha cancelada pelo fornecedor." }
}

reason é obrigatório (mínimo 10 caracteres). A janela de cancelamento fecha quando o pedido entra em preparing: a partir daí, como em qualquer workflow, cancelar passa a ser assunto da operação da plataforma.

Como a integração percebe a espera

1. O campo status é awaiting_campaign_conclusion. Com status_label "Aguardando Campanha". O pedido não aparece nos seus filtros de fila de preparação (?status=paid,preparing), e isso é correto.

2. A listagem filtra por workflow.

GET /api/v1/sellers/orders?workflow=collective&status=awaiting_campaign_conclusion&sort=release_at

3. is_collective e is_awaiting_campaign são atalhos prontos. Em vez de comparar workflow_type/status manualmente em toda tela, o detalhe do pedido já traz esses dois booleanos.

4. A timeline conta a história.GET /orders/{id}/events registra o paid → awaiting_campaign_conclusion com autoria do sistema e, na liberação, o awaiting_campaign_conclusion → preparing, com a descrição "Liberação automática pós-campanha de compra coletiva" quando veio do job, ou a sua quando foi forçada manualmente.

Pontos de atenção

A liberação depende de um processo agendado da plataforma. Se esse processo não estiver rodando, pedidos com release_at vencido continuam represados indefinidamente. Se você notar pedidos "travados" muito além do release_at, é sinal de operação, não da sua integração.

Os dados do comprador ficam visíveis durante a espera.awaiting_campaign_conclusion acontece depois do pagamento confirmado, então customer_data_released vem true normalmente.

A emissão fiscal fica bloqueada durante a espera. Igual ao backorder: a API de emissão recusa com 422 enquanto o pedido está em awaiting_campaign_conclusion. A elegibilidade abre quando o pedido chega em preparing, exatamente como no fluxo de entrega.