Cloud Jasmin DesenvolvimentoConceitos
DesenvolvimentoConceitos
Conceitos
Voltar | Lista de artigos

Características dos recursos da Web API

Última alteração a 26/08/2022

Os recursos da Web API correspondem às entidades geridas pelo sistema, os clientes, os fornecedores, encomendas, faturas, etc. Estas entidades têm um conjunto de características transversais que implementam comportamentos uniformes. Essas características e comportamentos têm influência na forma como os recursos são tratados na Web API.

De seguida descrevem-se as características principais das entidades.

Identificação

Nome do recurso

Os recursos são identificados pelo seu nome em inglês, sempre no plural. Eis alguns exemplos:

  • Tipos de encomenda: OrderTypes
  • Encomendas de venda: Orders
  • Faturas: Invoices
  • Clientes: CustomerParties

Identificador único

Todas as entidades do sistema têm um identificador único que é gerado automaticamente pelo sistema. Trata-se de um GUID (global unique identifier).

Todas as entidades têm, portanto, um atributo com o nome “id” que corresponde a este identificador único.

Eis um exemplo (atributo “id”):

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

É este identificador que deve ser utilizado nos endpoints que suportam a seleção do registo pelo seu id. Como no exemplo seguinte:

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

Chaves

Chave natural da entidade

A chave natural corresponde a identificador único da entidade, tipicamente uma string, sendo que, em alguns casos, essa chave pode ser composta por vários atributos, que é reconhecida e definida pelo utilizador. É essa chave que o utilizador introduz (ou é gerada automaticamente) na própria aplicação.

Na prática trata-se de uma forma de obter um registo sem ter que conhecer o identificador interno.

Normalmente, o nome do atributo que corresponde à chave natural com o sufixo “Key” no nome da própria entidade. Exemplos: CustomerKey, SupplierKey, CompanyKey.

Veja-se a chave natural no exemplo anterior (atributo “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"
}

Note-se que, no caso da entidade Order Types, a chave natural é composta pela chave da empresa (Company) e pelo valor do atributo TypeKey.

A chave natural pode ser utilizada nos endpoints que suportam seleção do registo pela chave.

O exemplo seguinte ilustra a seleção pela chave no caso de uma entidade com uma chave simples:

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

Quando a chave é composta por um ou mais atributos, os seus valores devem ser colocados no pedido separados por /, como no seguinte exemplo:

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

Chaves estrangeiras

Uma chave estrangeira define uma relação entre duas entidades.

Por exemplo, uma fatura pertence a um cliente, o que significa que a entidade Invoices tem uma chave estrangeira para a entidade CustomerParties.

As chaves estrangeiras no Jasmin são definidas pela inclusão do identificador único da entidade referenciada (CustomerParties) no registo da entidade que tem a referência (Invoices).

Em termos de recursos da Web API podemos ver isso no exemplo seguinte (atributo “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",
    (…)
}

É comum que os recursos da “entidade origem” incluam ainda uma série de atributos da “entidade referenciada” como a sua chave natural (“buyerCustomerParty”), a sua descrição (“buyerCustomerPartyName”). Estes atributos adicionais permitem, por exemplo, apresentar esses dados comuns ao utilizador sem ser necessário fazer uma consulta adicional à Web API.

Descrições

Praticamente todas as entidades do sistema incluem um atributo que descreve cada registo. Por exemplo, um cliente tem um código (a chave natural) e um nome (a descrição).

O nome do atributo pode ter várias formas, sendo que as mais comuns são as seguintes:

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

Atributos Auditing

Todas as entidades incluem sempre os seguintes atributos para auditing:

  • CreatedBy: identifica o utilizador que criou o registo.
  • CreatedOn: indica a data em que o registo foi criado.
  • ModifiedBy: identifica o utilizador que efetuou a última alteração.
  • ModifiedOn: indica a data em que o registo foi modificado pela última vez.

Estes atributos não podem ser manipulados pelo utilizador e, por isso, também não podem ser modificados pela Web API. São apenas de consulta.

Adicionar aos favoritos ou partilhar este artigo
Esta página foi útil?
Obrigado pelo seu voto.

login para deixar a sua opinião.

Obrigado pelo seu feedback. Iremos analisá-lo para continuarmos a melhorar!
Artigos Relacionados
Quais são os endpoints da Web API? Características da Web API Primavera Formato dos pedidos e respostas Mensagens de erro Entidades base e extensões