@ deliverart/ sdk- js- company (英语)
交付艺术JavaScript SDK公司管理套件.
安装
npm install @deliverart/sdk-js-company @deliverart/sdk-js-core
# or
pnpm add @deliverart/sdk-js-company @deliverart/sdk-js-core
# or
yarn add @deliverart/sdk-js-company @deliverart/sdk-js-core
导出类型
模型
企业
interface Company {
id: string
businessName: string
vat: string
taxCode: string | null
operationalAddress: Address
createdAt: string
updatedAt: string
}
基本公司信息.
属性 :
id: string- 独特的公司识别标志businessName: string- 公司商业名称(需要)vat: string- 增值税编号(所需)taxCode: string | null- 税法(可选)operationalAddress: Address- 业务地址(所需)createdAt: string- 创建时间戳(ISO 8601)updatedAt: string- 最后更新时间戳(ISO 8601)
公司详情
interface CompanyDetails extends Company {
billingAddress: Address
billingData: BillingData
adminBy: string
}
提供公司信息及账单细节.
其它属性 :
billingAddress: Address- 账单地址(所需)billingData: BillingData- 账单信息(需要)adminBy: string- 管理该公司的IRI用户(需要)
公司查询
interface CompaniesQueryParams {
businessName?: string
vat?: string
taxCode?: string
'billingAddress.city'?: string
'billingAddress.postalCode'?: string
'operationalAddress.city'?: string
'operationalAddress.postalCode'?: string
'order[businessName]'?: 'asc' | 'desc'
'order[createdAt]'?: 'asc' | 'desc'
'order[updatedAt]'?: 'asc' | 'desc'
page?: number
}
过滤和排序公司的查询参数.
过滤参数 :
businessName?: string- 按业务名称过滤(部分匹配)vat?: string- 按增值税号码过滤(精确匹配)taxCode?: string- 通过税法过滤(精确匹配)billingAddress.city?: string- 通过收费城市过滤billingAddress.postalCode?: string- 通过计费邮政编码过滤operationalAddress.city?: string- 按运营城市过滤operationalAddress.postalCode?: string- 按业务邮政编码过滤
排序参数 :
order[businessName]?: 'asc' | 'desc'- 按商业名称排序order[createdAt]?: 'asc' | 'desc'- 按创建日期排序order[updatedAt]?: 'asc' | 'desc'- 按更新日期排序
铺设 :
page?: number- 页数( 默认:1)
IRI 类型
艾丽公司
type CompanyIri = string
公司IRI类型(格式 : /companies/:id(中文(简体) )
NullableIri公司
type CompanyNullableIri = string | null
无效公司 IRI 类型
可用请求
创建公司
创建新公司.
类 : CreateCompany
输入外观 :
{
businessName: string // Required, min 1 char
vat: string // Required
taxCode?: string | null // Optional
billingAddress: { // Required
street: string
city: string
postalCode: string
country: string
state?: string
province?: string
}
operationalAddress: { // Required
street: string
city: string
postalCode: string
country: string
state?: string
province?: string
}
billingData: { // Required
email: string
pec?: string
sdi?: string
}
adminBy: string // Required, User IRI (e.g., '/users/123')
}
回应: CompanyDetails
示例
import { CreateCompany } from '@deliverart/sdk-js-company';
const company = await sdk.call(new CreateCompany({
businessName: 'Acme Corporation',
vat: 'IT12345678901',
taxCode: 'ACME1234567890',
billingAddress: {
street: 'Via Roma 1',
city: 'Milano',
postalCode: '20100',
country: 'IT'
},
operationalAddress: {
street: 'Via Roma 1',
city: 'Milano',
postalCode: '20100',
country: 'IT'
},
billingData: {
email: '[email protected]',
pec: '[email protected]'
},
adminBy: '/users/123'
}));
验证 :
businessName: 必需, 最小 1 个字符vat所需时间billingAddress: 需要, 所有地址字段已验证operationalAddress: 需要, 所有地址字段已验证billingData: 需要,电子邮件必须有效adminBy: 必需, 必须是一个有效的用户 IRI
获取公司
获得带有可选过滤器的标定公司名单.
类 : GetCompanies
构造器 :
new GetCompanies(options?: { query?: CompaniesQueryParams })
查询参数: 见 CompaniesQueryParams 上文
回应: Paginated<Company>
示例
import { GetCompanies } from '@deliverart/sdk-js-company';
// Get all companies
const companies = await sdk.call(new GetCompanies());
// Get companies with filters
const filtered = await sdk.call(new GetCompanies({
query: {
businessName: 'Acme',
'operationalAddress.city': 'Milano',
'order[createdAt]': 'desc',
page: 1
}
}));
// Access pagination info
console.log(filtered.pagination.totalItems);
console.log(filtered.pagination.currentPage);
console.log(filtered.pagination.itemsPerPage);
// Access data
filtered.data.forEach(company => {
console.log(company.businessName);
});
验证 :
page: 可选,必须是正数- 所有过滤器值都是可选的
获取公司详情
获取具体公司的详细信息.
类 : GetCompanyDetails
构造器 :
new GetCompanyDetails(companyId: string)
参数:
companyId: string- 公司身份证(需要)
回应: CompanyDetails
示例
import { GetCompanyDetails } from '@deliverart/sdk-js-company';
const company = await sdk.call(new GetCompanyDetails('company-123'));
console.log(company.businessName);
console.log(company.billingAddress);
console.log(company.billingData);
验证 :
companyId: 需要, 必须是非空字符串
获取用户连线
获取由特定用户管理的公司.
类 : GetUserCompanies
构造器 :
new GetUserCompanies(userId: string)
参数:
userId: string- 用户标识(需要)
回应: Company[]
示例
import { GetUserCompanies } from '@deliverart/sdk-js-company';
const companies = await sdk.call(new GetUserCompanies('user-123'));
companies.forEach(company => {
console.log(company.businessName);
});
验证 :
userId: 需要, 必须是非空字符串
更新公司
更新现有公司(部分更新).
类 : UpdateCompany
构造器 :
new UpdateCompany(companyId: string, input: Partial<CompanyInput>)
参数:
companyId: string- 公司身份证(需要)input: Partial<CompanyInput>- 要更新的字段( 所有选项)
输入外观 :
{
businessName?: string
vat?: string
taxCode?: string | null
billingAddress?: {
street: string
city: string
postalCode: string
country: string
state?: string
province?: string
}
operationalAddress?: {
street: string
city: string
postalCode: string
country: string
state?: string
province?: string
}
billingData?: {
email: string
pec?: string
sdi?: string
}
adminBy?: string // User IRI
}
回应: CompanyDetails
示例
import { UpdateCompany } from '@deliverart/sdk-js-company';
// Update single field
const updated = await sdk.call(new UpdateCompany('company-123', {
businessName: 'Acme Corp Updated'
}));
// Update multiple fields
const updated = await sdk.call(new UpdateCompany('company-123', {
businessName: 'New Name',
billingAddress: {
street: 'Via Nuova 10',
city: 'Roma',
postalCode: '00100',
country: 'IT'
}
}));
验证 :
companyId: 需要, 必须是非空字符串- 所有输入字段均为可选但提供时已验证
- 用途
application/merge-patch+json部分更新的内容类型
删除公司
删除公司.
类 : DeleteCompany
构造器 :
new DeleteCompany(companyId: string)
参数:
companyId: string- 公司身份证(需要)
回应: void
示例
import { DeleteCompany } from '@deliverart/sdk-js-company';
await sdk.call(new DeleteCompany('company-123'));
验证 :
companyId: 需要, 必须是非空字符串
完成使用示例
import { sdk } from './lib/sdk';
import {
CreateCompany,
GetCompanies,
GetCompanyDetails,
GetUserCompanies,
UpdateCompany,
DeleteCompany
} from '@deliverart/sdk-js-company';
async function companyManagement() {
// Create a company
const newCompany = await sdk.call(new CreateCompany({
businessName: 'Tech Startup SRL',
vat: 'IT98765432109',
taxCode: null,
billingAddress: {
street: 'Via Innovation 42',
city: 'Milano',
postalCode: '20100',
country: 'IT'
},
operationalAddress: {
street: 'Via Innovation 42',
city: 'Milano',
postalCode: '20100',
country: 'IT'
},
billingData: {
email: '[email protected]',
pec: '[email protected]'
},
adminBy: '/users/456'
}));
console.log('Created company:', newCompany.id);
// Get all companies
const allCompanies = await sdk.call(new GetCompanies());
console.log(`Total companies: ${allCompanies.pagination.totalItems}`);
// Search companies
const milanCompanies = await sdk.call(new GetCompanies({
query: {
'operationalAddress.city': 'Milano',
'order[businessName]': 'asc'
}
}));
// Get company details
const details = await sdk.call(new GetCompanyDetails(newCompany.id));
console.log('Billing email:', details.billingData.email);
// Get user's companies
const userCompanies = await sdk.call(new GetUserCompanies('user-456'));
console.log(`User has ${userCompanies.length} companies`);
// Update company
const updated = await sdk.call(new UpdateCompany(newCompany.id, {
businessName: 'Tech Startup Updated SRL',
billingData: {
email: '[email protected]',
pec: '[email protected]',
sdi: 'ABC1234'
}
}));
// Delete company
await sdk.call(new DeleteCompany(newCompany.id));
console.log('Company deleted');
}
处理错误
import { ApiError } from '@deliverart/sdk-js-error-handler';
import { CreateCompany } from '@deliverart/sdk-js-company';
try {
await sdk.call(new CreateCompany({
businessName: '', // Invalid: too short
vat: 'INVALID',
// ... other fields
}));
} catch (error) {
if (error instanceof ApiError && error.data?.type === 'VALIDATION_ERROR') {
error.data.value.violations.forEach(violation => {
console.error(`${violation.propertyPath}: ${violation.message}`);
});
}
}
类型脚本
所有类型都完全使用 TypeScript 键入. 直接导入 :
import type {
Company,
CompanyDetails,
CompaniesQueryParams,
CompanyIri,
CompanyNullableIri
} from '@deliverart/sdk-js-company';
许可证
麻省理工学院
行政设置
CreateCompany 链接当前引用的用户 adminBy;它不创建账户,发送邀请,或赠款管理者角色. 管理员界面应当选择现有的活动管理器. 铅初始化是一个单独的API工作流程,可以创建一个管理器.
增值税号码,从 IT,提供 billingData 两者 sdi 财务报告和审定财务报表 pec 键和至少一个非空值。 其他国家可以使用 { sdi: null, pec: null }. 公司反应验证不对外国公司实施意大利发票规则。 PATCH将有条件的增值税要求推迟到API,后者可以验证完整的恒定公司.