Índice
Objetivo
Disponibilizar recursos para simplificar a integração das rotinas do módulo TAF (TOTVS Automação Fiscal) através da utilização de APIs REST.
01. CONCEITO
A integração via APIs REST permite a comunicação eficiente e escalável entre diferentes sistemas ou aplicativos, utilizando métodos HTTP padrão como GET, POST, PUT e DELETE. Essas APIs seguem o padrão REST, facilitando o compartilhamento de dados e funcionalidades entre os sistemas.
Cada método HTTP tem um propósito específico:
- GET: Utilizado para consultar dados no servidor sem modificar nada, como, por exemplo, uma consulta de cadastro.
- POST: Utilizado para enviar dados ao servidor para serem processados ou armazenados, como, por exemplo, a inclusão de um cadastro.
- PUT: Utilizado para atualizar dados no servidor, como, por exemplo, a alteração de um cadastro.
- DELETE: Utilizado para remover dados do servidor, como, por exemplo, a exclusão de um cadastro.
Observação
Por padrão, para consultar um determinado dado do servidor através do método GET, é necessário informar a chave primária (PK) do registro do modelo, codificada em base64. Caso contrário, se a chave primária não for informada, os registros serão retornados conforme a paginação padrão.
Exemplo:
"RCBNRyAwMSBEIE1HIDAxIDAwMDAwMDAwMDAwMDAwMiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIA==" - representa a chave primária do registro da tabela da rotina em base64
Para atualizar um determinado dado do servidor através do método PUT, é necessário informar a chave primária (PK) do registro do modelo, codificada em base64. Nesse caso, a chave primária é obrigatória para realizar a alteração; caso contrário, a operação será entendida como uma inclusão de novo registro.
Para excluir um determinado dado do servidor através do método DELETE, também é necessário informar a chave primária (PK) do registro do modelo, codificada em base64.
Para incluir dados no servidor através do método POST em outras filiais, é importante o uso do tenantId no header da requisição.
02. API REST DISPONÍVEIS
Após configurar o REST do Protheus, é possível verificar todas as APIs REST disponíveis seguindo os passos abaixo:
- Acesse o endereço configurado do REST. No exemplo, foi configurado como:
http://localhost:8080/rest. - Procure pelo serviço FWMODEL.
- Clique em /rest/fwmodel.catalog.
Para consumir uma API REST disponível no módulo TAF (TOTVS Automação Fiscal), siga o formato abaixo:
API's disponíveis no módulo SIGATAF
http://localhost:8080/rest/FwModel/TAFA053 http://localhost:8080/rest/FwModel/TAFA057 http://localhost:8080/rest/FwModel/TAFA448 http://localhost:8080/rest/FwModel/TAFA535
Onde:
- http://localhost:8080/rest é o endereço configurado do REST.
- /FwModel é um segmento fixo indicando o framework.
- /TAFA053 é o nome da API disponível.
03. ESTRUTURA DE ENVIO
A estrutura do JSON de envio (body) não precisa ser informada na requisição para os métodos GET e DELETE; basta consumir a API.
No entanto, para os métodos POST e PUT, o JSON deve ser enviado no seguinte formato básico:
JSON - Exemplo
{
"id": "TAFA057",
"operation": 1,
"models": [
{
"id": "MODEL_C1L",
"modeltype": "FIELDS",
"fields": [
{
"id": "C1L_FILIAL",
"order": 1,
"value": "D MG 01"
},
{
"id": "C1L_CODIGO",
"order": 3,
"value": "PRD12345"
},
{
"id": "C1L_DESCRI",
"order": 4,
"value": "PRD-VIA-POST"
},
{
"id": "C1L_UM",
"order": 6,
"value": "000084"
},
{
"id": "C1L_TIPITE",
"order": 8,
"value": "000010"
},
{
"id": "C1L_CODGEN",
"order": 12,
"value": "000102"
},
{
"id": "C1L_CODSER",
"order": 14,
"value": "000045"
},
{
"id": "C1L_ORIMER",
"order": 21,
"value": "000001"
},
{
"id": "C1L_ALQICM",
"order": 23,
"value": "18.00"
},
{
"id": "C1L_DTINCL",
"order": 26,
"value": "20221019"
},
{
"id": "C1L_SRVMUN",
"order": 29,
"value": "1402"
},
{
"id": "C1L_IDTSER",
"order": 48,
"value": "000016"
}
],
"models": [
{
"id": "MODEL_C1M",
"modeltype": "GRID",
"optional": 1,
"struct": [
{
"id": "C1M_FILIAL",
"order": 1
},
{
"id": "C1M_DTALT",
"order": 2
},
{
"id": "C1M_HRALT",
"order": 3
},
{
"id": "C1M_NRCAMP",
"order": 4
},
{
"id": "C1M_CTDANT",
"order": 6
}
],
"items": [
{
"id": 1,
"deleted": 0,
"fields": [
{
"id": "C1M_FILIAL",
"value": "D MG 01"
},
{
"id": "C1M_DTALT",
"value": "20240520"
},
{
"id": "C1M_HRALT",
"value": "1313"
},
{
"id": "C1M_NRCAMP",
"value": "000001"
},
{
"id": "C1M_CTDANT",
"value": "PRD12345"
}
]
}
]
}
]
}
]
}
Estrutura Hierárquica
- id: é id da API
- models: são os modelos de negócios de cada API, que contém:
- 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, que contém:
- 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, que contém:
- 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, que contém:
- id: é nome do campo
- order: é a ordem do campo
- items: é um vetor definindo os itens do GRID, que contém:
- id: é um sequêncial do vetor dos itens
- fields: é um vetor com os campos e valores dos itens do GRID, que contém:
- id: é nome do campo
- value: é o valor do campo
A estrutura do JSON de resposta para os métodos GET (por chave primária - pk), POST e PUT é basicamente a seguinte:
JSON - Exemplo de resposta do GET[pk]
{
"id": "TAFA057",
"pk": "RCBNRyAwMSBEIE1HIDAxIDAwMDAwMDAwMDAwMDAwMiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIA==",
"models": []
}
Onde a estrutua hierárquica é: :
- id: é id da API
- pk: chave primária de cada registro para realizar uma consulta específica GET[id], 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 especificar uma chave primária (pk), será conforme abaixo:
JSON - Exemplo de resposta do GET sem [pk]
{
"total": 142,
"count": 10,
"startindex": 1,
"resources": [{
"id": "TAFA057",
"pk": "RCBNRyAwMSBEIE1HIDAxIDAwMDAwMDAwMDAwMDAwMiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIA==",
"models": []
}, {
"id": "TAFA057",
"pk": "RCBNRyAwMSBEIE1HIDAxIDEyMyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIA==",
"models": []
}
]
}
Onde a estrutua hierárquica é:
- total: é o total de registros que existem no sistema
- count: é a quantidade de registros retornados na requisição
- startindex: é o 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 será da seguinte maneira:
JSON - Exemplo de resposta do POST
true
A estrutura do JSON de resposta em caso de falha será da seguinte maneira:
JSON - Exemplo de resposta falha no POST
{
"errorCode": 400,
"errorMessage": "\r\n --- Erro no Modelo ---\r\nId submodelo origem:[MODEL_C1L]\r\nId campo origem:[C1L_CODIGO]\r\nId submodelo erro: [MODEL_C1L]\r\nId campo erro: [C1L_CODIGO]\r\nId erro:
[TAFJAGRAVADO]\r\nMensagem de erro: [ Esta chave de registro formada pelos campos obrigatórios já foi informada em outro momento neste mesmo cadastro.
Para manter a integridade da informação não poderá haver duplicidade no cadastro, portanto não será permitido salvar este registro.]
\r\nMensagem da solução: [Deverá ser alterada a chave de identificação única do registro composta pelos campos obrigatórios de forma a não coincidir com outros dados já gravados neste mesmo
cadastro.\r\n]\r\nValor atribuído: []\r\nValor anterior: [1234 ]\r\n"
}
{
"errorCode": 400,
"errorMessage": "\r\n --- Erro no Modelo ---\r\nId submodelo origem:[MODEL_C1L]\r\nId campo origem:[C1L_UM]\r\nId submodelo erro: [MODEL_C1L]\r\nId campo erro:
[C1L_UM]\r\nId erro: [C1L_UM ]\r\nMensagem de erro: [ Deve representar a Unidade de medida utilizada na quantificação de estoques, conforme determina o fisco no Convênio 31/99, no
Guia Prático EFD Fiscal e Contribuições.
\r\n\r\nA informação deste campo corresponde á um código de identificação conforme respectivo cadastro.]
\r\nMensagem da solução: [\r\n]\r\nValor atribuído: []\r\nValor anterior: [xxx ]\r\n"
}
Dica
Ao realizar um POST, devem ser respeitados os campos de ID recebidos no método GET. Por exemplo, considere os seguintes campos:
C1H_UF: Enviar o código 000027 vinculado à tabela C09 (unidade federativa), e não SP.
C1H_CODMUN: Enviar o código 003293 vinculado à tabela C07 (Municípios do IBGE), e não AMERICO DE CAMPOS.
C1L_UM: Enviar o código presente na tabela de unidade de medida, e não UN.
Certifique-se de que os dados enviados no POST correspondam corretamente aos identificadores recebidos no GET, evitando o uso de valores literais inadequados.
08. ASSUNTOS RELACIONADOS
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas