Informações Gerais Conjunto de APIs Apresenta informações gerais para gerenciamento de envios de dados para o SAGRES Captura. eticons.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 Obtenção do token de acesso Autenticação nas chamadas à API 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. Obtenção do Token de Acesso Para obter o token de acesso, deve ser realizada uma requisição POST ao serviço de autenticação, utilizando o método Basic Auth. 3.1 Credenciais de autenticação Campo Valor a informar Username Client ID gerado para a empresa. Password Secret gerada no momento do cadastro da empresa no SISCAD. No ambiente de testes, as credenciais são fornecidas diretamente pelo TCE-PB. Para solicitá-las, utilize o e-mail suportesagres@tce.pb.gov.br. 3.2 URLs de autenticação Ambiente URL Sandbox / Testes https://login-teste.tce.pb.gov.br/oauth/token Produção https://login.tce.pb.gov.br/oauth/token 3.3 Cabeçalho da requisição Content-Type: application/x-www-form-urlencoded 3.4 Corpo da requisição grant_type=client_credentials 3.5 Exemplo em cURL — Sandbox curl -X POST \ 'https://login-teste.tce.pb.gov.br/oauth/token' \ -u ':' \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data 'grant_type=client_credentials' 3.6 Exemplo em cURL — Produção curl -X POST \ 'https://login.tce.pb.gov.br/oauth/token' \ -u ':' \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data 'grant_type=client_credentials' 3.7 Utilização do token A resposta do serviço de autenticação conterá o campo access_token. Esse valor deve ser enviado no cabeçalho Authorization das chamadas à API do SAGRES Captura. Authorization: Bearer {access_token} Por segurança, o Client ID, a Secret e o access_token não devem ser registados em logs, expostos no código-fonte ou armazenados em ficheiros públicos. 3.8 Ilustração do fluxo Cliente envia Client ID, Secret e grant type para o serviço de autenticação, que devolve o access token utilizado na API SAGRES Captura. Sistema Cliente Client ID + Secret POST /oauth/token grant_type=client_credentials Autenticação TCE-PB OAuth2 / Basic Auth access_token API SAGRES Bearer Token Fluxo resumido de obtenção e utilização do token de acesso. 4. Autenticação nas Chamadas à API 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 ' -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. 5. 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. Primeiro precisa abrir o envio https://docs-api.tce.pb.gov.br/docs/openapi-sagres-captura#tag/Envios/operation/postEnvio  Fluxo --> Cria o envio, recebe o protocolo e assim começa a enviar as entidade referente aquele protocolo 6. 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. 7. 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 8. 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. 9. 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. 10. 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. 11. 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 Documento versionável — SAGRES Captura 2.0 | eticons.ai