Cloud Jasmin DesenvolvimentoConceitos
DesenvolvimentoConceitos
Conceitos
Voltar | Lista de artigos

Quais são os endpoints da Web API?

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

A Web API disponibiliza endpoints para aceder a todas as entidades do sistema e para realizar as seguintes operações:

OperaçãoVerbExemplo
Obter uma lista de todos os registosGETGET /sales/orders
Obter uma página da lista de todos os registosGETGET /sales/orders?page={page}&pageSize={size}
Obter um registo a partir do seu idGETGET /sales/orders/{id}
Obter um registo a partir da sua chaveGETGET /sales/orders/{key}
Criação de um novo registoPOSTPOST /sales/orders
Atualizar o valor de um atributo do registoPUTPUT /sales/orders/{key}/{field}
Anular um registo a partir do seu idDELETEDELETE /sales/orders/{id}
Anular um registo a partir da sua chaveDELETEDELETE /sales/orders/{key}

Nota: Não existem endpoints para atualizar um registo numa única operação.

Estas são as operações standard disponíveis para todas as entidades. Podem estar disponíveis outras operações para entidades particulares, de acordo com a respetiva lógica de negócio. A lista exaustiva de todos os endpoints, operações e parâmetros de entrada está disponível na documentação de referência.

Organização dos endpoints

Por questões de organização, as entidades e os endpoints estão agrupados em módulos. Um módulo define uma categoria de entidades que estão logicamente relacionadas porque fazem parte da mesma área funcional do produto. O identificador do módulo é utilizado no URL do endpoint antes do identificador da entidade (sales nos exemplos anteriores).

Seguem alguns exemplos dos módulos existentes e respetivas entidades:

MóduloDescriçãoEntidades
FinancialsTratamento financeiro das transaçõesfinancialInstitutions, paymentMethods, pettyCashes
LogisticsTratamento logístico das transaçõesdeliveryTerms, deliveryTypes, shippingMethods
PurchasesTransações de compras a fornecedoresinvoice, orders, supplierParties
SalesTransações de vendas a clientesinvoices, orders, customerParties

Entidades (Resources)

As entidades são identificadas por um nome que normalmente corresponde ao seu nome em Inglês, em camel case.

Por exemplo, a encomenda de compra e a encomenda de venda são ambas identificadas pelo termo order mas não existe conflito porque estão em módulos diferentes (purchases e sales).

Outros exemplos de nomes de entidades podem ser a condição de entrega (deliveryTerm), caixa (pettyCash) ou instituição financeira (financialInstitution).

A forma mais fácil de determinar o nome exato de cada entidade na Web API é consultar a documentação de referência da API.

Listagem de uma entidade

É possível obter a lista de todos os registos de uma entidade, como por exemplo, todos os clientes existentes, através do endpoint principal com o verb GET.

https://baseurl/api/{account}/{subscription}/salesCore/customerParties

O resultado é devolvido no corpo da mensagem em JSON:

[
{
    "settlementDiscountPercent": 10,
    "locked": false,
    "oneTimeCustomer": false,
    "endCustomer": true,
    "partyKey": "0001",
    "partyKeySegments": null,
    "partyKeySequenceId": null,
    "searchTerm": null,
    "name": "Fornecedor",
    "companyTaxID": "123456789",
    "electronicMail": null,
    "telephone": null,
    "mobile": null,
    "websiteUrl": null,
    "notes": null,
    "picture": null,
    "pictureThumbnail": null,
    "streetName": "Rua",
    "buildingNumber": "100",
    "postalZone": "4700-100",
    "cityName": "Braga",
    "contactName": "Fornecedor",
    "contactTitle": null,
    "username": null,
    "externalId": null,
    "externalVersion": null,
    "isExternallyManaged": false,
    "customerGroup": "01",
    "customerGroupId": "59548ad9-8647-400b-9a6d-4ad9042179d0",
    "customerGroupDescription": "Clientes Finais",
    "priceList": "PVP1",
    "priceListId": "d74c0465-edfb-4855-a988-5e8ee40e555f",
    "priceListDescription": "Preço de venda ao público 1",
    "paymentMethod": "NUM",
    "paymentMethodId": "6fcdea7e-274c-40bd-aeee-848d73ccd4d3",
    "paymentMethodDescription": "Numerário",
    "paymentTerm": "00",
    "paymentTermId": "34a8eeac-9dfe-4ada-b46d-8776566dc5f4",
    "paymentTermDescription": "Pronto Pagamento",
    "salesperson": null,
    "salespersonId": null,
    "salespersonBaseEntityId": null,
    "salespersonDescription": null,
    "partyTaxSchema": "IVA-RN-MN2",
    "partyTaxSchemaId": "7bdc2748-fa41-e711-9401-0003ff41e200",
    "partyTaxSchemaDescription": "IVA - Regime Normal - Mercado Nacional",
    "partyWithholdingTaxSchema": null,
    "partyWithholdingTaxSchemaId": null,
    "partyWithholdingTaxSchemaDescription": null,
    "deliveryTerm": "EM-MAO",
    "deliveryTermId": "d50e4e63-e95f-406a-91f6-b7a0c1b45674",
    "deliveryTermDescription": "Entregue em mão",
    "accountingSchema": 1,
    "accountingParty": null,
    "accountingPartyId": null,
    "accountingPartyDescription": null,
    "currency": "EUR",
    "currencyId": "b28426d4-f1c0-4210-baa3-a080cf06ff4f",
    "currencyDescription": "Euro",
    "country": "PT",
    "countryId": "02c605d0-24ca-11df-85ae-005056c00001",
    "countryDescription": "Portugal",
    "address": "3",
    "addressId": "85c719da-56b9-4004-88b2-9b47b4e376cf",
    "contact": "2",
    "contactId": "85c719da-56b9-4004-88b2-9b47b4e376cf",
    "culture": "PT-PT",
    "cultureId": "fcd41e40-248e-11df-9deb-005056c00001",
    "cultureDescription": "Portuguese-Portugal",
    "baseEntityId": "85c719da-56b9-4004-88b2-9b47b4e376cf",
    "isDraft": false,
    "id": "fb70fb36-2240-4e09-8b74-6cfc8ba771a7",
    "isActive": true,
    "isDeleted": false,
    "isSystem": false,
    "createdBy": "[email protected]",
    "createdOn": "2017-05-18T09:29:53.1202287",
    "modifiedBy": "[email protected]",
    "modifiedOn": "2017-07-19T16:27:45.2775966",
    "subscriptionId": null,
    "draftId": "00000000-0000-0000-0000-000000000000"
},
(…)
]

Este resultado é uma lista de resources CustomerPartyResource.

Criar registo

Quando se pretende criar uma nova entidade, como por exemplo, um método de pagamento, deve utilizar-se o endpoint principal da entidade e o verb POST.

https://baseurl/api/{account}/{subscription}/financialCore/paymentTerms

Os dados da entidade nova devem ser fornecidos no corpo da mensagem.

{
    "paymentTermKey": "PT001",
    "description": "My payment term 001",
    "useInAccountsReceivable": true,
    "useInAccountsPayable": true
}

Se o registo for devidamente criado, será devolvido o status code 201 (Created) e o identificador do novo registo será devolvido no corpo da mensagem.

Atualizar atributo do registo

Os registos existentes no sistema podem ser atualizados atributo a atributo, usando o endpoint respetivo.

Usando o exemplo anterior, podemos atualizar o atributo “useInAccountsPayable” da condição de pagamento usando o seguinte URL:

https://baseurl/api/{account}/{subscription}/financialCore/paymentTerms/{key}/useInAccountsPayable

Note-se que este URL inclui a chave do registo (PT001) antes da parte que define o atributo a atualizar.

O novo valor do atributo deve ser passado no corpo da mensagem em JSON.

Consultar registo

Pode obter-se um determinado registo de uma entidade de duas formas: usando o identificador único do registo (o resultado da operação de criação) ou a chave única do registo (um dos atributos do registo).

Os parâmetros dos endpoints serão diferentes, mas ambos usam o verb GET.

https://baseurl/api/{account}/{subscription}/financialCore/paymentTerms/{id}
https://baseurl/api/{account}/{subscription}/financialCore/paymentTerms/{key}
{
    "version": [
        0,
        0,
        0,
        0,
        0,
        2,
        89,
        31
    ],
    "paymentTermKey": "PT001",
    "description": "My payment term 001",
    "validFrom": "2017-01-01T00:00:00",
    "validTo": "2099-12-31T00:00:00",
    "useInAccountsReceivable": true,
    "useInAccountsPayable": false,
    "daysFromReferenceDate": 1,
    "naturalKey": "PT001",
    "isDraft": false,
    "id": "7b0595fd-bdd6-4f96-8f5c-0dd3ba6c685f",
    "isActive": true,
    "isDeleted": false,
    "isSystem": false,
    "createdBy": "[email protected]",
    "createdOn": "2017-09-12T14:57:05.5452566",
    "modifiedBy": "[email protected]",
    "modifiedOn": "2017-09-12T15:05:09.1178198",
    "subscriptionId": null,
    "draftId": "00000000-0000-0000-0000-000000000000"
}

Anular registo

Os registos podem ser eliminados (ou anulados, dependendo da entidade em causa) usando o verbo DELETE no endpoint principal. Neste caso, também se pode usar o identificador do registo ou a chave natural para identificar o registo a eliminar.

https://baseurl/api/{account}/{subscription}/financialCore/paymentTerms/{id}
https://baseurl/api/{account}/{subscription}/financialCore/paymentTerms/{key}

Se o registo for eliminado com sucesso o status code devolvido será o 204 (No Content).

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
Características da Web API Primavera Formato dos pedidos e respostas Mensagens de erro Entidades base e extensões Características dos recursos da Web API