PRODUÇÃO
Esta página disponibiliza o conjunto de especificações e informações gerais sobre o funcionamento da nova plataforma para Envio de Dados ao TCMGO.
Dúvidas / Sugestões? Acesse o Ticket e abra uma demanda!
O envio de dados ao TCMGO será realizado por meio de um conjunto de soluções de TI que atuam de forma integrada para a recepção, verificação e persistência dos dados.
O COnstrutor de LAyouts e REgras de recepção é um dos sistemas e tem por objetivo gerar insumos para a validação, verificação e persistência de dados. O produto gerado pelo Colare é pré-requisito para que o sistema Recepção possa capturar e realizar o tratamento de dados.
Importante destacar que a construção de layouts e regras é customizável às necessidades do negócio, sendo realizada diretamente pela área de negócio interessada através de funcionalidades contidas no Colare, ou seja, sem a necessidade de manipulação do código-fonte da aplicação.
É o meio oficial de disponibilização de informações técnicas relacionadas ao envio de dados. Contém informações quanto aos requisitos técnicos para os sistemas dos jurisdicionados, além da especificação dos layouts disponíveis para a recepção de dados, detalhando a composição do layout, com seus recpectivos campos e regras de integridade associadas, bem como as regras de recepção.
Tem as seguintes funcionalidades:
Regulamentado pela IN 006/2018, o Passaporte é a ferramenta centralizada de cadastro e controle de acesso aos sistemas da inédita plataforma tecnológica do TCMGO. Integrado às bases da Receita Federal do Brasil e Tribunal Regional Eleitoral, permite acesso seguro para gestão cadastral 100% eletrônica dos agentes públicos e das unidades gestoras e orçamentárias da administração municipal. Todo processo de credenciamento se dará 100% online, sem necessidade de deslocamentos ou papéis. Mais informações em: wwws.tcm.go.gov.br/passaporte .
É o sistema que proverá os endpoints que serão utilizados pelos sistemas de gestão dos jurisdicionados para envio automatizado dos dados. A interoperabilidade entre os sistemas se dará através da arquitetura REST e os dados serão trafegados no formato JSON.
Para validar o formato dos dados enviados ao sistema, será gerado um schema a partir do layout cadastrado no Colare que validará as regras de integridade e estruturais do formato válido para o envio das informações. Caso os dados submetidos não estejam em conformidade com o schema gerado, será evidenciado o que está em desacordo (ver item 2.5).
Por meio dessa ferramenta é possível ao jurisdicionado verificar quais entregas foram realizadas, editá-las ou excluí-as (caso necessário e não esteja homologada) e obter o recibo das entregas homologando-as ao final do processo de envio. É importante salientar que só será considerado entregue os dados homologados.
1.5.1 Homologação da Entrega
A homologação pode ser feita de duas formas, conforme abaixo. O TCMGO recomenda o uso de sistemas integrados, por garantirem maior confiabilidade, além de facilitar a realização dos procedimentos pelos gestores:
a) Via Colare-Envios
Após o envio de dados, o jurisdicionado deverá homologar a entrega, por meio do Colare Envios. Durante o processo de homologação, o jurisdicionado consolida os dados e assina eletronicamente a entrega, utilizando um certificado digital ICP-Brasil. Para tal, deverá logar na ferramenta, acessar o menu ENVIOS. Na listagem das entregas selecionar uma ou mais entregas não homologadas e acionar a opção HOMOLOGAR.
b) Via Sistema integrado (novo)
Após o envio de dados, o jurisdicionado deverá homologar a entrega, seguindo os passos definidos pelo fornecedor de seu sistema de gestão. Note que essa forma de homologação simplifica demasiadamente o processo de homologação, em relação ao uso do Colare-Envios.
1.5.2 Retificação de Entrega Homologada
1.5.2.1 Prestação de contas Licitações, Dispensas e Adesão a Registro de Preços:
Depois de homologados, os envios podem ser retificados da seguinte forma:
1.5.2.2 Prestações de contas Atos de Pessoal e Folha de Pagamento:
1.5.3 Formulários de envios (funcionalidade exclusiva para os layouts de Licitação e Contratos)
Para os layout vinculados a prestação de contas Licitações, Dispensas e Adesão a Registro de Preços, além da homologação, também é possível realizar o envio manual dos dados, pelo preenchimento de formulários. Caso o jurisdicionado não possua solução que permite o envio de dados de forma integrada, deverá acessar o Colare Envios para obter acesso ao formulário correspondente ao layout a que se refere o envio de dados. Os formulários são gerados dinamicamente e sempre se referem à versão mais recente do layout publicada, de acordo com a vigência (mês/ano) carregadas na página. Ao navegar pela vigência os layouts poderão sofrer algumas mudanças, pois modificações no layout poderão ser realizadas para vigências futuras. O jurisdicionado, então, deverá inserir manualmente os dados solicitados pelo layout. A validação de integridade é feita durante o preenchimento do formulário, facilitando esta tarefa. Após o preenchimento, o Colare Envios cria um objeto JSON que será enviado através do mesmo endpoint utilizado na forma de envio integrada. É oportuno destacar que tal funcionalidade será desativada, exigindo que os jurisdicionados tenham sistemas de gestão que possa realizar o envio de forma integrada.
Abaixo seguem algumas mídias inerentes ao projeto.
Visando esclarecer dúvidas e orientar os jurisdicionados quanto a operação do sistema PASSAPORTE e COLARE, o TCMGO por meio da Escola de Contas organizou uma série de turmas para cursos sobre as plataformas. Os cursos também foram transmitidos pelo Youtube e estão disponíveis abaixo.
Representational State Transfer (REST), em português Transferência de Estado Representacional, é uma abstração da arquitetura da World Wide Web (Web), um estilo arquitetural que consiste de um conjunto coordenado de restrições arquiteturais aplicadas a componentes, conectores e elementos de dados dentro de um sistema de hipermídia distribuído. O REST ignora os detalhes da implementação de componente e a sintaxe de protocolo com o objetivo de focar nos papéis dos componentes, nas restrições sobre sua interação com outros componentes e na sua interpretação de elementos de dados significantes.
Segue abaixo princípios fundamentais:
JSON (JavaScript Object Notation), em português Notação de Objetos JavaScript, é uma formatação leve de troca de dados. Para seres humanos, é fácil de ler e escrever. Para máquinas, é fácil de interpretar e gerar. Está baseado em um subconjunto da linguagem de programação JavaScript, Standard ECMA-262 3a Edição - Dezembro - 1999. JSON é em formato texto e completamente independente de linguagem, pois usa convenções que são familiares às linguagens C e familiares, incluindo C++, C#, Java, JavaScript, Perl, Python e muitas outras. Estas propriedades fazem com que JSON seja um formato ideal de troca de dados.
JSON está constituído em duas estruturas:
Estas são estruturas de dados universais. Virtualmente todas as linguagens de programação modernas as suportam, de uma forma ou de outra. É aceitável que um formato de troca de dados que seja independente de linguagem de programação se baseie nestas estruturas. Segue abaixo um exemplo de JSON:
{ "codOrgao": 10, "codUnidade": 10, "nroProcessoLicitatorio": 2, "anoExercicioProcesso": 2017, "tipoProcesso": 1, "dtAbertura": "15/06/1989", "naturezaObjeto": 1, "objeto": "objeto", "justificativa": "justificativa", "razao": "123" }
Endpoints são os pontos de entrada para serviços, ou seja, são a interface de comunicação entre as aplicações dos jurisdicionados e o Colare. Dessa forma, para transmitir os dados ao TCMGO, a aplicação deverá enviar uma requisição HTTP para uma URL definida no sistema "Recepção". A partir do contexto "https://virtual.tcm.go.gov.br/recepcao/" existem diversas URLs que permitem o recebimento de dados. Algumas dessas URLs já estão previamente definidas e outras são geradas dinamicamente pela agregação de informações, obedecendo a um padrão.
Conforme dito na seção 1.3, o Passaporte será utilizado para permissão e autenticação dos jurisdicionados nos sistemas do TCMGO. O sistema de Recepção também utilizará o passaporte para validar o acesso aos Endpoints que necessitam de segurança e autenticidade para o envio das informações.
O controle de permissões do Passaporte se dá por meio das representações das quais o usuário possui. Por isso, a obtenção do token no Passaporte é realizada em dois passos:
{ "nome": "NOME DA PESSOA", "representacoes": [ { "codigo": 021, "representacao": "PRESIDENTE DA CÂMARA", "unidade": "CÂMARA DE PESSOA FELIZ", "tipo": "CÂMARA", "poder": "LEGISLATIVO", "municipio": "PESSOA FELIZ", "dataInicioRepresentacao": "2018-01-01", "dataFimRepresentacao": "2019-12-31" } ] }
{ "token": { "valor": "eyJhbGciOiJIUzUxMiJ9.ey...Isw", "claims": { "logadoComCertificadoDigital": true, "sub": "12345678900", "audience": "web", "created": 1543603909, "representacao": 21, "exp": 1543625509 } }, "usuario": { "id": 12, "status": "ATIVO", "dataCriacao": 1533154801920, ... }, "representacoes": [ { "id": 21, "status": "ATIVO", "dataCriacao": 1541435231560, }, "unidadeGestoraRepresentada": { "id": 198, "status": "ATIVO", ... }, "dataInicioRepresentacao": "2018-01-01", "dataFimRepresentacao": "2019-12-31", ... } ], "nome": "NOME DA PESSOA", "cpfCnpj": "12345678900", ... } }
Com o token é possível acessar os endpoints que necessitam de autenticação colocando seu valor ("token.valor") no cabeçalho Authorization da requisição HTTP. Segue exemplo de obtenção dos dados enviados LC1, layout RPR, mês 1 de 2017 com o ID 1:
Authorization
GET /recepcao/LC1/RPR/1/2017/1 HTTP/1.1 Host: virtual.tcm.go.gov.br Content-Type: application/json Authorization: eyJhbGciOiJIUzUxM....Q4-tuHg
Cada combinação de prestação de contas layout e mês/ano, juntamente com a operação que se pretende realizar, forma uma URL específica. Veja:
¹ O endpoint de "Homologar Entrega" deverá ser utilizado para realizar a homologação através do envio do PDF de homologação assinado digitalmente pelo responsável do envio. O arquivo PDF pode ser obtido através do endpoint "Obter PDF de homologação do envio", assinado e posteriormente enviado através do endpoint "Homologar entrega", seguindo a mesma estrutura de envio do endpoint de upload de arquivo. Caso o arquivo esteja assinado pelo responsável do envio e íntegro o envio é alterado para o status HOMOLOGADO.
SLP - Sigla do Layout Pai
MES - Mês de Referência
ANO - Ano de Referência
ID - Identificador da prestação de contas recebido como retorno do envio de dados realizado com sucesso
Observação: OS DADOS ENVIADOS DEVERÃO ESTAR CODIFICADOS NO FORMATO UTF-8.
O sistema de Recepção permite que o layout contenha o recebimento de arquivos em sua especificação. O envio de arquivos, entretanto, será realizado através de um endpoint próprio para o recebimento de todos os arquivos. Dessa forma, para informar um arquivo em uma prestação de contas, o jurisdicionado deverá enviar primeiramente o arquivo no endpoint que retornará um identificador (tipo STRING) que deverá ser informado no respectivo campo do layout.
Caso não sejam imagens, antes do envio os arquivos deverão ser assinados digitalmente no formato P7S (PKCS7) ou PDFs assinados. Para assiná-los poderá ser utilizado o assinador desenvolvido pelo tribunal ou qualquer outro programa que realize a assinatura mantendo um único arquivo assinado envelopando o conteúdo. Não será aceito assinatura apenas do HASH do arquivo.
Arquivos PDF/A poderão ser enviados via upload porém, dependendo do tipo de formato associado, a validação do PDF/A é aplicada no momento da recepção das informações de um determinado layout. Caso necessite converter seu PDF para PDF/A, clique aqui.
Arquivos de imagens poderão ser enviados nos formatos PNG e JPEG com o tamanho máximo de 512kb sem a necessidade de assiná-los (gerando um arquivo P7S).
Ao enviar informações de um determinado layout no COLARE, possivelmente estará associado um ou mais arquivos, conforme vimos na seção anterior. Esses arquivos, quando vinculados a uma entrega já persistida no COLARE, poderão, porteriormente ao envio, serem baixados através do endpoint do sistema de envio manual.
Os sistemas que compõem a plataforma Colare estão disponíveis em ambiente próprio para os desenvolvedores realizarem testes de integração.
Chamado de ambiente TESTES, os serviços que estão disponíveis neste ambiente são acessíveis pelos mesmos endereços dos serviços em produção, alterando o domínio de terceiro nível de "virtual" para "testes":
*O endpoint de "Homologar Entrega" deverá ser utilizado para realizar a homologação através do envio do PDF de homologação assinado digitalmente pelo responsável do envio. O arquivo PDF pode ser obtido através do endpoint "Obter PDF de homologação do envio", assinado e posteriormente enviado através do endpoint "Homologar entrega", seguindo a mesma estrutura de envio do endpoint de upload de arquivo. Caso o arquivo esteja assinado pelo responsável do envio e íntegro o envio é alterado para o status HOMOLOGADO.
No ambiente Testes, os requisitos referentes à autenticação e às permissões continuam válidos como demonstrado no tópico anterior.
Entretanto, os desenvolvedores precisarão de cadastros específicos para o ambiente Testes que deverão ser solicitados ao TCMGO, através do Ticket, conforme descrito abaixo.
Abertura de solicitação de cadastro pelo Ticket no Ambiente TESTES
Deverá ser informado no título:
Na descrição:
Após a solicitação, o usuário será cadastrado em uma representação e as informações serão repassadas através do chamado aberto, que deverá ser acompanhado pelo solicitante.
Endpoints de representação no ambiente TESTES
A plataforma COLARE foi arquitetada para que houvesse integração entre os sistemas de gestão das unidades jurisdicionadas com o TCMGO, visando o envio sistematizado das informações. Objetivando facilitar o entendimento dessas integrações para as áreas técnicas envolvidas, essa seção evidenciará exemplos de como poderá ser feita essas integrações, o formato dos dados enviados e o formado das mensagens de retorno. Qualquer sugestão de conteúdo poderá ser feita através do Ticket.
Alguns campos dos layouts são especificos para envio de arquivos como, por exemplo, o idDocumentoPDF do layout de LICITAÇÃO FASE 1 que é referente ao EDITAL da licitação. Para enviar o arquivo de EDITAL ao invés de embarcá-lo na estrutura do JSON, que oneraria o envio das informações, primeiramente é necessário enviar o arquivo num endpoint próprio para upload de arquivos. Ao submeter o arquivo para o tribunal é gerado um identificador que será utilizado para compor o layout da LICITAÇÃO FASE 1, fazendo assim, a amarração do layout com o arquivo enviado.
Os arquivos a serem enviadas deverão ter, no máximo, 10MB. Caso esteja tentando enviar um arquivo PDF maior que o permitido, utilize a ferramenta I LOVE PDF para comprimi-lo.
POST /recepcao/arquivo/upload HTTP/1.1 Host: virtual.tcm.go.gov.br Authorization: eyJhbGciOiJIUzUxMiJ9... cache-control: no-cache Content-Disposition: form-data; name="arquivo"; filename="C:\EDITAL.pdf.pdf
curl -X POST \ https://virtual.tcm.go.gov.br/recepcao/arquivo/upload \ -H 'Authorization: eyJhbGciOiJIUzUxMiJ9...' \ -H 'cache-control: no-cache' \ -H 'content-type: multipart/form-data' \ -F 'arquivo=@C:\EDITAL.pdf.pdf'
import org.apache.http.HttpResponse; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpPost import org.apache.http.entity.mime.MultipartEntity import org.apache.http.entity.mime.content.FileBody; import org.apache.http.impl.client.DefaultHttpClient; HttpClient client = new DefaultHttpClient(); HttpPost post = new HttpPost("https://virtual.tcm.go.gov.br/recepcao/arquivo/upload"); post.setHeader("Authorization", "eyJhbGciOiJIUzUxMiJ9...") MultipartEntity entity = new MultipartEntity(); entity.addPart("arquivo", new FileBody(new File("C:\\EDITAL.pdf"))); post.setEntity(entity); HttpResponse response = client.execute(post);
<?php $request = new HttpRequest(); $request->setUrl('https://virtual.tcm.go.gov.br/recepcao/arquivo/upload'); $request->setMethod(HTTP_METH_POST); $request->setHeaders(array( 'Authorization' => 'eyJhbGciOiJIUzUxMiJ9...', 'content-type' => 'multipart/form-data' )); $request->addPostFile('arquivo', 'c:\edital.pdf') try { $response = $request->send(); echo $response->getBody(); } catch (HttpException $ex) { echo $ex; }
Ao enviar o arquivo para o endpoint de upload é gerada uma mensagem de retorno. No exemplo de retorno abaixo vemos que o identificador gerado para o arquivo enviado é e3f6a262-84a8-4cc4-9960-52ba863cbe94 e que o arquivo foi assinador pelo JOÃO DA SILVA SAURO na data 1544124396000 (Quinta-feira, 6 de dezembro de 2018 às 17:26:36 GMT-02:00 DST, conforme conversão realizada no site https://www.epochconverter.com/).
e3f6a262-84a8-4cc4-9960-52ba863cbe94
1544124396000
{ "arquivo": "e3f6a262-84a8-4cc4-9960-52ba863cbe94", "signatarios": [ { "nome": "JOÃO DA SILVA SAURO", "cpf": "999999999", "data": 1544124396000 } ] }
Se ao enviar o arquivo para o tribunal foi utilizado um Token inválido ou expirado (o token expira todos os dias às 23:59, é recomendável que a implementação dos sistemas trate automaticamente os casos de expiração do token), a seguinte mensagem é retornada:
{ "message": "O Token enviado é inválido! Para maiores informações acesse: https://testes.tcm.go.gov.br/colare-doc" }
Caso o arquivo enviado não seja PDF ou P7S, a seguinte mensagem é retornada:
{ "message": "Só será aceito arquivos do tipo application/pdf ou application/pkcs7-signature" }
Ao enviar um arquivo não assinado digitalmente, a seguinte mensagem é retornada:
{ "message": "Arquivo enviado não está assinado digitalmente!" }
Conforme orientado na seção 1.4.4.3, cada layout terá um conjunto de endpoins de manutenção para enviar, alterar, excluir, obter e validar os dados. Além desses endpoints de manutenção, existe um outro que serve para gerar o schema json utilizado na validação da estrutura de dados. Cada layout tem sua estrutura própria de dados e essa estrutura pode ser consultada no menu Prestação de Contas -> Layouts ou através do schema json. Abaixo segue um exemplo de como será enviado o layout de regulamentação dos procedimentos licitatórios:
POST /recepcao/LIC/REG_LICITACAO/2/2019 HTTP/1.1 Host: virtual.tcm.go.gov.br Content-Type: application/json Authorization: eyJhbGciOiJIUzUxMiJ9... cache-control: no-cache { "detalhamentoLc123": { "regulamentouParticipExclusivaMEEPP": true, "artigoRegulamentouParticipExclusivaMEEPP": "25", "valorLimiteRegParticipExclusivaMEEPP": 50000, "regulamentouProcSubContratacaoMEEPP": true, "artigoProcSubContratacaoMEEPP": "26", "percentualSubContratacaoMEEPP": 5.5, "regulamentouCriteriosEmpenhoPagamentoMEEPP": false, "regulamentouPercObjetoContratacaoMEEPP": false }, "codTipoRegulamentacao": 1, "existeRegulamentacaoMunicipal": true, "numeroDecretoMunicipal": "659", "dataDecretoMunicipal": "2019-01-01", "dataPublicacao": "2019-01-02", "codTipoEnvio": 1, "idDocumentoPDF": "29f5882c-1188-4be6-9d16-b56d959e3518" }
curl -X POST \ https://virtual.tcm.go.gov.br/recepcao/LIC/REG_LICITACAO/2/2019 \ -H 'Authorization: eyJhbGciOiJIUzUxMiJ9...' \ -H 'Content-Type: application/json' \ -H 'cache-control: no-cache' \ -d '{ "detalhamentoLc123": { "regulamentouParticipExclusivaMEEPP": true, "artigoRegulamentouParticipExclusivaMEEPP": "25", "valorLimiteRegParticipExclusivaMEEPP": 50000, "regulamentouProcSubContratacaoMEEPP": true, "artigoProcSubContratacaoMEEPP": "26", "percentualSubContratacaoMEEPP": 5.5, "regulamentouCriteriosEmpenhoPagamentoMEEPP": false, "regulamentouPercObjetoContratacaoMEEPP": false }, "codTipoRegulamentacao": 1, "existeRegulamentacaoMunicipal": true, "numeroDecretoMunicipal": "659", "dataDecretoMunicipal": "2019-01-01", "dataPublicacao": "2019-01-02", "codTipoEnvio": 1, "idDocumentoPDF": "29f5882c-1188-4be6-9d16-b56d959e3518" }'
import org.apache.http.HttpResponse; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.StringEntity; import org.apache.http.entity.mime.MultipartEntity; import org.apache.http.entity.mime.content.FileBody; import org.apache.http.impl.client.DefaultHttpClient; HttpClient client = new DefaultHttpClient(); HttpPost post = new HttpPost("https://virtual.tcm.go.gov.br/recepcao/LIC/REG_LICITACAO/2/2019"); post.setHeader("Authorization", "eyJhbGciOiJIUzUxMiJ9...") String json = "{\r\n \"detalhamentoLc123\": {\r\n \"regulamentouParticipExclusivaMEEPP\": true,\r\n \"artigoRegulamentouParticipExclusivaMEEPP\": \"25\",\r\n \"valorLimiteRegParticipExclusivaMEEPP\": 50000,\r\n \"regulamentouProcSubContratacaoMEEPP\": true,\r\n \"artigoProcSubContratacaoMEEPP\": \"26\",\r\n \"percentualSubContratacaoMEEPP\": 5.5,\r\n \"regulamentouCriteriosEmpenhoPagamentoMEEPP\": false,\r\n \"regulamentouPercObjetoContratacaoMEEPP\": false\r\n },\r\n \"codTipoRegulamentacao\": 1,\r\n \"existeRegulamentacaoMunicipal\": true,\r\n \"numeroDecretoMunicipal\": \"659\",\r\n \"dataDecretoMunicipal\": \"2019-01-01\",\r\n \"dataPublicacao\": \"2019-01-02\",\r\n \"codTipoEnvio\": 1,\r\n \"idDocumentoPDF\": \"29f5882c-1188-4be6-9d16-b56d959e3518\",\r\n}"; StringEntity stringEntity = new StringEntity(json); stringEntity.setContentType("application/json"); post.setEntity(stringEntity); HttpResponse response = client.execute(post);
<?php $request = new HttpRequest(); $request->setUrl('https://virtual.tcm.go.gov.br/recepcao/LIC/REG_LICITACAO/2/2019'); $request->setMethod(HTTP_METH_POST); $request->setHeaders(array( 'Authorization' => 'eyJhbGciOiJIUzUxMiJ9...', 'Content-Type' => 'application/json' )); $request->setBody('{ "detalhamentoLc123": { "regulamentouParticipExclusivaMEEPP": true, "artigoRegulamentouParticipExclusivaMEEPP": "25", "valorLimiteRegParticipExclusivaMEEPP": 50000, "regulamentouProcSubContratacaoMEEPP": true, "artigoProcSubContratacaoMEEPP": "26", "percentualSubContratacaoMEEPP": 5.5, "regulamentouCriteriosEmpenhoPagamentoMEEPP": false, "regulamentouPercObjetoContratacaoMEEPP": false }, "codTipoRegulamentacao": 1, "existeRegulamentacaoMunicipal": true, "numeroDecretoMunicipal": "659", "dataDecretoMunicipal": "2019-01-01", "dataPublicacao": "2019-01-02", "codTipoEnvio": 1, "idDocumentoPDF": "29f5882c-1188-4be6-9d16-b56d959e3518" }'); try { $response = $request->send(); echo $response->getBody(); } catch (HttpException $ex) { echo $ex; }
Ao enviar os dados de um determinado layout para o tribunal é gerada uma mensagem de retorno evidenciando se os dados foram recepcionados ou se houve algum tipo de erro/falha que impediu sua recepção. Segue abaixo os possíveis retornos.
Quando a estrutura dos dados do layout é informada de forma correta, é retornada a seguinte mensagem:
{ "arquivo": { "id": 505, "ano": 2019, "mes": 2, "idRepresentacao": 830, "jsonNode": { "detalhamentoLc123": { "regulamentouParticipExclusivaMEEPP": true, "artigoRegulamentouParticipExclusivaMEEPP": "25", "valorLimiteRegParticipExclusivaMEEPP": 50000, "regulamentouProcSubContratacaoMEEPP": true, "artigoProcSubContratacaoMEEPP": "26", "percentualSubContratacaoMEEPP": 5.5, "regulamentouCriteriosEmpenhoPagamentoMEEPP": false, "regulamentouPercObjetoContratacaoMEEPP": false }, "codTipoRegulamentacao": 1, "existeRegulamentacaoMunicipal": true, "numeroDecretoMunicipal": "659", "dataDecretoMunicipal": "2019-01-01", "dataPublicacao": "2019-01-02", "codTipoEnvio": 1, "idDocumentoPDF": "29f5882c-1188-4be6-9d16-b56d959e3518" }, "recibo": "e90ff07d-8b7c-4c87-9347-5bb803d977b5", "statusEnvio": "NAO_HOMOLOGADO", "arquivoHomologacao": null, "layoutSigla": "REG_LICITACAO", "prestacaoDeContasSigla": "LIC" }, "mensagens": { "advertencias": [], "informacoes": [], "erros": [] } }
Neste retorno é importante observar as seguintes informações:
Os dados retornados no envio são os mesmos resultantes da obtenção do envio pelo ID.
Ao realizar o envio de dados para o tribunal pode acontecer de estar faltando alguma informação que compoe o layout, como no caso abaixo:
{ "detalhamentoLc123": { "regulamentouParticipExclusivaMEEPP": true, "artigoRegulamentouParticipExclusivaMEEPP": "25", "valorLimiteRegParticipExclusivaMEEPP": 50000, "regulamentouProcSubContratacaoMEEPP": true, "artigoProcSubContratacaoMEEPP": "26", "percentualSubContratacaoMEEPP": 5.5, "regulamentouCriteriosEmpenhoPagamentoMEEPP": false, "regulamentouPercObjetoContratacaoMEEPP": false } }
Nesta situação, é retornado a seguinte mensagem de erro:
[ { "level": "error", "schema": { "loadingURI": "#", "pointer": "" }, "instance": { "pointer": "" }, "domain": "validation", "keyword": "required", "message": "objeto tem as seguintes propriedades exigidas faltando ([\"codTipoEnvio\",\"codTipoRegulamentacao\",\"existeRegulamentacaoMunicipal\"])", "required": [ "codTipoEnvio", "codTipoRegulamentacao", "existeRegulamentacaoMunicipal" ], "missing": [ "codTipoEnvio", "codTipoRegulamentacao", "existeRegulamentacaoMunicipal" ] } ]
Neste retorno, é importante enfatizar as seguintes propriedades:
Quando os dados enviados não estão adequados ao schema do layout e as informações não estão no formato esperado, como no exemplo abaixo:
{ "detalhamentoLc123": { "regulamentouParticipExclusivaMEEPP": "true", "artigoRegulamentouParticipExclusivaMEEPP": "25", "valorLimiteRegParticipExclusivaMEEPP": "50000", "regulamentouProcSubContratacaoMEEPP": true, "artigoProcSubContratacaoMEEPP": "26", "percentualSubContratacaoMEEPP": 5.5, "regulamentouCriteriosEmpenhoPagamentoMEEPP": false, "regulamentouPercObjetoContratacaoMEEPP": false }, "codTipoRegulamentacao": 1, "existeRegulamentacaoMunicipal": true, "numeroDecretoMunicipal": "659", "dataDecretoMunicipal": "01/01/2019", "dataPublicacao": "2019-01-02", "codTipoEnvio": 1, "idDocumentoPDF": "29f5882c-1188-4be6-9d16-b56d959e3518" }
a seguinte mensagem é retornada:
[ { "level": "error", "schema": { "loadingURI": "#", "pointer": "/properties/dataDecretoMunicipal" }, "instance": { "pointer": "/dataDecretoMunicipal" }, "domain": "validation", "keyword": "format", "attribute": "date", "message": "string \"01/01/2019\" é inválido contra o formato de data solicitado yyyy-MM-dd", "value": "01/01/2019", "expected": "yyyy-MM-dd" }, { "level": "error", "schema": { "loadingURI": "#", "pointer": "/definitions/detalhamentoLc123/properties/regulamentouParticipExclusivaMEEPP" }, "instance": { "pointer": "/detalhamentoLc123/regulamentouParticipExclusivaMEEPP" }, "domain": "validation", "keyword": "type", "message": "instância de tipo (string) não corresponde a nenhum tipo primitivo permitido ( permitido : [\"boolean\"] )", "found": "string", "expected": [ "boolean" ] }, { "level": "error", "schema": { "loadingURI": "#", "pointer": "/definitions/detalhamentoLc123/properties/valorLimiteRegParticipExclusivaMEEPP" }, "instance": { "pointer": "/detalhamentoLc123/valorLimiteRegParticipExclusivaMEEPP" }, "domain": "validation", "keyword": "type", "message": "instância de tipo (string) não corresponde a nenhum tipo primitivo permitido ( permitido : [\"integer\",\"number\"] )", "found": "string", "expected": [ "integer", "number" ] } ]
Analisando o retorno é possível perceber que:
Caso seja enviado os dados do layout contendo um identificador de arquivo inválido a seguinte mensagem é retornada:
[ { "level": "error", "schema": { "loadingURI": "#", "pointer": "/properties/idDocumentoPDF" }, "instance": { "pointer": "/idDocumentoPDF" }, "domain": "validation", "keyword": "format", "attribute": "arquivo-ged", "message": "Formato do arquivo GED inválido. O formato segue a estrutura UUID (Universally Unique IDentifier).", "value": "abcd", "expected": "UUID" } ]
Caso nas informações do layout seja informado um identificador válido de um arquivo mas ele não consta na base de dados do TCM a seguinte mensagem é retornada:
[ { "level": "error", "schema": { "loadingURI": "#", "pointer": "/properties/idDocumentoPDF" }, "instance": { "pointer": "/idDocumentoPDF" }, "domain": "validation", "keyword": "format", "attribute": "arquivo-ged", "message": "Arquivo não existente na base do GED.", "value": "29f5882c-1188-4be6-9d16-b56d959e3519" } ]
Quando uma regra de recepção não é atendida os dados não são recepcionados e as informações das regras não obedecidas são retornadas. Tomando como exemplo, vamos supor que exista uma regra que impeça que o percentual estabelecido para subcontratação de ME e EPP seja maior que 10%. Neste caso, ao enviar os dados abaixo o colare recepção barrará o envio visto que o valor informado é de 20%.
{ "detalhamentoLc123": { "regulamentouParticipExclusivaMEEPP": true, "artigoRegulamentouParticipExclusivaMEEPP": "25", "valorLimiteRegParticipExclusivaMEEPP": 50000, "regulamentouProcSubContratacaoMEEPP": true, "artigoProcSubContratacaoMEEPP": "26", "percentualSubContratacaoMEEPP": 20, "regulamentouCriteriosEmpenhoPagamentoMEEPP": false, "regulamentouPercObjetoContratacaoMEEPP": false }, "codTipoRegulamentacao": 1, "existeRegulamentacaoMunicipal": true, "numeroDecretoMunicipal": "659", "dataDecretoMunicipal": "2019-01-01", "dataPublicacao": "2019-01-02", "codTipoEnvio": 1, "idDocumentoPDF": "29f5882c-1188-4be6-9d16-b56d959e3518", "tcmEnvioManual": true }
Neste contexto, ao submeter as informações acima a seguinte mensagem de erro é retornada e os dados não são recepcionados:
{ "mensagens": { "advertencias": [], "informacoes": [], "erros": [ { "regra": 6, "mensagem": "O percentual estabelecido para subcontrtação de ME e EPP não pode ser maior que 10%." } ] } }
Caso no envio das informações ocorra alguma erro no COLARE RECEPÇÃO, ou em algum dos sitemas integrados a plataforma, será retornada uma mensagem como a abaixo:
{ "message": "mensagem do erro" }
/** * * Copyright 2019 Rodrigo Rezende * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see <https://www.gnu.org/licenses/>. */ unit classColare; /////////////////////////////////////////////////////////////////////// // // DESENVOLVIDO POR: // TCM - SINFO // Rodrigo Ribeiro Rezende // 2019-02 // Classe utilizada para conexão com o Sistema COLARE e PASSAPORTE DO TCMGO // Versão do DELPHI (XE 10.2.3) // Necessario fazer uma atualização do Windows 7 para ativar o TLS1.1 e 1.2 // https://support.microsoft.com/pt-br/help/3140245/update-to-enable-tls-1-1-and-tls-1-2-as-default-secure-protocols-in-wi // Necessário DLLs (Atualizadas) na pasta do EXE // ssleay32.dll // libeay32.dll /////////////////////////////////////////////////////////////////////// interface uses Forms, Classes, Controls, Dialogs, SysUtils, // Soap.SOAPHTTPClient, IdHTTP, IdSSLOpenSSL, IdMultipartFormData; type TColare = class private public //Obter Representações por Certificado Digital com HandShake (SSL) function getHTTP_SSL(strUrl: string): string; //Obter os Dados Enviados ao Colare function getHTTP_Token(TokenAuthorization, Url: string): string; //Enviar JSON Colare com Token function postHTTP_Token(TokenAuthorization, Url: string; JsonToSendString: string): string; //Enviar Arquivo Colare com Token function postHTTP_Token_Upload(TokenAuthorization, Url, Arquivo: string): string; end; implementation function TColare.getHTTP_SSL(strUrl: string): string; var httpRio: THTTPRIO; jsonRetorno: TStringStream; begin //Passaporte Obter Representações por Certificado Digital com HandShake (SSL) //strUrl = 'https://testes.tcm.go.gov.br:8443/passaporte/api/auth/representacoes' //Passaporte Obter Token da Representação por Certificado Digital com HandShake (SSL) //strUrl = 'https://testes.tcm.go.gov.br:8443/passaporte/api/auth/certificado?representacao=NumeroIDRepresentacao' jsonRetorno := TStringStream.Create; httpRio := THTTPRIO.Create(nil); try try httpRio.URL := strUrl; httpRio.HTTPWebNode.Get(jsonRetorno); Result := jsonRetorno.DataString; except on E: EIdHTTPProtocolException do begin raise EIdHTTPProtocolException.Create('Falha ao conectar no Colare!' + #10#13 + // 'Código: ' + IntToStr(E.ErrorCode) + #10#13 + // 'Mensagem: ' + e.Message + #10#13 + // 'Mensagem Retorno: ' + e.ErrorMessage); end; on E: Exception do raise Exception.Create('Falha ao conectar no Colare!' + #10#13 + // 'Erro geral: ' + E.Message); end; finally FreeAndNil(httpRio); FreeAndNil(jsonRetorno); end; end; function TColare.getHTTP_Token(TokenAuthorization, Url: string): string; var JsonStreamRetorno: TStringStream; idHttp: TIdHTTP; IdSSLIOHandlerSocketOpenSSL1: TIdSSLIOHandlerSocketOpenSSL; begin //Obter o JSON SCHEMA via Colare com Token //Url = 'https://testes.tcm.go.gov.br/recepcao/LIC/REG_LICITACAO/1/2019/schema' //TokenAuthorization = '' Não necessita de token //Obter os Dados Enviados ao Colare //Url = 'https://testes.tcm.go.gov.br/recepcao/LIC/REG_LICITACAO/2/2019/NumeroIDEntrega' //TokenAuthorization = 'eyJhbGciOiJIUzUxMiJ9.eyJsb2...' Token da Representação Obtido por Certificado Digital idHttp := TIdHTTP.Create(nil); IdSSLIOHandlerSocketOpenSSL1 := TIdSSLIOHandlerSocketOpenSSL.Create; JsonStreamRetorno := TStringStream.Create; try try idHttp.Request.Clear; idHttp.Request.CustomHeaders.Clear; idHttp.Request.BasicAuthentication := False; idHttp.IOHandler := IdSSLIOHandlerSocketOpenSSL1; idHttp.Request.CustomHeaders.Values['Authorization'] := TokenAuthorization; idHttp.Request.CustomHeaders.Values['Content-Type'] := 'application/json'; idHttp.Request.CustomHeaders.Values['Content-Encoding'] := 'utf-8'; idHttp.Request.Connection := 'Keep-Alive'; idHttp.Request.CacheControl := 'no-cache'; //RESPONSE idHttp.Response.ContentType := 'application/json'; idHttp.Response.ContentEncoding := 'utf-8'; idHttp.get(Url, JsonStreamRetorno); Result := JsonStreamRetorno.DataString; except on E: EIdHTTPProtocolException do begin raise EIdHTTPProtocolException.Create('Falha ao conectar no Colare!' + #10#13 + // 'Código: ' + IntToStr(E.ErrorCode) + #10#13 + // 'Mensagem: ' + e.Message + #10#13 + // 'Mensagem Retorno: ' + e.ErrorMessage); end; on E: Exception do raise Exception.Create('Falha ao conectar no Colare!' + #10#13 + // 'Erro geral: ' + E.Message); end; finally FreeAndNil(idHttp); FreeAndNil(IdSSLIOHandlerSocketOpenSSL1); FreeAndNil(JsonStreamRetorno); end; end; function TColare.postHTTP_Token(TokenAuthorization, Url: string; JsonToSendString: string): string; var sResponse: string; idHttp: TIdHTTP; IdSSLIOHandlerSocketOpenSSL1: TIdSSLIOHandlerSocketOpenSSL; JsonToSend: TStringStream; begin //Enviar JSON Colare com Token //Url = 'https://testes.tcm.go.gov.br/recepcao/LIC/REG_LICITACAO/2/2019' //TokenAuthorization = 'eyJhbGciOiJIUzUxMiJ9.eyJsb2...' Token da Representação Obtido por Certificado Digital idHttp := TIdHTTP.Create(nil); IdSSLIOHandlerSocketOpenSSL1 := TIdSSLIOHandlerSocketOpenSSL.Create; JsonToSend := TStringStream.Create(Utf8Encode(JsonToSendString)); try try idHttp.Request.Clear; idHttp.Request.CustomHeaders.Clear; idHttp.Request.BasicAuthentication := False; idHttp.IOHandler := IdSSLIOHandlerSocketOpenSSL1; TokenAuthorization := TokenAuthorization; idHttp.Request.CustomHeaders.Values['Authorization'] := TokenAuthorization; idHttp.Request.CustomHeaders.Values['Content-Type'] := 'application/json'; idHttp.Request.CustomHeaders.Values['Content-Encoding'] := 'utf-8'; idHttp.Request.Connection := 'Keep-Alive'; idHttp.Request.CacheControl := 'no-cache'; //RESPONSE idHttp.Response.ContentType := 'application/json'; idHttp.Response.ContentEncoding := 'utf-8'; sResponse := idHttp.Post(Url, JsonToSend); Result := sResponse; except on E: EIdHTTPProtocolException do begin raise EIdHTTPProtocolException.Create('Falha ao conectar no Colare!' + #10#13 + // 'Código: ' + IntToStr(E.ErrorCode) + #10#13 + // 'Mensagem: ' + e.Message + #10#13 + // 'Mensagem Retorno: ' + e.ErrorMessage); end; on E: Exception do raise Exception.Create('Falha ao conectar no Colare!' + #10#13 + // 'Erro geral: ' + E.Message); end; finally FreeAndNil(idHttp); FreeAndNil(IdSSLIOHandlerSocketOpenSSL1); FreeAndNil(JsonToSend); end; end; function TColare.postHTTP_Token_Upload(TokenAuthorization, Url, Arquivo: string): string; var JsonStreamRetorno: TStringStream; idHttp: TIdHTTP; IdSSLIOHandlerSocketOpenSSL1: TIdSSLIOHandlerSocketOpenSSL; ArquivoMultPartFormData: TIdMultipartFormDataStream; begin //Enviar Arquivo Colare com Token //Url = 'https://testes.tcm.go.gov.br/recepcao/arquivo/upload' //TokenAuthorization = 'eyJhbGciOiJIUzUxMiJ9.eyJsb2...' Token da Representação Obtido por Certificado Digital //Arquivo = 'C:\NomeArquivoAssinadoPDF-P7S' Caminho do arquivo a ser enviado idHttp := TIdHTTP.Create(nil); IdSSLIOHandlerSocketOpenSSL1 := TIdSSLIOHandlerSocketOpenSSL.Create; JsonStreamRetorno := TStringStream.Create; ArquivoMultPartFormData := TIdMultipartFormDataStream.Create; try try idHttp.Request.Clear; idHttp.Request.CustomHeaders.Clear; idHttp.Request.BasicAuthentication := False; idHttp.IOHandler := IdSSLIOHandlerSocketOpenSSL1; //Carrega o arquivo no MultPartData ArquivoMultPartFormData.AddFile('arquivo', Arquivo, 'application/octet-stream'); ArquivoMultPartFormData.AddFormField('filename', Arquivo); idHttp.Request.CustomHeaders.Values['Authorization'] := TokenAuthorization; idHttp.Request.CustomHeaders.Values['arquivo'] := Arquivo; idHttp.Request.CacheControl := 'no-cache'; idHttp.Request.ContentType := 'multipart/form-data'; idHttp.Request.ContentEncoding := 'utf-8'; //RESPONSE idHttp.Response.ContentType := 'application/json'; idHttp.Response.ContentEncoding := 'utf-8'; idHttp.Post(Url, ArquivoMultPartFormData, JsonStreamRetorno); Result := JsonStreamRetorno.DataString; except on E: EIdHTTPProtocolException do begin raise EIdHTTPProtocolException.Create('Falha ao conectar no Colare!' + #10#13 + // 'Código: ' + IntToStr(E.ErrorCode) + #10#13 + // 'Mensagem: ' + e.Message + #10#13 + // 'Mensagem Retorno: ' + e.ErrorMessage); end; on E: Exception do raise Exception.Create('Falha ao conectar no Colare!' + #10#13 + // 'Erro geral: ' + E.Message); end; finally FreeAndNil(idHttp); FreeAndNil(IdSSLIOHandlerSocketOpenSSL1); FreeAndNil(JsonStreamRetorno); end; end; end.
O TCMGO, através da Superintendência de Informática (SINFO), disponibiliza serviços de compartilhamento de dados com órgãos da administração pública e a sociedade civil. Dentre os diversos serviços disponibilizados, alguns fazem referência ao sistema Passaporte e o COLARE. Esses serviços são essenciais para mantenedores dos sistemas de gestão dos jurisdicionados pois disponibilizam informações importantes acerca da situação cadastral e adimplência dos municípios goianos em relação ao COLARE. Segue abaixo o link para os serviços:
Seção para disponibilização de ferramentas e utilitários para dar suporte a requisitos de implementação e disponibilidade de sistemas e/ou recursos necessários ao envio de informações para o TCMGO através do COLARE.
PDF/A é um formato de PDF que garante que um documento possa ser reproduzido exatamente da mesma maneira, independentemente do software utilizado. Basicamente, todas as informações necessárias para exibir o documento são incorporadas ao arquivo, deixando seus documentos seguros, acessíveis e seguros por um longo período de tempo. Abaixo segue as versões dos arquivos PDF/A e a respectiva norma que padroniza os arquivos:
A ferramenta abaixo poderá ser utilizada para verificar se um determinado arquivo PDF segue algum padrão PDF/A definido na norma.