Skip to main content

Informações Gerais Conjunto de APIs

Apresenta informações gerais para gerenciamento de envios de dados para o SAGRES Captura.

gptonline.ai

SAGRES Captura 2.0

Resumo Técnico, Documental e Funcional da API
Versão da API 1.0.0 Versão deste documento 1.0 Situação Documento base para versionamento Licença Apache 2.0 Suporte SAGRES suportesagres@tce.pb.gov.br Data de emissão 14 de julho de 2026

Controlo de Versões

Versão Data Autor/Responsável Descrição Estado 1.0 14/07/2026 Equipa de Integração Criação do documento base consolidado. Inicial
Qualquer alteração funcional, contratual ou de schema deve gerar nova entrada no controlo de versões e atualização do número da versão documental.

Sumário

    Objetivo e escopo Visão geral da solução Autenticação e segurança Ciclo funcional de um envio Catálogo de endpoints Entidades suportadas Requisitos de integração Regras operacionais Glossário Referências

    1. Objetivo e Escopo

    Este documento consolida, em formato técnico, documental e funcional, as principais informações da API SAGRES Captura 2.0. Serve como referência para desenvolvimento, integração, sustentação, testes, auditoria e gestão de versões.

    O escopo cobre autenticação, criação e consulta de envios, transmissão de entidades, anexos, validações e consulta de agregados. Os detalhes de respostas HTTP foram omitidos, mantendo-se a identificação e a finalidade de cada endpoint.

    2. Visão Geral da Solução

    O SAGRES Captura 2.0 disponibiliza APIs REST para gerenciamento de envios de dados ao Tribunal de Contas do Estado da Paraíba. A solução cobre abertura do envio, transmissão de dados, associação de documentos, validação e consulta dos resultados.

      Formato predominante: JSON. Transporte: HTTPS. Autenticação: OAuth2 com Bearer Token. Documentação: OpenAPI. Licença: Apache 2.0.

      3. Autenticação e Segurança

      Os tokens de acesso são obtidos através do fluxo de credenciais OAuth2 e devem ser enviados em todas as chamadas protegidas.

      Authorization: Bearer {access_token}

      Exemplo em cURL:

      curl -X GET   -H 'Authorization: Bearer <ACCESS_TOKEN>'   -H 'Content-Type: application/json'   https://api.sagrescaptura.tce.pb.gov.br/envios

      O token também determina a Unidade Gestora vinculada às operações, conforme as permissões atribuídas.

      4. Ciclo Funcional de um Envio

      Etapa Operação Descrição 1 Autenticar Obter token OAuth2 válido. 2 Criar envio Abrir envio para o tipo e competência definidos. 3 Transmitir entidades Enviar os dados conforme o JSON Schema. 4 Anexar documentos Carregar ficheiros vinculados ao protocolo, quando aplicável. 5 Iniciar validação Solicitar processamento assíncrono. 6 Consultar validação Acompanhar o resultado por protocolo e chave. 7 Consultar agregados Obter a consolidação das entidades processadas.

      5. Catálogo de Endpoints

      POST/envios

      Criar envio

      Cria e abre um registo de envio de acordo com o tipo e a competência. A Unidade Gestora é determinada pelo token.

      Parâmetros: tipoEnvio e competencia.

      GET/envios/{protocoloEnvio}

      Consultar envio por protocolo

      Obtém os dados de um envio a partir do respetivo protocolo.

      GET/envios/{codigoUnidadeGestora}/{tipoEnvio}/{competencia}

      Consultar envio por Unidade Gestora, tipo e competência

      Localiza um envio utilizando a Unidade Gestora, o tipo de envio e a competência.

      DELETE/envios/{protocoloEnvio}

      Eliminar envio

      Elimina o envio e todos os dados associados ao protocolo.

      Endpoint temporário, destinado ao período de integração.
      POST/envios/{protocoloEnvio}/{entidade}

      Enviar informações de uma entidade

      Recebe e processa dados de uma entidade vinculada ao envio. O corpo deve obedecer ao JSON Schema específico.

      POST/envios/{protocoloEnvio}/validacoes

      Iniciar validação

      Solicita a validação do envio e adiciona o processamento a uma fila, gerando uma chave de validação.

      GET/envios/{protocoloEnvio}/validacoes

      Consultar resultado das validações

      Obtém o resultado da última validação ou de uma validação específica através de chaveValidacao.

      GET/envios/{protocoloEnvio}/validacoes/agregados

      Consultar agregados

      Obtém o agregado das entidades processadas na última validação ou numa validação específica.

      GET/envios/{protocoloEnvio}/anexos

      Listar anexos

      Lista os anexos vinculados ao envio identificado pelo protocolo.

      POST/envios/{protocoloEnvio}/anexos

      Carregar anexo

      Realiza o upload de um ficheiro associado ao envio usando multipart/form-data.

      6. Entidades Suportadas

      Grupo funcional Entidades Planeamento e orçamento ACAO, PROGRAMA, UNIDADE_ORCAMENTARIA, DOTACAO, RECEITA_PREVISTA, RECEITA_ORCAMENTARIA, ATUALIZACAO_ORCAMENTARIA, DECRETO_OFICIO Execução da despesa EMPENHO, ESTORNO_EMPENHO, LIQUIDACAO, ESTORNO_LIQUIDACAO, PAGAMENTO, ESTORNO_PAGAMENTO, RETENCAO, ESTORNO_RETENCAO Cadastros e apoio CONTA_BANCARIA, CONTA_BANCARIA_CREDOR, CREDOR, ORDENADOR

      7. Requisitos de Integração

        Utilizar HTTPS em todas as chamadas. Enviar o cabeçalho Authorization com Bearer Token válido. Enviar Content-Type: application/json nas operações JSON. Utilizar multipart/form-data no upload de anexos. Respeitar os formatos de data e timestamp definidos nos schemas. Persistir protocolo do envio e chave de validação. Validar localmente o payload antes da transmissão. Registar logs sem expor tokens, credenciais ou dados sensíveis.

        8. Regras Operacionais

          O envio deve estar aberto para receber entidades e anexos. A competência deve ser compatível com o tipo de envio. A validação é processada de forma assíncrona. Sem chaveValidacao, a API devolve a validação mais recente. A eliminação de envio é temporária e voltada à integração. Os anexos devem manter rastreabilidade por nome, referência, tamanho e SHA-256.

          9. Glossário

          Termo Definição API Interface de programação utilizada para integração entre sistemas. Bearer Token Token enviado no cabeçalho Authorization. Competência Período de referência do envio. Entidade Conjunto lógico de dados, como EMPENHO ou LIQUIDACAO. Protocolo de envio Identificador único do envio no SAGRES Captura. Chave de validação Identificador de uma execução de validação. Unidade Gestora Órgão ou unidade vinculada ao token. JSON Schema Contrato que define estrutura, tipos e obrigatoriedade dos dados.

          10. Referências

          Documentação da API:
          https://docs-api.tce.pb.gov.br/docs/openapi-sagres-captura

          Schemas das entidades:
          https://docs.tcepb.tc.br/books/entidades

          Suporte técnico:
          suportesagres@tce.pb.gov.br

          Back to top