跳转到主要内容

​
概览

在用户执行 ramp 交易之前，必须在 KillB 中注册并提供适当的 KYC 信息。本指南涵盖创建个人（PERSON）和企业（COMPANY）用户。
所有用户从 KYC 级别 L0 或 L1 开始，可以通过提交额外文档进行升级。

​
先决条件

  • 来自 /api/v2/auth/login 的有效访问令牌
  • 要提交的用户信息
  • 政府身份证详情

​
创建个人用户

​
基本示例

POST /api/v2/users

{
  "type": "PERSON",
  "externalId": "user-12345",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "[email protected]",
    "phone": "+573001234567",
    "dateOfBirth": "1990-05-15",
    "address": {
      "street1": "Calle 123 #45-67",
      "city": "Bogotá",
      "state": "Cundinamarca",
      "zipCode": "110111",
      "countryCode": "CO"
    },
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}

​
必需字段

字段类型描述示例
firstNamestring名字”Juan”
lastNamestring姓氏”García”
emailstring电子邮件地址”[email protected]”
phonestring带国家代码的电话”+573001234567”
dateOfBirthstringYYYY-MM-DD 格式的日期”1990-05-15”
addressobject物理地址见下文
documentobject政府身份证见下文

​
地址对象

{
  "street1": "Calle 123 #45-67",
  "street2": "Apt 301",
  "city": "Bogotá",
  "state": "Cundinamarca",
  "zipCode": "110111",
  "countryCode": "CO"
}
street2 是可选的。用于公寓号码、建筑物名称等。

​
文档对象

为用户所在国家选择适当的文档类型： 
{
  "type": "NUIP",
  "number": "1234567890",
  "issuedCountryCode": "CO"
}
支持的类型：
  • NUIP - Número Único de Identificación Personal
  • PASSPORT - 护照
  • DRIVER_LICENSE - 驾照

​
创建企业用户

对于商业实体： 
{
  "type": "COMPANY",
  "externalId": "company-456",
  "data": {
    "companyName": "Acme Technologies SAS",
    "tradeName": "Acme Tech",
    "registeredNumber": "900123456",
    "legalStructure": "LLC",
    "establishedOn": "2015-03-20",
    "phone": "+573001234567",
    "email": "[email protected]",
    "address": {
      "street1": "Carrera 7 #123-45",
      "city": "Bogotá",
      "state": "Cundinamarca",
      "zipCode": "110111",
      "countryCode": "CO"
    },
    "document": {
      "type": "NIT",
      "number": "900123456-1",
      "issuedCountryCode": "CO"
    },
    "mainOwnerUser": "owner-user-id",
    "ownerUsers": ["owner-1-id", "owner-2-id"]
  }
}

​
企业特定字段

字段必需描述
companyName✅法定注册名称
tradeName❌经营名称
registeredNumber❌商业注册号码
legalStructure❌LLC, C_CORP, S_CORP 等
establishedOn❌公司成立日期
mainOwnerUser❌主要所有者用户 ID
ownerUsers❌所有者用户 ID 数组
naics❌行业分类代码
公司所有者必须首先创建为 PERSON 用户，然后在公司资料中引用。

​
可选增强字段

​
投资资料

为更高的 KYC 级别提供： 
{
  "investmentProfile": {
    "primarySourceOfFunds": "EMPLOYMENT",
    "primarySourceOfFundsDescription": "软件工程薪资",
    "totalAssets": "TEN_TO_100K",
    "usdValueOfFiat": "TEN_TO_100K",
    "monthlyDeposits": "UPTO_5",
    "monthlyWithdrawals": "UPTO_5",
    "monthlyInvestmentDeposit": "ONE_TO_100K",
    "monthlyInvestmentWithdrawal": "UPTO_1K"
  }
}
资金来源选项：
  • EMPLOYMENT - 薪资/工资
  • SAVINGS - 个人储蓄
  • INVESTMENT - 投资回报
  • COMPANY - 商业收入
  • REAL_ESTATE - 房地产收入
  • OTHER - 其他来源

​
KYC 资料

反洗钱信息： 
{
  "kycProfile": {
    "fundsSendReceiveJurisdictions": ["CO", "US", "MX"],
    "engageInActivities": ["NONE"]
  }
}

​
完整代码示例

const createUser = async (userData) => {
  const response = await fetch('https://teste-94u93qnn.uc.gateway.dev/api/v2/users', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'PERSON',
      externalId: userData.id,
      data: {
        firstName: userData.firstName,
        lastName: userData.lastName,
        email: userData.email,
        phone: userData.phone,
        dateOfBirth: userData.dateOfBirth,
        address: {
          street1: userData.address.street,
          city: userData.address.city,
          state: userData.address.state,
          zipCode: userData.address.zipCode,
          countryCode: userData.address.country
        },
        document: {
          type: userData.document.type,
          number: userData.document.number,
          issuedCountryCode: userData.document.country
        }
      }
    })
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`用户创建失败: ${error.message}`);
  }
  
  const user = await response.json();
  
  // 在数据库中存储用户 ID
  await db.users.update(userData.id, {
    killbUserId: user.id,
    kycLevel: user.accessLevel,
    kycStatus: user.status
  });
  
  return user;
};

​
验证

提交前验证数据： 
const validateUserData = (data) => {
  const errors = [];
  
  // 电子邮件格式
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email)) {
    errors.push('电子邮件格式无效');
  }
  
  // 电话格式（E.164）
  if (!/^\+[1-9]\d{10,14}$/.test(data.phone)) {
    errors.push('电话必须采用格式: +[国家代码][号码]');
  }
  
  // 出生日期（18 岁以上）
  const dob = new Date(data.dateOfBirth);
  const age = (Date.now() - dob.getTime()) / (365.25 * 24 * 60 * 60 * 1000);
  if (age < 18) {
    errors.push('用户必须年满 18 岁');
  }
  
  // 文档号码格式
  if (data.document.type === 'NUIP' && !/^\d{10}$/.test(data.document.number)) {
    errors.push('NUIP 必须是 10 位数字');
  }
  
  return errors;
};

​
错误处理

常见的用户创建错误：
错误代码描述解决方案
USER.0001用户已存在使用现有用户 ID
USER.0002无效文档检查文档格式
USER.0003电子邮件已注册使用不同的电子邮件
USER.0004无效电话格式使用 E.164 格式（+57…）
USER.0005未成年用户用户必须年满 18 岁

​
创建后的下一步

1

存储用户 ID

在数据库中保存返回的 id，映射到您的 externalId
2

检查 KYC 状态

监控 status 和 accessLevel 字段
3

上传文档

对于 L2+，上传身份证图像和其他文档
4

创建账户

为此用户添加银行账户或钱包

KYC 级别

了解 KYC 验证级别

上传文档

提交身份证图像和证明文档

管理用户

查询、更新和删除用户

API 参考

完整的用户 API 文档