jonatan/sowai-fiscal-svc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(openapi): declare the full response contract (401/404/409/413) on every v1 route

Browse Source 
Honors portability safeguard (c) -- the committed docs/openapi-v1.json was
enforced to stay in sync with app.openapi() (test_openapi_committed.py),
but the app declared almost no error responses: POST /v1/emissoes showed
only 200/422 (no 201), and no route declared 401/404/409/413 or the
structured 409 codes the spec names as contract. A Go reimplementation
reading only the committed OpenAPI as source of truth wouldn't learn them.

Adds responses={...} to every v1 router (emissao, certificados, series,
documentos GET/xml) covering the status codes each route actually returns
-- 201 as the default on POST /v1/emissoes (with 200 documented for the
Idempotency-Key replay case), 401 on every authenticated route, 404 where
the anti-oracle boundary applies, 409 naming the structured codes each
route raises, 413 on the certificate upload's size cap. Regenerated
docs/openapi-v1.json from app.openapi() (uv run python -c '...json.dump...'
per test_openapi_committed.py's own docstring) so the committed==generated
assertion stays green with FIX 1-4's new 409 codes included.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
jonatanritter
2026-08-08 15:36:58 -03:00
co-authored by Claude Opus 4.8
parent 260644c961
commit c2d2d30b70
4 changed files with 177 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/openapi-v1.json
+73 -9
View File
@@ -1166,6 +1166,12 @@
"204": {
"description": "Successful Response"
},
"401": {
"description": "API key ausente ou inv\u00e1lida"
},
"404": {
"description": "Nenhum certificado vivo para este (tenant_ref, branch_ref) -- anti-oracle"
},
"422": {
"content": {
"application/json": {
@@ -1234,6 +1240,12 @@
},
"description": "Successful Response"
},
"401": {
"description": "API key ausente ou inv\u00e1lida"
},
"404": {
"description": "Nenhum certificado vivo para este (tenant_ref, branch_ref) -- anti-oracle"
},
"422": {
"content": {
"application/json": {
@@ -1311,15 +1323,17 @@
},
"description": "Successful Response"
},
"401": {
"description": "API key ausente ou inv\u00e1lida"
},
"409": {
"description": "`detail.code`=`certificate_upload_conflict` -- upload concorrente venceu a corrida"
},
"413": {
"description": "Certificado excede o tamanho m\u00e1ximo permitido (262144 bytes)"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
"description": "PFX inv\u00e1lido/senha incorreta, CNPJ do certificado diverge do declarado, certificado vencido ou ainda n\u00e3o vigente"
}
},
"summary": "Upload Certificate Endpoint",
@@ -1438,6 +1452,9 @@
},
"description": "Successful Response"
},
"401": {
"description": "API key ausente ou inv\u00e1lida"
},
"422": {
"content": {
"application/json": {
@@ -1497,6 +1514,12 @@
},
"description": "Successful Response"
},
"401": {
"description": "API key ausente ou inv\u00e1lida"
},
"404": {
"description": "Documento fiscal n\u00e3o encontrado (ou de outro product/tenant -- anti-oracle)"
},
"422": {
"content": {
"application/json": {
@@ -1550,10 +1573,17 @@
"content": {
"application/json": {
"schema": {}
}
},
"application/xml": {}
},
"description": "Successful Response"
},
"401": {
"description": "API key ausente ou inv\u00e1lida"
},
"404": {
"description": "Documento fiscal n\u00e3o encontrado (ou de outro product/tenant -- anti-oracle)"
},
"422": {
"content": {
"application/json": {
@@ -1616,6 +1646,16 @@
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FiscalDocumentRead"
}
}
},
"description": "Idempotency-Key repetida -- documento j\u00e1 emitido devolvido (replay, created=False)"
},
"201": {
"content": {
"application/json": {
"schema": {
@@ -1625,6 +1665,12 @@
},
"description": "Successful Response"
},
"401": {
"description": "API key ausente ou inv\u00e1lida"
},
"409": {
"description": "Conflito estruturado -- `detail.code` identifica a causa: `fiscal_config_missing` (certificado/s\u00e9rie ausentes ou certificado vencido), `emitente_certificate_cnpj_mismatch` (CNPJ do emitente diverge do certificado da filial), `pagamento_total_diverge` (\u03a3 vPag \u2260 vNF), `fiscal_document_conflict` (colis\u00e3o de chave de acesso)."
},
"422": {
"content": {
"application/json": {
@@ -1720,6 +1766,9 @@
},
"description": "Successful Response"
},
"401": {
"description": "API key ausente ou inv\u00e1lida"
},
"422": {
"content": {
"application/json": {
@@ -1777,6 +1826,12 @@
},
"description": "Successful Response"
},
"401": {
"description": "API key ausente ou inv\u00e1lida"
},
"409": {
"description": "`detail.code`=`duplicate_fiscal_series` -- j\u00e1 existe uma s\u00e9rie fiscal (live ou soft-deletada) para este (tenant_ref, branch_ref, document_model, serie)"
},
"422": {
"content": {
"application/json": {
@@ -1846,6 +1901,15 @@
},
"description": "Successful Response"
},
"401": {
"description": "API key ausente ou inv\u00e1lida"
},
"404": {
"description": "S\u00e9rie fiscal n\u00e3o encontrada (ou de outro product -- anti-oracle)"
},
"409": {
"description": "`detail.code`=`fiscal_series_number_regression`"
},
"422": {
"content": {
"application/json": {