Organizations & Merchants

A Tokeflow é multi-tenant por design. Cada conta é modelada como uma Organization que possui um ou mais Merchants. Essa hierarquia de dois níveis é a base de como você autentica, delimita o escopo dos dados e governa o acesso em toda a sua plataforma.

Você integra em um de dois níveis:

• Nível de Organization — um único conjunto de credenciais que opera em todos os merchants da organização. Ideal para plataformas e sistemas de back-office.
• Nível de Merchant — credenciais com escopo limitado a um único merchant, no qual o merchant é inferido automaticamente. Ideal para uma única loja.

Esta página explica a hierarquia e ajuda você a escolher o nível de integração certo. Para formatos de cabeçalho e manuseio de chaves, consulte Autenticação.

A hierarquia

Uma Organization é o tenant de nível superior. Ela possui Merchants. Cada Merchant é totalmente isolado: tem suas próprias credenciais de API, catálogo de produtos, clientes, transações e endpoints de webhook. Os dados nunca vazam através das fronteiras entre merchants.

Integração em nível de Organization

Uma chave de Organization abrange todos os merchants da organização. Use-a a partir de uma plataforma central ou de um sistema de back-office que precise operar em nome de muitos merchants com uma única credencial.

Como a chave de organização não está vinculada a um único merchant, você precisa informar à Tokeflow qual merchant uma operação com escopo de merchant tem como alvo:

• Endpoints de listagem e leitura: passe o merchant como o parâmetro de consulta merchant_id.
• Endpoints de criação: passe merchant_id no corpo da requisição.

Omitir merchant_id em uma operação com escopo de merchant retorna 400 validation_error.

# Organization key — list a specific merchant's transactions
curl https://api.tokeflow.com/api/v1/transactions?merchant_id=mrc_123&page=1&limit=20 \
  -H "Authorization: Bearer sk_live_org_xxxxxxxxxxxxxxxxxxxx"

// Organization key — create a customer for a specific merchant
const res = await fetch("https://api.tokeflow.com/api/v1/customers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TOKEFLOW_ORG_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    merchant_id: "mrc_123", // required for org keys on merchant-scoped resources
    email: "ada@example.com",
    name: "Ada Lovelace",
  }),
});

Se merchant_id estiver ausente, a API responde:

{
  "error": {
    "type": "validation_error",
    "code": "MERCHANT_ID_REQUIRED",
    "message": "merchant_id is required when using organization API keys",
    "details": {},
    "request_id": "req_8f3c2a1b9d",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

Integração em nível de Merchant

Uma chave de Merchant tem escopo permanentemente limitado a um único merchant. O merchant é inferido a partir da chave — você nunca passa merchant_id. Use-a para uma única loja ou qualquer integração que só toque em um merchant.

# Merchant key — list this merchant's transactions (no merchant_id needed)
curl https://api.tokeflow.com/api/v1/transactions?page=1&limit=20 \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxxxxxx"

// Merchant key — create a customer (merchant is inferred)
const res = await fetch("https://api.tokeflow.com/api/v1/customers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TOKEFLOW_MERCHANT_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    email: "ada@example.com",
    name: "Ada Lovelace",
  }),
});

Uma resposta bem-sucedida é encapsulada no envelope de sucesso padrão:

{
  "success": true,
  "data": {
    "id": "cust_4f9a1c2e7b",
    "merchant_id": "mrc_123",
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_8f3c2a1b9d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Chave de Organization vs chave de Merchant

Ambos os níveis de chave existem como chaves secretas (sk_…, apenas no lado do servidor) e chaves públicas (pk_…, seguras para o cliente). O nível controla sobre qual entidade a chave atua; o tipo controla onde ela pode ser usada. Consulte Autenticação para a anatomia e o manuseio das chaves.

Quando usar cada uma

Escolha o nível de integração que corresponde à forma como seu sistema mapeia para os merchants.

Use uma chave de Organization quando:

• Você opera uma plataforma ou marketplace que gerencia muitos merchants.
• Um serviço de back-office, faturamento ou análise precisa de visibilidade sobre toda a organização.
• Você provisiona ou concilia dados entre lojas a partir de um único lugar.

Use uma chave de Merchant quando:

• Você está integrando uma única loja ou marca.
• Você quer as requisições mais simples possíveis — sem merchant_id para gerenciar.
• Você quer limitar o raio de impacto de uma credencial a um único merchant.

Próximos passos

• Autenticação — anatomia das chaves, cabeçalhos, chaves secretas vs públicas e regras de segurança.