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

Pedidos programados

Supervisiona as grades de entrega dos compradores: lista, projeta a demanda futura e pausa ou cancela uma grade.

Um pedido programado (standing order, ou "grade de entrega") é uma compra recorrente que o comprador B2B agenda: "toda segunda, 200 unidades deste item". Quem cria e edita a grade é o próprio comprador, pela vitrine. A loja usa estas rotas para enxergar todas as grades, projetar a demanda dos próximos meses (útil para estoque e compras) e intervir quando preciso, pausando ou cancelando.

Exigem o módulo b2b-pricing e o privilégio manage_b2b ou manage_orders.

O ciclo de uma grade

Ativa→Pausada→Cancelada
statusSignificadoPróximos estados
activeGera um pedido real a cada data prevista.paused, canceled
pausedParada. Pode ser pausada pelo comprador, pela loja ou automaticamente após 3 falhas seguidas.active (só o comprador retoma), canceled
canceledEncerrada. Estado final.nenhum
completedChegou ao fim (data final ou número de ocorrências). Estado final.nenhum
A loja pausa, o comprador retoma

Não existe rota de administrador para retomar uma grade. Se a loja pausar por engano, o comprador precisa retomar pela vitrine. Já o cancelamento não tem volta.

Listar pedidos programados

Devolve as grades de toda a loja, da data mais próxima para a mais distante, já com os itens. Não há paginação.

GET/api/v1/admin/b2b/standing-ordersAdmin

Lista os pedidos programados da loja

Parâmetros de consulta

user_iduuid
Só as grades deste comprador.
statusstring
activepausedcanceledcompleted
Só as grades neste estado. Um valor desconhecido devolve lista vazia.

Exemplo de requisição

Resposta

200Grades devolvidas

Campos da resposta

iduuid
Id da grade.
user_iduuid
Comprador dono da grade.
corporate_account_iduuid
Conta corporativa, quando a grade pertence a uma empresa. Ausente quando não há.
contract_iduuid
Contrato vinculado, quando houver. Ausente quando não há.
namestring
Nome dado pelo comprador.
statusstring
activepausedcanceledcompleted
Estado.
frequencystring
weeklybiweeklymonthly
Frequência: a cada 7 dias, a cada 14 dias ou todo mês.
next_run_onstring
Próxima data de geração do pedido, YYYY-MM-DD.
ends_onstring
Data final, YYYY-MM-DD. Ausente quando a grade não tem fim.
occurrences_totalinteger
Total de ocorrências previstas. Ausente quando ilimitado.
occurrences_doneinteger
Quantas já foram geradas.
on_contract_expiredstring
pausecontinue_base
O que fazer se o contrato de preço vencer: pause para a grade, continue_base segue com o preço base.
consecutive_failuresinteger
Falhas seguidas de geração. Ao chegar em 3 a grade é pausada sozinha.
anchor_dayinteger
Dia do mês de referência das grades mensais (de 1 a 31). Em meses curtos a data é ajustada para o último dia e volta ao dia de referência no mês seguinte. Vale 0 em grades antigas, sem referência gravada.
shipping_addressobject
Endereço de entrega gravado na grade, ou null.
payment_method_idstring
Forma de pagamento escolhida, quando houver.
itemsarray
Linhas da grade: id, product_id, quantity (inteiro, 1 ou mais), product_name e sku.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo
401Sem token{"error":"missing authorization header"}
403Sem privilégio{"error":"insufficient privileges","privilege_required_any":["manage_b2b","manage_orders"]}
403Módulo desligado{"error":"module_disabled","module":"b2b-pricing"}
500user_id que não é UUID, ou falha de consulta{"error":"standing order operation failed","detail":"..."}
Preço não fica na grade

A grade guarda produto e quantidade, nunca o preço. O preço é resolvido no dia de gerar cada pedido, com a tabela ou o contrato em vigor naquele dia. Um reajuste de tabela já vale para as próximas entregas.

Projetar a demanda

Soma, por mês e por produto, o que as grades ativas vão pedir nos próximos dias. Serve para antecipar compra e estoque.

GET/api/v1/admin/b2b/standing-orders/forecastAdmin

Projeta a demanda futura das grades ativas

Parâmetros de consulta

daysintegerpadrão: 90
Horizonte da projeção, em dias a partir de hoje. Valor ausente, zero, negativo ou inválido volta para 90.

Exemplo de requisição

Resposta

200Projeção calculada

Campos da resposta

bucketsarray
Um item por mês e produto. Lista vazia quando não há grade ativa na janela. A ordem não é garantida: ordene no cliente.
monthstring
Mês da entrega, YYYY-MM.
product_iduuid
Produto.
skustring
SKU.
product_namestring
Nome do produto.
quantityinteger
Unidades previstas no mês, somando todas as grades.
revenue_centsinteger
Receita estimada em centavos, com o preço vigente hoje. É uma estimativa: preços mudam e o valor usa o preço do primeiro comprador encontrado para o par mês e produto.

Erros

StatusQuandoCorpo
401 / 403Sem token, sem privilégio, módulo desligadoveja a lista acima

Pausar uma grade

Para a geração de pedidos de uma grade active. Nada é cancelado: as datas futuras ficam guardadas até o comprador retomar.

POST/api/v1/admin/b2b/standing-orders/{id}/pauseAdmin

Pausa um pedido programado

Parâmetros de caminho

iduuidobrigatório
Id da grade.

Exemplo de requisição

Resposta

200Grade pausada

A resposta é a grade completa, com os campos da listagem, já no novo estado. O evento b2b.standing_order.paused é publicado.

Erros

StatusQuandoCorpo
404Grade inexistente ou excluída{"error":"standing order not found"}
409Grade que não está active (já pausada, cancelada ou concluída){"error":"invalid status transition"}
403Módulo desligado (checado também pelo serviço){"error":"b2b-pricing module is disabled"}
500Id que não é UUID{"error":"standing order operation failed","detail":"..."}

Cancelar uma grade

Encerra a grade de forma definitiva. Pedidos já gerados não são afetados.

POST/api/v1/admin/b2b/standing-orders/{id}/cancelAdmin

Cancela um pedido programado

Parâmetros de caminho

iduuidobrigatório
Id da grade.

Exemplo de requisição

Resposta

200Grade cancelada

Exemplo abreviado: a resposta real inclui items e os demais campos da listagem. O evento b2b.standing_order.canceled é publicado.

Erros

StatusQuandoCorpo
404Grade inexistente ou excluída{"error":"standing order not found"}
409Grade já cancelada ou concluída{"error":"invalid status transition"}
Cancelar é definitivo

Uma grade canceled não volta. Se a intenção é só interromper por um tempo, use a pausa e deixe o comprador retomar.

Veja também

  • Tabelas de preço
  • Visão geral de B2B
Anterior
Simulador, reajuste e prévia de preço
Próxima
Pagar.me: pagamentos e split
Nesta página
  • O ciclo de uma grade
  • Listar pedidos programados
  • Exemplo de requisição
  • Resposta
  • Erros
  • Projetar a demanda
  • Exemplo de requisição
  • Resposta
  • Erros
  • Pausar uma grade
  • Exemplo de requisição
  • Resposta
  • Erros
  • Cancelar uma grade
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/b2b/standing-orders?status=active" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/b2b/standing-orders/forecast?days=90" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/admin/b2b/standing-orders/55fb7008-5c77-4471-9f72-22a5d9d1f41b/pause" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/admin/b2b/standing-orders/55fb7008-5c77-4471-9f72-22a5d9d1f41b/cancel" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "standing_orders": [
    {
      "id": "55fb7008-5c77-4471-9f72-22a5d9d1f41b",
      "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "name": "Reposição mensal da filial Campinas",
      "status": "active",
      "frequency": "monthly",
      "next_run_on": "2026-11-05",
      "occurrences_total": 6,
      "occurrences_done": 1,
      "on_contract_expired": "pause",
      "consecutive_failures": 0,
      "anchor_day": 5,
      "shipping_address": null,
      "created_at": "2026-09-05T11:29:21Z",
      "updated_at": "2026-10-05T05:00:04Z",
      "items": [
        {
          "id": "5eaad2eb-a944-453e-8f43-ce1b0c797974",
          "product_id": "e3a71800-294f-4167-a755-cabedcf094b4",
          "quantity": 200,
          "product_name": "Teclado Pro Cinza",
          "sku": "SD-003568"
        }
      ]
    }
  ]
}
json
{
  "buckets": [
    {
      "month": "2026-11",
      "product_id": "e3a71800-294f-4167-a755-cabedcf094b4",
      "sku": "SD-003568",
      "product_name": "Teclado Pro Cinza",
      "quantity": 400,
      "revenue_cents": 3600000
    }
  ]
}
json
{
  "id": "55fb7008-5c77-4471-9f72-22a5d9d1f41b",
  "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
  "name": "Reposição mensal da filial Campinas",
  "status": "paused",
  "frequency": "monthly",
  "next_run_on": "2026-11-05",
  "occurrences_done": 1,
  "on_contract_expired": "pause",
  "consecutive_failures": 0,
  "anchor_day": 5,
  "items": [
    { "id": "5eaad2eb-a944-453e-8f43-ce1b0c797974", "product_id": "e3a71800-294f-4167-a755-cabedcf094b4", "quantity": 200, "product_name": "Teclado Pro Cinza", "sku": "SD-003568" }
  ]
}
json
{
  "id": "55fb7008-5c77-4471-9f72-22a5d9d1f41b",
  "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
  "name": "Reposição mensal da filial Campinas",
  "status": "canceled",
  "frequency": "monthly",
  "next_run_on": "2026-11-05",
  "occurrences_done": 1,
  "on_contract_expired": "pause",
  "consecutive_failures": 0,
  "anchor_day": 5
}