Configuración del Merchant

Lee y actualiza la configuración y el perfil de un Merchant en el Dashboard, y gestiona a las personas que tienen acceso a él.

Estos endpoints alimentan la pantalla de configuración del Dashboard para un único Merchant: su perfil y configuración, además de los miembros del equipo que pueden iniciar sesión y actuar en su nombre.

La membresía aquí es lo que el encabezado x-merchant-id verifica en todas las demás llamadas del Dashboard — agrega o elimina un miembro y cambias quién puede gestionar el catálogo, los conectores y los pedidos de este Merchant.

Estos endpoints alimentan la Tokeflow Dashboard UI. Están autenticados por sesión (JWT bearer) — el token proviene de iniciar sesión en el Dashboard, no de una clave de API sk_/pk_. Las solicitudes también llevan el encabezado x-merchant-id que identifica al Merchant en contexto, y el usuario que ha iniciado sesión debe ser un miembro con acceso a él.

El objeto merchant

Devuelto por los endpoints de listado y de recuperación en esta página.

Campo	Tipo	Descripción
`id`	string	—
`organization_id`	string	—
`organization`	object	—
`name`	string	—
`slug`	string	—
`external_reference`	string \| null	—
`business_registration_number`	string \| null	—
`mcc`	string \| null	—
`phone_number`	string \| null	—
`address_line1`	string \| null	—
`address_line2`	string \| null	—
`city`	string \| null	—
`state`	string \| null	—
`postal_code`	string \| null	—
`country_code`	string \| null	—
`website`	string \| null	—
`status`	string	—
`created_at`	string	(ISO 8601 UTC).
`updated_at`	string	(ISO 8601 UTC).
`webhook_configs`	array	—
`memberships`	array	—
`customers`	array	—

Endpoints

GET`/api/v1/merchant/profile`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Obtiene el perfil del Merchant.

Ejemplo de solicitud

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

Ejemplo de respuesta — 200

{
  "id": "obj_1a2b3c4d",
  "organization_id": "org_4b21e7c3",
  "organization": {
    "id": "obj_1a2b3c4d",
    "name": "Acme Store",
    "slug": "acme-store",
    "status": "active",
    "business_registration_number": "string",
    "mcc": "string",
    "country_code": "BR",
    "external_reference": "string",
    "phone_number": "+5511987654321",
    "address_line1": "string",
    "address_line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:00.000Z",
    "memberships": [
      {
        "id": "obj_1a2b3c4d",
        "organization_id": "org_4b21e7c3",
        "user_id": "string",
        "role": "owner",
        "created_at": "2026-01-15T12:30:00.000Z",
        "updated_at": "2026-01-15T12:30:00.000Z",
        "organization": {},
        "user": {
          "id": "obj_1a2b3c4d",
          "email": "jane@example.com",
          "name": "Acme Store",
          "auth_provider": "string",
          "auth_subject_id": "string",
          "password_hash": "string",
          "last_login_at": "2026-01-15T12:30:00.000Z",
          "must_change_password": true,
          "refresh_token_hash": "string",
          "failed_login_attempts": 1,
          "locked_until": "2026-01-15T12:30:00.000Z",
          "created_at": "2026-01-15T12:30:00.000Z",
          "updated_at": "2026-01-15T12:30:00.000Z",
          "memberships": [
            {}
          ]
        }
      }
    ],
    "merchants": [
      {}
    ],
    "branding": {
      "id": "obj_1a2b3c4d",
      "organization_id": "org_4b21e7c3",
      "organization": {},
      "custom_url": "https://example.com/webhooks/tokeflow",
      "site_title": "string",
      "favicon": "string",
      "logo_light_mode": "string",
      "logo_dark_mode": "string",
      "collapsible_logo_light_mode": "string",
      "collapsible_logo_dark_mode": "string",
      "theme_primary_color": "#1c1c1c",
      "theme_secondary_color": "#1c1c1c",
      "show_name_with_logo": true,
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z"
    }
  },
  "name": "Acme Store",
  "slug": "acme-store",
  "external_reference": "string",
  "business_registration_number": "string",
  "mcc": "string",
  "phone_number": "+5511987654321",
  "address_line1": "string",
  "address_line2": "string",
  "city": "string",
  "state": "string",
  "postal_code": "string",
  "country_code": "BR",
  "website": "string",
  "status": "active",
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:00.000Z",
  "webhook_configs": [
    {
      "id": "obj_1a2b3c4d",
      "merchant_id": "mrc_8a3f12d9",
      "merchant": {},
      "url": "https://example.com/webhooks/tokeflow",
      "secret": {},
      "description": "Human-readable description",
      "event_filter": [
        "transaction.created"
      ],
      "is_active": true,
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z",
      "deleted_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "memberships": [
    {
      "id": "obj_1a2b3c4d",
      "merchant_id": "mrc_8a3f12d9",
      "user_id": "string",
      "role": "owner",
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z",
      "merchant": {},
      "user": {
        "id": "obj_1a2b3c4d",
        "organization_id": "org_4b21e7c3",
        "email": "jane@example.com",
        "name": "Acme Store",
        "auth_provider": "string",
        "auth_subject_id": "string",
        "password_hash": "string",
        "invitation_token": "string",
        "invitation_expires_at": "2026-01-15T12:30:00.000Z",
        "is_active": true,
        "last_login_at": "2026-01-15T12:30:00.000Z",
        "must_change_password": true,
        "refresh_token_hash": "string",
        "failed_login_attempts": 1,
        "locked_until": "2026-01-15T12:30:00.000Z",
        "created_at": "2026-01-15T12:30:00.000Z",
        "updated_at": "2026-01-15T12:30:00.000Z",
        "organization": {
          "id": "obj_1a2b3c4d",
          "name": "Acme Store",
          "slug": "acme-store",
          "status": "active",
          "business_registration_number": "string",
          "mcc": "string",
          "country_code": "BR",
          "external_reference": "string",
          "phone_number": "+5511987654321",
          "address_line1": "string",
          "address_line2": "string",
          "city": "string",
          "state": "string",
          "postal_code": "string",
          "created_at": "2026-01-15T12:30:00.000Z",
          "updated_at": "2026-01-15T12:30:00.000Z",
          "memberships": [
            {}
          ],
          "merchants": [
            {}
          ],
          "branding": {}
        },
        "memberships": [
          {}
        ]
      }
    }
  ],
  "customers": [
    {
      "id": "obj_1a2b3c4d",
      "merchant_id": "mrc_8a3f12d9",
      "merchant": {},
      "email": "jane@example.com",
      "name": "Acme Store",
      "phone": "+5511987654321",
      "document_type": "12345678909",
      "document_number": "12345678909",
      "metadata": {},
      "billing_address": {},
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z",
      "deleted_at": "2026-01-15T12:30:00.000Z"
    }
  ]
}

PATCH`/api/v1/merchant/profile`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Una vez que el Merchant está inscrito en la red de tarjetas para tokens de red, los campos enviados en la inscripción (name, website, mcc y la dirección) quedan fijos en las redes de tarjetas y ya no se pueden cambiar — intentarlo devuelve 409.

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`name`	string	No	—
`business_registration_number`	string	No	—
`mcc`	string	No	—
`country_code`	string	No	—
`phone_number`	string	No	—
`address_line1`	string	No	—
`address_line2`	string	No	—
`city`	string	No	—
`state`	string	No	Código de subdivisión ISO 3166-2 sin el prefijo de país ("SP", no "BR-SP"). Se verifica contra `country_code` cuando se envían ambos.
`postal_code`	string	No	—
`website`	string	No	—

Ejemplo de solicitud

curl -X PATCH https://api.tokeflow.com/api/v1/merchant/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John's Store",
    "business_registration_number": "12345678000199",
    "mcc": "5732",
    "country_code": "BR",
    "phone_number": "+55 11 99999-0000",
    "address_line1": "Av Paulista, 1000",
    "address_line2": "Apt 10",
    "city": "S\u00e3o Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "website": "https://johnsstore.com.br"
  }'

Ejemplo de respuesta — 200

{}

POST`/api/v1/merchant/team/invitations`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Aprovisiona una fila merchant_users con alcance en esta Organization (o reutiliza una existente) y adjunta una membresía para este Merchant. Envía un correo de invitación para que el destinatario pueda definir una contraseña.

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`email`	string	Sí	—
`role`	string	Sí	Uno de `owner`, `admin` o `viewer`.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/merchant/team/invitations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "role": "owner"
  }'

Ejemplo de respuesta — 201

{}

GET`/api/v1/merchant/team/members`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Lista los miembros del equipo.

Parámetros de consulta

Campo	Tipo	Obligatorio	Descripción
`page`	number	No	Número de página (indexado desde 1). Predeterminado `1`, mín. `1`.
`limit`	number	No	Número de elementos por página. Predeterminado `20`, mín. `1`, máx. `100`.

Ejemplo de solicitud

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

DELETE`/api/v1/merchant/team/members/:id`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Elimina un miembro del equipo.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	—

Ejemplo de solicitud

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

PATCH`/api/v1/merchant/team/members/:id`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Actualiza el rol de un miembro del equipo.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	—

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`role`	string	Sí	Uno de `owner`, `admin` o `viewer`.

Ejemplo de solicitud

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

POST`/api/v1/merchant/team/members/:id/resend`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Reenvía una invitación de equipo pendiente.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	—

Ejemplo de solicitud

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

Ejemplo de respuesta — 200

{
  "membership_id": "mem_7b2f9c14",
  "user_id": "string",
  "email": "jane@example.com",
  "name": "Acme Store",
  "role": "owner",
  "joined_at": "2026-01-15T12:30:00.000Z",
  "status": "active",
  "invitation_expires_at": "2026-01-15T12:30:00.000Z"
}

Errores

Los errores usan el envoltorio 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 que ha iniciado sesión no tiene acceso a esta entidad.
`404`	El registro no existe o no es visible para esta entidad.

Configuración del Merchant

El objeto merchant

Endpoints

GET`/api/v1/merchant/profile`

PATCH`/api/v1/merchant/profile`

POST`/api/v1/merchant/team/invitations`

GET`/api/v1/merchant/team/members`

DELETE`/api/v1/merchant/team/members/:id`

PATCH`/api/v1/merchant/team/members/:id`

POST`/api/v1/merchant/team/members/:id/resend`

Errores

Relacionados

En esta página

Configuración del Merchant

El objeto merchant

Endpoints

GET/api/v1/merchant/profile

PATCH/api/v1/merchant/profile

POST/api/v1/merchant/team/invitations

GET/api/v1/merchant/team/members

DELETE/api/v1/merchant/team/members/:id

PATCH/api/v1/merchant/team/members/:id

POST/api/v1/merchant/team/members/:id/resend

Errores

Relacionados

En esta página

GET`/api/v1/merchant/profile`

PATCH`/api/v1/merchant/profile`

POST`/api/v1/merchant/team/invitations`

GET`/api/v1/merchant/team/members`

DELETE`/api/v1/merchant/team/members/:id`

PATCH`/api/v1/merchant/team/members/:id`

POST`/api/v1/merchant/team/members/:id/resend`