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

3.2 URLs de autenticação

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}

3.8 Ilustração do fluxo

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.

5. Ciclo Funcional de um Envio

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

7. Entidades Suportadas

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

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