# Informações Gerais  Conjunto de APIs

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

<main class="pagina" id="bkmrk-eticons.ai-sagres-ca"><header><div class="marca">eticons.ai</div># SAGRES Captura 2.0

<div class="subtitulo">Resumo Técnico, Documental e Funcional da API</div></header><table class="meta"><tbody><tr><th>Versão da API</th><td>1.0.0</td></tr><tr><th>Versão deste documento</th><td>1.0</td></tr><tr><th>Situação</th><td>Documento base para versionamento</td></tr><tr><th>Licença</th><td>Apache 2.0</td></tr><tr><th>Suporte SAGRES</th><td>suportesagres@tce.pb.gov.br</td></tr><tr><th>Data de emissão</th><td>14 de julho de 2026</td></tr></tbody></table>

## Controlo de Versões

<table><thead><tr><th>Versão</th><th>Data</th><th>Autor/Responsável</th><th>Descrição</th><th>Estado</th></tr></thead><tbody><tr><td>1.0</td><td>14/07/2026</td><td>Equipa de Integração</td><td>Criação do documento base consolidado.</td><td>Inicial</td></tr></tbody></table>

<div class="nota">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.</div>## Sumário

1. [Objetivo e escopo](#bkmrk-1.-objetivo-e-escopo)
2. [Visão geral da solução](#bkmrk-2.-vis%C3%A3o-geral-da-so)
3. [Obtenção do token de acesso](#bkmrk-3.-obten%C3%A7%C3%A3o-do-token)
4. [Autenticação nas chamadas à API](#bkmrk-4.-autentica%C3%A7%C3%A3o-nas-)
5. [Ciclo funcional de um envio](#bkmrk-5.-ciclo-funcional-d)
6. [Catálogo de endpoints](#bkmrk-6.-cat%C3%A1logo-de-endpo)
7. [Entidades suportadas](#bkmrk-7.-entidades-suporta)
8. [Requisitos de integração](#bkmrk-8.-requisitos-de-int)
9. [Regras operacionais](#bkmrk-9.-regras-operaciona)
10. [Glossário](#bkmrk-10.-gloss%C3%A1rio-termo-)
11. [Referências](#bkmrk-11.-refer%C3%AAncias-docu)

<section id="bkmrk-1.-objetivo-e-escopo">## 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.

</section><section id="bkmrk-2.-vis%C3%A3o-geral-da-so">## 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.

</section><section id="bkmrk-3.-obten%C3%A7%C3%A3o-do-token">## 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

<table><thead><tr><th>Campo</th><th>Valor a informar</th></tr></thead><tbody><tr><td>Username</td><td>**Client ID** gerado para a empresa.</td></tr><tr><td>Password</td><td>**Secret** gerada no momento do cadastro da empresa no SISCAD.</td></tr></tbody></table>

<div class="nota">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>.</div>### 3.2 URLs de autenticação

<table><thead><tr><th>Ambiente</th><th>URL</th></tr></thead><tbody><tr><td>Sandbox / Testes</td><td>`https://login-teste.tce.pb.gov.br/oauth/token`</td></tr><tr><td>Produção</td><td>`https://login.tce.pb.gov.br/oauth/token`</td></tr></tbody></table>

### 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 '<CLIENT_ID>:<SECRET>' \
  -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 '<CLIENT_ID>:<SECRET>' \
  -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}
```

<div class="nota">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.</div>### 3.8 Ilustração do fluxo

<figure class="fluxo-token"><svg aria-labelledby="tituloFluxoToken descricaoFluxoToken" role="img" viewbox="0 0 980 240"> <title id="bkmrk-fluxo-para-obten%C3%A7%C3%A3o-">Fluxo para obtenção do token OAuth2</title> <desc id="bkmrk-cliente-envia-client">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.</desc> <defs> <marker id="bkmrk-" markerheight="10" markerwidth="10" orient="auto" refx="9" refy="3"> <path d="M0,0 L0,6 L9,3 z" fill="#f26700"></path> </marker> </defs> <rect fill="#fff7ed" height="100" rx="12" stroke="#f26700" stroke-width="3" width="220" x="20" y="70"></rect> <text fill="#1f2933" font-size="22" font-weight="700" text-anchor="middle" x="130" y="108">Sistema Cliente</text> <text fill="#1f2933" font-size="16" text-anchor="middle" x="130" y="140">Client ID + Secret</text> <line marker-end="url(#seta)" stroke="#f26700" stroke-width="4" x1="250" x2="385" y1="120" y2="120"></line> <text fill="#1f2933" font-size="14" text-anchor="middle" x="317" y="98">POST /oauth/token</text> <text fill="#1f2933" font-size="13" text-anchor="middle" x="317" y="154">grant\_type=client\_credentials</text> <rect fill="#fff7ed" height="130" rx="12" stroke="#f26700" stroke-width="3" width="240" x="400" y="55"></rect> <text fill="#1f2933" font-size="21" font-weight="700" text-anchor="middle" x="520" y="100">Autenticação TCE-PB</text> <text fill="#1f2933" font-size="16" text-anchor="middle" x="520" y="134">OAuth2 / Basic Auth</text> <line marker-end="url(#seta)" stroke="#f26700" stroke-width="4" x1="650" x2="785" y1="120" y2="120"></line> <text fill="#1f2933" font-size="14" text-anchor="middle" x="717" y="98">access\_token</text> <rect fill="#fff7ed" height="100" rx="12" stroke="#f26700" stroke-width="3" width="160" x="800" y="70"></rect> <text fill="#1f2933" font-size="21" font-weight="700" text-anchor="middle" x="880" y="108">API SAGRES</text> <text fill="#1f2933" font-size="15" text-anchor="middle" x="880" y="140">Bearer Token</text> </svg><figcaption>Fluxo resumido de obtenção e utilização do token de acesso.</figcaption></figure></section><section id="bkmrk-4.-autentica%C3%A7%C3%A3o-nas-">## 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 <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.

</section><section id="bkmrk-5.-ciclo-funcional-d">## 5. Ciclo Funcional de um Envio

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

</section><section id="bkmrk-6.-cat%C3%A1logo-de-endpo"><p class="callout info">Primeiro precisa abrir o envio [https://docs-api.tce.pb.gov.br/docs/openapi-sagres-captura#tag/Envios/operation/postEnvio ](https://docs-api.tce.pb.gov.br/docs/openapi-sagres-captura#tag/Envios/operation/postEnvio)</p>

<p class="callout info">Fluxo --&gt; Cria o envio, recebe o protocolo e assim começa a enviar as entidade referente aquele protocolo</p>

## 6. Catálogo de Endpoints

<article class="endpoint"><div class="endpoint-cabecalho"><span class="metodo">POST</span><span class="rota">/envios</span></div>### 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.

</article><article class="endpoint"><div class="endpoint-cabecalho"><span class="metodo">GET</span><span class="rota">/envios/{protocoloEnvio}</span></div>### Consultar envio por protocolo

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

</article><article class="endpoint"><div class="endpoint-cabecalho"><span class="metodo">GET</span><span class="rota">/envios/{codigoUnidadeGestora}/{tipoEnvio}/{competencia}</span></div>### Consultar envio por Unidade Gestora, tipo e competência

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

</article><article class="endpoint"><div class="endpoint-cabecalho"><span class="metodo">DELETE</span><span class="rota">/envios/{protocoloEnvio}</span></div>### Eliminar envio

Elimina o envio e todos os dados associados ao protocolo.

<div class="endpoint-corpo"><div class="nota">Endpoint temporário, destinado ao período de integração.</div></div></article><article class="endpoint"><div class="endpoint-cabecalho"><span class="metodo">POST</span><span class="rota">/envios/{protocoloEnvio}/{entidade}</span></div>### 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.

</article><article class="endpoint"><div class="endpoint-cabecalho"><span class="metodo">POST</span><span class="rota">/envios/{protocoloEnvio}/validacoes</span></div>### Iniciar validação

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

</article><article class="endpoint"><div class="endpoint-cabecalho"><span class="metodo">GET</span><span class="rota">/envios/{protocoloEnvio}/validacoes</span></div>### Consultar resultado das validações

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

</article><article class="endpoint"><div class="endpoint-cabecalho"><span class="metodo">GET</span><span class="rota">/envios/{protocoloEnvio}/validacoes/agregados</span></div>### Consultar agregados

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

</article><article class="endpoint"><div class="endpoint-cabecalho"><span class="metodo">GET</span><span class="rota">/envios/{protocoloEnvio}/anexos</span></div>### Listar anexos

Lista os anexos vinculados ao envio identificado pelo protocolo.

</article><article class="endpoint"><div class="endpoint-cabecalho"><span class="metodo">POST</span><span class="rota">/envios/{protocoloEnvio}/anexos</span></div>### Carregar anexo

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

</article></section><section id="bkmrk-7.-entidades-suporta">## 7. Entidades Suportadas

<table><thead><tr><th>Grupo funcional</th><th>Entidades</th></tr></thead><tbody><tr><td>Planeamento e orçamento</td><td>ACAO, PROGRAMA, UNIDADE\_ORCAMENTARIA, DOTACAO, RECEITA\_PREVISTA, RECEITA\_ORCAMENTARIA, ATUALIZACAO\_ORCAMENTARIA, DECRETO\_OFICIO</td></tr><tr><td>Execução da despesa</td><td>EMPENHO, ESTORNO\_EMPENHO, LIQUIDACAO, ESTORNO\_LIQUIDACAO, PAGAMENTO, ESTORNO\_PAGAMENTO, RETENCAO, ESTORNO\_RETENCAO</td></tr><tr><td>Cadastros e apoio</td><td>CONTA\_BANCARIA, CONTA\_BANCARIA\_CREDOR, CREDOR, ORDENADOR</td></tr></tbody></table>

</section><section id="bkmrk-8.-requisitos-de-int">## 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.

</section><section id="bkmrk-9.-regras-operaciona">## 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.

</section><section id="bkmrk-10.-gloss%C3%A1rio-termo-">## 10. Glossário

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

</section><section id="bkmrk-11.-refer%C3%AAncias-docu">## 11. Referências

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

**Schemas das entidades:**  
[https://docs.tcepb.tc.br/books/entidades](https://docs.tcepb.tc.br/books/entidades)

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

</section><footer>Documento versionável — SAGRES Captura 2.0 | eticons.ai</footer></main>