CONTEÚDO
- Visão Geral
- Conceito
- Estrutura de envio
- Estrutura de respostas
- Exemplo de configuração
- APIs REST disponíveis
- Exemplo de utilização
- Assuntos Relacionados
01. VISÃO GERAL
O objetivo deste documento é mostrar como devem ser utilizados os modelos de dados existentes no módulo Pré-faturamento de Serviços (SIGAPFS), que usam o modelo padrão FWRESTMODEL.
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, não realizando qualquer modificação neles, por exemplo, uma consulta de cadastro.
- POST: é usado para enviar dados para serem processados ou armazenados no servidor, por exemplo, uma inclusão de cadastro.
- PUT: é usado para atualizar algum dado do servidor, como uma alteração de cadastro.
- DELETE: é usado para remover algum dado do servidor, como uma exclusão de cadastro.
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 primária do alias do modelo encodado em base64. Caso não seja informada, serão retornados 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 primária do alias do modelo encodado em base64. Nesse caso, é obrigatório para realizar a alteração, caso contrário, é entendido que está sendo feita 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 primária do alias do modelo 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:
|
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 sequencial 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:
|
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:
|
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:
|
A estrutura do JSON de resposta com falha, será da seguinte maneira:
|
05. EXEMPLO DE CONFIGURAÇÃO
Abaixo um exemplo de configuração do arquivo appserver.ini
Exemplo de configuração appserver.ini
|
06. APIs REST DISPONÍVEIS
As APIs REST disponíveis do módulo Pré-faturamento de Serviços são:
Descrição | Modelo | Apelido |
---|---|---|
Parâmetros | JURA171 | JPARAM |
Empresas / filiais | JURA193 | JEMPRESA |
Fila de Sincronização | JURA170 | JFILASINC |
Idiomas de Faturamento | JURA029 | JIDIOMA |
Moedas Contábeis | CTBA140 | JMOEDA |
Centros de Custos / Grupos Jurídicos | CTBA030 | JGRPJUR |
Cotações Diárias | MATA090 | JCOTDIARIA |
Lançamentos Tabelados | JURA027 | JLANCTAB |
Fechamento de Período | JURA030 | JFECHPER |
Áreas Jurídicas | JURA038 | JAREAJUR |
Tipos de Despesa | JURA044 | JTPDESP |
Despesas | JURA049 | JDESPESA |
Escritórios | JURA068 | JESCRITORIO |
Casos | JURA070 | JCASO |
Contratos de Faturamento | JURA096 | JCONTRATO |
Time Sheets | JURA144 | JTIMESHEET |
Clientes | JURA148 | JCLIENTE |
Participantes | JURA159 | JPARTICIPANTE |
Pré-faturas | JURA202 | JPREFAT |
Modelo resumido de Pré-fatura | JURA202E | JURA202RES |
Faturas | JURA204 | JFATURA |
Municípios | FISA010 | JMUNICIPIO |
Países | JURA194 | JPAIS |
Estados | JURA195 | JESTADO |
Tipos de Honorários | JURA037 | JTPHONOR |
Tipos de Atividade | JURA039 | JTPATIV |
Serviços Tabelados | JURA040 | JSERVTAB |
Tabela de Serviços | JURA041 | JTABSERV |
Tipo de Originação | JURA045 | JTPORIG |
Tipo da Tabela de Serviços | JURA047 | JTPTABSERV |
Subárea Jurídica | JURA048 | JSUBAREAJUR |
Categoria de Participante | JURA050 | JCATEGPART |
Documento E-billing | JURA057 | JDOCEBILL |
Empresa E-billing | JURA058 | JEMPEBILL |
Feriados | JURA078 | JFERIADO |
Cotações Mensais | JURA111 | JCOTMENSAL |
Localidades | JURA123 | JLOCALIDADE |
Tipo de Prestação de Contas | JURA164 | JTPPREST |
Tipo de Retorno / Situação de Cobrança | JURA073 | JTPRET |
Grupo de Clientes | FATA110 | JGRPCLI |
Condição de Pagamento | MATA360 | JCONDPAG |
Motivo de WO | JURA140 | JMOTIVOWO |
Anexos | JURA026 | JANEXOS |
Contatos | JURA232 | JCONTATOS |
Tabela de Honorários | JURA042 | JTABHONOR |
Faturas Adicionais | JURA033 | JFATADIC |
Solicitações de Despesa | JURA235 | JSOLICDES |
Consulta WO | JURA146 | JCONSULTWO |
Naturezas Financeiras | FINA010 | JNATUREZA |
Tabelas de Rateio | JURA238 | JTABRATEIO |
Lançamentos Financeiros | JURA241 | JLANCAMENTOS |
Orçamentos | JURA252 | JORCAMENTOS |
Calendário Contábil | JURA253 | JCALENDARIO |
Controles de Adiantamentos | JURA069 | JADIANTAMENTO |
Posição Histórica do Contas a Receber | JURA255 | JPOSRECEBER |
Rastreio de Recebimento dos Casos da Fatura | JURA256 | JRASTRECEBER |
Bancos | MATA070 | JBANCO |
Projetos e Finalidades | JURA264 | JPROJETO |
Fornecedores | MATA020 | JFORNECE |
Cobrança | JURA244 | JCOBRANCA |
Segmentos | CRMA610 | JSEGMENTO |
Anexos (NUM) | JURA290 | JDOCANEXO |
Tabela de Honorários Padrão | JURA028 | JTABPADRAO |
Controle de Versão Legal Desk | JURA300 | - |
Movimentações em Adiantamentos | JURA311 | JMOVADIANT |
Tipos de Fatura | JURA036 | JTPFAT |
Motivos de Cancelamento de Fatura | JURA071 | JMOTCANFT |
Classificação de Naturezas | JURA266 | JCLNAT |
Tipo de Carta de Cobrança | JURA043 | JTPCARTA |
Tipo de Relatório de Faturamento | JURA046 | JTPRELFAT |
Tipo de Fechamento | JURA274 | JTPFECH |
Exceções da Numeração da Fatura | JURA075 | JEXNUMFAT |
Tipos de Relatório de Pré-fatura | JURA196 | JTPRELPFT |
Sugestão Título do Caso | JURA231 | JSTITCAS |
Ramais por Profissional | JURA034 | JRAMPROF |
Retificação de Time Sheet | JURA072 | JRETTS |
Moedas Bloqueadas | JURA121 | JCMOEBLQ |
Tipos de Protocolo de Faturamento | JURA084 | JTPPROTFT |
07. EXEMPLO DE UTILIZAÇÃO
Todos os modelos listados acima usam o padrão FWMODEL. Suportam todas as operações (POST PUT, GET, DELETE) RESTFUL. A documentação completa pode ser vista no documento FWRestModel.
A API pode retornar todos os registros ou apenas um registro específico. Para acessar um registro específico, deve ser informada a chave única do registro em formato BASE64.
Exemplo para o modelo de Time Sheets:
A chave da tabela de processos é NUE_FILIAL + NUE_COD
GET para retornar todos os registros:
<HTTPRESTCLIENTE:/fwmodel/jura144/
Se quisermos retornar um registro específico (registro filial 01 código 0000000001:
<HTTPRESTCLIENTE:/fwmodel/jura144/MDEwMDAwMDAwMDAx
A estrutura de retorno é a mesma estrutura que deve ser usada em operações como PUT e POST.
QueryStrings
COUNT = Quantidade de registro que devem ser retornados (padrão: 10)
STARTINDEX = Indica a partir que qual index deverá ser retornado (padrão: 1)
FILTER = Filtro que será aplicado no método SetFilter()
FIELDDETAIL = Habilita mostrar mais informações nos campos do modelo (padrão: 10)
FIELDVIRTUAL = Habilita o retorno de campos virtuais (padrão: false)
FIELDEMPTY = Habilita o retorno de campos sem valores (padrão: false)
FIRSTLEVEL = Habilita o retorno dos sub modelos (padrão: true)
FIELDS = Indica os campos a serem filtrados no retorno do modelo, incluindo os sub modelos, caso não informado todos os campos serão retornados
DEBUG = Valor booleano para habilitar o modo debug (padrão: false)
CACHE = Indica se será feito cache do total de registros por alias, refere-se ao valor do total no retorno (padrão: true)
INTERNALID = Indica se deve retornar o ID (Recno) como informação complementar das linhas do GRID (padrão: false)