Entidades base e extensões

O conceito de entidade e entidade extensão (extensões) permite que determinada entidade de negócio – uma empresa que tem uma relação comercial ou de outro tipo com a empresa - assuma vários “papéis” no sistema e seja sempre gerida com uma única identidade.

Um exemplo deste conceito são as empresas que podem ser em simultâneo clientes e fornecedores.

Os dados comuns da empresa são mantidos na entidade base e os dados particulares de cada um desses papéis são mantidos nas respetivas extensões. É possivél inclusivamente que se adicione uma nova extensão, entre as disponíveis, a determinada entidade em qualquer momento.

Os dois exemplos mais importantes são as entidades Parceiro (Partner) e o Item.

No primeiro caso a entidade base é a Party, que incluirá os dados comuns da empresa, como o seu nome, morada, contactos, etc. As extensão são CustomerParty (cliente), SupplierParty (fornecedor), FinancialInstitution (instituição financeira) e SalesPerson (vendedor).

No caso do artigo, a entidade base (Item) contém os dados comuns (descrição, unidades, etc.) e as extensões correspondem aos dados necessários para gerir esse artigo nas outras áreas da aplicação: Sales (vendas), Purchases (compras) e  Materials (inventário).

API

A Web API disponibiliza os endpoints necessários para gerir estes dois tipos de entidades. É possível:

• Criar uma nova entidade base.
• Criar uma nova entidade base e uma extensão.
• Adicionar uma extensão a uma entidade existente.
• Remover uma extensão de uma entidade existente.

Criar entidades base

Este caso é semelhante à criação de um registo em qualquer tipo de entidade. Utiliza-se o endpoint da entidade base (Item no exemplo) como outro qualquer (POST):

https://baseurl/api/{Account}/{Subscription}/businessCore/items

Criar entidades base e de extensão

Ao criar um registo na extensão estaremos na realidade a criar dois registos, um na entidade base e outro na extensão. Por isso utiliza-se o endpoint da extensão (POST):

https://baseurl/api/{Account}/{Subscription}/salesCore/salesItems

A resource usada neste endpoint é na realidade uma conjugação das entidades Item e SalesItem.

Adicionar extensão a entidades existentes

Pode adicionar-se uma extensão a uma entidade base desde que essa extensão não exista já.

Para tal, é necessário passar no body do pedido, o atributo "baseEntityKey" que corresponde à chave natural do registo.

O endpoint será semelhante ao seguinte (POST):

https://baseurl/api/{Account}/{Subscription}/salescore/salesitems/extension