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

`status`	Significado	Próximos estados
`active`	Gera um pedido real a cada data prevista.	`paused`, `canceled`
`paused`	Parada. Pode ser pausada pelo comprador, pela loja ou automaticamente após 3 falhas seguidas.	`active` (só o comprador retoma), `canceled`
`canceled`	Encerrada. Estado final.	nenhum
`completed`	Chegou ao fim (data final ou número de ocorrências). Estado final.	nenhum

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

bash

curl "$BASE_URL/api/v1/admin/b2b/standing-orders?status=active" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grades devolvidas

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"
        }
      ]
    }
  ]
}

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

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

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

bash

curl "$BASE_URL/api/v1/admin/b2b/standing-orders/forecast?days=90" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Projeção calculada

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
    }
  ]
}

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

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, módulo desligado	veja 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

bash

curl -X POST "$BASE_URL/api/v1/admin/b2b/standing-orders/55fb7008-5c77-4471-9f72-22a5d9d1f41b/pause" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grade pausada

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" }
  ]
}

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

Erros

Status	Quando	Corpo
404	Grade inexistente ou excluída	`{"error":"standing order not found"}`
409	Grade que não está `active` (já pausada, cancelada ou concluída)	`{"error":"invalid status transition"}`
403	Módulo desligado (checado também pelo serviço)	`{"error":"b2b-pricing module is disabled"}`
500	Id 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

bash

curl -X POST "$BASE_URL/api/v1/admin/b2b/standing-orders/55fb7008-5c77-4471-9f72-22a5d9d1f41b/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grade cancelada

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
}

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

Erros

Status	Quando	Corpo
404	Grade inexistente ou excluída	`{"error":"standing order not found"}`
409	Grade já cancelada ou concluída	`{"error":"invalid status transition"}`

Veja também

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.

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

O ciclo de uma grade

Ativa→Pausada→Cancelada

`status`	Significado	Próximos estados
`active`	Gera um pedido real a cada data prevista.	`paused`, `canceled`
`paused`	Parada. Pode ser pausada pelo comprador, pela loja ou automaticamente após 3 falhas seguidas.	`active` (só o comprador retoma), `canceled`
`canceled`	Encerrada. Estado final.	nenhum
`completed`	Chegou ao fim (data final ou número de ocorrências). Estado final.	nenhum

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

bash

curl "$BASE_URL/api/v1/admin/b2b/standing-orders?status=active" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grades devolvidas

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"
        }
      ]
    }
  ]
}

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

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

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

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

bash

curl "$BASE_URL/api/v1/admin/b2b/standing-orders/forecast?days=90" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Projeção calculada

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
    }
  ]
}

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

Status	Quando	Corpo
401 / 403	Sem token, sem privilégio, módulo desligado	veja 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

bash

curl -X POST "$BASE_URL/api/v1/admin/b2b/standing-orders/55fb7008-5c77-4471-9f72-22a5d9d1f41b/pause" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grade pausada

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" }
  ]
}

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

Erros

Status	Quando	Corpo
404	Grade inexistente ou excluída	`{"error":"standing order not found"}`
409	Grade que não está `active` (já pausada, cancelada ou concluída)	`{"error":"invalid status transition"}`
403	Módulo desligado (checado também pelo serviço)	`{"error":"b2b-pricing module is disabled"}`
500	Id 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

bash

curl -X POST "$BASE_URL/api/v1/admin/b2b/standing-orders/55fb7008-5c77-4471-9f72-22a5d9d1f41b/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grade cancelada

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
}

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

Erros

Status	Quando	Corpo
404	Grade inexistente ou excluída	`{"error":"standing order not found"}`
409	Grade já cancelada ou concluída	`{"error":"invalid status transition"}`