Wednesday
Jan 26

Weather

New York, USA

21℃
  • Thursday 24
  • Friday 19
  • Saturday 15
  • Sunday 24
  • Monday 21
  • Tuesday 20

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.

Sumário

Dúvidas / Sugestões? Acesse o Ticket e abra uma demanda!

A - CONCEITOS GERAIS

1. A nova plataforma para envio de dados ao TCMGO

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.

1.1 Colare

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. 

1.2 Colare.doc

É 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:

1.3 Passaporte

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 .

1.4 Colare Recepção

É 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). 

1.5 Colare Envios

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. Utilizar o layout chamado “SOLICITACAO DE RETIFICACAO DE ENVIO HOMOLOGADO”;
  2. Informar o ID do procedimento ou do contrato que precisa ser retificado;
  3. Informar o tipo de retificação, que pode ser “alteração” ou “correção”. A diferença entre alteração e correção é que na alteração você está retificando uma informação que estava originalmente correta, mas precisa ser atualizada, pois algo novo aconteceu e alterou o estado da informação, já na correção você está retificando uma informação cadastrada originalmente errada, mas agora você vai cadastrar a informação correta.
  4. Informar o motivo pelo qual a informação precisa ser retificada, descrevendo as circunstâncias que caracterizam a necessidade de retificação.
  5. Enviar e homologar o envio do layout “SOLICITACAO DE RETIFICACAO DE ENVIO HOMOLOGADO” preenchido. Nesse ponto, o sistema permitirá a correção de um envio homologado.
  6. Em seguida, proceder com a retificação da remessa cujo ID foi informado na solicitação de retificação, informando o “Tipo de Envio” (“Alteração” ou “Correção”) e o “Motivo da atualização ou correção” (o que está sendo alterado).
  7. Homologar o envio retificado.

1.5.2.2 Prestações de contas Atos de Pessoal e Folha de Pagamento: 

Depois de homologados, os envios podem ser retificados da seguinte forma:

  1. A partir do sistema de gestão de uso no municípío, fazer um envio do layout “SOLICITACAO DE RETIFICACAO DE ENVIO HOMOLOGADO - PESSOAL” (em caso de dúvida, procurar o suporte do sistema de gestão); 
  2. Informar o ID do procedimento ou do contrato que precisa ser retificado;
  3. Informar o tipo de retificação, que pode ser “alteração” ou “correção”. A diferença entre alteração e correção é que na alteração você está retificando uma informação que estava originalmente correta, mas precisa ser atualizada, pois algo novo aconteceu e alterou o estado da informação, já na correção você está retificando uma informação cadastrada originalmente errada, mas agora você vai cadastrar a informação correta.
  4. Informar o motivo pelo qual a informação precisa ser retificada, descrevendo as circunstâncias que caracterizam a necessidade de retificação. Informar também o "Detalhamento da Situação", conforme os valores pré-definidos. E, caso possua, anexar o documento contendo justificativa da correção.
  5. Enviar e homologar o envio do layout “SOLICITACAO DE RETIFICACAO DE ENVIO HOMOLOGADO - PESSOAL” preenchido.
  6. Após o envio da solicitação, ela será avaliada e autorizada pela área responsável no Tribunal. Excepcionalmente até 31/10/2020, todas as solicitações são automaticamente aprovadas.
  7. Após a aprovação, o sistema permitirá a correção de um envio homologado.
  8. Em seguida, proceder com a retificação da remessa cujo ID foi informado na solicitação de retificação, informando o “Tipo de Envio” (“Alteração” ou “Correção”) e o “Motivo da atualização ou correção” (o que está sendo alterado).
  9. Homologar o envio retificado.

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. 

B - INFORMAÇÕES AOS JURISDICIONADOS

Abaixo seguem algumas mídias inerentes ao projeto.

1. Cursos da plataforma COLARE / PASSAPORTE

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.

1.1 TURMA I - 11/02/2019

1.2 TURMA II - 12/02/2019

1.3 TURMA III - 18/02/2019

1.4 TURMA IV - 19/02/2018

C - INFORMAÇÕES AOS DESENVOLVEDORES (API)

 

1. A arquitetura e integração do Colare com os sistemas de gestão dos municípios

1.1 REST

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:

  • Um protocolo cliente/servidor sem estado (HTTP): cada mensagem HTTP contém toda a informação necessária para compreender o pedido. Como resultado, nem o cliente e nem o servidor necessitam gravar nenhum estado das comunicações entre mensagens.
  • Um conjunto de operações bem definidas que se aplicam a todos os recursos de informação: HTTP em si define um pequeno conjunto de operações, as mais importantes são POST, GET, PUT e DELETE. Com frequência estas operações são combinadas com operações CRUD para a persistência de dados, onde POST não se encaixa exatamente neste esquema.
  • Uma sintaxe universal para identificar os recursos. No sistema REST, cada recurso é unicamente direcionado através da sua URI.
  • O uso de hipermídia, tanto para a informação da aplicação como para as transições de estado da aplicação: a representação deste estado em um sistema REST são tipicamente XML/JSON. Como resultado disto, é possível navegar com um recurso REST a muitos outros, simplesmente seguindo ligações sem requerer o uso de registros ou outra infraestrutura adicional.

1.2 JSON

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:

  1. Uma coleção de pares nome/valor. Em várias linguagens, isto é caracterizado como um object, record, struct, dicionário, hash table, keyed list, ou arrays associativas.
  2. Uma lista ordenada de valores. Na maioria das linguagens, isto é caracterizado como uma array, vetor, lista ou sequência.

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"
}

1.3 Endpoints

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.

1.3.1 Token do Passaporte de Produção (https://wwws.tcm.go.gov.br)

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: 

  • No primeiro passo, o usuário faz a requisição a URI abaixo, juntamente com seu certificado digital e-CPF, pois o recurso necessita de uma autenticação mútua entre o servidor e o cliente:
OPERAÇÃO MÉTODO HTTP ENDPOINT
Obter lista de representações GET https://wwws.tcm.go.gov.br/passaporte/api/auth/representacoes
  • Em resposta a requisição acima, o usuário recebe a estrutura abaixo, que contém as representações que o usuário possui no Passaporte:
{
    "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"
        }
    ]
}
  • No segundo passo o usuário envia nova requisição, passando a representação desejada como parâmetro na URI, conforme exemplo abaixo:
OPERAÇÃO MÉTODO HTTP ENDPOINT
Obter token GET https://wwws.tcm.go.gov.br/passaporte/api/auth/certificado?representacao=21
  • Após a requisição acima será retornada a seguinte estrutura para o requerente:
{
    "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:

GET /recepcao/LC1/RPR/1/2017/1 HTTP/1.1
Host: virtual.tcm.go.gov.br
Content-Type: application/json
Authorization: eyJhbGciOiJIUzUxM....Q4-tuHg

 

1.3.2 Endpoints para manutenção e obtenção de dados

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: 

OPERAÇÃO MÉTODO HTTP NECESSITA DE TOKEN? ENDPOINT
Enviar dados de uma prestação de contas POST SIM https://virtual.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}
Alterar dados de uma prestação de contas PUT SIM https://virtual.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}/{ID}
Excluir dados de uma prestação de contas DELETE SIM https://virtual.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}/{ID}
Obter o JSON enviado anteriormente GET SIM https://virtual.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}/{ID}
Obter o JSON SCHEMA do layout vigente GET NÃO https://virtual.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}/schema
Validar o JSON da prestação de contas POST NÃO https://virtual.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}/validar-schema
Validar e obter dados do recibo  GET NÃO https://virtual.tcm.go.gov.br/recepcao/validar-recibo/{RECIBO}
Obter PDF de homologação do envio GET NÃO https://virtual.tcm.go.gov.br/envio-manual/api/envio/pdf/homologacao/{RECIBO}
Homologar entrega¹ PUT NÃO https://virtual.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}/{ID}/homologar

¹ 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.

  • SPC - Sigla da Prestação de Contas

  • 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.

1.3.3 Endpoint para envio de arquivos

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

OPERAÇÃO MÉTODO HTTP NECESSITA DE TOKEN? ENDPOINT
Enviar arquivo pra o GED do TCMGO POST SIM https://virtual.tcm.go.gov.br/recepcao/arquivo/upload

1.3.4 Endpoint para download de arquivo

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.

OPERAÇÃO MÉTODO HTTP NECESSITA DE TOKEN? ENDPOINT
Obter arquivo enviado GET NÃO https://virtual.tcm.go.gov.br/envio-manual/api/envio/pdf/anexo/{RECIBO-DO-ENVIO}/{ID-ARQUIVO-GERADO-NO-UPLOAD}
  • RECIBO-DO-ENVIO: Recibo gerado no do envio.
  • ID-ARQUIVO-GERADO-NO-UPLOAD: Identificador do arquivo gerado no upload.

1.4 Ambiente para testes de integração

1.4.1 O ambiente TESTES

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": 

OPERAÇÃO MÉTODO HTTP NECESSITA DE TOKEN? ENDPOINT
Enviar dados de uma prestação de contas POST SIM https://testes.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}
Alterar dados de uma prestação de contas PUT SIM https://testes.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}/{ID}
Excluir dados de uma prestação de contas DELETE SIM https://testes.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}/{ID}
Obter o JSON enviado anteriormente GET SIM https://testes.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}/{ID}
Obter o JSON SCHEMA do layout vigente GET NÃO https://testes.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}/schema
Validar o JSON da prestação de contas POST NÃO https://testes.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}/validar-schema
Validar e obter dados do recibo  GET NÃO https://testes.tcm.go.gov.br/recepcao/validar-recibo/{RECIBO}
Obter PDF de homologação do envio GET NÃO https://testes.tcm.go.gov.br/envio-manual/api/envio/pdf/homologacao/{RECIBO}
Homologar entrega* PUT NÃO https://testes.tcm.go.gov.br/recepcao/{SPC}/{SLP}/{MES}/{ANO}/{ID}/homologar

*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.

1.4.2 Token do Passaporte no AMBIENTE DE TESTES (https://testes.tcm.go.gov.br:8443/passaporte):

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:

  • SOLICITAÇÃO DE REPRESENTAÇÃO NO PASSAPORTE - AMBIENTE TESTES

Na descrição: 

  • CPF da pessoa que será cadastrada como representante no Passaporte (necessário o solicitante ter um certificado e-CPF);
  • RG;
  • Nome;
  • Município e unidade em que trabalha, no caso de desenvolvimento próprio, ou empresa fornecedora de solução de TI, no caso de empresas que oferecem serviços de TI a jurisdicionados do TCMGO;
  • E-mail;
  • Telefone fixo;
  • Celular;

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

OPERAÇÃO MÉTODO HTTP ENDPOINT
Obter lista de representações GET https://testes.tcm.go.gov.br:8443/passaporte/api/auth/representacoes
Obter token GET https://testes.tcm.go.gov.br:8443/passaporte/api/auth/certificado?representacao={numero da representação}

 

2. Exemplos de integração

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.

2.1 UPLOAD DE ARQUIVOS

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.

2.1.1 EXEMPLO DE CHAMADA HTTP

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

2.1.2 UTILIZANDO O CURL

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'

2.1.2 UTILIZANDO O JAVA

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);

2.1.3 UTILIZANDO O PHP

<?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;
}

2.1.4 RETORNO

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/).

{
    "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!"
}

2.2 ENVIO DE DADOS REFERENTES AOS LAYOUTS

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:

2.2.1 EXEMPLO DE CHAMADA HTTP

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"
}

1.2.2.2 UTILIZANDO O CURL

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"
}'

2.2.3 UTILIZANDO O JAVA

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);

2.2.4 UTILIZANDO O PHP

<?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;
}

2.2.5 RETORNO

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.

2.2.5.1 DADOS ENVIADOS COM SUCESSO

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:

CAMPO PATH DESCRIÇÃO
ID arquivo.id O ID é o identificador único do envio e poderá ser utilizada em momentos futuros, como, por exemplo, um layout que exige a informação do identificador de um envio anterior. Também é utilizado nos endpoins de manutenção nas operações de obter, alterar ou excluir um envio.
REPRESENTAÇÃO arquivo.idRepresentacao Esse campo evidencia quem foi o responsável por enviar a informação para o tribunal.
DADOS ENVIADOS arquivo.jsonNode São os dados que foram enviados para o tribunal e são devolvidos ao cliente embarcados numa estrutura de metainformações do envio.
RECIBO arquivo.recibo Essa informação deverá ser utilizada para validar a entrega junto ao tribunal componendo a seguinte URL: https://testes.tcm.go.gov.br/recepcao/validar-recibo/RECIBO.
STATUS DO ENVIO arquivo.statusEnvio Esse campo pode assumir dois valores: HOMOLOGADO e NAO_HOMOLOGADO. Evidencia se o envio foi homologado ou não. Logo após o envio das informações ao tribunal logicamente que o envio não estará homologado, visto que não se envia e homologa os dados numa única operação. Na seção 1.5 é evidenciado o procedimento de homologação das entregas.
ARQUIVO DE HOMOLOGAÇÃO arquivo.arquivoHomologacao Quando o envio está homologado, é evidenciado o identificador do arquivo de homologação.
SIGLA DO LAYOUT arquivo.siglaLayout Sigla do layout correspondente ao envio.
SIGLA DA PRESTAÇÃO DE CONTAS arquivo.prestacaoDeContasSigla Sigla da prestaçaõ de contas correspondente ao envio.
MENSAGENS DE ADVERTÊNCIAS mensagens.advertencias Lista das mensagens de advertência referentes ao envio. Será utilizada pelo tribunal para advertir o jurisdicionado quanto a possíveis ocorrencias de futuros erros.
MENSAGENS INFORMATIVAS mensagens.informativas Lista das mensagens informativas referentes ao envio. Será utilizada pelo tribunal para informar o jurisdicionado quanto a possíveis mudanças no envio das informações ou aplicação de novas regras.
MENSAGENS DE ERRO mensagens.erros Lista das mensagens de erro. Quando preenchidas as informações não são recepcionadas.

Os dados retornados no envio são os mesmos resultantes da obtenção do envio pelo ID.

2.2.5.2 DADOS NÃO ADERENTES AO SCHEMA - FALTANDO INFORMAÇÕES

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:

CAMPO PATH DESCRIÇÃO
MENSAGEM [].message Mensagem informando as propriedades que são obrigatórias e não foram enviadas;
CAMPOS REQUERIDOS [].required Lista das propriedades que são requeridas, ou seja, obrigatórias;
CAMPOS FALTANDO [].missing Lista das propriedades que são requeridas e não foram enviadas;
2.2.5.3 DADOS NÃO ADERENTES AO SCHEMA - FORMATO DE DADOS INVÁLIDO

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"
        ]
    }
]
CAMPO PATH DESCRIÇÃO
PONTO DO ERRO NO SCHEMA [].schema.pointer Ponto no qual o erro ocorreu tendo como base o layout pai
PONTO DO ERRO NA INSTÂNCIA [].instance.pointer Ponto no qual o erro ocorreu tendo como base o layout filho
DOMÍNIO [].domain Domínio do erro, que, na maioria dos casos, é o processo de validação
CHAVE [].keyword Processo de validação que ocasionou o erro: type ou format
FORMATO [].attribute Identificador do formato esperado para o dado (apenas em erros de formato)
MENSAGEM [].message Mensagem descrevendo o erro de validação
VALOR INFORMADO [].value Valor informado no ponto de erro do esquema (apenas em erros de formato)
TIPO INFORMADO [].found Descrição do tipo de dados informado no ponto de erro no schema
TIPO DE DADOS / FORMATO ESPERADO [].expected Informa o tipo de dados ou o formato esperado no ponto de erro

Analisando o retorno é possível perceber que:

  1. A data do decreto municipal não está no formado esperado: AAAA-MM-DD;
  2. A informação que identifica se o município regulamentou procedimentos para participação exclusiva de ME e EPP que deveria ser booleana (true ou false), veio no formado de string;
  3. O valor limite da regulamentação da participação exclusiva de ME e EPP que deveria ser numérica está no formato de string;
2.2.5.4 DADOS NÃO ADERENTES AO SCHEMA - IDENTIFICADOR DO ARQUIVO INVÁLIDO

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"
    }
]
2.2.5.5 DADOS NÃO ADERENTES AO SCHEMA - ARQUIVO NÃO ENCONTRADO

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"
    }
]
2.2.5.6 ENVIO BARRADO POR REGRAS DE RECEPÇÃO

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%."
            }
        ]
    }
}
2.2.5.7 ENVIO BARRADO POR ERROS INTERNOS (DESCONHECIDOS)

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"
}

2.3 Exemplo em Delphi

/**
*
*    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.

3. Serviços de consulta

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:

4. Multimídia

4.1 Modelo de Dados representativo de Layouts / Campos / Regras

4.2 Visão de componentes arquitetural da solução

4.3 Diagrama de Sequência demonstrando o envio de dados

 

3.4 Diagrama de Sequência demonstrando o envio de dados com erros

D - FERRAMENTAS

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.

1 - VALIDADOR DE PDF/A

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:

  • PDF/A 1A - ISO 19005-1,
  • PDF/A 1B - ISO 19005-1,
  • PDF/A 2A - ISO 19005-2,
  • PDF/A 2B - ISO 19005-2,
  • PDF/A 2U - ISO 19005-2,
  • PDF/A 3A - ISO 19005-3,
  • PDF/A 3B - ISO 19005-3,
  • PDF/A 3U - ISO 19005-3,

A ferramenta abaixo poderá ser utilizada para verificar se um determinado arquivo PDF segue algum padrão PDF/A definido na norma.


Última atualização em 26/05/2022 15:43:02