Configurações do Merchant

Leia e atualize as próprias configurações e o perfil de um Merchant no Dashboard, e gerencie as pessoas que têm acesso a ele.

Estes endpoints alimentam a tela de configurações do Dashboard para um único Merchant: seu perfil e configuração, além dos membros da equipe que podem fazer login e agir em seu nome.

A associação aqui é o que o cabeçalho x-merchant-id verifica em todas as outras chamadas do Dashboard — adicione ou remova um membro e você muda quem pode gerenciar o catálogo, os conectores e os pedidos deste Merchant.

Estes endpoints alimentam a Tokeflow Dashboard UI. 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 cabeçalho x-merchant-id que identifica o Merchant em contexto, e o usuário logado deve ser um membro com acesso a ele.

O objeto merchant

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

Campo	Tipo	Descrição
`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). É necessário ser membro do Merchant.

Obtém o perfil do Merchant.

Exemplo de requisição

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

Exemplo de resposta — 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). É necessário ser membro do Merchant.

Uma vez que o Merchant esteja credenciado nas redes de cartões, os campos enviados no credenciamento (name, website, mcc e o endereço) ficam fixos nas redes de cartões e não podem mais ser alterados — a tentativa retorna 409.

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Não	—
`business_registration_number`	string	Não	—
`mcc`	string	Não	—
`country_code`	string	Não	—
`phone_number`	string	Não	—
`address_line1`	string	Não	—
`address_line2`	string	Não	—
`city`	string	Não	—
`state`	string	Não	Código de subdivisão ISO 3166-2 sem o prefixo de país ("SP", não "BR-SP"). Verificado contra `country_code` quando ambos são enviados.
`postal_code`	string	Não	—
`website`	string	Não	—

Exemplo de requisição

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"
  }'

Exemplo de resposta — 200

{}

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

Merchant

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

Provisiona uma linha merchant_users com escopo nesta Organization (ou reutiliza uma existente) e anexa uma associação para este Merchant. Envia um e-mail de convite para que o destinatário possa definir uma senha.

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`email`	string	Sim	—
`role`	string	Sim	Um dos `owner`, `admin` ou `viewer`.

Exemplo de requisição

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"
  }'

Exemplo de resposta — 201

{}

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

Merchant

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

Lista os membros da equipe.

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`.

Exemplo de requisição

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). É necessário ser membro do Merchant.

Remove um membro da equipe.

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/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). É necessário ser membro do Merchant.

Atualiza o papel de um membro da equipe.

Parâmetros de caminho

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

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`role`	string	Sim	Um dos `owner`, `admin` ou `viewer`.

Exemplo de requisição

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). É necessário ser membro do Merchant.

Reenvia um convite de equipe pendente.

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

Exemplo de resposta — 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"
}

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 logado não tem acesso a esta entidade.
`404`	O registro não existe ou não está visível para esta entidade.

Configurações do Merchant

O 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`

Erros

Relacionados

Nesta página

Configurações do Merchant

O 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

Erros

Relacionados

Nesta 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`