Recursos
Recursos
Recursos
Recursos
Nesta área encontra informações sobre a tecnologia de integração Jasmin, bem como guias de ajuda com exemplos simples e práticos sobre como iniciar o desenvolvimento de uma solução. Também encontra informações sobre todos os aspetos da Web API necessários ao desenvolvimento de aplicações, desde tópicos de referência até funcionalidades mais avançadas.
API
API
API
API
A API é a forma como aplicações terceiras podem aceder ao Jasmin e pode ser usada para uma variedade de operações, como por exemplo a criação de transações como faturas ou notas de crédito, até a exploração de informação através de listagem de dados.
Postman
Postman
Postman
Postman
Postman
Postman
POSTMAN

COMPRAS E VENDAS

Nesta coleção vais encontrar exemplos de utilização da WebAPI para as áreas de compras e vendas.

EXPEDIÇÃO E INVENTÁRIO

Nesta coleção vais encontrar exemplos de utilização da WebAPI para as áreas de inventário e expedição de mercadoria.

IMPOSTOS E FINANÇAS

Nesta coleção vais encontrar exemplos de utilização da WebAPI para as áreas de pagamentos, recebimentos e impostos.

PLATAFORMA E ENTIDADES BASE

Nesta coleção vais encontrar exemplos de utilização da WebAPI para a área de plataforma.

Adicionar aos favoritos ou partilhar este artigo
Artigos Relacionados
POSTMAN
RecursosReferências
RecursosReferências
Referências
Voltar | Lista de artigos
Quais são os endpoints da Web API?

A Web API Jasmin 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://my.jasminsoftware.com/api/{account}/{subscription}/salesCore/customerParties

O resultado é devolvido no corpo da mensagem em JSON:

[
{
    "version": [
        0,
        0,
        0,
        0,
        0,
        1,
        184,
        56
    ],
    "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": "andre.silva@primaverabss.com",
    "createdOn": "2017-05-18T09:29:53.1202287",
    "modifiedBy": "sergio.sereno@primaverabss.com",
    "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://my.jasminsoftware.com/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://my.jasminsoftware.com/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://my.jasminsoftware.com/api/{account}/{subscription}/financialCore/paymentTerms/{id}
https://my.jasminsoftware.com/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": "hugo.ribeiro@primaverabss.com",
    "createdOn": "2017-09-12T14:57:05.5452566",
    "modifiedBy": "hugo.ribeiro@primaverabss.com",
    "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://my.jasminsoftware.com/api/{account}/{subscription}/financialCore/paymentTerms/{id}
https://my.jasminsoftware.com/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
Artigos Relacionados
Boas práticas de integração Como executar queries OData sobre os dados? Como funciona a autorização OAuth 2.0? Características dos recursos da Web API Códigos de estado das respostas