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

Question

(注意：下面提到的 documentation 在提交时是错误的。看起来它是从模板复制的，没有更改。我已经提交了对 Microsoft GitHub 的评论页。）

有没有人使用 Business Central v2 API 成功创建了联系人？我正在按照文档 here 进行操作，但没有取得任何成功。更新效果很好，但我根本无法创建请求。

文档说我应该可以 post 联系联系人 end-point，

POST businesscentralPrefix/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" : "ah@contoso.com",
    "website" : "",
    "searchName" : "",
    "privacyBlocked" : true,
    "lastInteractionDate" : "2021-06-01",
    "lastModifiedDateTime" : "2021-06-01"
}

该示例在有效负载中有一个 id 属性，这似乎不是我应该创建的东西。考虑到 URL.

中重复的 {id} 占位符，这里的 id 再次令人困惑

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

If-Match Required. When this request header is included and the eTag provided does not match the current tag on the contact, the contact will not be updated.

如果我正在创建联系人，我不会有 etag，因此 header 似乎不适用于创建请求。如果是这种情况，那么可能不能太依赖文档。如果是的话，那我不禁想知道create end-point是不是不应该：

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

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

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

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

这是文档所暗示的，但考虑到您通过公司 ID 有效过滤联系人 table，它没有任何意义。我只是为了它而试了一下

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"
    }
}

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."
    }
}

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."
    }
}

有没有人使用 Business Central v2 API 成功创建了联系人？如果是这样，你是怎么做到的，我做错了什么？此外，我正在使用的系统是从本地 NAV 实例升级而来的，fwiw。

Answer 1

当 number 和 type 都包含在负载中时，似乎会发生错误。

解决方案是在没有 number 或 type 的情况下创建联系人，然后使用补丁请求更新您遗漏的值。

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

How to create a contact using Business Central API 2.0?

odata

dynamics-business-central