跳转到主要内容

​
查询用户

​
获取所有用户

GET /api/v2/users?type=PERSON
过滤参数：
  • type - PERSON 或 COMPANY
  • id - 特定用户 ID
  • externalId - 您系统的用户 ID
  • firstName, lastName - 姓名搜索
  • email - 电子邮件搜索
  • customerId - 按客户过滤
  • limit, page - 分页
示例： 
curl --request GET \
  --url 'https://teste-94u93qnn.uc.gateway.dev/api/v2/users?type=PERSON&limit=10&page=1' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
响应： 
{
  "users": [
    {
      "id": "user-1",
      "type": "PERSON",
      "status": "ACTIVE",
      "accessLevel": "L2",
      "data": { /* 用户数据 */ }
    }
  ],
  "totalPage": 5
}

​
按 ID 获取用户

GET /api/v2/users/{userId}

const getUser = async (userId) => {
  const response = await fetch(
    `https://teste-94u93qnn.uc.gateway.dev/api/v2/users/${userId}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );
  
  return await response.json();
};

​
按外部 ID 查找

GET /api/v2/users?externalId=user-12345
使用 externalId 通过您的内部用户 ID 快速查找用户，而无需到处存储 KillB 的用户 ID。

​
更新用户

PATCH /api/v2/users/{userId}
创建后更新用户信息： 
{
  "type": "PERSON",
  "data": {
    "email": "[email protected]",
    "phone": "+573009876543",
    "address": {
      "street1": "New Street 456",
      "city": "Medellín",
      "state": "Antioquia",
      "zipCode": "050001",
      "countryCode": "CO"
    }
  }
}
可更新字段：
  • 电子邮件
  • 电话号码
  • 地址
  • 就业信息
  • 投资资料
  • KYC 资料
更改某些字段（如文档号码）可能会触发重新验证，并暂时将状态设置为 PENDING。

​
删除用户

DELETE /api/v2/users/{userId}

const deleteUser = async (userId) => {
  const response = await fetch(
    `https://teste-94u93qnn.uc.gateway.dev/api/v2/users/${userId}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );
  
  if (response.ok) {
    console.log('用户已成功删除');
  }
};
用户删除是软删除。用户数据为合规目的而保留，但标记为不活动。具有待处理 ramps 的用户无法删除。

​
用户状态管理

监控和处理不同的用户状态： 
const handleUserStatus = (user) => {
  switch(user.status) {
    case 'ACTIVE':
      // 用户可以交易
      return { canTransact: true, message: '准备交易' };
      
    case 'PENDING':
      // KYC 审核中
      return {
        canTransact: false,
        message: 'KYC 验证进行中',
        action: `在 ${user.complianceUrl} 完成验证`
      };
      
    case 'REJECTED':
      // KYC 被拒绝
      return {
        canTransact: false,
        message: '验证失败',
        reason: user.note,
        action: '请重新提交文档'
      };
      
    default:
      return { canTransact: false };
  }
};

​
批量操作

​
获取多个用户

const getUsersByExternalIds = async (externalIds) => {
  const users = await Promise.all(
    externalIds.map(externalId =>
      fetch(`/api/v2/users?externalId=${externalId}`, {
        headers: { 'Authorization': `Bearer ${token}` }
      }).then(r => r.json())
    )
  );
  
  return users.flat(2); // 展平嵌套数组
};

​
批量用户创建

const createMultipleUsers = async (usersData) => {
  const results = {
    successful: [],
    failed: []
  };
  
  for (const userData of usersData) {
    try {
      const user = await createUser(userData);
      results.successful.push(user);
    } catch (error) {
      results.failed.push({
        externalId: userData.externalId,
        error: error.message
      });
    }
  }
  
  return results;
};

​
同步用户数据

保持您的系统和 KillB 之间的用户数据同步： 
const syncUser = async (localUserId) => {
  // 从数据库获取用户
  const localUser = await db.users.findById(localUserId);
  
  if (!localUser.killbUserId) {
    // 在 KillB 中创建
    const killbUser = await createUser(localUser);
    await db.users.update(localUserId, {
      killbUserId: killbUser.id
    });
    return killbUser;
  }
  
  // 从 KillB 获取当前状态
  const killbUser = await getUser(localUser.killbUserId);
  
  // 更新本地数据库
  await db.users.update(localUserId, {
    kycStatus: killbUser.status,
    kycLevel: killbUser.accessLevel
  });
  
  return killbUser;
};

​
Webhook 集成

使用 webhooks 保持更新： 
app.post('/webhooks/killb', (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'user.updated') {
    // 更新本地数据库
    db.users.updateByKillbId(data.id, {
      kycStatus: data.status,
      kycLevel: data.accessLevel,
      updatedAt: new Date()
    });
  }
  
  res.status(200).json({ received: true });
});

​
最佳实践

创建用户时始终提供 externalId：
{
  "externalId": yourSystemUserId,
  "data": { /* 用户信息 */ }
}
这允许轻松查找，而无需到处存储 KillB ID。
在本地存储频繁访问的数据：
const getUserWithCache = async (userId) => {
  const cached = await cache.get(`user:${userId}`);
  if (cached) return cached;
  
  const user = await getUser(userId);
  await cache.set(`user:${userId}`, user, 3600); // 1 小时
  return user;
};
并非所有字段都可以更新。处理错误：
try {
  await updateUser(userId, updates);
} catch (error) {
  if (error.code === 'USER.0006') {
    // 字段不可更新
    console.log('无法更新此字段');
  }
}

​
下一步

创建账户

为用户添加银行账户和钱包

开始交易

开始处理 ramp 交易