Histórico da Página

...

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.

Informações

title	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 informadoinformada, 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 . Nesse caso, é obrigatório para realizar a alteração. Caso , 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.

...

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

...

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:

{
    "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. 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)

...

INTERNALID = Indica se deve retornar o ID (Recno) como informação complementar das linhas do GRID (padrão: false)

Card documentos

Informacao	Consulte a documentação https://tdn.totvs.com/pages/releaseview.action?pageId=271671548 para mais detalhes técnicos.
Titulo	IMPORTANTE!

...

Árvore de páginas

Versões comparadas

Versão antiga 11

Nova versão Atual

Chave

01. VISÃO GERAL

02. CONCEITO

04. ESTRUTURA DE RESPOSTAS

05. EXEMPLO DE CONFIGURAÇÃO

06. APIs REST DISPONÍVEIS

07.

EXEMPLO DE UTILIZAÇÃO

08. ASSUNTOS RELACIONADOS