apideck-connector-coverage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apideck Connector Coverage Skill

Overview

概述

Not all Apideck connectors support all operations. Before building an integration, always check connector coverage to avoid runtime errors. The Connector API provides real-time metadata about which operations each connector supports.

并非所有Apideck连接器都支持全部操作。在构建集成之前，请务必检查连接器覆盖范围，以避免运行时错误。Connector API提供每个连接器支持哪些操作的实时元数据。

IMPORTANT RULES

重要规则

ALWAYS check connector coverage before recommending an integration approach. Never assume a connector supports an operation.
If an operation is not supported, suggest alternatives: a different connector, pass-through to the raw API, or a workaround using supported operations.
USE the Connector API to verify coverage programmatically. Do not rely on hardcoded lists.
When a user reports a
```
501 Not Implemented
```
or
```
UnsupportedOperationError
```
, check coverage first.

始终在推荐集成方案前检查连接器覆盖范围。绝不要假设连接器支持某一操作。
如果某操作不被支持，建议替代方案：使用其他连接器、通过代理调用原始API，或使用支持的操作实现变通方案。
使用Connector API以编程方式验证覆盖范围。不要依赖硬编码列表。
当用户报告
```
501 Not Implemented
```
或
```
UnsupportedOperationError
```
错误时，首先检查覆盖范围。

Checking Coverage

检查覆盖范围

Using the SDK (TypeScript)

使用SDK（TypeScript）

typescript

import { Apideck } from "@apideck/unify";

const apideck = new Apideck({
  apiKey: process.env["APIDECK_API_KEY"] ?? "",
  appId: "your-app-id",
  consumerId: "your-consumer-id",
});

// List all connectors for an API
const { data } = await apideck.connector.connectorResources.get({
  id: "crm",
  resourceId: "contacts",
});
// Returns coverage per connector: which operations are supported

// Get specific connector details
const { data: connector } = await apideck.connector.connectors.get({
  id: "salesforce",
});
// Returns: name, status, auth_type, supported_resources, supported_events

typescript

import { Apideck } from "@apideck/unify";

const apideck = new Apideck({
  apiKey: process.env["APIDECK_API_KEY"] ?? "",
  appId: "your-app-id",
  consumerId: "your-consumer-id",
});

// 列出某API的所有连接器
const { data } = await apideck.connector.connectorResources.get({
  id: "crm",
  resourceId: "contacts",
});
// 返回每个连接器的覆盖情况：支持哪些操作

// 获取特定连接器详情
const { data: connector } = await apideck.connector.connectors.get({
  id: "salesforce",
});
// 返回：名称、状态、认证类型、支持的资源、支持的事件

Using the REST API

使用REST API

bash

undefined

bash

undefined

List connectors for a unified API

列出统一API的连接器

curl 'https://unify.apideck.com/connector/connectors?filter[unified_api]=crm'
-H 'Authorization: Bearer {API_KEY}'
-H 'x-apideck-app-id: {APP_ID}'

Get connector details including supported resources

获取包含支持资源的连接器详情

curl 'https://unify.apideck.com/connector/connectors/salesforce'
-H 'Authorization: Bearer {API_KEY}'
-H 'x-apideck-app-id: {APP_ID}'

Get API resource coverage (which connectors support what)

获取API资源覆盖情况（哪些连接器支持哪些操作）

curl 'https://unify.apideck.com/connector/apis/crm/resources/contacts'
-H 'Authorization: Bearer {API_KEY}'
-H 'x-apideck-app-id: {APP_ID}'

undefined

curl 'https://unify.apideck.com/connector/apis/crm/resources/contacts'
-H 'Authorization: Bearer {API_KEY}'
-H 'x-apideck-app-id: {APP_ID}'

undefined

Using the Vault API

使用Vault API

Check which connections a consumer has and their state:

typescript

const { data } = await apideck.vault.connections.list({
  api: "crm",
});

for (const conn of data) {
  console.log(`${conn.serviceId}: ${conn.state} (enabled: ${conn.enabled})`);
  // state: available | callable | added | authorized | invalid
}

检查消费者拥有的连接及其状态：

typescript

const { data } = await apideck.vault.connections.list({
  api: "crm",
});

for (const conn of data) {
  console.log(`${conn.serviceId}: ${conn.state} (enabled: ${conn.enabled})`);
  // 状态：available | callable | added | authorized | invalid
}

Coverage States

覆盖状态

Each operation on a connector has a coverage status:

Status	Meaning
`supported`	Fully implemented and tested
`beta`	Implemented but may have edge cases
`not_supported`	Not available for this connector

连接器的每个操作都有对应的覆盖状态：

状态	含义
`supported`	完全实现并经过测试
`beta`	已实现但可能存在边缘情况
`not_supported`	该连接器不支持此操作

Common Coverage Patterns

常见覆盖模式

Accounting API

会计API

Operation	QuickBooks	Xero	NetSuite	Sage Intacct	FreshBooks
Invoices CRUD	Full	Full	Full	Full	Full
Bills CRUD	Full	Full	Full	Full	Partial
Payments	Full	Full	Full	Full	Full
Journal Entries	Full	Full	Full	Full	Limited
Balance Sheet	Full	Full	Full	Full	No
Tax Rates (read)	Full	Full	Full	Full	Full

操作	QuickBooks	Xero	NetSuite	Sage Intacct	FreshBooks
发票CRUD	完整支持	完整支持	完整支持	完整支持	完整支持
账单CRUD	完整支持	完整支持	完整支持	完整支持	部分支持
支付	完整支持	完整支持	完整支持	完整支持	完整支持
日记账分录	完整支持	完整支持	完整支持	完整支持	有限支持
资产负债表	完整支持	完整支持	完整支持	完整支持	不支持
税率（读取）	完整支持	完整支持	完整支持	完整支持	完整支持

CRM API

Operation	Salesforce	HubSpot	Pipedrive	Zoho CRM	Close
Contacts CRUD	Full	Full	Full	Full	Full
Companies CRUD	Full	Full	Full	Full	Full
Leads CRUD	Full	Full	Full	Full	Full
Opportunities	Full	Full	Full	Full	Full
Activities	Full	Full	Full	Full	Partial
Pipelines (read)	Full	Full	Full	Full	Full

操作	Salesforce	HubSpot	Pipedrive	Zoho CRM	Close
联系人CRUD	完整支持	完整支持	完整支持	完整支持	完整支持
公司CRUD	完整支持	完整支持	完整支持	完整支持	完整支持
线索CRUD	完整支持	完整支持	完整支持	完整支持	完整支持
商机	完整支持	完整支持	完整支持	完整支持	完整支持
活动	完整支持	完整支持	完整支持	完整支持	部分支持
销售管道（读取）	完整支持	完整支持	完整支持	完整支持	完整支持

HRIS API

Operation	BambooHR	Workday	Personio	Gusto	Rippling
Employees CRUD	Full	Full	Full	Full	Full
Departments	Full	Full	Full	Full	Full
Payrolls (read)	Full	Partial	Partial	Full	Full
Time-Off	Full	Full	Full	Full	Full

These tables are approximate. Always verify with the Connector API for real-time accuracy.

操作	BambooHR	Workday	Personio	Gusto	Rippling
员工CRUD	完整支持	完整支持	完整支持	完整支持	完整支持
部门	完整支持	完整支持	完整支持	完整支持	完整支持
薪资（读取）	完整支持	部分支持	部分支持	完整支持	完整支持
休假管理	完整支持	完整支持	完整支持	完整支持	完整支持

这些表格仅为近似值。请始终通过Connector API验证实时准确数据。

Handling Unsupported Operations

处理不支持的操作

When an operation isn't supported for a connector:

当连接器不支持某操作时：

1. Use Pass-Through (Proxy API)

1. 使用直通模式（Proxy API）

Make direct calls to the downstream API through Apideck's proxy:

typescript

// Direct pass-through to the downstream API
const response = await fetch("https://unify.apideck.com/proxy", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "x-apideck-app-id": appId,
    "x-apideck-consumer-id": consumerId,
    "x-apideck-service-id": "salesforce",
    "x-apideck-downstream-url": "https://api.salesforce.com/services/data/v59.0/sobjects/CustomObject__c",
    "x-apideck-downstream-method": "GET",
    "Content-Type": "application/json",
  },
});

通过Apideck的代理直接调用下游API：

typescript

// 直接直通到下游API
const response = await fetch("https://unify.apideck.com/proxy", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "x-apideck-app-id": appId,
    "x-apideck-consumer-id": consumerId,
    "x-apideck-service-id": "salesforce",
    "x-apideck-downstream-url": "https://api.salesforce.com/services/data/v59.0/sobjects/CustomObject__c",
    "x-apideck-downstream-method": "GET",
    "Content-Type": "application/json",
  },
});

2. Check for Alternative Resources

2. 检查替代资源

Some connectors map the same data to different unified resources. For example, a "deal" in Pipedrive maps to "opportunities" in the unified CRM API.

部分连接器会将相同数据映射到不同的统一资源。例如，Pipedrive中的"deal"会映射到统一CRM API中的"opportunities"。

3. Suggest a Different Connector

3. 建议使用其他连接器

If the user's chosen connector doesn't support an operation, suggest alternatives that do. Use the Connector API to find connectors that support the specific operation.

如果用户选择的连接器不支持某操作，建议使用支持该操作的替代连接器。使用Connector API查找支持特定操作的连接器。

4. Feature Request

4. 功能请求

If a critical operation is missing, users can request it at https://github.com/apideck-libraries or through the Apideck dashboard.

如果缺少关键操作，用户可在https://github.com/apideck-libraries或通过Apideck仪表板提交请求。

Connector Authentication Types

连接器认证类型

Auth Type	Description	Connectors
`oauth2`	OAuth 2.0 flow (managed by Vault)	Most cloud SaaS (Salesforce, HubSpot, QuickBooks Online, etc.)
`apiKey`	API key authentication	Some self-hosted or simpler services
`basic`	Username/password	Legacy systems, on-premise
`custom`	Connector-specific auth	Varies

Vault handles all OAuth flows. Users authorize via the Vault modal — you never need to implement OAuth yourself.

认证类型	描述	连接器示例
`oauth2`	OAuth 2.0流程（由Vault管理）	大多数云SaaS（Salesforce、HubSpot、QuickBooks Online等）
`apiKey`	API密钥认证	部分自托管或简单服务
`basic`	用户名/密码认证	遗留系统、本地部署系统
`custom`	连接器专属认证	因连接器而异

Vault处理所有OAuth流程。用户通过Vault弹窗完成授权——您无需自行实现OAuth。

Debugging Coverage Issues

调试覆盖问题

When an API call fails:

Check the error type —
```
UnsupportedOperationError
```
or
```
501
```
means the operation isn't implemented
Verify connection state — Use
```
vault.connections.list()
```
to check the connection is
```
authorized
```
Check connector coverage — Use the Connector API to verify the operation is supported
Check field support — Some connectors support an operation but not all fields. Missing fields return
```
null
```
Use raw mode — Add
```
raw=true
```
to see the downstream response for debugging

当API调用失败时：

检查错误类型 —
```
UnsupportedOperationError
```
或
```
501
```
表示操作未实现
验证连接状态 — 使用
```
vault.connections.list()
```
检查连接是否处于
```
authorized
```
状态
检查连接器覆盖范围 — 使用Connector API验证操作是否被支持
检查字段支持 — 部分连接器支持操作但不支持所有字段。缺失字段会返回
```
null
```
使用原始模式 — 添加
```
raw=true
```
参数查看下游响应以进行调试