VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Compra B2B: atacado e pedidos programados

Controlar uma grade

Pausa, retoma e cancela uma grade e consulta os pedidos que ela gerou.

Depois de criada, a grade percorre um ciclo simples de estados. Estas quatro rotas movem a grade entre eles e mostram o histórico. As três ações não levam corpo e devolvem a grade inteira.

Pausar uma grade

Pausa uma grade active. Nenhum pedido é gerado enquanto ela estiver paused. A grade também é pausada sozinha após 3 falhas seguidas de geração.

POST/api/v1/storefront/b2b/standing-orders/{id}/pauseCliente

Pausar uma grade

Parâmetros de caminho

iduuidobrigatório
Id da grade.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/b2b/standing-orders/d2f6a8c0-3b5e-4719-a0c2-8e4f6b1d3a57/pause" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grade atualizada
json
{
  "id": "d2f6a8c0-3b5e-4719-a0c2-8e4f6b1d3a57",
  "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
  "name": "Reposição mensal de canetas",
  "status": "paused",
  "frequency": "monthly",
  "next_run_on": "2026-11-05",
  "ends_on": "2027-10-05",
  "occurrences_done": 0,
  "on_contract_expired": "pause",
  "consecutive_failures": 0,
  "anchor_day": 5,
  "shipping_address": {
    "zipcode": "01310-100",
    "address": "Avenida Paulista, 1000",
    "city": "São Paulo",
    "state": "SP"
  },
  "created_at": "2026-10-11T14:20:00Z",
  "updated_at": "2026-10-11T14:20:00Z",
  "items": [
    {
      "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "quantity": 200,
      "product_name": "Caneta esferográfica azul (cx 50)",
      "sku": "CAN-AZ-50"
    }
  ]
}

Campos da resposta

(corpo)object
A grade inteira, com o novo status.

Erros

StatusQuandoCorpo de exemplo
401Sem token de cliente no cabeçalho Authorization.{"error":"missing authorization header"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}
403Perfil só de leitura (viewer) numa conta corporativa.{"error":"not allowed to manage standing orders"}
404Grade inexistente ou de outro cliente.{"error":"standing order not found"}
409Transição não permitida a partir do estado atual.{"error":"invalid status transition"}
500id que não é um UUID válido, ou falha de leitura (a causa vem em detail).{"error":"standing order operation failed","detail":"..."}

Retomar uma grade

Volta uma grade paused para active e zera o contador de falhas. A data de next_run_on não muda: se ela já passou, o processamento diário gera um pedido por dia até alcançar o futuro. Se isso não é o que o cliente quer, cancele e crie outra grade.

POST/api/v1/storefront/b2b/standing-orders/{id}/resumeCliente

Retomar uma grade

Parâmetros de caminho

iduuidobrigatório
Id da grade.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/b2b/standing-orders/d2f6a8c0-3b5e-4719-a0c2-8e4f6b1d3a57/resume" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grade atualizada
json
{
  "id": "d2f6a8c0-3b5e-4719-a0c2-8e4f6b1d3a57",
  "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
  "name": "Reposição mensal de canetas",
  "status": "active",
  "frequency": "monthly",
  "next_run_on": "2026-11-05",
  "ends_on": "2027-10-05",
  "occurrences_done": 0,
  "on_contract_expired": "pause",
  "consecutive_failures": 0,
  "anchor_day": 5,
  "shipping_address": {
    "zipcode": "01310-100",
    "address": "Avenida Paulista, 1000",
    "city": "São Paulo",
    "state": "SP"
  },
  "created_at": "2026-10-11T14:20:00Z",
  "updated_at": "2026-10-11T14:20:00Z",
  "items": [
    {
      "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "quantity": 200,
      "product_name": "Caneta esferográfica azul (cx 50)",
      "sku": "CAN-AZ-50"
    }
  ]
}

Campos da resposta

(corpo)object
A grade inteira, com o novo status.

Erros

StatusQuandoCorpo de exemplo
401Sem token de cliente no cabeçalho Authorization.{"error":"missing authorization header"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}
403Perfil só de leitura (viewer) numa conta corporativa.{"error":"not allowed to manage standing orders"}
404Grade inexistente ou de outro cliente.{"error":"standing order not found"}
409Transição não permitida a partir do estado atual.{"error":"invalid status transition"}
500id que não é um UUID válido, ou falha de leitura (a causa vem em detail).{"error":"standing order operation failed","detail":"..."}

Cancelar uma grade

Cancela uma grade active ou paused. É definitivo: canceled e completed são estados finais. Pedidos já gerados continuam valendo.

POST/api/v1/storefront/b2b/standing-orders/{id}/cancelCliente

Cancelar uma grade

Parâmetros de caminho

iduuidobrigatório
Id da grade.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/b2b/standing-orders/d2f6a8c0-3b5e-4719-a0c2-8e4f6b1d3a57/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grade atualizada
json
{
  "id": "d2f6a8c0-3b5e-4719-a0c2-8e4f6b1d3a57",
  "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
  "name": "Reposição mensal de canetas",
  "status": "canceled",
  "frequency": "monthly",
  "next_run_on": "2026-11-05",
  "ends_on": "2027-10-05",
  "occurrences_done": 0,
  "on_contract_expired": "pause",
  "consecutive_failures": 0,
  "anchor_day": 5,
  "shipping_address": {
    "zipcode": "01310-100",
    "address": "Avenida Paulista, 1000",
    "city": "São Paulo",
    "state": "SP"
  },
  "created_at": "2026-10-11T14:20:00Z",
  "updated_at": "2026-10-11T14:20:00Z",
  "items": [
    {
      "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "quantity": 200,
      "product_name": "Caneta esferográfica azul (cx 50)",
      "sku": "CAN-AZ-50"
    }
  ]
}

Campos da resposta

(corpo)object
A grade inteira, com o novo status.

Erros

StatusQuandoCorpo de exemplo
401Sem token de cliente no cabeçalho Authorization.{"error":"missing authorization header"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}
403Perfil só de leitura (viewer) numa conta corporativa.{"error":"not allowed to manage standing orders"}
404Grade inexistente ou de outro cliente.{"error":"standing order not found"}
409Transição não permitida a partir do estado atual.{"error":"invalid status transition"}
500id que não é um UUID válido, ou falha de leitura (a causa vem em detail).{"error":"standing order operation failed","detail":"..."}

Histórico de pedidos gerados

Lista as tentativas de geração, da mais recente para a mais antiga: as que viraram pedido (created, com o order_id) e as que falharam (failed, com o motivo). Cada data tem no máximo uma tentativa.

GET/api/v1/storefront/b2b/standing-orders/{id}/runsCliente

Cada tentativa de gerar pedido de uma grade

Parâmetros de caminho

iduuidobrigatório
Id da grade.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/b2b/standing-orders/d2f6a8c0-3b5e-4719-a0c2-8e4f6b1d3a57/runs" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Tentativas
json
{
  "runs": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "standing_order_id": "d2f6a8c0-3b5e-4719-a0c2-8e4f6b1d3a57",
      "run_on": "2026-12-05",
      "status": "failed",
      "failure_reason": "credit",
      "created_at": "2026-12-05T08:00:03Z"
    },
    {
      "id": "9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
      "standing_order_id": "d2f6a8c0-3b5e-4719-a0c2-8e4f6b1d3a57",
      "run_on": "2026-11-05",
      "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "status": "created",
      "created_at": "2026-11-05T08:00:02Z"
    }
  ]
}

Campos da resposta

runsarray

Tentativas.

iduuid
Id da tentativa.
standing_order_iduuid
A grade.
run_onstring
Data da tentativa (YYYY-MM-DD).
order_iduuid
Pedido gerado. Só em created.
statusstring
createdfailed
Resultado.
failure_reasonstring
Só em failed: credit (limite de crédito insuficiente), contract_expired (contrato vencido com on_contract_expired: pause), no purchasable items, product <id>: price unavailable ou order: <erro ao criar o pedido>.
created_atstring
Quando a tentativa foi registrada (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
401Sem token de cliente no cabeçalho Authorization.{"error":"missing authorization header"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}
404Grade inexistente ou de outro cliente.{"error":"standing order not found"}
500id que não é um UUID válido, ou falha de leitura (a causa vem em detail).{"error":"standing order operation failed","detail":"..."}
Quando o pedido é gerado

Um processamento diário, que abre às 05:00 no horário de Brasília, gera um pedido por grade active cuja data chegou. Cada grade só gera um pedido por data, mesmo que o processamento rode mais de uma vez.

Veja também

  • Grades de entrega
  • Criar pedido (visão geral)
Anterior
Grades de entrega
Próxima
Assinaturas e compras programadas
Nesta página
  • Pausar uma grade
  • Retomar uma grade
  • Cancelar uma grade
  • Histórico de pedidos gerados
  • Veja também