# Dossiê de prontidão de integração FAPES

Versão: v0-pre-proposta
Gerado em: 2026-06-09T15:04:57.156Z
Fonte OpenAPI: docs/api/openapi.yaml
integrationReadinessReady=true
realFapesApiReady=false
officialConfirmationRequired=true

Consolidar a prova de integração imediata em um anexo executivo: OpenAPI, cliente mock FAPES, erros controlados, segurança, LGPD e dependências oficiais CTA/PRODEST.

## Resumo

| Endpoints | Métodos cobertos | Erros doc/executáveis | Checks segurança | Findings | Dependências oficiais | Pronto |
| --- | --- | --- | --- | --- | --- | --- |
| 3 | 3/3 | 4/4 / 4/4 | 11/11 | 5 ready / 1 attention / 0 blocked | 2 | sim |

## Decisão de autenticação

| Status | Referência técnica | Fallback | Gateway | Protocolo | Sessão mock | Confirmação oficial pendente |
| --- | --- | --- | --- | --- | --- | --- |
| decided_pre_proposal | Acesso Cidadao | gov.br | PRODEST | OIDC/OAuth2 authorization code | /api/auth/session (mock_oidc) | URL de autorização/token; claims obrigatórias; escopos e perfis institucionais; ambiente de sandbox; chaves e rotação de credenciais |

Integração preparada por OpenAPI e adaptador OIDC/OAuth2 compatível com Acesso Cidadão como referência técnica indicada pela CTA em 04/06/2026, gov.br como fallback federado e PRODEST como gateway institucional possível; a PoC confirmará URLs, claims e credenciais sem alterar o motor TRL/BRL.

## Findings

| ID | Status | Anexo VI | Evidência | Mensagem | Próxima ação | Cautela |
| --- | --- | --- | --- | --- | --- | --- |
| auth_decision_explicit | ready | 2.A, 4.B, 5.A, 5.E, 9.B | docs/architecture/adr-002-auth-integration.md; /api/auth/session; /api/operations/security-regression | Acesso Cidadao/gov.br via PRODEST; protocolo=OIDC/OAuth2 authorization code; mock=mock_oidc. | Colar no Solv como decisão arquitetural e manter M1 para URLs, claims, escopos e sandbox. | Não declarar integração real homologada antes de resposta CTA/PRODEST. |
| openapi_contract_ready | ready | 1.D, 2.A, 4.B, 5.A, 6.D | docs/api/openapi.yaml; /api/integration/fapes/contract?format=md | 3/3 endpoints cobertos por método; 4/4 erros documentados. | Anexar OpenAPI e relatório de conformidade no pacote técnico. | Contrato pronto não substitui confirmação de API real FAPES. |
| controlled_error_handling_ready | ready | 2.A, 5.A, 6.D | /api/integration/fapes/status; /api/integration/fapes/projects; /api/integration/fapes/results | 4/4 erros controlados executáveis no mock. | Usar no pitch para mostrar que integração falha de forma auditável e recuperável. | Se a API real usar códigos diferentes, ajustar contrato após esclarecimento oficial. |
| auth_rbac_audit_ready | ready | 2.A, 4.B, 5.A | /api/auth/session; /api/operations/security-regression | 11/11 checks de segurança passaram; falhas críticas=0. | Manter regressão como gate antes de M10/M11 e antes de qualquer integração real. | Regressão local não substitui homologação PRODEST. |
| lgpd_real_data_boundary_ready | ready | 2.A, 5.E, 7.B | /api/privacy/dpia; /api/operations/security-regression | privacyGateDeclared=true; realDataUseAllowed=false. | Citar separação entre mock pré-proposta e amostra real autorizada no CPSI. | Não anexar dado sigiloso da FAPES no Solv nem na demo pré-proposta. |
| official_dependencies_explicit | attention | 2.A, 5.A, 5.E, 9.B | /api/proposal/clarifications/tracker; /api/proposal/clarifications?format=md | 2 dependências oficiais pendentes: provedor de autenticação e API/sandbox FAPES. | Enviar ou arquivar esclarecimentos oficiais até 2026-06-08 e citar respostas se chegarem. | Atenção intencional: dependência oficial aberta não bloqueia o mock, mas precisa ser declarada para não prometer integração inexistente. |

## Anexos de suporte

| Anexo | Formato | Fonte | Anexo VI | Uso |
| --- | --- | --- | --- | --- |
| OpenAPI/Swagger FAPES | yaml | docs/api/openapi.yaml | 1.D, 2.A, 4.B, 5.A, 6.D | Contrato técnico versionado para integração, erros controlados e endpoints de mock. |
| Relatório de conformidade OpenAPI | markdown | /api/integration/fapes/contract?format=md | 2.A, 5.A, 6.D | Cross-check entre endpoints executáveis, respostas documentadas e dependências oficiais. |
| Cliente mock FAPES | json | /api/integration/fapes/status | 2.A, 4.B, 5.A | Lista endpoints, projetos sintéticos e erros controlados executáveis. |
| Regressão de segurança e LGPD | json | /api/operations/security-regression | 2.A, 5.E, 7.B | Prova auth, RBAC, auditoria, integração, privacidade e bloqueio de dados reais. |

## Cobertura OpenAPI

| Endpoint | Método | Runtime | OpenAPI | Respostas | Status |
| --- | --- | --- | --- | --- | --- |
| fapes_integration_status | GET | /api/integration/fapes/status | /integration/fapes/status | 200, 401, 403, 404, 422 | covered |
| fapes_project_query | GET | /api/integration/fapes/projects | /integration/fapes/projects | 200, 401, 403, 404, 422 | covered |
| fapes_result_submission | POST | /api/integration/fapes/results | /integration/fapes/results | 201, 400, 401, 403, 404, 422 | covered |

## Erros controlados

| HTTP | Código | Documentado | Executável | Gatilho |
| --- | --- | --- | --- | --- |
| 401 | mock_session_missing | sim | sim | Header x-fapes-mock-error: mock_session_missing |
| 403 | mock_role_forbidden | sim | sim | Header x-fapes-mock-error: mock_role_forbidden |
| 404 | mock_project_not_found | sim | sim | GET /api/integration/fapes/projects?externalProjectId=FAPES-MOCK-UNKNOWN |
| 422 | mock_payload_invalid | sim | sim | POST /api/integration/fapes/results com payload incompleto |

## Regressão de segurança

| Checks | Falhas | Auth | RBAC | Auditoria | Integração | LGPD | Dados reais |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 11/11 | 0 | ok | ok | ok | ok | ok | bloqueado |

## Dependências oficiais

- auth_provider: pending_official_confirmation; responsável: CTA/PRODEST/FAPES; mitigação: Manter adaptador mock compatível com Acesso Cidadao/gov.br/PRODEST ate confirmacao oficial.
- fapes_api: pending_official_confirmation; responsável: CTA/PRODEST/FAPES; mitigação: Manter contrato OpenAPI, fixtures e contingencia CSV/PDF/JSON ate acesso ao ambiente real.

## Runbook

- Anexar este dossiê junto ao OpenAPI e ao relatório de conformidade quando o Solv pedir evidência de integração.
- Citar a decisão pré-proposta de autenticação: adaptador OIDC/OAuth2 com Acesso Cidadão como referência técnica indicada pela CTA, gov.br como fallback federado e PRODEST como gateway institucional possível.
- Citar que a integração real depende de confirmação oficial da CTA/FAPES/PRODEST para URL, credenciais, claims e sandbox, mas que o contrato executável e os erros controlados já estão preparados.
- Não usar dados reais da FAPES antes de DPIA M1, definição de controlador/operador e ambiente autorizado.
- Reexecutar este dossiê depois de qualquer mudança em OpenAPI, autenticação, permissões, LGPD ou endpoints de integração.
- Se a CTA confirmar API/sandbox ou provedor de autenticação, substituir a premissa mock por referência oficial arquivada no tracker.

## Limitações

- Este dossiê prova prontidão técnica e mock homologável; não afirma que a FAPES já disponibilizou API real.
- A decisão pré-proposta usa Acesso Cidadão como referência técnica oficial indicada em 04/06/2026, mas a resposta oficial pode trocar URLs, claims, escopos ou gateway sem mudar o motor de avaliação.
- A regressão de segurança é local e pré-proposta; homologação institucional deve ocorrer no CPSI.