Transições de oferta do Merchant

Uma transição de oferta é uma regra de cobrança por par para mudanças de plano. Ela fixa uma movimentação específica from_offer_id → to_offer_id — um upgrade, um downgrade ou uma troca de plano dentro da mesma família de produtos — a uma regra de cobrança (change_charge_behavior) e a um interruptor liga/desliga (is_active). Quando uma assinatura muda entre esse par exato de ofertas, a regra da transição tem precedência sobre o padrão da família de produtos.

Esses endpoints são a superfície por trás das telas de catálogo do dashboard: a tabela de transições, o diálogo de criação e os controles de ativar/desativar e excluir. Eles operam sobre as mesmas linhas de transição subjacentes que a API pública de transições de oferta — uma regra criada aqui fica imediatamente visível lá, e vice-versa.

Todo endpoint nesta página também requer o header x-merchant-id:

Como uma transição entra em vigor

Criar, desativar ou excluir uma transição muda qual regra de cobrança se aplica na próxima vez que uma assinatura se mover entre o par:

Uma transição inativa ou excluída nunca bloqueia uma mudança de plano — a movimentação simplesmente recorre ao change_charge_behavior padrão da família de produtos. Desativar (PATCH) é reversível; excluir não é.

O objeto de transição de oferta

Os três valores de change_charge_behavior:

Os endpoints do Dashboard retornam o objeto diretamente — não há um envelope success/data em torno das respostas de recurso único.

Endpoints

GET/api/v1/merchant/offer-transitions

Retorna uma lista paginada das transições de oferta do Merchant. Esta é a consulta por trás da tabela de transições do dashboard, incluindo seus filtros de oferta e status.

Parâmetros de consulta

Exemplo de solicitação

curl -G https://api.tokeflow.com/api/v1/merchant/offer-transitions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
  -H "x-merchant-id: mrc_123" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "is_active=true"

Exemplo de resposta — 200 OK

{
  "data": [
    {
      "id": "oft_a1b2c3d4e5",
      "from_offer_id": "ofr_3hk9d2",
      "to_offer_id": "ofr_7pq4m1",
      "change_charge_behavior": "next_renew",
      "is_active": true,
      "created_at": "2026-05-19T12:00:00Z",
      "updated_at": "2026-05-19T12:00:00Z"
    },
    {
      "id": "oft_f6g7h8i9j0",
      "from_offer_id": "ofr_7pq4m1",
      "to_offer_id": "ofr_3hk9d2",
      "change_charge_behavior": null,
      "is_active": true,
      "created_at": "2026-06-02T15:45:00Z",
      "updated_at": "2026-06-02T15:45:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

A segunda transição do exemplo define change_charge_behavior como null — a linha existe por causa do seu interruptor is_active, e a regra de cobrança recorre ao padrão da família.

Metadados de paginação

POST/api/v1/merchant/offer-transitions

Cria uma transição de oferta para um par from_offer_id → to_offer_id. Ambas as ofertas devem pertencer à mesma família de produtos.

Campos da solicitação

Exemplo de solicitação

curl -X POST https://api.tokeflow.com/api/v1/merchant/offer-transitions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
  -H "x-merchant-id: mrc_123" \
  -H "Content-Type: application/json" \
  -d '{
    "from_offer_id": "ofr_3hk9d2",
    "to_offer_id": "ofr_7pq4m1",
    "change_charge_behavior": "next_renew",
    "is_active": true
  }'

Exemplo de resposta — 201 Created

{
  "id": "oft_a1b2c3d4e5",
  "from_offer_id": "ofr_3hk9d2",
  "to_offer_id": "ofr_7pq4m1",
  "change_charge_behavior": "next_renew",
  "is_active": true,
  "created_at": "2026-05-19T12:00:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

Um 400 é retornado quando to_offer_id não pertence à mesma família de produtos que from_offer_id, ou quando change_charge_behavior não é um dos três valores permitidos.

GET/api/v1/merchant/offer-transitions/:id

Recupera uma única transição de oferta pelo ID. Retorna o objeto de transição de oferta.

Exemplo de solicitação

curl https://api.tokeflow.com/api/v1/merchant/offer-transitions/oft_a1b2c3d4e5 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
  -H "x-merchant-id: mrc_123"

Exemplo de resposta — 200 OK

{
  "id": "oft_a1b2c3d4e5",
  "from_offer_id": "ofr_3hk9d2",
  "to_offer_id": "ofr_7pq4m1",
  "change_charge_behavior": "next_renew",
  "is_active": true,
  "created_at": "2026-05-19T12:00:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

Um 404 é retornado se a transição não existir ou não pertencer ao Merchant em x-merchant-id.

PATCH/api/v1/merchant/offer-transitions/:id

Atualiza uma transição de oferta. O payload é um objeto parcial — envie apenas os campos que deseja alterar. As atualizações mais comuns são alternar is_active (o controle de ativar/desativar do dashboard) e ajustar change_charge_behavior, inclusive definindo-o como null para recorrer ao padrão da família.

Para redirecionar uma regra para um par de ofertas diferente, prefira excluir a transição e criar uma nova — o par from_offer_id → to_offer_id é a identidade da transição.

Exemplo de solicitação — desativar uma transição

curl -X PATCH https://api.tokeflow.com/api/v1/merchant/offer-transitions/oft_a1b2c3d4e5 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
  -H "x-merchant-id: mrc_123" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Exemplo de resposta — 200 OK

{
  "id": "oft_a1b2c3d4e5",
  "from_offer_id": "ofr_3hk9d2",
  "to_offer_id": "ofr_7pq4m1",
  "change_charge_behavior": "next_renew",
  "is_active": false,
  "created_at": "2026-05-19T12:00:00Z",
  "updated_at": "2026-08-12T09:30:00Z"
}

Enquanto is_active é false, o par é cobrado pelo change_charge_behavior padrão da família de produtos. Reative a qualquer momento com { "is_active": true }.

DELETE/api/v1/merchant/offer-transitions/:id

Exclui uma transição de oferta. A partir daí, as mudanças de plano entre o par seguem o change_charge_behavior padrão da família de produtos.

Exemplo de solicitação

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/offer-transitions/oft_a1b2c3d4e5 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs…" \
  -H "x-merchant-id: mrc_123"

Exemplo de resposta — 204 No Content

A resposta não tem corpo.

Erros

Consulte Erros para o formato de erro usado em toda a API.

Relacionados

• Transições de oferta (API pública) — o mesmo recurso via chaves de API sk_, com o modelo completo de precedência.
• Famílias de produtos — onde vive o change_charge_behavior padrão.
• Ofertas — os pares que uma transição conecta, incluindo o resolvedor de effective-behavior.
• Assinaturas — as mudanças de plano que essas regras governam.