Web API resources characteristics

The Web API resources match the entities managed by the system, clients, suppliers, orders, invoices, etc. These entities have a set of common characteristics that implement a uniform behavior. These characteristics and behaviors have an influence on the way resources are handled in the Web API.

The main characteristics of the entities are described below.

Identification

Resource name

Resources are identified by their english name, always in plural. Here are some examples:

• Order types: OrderTypes
• Sales orders: Orders
• Invoices: Invoices
• Customers: CustomerParties

Unique identifier

All entities in the system have a unique identifier that is automatically generated by the system. It is a GUID (global unique identifier).

Therefore, all entities have an attribute called "id" which matches this unique identifier.

Here is an example ("id" attribute):

{
    "typeKey": "ECL2",
    "description": "Encomenda",
    "deliveryOnInvoice": false,
    "isInternal": false,
    "company": "PRI",
    "companyId": "b74e4e50-0c84-45b0-b20a-836cc45b2409",
    "companyDescription": "PRIMAVERA BSS",
    "documentTypeSeries": [
    (...)
    ],
    "fiscalDocumentType": "NE",
    "fiscalDocumentTypeId": "b5eaa842-24e8-442a-b423-62eb43669fce",
    "fiscalDocumentTypeDescription": "Nota de encomenda",
    "defaultInvoiceType": "FA",
    "defaultInvoiceTypeId": "86285923-ef02-4e6f-bc34-972578ae8ae3",
    "defaultInvoiceTypeDescription": "Fatura",
    "orderNature": 1,
    "defaultMemoType": null,
    "defaultMemoTypeId": null,
    "defaultMemoTypeDescription": null,
    "defaultDeliveryType": "GR",
    "defaultDeliveryTypeId": "e76764aa-d606-4e4e-a7d8-7525dd36c5ae",
    "defaultDeliveryTypeDescription": "Guia de Remessa",
    "defaultGoodsReceiptNoteType": null,
    "defaultGoodsReceiptNoteTypeId": null,
    "defaultGoodsReceiptNoteTypeDescription": null,
    "contactType": "01",
    "contactTypeId": "ffff2a64-152b-4908-9c2c-82d461f176c2",
    "contactTypeDescription": "Principal",
    "notification": "DEFAULT",
    "notificationId": "353df62d-c525-4b69-ad85-4de6c202c9d8",
    "notificationDescription": "Notificação Jasmin",
    "naturalKey": "ECL2",
    "isDraft": false,
    "id": "6b2d37d9-4d92-e711-9401-0003ff41c4eb",
    "isActive": true,
    "isDeleted": false,
    "isSystem": false,
    "createdBy": "[email protected]",
    "createdOn": "2017-09-05T15:21:42.939088",
    "modifiedBy": "[email protected]",
    "modifiedOn": "2017-09-05T15:21:42.939088",
    "subscriptionId": null,
    "draftId": "00000000-0000-0000-0000-000000000000"
}

This identifier should be used on endpoints that support record selection by its id. As per the following example:

https://baseurl/api/{Account}/{Subscription}/salesCore/orderTypes/6b2d37d9-4d92-e711-9401-0003ff41c4eb

Keys

Natural entity key

The natural key matches the entity's unique identifier, generally a string, and in some cases, this key may be composed of several attributes, which is recognized and defined by the user. The user introduces this key (or it is automatically generated) in the app.

In practice, this is a way to obtain a record without having to know the internal identifier.

Usually, the name of the attribute that matches the natural key with the suffix "Key" in the entity name. Examples: CustomerKey, SupplierKey, CompanyKey.

See the natural key in the previous example (attribute "typeKey"):

{
    "typeKey": "ECL2",
    "description": "Encomenda",
    "deliveryOnInvoice": false,
    "isInternal": false,
    "company": "PRI",
    "companyId": "b74e4e50-0c84-45b0-b20a-836cc45b2409",
    "companyDescription": "PRIMAVERA BSS",
    "documentTypeSeries": [
    (...)
    ],
    "fiscalDocumentType": "NE",
    "fiscalDocumentTypeId": "b5eaa842-24e8-442a-b423-62eb43669fce",
    "fiscalDocumentTypeDescription": "Nota de encomenda",
    "defaultInvoiceType": "FA",
    "defaultInvoiceTypeId": "86285923-ef02-4e6f-bc34-972578ae8ae3",
    "defaultInvoiceTypeDescription": "Fatura",
    "orderNature": 1,
    "defaultMemoType": null,
    "defaultMemoTypeId": null,
    "defaultMemoTypeDescription": null,
    "defaultDeliveryType": "GR",
    "defaultDeliveryTypeId": "e76764aa-d606-4e4e-a7d8-7525dd36c5ae",
    "defaultDeliveryTypeDescription": "Guia de Remessa",
    "defaultGoodsReceiptNoteType": null,
    "defaultGoodsReceiptNoteTypeId": null,
    "defaultGoodsReceiptNoteTypeDescription": null,
    "contactType": "01",
    "contactTypeId": "ffff2a64-152b-4908-9c2c-82d461f176c2",
    "contactTypeDescription": "Principal",
    "notification": "DEFAULT",
    "notificationId": "353df62d-c525-4b69-ad85-4de6c202c9d8",
    "notificationDescription": "Notificação Jasmin",
    "naturalKey": "ECL2",
    "isDraft": false,
    "id": "6b2d37d9-4d92-e711-9401-0003ff41c4eb",
    "isActive": true,
    "isDeleted": false,
    "isSystem": false,
    "createdBy": "[email protected]",
    "createdOn": "2017-09-05T15:21:42.939088",
    "modifiedBy": "[email protected]",
    "modifiedOn": "2017-09-05T15:21:42.939088",
    "subscriptionId": null,
    "draftId": "00000000-0000-0000-0000-000000000000"
}

Please note that, in the case of the Order Types entity, the natural key is composed by the company key (Company) and by the value of the TypeKey attribute.

The natural key can be used in the endpoints, which support the record's selection by key.

The following example illustrates the selection by the key in the case of an entity with a simple key:

https://baseurl/api/{Account}/{Subscription}/corePatterns/companies/company

When the key is composed of one or more attributes, their values must be placed in the request separated by /, as in the following example:

https://baseurlapi/{Account}/{Subscription}/salesCore/orderTypes/COMPANY/EI

Foreign keys

A foreign key defines a relationship between two entities.

For example, an invoice belongs to a customer, which means that the Invoices entity has a foreign key to the CustomerParties entity.

Foreign keys in Jasmin are defined by including the unique identifier of the referenced entity (CustomerParties) in the record of the entity that has the reference (Invoices).

In terms of Web API resources we can see this in the following example (attribute "buyerCustomerPartyId"):

{
    "version": [
        (…)
    ],
    (…)
    "buyerCustomerPartyName": "SOFRIO",
    "buyerCustomerPartyTaxId": "123456789",
    "buyerCustomerPartyAddress": "SOFRIOrnAvenida do Gelo 11rn4719-006 Braga",
    "buyerCustomerParty": "0019",
    "buyerCustomerPartyId": "2dd17e54-0369-4264-8c43-dcdda7507f9d",
    "buyerCustomerPartyBaseEntityId": "c805b2c2-8f7c-47ca-931e-5fae28b7aa35",
    "buyerCustomerPartyDescription": "SOFRIO",
    (…)
    "id": "682df3eb-fc6d-e711-9401-0003ff41c6db",
    (…)
}

That the "source entity" resources also include a number of attributes of the "referenced entity", such as its natural key ("buyerCustomerParty"), its description ("buyerCustomerPartyName"). These additional attributes allow, for example, to present such common data to the user without the need to make an additional query to the Web API.

Descriptions

Virtually every entity in the system includes an attribute that describes each record. For example, a customer has a code (the natural key) and a name (the description).

The attribute name can take several forms, the most common of which are as follows:

• Description
• Name
• EntityDescription (example: DeliveryTermDescription)
• EntityName (example: BuyerCustomerName)

Auditing Attributes

All entities always include the following attributes for auditing:

• CreatedBy: identifies the user who created the record;
• CreatedOn: indicates the date in which the record was created;
• ModifiedBy: identifies the user who made the last change;
• ModifiedOn: indicates the date when the record was last modified.

These attributes cannot be manipulated by the user and therefore cannot be modified by the Web API. They are only for consultation.