imperio-api 1.1.0

Python SDK for Imperio Utilities API — developer tools, Italian validators, FatturaPA, Secret Scanner, PDF processing, AI tools

Imperio API — Python SDK

Official Python SDK for Imperio Utilities — the developer tools platform for B2B automation.

Installation

pip install imperio-api

Quick Start

Get your API key at imperioutils.com/enterprise.

from imperio import ImperioClient

client = ImperioClient("empire_live_your_key_here")

Features

Secret Scanner — CI/CD ready

Detect exposed credentials before they hit production.

# Scan source code
result = client.scan_secrets(open("app.py").read(), filename="app.py")
print(result["risk_score"])      # CLEAN | LOW | MEDIUM | HIGH | CRITICAL
print(result["total"])           # number of findings
for f in result["findings"]:
    print(f["severity"], f["type"], f["line"], f["masked_value"])

Values are always masked in the response — safe to log.

Italian Validators (batch)

Validate CF, P.IVA, IBAN, CAP in a single call (up to 500 items).

result = client.validate_italian_batch([
    {"type": "cf",   "value": "RSSMRA85T10A562S"},
    {"type": "piva", "value": "12345678901"},
    {"type": "iban", "value": "IT60X0542811101000000123456"},
    {"type": "cap",  "value": "00100"},
])
print(result["valid_count"], "/", result["total"])

FatturaPA Parser

Parse Italian electronic invoices (SDI XML format, versions 1.2 and 1.3).

xml = open("fattura.xml").read()
result = client.parse_fattura_pa(xml)
print(result["cedente_prestatore"])      # seller info
print(result["cessionario_committente"]) # buyer info
for f in result["fatture"]:
    print(f["numero"], f["totale"])

GDPR Anonymization (batch)

Remove PII from text — regex-based, no AI, fully deterministic.

result = client.anonymize_batch(
    texts=["Mario Rossi, via Roma 1, [e-mail]"],
    level="standard"   # or "aggressive"
)
print(result["results"][0]["anonymized"])
# "[NOME] [NOME], [INDIRIZZO], [EMAIL]"

AI Tools

# Extract structured data from invoice text
invoice = client.extract_invoice_ai("Fattura n. 123 del 01/06/2026 ...")

# Analyze a contract for risks and clauses
analysis = client.analyze_contract(contract_text, language="it")

# Summarize long text
summary = client.summarize(text, style="bullets")  # brief | detailed | bullets

GitHub Actions CI/CD

Use the Secret Scanner template to scan every PR automatically:

- name: Install Imperio SDK
  run: pip install imperio-api

- name: Scan for secrets
  env:
    IMPERIO_API_KEY: ${{ secrets.IMPERIO_API_KEY }}
  run: python -c "
    from imperio import ImperioClient
    import os, sys
    client = ImperioClient(os.environ['IMPERIO_API_KEY'])
    result = client.scan_secrets(open('app.py').read())
    if result['critical'] > 0: sys.exit(1)
  "

Error Handling

from imperio.exceptions import ImperioError, AuthenticationError, InsufficientCreditsError

try:
    result = client.scan_secrets(code)
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError:
    print("Top up credits at imperioutils.com/billing")
except ImperioError as e:
    print(f"API error {e.status_code}: {e}")

Authentication

All requests use X-API-Key header. Keys follow the empire_live_* format and are managed at imperioutils.com/enterprise.

Links

• Documentation
• API Reference
• Get API Key
• GitHub
• Issues