Produtos do Merchant

Gerencie os produtos de um Merchant a partir do Dashboard — os itens vendáveis pelos quais os clientes pagam, avulsos ou recorrentes.

Um produto é algo que um Merchant vende. Ele pertence a uma família de produtos e é vendido por meio de uma ou mais ofertas que definem os termos de cobrança. Esses endpoints dão suporte à tela de produtos do Dashboard: criar, listar, atualizar, excluir (soft delete) e restaurar.

Um produto é one_time ou recurring; o tipo molda quais ofertas e preços fazem sentido para ele. Os produtos são removidos por soft delete para que pedidos históricos continuem resolvendo para um registro real.

Esses endpoints alimentam a interface 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 solicitações também carregam o header x-merchant-id, identificando o Merchant em contexto, e o usuário autenticado deve ser membro com acesso a ele.

O objeto produto

Retornado pelos endpoints de listagem e recuperação desta página.

Campo	Tipo	Descrição
`id`	string	—
`merchant_id`	string	—
`product_family_id`	string \| null	—
`name`	string	—
`description`	string \| null	—
`type`	string	Um de `one_time`, `recurring`.
`tier_order`	number \| null	—
`status`	string	Um de `active`, `archived`.
`metadata`	object \| null	—
`created_at`	string	(ISO 8601 UTC).
`updated_at`	string	(ISO 8601 UTC).

Endpoints

GET`/api/v1/merchant/products`

Merchant

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

Lista os 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`.
`type`	string	Não	Um de `one_time`, `recurring`.
`status`	string	Não	Um de `active`, `archived`.
`product_family_id`	string	Não	Filtra os produtos para uma única família
`name`	string	Não	Filtro de correspondência parcial pelo nome do produto
`date_from`	string	Não	Filtra produtos criados após esta data (ISO 8601)
`date_to`	string	Não	Filtra produtos criados antes desta data (ISO 8601)

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/merchant/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "type=recurring" \
  --data-urlencode "status=active"

Exemplo de resposta — 200

{
  "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: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/products`

Merchant

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

Cria um produto.

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`product_family_id`	string	Não	ID opcional de família de produtos para agrupar produtos relacionados. Obrigatório para recorrentes com upgrade/downgrade.
`name`	string	Sim	—
`description`	string	Não	—
`type`	string	Sim	Um de `one_time`, `recurring`.
`tier_order`	number	Não	Posição na família. Maior = plano superior. Obrigatório quando product_family_id está definido.
`status`	string	Sim	Um de `active`, `archived`.
`metadata`	object	Não	Metadados arbitrários (jsonb).

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/merchant/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "product_family_id": "pfa_12345",
    "name": "Plano Light",
    "description": "Plano com recursos essenciais",
    "type": "recurring",
    "tier_order": 1,
    "status": "active",
    "metadata": {
      "source": "dashboard"
    }
  }'

Exemplo de resposta — 201

{
  "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:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

DELETE`/api/v1/merchant/products/:id`

Merchant

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

Recusa com 409 enquanto qualquer oferta (ativa) ou assinatura (qualquer status, via a oferta) referenciar o produto. Exclua as ofertas primeiro; produtos referenciados por assinaturas são mantidos 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/products/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/products/:id`

Merchant

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

Obtém um produto 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/products/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Exemplo de resposta — 200

{
  "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:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

PATCH`/api/v1/merchant/products/:id`

Merchant

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

Atualiza um produto.

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/products/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{}'

Exemplo de resposta — 200

{
  "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:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

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

Merchant

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

Arquiva um produto (status = archived).

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/products/obj_1a2b3c4d/archive \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Exemplo de resposta — 201

{
  "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:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

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

Merchant

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

Obtém a oferta padrão de um produto (null se não houver).

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/products/obj_1a2b3c4d/default-offer \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Exemplo de resposta — 200

{}

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

Merchant

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

Restaura um produto removido por 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/products/obj_1a2b3c4d/restore \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Exemplo de resposta — 201

{
  "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:00Z",
  "updated_at": "2026-05-19T12:00:00Z"
}

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

Merchant

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

Desarquiva um produto (status = active).

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/products/obj_1a2b3c4d/unarchive \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Exemplo de resposta — 201

{
  "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: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 é visível para esta entidade.

Produtos do Merchant

O objeto produto

Endpoints

GET`/api/v1/merchant/products`

POST`/api/v1/merchant/products`

DELETE`/api/v1/merchant/products/:id`

GET`/api/v1/merchant/products/:id`

PATCH`/api/v1/merchant/products/:id`

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

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

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

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

Erros

Relacionados

Nesta página

Produtos do Merchant

O objeto produto

Endpoints

GET/api/v1/merchant/products

POST/api/v1/merchant/products

DELETE/api/v1/merchant/products/:id

GET/api/v1/merchant/products/:id

PATCH/api/v1/merchant/products/:id

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

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

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

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

Erros

Relacionados

Nesta página

GET`/api/v1/merchant/products`

POST`/api/v1/merchant/products`

DELETE`/api/v1/merchant/products/:id`

GET`/api/v1/merchant/products/:id`

PATCH`/api/v1/merchant/products/:id`

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

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

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

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