Guide de demarrage

Ce guide explique comment obtenir une cle API et envoyer une premiere requete d'extraction.

Etape 1 - Creer un compte gratuit

Inscrivez-vous sur parsurai.com sans carte bancaire. L'offre Free inclut 100 extractions par mois et la detection automatique de locale.

Etape 2 - Verifier l'e-mail et recuperer la cle API

Cliquez sur le lien de verification recu par e-mail. La page de confirmation affiche votre cle API -- c'est la seule fois ou elle est affichee en entier. Copiez-la avant de quitter cette page.

Les cles portent le prefixe sk_live_. Le Developer Dashboard n'affiche ensuite que le prefixe, jamais la cle complete : si vous ne l'avez pas enregistree, creez-en une nouvelle depuis Parametres -> Cles API ; l'ancienne reste valide jusqu'a ce que vous la supprimiez.

export PARSURAI_API_KEY="sk_live_your_actual_key_here"

Etape 3 - Envoyer la premiere extraction

L'endoint texte accepte un body JSON avec text et locale optionnel. Les comptes Free doivent utiliser auto; les locales explicites exigent Hobby ou superieur.

curl -X POST https://api.parsurai.com/v1/extract \
  -H "X-API-Key: $PARSURAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "INVOICE\nFrom: Acme Ltd...\nTotal: £1,200.00", "locale": "auto"}'

Etape 4 - Comprendre la reponse

Une reponse 200 OK suit le schema d'extraction backend:

{
  "invoice_id": "2f7d7f8a-32fb-4a7c-a3b1-53b61b64252f",
  "invoice": {
    "document_type": "invoice",
    "vendor": {
      "name": "Acme Ltd",
      "address": "123 High Street, London EC1A 1BB",
      "email": null,
      "phone": null,
      "tax_id": "GB123456789",
      "iban": "GB29NWBK60161331926819",
      "bank_name": null
    },
    "buyer": {
      "name": "Buyer GmbH",
      "address": null,
      "email": null,
      "phone": null,
      "tax_id": "DE123456789",
      "iban": null,
      "bank_name": null
    },
    "invoice_number": "INV-2026-001",
    "issue_date": "2026-06-13",
    "due_date": "2026-07-13",
    "billing_period_start": null,
    "billing_period_end": null,
    "reference_numbers": [],
    "line_items": [
      {
        "description": "Software Subscription - Annual",
        "quantity": 1,
        "unit": null,
        "unit_price": 1200.0,
        "discount": null,
        "total": 1200.0,
        "tax_rate": 0.0
      }
    ],
    "subtotal": 1200.0,
    "discount_total": null,
    "tax_breakdown": [
      {
        "tax_type": "VAT",
        "rate": 0.0,
        "taxable_amount": 1200.0,
        "tax_amount": 0.0
      }
    ],
    "tax_total": 0.0,
    "total_amount": 1200.0,
    "amount_paid": null,
    "amount_due": 1200.0,
    "currency": "GBP",
    "payment_terms": "Net 30",
    "payment_instructions": null,
    "locale": "en",
    "confidence": 0.98,
    "field_confidence": {},
    "notes": []
  },
  "duplicate_risk": null,
  "anomalies": [],
  "confidence_low": false,
  "field_bboxes": null
}

Champs principaux

Etape 5 - Parser un fichier

Utilisez l'endpoint fichier pour les uploads PDF ou image. L'indice de locale est un query parameter.

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

Workflows texte, fichier et URL

Utilisez POST /v1/extract quand le texte de facture existe deja dans votre backend, par exemple depuis un parseur d'email ou un champ de note ERP. C'est le chemin d'integration le plus leger parce que le body est du JSON simple.

Utilisez POST /v1/extract/file quand votre backend recoit un PDF ou une image. Envoyez le fichier en multipart form data et passez locale=auto dans la query, sauf si votre offre autorise les indices de locale explicites.

Utilisez POST /v1/extract/url quand le document est deja stocke sur une URL publique. L'API recupere l'URL cote serveur, donc le fichier doit etre accessible sans cookies navigateur ni reseau prive.

Scans en lot, division et classification

Tous les documents ne sont pas une facture unique et propre. Les endpoints de documents AP de Parsurai gerent les lots multi-pages et les scans de types melanges:

• POST /v1/documents/split - Regroupe un lot PDF multi-pages en documents logiques selon les limites de documents, transformant un upload de 20 pages en 5 factures separees.
• POST /v1/documents/crop - Detecte et isole plusieurs documents physiques scannes ou photographies ensemble sur une seule page.
• POST /v1/documents/classify - Identifie le type de document (invoice, purchase_order, delivery_note, receipt, bank_statement, etc.) avec un score de confiance avant le parsing.
• POST /v1/documents/extract - Parse les bons de commande, bons de livraison, avis de paiement et autres documents AP via l'enveloppe de document AP dediee, distincte des endpoints de facture ci-dessus.

Ces endpoints sont disponibles sur les offres Pro et Business. Voir Extraction de documents AP, Division automatique, Recadrage automatique et Classification AP pour la reference complete.

Verifier usage et erreurs

Apres une extraction reussie, appelez GET /v1/usage pour afficher calls_this_month, quota, plan_name et resets_on dans votre propre UI. Si une extraction renvoie quota_exceeded, arretez le trafic d'extraction jusqu'a la date de reset ou passez a une offre superieure.

Si une requete renvoie feature_not_in_plan, conservez le resultat d'extraction enregistre mais masquez le workflow restreint dans votre UI. Exemples courants: indices de locale explicites sur Free, ZUGFeRD sous Pro et fonctions d'intelligence sous Pro.

Etapes suivantes