API atual/Referência completa/Mini-loja WhatsApp: pedidos

Assinaturas e compras agendadas

Consulta se um produto pode ser assinado, cria uma assinatura ou compra agendada, lista e cancela as do cliente.

Dois tipos de compra recorrente, os mesmos da loja online (a mini-loja é só outra porta para o mesmo módulo, então o que nasce no WhatsApp aparece em "Minhas assinaturas" no site e o contrário também):

`kind`	O que é
`subscription` (assinatura)	Cobra e entrega sozinha a cada ciclo, com o desconto da assinatura.
`scheduled` (compra agendada)	Só a entrega programada a cada ciclo.

O ciclo é um número de dias (cycle_days) entre os que a loja oferece para o produto: semanal (7), quinzenal (14), mensal (30), bimestral (60), trimestral (90), quadrimestral (120), semestral (180) e anual (365). O preço nunca vem do cliente: o servidor calcula o preço com o desconto da assinatura.

Tudo isso depende do módulo de pagamentos recorrentes estar ligado na loja. Desligado, as leituras respondem 200 com enabled: false e as escritas respondem 403 module_disabled.

Ver se o produto pode ser assinado

GET/api/v1/storefront/wa-coex/recurring/{token}/product/{productID}Pública

Ciclos e descontos de assinatura de um produto

É o que a ficha do produto lê para decidir se mostra "Assine e economize".

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

productIDuuidobrigatório

Id do produto.

Resposta

200Produto assinável

json

{
  "enabled": true,
  "plan": {
    "options": [
      { "cycle_days": 15, "frequency": "quinzenal", "discount_percent": 5 },
      { "cycle_days": 30, "frequency": "mensal", "discount_percent": 10 }
    ]
  }
}

200Produto não assinável

json

{ "enabled": false }

Campos da resposta

enabledboolean

false quando o módulo está desligado, o produto não está à venda neste canal ou ele não pode ser assinado.

planobject

Presente quando enabled é true.

optionsarray

Ciclos oferecidos, do mais curto ao mais longo: cycle_days, frequency (o nome do ciclo, como mensal) e discount_percent (desconto da assinatura, omitido quando não há).

Um produto sem tabela de desconto, mas assinável, devolve um único ciclo mensal sem desconto.

Listar as do cliente

GET/api/v1/storefront/wa-coex/recurring/{token}Pública

Assinaturas e compras agendadas do cliente

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Resposta

200Assinaturas do cliente

json

{
  "enabled": true,
  "items": [
    {
      "id": "7d1f2a60-5c1e-4f51-b6b2-6d2c3a1e9f20",
      "kind": "subscription",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "product_name": "Café Especial 500g",
      "image_url": "/uploads/exemplo/cafe.png",
      "status": "active",
      "cycle_days": 30,
      "price_cents": 4590,
      "next_at_unix": 1794336000
    }
  ]
}

200Cliente sem conta

json

{ "enabled": true, "account_required": true, "items": [] }

Campos da resposta

enabledboolean

O módulo está ligado na loja. Desligado: false e items: [].

account_requiredboolean

Só aparece (true) quando o módulo está ligado mas o token não tem conta identificada. Sem conta não há assinatura.

itemsarray

Assinaturas e compras agendadas.

idstring

Id do item. Use na troca e no cancelamento.

kindstring

subscriptionscheduled

Tipo.

product_iduuid

Produto. product_name e image_url vêm do catálogo.

statusstring

Situação do item, como o módulo de pagamentos recorrentes a registra.

cycle_daysinteger

Ciclo, em dias.

price_centsinteger

Preço por ciclo com desconto, em centavos. Só na assinatura.

next_at_unixinteger

Próxima cobrança (assinatura) ou próxima entrega (agendada), em segundos Unix.

Criar uma assinatura ou compra agendada

POST/api/v1/storefront/wa-coex/recurring/{token}Pública

Cria uma assinatura ou uma compra agendada para um produto

Exige cliente com conta identificada e o módulo ligado. O produto precisa estar à venda no canal e ser assinável.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

product_iduuidobrigatório

Produto.

kindstringpadrão: scheduled

subscriptionscheduled

subscription cria assinatura. Qualquer outro valor (inclusive ausente) cria compra agendada.

cycle_daysinteger

Ciclo, em dias, entre os de plan.options. Ausente usa o ciclo mais curto. Valor que a loja não oferece é recusado.

O corpo aceita no máximo 4 KB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/recurring/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"subscription","product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035","cycle_days":30}'

Resposta

200Criada

json

{ "created": true }

A resposta não devolve o item. Releia a lista para obter o id.

Erros

Status	Quando	Corpo
400	Corpo ilegível, maior que 4 KB ou sem `product_id`.	`{"error":"invalid_body"}`
403	O módulo de pagamentos recorrentes está desligado na loja.	`{"error":"module_disabled","module":"recurring-payments"}`
404	A loja não tem o módulo ligado (detectado pelo token).	`{"error":"recurring_disabled"}`
404	O produto não está à venda no canal.	`{"error":"product_not_found","message":"Produto indisponível"}`
200	O token não tem conta identificada. Nada é criado.	`{"enabled":true,"account_required":true,"items":[]}`
422	O produto não pode ser assinado.	`{"error":"not_subscribable"}`
422	`cycle_days` que a loja não oferece para o produto.	`{"error":"invalid_cycle"}`
503	Falha ao criar.	`{"error":"recurring_unavailable"}`

Cancelar

POST/api/v1/storefront/wa-coex/recurring/{token}/{kind}/{id}/cancelPública

Cancela uma assinatura ou compra agendada do cliente

Cancela o item do cliente. O servidor confere que o id é mesmo do cliente antes de cancelar: id de outra pessoa responde 404 not_found, igual a um id que não existe.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

kindstringobrigatório

subscriptionscheduled

Tipo do item, o kind da listagem.

idstringobrigatório

id do item.

Corpo da requisição

reasonstring

Motivo do cancelamento, opcional. Corpo de até 2 KB.

Resposta

200Cancelada

json

{ "cancelled": true }

Erros

Status	Quando	Corpo
403	O módulo de pagamentos recorrentes está desligado na loja.	`{"error":"module_disabled","module":"recurring-payments"}`
404	O módulo está desligado (detectado pelo token).	`{"error":"recurring_disabled"}`
404	O item não existe ou não é do cliente.	`{"error":"not_found"}`
200	O token não tem conta identificada.	`{"enabled":true,"account_required":true,"items":[]}`
503	Falha ao cancelar.	`{"error":"recurring_unavailable"}`

Veja também

API atual/Referência completa/Mini-loja WhatsApp: pedidos

Assinaturas e compras agendadas

Consulta se um produto pode ser assinado, cria uma assinatura ou compra agendada, lista e cancela as do cliente.

`kind`	O que é
`subscription` (assinatura)	Cobra e entrega sozinha a cada ciclo, com o desconto da assinatura.
`scheduled` (compra agendada)	Só a entrega programada a cada ciclo.

Tudo isso depende do módulo de pagamentos recorrentes estar ligado na loja. Desligado, as leituras respondem 200 com enabled: false e as escritas respondem 403 module_disabled.

Ver se o produto pode ser assinado

GET/api/v1/storefront/wa-coex/recurring/{token}/product/{productID}Pública

Ciclos e descontos de assinatura de um produto

É o que a ficha do produto lê para decidir se mostra "Assine e economize".

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

productIDuuidobrigatório

Id do produto.

Resposta

200Produto assinável

json

{
  "enabled": true,
  "plan": {
    "options": [
      { "cycle_days": 15, "frequency": "quinzenal", "discount_percent": 5 },
      { "cycle_days": 30, "frequency": "mensal", "discount_percent": 10 }
    ]
  }
}

200Produto não assinável

json

{ "enabled": false }

Campos da resposta

enabledboolean

false quando o módulo está desligado, o produto não está à venda neste canal ou ele não pode ser assinado.

planobject

Presente quando enabled é true.

optionsarray

Ciclos oferecidos, do mais curto ao mais longo: cycle_days, frequency (o nome do ciclo, como mensal) e discount_percent (desconto da assinatura, omitido quando não há).

Um produto sem tabela de desconto, mas assinável, devolve um único ciclo mensal sem desconto.

Listar as do cliente

GET/api/v1/storefront/wa-coex/recurring/{token}Pública

Assinaturas e compras agendadas do cliente

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Resposta

200Assinaturas do cliente

json

{
  "enabled": true,
  "items": [
    {
      "id": "7d1f2a60-5c1e-4f51-b6b2-6d2c3a1e9f20",
      "kind": "subscription",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "product_name": "Café Especial 500g",
      "image_url": "/uploads/exemplo/cafe.png",
      "status": "active",
      "cycle_days": 30,
      "price_cents": 4590,
      "next_at_unix": 1794336000
    }
  ]
}

200Cliente sem conta

json

{ "enabled": true, "account_required": true, "items": [] }

Campos da resposta

enabledboolean

O módulo está ligado na loja. Desligado: false e items: [].

account_requiredboolean

Só aparece (true) quando o módulo está ligado mas o token não tem conta identificada. Sem conta não há assinatura.

itemsarray

Assinaturas e compras agendadas.

idstring

Id do item. Use na troca e no cancelamento.

kindstring

subscriptionscheduled

Tipo.

product_iduuid

Produto. product_name e image_url vêm do catálogo.

statusstring

Situação do item, como o módulo de pagamentos recorrentes a registra.

cycle_daysinteger

Ciclo, em dias.

price_centsinteger

Preço por ciclo com desconto, em centavos. Só na assinatura.

next_at_unixinteger

Próxima cobrança (assinatura) ou próxima entrega (agendada), em segundos Unix.

Criar uma assinatura ou compra agendada

POST/api/v1/storefront/wa-coex/recurring/{token}Pública

Cria uma assinatura ou uma compra agendada para um produto

Exige cliente com conta identificada e o módulo ligado. O produto precisa estar à venda no canal e ser assinável.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

product_iduuidobrigatório

Produto.

kindstringpadrão: scheduled

subscriptionscheduled

subscription cria assinatura. Qualquer outro valor (inclusive ausente) cria compra agendada.

cycle_daysinteger

Ciclo, em dias, entre os de plan.options. Ausente usa o ciclo mais curto. Valor que a loja não oferece é recusado.

O corpo aceita no máximo 4 KB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/recurring/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"subscription","product_id":"c3f92551-9dda-4fc7-b518-353d1c4e4035","cycle_days":30}'

Resposta

200Criada

json

{ "created": true }

A resposta não devolve o item. Releia a lista para obter o id.

Erros

Status	Quando	Corpo
400	Corpo ilegível, maior que 4 KB ou sem `product_id`.	`{"error":"invalid_body"}`
403	O módulo de pagamentos recorrentes está desligado na loja.	`{"error":"module_disabled","module":"recurring-payments"}`
404	A loja não tem o módulo ligado (detectado pelo token).	`{"error":"recurring_disabled"}`
404	O produto não está à venda no canal.	`{"error":"product_not_found","message":"Produto indisponível"}`
200	O token não tem conta identificada. Nada é criado.	`{"enabled":true,"account_required":true,"items":[]}`
422	O produto não pode ser assinado.	`{"error":"not_subscribable"}`
422	`cycle_days` que a loja não oferece para o produto.	`{"error":"invalid_cycle"}`
503	Falha ao criar.	`{"error":"recurring_unavailable"}`

Cancelar

POST/api/v1/storefront/wa-coex/recurring/{token}/{kind}/{id}/cancelPública

Cancela uma assinatura ou compra agendada do cliente

Cancela o item do cliente. O servidor confere que o id é mesmo do cliente antes de cancelar: id de outra pessoa responde 404 not_found, igual a um id que não existe.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

kindstringobrigatório

subscriptionscheduled

Tipo do item, o kind da listagem.

idstringobrigatório

id do item.

Corpo da requisição

reasonstring

Motivo do cancelamento, opcional. Corpo de até 2 KB.

Resposta

200Cancelada

json

{ "cancelled": true }

Erros

Status	Quando	Corpo
403	O módulo de pagamentos recorrentes está desligado na loja.	`{"error":"module_disabled","module":"recurring-payments"}`
404	O módulo está desligado (detectado pelo token).	`{"error":"recurring_disabled"}`
404	O item não existe ou não é do cliente.	`{"error":"not_found"}`
200	O token não tem conta identificada.	`{"enabled":true,"account_required":true,"items":[]}`
503	Falha ao cancelar.	`{"error":"recurring_unavailable"}`