如何使用 Business Central API 2.0 创建联系人？

Question

（注意：下面提到的文档在提交时是错误的。看起来它是从模板复制的并且没有更改。我已在 Microsoft 的 GitHub 页面上提交了评论。）

有没有人成功创建了使用 Business Central v2 API 进行联系？我正在遵循文档 这里并且没有任何成功。更新效果很好，但我根本无法让创建请求工作。

该文档说我应该能够像这样发布到联系人端点，

POSTbusinesscentralPrefix/companies({id})/contacts({id})

事实上 {id} 用作 companies 和 contacts URL 组件的占位符很奇怪，根本不是我所期望的。该页面上还给出了一个更完整的示例：

POST https://{businesscentralPrefix}/api/v2.0/companies({id})/contacts({id})
Content-type: application/json
{
    "id" : "5d115c9c-44e3-ea11-bb43-000d3a2feca1",
    "number" : "108001",
    "type" : "Company",
    "displayName": "CRONUS USA, Inc.",
    "companyNumber" : "17806",
    "companyName" : "CRONUS US",
    "businessRelation" : "Vendor",
    "addressLine1": "7122 South Ashford Street",
    "addressLine2": "Westminster",
    "city": "Atlanta",
    "state": "GA",
    "country": "US",
    "postalCode": "31772",
    "phoneNumber": "+1 425 555 0100",
    "mobilePhoneNumber" : "",
    "email" : "[email protected]",
    "website" : "",
    "searchName" : "",
    "privacyBlocked" : true,
    "lastInteractionDate" : "2021-06-01",
    "lastModifiedDateTime" : "2021-06-01"
}

该示例在有效负载中有一个 id 属性，这似乎不是我应该创建的东西。考虑到 URL 中存在重复的 {id} 占位符，这里的 id 再次令人困惑。

此外，还有一些标头要求对于创建请求没有意义：

If-Match 必需。当包含此请求标头并且提供的 eTag 与联系人上的当前标签不匹配时，将不会更新联系人。

如果我创建联系人，则不会有 etag，因此该标头似乎不适用于创建请求。如果是这样的话，那么可能就不能太依赖文档了。如果是这样的话，那么我不禁想知道创建端点是否不应该是：

POST https://{businesscentralPrefix}/api/v2.0/companies ({company-guid})/contacts

这似乎与我遇到的其他 REST API 更一致，但让我想知道是否需要为新联系人提供 id ？我的回答是“不”，但 Microsoft 的文档在示例之外并未提及这一点。

我更新现有联系人没有任何问题。我只剩下三个选项来创建一个：

1. POST https://{businesscentralPrefix}/api/v2.0/companies({company-guid})/contacts({company-guid})< /代码>

   这就是文档所暗示的内容，但考虑到您正在通过公司 ID 有效地过滤联系人表，它没有任何意义。我只是为了它而尝试

POST https://{businesscentralPrefix}/api/v2.0/companies({company-guid})/contacts({company-guid})
{
    "id":"8adc4ec5-8393-44ac-8860-fadd9e3603cb",
    "number": "TEST123",
    "displayName": "Another Test Contact",
    "type": "Person",
    ...
}
...
Response (with and without the contact guid in payload)
{
    "error": {
        "code": "BadRequest_MethodNotAllowed",
        "message": "'POST' requests for 'contacts' of EdmType 'Entity' are not allowed within Dynamics 365 Business Central OData web services.  CorrelationId:  XXX"
    }
}

2. POST https://{businesscentralPrefix}/api/v2.0/companies({company-guid})/contacts({contact-guid})< /代码>

   这看起来也很奇怪，因为我似乎不应该创建记录的 ID。也只是为了尝试一下：

POST https://api.businesscentral.dynamics.com/v2.0/{tenent-guid}/{environment}/api/v2.0/companies({company-guid})/contacts(8adc4ec5-8393-44ac-8860-fadd9e3603cb)
{
    "id":"8adc4ec5-8393-44ac-8860-fadd9e3603cb",
    "number": "TEST123",
    "displayName": "Another Test Contact",
    "type": "Person",
    ...
}
...
Response (with and without the contact id guid in payload)
{
    "error": {
        "code": "BadRequest_MethodNotAllowed",
        "message": "'POST' requests for 'contacts' of EdmType 'Entity' are not allowed within Dynamics 365 Business Central OData web services.  CorrelationId:  XXXX."
    }
}

3. POST https://{businesscentralPrefix}/api/v2.0/companies({company-guid})/contacts

   数字 3 在我看来是有道理的，但失败了

POST https://api.businesscentral.dynamics.com/v2.0/{tenent-guid}/{environment}/api/v2.0/companies({company-guid})/contacts(8adc4ec5-8393-44ac-8860-fadd9e3603cb)

{
    "id":"8adc4ec5-8393-44ac-8860-fadd9e3603cb",
    "number": "TEST123",
    "displayName": "Another Test Contact",
    "type": "Person",
    ...
}
...
Response (with and without the contact id guid in payload)
{
    "error": {
        "code": "Internal_RecordNotFound",
        "message": "The Contact does not exist. Identification fields and values: No.='TEST123'  CorrelationId:  XXX."
    }
}

有没有人成功创建联系人使用业务中心 v2 API？如果是这样，你是怎么做到的以及我做错了什么？另外，我正在使用的系统是从本地 NAV 实例 fwiw 升级的。

Answer 1

当有效负载中同时包含 number 和 type 时，似乎会发生该错误。

解决方案是创建不带 number 或 type 的联系人，然后通过补丁请求更新您遗漏的值。