API d'extraction de factures

Parsurai expose des endpoints d'extraction pour texte, uploads de fichiers, URLs distantes et PDFs ZUGFeRD niveau Pro. L'extraction standard utilise la meme enveloppe de reponse pour tous les formats d'entree.

Vue d'ensemble des endpoints

Extraire depuis du texte

{
  "text": "Facture de Supplier Inc. Numero INV-9812. Total: 1500 EUR. TVA: 19%.",
  "locale": "auto"
}

curl -X POST https://api.parsurai.com/v1/extract \
  -H "X-API-Key: $PARSURAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Facture de Supplier Inc. INV-9812. Total: 1500 EUR. TVA: 19%.", "locale": "auto"}'

Extraire depuis un fichier

Envoyez un PDF ou une image en multipart. L'indice de locale est lu depuis la query.

curl -X POST "https://api.parsurai.com/v1/extract/file?locale=fr" \
  -H "X-API-Key: $PARSURAI_API_KEY" \
  -F "file=@invoice.pdf"

Extraire depuis une URL

{
  "url": "https://example.com/invoices/inv-01.jpg",
  "locale": "auto"
}

Schema de reponse

{
  "invoice_id": "2f7d7f8a-32fb-4a7c-a3b1-53b61b64252f",
  "invoice": {
    "document_type": "invoice",
    "vendor": {
      "name": "Supplier Inc.",
      "address": "Main Street 1, 10115 Berlin",
      "email": null,
      "phone": null,
      "tax_id": "DE123456789",
      "iban": "DE89370400440532013000",
      "bank_name": null
    },
    "buyer": {
      "name": "Buyer GmbH",
      "address": null,
      "email": null,
      "phone": null,
      "tax_id": "DE987654321",
      "iban": null,
      "bank_name": null
    },
    "invoice_number": "INV-9812",
    "issue_date": "2026-06-13",
    "due_date": "2026-07-13",
    "billing_period_start": null,
    "billing_period_end": null,
    "reference_numbers": [{ "type": "order", "value": "PO-7781" }],
    "line_items": [
      {
        "description": "Consulting",
        "quantity": 1,
        "unit": "hour",
        "unit_price": 1500.0,
        "discount": null,
        "total": 1500.0,
        "tax_rate": 0.19
      }
    ],
    "subtotal": 1500.0,
    "discount_total": null,
    "tax_breakdown": [
      {
        "tax_type": "VAT",
        "rate": 0.19,
        "taxable_amount": 1500.0,
        "tax_amount": 285.0
      }
    ],
    "tax_total": 285.0,
    "total_amount": 1785.0,
    "amount_paid": null,
    "amount_due": 1785.0,
    "currency": "EUR",
    "payment_terms": "Net 30",
    "payment_instructions": "Pay by bank transfer.",
    "locale": "de",
    "confidence": 0.97,
    "field_confidence": {},
    "notes": []
  },
  "duplicate_risk": null,
  "anomalies": [],
  "confidence_low": false,
  "field_bboxes": null
}

Reference des champs

Locales supportees

Les valeurs explicites autres que auto exigent Hobby, Starter, Pro ou Business.

Champs de reponse limites par offre

La reponse top-level contient toujours duplicate_risk, anomalies, confidence_low et field_bboxes, mais leurs valeurs dependent de l'offre et du type d'entree.

Mode de precision (Accuracy Mode)

Pour prendre en charge les workflows de haute precision, Parsurai propose un Mode de precision ameliore (Enhanced Accuracy Mode) accessible uniquement avec les offres Pro et Business.

Paramètres

• accuracy_mode (string) : Defini sur standard ou enhanced.
  • Valeur par defaut : standard
  • Pris en charge sur : Le body JSON pour POST /v1/extract and POST /v1/extract/url ; le parametre de requete accuracy_mode pour POST /v1/extract/file.
  • Restriktion d'offre : enhanced est reserve aux offres Pro et Business. Les requetes avec le mode de precision enhanced sur des offres inferieures echoueront avec une erreur 402 feature_not_in_plan.

Fonctionnement

Contrairement a l'extraction standard, le Mode de precision ameliore applique :

1. Validateurs deterministes : Execution de regles de verification (par exemple, verifier que les postes correspondent aux sous-totaux, totaux, calculs de TVA/taxes, et dates).
2. Une tentative de correction bornee : Si une validation echoue, le moteur effectue une unique tentative de correction a l'aide du LLM avec les details de l'erreur.
3. Compromis : En raison du passage de validation et de correction, le mode ameliore entraine une latence plus elevee et un cout de modele supplementaire (jusqu'a deux appels de modele par extraction de facture).

Exemple d'objet accuracy

Lorsque accuracy_mode est demande (ou renvoye dans une reponse reservee aux plans superieurs), la reponse d'extraction contient un objet de metadaten accuracy avec des statistiques detaillees :

{
  "invoice_id": "2f7d7f8a-32fb-4a7c-a3b1-53b61b64252f",
  "invoice": {
    "document_type": "invoice",
    "vendor": {
      "name": "Supplier Inc.",
      "tax_id": "DE123456789",
      "iban": "DE89370400440532013000"
    },
    "subtotal": 1500.0,
    "tax_total": 285.0,
    "total_amount": 1785.0,
    "confidence": 0.97
  },
  "accuracy": {
    "mode": "enhanced",
    "correction_attempted": true,
    "correction_used": true,
    "validators_failed": [
      "subtotal_tax_match"
    ],
    "unresolved_warnings": [],
    "findings": [],
    "latency_ms": 1250,
    "model_calls": 2,
    "tokens_input": 1850,
    "tokens_output": 450
  }
}

Reference des champs de l'objet accuracy

Limites des documents

Chaque upload est borne avant l'extraction. Un document au-dela d'une limite est rejete avec le code correspondant, et non traite partiellement.

100 pages constituent un plafond serveur absolu, pas un droit lie a l'offre. La limite de pages applicable a une requete est la plus basse entre ce plafond et le quota de votre offre pour l'endpoint appele. Aucun endpoint et aucune offre future ne peut envoyer plus de 100 pages.

Le texte extrait est plafonne a 400 000 caracteres. Ce plafond tronque au lieu d'echouer: un document plus long est extrait jusqu'a cette limite puis traite normalement.

PDF scannes et uniquement composes d'images

Un PDF issu d'un scan ne contient aucune couche de texte : la lecture du PDF ne renvoie donc rien. Parsurai le detecte et relit le meme fichier par OCR avant l'extraction, de sorte qu'un scan encapsule dans un PDF se comporte comme le meme scan importe en JPEG ou PNG.

Le repli OCR est borne independamment des limites de pages ci-dessus : il s'applique aux documents de 10 pages au maximum. Un scan plus long est rejete avec 422 pdf_no_extractable_text plutot qu'envoye a la reconnaissance. Si l'OCR ne parvient pas non plus a lire le fichier, ou s'il est momentanement indisponible, la requete echoue avec 422 pdf_no_extractable_text ou 503 ocr_unavailable -- la requete n'atteint jamais le modele avec un document vide.

Reponses d'erreur courantes

428 est la seule erreur qu'un retry ne resout pas. Elle signifie que le titulaire du compte n'a pas encore accepte des conditions generales ou une politique de confidentialite mises a jour. Tout endpoint authentifie la renvoie tant que ce n'est pas fait, depuis le tableau de bord — une cle API ne peut pas accepter a sa place. Dans une integration non supervisee, cela releve de l'alerte, pas de la boucle de retry.

---

Extraction de documents AP (Pro et Business)

La famille d'endpoints /v1/documents extrait des documents Accounts Payable au-dela des factures standard. Elle couvre les e-factures DACH ainsi que les documents d'achat, livraison, paiement et releves bancaires.

Apercu des endpoints

Types de documents et formats source

Les reponses AP utilisent une enveloppe document distincte avec document_type et source_format. document_type decrit le document metier, par exemple purchase_order, delivery_note, remittance_advice, payment_advice ou bank_statement. source_format decrit le format d'entree, par exemple pdf, image, xrechnung, zugferd, factur_x ou peppol_bis_billing.

XRechnung, ZUGFeRD/Factur-X et Peppol BIS Billing 3.0 sont parses de facon deterministe lorsque le profil est supporte. Les profils XML non supportes renvoient 422 unsupported_einvoice_profile.

{
  "document_id": "3a1b2c4d-...",
  "document_type": "invoice",
  "source_format": "xrechnung",
  "schema_version": "1.0",
  "document": {},
  "classification": {
    "document_type": "invoice",
    "confidence": 0.98,
    "signals": ["xml_profile_xrechnung"]
  },
  "warnings": []
}