Factum Parse API

What we do and what we don’t

A tax parser. Not an archive. Not a data warehouse. Not a training engine.

Does.

• Extracts invoices, F24 and tax documents — FatturaPA XML, text PDF, free text — into structured, validated JSON with verified arithmetic.
• Pseudonymizes every sensitive data point (22 categories) before any AI call. The model sees placeholders, never your data.
• Processes 100% in RAM: zero disk writes, zero retention, zero training on your documents.
• Answers deterministically on XML in ~12 ms, without touching any model.

Doesn’t.

• No OCR. A scanned PDF is rejected with a clean error (HTTP 422). We don’t invent text that isn’t there.
• No clear-text data to any model. If pseudonymization isn’t available, the system stops (HTTP 503). Never a degradation.
• Nothing is kept. After the response, nothing of your document remains: no file, no dictionary, no content logs.

If this is what you need, you can try it in a minute. If it isn’t, we didn’t waste your time.

---

⚡️ Quickstart — Time-to-first-call < 60s

Send a textual payload (invoice, F24, free text) and get back a structured DocumentEnvelope v2. Authentication: X-API-Key header.

Fastest First Call Raw Text / JSON — test the endpoint in 30 seconds with a text payload. For production PDF/XML/multipart workflows, see Endpoint Reference.

cURL

curl -X POST https://api.factum.pyragogy.org/v1/parse \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Invoice no. 2026/001 dated 15/03/2026. Supplier: ACME S.r.l. — Via Roma 1, Milan. VAT IT01234567890. Client: Mario Rossi. Total: € 1,220.00. Taxable: € 1,000.00. VAT 22%: € 220.00.",
    "doc_type": "auto"
  }'

Python (httpx)

import httpx

payload = {
    "text": "Invoice no. 2026/001. Supplier: ACME S.r.l. Total: € 1,220.00.",
    "doc_type": "auto",
}

resp = httpx.post(
    "https://api.factum.pyragogy.org/v1/parse",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json=payload,
)
resp.raise_for_status()
print(resp.json())

TypeScript (fetch)

// Replace with your actual API key
const API_KEY = "YOUR_API_KEY";

const response = await fetch("https://api.factum.pyragogy.org/v1/parse", {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Invoice no. 2026/001. Supplier: ACME S.r.l. Total: € 1,220.00.",
    doc_type: "auto",
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

Go

package main

import (
    "bytes"
    "fmt"
    "net/http"
)

func main() {
    body := []byte(`{"text":"Invoice no. 2026/001. Supplier: ACME S.r.l. Total: € 1,220.00.","doc_type":"auto"}`)
    req, _ := http.NewRequest("POST", "https://api.factum.pyragogy.org/v1/parse", bytes.NewReader(body))
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    fmt.Println(res.Status)
}

PHP

<?php
$apiKey = 'YOUR_API_KEY'; // Sostituisci con la tua chiave
$ch = curl_init('https://api.factum.pyragogy.org/v1/parse');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'text' => 'Invoice no. 2026/001. Supplier: ACME S.r.l. Total: € 1,220.00.',
        'doc_type' => 'auto',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
curl_close($ch);
echo $response;

⚡

Recommended for production integrations: FatturaPA XML. Deterministic path: ~12 ms end-to-end, no LLM, stable cost. The text-PDF path extracts via LLM in ~10–15 s (improvement margin on the roadmap); scanned PDFs are not supported (HTTP 422). Details and chart: Processing latency.

---

🧪 Try it in your browser

Enter your X-API-Key and a document excerpt to test the endpoint directly from your browser. The response is displayed with syntax highlighting.

🔑 X-API-Key

🎯 Quick Presets

Preset 1: FatturaPA XML (Fast-path deterministic, 100% RAM)Preset 2: Free-text / Receipt (LLM Fallback with PII Sanitization)Preset 3: Invalid Document (RFC 7807 Error Demo — 422 Unprocessable)

📄 Document Text

📋 Document Type

autofatturaf24generico

Show PII pseudonymization payload

Zero Disk I/O

🛡️ Pseudonymized Payload (sent to LLM)

▶️ Run Parse (Demo)

📋 Copy JSON

📦 Response JSON

⚠️ Demonstrational execution with rate-limiting. Your key is never stored nor sent to third parties.

Response — ParseResponse with DocumentEnvelope v2

{
  "job_id": "3f2b5e6a-0000-4000-8000-000000000004",
  "status": "done",
  "document_type": "invoice",
  "provider_used": "fast-path",
  "prompt_version": "fast-path-v1",
  "confidence": 1.0,
  "cost_usd": 0.0,
  "tokens": 0,
  "fallbacks": [],
  "content_hash": "a1b2c3d4e5f67890abcdef1234567890abcdef12",
  "result": {
    "schema_version": "2.0",
    "document_type": "invoice",
    "meta": {
      "confidence": 1.0,
      "provider": "fast-path",
      "prompt_version": "fast-path-v1"
    },
    "payload": {
      "kind": "invoice",
      "cedente_prestatore": {
        "Denominazione": "ACME S.r.l.",
        "Indirizzo": "Via Roma 1, Milano",
        "PartitaIVA": "IT01234567890"
      },
      "cessionario_committente": {
        "Denominazione": "Mario Rossi"
      },
      "corpi": []
    }
  },
  "error": null
}

Key points

Aspect	Detail
Auth	X-API-Key header on business endpoints; fail-closed
Document type	auto detects; explicit fattura, f24, generico available
ZDR Privacy	Direct text is stateless; PII mapping is request-scoped RAM
Deterministic	FatturaPA XML → 100% deterministic, 0 tokens, 0 cost
LLM fallback	PDF/invoice images → PII pseudonymization → LLM extraction

What’s next?

• API Reference — Endpoints for full HTTP contract details
• Privacy Model for zero-retention semantics and the ZDR boundary
• Rizzo PII Sidecar for the pseudonymization pipeline

---

💰 Purchase channels

Factum Parse is available through two channels, depending on your needs.

📡 Zyla API Hub — subscription (recommended)

Tier	Price / month	Requests / month	Rate limit	Best for
Basic	$24.99	2,000	60 req/min	Testing, low volume
Pro	$49.99	5,000	120 req/min	Production, mid volume
ProPlus	$99.99	15,000	180 req/min	Medium-high volume
Premium	$199.99	40,000	240 req/min	Intensive production
Elite	$499.99	120,000	240 req/min	High volume
Ultimate	$999.99	300,000	240 req/min	Enterprise

✓ No fixed cost: a Basic customer pays $24.99 and gets 2,000 requests.
✓ API Key is auto-generated on subscription.
✓ Zyla handles payments, invoicing, rate limiting, and per-tier credits.

➡️ Subscribe on Zyla API Hub

🍋 Lemon Squeezy — one-off pack

For occasional use without a recurring subscription:

Product	Price	Documents
Pack 100 documents	€9.99 one-time	100 elaborations

No auto-renewal. License Key activates on order confirmation and lasts until credits are consumed.

➡️ Buy pack 100 docs — €9.99

---

💬 Support & Contacts

For technical support, enterprise contracts and commercial inquiries:

• Email: info@pyragogy.org
• GitHub Issues: factum-community — bug reports, parser requests, discussions
• Documentation: docs.factum.pyragogy.org