Famílias de produtos do Merchant

Gerencie as famílias de produtos de um Merchant — o agrupamento de nível superior que organiza produtos relacionados.

Uma família de produtos é o agrupamento de nível superior para produtos relacionados. Ela não tem preço próprio; existe para organizar o catálogo e delimitar o escopo dos relatórios. Esses endpoints dão suporte à tela de famílias de produtos do Dashboard.

A exclusão de uma família se propaga em cascata para os produtos vinculados a ela, portanto as remoções são reversíveis (soft delete) e podem ser restauradas. Reordenar famílias altera a forma como o catálogo é apresentado, não a forma como algo é cobrado.

Esses endpoints alimentam a UI do Tokeflow Dashboard. Eles são autenticados por sessão (JWT bearer) — o token vem do login no Dashboard, não de uma chave de API sk_/pk_. As requisições também carregam o header x-merchant-id, identificando o Merchant em contexto, e o usuário autenticado precisa ser um membro com acesso a ele.

O objeto de família de produtos

Retornado pelos endpoints de listagem e busca desta página.

Campo	Tipo	Descrição
`id`	string	—
`merchant_id`	string	—
`name`	string	—
`slug`	string	—
`description`	string \| null	—
`custom_plan_id`	string \| null	ID de referência do plano externo (somente exibição).
`change_charge_behavior`	string	Comportamento padrão quando uma assinatura transita entre ofertas nesta família. Um de `next_renew`, `prorated`, `override`.
`created_at`	string	(ISO 8601 UTC).
`updated_at`	string	(ISO 8601 UTC).

Endpoints

GET`/api/v1/merchant/product-families`

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Lista famílias de produtos.

Parâmetros de consulta

Campo	Tipo	Obrigatório	Descrição
`page`	number	Não	Número da página (indexado a partir de 1). Padrão `1`, mín. `1`.
`limit`	number	Não	Número de itens por página. Padrão `20`, mín. `1`, máx. `100`.
`name`	string	Não	Filtro de correspondência parcial pelo nome da família
`slug`	string	Não	Filtro por slug exato
`change_charge_behavior`	string	Não	Um de `next_renew`, `prorated`, `override`.

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/merchant/product-families \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "name=Streaming" \
  --data-urlencode "slug=streaming-plans"

Exemplo de resposta — 200

{
  "data": [
    {
      "id": "pfa_a1b2c3d4e5",
      "merchant_id": "mrc_a1b2c3d4e5",
      "name": "Streaming Plans",
      "slug": "streaming-plans",
      "description": "Family of streaming subscription plans",
      "custom_plan_id": "plan_external_42",
      "change_charge_behavior": "next_renew",
      "created_at": "2026-05-19T12:00:00Z",
      "updated_at": "2026-05-19T12:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

POST`/api/v1/merchant/product-families`

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Cria uma família de produtos.

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	—
`slug`	string	Sim	Identificador em minúsculas, único por Merchant.
`description`	string	Não	—
`custom_plan_id`	string	Não	ID de referência do plano externo (somente exibição).
`change_charge_behavior`	string	Não	Comportamento padrão de transição de oferta. Omita para usar next_renew. Um de `next_renew`, `prorated`, `override`.

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/merchant/product-families \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Streaming Plans",
    "slug": "streaming-plans",
    "description": "Family of streaming subscription plans",
    "custom_plan_id": "plan_external_42",
    "change_charge_behavior": "next_renew"
  }'

Exemplo de resposta — 201

{
  "id": "pfa_a1b2c3d4e5",
  "merchant_id": "mrc_a1b2c3d4e5",
  "name": "Streaming Plans",
  "slug": "streaming-plans",
  "description": "Family of streaming subscription plans",
  "custom_plan_id": "plan_external_42",
  "change_charge_behavior": "next_renew",
  "created_at": "2026-05-19T12:00:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

DELETE`/api/v1/merchant/product-families/:id`

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Recusa com 409 enquanto qualquer produto (ativo) ou assinatura (qualquer status) referenciar a família. Exclua ou mova os produtos primeiro; famílias referenciadas por assinaturas são mantidas para o histórico de cobrança.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	—

Exemplo de requisição

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/product-families/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Exemplo de resposta — 204 No Content

Um corpo vazio é retornado em caso de sucesso.

GET`/api/v1/merchant/product-families/:id`

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Obtém uma família de produtos pelo ID.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	—

Exemplo de requisição

curl https://api.tokeflow.com/api/v1/merchant/product-families/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Exemplo de resposta — 200

{
  "id": "pfa_a1b2c3d4e5",
  "merchant_id": "mrc_a1b2c3d4e5",
  "name": "Streaming Plans",
  "slug": "streaming-plans",
  "description": "Family of streaming subscription plans",
  "custom_plan_id": "plan_external_42",
  "change_charge_behavior": "next_renew",
  "created_at": "2026-05-19T12:00:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

PATCH`/api/v1/merchant/product-families/:id`

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Atualiza uma família de produtos.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	—

Exemplo de requisição

curl -X PATCH https://api.tokeflow.com/api/v1/merchant/product-families/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{}'

Exemplo de resposta — 200

{
  "id": "pfa_a1b2c3d4e5",
  "merchant_id": "mrc_a1b2c3d4e5",
  "name": "Streaming Plans",
  "slug": "streaming-plans",
  "description": "Family of streaming subscription plans",
  "custom_plan_id": "plan_external_42",
  "change_charge_behavior": "next_renew",
  "created_at": "2026-05-19T12:00:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

POST`/api/v1/merchant/product-families/:id/restore`

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Restaura uma família de produtos excluída de forma reversível (soft delete).

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	—

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/merchant/product-families/obj_1a2b3c4d/restore \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Exemplo de resposta — 201

{
  "id": "pfa_a1b2c3d4e5",
  "merchant_id": "mrc_a1b2c3d4e5",
  "name": "Streaming Plans",
  "slug": "streaming-plans",
  "description": "Family of streaming subscription plans",
  "custom_plan_id": "plan_external_42",
  "change_charge_behavior": "next_renew",
  "created_at": "2026-05-19T12:00:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

Erros

Os erros usam o envelope padrão. Os casos mais comuns aqui:

HTTP	Significado
`400`	Parâmetros inválidos ou um estado que não permite esta operação.
`401`	Token de sessão do Dashboard ausente, expirado ou inválido.
`403`	Autenticado, mas o usuário autenticado não tem acesso a esta entidade.
`404`	O registro não existe ou não está visível para esta entidade.

Famílias de produtos do Merchant

O objeto de família de produtos

Endpoints

GET`/api/v1/merchant/product-families`

POST`/api/v1/merchant/product-families`

DELETE`/api/v1/merchant/product-families/:id`

GET`/api/v1/merchant/product-families/:id`

PATCH`/api/v1/merchant/product-families/:id`

POST`/api/v1/merchant/product-families/:id/restore`

Erros

Relacionados

Nesta página

Famílias de produtos do Merchant

O objeto de família de produtos

Endpoints

GET/api/v1/merchant/product-families

POST/api/v1/merchant/product-families

DELETE/api/v1/merchant/product-families/:id

GET/api/v1/merchant/product-families/:id

PATCH/api/v1/merchant/product-families/:id

POST/api/v1/merchant/product-families/:id/restore

Erros

Relacionados

Nesta página

GET`/api/v1/merchant/product-families`

POST`/api/v1/merchant/product-families`

DELETE`/api/v1/merchant/product-families/:id`

GET`/api/v1/merchant/product-families/:id`

PATCH`/api/v1/merchant/product-families/:id`

POST`/api/v1/merchant/product-families/:id/restore`