Roteiro de Demonstração de APIs da PGCC

Este documento apresenta o roteiro de demonstração das APIs da PGCC para as GCCs.

Objetivo

A organização interessada em exercer o papel de GCC precisa comprovar sua competência técnica para acionar todos os serviços de API da PGCC. Esses serviços podem ser divididos nos grupos abaixo:

Gestão de Chaves Criptográficas: Manter as chaves assimétricas para assinaturas digitais
Gestão de Webhooks: Manter os serviços web para o recebimento de mensagens HTTP
Gestão de Ciência e Consentimento: Manter os pedidos de consentimento e ciência de tratamentos de dados
Gestão de Hashes de Consultas: Manter as assinaturas digitais dos Hashes de Consulta

Pré-requisitos

Antes da demonstração, a GCC precisa:

Possuir certificado e-CNPJ ou de equipamento da empresa válido
Concluir a autorização e habilitação do credenciamento no Credencia (homologação ou produção)
Ter vínculo ativo com ao menos um Usuário confirmado no Credencia
Gerar chaves assimétricas RSA e mantê-las em segurança para a assinatura de JWTs
Prover um serviço web em domínio público acessível para o recebimento de mensagens HTTP

Configuração Inicial

Configuração - Homologação
Passo a Passo: Credenciamento
Roteiro - APIs Credencia (pré-requisito)

Etapas da Demonstração

A demonstração é dividida em etapas na qual cada etapa abrange um subconjunto de APIs que podem ser acionadas em conjunto e independentemente das outras APIs. Cada etapa sugere um número de cenários em que um ou mais recursos das APIs devem ser acionados. Todas as APIs foram especificadas conforme o padrão OpenAPI e apresentam suas respectivas páginas Swagger.

Lista de etapas:

Etapa 1: Gestão de Chaves Criptográficas
Etapa 2: Gestão de Webhooks
Etapa 3: Gestão de Consentimento e Ciência
Etapa 4: Geração e Validação de Hash JWT
Etapa 5: Fluxo Integrado

Etapa 1: Gestão de Chaves Criptográficas

A GCC precisa estar apta para gerir suas chaves criptográficas e informar à PGCC quais são as Chaves Públicas que serão usadas para validar as consultas dos Usuários. Essa gestão se dá por meio dos métodos da API de Gestão de Chaves Públicas da plataforma. Essa API permite que a GCC cadastre chaves públicas e gerencie o ciclo de vida de suas chaves criptográficas.

Tempo Estimado: 30 minutos

Critérios de Sucesso

Registrar chave pública com sucesso
Consultar chaves com sucesso
Consultar chaves incluindo revogadas com sucesso
Detalhar chave específica com sucesso
Revogar chave com sucesso

Links relevantes

Cenário 1.1: Registrar Chave Pública

A GCC deve acionar o método POST /admin/gcc/v1/chaves-publicas para registrar uma nova chave pública. A chave deve estar em formato binário (DER) e ser enviada no corpo da mensagem HTTP, conforme exemplo abaixo:

POST /admin/gcc/v1/chaves-publicas HTTP/1.1
Content-Type: application/octet-stream
[... Outros cabeçalhos ...]

[Corpo: bytes da chave pública em formato DER]

Sobre o formato da chave

A API de Gestão de Chaves Públicas da PGCC espera que GCC cadastre a Chaves Pública (RSA SHA-256) do par de chaves assimétricas geridas pela GCC para assinaturas digitais. Ou seja, a Chave Privada de cada par chaves deve ser mantida em segurança pela GCC e não deve ser compartilhada em hipótese alguma. Já a Chava Pública de cada par de chaves deve ser informada à PGCC.

A API aceita apenas os bytes da chave pública (formato binário DER)
Não enviar chave em formato PEM (com headers -----BEGIN PUBLIC KEY-----)
Content-Type aceitos: application/octet-stream ou application/x-x509-ca-cert
Não incluir headers ou wrappers adicionais no conteúdo da chave

Conversão de formato usando OpenSSL

É comum que chaves assimétricas sejam distribuídas em formato textual (PEM). Para converter uma chave pública para o formato binário (DER), é possível fazer uso da ferramenta openssl:

openssl rsa -pubin -in chave-publica.pem -outform DER -out chave-publica.der

Exemplo de requisição autenticada usando curl:

curl -X POST ${uriBasePgcc}/admin/gcc/v1/chaves-publicas \
  -H "Content-Type: application/octet-stream" \
  --cert certificado-gcc.pem --key certificado-gcc.key \
  --data-binary @chave-publica.der

Cenário 1.2: Consultar Chaves Públicas

A GCC deve acionar o método GET /admin/gcc/v1/chaves-publicas para consultar todas as chaves públicas cadastradas. Por exemplo:

GET /admin/gcc/v1/chaves-publicas HTTP/1.1

Sobre os parâmetros de consulta

Esta API apresenta atributos de query para controlar a paginação do resultado e a exibição de chaves públicas já revogadas.

Cenário 1.3: Detalhar Chave Pública Específica

A GCC deve acionar o método GET /admin/gcc/v1/chaves-publicas/{id} para consultar detalhes de uma chave pública especificada por ID. Por exemplo:

GET /admin/gcc/v1/chaves-publicas/00000000-0000-0000-0000-000000000000 HTTP/1.1

Sobre o ID da chave pública

O formato UUID foi adotado para o identificador público das chaves públicas e será validado na consulta.

Cenário 1.4: Revogar Chave Pública

A GCC deve acionar o método DELETE /admin/gcc/v1/chaves-publicas/{id} para revogar uma chave pública especificada por ID. Por exemplo:

DELETE /admin/gcc/v1/chaves-publicas/00000000-0000-0000-0000-000000000000 HTTP/1.1

Sobre a revogação de chaves públicas

A revogação é irreversível
Chaves revogadas não podem mais ser usadas para validar assinaturas
Chaves revogadas permanecem no histórico para auditoria
Use incluirRevogadas=true na consulta para visualizá-las

Etapa 2: Gestão de Webhooks

A GCC precisar estar apta para gerir seus webhooks e informar à PGCC quais são as URLs públicas dos serviços web que receberão mensagens HTTP com eventos ou notificações da PGCC. Essa gestão se dá por meio dos métodos da API de Gestão de Webhooks da plataforma. Essa API permite que a GCC cadastre URLs de webhooks para receberem notificações sobre eventos como alterações de consentimento, criação de ciências, e outros eventos do sistema.

Tempo Estimado: 30 minutos

Critérios de Sucesso

Webhook registrado com sucesso (HTTP 201 Created)
ID UUID retornado e armazenado
Listagem de webhooks funcionando com paginação (HTTP 200 OK)
Detalhamento exibindo todos os campos, incluindo chaveAcesso
Atualização de URL ou chaveAcesso aplicada (HTTP 200 OK)
Exclusão executada corretamente (HTTP 204 No Content)
Endpoint da GCC implementado e funcional
Validação de token funcionando
Resposta em até 5 segundos
Idempotência implementada
Logs de auditoria registrados

Links relevantes

Cenário 2.1: Registrar Novo Webhook

A GCC deve acionar o método POST /admin/gcc/v1/webhooks para registrar uma nova URL de webhook. O corpo da mensagem HTTP deve estar em formato JSON, conforme o exemplo abaixo:

POST /admin/gcc/v1/webhooks HTTP/1.1
Content-Type: application/json

{
  "url": "https://gcc.exemplo.com.br/api/webhooks/pgcc",
  "chaveAcesso": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Sobre os parâmetros de entrada

A URL deve ser HTTPS. É recomendado que a GCC use um domínio fixo para todas as URLs de webhooks, pois o registro de novos domínios não é síncrono e pode levar alguns minutos
A chaveAcesso será enviada no header Authorization usando o formato Bearer quando a PGCC chamar o webhook. O valor que a GCC passar nesse campo será repassado na requisição à URL do webhook por meio do cabeçalho Authorization com o prefixo Bearer. Por exemplo, se chaveAcesso for 12345, a requisição da PGCC será feita com o cabeçalho: Authorization: Bearer 12345
A GCC deve implementar endpoint que responda com HTTP 2xx em até 5 segundos
Implementar idempotência: eventos podem ser entregues mais de uma vez

Cenário 2.2: Consultar Webhooks Cadastrados

A GCC deve acionar o método GET /admin/gcc/v1/webhooks para consultar todos os webhooks cadastrados. Por exemplo:

GET /admin/gcc/v1/webhooks HTTP/1.1

Sobre os parâmetros de consulta

Esta API apresenta atributos de query para controlar a paginação do resultado.

Cenário 2.3: Detalhar Webhook Específico

A GCC deve acionar o método GET /admin/gcc/v1/webhooks/{id} para consultar detalhes de um webhooks especificado por ID. Por exemplo:

GET /admin/gcc/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1

Cenário 2.4: Atualizar Webhook Existente

A GCC deve acionar o método PUT /admin/gcc/v1/webhooks/{id} para atualizar uma URL ou chave de acesso de um webhook especificado por ID. O corpo da mensagem HTTP deve estar em formato JSON, conforme o exemplo abaixo:

PUT /admin/gcc/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1
Content-Type: application/json

{
  "url": "https://gcc.exemplo.com.br/api/v2/webhooks/pgcc",
  "chaveAcesso": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.novo-token..."
}

Os casos de uso para esta operação são diversos, por exemplo:

Migração de URL do endpoint após mudança de infraestrutura
Rotação de chave de acesso por questões de segurança
Atualização de domínio ou path do webhook

Sobre os parâmetros de entrada

Pelo menos um dos campos deve ser fornecido para atualização
Caso um campo seja fornecido, o mesmo será atualizado
Para não atualizar um campo, basta omiti-lo no corpo da mensagem

Cenário 2.5: Excluir Webhook

A GCC deve acionar o método DELETE /admin/gcc/v1/webhooks/{id} para excluir um webhook especificado por ID. Por exemplo:

DELETE /admin/gcc/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1

Sobre o impacto da exclusão

Após exclusão, a PGCC para de enviar notificações para aquela URL
Webhooks excluídos não aparecem em listagens normais
Caso a exclusão permanente não seja desejada, considere desabilitar um webhook temporariamente, por exemplo, por meio de uma atualização com chave de acesso inválida

Etapa 3: Gestão de Consentimento e Ciência

Objetivo: Demonstrar a capacidade de gerenciar consentimentos e ciências de tratamento de dados dos titulares.

A API PGCC Consentimento possui 3 módulos principais:

Consentimentos: Pedidos de consentimento para uso de dados pessoais
Ciências: Ciência de tratamentos de dados pessoais realizados
Autenticação: Autenticação de titulares via Gov.br

📌 Cenário 3.1: Gerar URL de Autenticação Gov.br

Acessar API PGCC - Consentimento
Gerar URL de autenticação para o titular:

GET /v1/autenticacao/{cpf}/url?redirectUrl={URL_RETORNO}

Parâmetros:

cpf: CPF do titular (path parameter)
redirectUrl: URL de retorno após autenticação (query parameter, opcional)

Resposta esperada:

{
    "url": "{Domínio base da PGCC}/consentimento/v1/redirect/login?state=eyJ..."
}

Fluxo:

GCC solicita URL de autenticação
PGCC gera um endereço personalizado
Titular é redirecionado para Gov.br
Titular Autentica com conta Gov.br (prata ou ouro)
PGCC recebe confirmação do Gov.br
Se a redirectUrl foi informada, o Titular é redirecionado a essa URI

📌 Cenário 3.2: Verificar Status de Autenticação

Consultar se titular já está autenticado:

GET /v1/autenticacao/{cpf}

Resposta esperada:

{
    "autenticado": true,
    "horaExpiracao": "2025-11-18T15:30:00Z"
}

⚠️ Importante: A autenticação Gov.br possui prazo de validade. Após expiração, é necessário solicitar nova autenticação.

📌 Cenário 3.3: Consultar Consentimentos do Titular

Listar todos os consentimentos (com filtro opcional por CNPJ de usuário):

GET /v1/consentimentos/{cpf}?cnpj={CNPJ_USUARIO}

Parâmetros:

cpf: CPF do titular (path parameter)
cnpj: CNPJ do usuário para filtrar consentimentos (query parameter, opcional)

Resposta esperada:

[
    {
        "id": "abc123",
        "status": "ATIVO",
        "dataHora": "2025-11-13T10:00:00Z",
        "dataExpiracao": "2026-11-13T10:00:00Z",
        "cnpjUsuario": "12345678000195",
        "href": "/v1/consentimentos/12345678901/abc123"
    },
    {
        "id": "def456",
        "status": "PENDENTE",
        "dataHora": "2025-11-14T14:30:00Z",
        "dataExpiracao": "2026-11-14T14:30:00Z",
        "cnpjUsuario": "98765432000198",
        "href": "/v1/consentimentos/12345678901/def456"
    }
]

Status possíveis:

PENDENTE - Aguardando autenticação ou aprovação do titular
ATIVO - Consentimento concedido e vigente
REVOGADO - Revogado pelo titular ou GCC
NEGADO - Negado pelo titular
EXPIRADO - Prazo de validade esgotado

📌 Cenário 3.4: Consultar Consentimento Detalhado

Obter informações completas de um consentimento específico:

GET /v1/consentimentos/{cpf}/{id}

Parâmetros:

cpf: CPF do titular
id: Identificador do consentimento

Resposta esperada:

{
    "id": "abc123",
    "idTemplatePdc": "136987",
    "status": "ATIVO",
    "dataHora": "2025-11-13T10:00:00Z",
    "dataExpiracao": "2026-11-13T10:00:00Z",
    "categoria": {
        "identificador": "DADOS_VEICULARES",
        "descricao": "Dados de veículos e infrações",
        "rotulo": "Dados Veiculares",
        "metadados": [
            {
                "identificador": "RENAVAM",
                "descricao": "Número RENAVAM do veículo",
                "rotulo": "RENAVAM",
                "sensivel": false
            },
            {
                "identificador": "PLACA",
                "descricao": "Placa do veículo",
                "rotulo": "Placa",
                "sensivel": false
            }
        ]
    },
    "usuario": {
        "cnpj": "12345678000195",
        "nome": "Empresa Exemplo LTDA",
        "email": "contato@exemplo.com.br",
        "contato": "(61) 99999-9999",
        "responsavel": {
            "cpf": "12345678901",
            "cnpj": null,
            "tipo": "DPO"
        }
    },
    "finalidade": {
        "identificador": "CONSULTA_VEICULAR",
        "descricao": "Consulta de dados veiculares para serviços",
        "rotulo": "Consulta Veicular"
    },
    "titular": {
        "cpf": "12345678901",
        "nome": "Fulano de Tal",
        "email": "fulano@email.com.br"
    },
    "historico": [
        {
            "status": "PENDENTE",
            "dataHora": "2025-11-13T10:00:00Z",
            "dataExpiracao": "2026-11-13T10:00:00Z"
        },
        {
            "status": "ATIVO",
            "dataHora": "2025-11-13T10:15:00Z",
            "dataExpiracao": "2026-11-13T10:00:00Z"
        }
    ]
}

Informações retornadas:

Identificadores únicos (id, idTemplatePdc)
Status atual e histórico completo
Categoria de dados com metadados
Dados do usuário controlador e DPO
Finalidade do tratamento (base legal)
Informações do titular
Datas de criação e expiração

📌 Cenário 3.5: Atualizar Status do Consentimento

Atualizar status para ATIVO, REVOGADO ou NEGADO:

PUT /v1/consentimentos/{cpf}/{id}/status/{status}

Parâmetros:

cpf: CPF do titular
id: Identificador do consentimento
status: Novo status (ATIVO, REVOGADO ou NEGADO)

Regras de transição:

PENDENTE → ATIVO ou NEGADO
ATIVO → REVOGADO
Não é possível reverter REVOGADO ou NEGADO

Exemplo - Ativar consentimento:

PUT /v1/consentimentos/12345678901/abc123/status/ATIVO

Exemplo - Revogar consentimento:

PUT /v1/consentimentos/12345678901/abc123/status/REVOGADO

Resposta esperada:

{
    "id": "abc123",
    "status": "ATIVO",
    "dataHora": "2025-11-13T10:15:00Z",
    "dataExpiracao": "2026-11-13T10:00:00Z",
    "cnpjUsuario": "12345678000195",
    "href": "/v1/consentimentos/12345678901/abc123"
}

📌 Cenário 3.6: Consultar Ciências de Tratamento

Listar todas as ciências de tratamento de dados (com filtro opcional por CNPJ):

GET /v1/ciencias/{cpf}?cnpj={CNPJ_USUARIO}

Parâmetros:

cpf: CPF do titular (path parameter)
cnpj: CNPJ do usuário para filtrar (query parameter, opcional)

Resposta esperada:

[
    {
        "id": "ciencia001",
        "dataHora": "2025-11-15T09:00:00Z",
        "cnpjUsuario": "12345678000195",
        "href": "/v1/ciencias/12345678901/ciencia001"
    },
    {
        "id": "ciencia002",
        "dataHora": "2025-11-16T11:30:00Z",
        "cnpjUsuario": "98765432000198",
        "href": "/v1/ciencias/12345678901/ciencia002"
    }
]

⚠️ Diferença entre Consentimento e Ciência:

Consentimento: Autorização prévia para tratamento de dados (base legal: consentimento LGPD Art. 7º, I)
Ciência: Notificação de tratamento realizado sem necessidade de consentimento prévio (outras bases legais LGPD Art. 7º)

📌 Cenário 3.7: Consultar Ciência Detalhada

Obter informações completas de uma ciência específica:

GET /v1/ciencias/{cpf}/{id}

Parâmetros:

cpf: CPF do titular
id: Identificador da ciência

Resposta esperada:

{
    "id": "ciencia001",
    "dataHora": "2025-11-15T09:00:00Z",
    "titular": {
        "cpf": "12345678901",
        "nome": "Fulano de Tal",
        "email": "fulano@email.com.br"
    },
    "usuario": {
        "cnpj": "12345678000195",
        "nome": "Empresa Exemplo LTDA",
        "email": "contato@exemplo.com.br",
        "contato": "(61) 99999-9999",
        "responsavel": {
            "cpf": "12345678901",
            "cnpj": null,
            "tipo": "DPO"
        }
    },
    "finalidade": {
        "identificador": "CUMPRIMENTO_OBRIGACAO_LEGAL",
        "descricao": "Tratamento para cumprimento de obrigação legal",
        "rotulo": "Obrigação Legal"
    },
    "historico": [
        {
            "info": "Consulta realizada para cumprimento de obrigação legal - DETRAN",
            "dataHora": "2025-11-15T09:00:00Z",
            "dataInicio": "2025-11-15T09:00:00Z",
            "metadados": [
                {
                    "identificador": "CNH",
                    "descricao": "Número da CNH",
                    "rotulo": "CNH",
                    "sensivel": false
                },
                {
                    "identificador": "PONTUACAO",
                    "descricao": "Pontuação da CNH",
                    "rotulo": "Pontuação",
                    "sensivel": false
                }
            ],
            "hipoteses": [
                {
                    "complemento": "Consulta realizada para atendimento de requisito legal",
                    "hipoteseTratamento": {
                        "envolveDadoSensivel": false,
                        "id": "OBRIGACAO_LEGAL",
                        "nome": "Cumprimento de obrigação legal ou regulatória"
                    }
                }
            ]
        }
    ]
}

Informações retornadas:

Identificador único e data/hora
Dados do titular e usuário controlador
Finalidade do tratamento
Histórico detalhado com:
- Metadados acessados
- Hipóteses legais (bases legais LGPD)
- Informações complementares
- Datas de início e execução

✅ Critérios de Sucesso - Etapa 2:

URL de autenticação Gov.br gerada (HTTP 200 OK)
Status de autenticação consultado corretamente
Consulta de consentimentos funcionando (HTTP 200 OK)
Detalhes de consentimento retornados com informações completas
Atualização de status operacional (HTTP 200 OK)
Consulta de ciências de tratamento funcionando
Detalhes de ciência retornados com histórico completo
Compreensão clara da diferença entre consentimento e ciência
Auditoria completa disponível (históricos)

⏱️ Tempo Estimado: 50 minutos

Etapa 4: Geração e Validação de Hash JWT

Objetivo: Demonstrar capacidade de gerar e enviar hashes de consulta assinados digitalmente com JWT, além de consultar e gerenciar hashes cadastrados.

A API PGCC Hash permite que GCCs registrem hashes JWT assinados digitalmente, que são utilizados para rastrear e auditar consultas a dados pessoais dos titulares, garantindo integridade e conformidade com a LGPD.

📌 Cenário 4.1: Gerar Hash JWT Assinado

Passo 1: Criar payload JSON com os campos obrigatórios:

{
    "templateId": "136987",
    "isConsentimento": true,
    "idConsentimento": "67890",
    "cnpjUsuario": "05884765000164",
    "cnpjAnuente": "03452307000111",
    "cnpjGcc": "05884765000164",
    "dataCriacao": "2025-11-13T10:45:00",
    "dataExpiracao": "2025-12-31T23:59:59"
}

Campos obrigatórios no payload:

templateId: ID do template do caso de uso
isConsentimento: Indica se há consentimento (true/false)
idConsentimento: ID do consentimento (se aplicável)
cnpjUsuario: CNPJ do usuário solicitante
cnpjAnuente: CNPJ do órgão anuente (ex: DETRAN)
cnpjGcc: CNPJ da GCC responsável
dataCriacao: Data/hora de criação do hash
dataExpiracao: Data/hora de expiração do hash

Passo 2: Assinar o payload com chave privada RSA usando algoritmo RS256

Passo 3: Gerar JWT no formato padrão (header.payload.signature):

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW1wbGF0ZUlkIjoiMTM2OTg3IiwiaXNDb25zZW50aW1lbnRvIjp0cnVlLCJpZENvbnNlbnRpbWVudG8iOiI2Nzg5MCIsImNucGpVc3VhcmlvIjoiMDU4ODQ3NjUwMDAxNjQiLCJjbnBqQW51ZW50ZSI6IjAzNDUyMzA3MDAwMTExIiwiY25wakdjYyI6IjA1ODg0NzY1MDAwMTY0IiwiZGF0YUNyaWFjYW8iOiIyMDI1LTExLTEzVDEwOjQ1OjAwIiwiZGF0YUV4cGlyYWNhbyI6IjIwMjUtMTItMzFUMjM6NTk6NTkifQ.hGxKN8H7m9p...

📌 Cenário 4.2: Enviar Hash JWT para Validação

Enviar JWT assinado para a PGCC validar e registrar:

POST /api/v1/hash
Headers:
  x-cnpj-consulta: 20211917000142
  x-cpf-operador: 10973787724
  Content-Type: application/json

Body:
"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW1wbGF0ZUlkIjoiMTM2OTg3Ii..."

Processo de validação:

PGCC extrai o CNPJ da GCC do certificado digital
Busca a chave pública RSA cadastrada para essa GCC
Valida a assinatura JWT usando a chave pública
Verifica campos obrigatórios do payload
Registra o hash na base de dados
Retorna o ID único do hash

Resposta esperada (HTTP 201 Created):

{
    "idhash": "47f1bc84-c5cb-417d-97b9-bef23208cbdd"
}

Possíveis erros:

HTTP 401: Assinatura inválida (chave pública não valida o JWT)
HTTP 422: Campos obrigatórios ausentes no payload
HTTP 500: Erro interno ao validar hash

⚠️ Importante:

A GCC deve usar a mesma chave privada correspondente à chave pública cadastrada na Etapa 1
O algoritmo de assinatura deve ser RS256 (RSA-SHA256)
O JWT deve estar no formato padrão (header.payload.signature)

📌 Cenário 4.3: Consultar Hash por Campos do Payload

Consultar hash específico utilizando campos do payload (não pelo JWT completo):

GET /api/v1/hash/payload?idTemplate=136987&idConsentimento=67890&cnpjUsuario=05884765000164&cnpjAnuente=03452307000111
Headers:
  x-cnpj-consulta: 20211917000142
  x-cpf-operador: 10973787724

Parâmetros de consulta (query parameters - todos opcionais):

idTemplate: ID do template
idConsentimento: ID do consentimento
cnpjUsuario: CNPJ do usuário
cnpjAnuente: CNPJ do anuente
dataCriacao: Data de criação (formato: 2025-07-01T12:34:56)
dataExpiracao: Data de expiração (formato: 2024-12-01T12:34:56)

Resposta esperada (HTTP 200 OK):

{
    "id": "47f1bc84-c5cb-417d-97b9-bef23208cbdd",
    "templateId": "136987",
    "isConsentimento": true,
    "idConsentimento": "67890",
    "cnpjUsuario": "05884765000164",
    "cnpjAnuente": "03452307000111",
    "cnpjGcc": "20211917000142",
    "dataCriacao": "2025-11-13T10:45:00Z",
    "dataExpiracao": "2025-12-31T23:59:59Z",
    "status": "PROCESSADO",
    "dataProcessamento": "2025-11-13T10:45:05Z"
}

Possíveis erros:

HTTP 404: Hash não encontrado com os parâmetros fornecidos
HTTP 400: Parâmetros de consulta inválidos

📌 Cenário 4.4: Consultar Hashes por CNPJ com Filtros

Listar todos os hashes de uma GCC com filtros opcionais:

GET /api/v1/hash/cnpjGcc/20211917000142?idTemplate=136987&status=PROCESSADO&dataInicial=2025-01-01&dataFinal=2025-12-31
Headers:
  x-cnpj-consulta: 20211917000142
  x-cpf-operador: 10973787724

Parâmetros:

cnpjGcc (path): CNPJ da GCC (obrigatório)
Query parameters (todos opcionais):
- idTemplate: Filtrar por template
- idConsentimento: Filtrar por consentimento
- status: Filtrar por status (PROCESSADO, PENDENTE, EXPIRADO, EXCLUIDO)
- cnpjUsuario: Filtrar por CNPJ do usuário
- cnpjAnuente: Filtrar por CNPJ do anuente
- dataInicial: Data inicial do intervalo (formato: yyyy-MM-dd)
- dataFinal: Data final do intervalo (formato: yyyy-MM-dd)

Resposta esperada (HTTP 200 OK):

[
    {
        "id": "47f1bc84-c5cb-417d-97b9-bef23208cbdd",
        "templateId": "136987",
        "isConsentimento": true,
        "idConsentimento": "67890",
        "cnpjUsuario": "05884765000164",
        "cnpjAnuente": "03452307000111",
        "cnpjGcc": "20211917000142",
        "dataCriacao": "2025-11-13T10:45:00Z",
        "dataExpiracao": "2025-12-31T23:59:59Z",
        "status": "PROCESSADO"
    },
    {
        "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "templateId": "136987",
        "isConsentimento": true,
        "idConsentimento": "67891",
        "cnpjUsuario": "05884765000164",
        "cnpjAnuente": "03452307000111",
        "cnpjGcc": "20211917000142",
        "dataCriacao": "2025-11-14T14:20:00Z",
        "dataExpiracao": "2025-12-31T23:59:59Z",
        "status": "PROCESSADO"
    }
]

Status possíveis:

PROCESSADO: Hash validado e registrado com sucesso
PENDENTE: Hash aguardando processamento
EXPIRADO: Hash com data de expiração ultrapassada
EXCLUIDO: Hash removido logicamente (soft delete)

Possíveis erros:

HTTP 404: Nenhum hash encontrado com os filtros fornecidos
HTTP 400: Parâmetros de filtro inválidos

📌 Cenário 4.5: Exclusão Lógica de Hash

Realizar exclusão lógica de um hash (mantém histórico para auditoria):

DELETE /api/v1/hash/id/47f1bc84-c5cb-417d-97b9-bef23208cbdd
Headers:
  x-cnpj-consulta: 20211917000142
  x-cpf-operador: 10973787724

Parâmetros:

id (path): UUID do hash a ser excluído

Resposta esperada (HTTP 200 OK):

Hash marcado como excluído com sucesso

⚠️ Importante:

A exclusão é lógica (soft delete), não física
O hash não é removido do banco de dados
O status é alterado para EXCLUIDO
Permite auditoria e rastreabilidade
Hashes excluídos não aparecem em consultas normais

Possíveis erros:

HTTP 404: Hash não encontrado
HTTP 400: UUID inválido

📌 Cenário 4.6: Estatísticas de Hashes (Análise)

Demonstrar análise dos hashes cadastrados:

Exemplos de análises úteis:

Total de hashes por status:

GET /api/v1/hash/cnpjGcc/20211917000142?dataInicial=2025-01-01&dataFinal=2025-12-31

Analisar a resposta e contar por status (PROCESSADO, EXPIRADO, etc.)

Hashes próximos da expiração:

GET /api/v1/hash/cnpjGcc/20211917000142?dataFinal=2025-11-20

Identificar hashes que expiram em breve para renovação

Volume de consultas por usuário:

GET /api/v1/hash/cnpjGcc/20211917000142?cnpjUsuario=05884765000164

Analisar quantos hashes foram gerados para um usuário específico

Auditoria de template específico:

GET /api/v1/hash/cnpjGcc/20211917000142?idTemplate=136987

Rastrear todas as consultas feitas com um caso de uso específico

✅ Critérios de Sucesso - Etapa 3:

Payload JSON criado com todos os campos obrigatórios
JWT assinado corretamente com RS256
Hash enviado e validado com sucesso (HTTP 201 Created)
ID do hash retornado e registrado
Consulta por campos do payload funcionando (HTTP 200 OK)
Consulta com filtros retornando resultados corretos
Exclusão lógica executada com sucesso (HTTP 200 OK)
Compreensão do processo de validação de assinatura
Capacidade de gerar estatísticas e análises
Auditoria completa mantida (histórico preservado)

⏱️ Tempo Estimado: 40 minutos

Etapa 5: Casos de Uso

A GCC precisa estar apta a executar casos de uso completos de gestão de consentimento, conhecimento e consultas.

Tempo Estimado: 50 minutos

Critérios de Sucesso

Fluxo completo executado sem erros
Todos os passos auditados corretamente
Conformidade com LGPD demonstrada
Transparência para o titular garantida
Integração entre todos os módulos funcionando

Cenário 5.1: Consultar dados sem necessidade de consentimento

Usuário solicita Hash de consulta de dados do Titular à GCC
GCC verifica que Caso de Uso não precisa de pedido de consentimento
GCC gera Hash (JWT) com dados da consulta
GCC envia Hash para validação na PGCC
PGCC valida e registra Hash com ID
GCC retorna ID do Hash de consulta ao Usuário
Usuário consulta dados na PGCC usando ID do Hash validado
Titular consulta tratamento no Portal PDC

Cenário 5.1: Consultar dados com pedido de consentimento

Usuário solicita Hash de consulta de dados do Titular para a GCC
GCC verifica que Caso de Uso precisa de pedido de consentimento
GCC verifica se existe pedido de consentimento ativo do Usuário ao Titular
Caso não exista (fluxo assíncrono)
1. GCC solicita criação de pedido de consentimento ao Titular
2. Titular autentica via Gov.br e aprova consentimento
3. GCC recebe evento via webhook sobre aprovação
GCC gera Hash (JWT) com dados da consulta
GCC envia Hash para validação na PGCC
PGCC valida e registra Hash com ID
GCC retorna ID do Hash de consulta ao Usuário
Usuário consulta dados na PGCC usando ID do Hash validado
Titular consulta tratamento no Portal PDC

📊 Diagrama do Fluxo Completo PGCC

sequenceDiagram
    participant Usuario
    participant GCC
    participant PGCC
    participant Titular
    participant GovBr
    Usuario ->> GCC: 1. Solicita consulta de dados
    GCC ->> PGCC: 2. Verifica consentimento ativo

    alt Consentimento não existe
        GCC ->> PGCC: 3. Cria consentimento pendente
        GCC ->> Titular: 4. Solicita autorização
        Titular ->> GovBr: 5. Autentica
        GovBr -->> Titular: 6. Token autenticação
        Titular ->> PGCC: 7. Aprova consentimento
        PGCC ->> GCC: 8. Notifica via webhook
    end

    GCC ->> GCC: 9. Gera hash JWT assinado
    GCC ->> PGCC: 10. Envia hash para validação
    PGCC -->> GCC: 11. Confirma validação (202)
    Usuario ->> PGCC: 12. Consulta dados com hash
    PGCC -->> Usuario: 13. Retorna dados solicitados

Tempo Total Estimado

Etapa	Tempo
Etapa 1: Administração de Chaves Públicas	30 min
Etapa 2: Webhooks	35 min
Etapa 3: Gestão de Consentimento	50 min
Etapa 4: Hash JWT	40 min
Etapa 5: Fluxo Integrado	30 min
Total	~3h 05min

Tempo adicional para perguntas e ajustes durante a demonstração.

✅ Checklist de Validação - APIs PGCC

Chaves Públicas RSA

[ ] Chave privada RSA gerada e segura
[ ] Chave pública RSA cadastrada na PGCC
[ ] Backup da chave privada em local seguro
[ ] Cadastro de chave testado
[ ] Consulta de chaves funcionando
[ ] Processo de rotação documentado

Webhooks

[ ] Webhook configurado e acessível
[ ] URL respondendo corretamente
[ ] Cadastro testado
[ ] Teste de ping bem-sucedido
[ ] Tratamento de retry implementado
[ ] Histórico acessível

Consentimento

[ ] Criação de consentimento pendente testada
[ ] Criação de consentimento ativo testada
[ ] Link de autenticação Gov.br gerando
[ ] Atualização de status funcionando
[ ] Consultas operacionais
[ ] Renovação testada

Hash JWT

[ ] Geração de JWT assinado implementada
[ ] Envio de hash funcionando
[ ] Consultas operacionais
[ ] Validação de integridade implementada
[ ] Estatísticas funcionando

Dados de Teste

[ ] CPF de teste válido
[ ] CNPJ de usuário de teste
[ ] Template ID de teste (136987)
[ ] Massa de dados preparada

🔍 Observações Técnicas - PGCC

Sobre Chaves RSA

Tamanho mínimo: 2048 bits
Algoritmo: RS256 (RSA-SHA256)
Manter chave privada segura
Cadastrar apenas chave pública
Rotação periódica recomendada

Sobre Hash JWT

JWT assinado com chave privada da GCC
PGCC valida com chave pública cadastrada
Payload deve conter campos obrigatórios
Histórico mantido para auditoria

Sobre Webhooks

URL deve ser HTTPS
Responder em até 5 segundos
Sistema realiza até 3 tentativas
Implementar idempotência
Validar assinatura dos eventos

Sobre Consentimento

Consentimento Gov.br garante autenticidade
Consentimento sem Gov.br requer registro prévio
GCC é responsável legal pela veracidade
Todos os eventos auditados
Titular pode revogar a qualquer momento

📚 Documentação de Referência

APIs PGCC

Guias e Fluxos

Roteiro de Demonstração - APIs Credencia (pré-requisito)
Passo a Passo: Credenciamento Completo
Webhooks - Como usar

📌 Observações Importantes

⚠️ ATENÇÃO:

A demonstração será presencial em Brasília/DF
É obrigatória a presença do preposto designado
Apoio remoto via videoconferência é facultado
O prazo para atendimento da convocação é de 60 dias
Não atendimento resulta em desclassificação

📞 Suporte e Dúvidas

🔹 FAQ - Perguntas Frequentes
🔹 Glossário de Termos
🔹 Suporte Técnico