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.

5. Obtenção de imagens

Na atual versão, os métodos que permitem obter as imagens (p.e. imagem de cliente ou artigo) devolvem diretamente o conteúdo da imagem.

Na nova versão, estes métodos passam a devolver um objeto com diversas informações da imagem além do seu conteúdo em Base64.

Exemplo:

• Obter imagem de cliente: GET /businesscore/parties/{guid}/picture?fileName=image.png
  • Resultado atual versão

    ?PNG  IHDR???b?A?PLTE???26;u??.03y??]o? &,??? '???^iy(-3-16???[^aPV^bmmpr%*0 '$*???GJN???PSW????????????uwz$???`cf>BG???8`??w??>zAWZ?:c???g ^????%Z??Dey????I?E?BW?j_??MU??%????3????h?E8l$?}X?YC2?G?|4@7??R??F????B_&???4?j??????'7?C ?v?#???aHO$V???k??<6??X????9&??n'?p*??2,???/cF?>p_j??9?.0?@??ziu??|?[=?::?"??V?hP??????s&?ER????Z?-"?e`|k??m??lU??P'???????jr?Q?O^??7?Z????+Zn????? ,C|v?h??u??W?R?\A?6c!?w??8M:??L??n? ??xb?)?*?????E+?????Fz?????*?Ù`U??I?B--??*Kcb.???L?7????ng<1m??z1'~?UZE????"?$??p?|?q&X?????}-?w????'???^?G?;2??? 6U\????8*[/?> &T;F9?}W??%???L??}sy?+Iv?&X_?????]{'c?f?????-?@$=??3?
    (...)

    O resultado é o conteúdo direto da imagem.

  • Resultado nova versão

    {
        "fileContents": "iVBORw0KGgoAAAANSUhEUgAAAOUAAADcCAYAAACPvGZzAAAAAXNSR0IArs4c6(...)",
        "contentType": "image/.png",
        "fileDownloadName": "",
        "lastModified": null,
        "entityTag": null,
        "enableRangeProcessing": false
    }

    O resultado é um objeto com diversas informações da imagem, nomeadamente o seu conteúdo em Base64 e o seu formato.

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

Está disponível um ambiente de testes com a nova versão do produto, onde poderá testar e validar a sua integração.

Para ter acesso a este ambiente necessita de obter uma nova subscrição DEMO, recorrendo à APP Store do Cegid Jasmin.
Para criar uma subscrição DEMO, deve autenticar-se e navegar para o menu Developer (menu no topo da página), onde terá a seguinte opção:

As subscrições DEMO, por omissão, possuem alguns dados exemplo - empresa, artigos, clientes, documentos, etc - e são válidas por 30 dias. Após esse período, a subscrição expirará e, caso pretenda continuar a utilizar, deverá criar uma nova.

Para a sua integração ter acesso à subscrição DEMO que acabou de criar, deverá dar-lhe permissões seguindo os passos descritos aqui. Caso não o faça, a integração não terá acesso à subscrição e todos os pedidos efetuados receberão 403 - Forbidden como resposta.

Nota: este ambiente tem como objetivo validar e testar as integrações, não sendo o ambiente final. Como tal, pode ter alguma instabilidade e/ou anomalias. Caso detete alguma anomalia, recomendamos a criação de uma pergunta no fórum com a tag Jasmin, explicando o cenário da forma mais detalhada possível.