Referência para a API REST de Classes

Serviços RESTful

Nesta seção serão esclarecidas os recursos e suas possíveis rotas.

Classe

Representa o recurso de manipulação de entidades de uma classe do sistema. As mesmas operações a serem realizadas pela manipulação deste recurso podem ser realizadas através do processo Bematech/Admin/Explorer.ip dentro do sistema ERP.

É importante ter em mente que todas as tabelas possuem o campo CLASSE ou iClass o que as torna entidades de uma classe do sistema, inclusive a tabela classe, ou seja, todas as classes são entidades de classe.

Importante: a API de Classes potencialmente pode manipular todos os dados das classes cadastrais do sistema, no entanto essa funcionalidade requer que as definições de classes seja revistas para utilizar o novo formato de definição de classes por meio dos arquivos x-model e x-view em vez dos arquivos x-class. Apesar de algumas classes de sistema terem sido revistas, a maior parte das classes relacionadas ao modelo de ERP encontram-se pendentes e serão revistas sobre demanda dos projetos de desenvolvimento. Lembramos que as APIs HTTP encontram-se em caráter experimental e devem ser utilizadas por orientação da Bematech. Caso deseje implementar algum processo de integração que requer acesso aos dados do sistema, entre em contato com a Bematech para avaliarmos as revisões das definições de classes necessárias para atender o objetivo da integração.

Consultas

Aqui serão exibidas todas as consultas disponíveis do recurso de classe.

Consulta o esquema das entidades de uma classe

Este ponto de acesso responde o esquema do banco dos registros de uma classe. Um esquema descreve os dados de acordo com a seção de Esquemas > Representação de consumo deste mesmo documento. * Parâmetros - Caminho do ponto de acesso: classKey - A chave da classe. - Querystring: Nenhum. - Corpo da requisição: Nenhum.

Ponto de acesso

GET /api/classes/v1/classes/<classKey>/schema

Exemplo de consumo

curl -X GET -i https://<your_domain>:<port>/api/classes/v1/classes/-1898187811/schema -u '<user>:<pass>'

Resultado

HTTP/1.1 200 OK Content-Type: application/schema+json { "title": "Esquema da classe de dados \/Dados\/Sistema\/Grupos, Papéis e Usuários (-1898187811)", "type": "object", "required": [ "iclass", "ifullname", "iname", "ikey" ], "properties": { "ishortcuts": { "items": { "type": "integer" }, "type": "array" }, "iversion": { "type": "integer" }, "iissuablelicenses": { "type": "string" }, "ikey": { "type": "integer" }, "ismtpusername": { "type": "string" }, "isecuritypolicy": { "type": "integer" }, "ismtppassword": { "type": "string" }, "igroups": { "items": { "type": "integer" }, "type": "array" }, "ifullname": { "type": "string" }, "iinformedfields": { "type": "string" }, "iallgroups": { "type": "string" }, "inavtreevisibilitymode": { "enum": [ 0, 1, 2 ] }, "igroupsinherited": { "type": "string" }, "estabeleci": { "items": { "type": "integer" }, "type": "array" }, "ccustres": { "items": { "type": "integer"}, "type": "array" }, "iclass": { "type": "integer" }, "iemailaddress": { "type": "string" }, "ismtpserver": { "type": "integer" }, "iproduct": { "type": "string" }, "ihomeprocess": { "type": "integer" }, "ilanguage": { "type": "integer" }, "iname": { "type": "string" }, "ipassword": { "type": "string" }, "themes": { "type": "integer" }, "ichangeablelicenses": { "type": "string" }, "environments": { "type": "integer" } }}

Consulta de entidades a partir de uma classe

Este ponto de acesso responde todos os registros a partir de uma classe. Ele é equivalente a colocar uma classe no campo de filtragem do processo localizado em Bematech/Admin/Explorer.ip do ERP. * Parâmetros: - Caminho do ponto de acesso: - classKey - A chave da classe. - Querystring: - Qualquer campo - Podem ser utilizados todos os campos para realizar a filtragem. - EX: ?ikey=<chave-do-registro> - Corpo da requisição: Nenhum.

Ponto de acesso

GET /api/classes/v1/classes/<classKey>/entities

Exemplo de consumo

curl -X GET -i https://<domain.com>:<port>/api/classes/v1/classes/-1898187811/entities?ikey=-1898186562 -u '<user>:<pass>'

Resultado

HTTP/1.1 200 OK Content-Type: application/json [ { "ilanguage": null, "iclass": -1898187810, "ccustres": null, "estabeleci": null, "inavtreevisibilitymode": null, "ishortcuts": [ 32145359 ], "ihomeprocess": null, "iissuablelicenses": null, "ichangeablelicenses": null, "ipassword": null, "ismtppassword": null, "ismtpusername": "user@company.com", "ismtpserver": null, "iemailaddress": "user@company.com", "igroups": null, "isecuritypolicy": null, "ifullname": "Administrador de papel", "iname": "Administrador de papel", "iversion": 17138993, "ikey": -1898186562, "iinformedfields": null } ]

Consulta de classes filhas de uma classe.

Este ponto de acesso responde o conjunto de todas as classes filhas de uma classe. Toda classe possui um campo chamado MAE ao qual referencia uma classe da mesma tabela, basicamente serão fornecidos todas as classes que possuem esse campo preenchido com a chave da classe informada.

- Parâmetros:
  - - Caminho do ponto de acesso: classKey - A chave da classe.
    - Querystring: Nenhum.
    - Corpo da requisição: Nenhum.

Ponto de acesso

GET /api/classes/v1/classes/<classKey>/children

Exemplo de consumo

curl -X GET -i https://<domain.com>:<port>/api/classes/v1/classes/-1898187811/children -u '<user>:<pass>'

Resultado

HTTP/1.1 200 OKContent-Type: application/json[ -1898187809, -1898141934]

Consulta as classes descendentes de uma classe.

Este ponto de acesso responde o conjunto de todas as classes filhas na hierarquia ou seja, todos as classes descendentes que podem ser filhas, netas, bisnetas incluindo as últimas classes que não possuem classes descendentes. Ou ainda podemos dizer que este ponto e acesso pega toda a árvore de classes a partir de uma classe raiz inclusa.

- Parâmetros:
  - - Caminho do ponto de acesso : -classKey - A chave da classe.
    - Querystring: Nenhum.
    - Corpo da requisição: Nenhum.

Ponto de acesso

GET /api/classes/v1/classes/<classKey>/descendants

Exemplo de consumo

curl -X GET -i https://<domain.com>:<port>/api/classes/v1/classes/-1898187811/descendants -u '<user>:<pass>'

Resposta

HTTP/1.1 200 OK Content-Type: application/json [ -1898187811, -1898187810, -1898187809, -1898142007, -1898141934 ]

Consultar uma entidade

Este ponto de acesso responde um objeto com as informações de uma entidade de acordo com o identificador parametrizado no caminho do ponto de acesso.

- Parâmetros:
  - - Caminho do ponto de acesso:
      - classKey - Chave da classe.
        id - Identificador ou chave da entidade.
    - Querystring: Nenhum.
    - Corpo da requisição: Nenhum.

Ponto de acesso

GET /api/classes/v1/classes/<classKey>/entities/<id>

Exemplo de consumo

curl -X POST -i https://<domain.com>:<port>/api/classes/v1/classes/-1898187809/entities/-1898186559 -u '<user>:<pass>'

Resposta

HTTP/1.1 200 OK Content-Type: application/json { "locescritu": null, "entidade": null, "iendhour": null, "iend": null, "ibeginhour": null, "ibegin": null, "ilastpasswdchg": "2010-11-23", "istatus": -1898143909, "iname": "administrator", "ipassword": "6EIIKcZ/2JlnN5LNXCeAwziUf8c=", "iclass": -1898187809, "ccustres": null, "estabeleci": null, "inavtreevisibilitymode": null, "ishortcuts": null, "ihomeprocess": null, "iissuablelicenses": null, "ichangeablelicenses": null, "ismtppassword": null, "ismtpusername": null, "ismtpserver": null, "ilanguage": -1898187416, "iemailaddress": null, "igroups": [ -1898186568 ], "isecuritypolicy": null, "ifullname": null, "iversion": 5377062, "ikey": -1898186559, "iinformedfields": null }

Criar entidades

O consumo deste ponto de acesso cria uma entidade de forma similar ao post da grade de Explorer.ip após a execução do botão `’+’.

- Parâmetros:
  - - Caminho do ponto de acesso:
      - classKey - Chave da classe.
    - Querystring: Nenhum.
    - Corpo da requisição: JSON válido com os dados referente a uma entidade.

Ponto de acesso

POST /api/classes/v1/classes/<classKey>/entities

Exemplo de consumo

curl -X POST -i https://<domain.com>:<port>/api/classes/v1/classes/-1898187810/entities -u '<user>:<pass>' -d '[{ "iclass": -1898187810, "ismtpusername": "web%group.com.br", "iemailaddress": "web@group.com.br", "ifullname": "Gerentes de Projeto", }]'

Resultado

HTTP/1.1 201 Created Content-Type: application/json { "ilanguage": null, "iclass": -1898187810, "ccustres": null, "estabeleci": null, "inavtreevisibilitymode": null, "ishortcuts": [ ], "ihomeprocess": null, "iissuablelicenses": null, "ichangeablelicenses": null, "ipassword": null, "ismtppassword": null, "ismtpusername": "web%group.com.br", "ismtpserver": null, "iemailaddress": "web@group.com.br", "igroups": null, "isecuritypolicy": null, "ifullname": "Gerentes de Projeto", "iname": "Novos Gerentes", "iversion": 17121493, "ikey": 1231235123, "iinformedfields": null }

Atualizar entidades

Existem duas formas de atualizar entidades, a diferença entre elas é o verbo HTTP utilizado, podem ser utilizados POST, PATCH e PUT.

O POST pode ser utilizado por convenção para atualizações quando houver parâmetro de identificador de entidade no caminho do ponto de acesso, ou seja, o POST pode ser utilizado como PATCH para realizar atualizações.

O PUT deveria ser utilizado quando o intuito da atualização é substituir todos os campos, ou seja, aqueles que não forem informados e estiverem preenchidos deveriam ser apagados, esse é o comportamento padrão do PUT contudo a API de classes não utiliza essa semântica de atualização ainda, por enquanto, o PUT pode ser utilizado como PATCH. O impedimento para deixar que o PUT tenha o propósito conceitual do REST é o fato de a aplicação cliente ter a necessidade de atualizar o esquema toda vez que houver uma criação de campo.

O PATCH deverá ser utilizado para atualizações complementares, ele irá atualizar somente os campos que forem informados, funcionando como uma atualização de fato. Este verbo é relativamente novo no HTTP e por isso os serviços de atualização são disponibilizados via POST.

Esse ponto de acesso irá realizar uma atualização em um registro devidamente identificados.

- Parâmetros:
  - - Caminho do ponto de acesso:
      - classKey - Chave da classe.
        id - Identificador ou chave da entidade.
    - Querystring: Nenhum.
    - Corpo da requisição:
      - JSON válido com os dados referentes a uma entidade ou mais entidades.

Ponto de acesso

POST /api/classes/v1/classes/<classKey>/entities/<id> PATCH /api/classes/v1/classes/<classKey>/entities/<id> PUT /api/classes/v1/classes/<classKey>/entities/<id>

Exemplo de consumo

curl -X PATCH -i https://<domain.com>:<port>/api/classes/v1/classes/-1898187810/entities/1231235123 -u '<user>:<pass> -d '[{ "ifullname": "Alterando o nome do Grupo de Gerentes de Projeto", }]'

Resultado

HTTP/1.1 200 OK Content-Type: application/json { "ilanguage": null, "iclass": -1898187810, "ccustres": null, "estabeleci": null, "inavtreevisibilitymode": null, "ishortcuts": [ ], "ihomeprocess": null, "iissuablelicenses": null, "ichangeablelicenses": null, "ipassword": null, "ismtppassword": null, "ismtpusername": "web%group.com.br", "ismtpserver": null, "iemailaddress": "web@group.com.br", "igroups": null, "isecuritypolicy": null, "ifullname": "Alterando o nome do Grupo de Gerentes de Projeto", "iname": "Novos Gerentes", "iversion": 17121493, "ikey": 1231235123, "iinformedfields": null }

Excluir uma entidade

O consumo deste ponto de acesso irá excluir uma entidade, semelhante o botão '-' da grade Explorer.ip localizada em Bematech\Admin.

- Parâmetros:
  - - Caminho do ponto de acesso:
      - classKey - Chave da classe.
        id - Identificador ou chave da entidade.
    - Querystring: Nenhum.
    - Corpo da requisição: Nenhum.

Ponto de acesso:

DELETE /api/classes/v1/classes/<classKey>/entities/<id>

Exemplo de consumo

curl -X POST -i https://<domain.com>:<port>/api/classes/v1/classes/-1898187810/entities/1231235123 -u '<user>:<pass>'

Resultado

HTTP/1.1 200 OK Content-Type: application/json

Entidades

Este recurso é referente a entidades de classes da mesma forma como o recurso de Classes, com isso, as mesmas regras anteriormente mencionadas se aplicam a este recurso tornando os seus pontos de acesso apelidos para os do recurso de Classes.

Este recurso possui um pequeno custo a mais que o recurso de Classes e por conta disso ele será utilizado para realizar referências a chaves estrangeiras (lookup).

Também não será possível realizar criação de entidades por meio deste recurso.

Consulta de entidades

O resultado deste ponto de acesso fornece a informação do registro da entidade de acordo com o identificador fornecido, de forma semelhante a consulta de entidade do recurso de Classes ou consulta de entidades filtrada por querystring.

- Parâmetros
  - - Caminho do ponto de acesso:
      - id - Identificador ou chave da entidade.
    - Querystring: Nenhum.
    - Corpo da requisição: Nenhum.

Ponto de acesso

GET /api/classes/v1/entities/<id>

Exemplo de consumo

curl -X POST -i https://<domain.com>:<port>/api/classes/v1/entities/-1898186559 -u '<user>:<pass>'

Resposta

Atualizar entidades

Esse ponto de acesso é apenas um atalho para o ponto de acesso mencionado no recuso de Classes ele possui os mesmos verbos HTTP mencionados lá e deve seguir o mesmo propósito quando o requisitante não possuir a classe de dados da entidade a ser atualizada.

- Parâmetros
  - - Caminho do ponto de acesso:
      - id - Identificador ou chave da entidade
    - Querystring: Nenhum
    - Corpo da requisição: Nenhum

Ponto de acesso

POST /api/classes/v1/entities/<id> PATCH /api/classes/v1/entities/<id> PUT /api/classes/v1/entities/<id>

Exemplo de consumo

curl -X PATCH -i https://<domain.com>:<port>/api/classes/v1/entities/1231235123 -u '<user>:<pass> -d '[{ "ifullname": "Alterando o nome do Grupo de Gerentes de Projeto", }]'

Resultado

Excluir entidades

Este ponto de acesso funciona como um atalho para o ponto de acesso de remoção de entidades do recurso de classes.

- Parâmetros:
  - - Caminho para o ponto de acesso:
      - id - Identificador ou chave da Entidade
    - Querystring: Nenhum.
    - Corpo da requisição: Nenhum.

Ponto de acesso:

DELETE /api/classes/v1/entities/<id>

Exemplo de consumo

curl -X POST -i https://<domain.com>:<port>/api/classes/v1/entities/1231235123 -u '<user>:<pass>'

Resultado

HTTP/1.1 200 OK Content-Type: application/json