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

Grades de entrega

Cria, lista, consulta e altera pedidos programados de uma cesta fixa.

Quatro rotas para o ciclo de vida de uma grade de entrega: criar, listar, consultar e alterar. Todas só enxergam e mudam grades do cliente do token e exigem o módulo b2b-pricing. Para pausar, retomar, cancelar e ver os pedidos gerados, veja Controlar uma grade.

Listar minhas grades

Devolve todas as grades do cliente, inclusive pausadas, canceladas e concluídas, em ordem de próxima data. Sem paginação e sem filtros. Cada grade vem com as linhas (items).

GET/api/v1/storefront/b2b/standing-ordersCliente

Grades de entrega do cliente logado

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/b2b/standing-orders" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grades
json
{
  "standing_orders": [
    {
      "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,
      "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"
        }
      ],
      "shipping_address": null
    }
  ]
}

Campos da resposta

standing_ordersarray
Grades, nos campos descritos em Criar uma grade. Na lista, shipping_address vem null.

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

Criar uma grade

Uma grade de entrega (standing order, ou pedido programado) é um contrato de recompra: o cliente define uma cesta e uma periodicidade e a plataforma gera um pedido real em cada data, sozinha. O preço não é fixado na criação: é calculado no dia de cada pedido, com as regras e o contrato vigentes. Nada é cobrado ao criar.

POST/api/v1/storefront/b2b/standing-ordersCliente

Programa pedidos recorrentes de uma cesta fixa

Corpo da requisição

namestringobrigatório
Nome da grade.
frequencystringobrigatório
weeklybiweeklymonthly
Periodicidade. Em monthly, o dia do mês de next_run_on é mantido, ajustado para o último dia nos meses curtos (31/jan vira 28/fev e volta a 31/mar).
next_run_onstringobrigatório
Data do primeiro pedido, YYYY-MM-DD.
itemsarrayobrigatório

Cesta fixa. Pelo menos uma linha válida.

product_iduuidobrigatório
Produto.
quantityintegerobrigatório
Quantidade, no mínimo 1. Linhas sem produto ou com quantidade menor que 1 são descartadas em silêncio.
ends_onstring
Data final, YYYY-MM-DD. Quando o próximo pedido passaria dessa data, a grade vira completed.
occurrences_totalinteger
Quantidade total de pedidos. Ao atingir, a grade vira completed.
on_contract_expiredstringpadrão: pause
pausecontinue_base
Se a grade está presa a um contrato e ele vence: pausar ou seguir ao preço normal. Qualquer outro valor vira pause.
contract_iduuid
Contrato de preços a que a grade fica presa.
corporate_account_iduuid
Conta corporativa dona da compra.
payment_method_iduuid
Forma de pagamento dos pedidos gerados.
shipping_addressobject
Endereço de entrega dos pedidos gerados, em JSON livre. Envie sempre, com o CEP; sem ele ({}) o pedido gerado não tem para onde ir.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/b2b/standing-orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reposição mensal de canetas",
    "frequency": "monthly",
    "next_run_on": "2026-11-05",
    "ends_on": "2027-10-05",
    "items": [
      {
        "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
        "quantity": 200
      }
    ],
    "shipping_address": {
      "zipcode": "01310-100",
      "address": "Avenida Paulista, 1000",
      "city": "São Paulo",
      "state": "SP"
    }
  }'

Resposta

201Grade criada
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

iduuid
Id da grade.
user_iduuid
Dono (o cliente do token).
corporate_account_iduuid
Conta corporativa, se informada. Ausente se não.
contract_iduuid
Contrato de preços a que a grade está presa, se houver.
namestring
Nome dado pelo cliente.
statusstring
activepausedcanceledcompleted
Estado da grade.
frequencystring
weeklybiweeklymonthly
Periodicidade: a cada 7, 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 se não houver.
occurrences_totalinteger
Total de pedidos previstos. Ausente se ilimitado.
occurrences_doneinteger
Pedidos já gerados.
on_contract_expiredstring
pausecontinue_base
O que fazer se o contrato vencer: pause pausa a grade; continue_base segue com o preço normal.
consecutive_failuresinteger
Falhas seguidas. Ao chegar a 3, a grade é pausada sozinha.
anchor_dayinteger
Dia do mês de referência (1 a 31) da grade mensal, para não "derivar" em meses curtos.
shipping_addressobject
Endereço de entrega usado nos pedidos. Livre; veja o aviso. Só vem no detalhe, não na lista.
payment_method_iduuid
Forma de pagamento dos pedidos, se informada.
created_at, updated_atstring
Datas (RFC 3339).
itemsarray
Linhas da grade: id, product_id, quantity, product_name, sku.

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido; name vazio; frequency fora da lista; next_run_on que não é uma data YYYY-MM-DD; nenhuma linha válida.{"error":"invalid standing order input","detail":"invalid standing order input"}
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"}
500Produto inexistente (viola vínculo) ou falha de gravação. A causa vem em detail.{"error":"standing order operation failed","detail":"..."}
Data no passado dispara pedidos em sequência

A data de next_run_on não é conferida. O processamento diário gera um pedido por dia enquanto next_run_on não alcançar o futuro, avançando um período a cada pedido. Envie sempre uma data de hoje em diante.

Consultar uma grade

Devolve a grade completa, inclusive shipping_address. Só enxerga grades do próprio cliente; a de outro cliente responde 404, como se não existisse.

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

Detalhe de uma grade com endereço e linhas

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" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grade
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
Os campos descritos em Criar uma grade.

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":"..."}

Alterar uma grade

Muda o nome e/ou a cesta. A alteração vale a partir do próximo pedido; pedidos já gerados não mudam. Periodicidade, datas, endereço e forma de pagamento não podem ser alterados aqui: cancele a grade e crie outra.

PUT/api/v1/storefront/b2b/standing-orders/{id}Cliente

Renomeia a grade e/ou troca a cesta

Parâmetros de caminho

iduuidobrigatório
Id da grade.

Corpo da requisição

namestring
Novo nome. Vazio ou ausente mantém o atual.
itemsarray

Nova cesta completa: linhas que não estiverem na lista são removidas. Ausente mantém a cesta; presente sem nenhuma linha válida é recusado.

product_iduuidobrigatório
Produto.
quantityintegerobrigatório
Quantidade, no mínimo 1. Linhas sem produto ou com quantidade menor que 1 são descartadas em silêncio.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/storefront/b2b/standing-orders/d2f6a8c0-3b5e-4719-a0c2-8e4f6b1d3a57" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reposição mensal de canetas e blocos",
    "items": [
      {
        "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
        "quantity": 300
      },
      {
        "product_id": "5a7b9c1d-3e4f-4a6b-8c0d-2e4f6a8b0c1d",
        "quantity": 50
      }
    ]
  }'

Resposta

200Grade atualizada
json
{
  "id": "d2f6a8c0-3b5e-4719-a0c2-8e4f6b1d3a57",
  "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
  "name": "Reposição mensal de canetas e blocos",
  "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, nos campos de Criar uma grade.

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido, ou items sem nenhuma linha válida.{"error":"invalid standing order input","detail":"invalid standing order input: grade must keep at least one item"}
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"}
500id que não é um UUID válido, ou falha de leitura (a causa vem em detail).{"error":"standing order operation failed","detail":"..."}
`items` substitui a cesta inteira

Para aumentar a quantidade de um produto, reenvie todas as linhas desejadas. Mandar só a linha alterada apaga as outras.

Veja também

  • Controlar uma grade
  • Preço de atacado
Anterior
Preço de atacado
Próxima
Controlar uma grade
Nesta página
  • Listar minhas grades
  • Criar uma grade
  • Consultar uma grade
  • Alterar uma grade
  • Veja também