Alterações na Web API do Cegid Jasmin

A Cegid irá disponibilizar brevemente uma nova versão do Cegid Jasmin. Esta nova versão tem como objetivo melhorar funcionalmente o produto, mas também o seu nível de desempenho, segurança e confiabilidade.

A nova versão introduzirá alterações significativas na Web API. Estas alterações poderão impactar com as atuais integrações com o Cegid Jasmin e poderá ser necessário adaptá-las para garantir o seu correto funcionamento.

Atualizações

Alterações

1. Métodos GET

Os métodos GET {module}/{resource}, que retornam a lista de todos os registos da coleção, serão descontinuados. Passarão a retornar 405 – Method Not Allowed.

Estes métodos deverão ser substituídos pelos equivalentes que fazem uso de OData. Assim, o método substituto será em tudo idêntico, mas com uma terminação diferente: GET {module}/{resource}/odata.

Exemplo:

• Obter lista de empresas
  • Atual versão: GET /corepatterns/companies
  • Nova versão: GET /corepatterns/companies/odata

O recurso a estes métodos permite tirar partido das potencialidades do OData, possibilitando otimizar o pedido efetuado (p.e. com filtros) e o resultado obtido (p.e. selecionado as propriedades pretendidas).

Nos métodos OData o resultado obtido também é diferente.

Exemplo:

• Obter lista de empresas (Resultado)
  • GET /corepatterns/companies

    [
        {
            "companyKey": "EMPRESA1",
            "name": "Empresa 1",
            "companyTaxID": "123456789",
            (...) 
        },
        {
            "companyKey": "EMPRESA2",
            "name": "Empresa 2",
            "companyTaxID": "999999990",
            (...)
        }
    ]

    O resultado é uma coleção (array) com todos os objetos correspondentes ao resultado.

  • GET /corepatterns/companies/odata

    {
        "items": [
            {
                "companyKey": "EMPRESA1",
                "name": "Empresa 1",
                "companyTaxID": "123456789",
                (...)
        	},
            {
                "companyKey": "EMPRESA2",
                "name": "Empresa 2",
                "companyTaxID": "999999990",
                (...)
            }        
        ],
        "nextPageLink": null,
        "count": null
    }

    O resultado é um objeto com três propriedades. A propriedade items contém uma coleção (array) com os vários objetos correspondentes ao resultado. Nesta coleção existe paginação e, por omissão, são devolvidos apenas os primeiros 100 resultados. A propriedadee nextPageLink contém o endpoint para solicitar a página seguinte de resultados. Se não existir mais nenhuma página, a propriedade fica com o valor null. A propriedade count, caso seja solicitado explícitamente no pedido (através de parâmetro), contém o número total de resultados. Mas por questões de desempenho, por omissão, tem o valor null.
    

Assim, as integrações que façam uso dos métodos GET {module}/{resource} devem ser adaptadas, não só ao nível da nomenclatura do próprio método mas também ao nível do resultado obtido.

Esta adaptação para os métodos OData pode ser efetuada a qualquer momento, uma vez que estes já se encontram disponíveis na versão atual (ter em conta o ponto 4 desta secção).

2. Entidades com relação para empresa

Na atual versão, quando se cria - através de métodos POST - uma entidade com relação para a empresa (p.e. documentos ou tipos de documentos), e caso apenas exista uma empresa no sistema, não é necessário indicá-la explícitamente.

Na nova versão, passa a ser obrigatório indicar a empresa em qualquer situação.

Existem duas formas distintas de num POST de criação de uma entidade indicar a empresa:

1. Sob a forma de valor de uma propriedade com o nome company, no objeto passado no body do pedido.
2. Sob a forma de valor de um header do pedido com o nome X-Company.

A adaptação com recurso à forma de propriedade pode ser efetuada a qualquer momento, sendo compatível com a atual versão e com a nova versão.

3. Criação de entidade já existente

Na atual versão, quando se tenta criar uma entidade com a mesma chave de uma já existente no sistema é devolvido um 400 - Bad Request.

Na nova versão, a mesma situação passará a devolver um 409 - Conflict.

4. Versão OData

A atual versão utiliza a versão OData v2.0.

A nova versão passará a utilizar uma versão superior de OData - v4.0. Esta versão possui diversas alterações na forma como os comandos devem ser utilizados e, por isso, recomendamos a consulta da documentação.

Sintetizámos algumas das principais alterações:

• Comando $expand - inversão da lógica de escrita
  • v2.0: $expand={Detail}&$select={MasterProperty1}, {Detail/Property1}, {Detail/Property2}, {Detail/Property3}
  • v4.0: $select={MasterProperty1}$expand={Detail}($select {Property1}, {Property2}, {Property3})
• Comando $inlinecount=allpages substituído por $count=true
• Comando $filter sobre atributos do tipo datetimeoffset
  • v2.0: $filter={Property} ge datetimeoff’2024-01-01T09:00:00’
  • v4.0: $filter={Property} ge 2024-01-01T09:00:00Z

Por questões de desempenho, recomendamos que sempre que possível seja explicitamente indicada a lista de propriedades pretendidas utilizando o comando $select. Desta forma, serão retornadas apenas as propriedades necessárias e será evitado todo o overload de percorrer todas as relações para retornar todas as propriedades existentes.

Retrocompatibilidade

O processo de migração das subscrições da atual versão para a nova será feito de forma gradual. Tal significa que, durante o processo, coexistirão subscrições na atual versão e na nova versão.

Desta forma, recomendamos fortemente a implementação de retrocompatibilidade nas integrações. Só dessa forma é possível assegurar que a integração continuará a funcionar tanto na versão atual como na nova versão.

Para permitir retrocompatibilidade, está disponível na Web API um método que permite identificar a versão do produto em que uma subscrição se encontra:

GET api/{account}/{subscription}/businessCore/productInfos/getVersions

Este método retorna um objeto contendo as versões em que a subscrição se encontra:

Exemplo de resultado

{
    "product": "2.22",
    "elevationFW": "12.5",
    "elevationSDK": "12.5"
}

A propriedade que interessa verificar é a propriedade product, mais concretamente o algarismo à esquerda do ponto, correspondente à major version.

A versão atual do produto tem product = 2.xx. A nova versão do produto terá product = 3.xx.

Desta forma, é possível identificar a versão do produto em que uma determinada subscrição se encontra e, a partir daí, implementar retrocompatibilidade na integração, para funcionar corretamente em qualquer uma das versões.

Ambiente de testes

Brevemente, irá estar disponível um ambiente de testes onde poderá ter acesso a uma subscrição na nova versão do produto e, desta forma, adaptar e testar as integrações.