Conector Scardua — recebe da API da FLS e entrega no Oracle do cliente

Servico que roda dentro da rede da Comercial Scardua e faz a ponte entre a
API publica da FLS (na VPS) e o Oracle privado (10.16.x), inalcancavel pela
internet.

Fluxo: Holmes -> API na VPS (trata e cifra) -> ESTE conector (abre e valida)
-> Oracle.

Recebimento:
- app/v1/compras.py: POST /v1/compras/dados
- app/services/cripto.py: abre o envelope AES-256-GCM + RSA-OAEP-SHA256 com a
  chave privada. O GCM autentica: corpo adulterado levanta InvalidTag em vez
  de devolver lixo
- app/schemas.py: modulo folha (so pydantic) com a config e o contrato
  PayloadCompras, que espelha o da API. Fora de sincronia devolve 422 de
  proposito, pra falhar explicito em vez de gravar dado torto

Seguranca:
- app/seguranca.py: header X-Token com compare_digest (nao vaza por tempo de
  resposta) + allowlist de IP da VPS
- .gitignore barra configs.json.*, *.bak-*, *.pem e *.key

Config:
- app/config.py e so o carregamento do configs.json
- o bloco "vps" guarda chave privada, token e ips permitidos

Estado: ainda NAO persiste. Recebe, valida e descarta (persistido: false).
O INSERT no Oracle e a proxima fase, e tem que ser MERGE por id_processo
porque o Holmes reentrega webhook.

Docs em docs/ — arquitetura, a decisao do conector (opcao A, com as
alternativas descartadas), deploy e problemas conhecidos.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

app/services/controle_api.py

@@ -0,0 +1,33 @@
+# app/services/api_tracker.py
+import logging
+
+
+def registrar_contador(
+    conn, api, endpoint, metodo, status_code, sucesso, duracao_ms, erro=None
+):
+    """Grava uma linha na tabela contadores_api."""
+    cursor = conn.cursor()
+    try:
+        cursor.execute(
+            """
+            INSERT INTO orvel_ti.contadores_api
+                (api, endpoint, metodo_http, status_code, sucesso, duracao_ms, mensagem_erro)
+            VALUES
+                (:api, :endpoint, :metodo, :status, :sucesso, :duracao, :erro)
+        """,
+            {
+                "api": api,
+                "endpoint": endpoint,
+                "metodo": metodo,
+                "status": status_code,
+                "sucesso": "S" if sucesso else "N",
+                "duracao": duracao_ms,
+                "erro": erro[:500] if erro else None,
+            },
+        )
+        conn.commit()
+    except Exception as e:
+        conn.rollback()
+        logging.error(f"Falha ao gravar contador: {e}")
+    finally:
+        cursor.close()