tokeflow.com
DocumentaçãoReferência da APIDashboardsSDKsChangelog

Produtos

Crie e gerencie produtos — os itens vendáveis e planos do seu catálogo Tokeflow, agrupados em famílias e precificados por meio de ofertas.

Um produto é algo vendável: um item avulso como um curso, ou um plano recorrente como um nível de assinatura. Os produtos são a camada intermediária do catálogo. Eles pertencem a uma família de produtos e são precificados por meio de uma ou mais ofertas.

Use produtos para modelar o que você vende. Use ofertas para modelar como isso é comprado e cobrado.

Um produto tem um type (one_time ou recurring) e um status (active ou archived). Quando um produto pertence a uma família, seu tier_order o posiciona dentro dessa família — maior significa um plano superior — o que alimenta os caminhos de upgrade e downgrade entre planos recorrentes.

A Tokeflow é uma plataforma de orquestração de pagamentos, não um processador de pagamentos. O catálogo modela sua precificação; a autorização, captura e liquidação efetivas de qualquer cobrança acontecem no provedor de pagamento conectado. Os objetos do catálogo nunca movimentam dinheiro.

O objeto produto

{
  "id": "prd_a1b2c3d4e5",
  "merchant_id": "mrc_a1b2c3d4e5",
  "product_family_id": "pfa_a1b2c3d4e5",
  "name": "Plano Light",
  "description": "Plano com recursos essenciais",
  "type": "recurring",
  "tier_order": 1,
  "status": "active",
  "metadata": {
    "source": "dashboard"
  },
  "created_at": "2026-05-19T12:00:00.000Z",
  "updated_at": "2026-05-19T12:00:00.000Z"
}
FieldTypeDescription
idstringID único do produto, prefixado com prd_. Opaco — nunca faça parsing dele.
merchant_idstringO Merchant que é dono do produto (mrc_).
product_family_idstring | nullFamília à qual este produto pertence (pfa_), ou null se for independente.
namestringNome legível, por exemplo "Plano Light".
descriptionstring | nullDescrição mais longa opcional.
typeenumone_time ou recurring.
tier_orderinteger | nullPosição dentro da família (maior = plano superior). null quando o produto não tem família.
statusenumactive ou archived.
metadataobject | nullDados arbitrários de chave/valor que você anexa. Retornados como estão.
created_atstringTimestamp de criação em ISO 8601 UTC.
updated_atstringTimestamp da última atualização em ISO 8601 UTC.

Enums

EnumValues
typeone_time, recurring
statusactive, archived

tier_order é obrigatório sempre que product_family_id estiver definido, e deve ser único dentro da família. Ele é usado para ordenar planos em upgrades e downgrades. Para um produto independente (sem família), deixe-o não definido.

Criar um produto

POST/api/v1/products

Auth: chave de Organization (com merchant_id) ou chave de Merchant. Escopo: products:write.

Cria um produto sob um Merchant. Combine esta criação com uma chave de idempotência quando novas tentativas forem possíveis.

Parâmetros do corpo

FieldTypeRequiredDescription
namestringSimNome do produto.
typeenumSimone_time ou recurring.
statusenumSimactive ou archived.
product_family_idstringNãoFamília para agrupar o produto (pfa_). Obrigatório para produtos recorrentes que participam de fluxos de upgrade/downgrade.
tier_orderintegerCondicionalPosição dentro da família (mín. 0, maior = superior). Obrigatório quando product_family_id está definido.
descriptionstringNãoDescrição opcional.
metadataobjectNãoMetadados arbitrários para anexar.

Com uma chave de Organization, inclua merchant_id no corpo da requisição para direcionar a um Merchant. Com uma chave de Merchant, o Merchant é inferido a partir da chave — omita-o.

curl -X POST https://api.tokeflow.com/api/v1/products \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1f7e0a-2c3d-4e5f-8a9b-0c1d2e3f4a5b" \
  -d '{
    "name": "Plano Light",
    "type": "recurring",
    "status": "active",
    "product_family_id": "pfa_a1b2c3d4e5",
    "description": "Plano com recursos essenciais",
    "tier_order": 1,
    "metadata": { "source": "dashboard" }
  }'

Resposta 201 Created

{
  "success": true,
  "data": {
    "id": "prd_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "product_family_id": "pfa_a1b2c3d4e5",
    "name": "Plano Light",
    "description": "Plano com recursos essenciais",
    "type": "recurring",
    "tier_order": 1,
    "status": "active",
    "metadata": { "source": "dashboard" },
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T12:00:00.000Z"
  },
  "request_id": "req_8f3c…",
  "timestamp": "2026-05-19T12:00:00.000Z"
}

tier_order deve ser único dentro de uma família. Reutilizar um tier_order já ocupado por outro produto na mesma família retorna 409 (conflict_error).

Listar produtos

GET/api/v1/products

Auth: chave de Organization (com merchant_id) ou chave de Merchant. Escopo: products:read.

Retorna uma lista paginada de produtos do Merchant, do mais recente ao mais antigo. Todos os filtros são opcionais e se combinam com AND.

Parâmetros de query

FieldTypeRequiredDescription
pageintegerNãoNúmero da página, começando em 1. Padrão 1.
limitintegerNãoItens por página. Padrão 20, máx. 100.
typeenumNãoFiltra por one_time ou recurring.
statusenumNãoFiltra por active ou archived.
product_family_idstringNãoRestringe a uma única família (pfa_).
namestringNãoCorrespondência parcial e sem distinção entre maiúsculas e minúsculas no nome do produto.
date_fromstringNãoApenas produtos criados em/após este timestamp ISO 8601.
date_tostringNãoApenas produtos criados em/antes deste timestamp ISO 8601.
merchant_idstringCondicionalObrigatório com uma chave de Organization para direcionar a um Merchant.
curl "https://api.tokeflow.com/api/v1/products?page=1&limit=20&type=recurring&status=active&product_family_id=pfa_a1b2c3d4e5&name=Pro&date_from=2026-01-01T00:00:00Z&date_to=2026-12-31T23:59:59Z" \
  -H "Authorization: Bearer sk_live_mer_…"

Resposta 200 OK

{
  "success": true,
  "data": [
    {
      "id": "prd_a1b2c3d4e5",
      "merchant_id": "mrc_a1b2c3d4e5",
      "product_family_id": "pfa_a1b2c3d4e5",
      "name": "Plano Light",
      "description": "Plano com recursos essenciais",
      "type": "recurring",
      "tier_order": 1,
      "status": "active",
      "metadata": { "source": "dashboard" },
      "created_at": "2026-05-19T12:00:00.000Z",
      "updated_at": "2026-05-19T12:00:00.000Z"
    },
    {
      "id": "prd_f6e5d4c3b2",
      "merchant_id": "mrc_a1b2c3d4e5",
      "product_family_id": "pfa_a1b2c3d4e5",
      "name": "Plano Pro",
      "description": "Plano com recursos avançados",
      "type": "recurring",
      "tier_order": 2,
      "status": "active",
      "metadata": null,
      "created_at": "2026-05-19T12:05:00.000Z",
      "updated_at": "2026-05-19T12:05:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c…",
  "timestamp": "2026-05-19T12:30:00.000Z"
}

Consulte Paginação e filtragem para as convenções compartilhadas.

Obter um produto

GET/api/v1/products/:id

Auth: chave de Organization (com merchant_id) ou chave de Merchant. Escopo: products:read.

Recupera um único produto pelo ID.

curl https://api.tokeflow.com/api/v1/products/prd_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_…"

Resposta 200 OK

{
  "success": true,
  "data": {
    "id": "prd_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "product_family_id": "pfa_a1b2c3d4e5",
    "name": "Plano Light",
    "description": "Plano com recursos essenciais",
    "type": "recurring",
    "tier_order": 1,
    "status": "active",
    "metadata": { "source": "dashboard" },
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T12:00:00.000Z"
  },
  "request_id": "req_8f3c…",
  "timestamp": "2026-05-19T12:30:00.000Z"
}

Um ID desconhecido retorna 404 (not_found_error).

Atualizar um produto

PATCH/api/v1/products/:id

Auth: chave de Organization (com merchant_id) ou chave de Merchant. Escopo: products:write.

Atualização parcial. Envie apenas os campos que você deseja alterar; campos omitidos permanecem intocados.

Parâmetros do corpo

FieldTypeRequiredDescription
namestringNãoNovo nome.
typeenumNãoone_time ou recurring.
statusenumNãoactive ou archived.
product_family_idstringNãoMove o produto para outra família.
tier_orderintegerNãoNova posição dentro da família.
descriptionstringNãoNova descrição.
metadataobjectNãoSubstitui o objeto de metadados armazenado.
curl -X PATCH https://api.tokeflow.com/api/v1/products/prd_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Light Plus",
    "tier_order": 2
  }'

Resposta 200 OK

{
  "success": true,
  "data": {
    "id": "prd_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "product_family_id": "pfa_a1b2c3d4e5",
    "name": "Plano Light Plus",
    "description": "Plano com recursos essenciais",
    "type": "recurring",
    "tier_order": 2,
    "status": "active",
    "metadata": { "source": "dashboard" },
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T13:00:00.000Z"
  },
  "request_id": "req_8f3c…",
  "timestamp": "2026-05-19T13:00:00.000Z"
}

metadata é substituído, não mesclado. Para manter as chaves existentes, envie o objeto completo que você deseja armazenar.

Excluir um produto

DELETE/api/v1/products/:id

Auth: chave de Organization (com merchant_id) ou chave de Merchant. Escopo: products:write.

Exclui um produto de forma reversível (soft delete). O registro é retido para fins de auditoria e pode ser recuperado com restaurar. Um produto excluído de forma reversível não aparece mais nos resultados de listagem.

curl -X DELETE https://api.tokeflow.com/api/v1/products/prd_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_…"

Resposta 204 No Content

Uma exclusão bem-sucedida retorna um corpo vazio com status 204.

Exclusão reversível (soft delete) e arquivamento são diferentes. Arquivar mantém o produto no seu catálogo com status: archived (visível, não vendável). Excluir o remove do catálogo (recuperável via restauração). Use o arquivamento para aposentar um plano que você ainda quer referenciar; use a exclusão para retirar um produto por completo.

Restaurar um produto

POST/api/v1/products/:id/restore

Auth: chave de Organization (com merchant_id) ou chave de Merchant. Escopo: products:write.

Restaura um produto excluído de forma reversível, retornando-o ao catálogo com seus atributos anteriores.

curl -X POST https://api.tokeflow.com/api/v1/products/prd_a1b2c3d4e5/restore \
  -H "Authorization: Bearer sk_live_mer_…"

Resposta 201 Created

{
  "success": true,
  "data": {
    "id": "prd_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "product_family_id": "pfa_a1b2c3d4e5",
    "name": "Plano Light",
    "description": "Plano com recursos essenciais",
    "type": "recurring",
    "tier_order": 1,
    "status": "active",
    "metadata": { "source": "dashboard" },
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T14:00:00.000Z"
  },
  "request_id": "req_8f3c…",
  "timestamp": "2026-05-19T14:00:00.000Z"
}

Arquivar um produto

POST/api/v1/products/:id/archive

Auth: chave de Organization (com merchant_id) ou chave de Merchant. Escopo: products:write.

Define status como archived. O produto permanece no seu catálogo e histórico, mas não é mais oferecido para novas compras.

curl -X POST https://api.tokeflow.com/api/v1/products/prd_a1b2c3d4e5/archive \
  -H "Authorization: Bearer sk_live_mer_…"

Resposta 201 Created

{
  "success": true,
  "data": {
    "id": "prd_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "product_family_id": "pfa_a1b2c3d4e5",
    "name": "Plano Light",
    "description": "Plano com recursos essenciais",
    "type": "recurring",
    "tier_order": 1,
    "status": "archived",
    "metadata": { "source": "dashboard" },
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T15:00:00.000Z"
  },
  "request_id": "req_8f3c…",
  "timestamp": "2026-05-19T15:00:00.000Z"
}

Desarquivar um produto

POST/api/v1/products/:id/unarchive

Auth: chave de Organization (com merchant_id) ou chave de Merchant. Escopo: products:write.

Define status de volta para active, retornando um produto arquivado ao estado vendável.

curl -X POST https://api.tokeflow.com/api/v1/products/prd_a1b2c3d4e5/unarchive \
  -H "Authorization: Bearer sk_live_mer_…"

Resposta 201 Created

{
  "success": true,
  "data": {
    "id": "prd_a1b2c3d4e5",
    "merchant_id": "mrc_a1b2c3d4e5",
    "product_family_id": "pfa_a1b2c3d4e5",
    "name": "Plano Light",
    "description": "Plano com recursos essenciais",
    "type": "recurring",
    "tier_order": 1,
    "status": "active",
    "metadata": { "source": "dashboard" },
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T16:00:00.000Z"
  },
  "request_id": "req_8f3c…",
  "timestamp": "2026-05-19T16:00:00.000Z"
}

Obter a oferta padrão

GET/api/v1/products/:id/default-offer

Auth: chave de Organization (com merchant_id) ou chave de Merchant. Escopo: products:read.

Retorna a oferta padrão do produto — aquela que um checkout usa quando nenhuma oferta específica é indicada. Responde com data: null quando o produto não tem oferta padrão.

curl https://api.tokeflow.com/api/v1/products/prd_a1b2c3d4e5/default-offer \
  -H "Authorization: Bearer sk_live_mer_…"

Resposta 200 OK — oferta padrão existe

{
  "success": true,
  "data": {
    "id": "ofr_a1b2c3d4e5",
    "product_id": "prd_a1b2c3d4e5",
    "name": "Mensal",
    "slug": "mensal",
    "description": "Plano mensal padrão",
    "billing_cycle": "monthly",
    "custom_billing_days": null,
    "cycle_limit": 12,
    "free_trial": false,
    "trial_days": null,
    "setup_charge": false,
    "renew_after_cycle_limit": false,
    "renewal_offer_id": null,
    "is_default": true,
    "status": "active",
    "created_at": "2026-05-19T12:00:00.000Z",
    "updated_at": "2026-05-19T12:00:00.000Z",
    "prices": [
      {
        "id": "opr_b1c2d3e4f5",
        "offer_id": "ofr_a1b2c3d4e5",
        "currency": "BRL",
        "amount": 9900,
        "first_charge_amount": null,
        "is_default": true,
        "created_at": "2026-05-19T12:00:00.000Z",
        "updated_at": "2026-05-19T12:00:00.000Z"
      }
    ]
  },
  "request_id": "req_8f3c…",
  "timestamp": "2026-05-19T12:30:00.000Z"
}

Resposta 200 OK — sem oferta padrão

{
  "success": true,
  "data": null,
  "request_id": "req_8f3c…",
  "timestamp": "2026-05-19T12:30:00.000Z"
}

Os valores nos preços das ofertas são inteiros em unidades menores (centavos). 9900 com a moeda BRL é R$99,00. Consulte Ofertas e Preços de Ofertas para o modelo de precificação completo.

Erros

Os produtos usam o envelope de erro padrão. Casos comuns:

StatustypeQuando
400validation_errorCampo ausente/inválido, por exemplo type ou status desconhecido.
401authentication_errorChave de API ausente ou inválida.
403authorization_errorA chave não tem o escopo products:read / products:write necessário.
404not_found_errorNenhum produto com esse ID para o Merchant.
409conflict_errortier_order já usado por outro produto na família.

Consulte o catálogo de erros completo para códigos e tratamento.

Relacionados

Famílias de Produtos

Anterior

Ofertas

Próxima

Nesta página

O objeto produtoEnumsCriar um produtoPOST /api/v1/productsParâmetros do corpoResposta 201 CreatedListar produtosGET /api/v1/productsParâmetros de queryResposta 200 OKObter um produtoGET /api/v1/products/:idResposta 200 OKAtualizar um produtoPATCH /api/v1/products/:idParâmetros do corpoResposta 200 OKExcluir um produtoDELETE /api/v1/products/:idResposta 204 No ContentRestaurar um produtoPOST /api/v1/products/:id/restoreResposta 201 CreatedArquivar um produtoPOST /api/v1/products/:id/archiveResposta 201 CreatedDesarquivar um produtoPOST /api/v1/products/:id/unarchiveResposta 201 CreatedObter a oferta padrãoGET /api/v1/products/:id/default-offerResposta 200 OK — oferta padrão existeResposta 200 OK — sem oferta padrãoErrosRelacionados