Organizations y Merchants

Tokeflow es multi-tenant por diseño. Cada cuenta se modela como una Organization que posee uno o varios Merchants. Esta jerarquía de dos niveles es la base de cómo te autenticas, delimitas el alcance de los datos y gobiernas el acceso en toda tu plataforma.

Te integras en uno de dos niveles:

• Nivel Organization — un único conjunto de credenciales que opera sobre todos los merchants de la org. Ideal para plataformas y sistemas de back-office.
• Nivel Merchant — credenciales delimitadas a un solo merchant, donde el merchant se infiere automáticamente. Ideal para una sola tienda.

Esta página explica la jerarquía y te ayuda a elegir el nivel de integración adecuado. Para los formatos de encabezados y el manejo de claves, consulta Autenticación.

La jerarquía

Una Organization es el tenant de nivel superior. Posee Merchants. Cada Merchant está completamente aislado: tiene sus propias credenciales de API, catálogo de productos, clientes, transacciones y endpoints de webhook. Los datos nunca se filtran a través de los límites entre merchants.

Integración a nivel de Organization

Una clave de Organization abarca todos los merchants de la org. Úsala desde una plataforma central o un sistema de back-office que necesite operar en nombre de muchos merchants con una sola credencial.

Como una clave de org no está vinculada a un único merchant, debes indicarle a Tokeflow a qué merchant apunta una operación delimitada a un merchant:

• Endpoints de listar y leer: pasa el merchant como el parámetro de consulta merchant_id.
• Endpoints de crear: pasa merchant_id en el cuerpo de la solicitud.

Omitir merchant_id en una operación delimitada a un merchant devuelve 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",
  }),
});

Si falta merchant_id, la 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"
  }
}

Integración a nivel de Merchant

Una clave de Merchant está delimitada de forma permanente a un merchant. El merchant se infiere de la clave: nunca pasas merchant_id. Úsala para una sola tienda o cualquier integración que solo toque un 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",
  }),
});

Una respuesta exitosa se envuelve en el sobre de éxito estándar:

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

Clave de Organization vs clave de Merchant

Ambos niveles de clave existen como claves secretas (sk_…, solo del lado del servidor) y claves públicas (pk_…, seguras para el cliente). El nivel controla sobre qué entidad actúa la clave; el tipo controla dónde puede usarse. Consulta Autenticación para la anatomía y el manejo de las claves.

Cuándo usar cuál

Elige el nivel de integración que coincida con la forma en que tu sistema se mapea a los merchants.

Usa una clave de Organization cuando:

• Ejecutas una plataforma o marketplace que gestiona muchos merchants.
• Un servicio de back-office, facturación o analítica necesita visibilidad a nivel de org.
• Aprovisionas o reconcilias datos entre tiendas desde un solo lugar.

Usa una clave de Merchant cuando:

• Estás integrando una sola tienda o marca.
• Quieres las solicitudes más simples posibles, sin merchant_id que gestionar.
• Quieres limitar el radio de impacto de una credencial a un solo merchant.

Próximos pasos

• Autenticación — anatomía de las claves, encabezados, claves secretas vs públicas y reglas de seguridad.