apideck-dotnet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apideck .NET SDK Skill

Apideck .NET SDK 技能文档

Overview

概述

The Apideck Unified API provides a single integration layer to connect with 200+ third-party services across accounting, CRM, HRIS, file storage, ATS, e-commerce, and more. The official .NET SDK (

ApideckUnifySdk

) provides typed clients for all unified APIs.

Apideck Unified API 提供了一个统一的集成层，可连接会计、CRM、HRIS、文件存储、ATS、电商等领域的200+款第三方服务。官方.NET SDK（

ApideckUnifySdk

）为所有统一API提供了类型化客户端。

Installation

安装

dotnet add package ApideckUnifySdk

dotnet add package ApideckUnifySdk

IMPORTANT RULES

重要规则

ALWAYS use the
```
ApideckUnifySdk
```
NuGet package. DO NOT make raw
```
HttpClient
```
calls to the Apideck API.
ALWAYS pass
```
apiKey
```
,
```
appId
```
, and
```
consumerId
```
when initializing the client.
USE
```
ServiceId
```
to specify which downstream connector to use (e.g.,
```
"salesforce"
```
,
```
"quickbooks"
```
).
USE async/await for all API calls — all operations return
```
Task<T>
```
.
ALWAYS handle errors with try/catch using
```
BaseException
```
as the base class.
DO NOT store API keys in source code. Use environment variables or a secrets manager.

始终使用
```
ApideckUnifySdk
```
NuGet包。请勿直接使用
```
HttpClient
```
调用Apideck API。
初始化客户端时，必须传入
```
apiKey
```
、
```
appId
```
和
```
consumerId
```
。
使用
```
ServiceId
```
指定要连接的下游连接器（例如：
```
"salesforce"
```
、
```
"quickbooks"
```
）。
所有API调用均使用async/await —— 所有操作都返回
```
Task<T>
```
。
始终使用
```
BaseException
```
作为基类，通过try/catch处理错误。
请勿在源代码中存储API密钥。请使用环境变量或密钥管理器。

Quick Start

快速开始

csharp

using ApideckUnifySdk;
using ApideckUnifySdk.Models.Requests;

var sdk = new Apideck(
    consumerId: "your-consumer-id",
    appId: "your-app-id",
    apiKey: Environment.GetEnvironmentVariable("APIDECK_API_KEY") ?? ""
);

var res = await sdk.Crm.Contacts.ListAsync(new CrmContactsAllRequest {
    ServiceId = "salesforce",
    Limit = 20,
});

while (res != null)
{
    foreach (var contact in res.GetContactsResponse?.Data ?? [])
    {
        Console.WriteLine($"{contact.Name} - {contact.Emails?.FirstOrDefault()?.Email}");
    }
    res = await res.Next!();
}

csharp

using ApideckUnifySdk;
using ApideckUnifySdk.Models.Requests;

var sdk = new Apideck(
    consumerId: "your-consumer-id",
    appId: "your-app-id",
    apiKey: Environment.GetEnvironmentVariable("APIDECK_API_KEY") ?? ""
);

var res = await sdk.Crm.Contacts.ListAsync(new CrmContactsAllRequest {
    ServiceId = "salesforce",
    Limit = 20,
});

while (res != null)
{
    foreach (var contact in res.GetContactsResponse?.Data ?? [])
    {
        Console.WriteLine($"{contact.Name} - {contact.Emails?.FirstOrDefault()?.Email}");
    }
    res = await res.Next!();
}

SDK Patterns

SDK 使用模式

Client Setup

客户端设置

csharp

using ApideckUnifySdk;

var sdk = new Apideck(
    consumerId: "your-consumer-id",
    appId: "your-app-id",
    apiKey: Environment.GetEnvironmentVariable("APIDECK_API_KEY") ?? ""
);

csharp

using ApideckUnifySdk;

var sdk = new Apideck(
    consumerId: "your-consumer-id",
    appId: "your-app-id",
    apiKey: Environment.GetEnvironmentVariable("APIDECK_API_KEY") ?? ""
);

CRUD Operations

CRUD 操作

All resources follow the pattern:

sdk.{Api}.{Resource}.{Operation}Async(request)

csharp

using ApideckUnifySdk;
using ApideckUnifySdk.Models.Requests;
using ApideckUnifySdk.Models.Components;

// LIST
var listRes = await sdk.Crm.Contacts.ListAsync(new CrmContactsAllRequest {
    ServiceId = "salesforce",
    Limit = 20,
    Filter = new ContactsFilter { Email = "john@example.com" },
    Sort = new ContactsSort {
        By = ContactsSortBy.UpdatedAt,
        Direction = SortDirection.Desc,
    },
});

// CREATE
var createRes = await sdk.Crm.Contacts.CreateAsync(new CrmContactsAddRequest {
    ServiceId = "salesforce",
    Contact = new ContactInput {
        FirstName = "John",
        LastName = "Doe",
        Emails = new List<Email> {
            new Email { EmailAddress = "john@example.com", Type = EmailType.Primary },
        },
        PhoneNumbers = new List<PhoneNumber> {
            new PhoneNumber { Number = "+1234567890", Type = PhoneNumberType.Mobile },
        },
    },
});
Console.WriteLine(createRes.CreateContactResponse?.Data?.Id);

// GET
var getRes = await sdk.Crm.Contacts.GetAsync(new CrmContactsOneRequest {
    Id = "contact_123",
    ServiceId = "salesforce",
});

// UPDATE
var updateRes = await sdk.Crm.Contacts.UpdateAsync(new CrmContactsUpdateRequest {
    Id = "contact_123",
    ServiceId = "salesforce",
    Contact = new ContactInput { FirstName = "Jane" },
});

// DELETE
await sdk.Crm.Contacts.DeleteAsync(new CrmContactsDeleteRequest {
    Id = "contact_123",
    ServiceId = "salesforce",
});

所有资源均遵循以下模式：

sdk.{Api}.{Resource}.{Operation}Async(request)

。

csharp

using ApideckUnifySdk;
using ApideckUnifySdk.Models.Requests;
using ApideckUnifySdk.Models.Components;

// 列表查询
var listRes = await sdk.Crm.Contacts.ListAsync(new CrmContactsAllRequest {
    ServiceId = "salesforce",
    Limit = 20,
    Filter = new ContactsFilter { Email = "john@example.com" },
    Sort = new ContactsSort {
        By = ContactsSortBy.UpdatedAt,
        Direction = SortDirection.Desc,
    },
});

// 创建
var createRes = await sdk.Crm.Contacts.CreateAsync(new CrmContactsAddRequest {
    ServiceId = "salesforce",
    Contact = new ContactInput {
        FirstName = "John",
        LastName = "Doe",
        Emails = new List<Email> {
            new Email { EmailAddress = "john@example.com", Type = EmailType.Primary },
        },
        PhoneNumbers = new List<PhoneNumber> {
            new PhoneNumber { Number = "+1234567890", Type = PhoneNumberType.Mobile },
        },
    },
});
Console.WriteLine(createRes.CreateContactResponse?.Data?.Id);

// 查询详情
var getRes = await sdk.Crm.Contacts.GetAsync(new CrmContactsOneRequest {
    Id = "contact_123",
    ServiceId = "salesforce",
});

// 更新
var updateRes = await sdk.Crm.Contacts.UpdateAsync(new CrmContactsUpdateRequest {
    Id = "contact_123",
    ServiceId = "salesforce",
    Contact = new ContactInput { FirstName = "Jane" },
});

// 删除
await sdk.Crm.Contacts.DeleteAsync(new CrmContactsDeleteRequest {
    Id = "contact_123",
    ServiceId = "salesforce",
});

Pagination

分页处理

Use the

Next

method on the response. Returns

null

when no more pages:

csharp

var res = await sdk.Accounting.Invoices.ListAsync(new AccountingInvoicesAllRequest {
    ServiceId = "quickbooks",
    Limit = 50,
});

while (res != null)
{
    foreach (var invoice in res.GetInvoicesResponse?.Data ?? [])
    {
        Console.WriteLine($"{invoice.Number}: {invoice.Total}");
    }
    res = await res.Next!();
}

使用响应对象的

Next

方法。当没有更多页面时返回

null

：

csharp

var res = await sdk.Accounting.Invoices.ListAsync(new AccountingInvoicesAllRequest {
    ServiceId = "quickbooks",
    Limit = 50,
});

while (res != null)
{
    foreach (var invoice in res.GetInvoicesResponse?.Data ?? [])
    {
        Console.WriteLine($"{invoice.Number}: {invoice.Total}");
    }
    res = await res.Next!();
}

Error Handling

错误处理

csharp

using ApideckUnifySdk.Models.Errors;

try
{
    var res = await sdk.Crm.Contacts.GetAsync(new CrmContactsOneRequest { Id = "invalid" });
}
catch (BadRequestResponse e)
{
    Console.Error.WriteLine($"Bad request: {e.Message}");
}
catch (UnauthorizedResponse e)
{
    Console.Error.WriteLine("Invalid API key or missing credentials");
}
catch (NotFoundResponse e)
{
    Console.Error.WriteLine("Record not found");
}
catch (PaymentRequiredResponse e)
{
    Console.Error.WriteLine("API limit reached");
}
catch (UnprocessableResponse e)
{
    Console.Error.WriteLine($"Validation error: {e.Message}");
}
catch (BaseException e)
{
    Console.Error.WriteLine($"API error: {e.Message}");
    Console.Error.WriteLine($"Status: {e.Response.StatusCode}");
}

csharp

using ApideckUnifySdk.Models.Errors;

try
{
    var res = await sdk.Crm.Contacts.GetAsync(new CrmContactsOneRequest { Id = "invalid" });
}
catch (BadRequestResponse e)
{
    Console.Error.WriteLine($"请求错误: {e.Message}");
}
catch (UnauthorizedResponse e)
{
    Console.Error.WriteLine("API密钥无效或凭据缺失");
}
catch (NotFoundResponse e)
{
    Console.Error.WriteLine("记录未找到");
}
catch (PaymentRequiredResponse e)
{
    Console.Error.WriteLine("API调用额度已耗尽");
}
catch (UnprocessableResponse e)
{
    Console.Error.WriteLine($"验证错误: {e.Message}");
}
catch (BaseException e)
{
    Console.Error.WriteLine($"API错误: {e.Message}");
    Console.Error.WriteLine($"状态码: {e.Response.StatusCode}");
}

Retry Configuration

重试配置

csharp

var sdk = new Apideck(
    retryConfig: new RetryConfig(
        strategy: RetryConfig.RetryStrategy.BACKOFF,
        backoff: new BackoffStrategy(
            initialIntervalMs: 1L,
            maxIntervalMs: 50L,
            maxElapsedTimeMs: 100L,
            exponent: 1.1
        ),
        retryConnectionErrors: false
    ),
    consumerId: "your-consumer-id",
    appId: "your-app-id",
    apiKey: Environment.GetEnvironmentVariable("APIDECK_API_KEY") ?? ""
);

csharp

var sdk = new Apideck(
    retryConfig: new RetryConfig(
        strategy: RetryConfig.RetryStrategy.BACKOFF,
        backoff: new BackoffStrategy(
            initialIntervalMs: 1L,
            maxIntervalMs: 50L,
            maxElapsedTimeMs: 100L,
            exponent: 1.1
        ),
        retryConnectionErrors: false
    ),
    consumerId: "your-consumer-id",
    appId: "your-app-id",
    apiKey: Environment.GetEnvironmentVariable("APIDECK_API_KEY") ?? ""
);

API Namespaces

API 命名空间

Namespace	Resources
`sdk.Accounting.*`	Invoices, Bills, Payments, Customers, Suppliers, LedgerAccounts, JournalEntries, TaxRates, CreditNotes, PurchaseOrders, BalanceSheet, ProfitAndLoss, and more
`sdk.Crm.*`	Contacts, Companies, Leads, Opportunities, Activities, Notes, Pipelines, Users
`sdk.Hris.*`	Employees, Companies, Departments, Payrolls, TimeOffRequests
`sdk.FileStorage.*`	Files, Folders, Drives, DriveGroups, SharedLinks, UploadSessions
`sdk.Ats.*`	Applicants, Applications, Jobs
`sdk.Vault.*`	Connections, Consumers, Sessions, CustomMappings, Logs
`sdk.Webhook.*`	Webhooks, EventLogs

命名空间	资源
`sdk.Accounting.*`	发票、账单、付款、客户、供应商、分类账账户、日记账分录、税率、贷项通知单、采购订单、资产负债表、损益表等
`sdk.Crm.*`	联系人、公司、销售线索、销售机会、活动、备注、销售漏斗、用户
`sdk.Hris.*`	员工、公司、部门、工资单、休假申请
`sdk.FileStorage.*`	文件、文件夹、驱动器、驱动器组、共享链接、上传会话
`sdk.Ats.*`	申请人、申请记录、职位
`sdk.Vault.*`	连接、消费者、会话、自定义映射、日志
`sdk.Webhook.*`	Webhook、事件日志