Histórico da Página

CONTEÚDO

01. VISÃO GERAL

Disponibilizar recursos para facilitar a integração das rotinas do módulo Easy Import Control com a utilização da tecnologia de APIs REST.

02. CONCEITO

A integração via APIs REST permite a comunicação entre diferentes sistemas ou aplicativos por meio de APIs que seguem o padrão REST, onde essas APIs utilizam métodos HTTP padrão, como GET, POST, PUT e DELETE, com objetivo de permitir que sistemas compartilhem dados e funcionalidades de maneira eficiente e escalável.

Esses métodos são fundamentais para a comunicação entre clientes e servidores e cada um tem um propósito específico, como:

GET: é usado para consultar algum dado do servidor, assim não realizando qualquer modificação neles, como por exemplo, uma consulta de cadastro.
POST: é usado para enviar dados para serem processados ou armazenados no servidor, como por exemplo, uma inclusão de cadastro.
PUT: é usado para atualizar algum dado do servidor, como por exemplo, uma alteração de cadastro.
DELETE: é usado para remover algum dado do servidor. como por exemplo, uma exclusão de cadastro

Informações

Observação

Por padrão, para realizar o consulta de um determinado dado do servidor através do método GET, é necessário informar a pk - valor da chave primaria do alias do modelo em encodado em base64, caso contrário não informado, serão retornado os registros conforme sua paginação.

Exemplo:

"ICAgIDAwMDAwMDAwMDAwMDIyOA==" - representa a chave primária do registro da tabela da rotina em base64

http://localhost:8080/rest/FwModel/EICCP400/ICAgIDAwMDAwMDAwMDAwMDIyOA==

Para realizar a atualização de um determinado dado do servidor através do método PUT, é necessário informar a pk - valor da chave primaria do alias do modelo em encodado em base64, nesse caso, é obrigatório para realizar a alteração, caso contrário é entendido que está sendo feito uma inclusão.

Para realizar a exclusão de um determinado dado do servidor através do método DELETE, é necessário informar a pk - valor da chave primaria do alias do modelo em encodado em base64

03. ESTRUTURA DE ENVIO

A estrutura do JSON de envio (body) para os métodos GET e DELETE não tem necessidade de informar na requisição, somente realizar o consumo da API.

Já para o método POST e PUT, deverá ser enviado basicamente no formato:

{
    "id": "ID_API",
    "models": [{
            "id": "MODELO_DADOS",
            "modeltype": "FIELDS"
            "fields": [{
                    "id": "CAMPO",
                    "order": 1,
                    "value": ""
                }, {
                    "id": "CAMPO2",
                    "order": 2,
                    "value": "01"
                }
            ],
            "models": [{
                    "id": "SUBMODELO_DADOS",
                    "modeltype": "GRID"
                    "struct": [{
                            "id": "CAMPO",
                            "order": 1
                        }, {
                            "id": "CAMPO2",
                            "order": 2
                        }
                    ],
                    "items": [{
                            "id": 1,
                            "fields": [{
                                    "id": "CAMPO",
                                    "value": "001"
                                }, {
                                    "id": "CAMPO2",
                                    "value": "01"
                                }
                            ]
                        }, {
                            "id": 2,
                            "fields": [{
                                    "id": "CAMPO",
                                    "value": "002"
                                }, {
                                    "id": "CAMPO2",
                                    "value": "02"
                                }
                            ]
                        }
                    ],
                }
            ],
        }
    ]
}

Onde:

id: é id da API

models: são os modelos de negócios de cada API, ou seja, modelo de dados do MVC, que é definido por:

id: é o modelo de dados definido no MVC

modeltype: é tipo de modelo de dados, "FIELDS" ou "GRID"

fields: é um vetor com os campos do modelo, definido por:

id: é nome do campo

order: é a ordem do campo

value: é o valor do campo

models: é um vetor com os submodelos do modelo de dados do MVC, definido por:

id: é o submodelo de dados definido no MVC

modeltype: é tipo de modelo de dados, "FIELDS" ou "GRID"

struct: é um vetor definindo os campos do GRID, definido por:

id: é nome do campo

order: é a ordem do campo

items: é um vetor definindo os itens do GRID, definido por:

id: é um sequêncial do vetor dos itens,

fields: é um vetor com os campos e valores dos itens do GRID, definido por:

id: é nome do campo

value: é o valor do campo

04. ESTRUTURA DE RESPOSTAS

A estrutura do JSON de resposta para os métodos GET (para um determinado uma chave primária - pk), POST e PUT é basicamente da seguinte maneira:

{
    "id": "ID_API",
    "pk": "ICAgIDAwMDAwMDAwMDAwMDAxOQ==",
    "models": []
}

Onde:

id: é id da API

pk: chave primária de cada registro para realizar uma consulta específica, consumir o método put e delete

models: são os modelos de negócios de cada API, ou seja, modelo de dados do MVC (FIELDS, GRID)

A estrutura do JSON de resposta para o método GET sem determinar uma chave primária (pk), será da seguinte maneira:

{
    "total": 82,
    "count": 10,
    "startindex": 1,
    "resources": [{
            "id": "ID_API",
            "pk": "ICAgIDAwMDAwMDAwMDAwMDAxOQ==",
            "models": []
        }, {
            "id": "ID_API",
            "pk": "ICAgIDAwMDAwMDAwMDAwMDAxOQ==",
            "models": []
        }
    ]
}

Onde:

total: é o total de registros que existem no sistema

count: é a quantidade de registros retornados na requisição

startindex: é a contador inicial para realizar a paginação

resources: são as informações dos modelos de dados da API, composto por:

id: é id da API

pk: chave primária de cada registro para realizar uma consulta específica, consumir o método put e delete

models: são os modelos de negócios de cada API, ou seja, modelo de dados do MVC (FIELDS, GRID)

A estrutura do JSON de resposta para o método DELETE da seguinte maneira:

true

A estrutura do JSON de resposta com falha, será da seguinte maneira:

{
"errorCode": 400,
"errorMessage": "\r\n --- Erro no Modelo ---\r\nId submodelo origem:[EK9MASTER]\r\nId campo origem:[EK9_COD_I]\r\nId submodelo erro: [EK9MASTER]\r\nId campo erro: [EK9_COD_I]\r\nId erro: [JAGRAVADO ]\r\nMensagem de erro: [ Já existe registro com esta informação.]\r\nMensagem da solução: [Troque a chave principal deste registro.\r\n]\r\nValor atribuído: []\r\nValor anterior: [4234234290 ]\r\n"
}

05. EXEMPLO DE CONFIGURAÇÃO

Abaixo um exemplo de configuração do arquivo appserver.ini
Exemplo de configuração appserver.ini

[HTTPV11]
Enable=1
Sockets=HTTPREST

[HTTPREST]
Port=8080
URIs=HTTPURI
SECURITY=1

[HTTPURI]
URL=/rest
PrepareIn=99,01
Instances=1,2

[ONSTART]
jobs=HTTPJOB
RefreshRate=120

[HTTPJOB]
MAIN=HTTP_START
ENVIRONMENT=ENVIRONMENT

06. API REST DISPONÍVEIS

Após a configuração do REST do Protheus, podemos verificar todas as APIs REST disponível:

acessar o endereço configurado do Rest, nesse exemplo foi configurado dessa forma http://localhost:8080/rest
procurar o serviço FWMODEL
clicar em /rest/fwmodel.catalog.

Image Added

Será apresentado o catálogo de API REST disponíveis para as rotinas do Protheus:

Image Added

Para realizar o consumo de uma API REST disponíveis do módulo Financeiro, deverá ser da seguinte forma:

http://localhost:8080/rest/FwModel/FINA040VA

Onde:

http://localhost:8080/rest é o endereço configurado do REST

/FwModel é fixo (framework)

/FINA040VA é nome da API disponível, nesse exemplo, é a rotina de catálogo de produto

Árvore de páginas

Versões comparadas

Versão antiga 2

Nova versão Atual

Chave

CONTEÚDO

01. VISÃO GERAL

02. CONCEITO

03. ESTRUTURA DE ENVIO

04. ESTRUTURA DE RESPOSTAS

05. EXEMPLO DE CONFIGURAÇÃO

06. API REST DISPONÍVEIS

07. ASSUNTOS RELACIONADOS