Organizaciones y Comercios

La jerarquía Organización-Comercio es la base de cómo estructuras tu negocio en Koywe Pagos.

Organizaciones

Una Organización es la entidad de nivel superior que representa tu empresa en el sistema Koywe.

¿Qué es una Organización?

• La entidad raíz para toda tu empresa
• Puede contener múltiples comercios (unidades de negocio)
• Gestiona usuarios y permisos a nivel empresa
• Controla credenciales API y acceso
• Maneja reportes y facturación a nivel organización

Permisos de Organización

Las organizaciones tienen permisos jerárquicos:

• Usuarios a nivel organización pueden acceder a todos los comercios dentro de la organización
• Usuarios root tienen acceso administrativo completo
• Credenciales API pueden tener alcance a nivel organización o comercio

Comercios

Un Comercio representa una unidad de negocio individual, marca o entidad operacional dentro de tu organización.

¿Qué es un Comercio?

• Una sub-entidad bajo una organización
• Tiene sus propias cuentas virtuales para cada moneda
• Procesa pagos independientemente
• Mantiene historial de transacciones separado
• Puede tener usuarios y permisos específicos

Cuándo Usar Múltiples Comercios

Usa comercios separados cuando necesites:

Recursos Automáticos del Comercio

Cuando se crea un comercio, Koywe aprovisiona automáticamente:

1. Cuentas Virtuales: Una para cada moneda soportada

   • COP (Peso Colombiano)
   • BRL (Real Brasileño)
   • MXN (Peso Mexicano)
   • CLP (Peso Chileno)
   • USD (Dólar Estadounidense)
   • EUR (Euro)
   • Y más…

2. Contacto Predeterminado: Información del comercio como contacto

   • Usado para cumplimiento y reportes
   • Representa al comercio en transacciones

Cómo Trabajan Juntos

Operaciones API

Obtener Información de Organización

1
async function getOrganizations(token) {
2
  const response = await axios.get(
3
    'https://api-sandbox.koywe.com/api/v1/user/organizations',
4
    {
5
      headers: { 'Authorization': `Bearer ${token}` }
6
    }
7
  );
8
  
9
  return response.data;
10
}
11
12
// Uso
13
const orgs = await getOrganizations(token);
14
console.log('Organizaciones:', orgs);

Respuesta:

1
[
2
  {
3
    "id": "org_abc123",
4
    "name": "Acme Corporation",
5
    "country": "CO",
6
    "createdAt": "2025-01-01T00:00:00Z"
7
  }
8
]

Listar Comercios en una Organización

1
async function getMerchants(token, organizationId) {
2
  const response = await axios.get(
3
    `https://api-sandbox.koywe.com/api/v1/organizations/${organizationId}/merchants`,
4
    {
5
      headers: { 'Authorization': `Bearer ${token}` }
6
    }
7
  );
8
  
9
  return response.data;
10
}
11
12
// Uso
13
const merchants = await getMerchants(token, 'org_abc123');
14
console.log('Comercios:', merchants);

Respuesta:

1
[
2
  {
3
    "id": "mrc_xyz789",
4
    "name": "Acme Store",
5
    "organizationId": "org_abc123",
6
    "status": "ACTIVE",
7
    "createdAt": "2025-01-15T00:00:00Z"
8
  },
9
  {
10
    "id": "mrc_def456",
11
    "name": "Acme Marketplace",
12
    "organizationId": "org_abc123",
13
    "status": "ACTIVE",
14
    "createdAt": "2025-02-01T00:00:00Z"
15
  }
16
]

Obtener Detalles de Comercio Específico

1
async function getMerchant(token, organizationId, merchantId) {
2
  const response = await axios.get(
3
    `https://api-sandbox.koywe.com/api/v1/organizations/${organizationId}/merchants/${merchantId}`,
4
    {
5
      headers: { 'Authorization': `Bearer ${token}` }
6
    }
7
  );
8
  
9
  return response.data;
10
}
11
12
// Uso
13
const merchant = await getMerchant(token, 'org_abc123', 'mrc_xyz789');
14
console.log('Detalles del comercio:', merchant);

Mejores Prácticas

Estructura de Organización

Estrategia de Comercios

Convenciones de Nomenclatura

Usa nombres claros y descriptivos:

✅ Buenos nombres:

• “Acme Store - E-commerce Principal”
• “Acme Ubicación Bogotá”
• “Acme División Mayorista”

❌ Evita:

• “Comercio 1”
• “Comercio Prueba”
• “Nuevo Comercio 2025”

Permisos y Control de Acceso

Permisos a Nivel Organización

Los usuarios con acceso a nivel organización pueden:

• Ver todos los comercios
• Crear nuevos comercios
• Gestionar configuraciones de organización
• Generar credenciales API

Permisos a Nivel Comercio

Los usuarios con acceso a nivel comercio pueden:

• Ver solo el(los) comercio(s) asignado(s)
• Procesar órdenes para ese comercio
• Gestionar contactos del comercio
• Ver saldos del comercio

Alcance de Credenciales API

Las credenciales API pueden tener alcance a:

1. Nivel Organización

   • Acceso a todos los comercios
   • Útil para integraciones a nivel plataforma

2. Nivel Comercio

   • Acceso solo a comercio específico
   • Más seguro para casos de uso limitados

1
// Credenciales a nivel organización pueden acceder a cualquier comercio
2
const orders = await axios.get(
3
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
4
  { headers: { 'Authorization': `Bearer ${orgLevelToken}` } }
5
);
6
7
// Credenciales a nivel comercio están pre-alcanzadas
8
const orders = await axios.get(
9
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
10
  { headers: { 'Authorization': `Bearer ${merchantLevelToken}` } }
11
);

Ejemplo del Mundo Real

Empresa de E-Commerce Multi-Marca

Organización: FashionCo Inc.

Comercios:

1. PremiumBrand Store

   • Moda de alta gama e-commerce
   • Cuentas virtuales: COP, USD, EUR
   • Transacción promedio: $200 USD

2. BudgetBrand Store

   • Moda asequible e-commerce
   • Cuentas virtuales: COP, BRL, MXN
   • Transacción promedio: $30 USD

3. FashionCo Marketplace

   • Plataforma de vendedores terceros
   • Cuentas virtuales: COP, USD, BRL, MXN
   • Maneja tanto PAYIN (cliente) como PAYOUT (vendedor)

Beneficios de esta estructura:

• Reportes financieros separados por marca
• Branding diferente para experiencias de pago
• Gestión de saldo independiente
• Reconciliación más clara

Próximos Pasos