Familias de productos del Merchant
Administre las familias de productos de un Merchant — la agrupación de nivel superior que organiza productos relacionados.
Una familia de productos es el contenedor de nivel superior para productos relacionados. No tiene un precio propio; existe para organizar el catálogo y delimitar el alcance de los informes. Estos endpoints respaldan la pantalla de familias de productos del Dashboard.
La eliminación de una familia se propaga en cascada a los productos que pertenecen a ella, por lo que las eliminaciones son reversibles (soft delete) y se pueden restaurar. Reordenar las familias cambia cómo se presenta el catálogo, no cómo se cobra algo.
Estos endpoints impulsan la UI del Tokeflow Dashboard. Están autenticados por sesión (JWT bearer) — el token proviene del inicio de sesión en el Dashboard, no de una clave de API sk_/pk_. Las solicitudes también incluyen el header x-merchant-id, que identifica al Merchant en contexto, y el usuario autenticado debe ser miembro con acceso a él.
El objeto de familia de productos
Devuelto por los endpoints de listado y obtención de esta página.
| Campo | Tipo | Descripción |
|---|---|---|
id | string | — |
merchant_id | string | — |
name | string | — |
slug | string | — |
description | string | null | — |
custom_plan_id | string | null | ID de referencia del plan externo (solo visualización). |
change_charge_behavior | string | Comportamiento predeterminado cuando una suscripción transiciona entre ofertas dentro de esta familia. Uno de next_renew, prorated, override. |
created_at | string | (ISO 8601 UTC). |
updated_at | string | (ISO 8601 UTC). |
Endpoints
GET/api/v1/merchant/product-families
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Enumera familias de productos.
Parámetros de consulta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
page | number | No | Número de página (indexado desde 1). Predeterminado 1, mín. 1. |
limit | number | No | Cantidad de elementos por página. Predeterminado 20, mín. 1, máx. 100. |
name | string | No | Filtro de coincidencia parcial por el nombre de la familia |
slug | string | No | Filtro por slug exacto |
change_charge_behavior | string | No | Uno de next_renew, prorated, override. |
Ejemplo de solicitud
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"Ejemplo de respuesta — 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
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Crea una familia de productos.
Campos de la solicitud
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
name | string | Sí | — |
slug | string | Sí | Identificador en minúsculas, único por Merchant. |
description | string | No | — |
custom_plan_id | string | No | ID de referencia del plan externo (solo visualización). |
change_charge_behavior | string | No | Comportamiento predeterminado de transición de oferta. Omita para usar next_renew. Uno de next_renew, prorated, override. |
Ejemplo de solicitud
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"
}'Ejemplo de respuesta — 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
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Rechaza con 409 mientras algún producto (activo) o suscripción (cualquier estado) haga referencia a la familia. Elimine o mueva los productos primero; las familias referenciadas por suscripciones se conservan para el historial de facturación.
Parámetros de ruta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
curl -X DELETE https://api.tokeflow.com/api/v1/merchant/product-families/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"Ejemplo de respuesta — 204 No Content
Se devuelve un cuerpo vacío cuando la operación tiene éxito.
GET/api/v1/merchant/product-families/:id
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Obtiene una familia de productos por ID.
Parámetros de ruta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
curl https://api.tokeflow.com/api/v1/merchant/product-families/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"Ejemplo de respuesta — 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
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Actualiza una familia de productos.
Parámetros de ruta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
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 '{}'Ejemplo de respuesta — 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
Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.
Restaura una familia de productos eliminada de forma reversible (soft delete).
Parámetros de ruta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
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"Ejemplo de respuesta — 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"
}Errores
Los errores utilizan el envelope estándar. Los casos más comunes aquí:
| HTTP | Significado |
|---|---|
400 | Parámetros inválidos o un estado que no permite esta operación. |
401 | Token de sesión del Dashboard ausente, expirado o inválido. |
403 | Autenticado, pero el usuario autenticado no tiene acceso a esta entidad. |
404 | El registro no existe o no es visible para esta entidad. |