Configuración de Organización e Invitaciones

Esta guía cubre los endpoints públicos de configuración que normalmente se usan antes de procesar pagos: invitaciones de organización, creación de merchants, invitaciones de usuarios, asignación de roles y generación de credenciales API.

Flujo Típico de Configuración

1. Aceptar Acceso a la Organización

Endpoints usados cuando un usuario se integra a una organización existente:

POST /api/v1/auth/organization-invitation/redeem
POST /api/v1/auth/invitation/redeem
POST /api/v1/auth/invitation/check-status

Usa la invitación de organización para acceso amplio y la invitación de merchant para acceso limitado a un merchant específico.

2. Listar Organizaciones

Después de autenticarte, lista las organizaciones disponibles:


curl -X GET 'https://api-sandbox.koywe.com/api/v1/organizations' \
  -H 'Authorization: Bearer TU_TOKEN'

La respuesta entrega el organizationId necesario para las operaciones a nivel organización.

3. Crear y Administrar Merchants

Endpoints del ciclo de vida del merchant:

POST /api/v1/organizations/{organizationId}/merchants
GET /api/v1/organizations/{organizationId}/merchants
GET /api/v1/organizations/{organizationId}/merchants/{merchantId}
PUT /api/v1/organizations/{organizationId}/merchants/{merchantId}
DELETE /api/v1/organizations/{organizationId}/merchants/{merchantId}

Cuando se crea un merchant, Koywe aprovisiona recursos por defecto como contactos y cuentas virtuales. Consulta Organizaciones y Merchants para el modelo de recursos.

4. Invitar Usuarios y Asignar Roles

Endpoints públicos de invitaciones:

POST /api/v1/users/organizations/{organizationId}/invitations
GET /api/v1/users/organizations/{organizationId}/invitations
POST /api/v1/users/organizations/{organizationId}/merchants/{merchantId}/invitations
GET /api/v1/users/organizations/{organizationId}/merchants/{merchantId}/invitations

Endpoints públicos de gestión de usuarios:

GET /api/v1/organizations/{organizationId}/users
PUT /api/v1/organizations/{organizationId}/users
GET /api/v1/organizations/{organizationId}/merchants/{merchantId}/users
PUT /api/v1/organizations/{organizationId}/merchants/{merchantId}/users

Usa invitaciones de organización para administradores corporativos y de merchant para usuarios operativos con alcance limitado.

5. Crear Credenciales API

Endpoints de credenciales:

POST /api/v1/auth/organizations/{organizationId}/credentials
POST /api/v1/auth/organizations/{organizationId}/merchants/{merchantId}/credentials
POST /api/v1/auth/organizations/{organizationId}/merchants/{merchantId}/pos/credentials/create

Usa credenciales de organización cuando una integración necesita acceso amplio. Usa credenciales de merchant cuando quieras mayor aislamiento.

6. Revisar Recursos del Merchant

Endpoints útiles después de la configuración:

GET /api/v1/organizations/{organizationId}/merchants/{merchantId}/features
GET /api/v1/organizations/{organizationId}/merchants/{merchantId}/virtual-accounts
GET /api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts/balances
GET /api/v1/organizations/{organizationId}/balances

Buenas Prácticas

Mantén separadas las organizaciones y credenciales de sandbox y producción.
Prefiere credenciales con alcance de merchant salvo que realmente necesites alcance de organización.
Usa invitaciones para gestionar acceso continuo en vez de compartir credenciales.
Guarda de forma segura los IDs retornados para organizaciones, merchants, usuarios y credenciales.