API Reference

Una REST API per estrarre dati strutturati dai documenti. Invia un file, ricevi JSON strutturato.

Ottieni API key gratis →Vedi documentazione completa →Postman Collezione Postman
REST APIRisposte JSONWebhooks60+ lingue

Autenticazione

Tutte le richieste richiedono un header X-API-Key . Ottieni la tua chiave da Settings → API nel tuo account Airparser.

cURL
curl https://api.airparser.com/inboxes \
  -H "X-API-Key: YOUR_API_KEY"

Conserva la tua API key in modo sicuro: trattala come una password.

Analizza documenti

Carica qualsiasi file e ricevi tutti i dati estratti in una singola richiesta sincrona: nessun webhook, nessun polling, nessuna seconda chiamata. La risposta contiene tutti i campi estratti come JSON strutturato, pronto per l'uso immediato nel tuo workflow.

POST/inboxes/{inbox_id}/upload-syncDocumentazione API →
curl \
  -X POST \
  https://api.airparser.com/inboxes/<INBOX_ID>/upload-sync \
  -F 'file=@./receipt.pdf' \
  -H "X-API-Key: <YOUR_API_KEY>"import requests

header = {"X-API-Key": "<API_KEY>"}
url = "https://api.airparser.com/inboxes/<INBOX_ID>/upload-sync"

with open('invoice.pdf', 'rb') as f:
    files = {'file': f}
    with requests.request("POST", url, files=files, headers=header) as response:
        print('response: ', response)const fetch = require("node-fetch");
const fs = require("fs");
const FormData = require("form-data");

const APIKEY = "<YOUR_API_KEY>";
const inboxId = "<INBOX_ID>";
const filePath = "/path/to/your/file.pdf";
const metadata = { foo: "bar" };

async function parseDocument(inboxId, filePath, metadata) {
  const url = `https://api.airparser.com/inboxes/${inboxId}/upload-sync`;

  const fileStream = fs.createReadStream(filePath);

  const form = new FormData();
  form.append("file", fileStream);
  form.append("meta", JSON.stringify(metadata));

  try {
    const response = await fetch(url, {
      method: "POST",
      body: form,
      headers: {
        "X-API-Key": APIKEY,
      },
    });

    const docId = await response.json();
    console.log(response.status);
    console.log("Document id:", docId);
  } catch (e) {
    console.error("Error:", e.message);
  }
}

parseDocument(inboxId, filePath, metadata);<?php

$apikey = '<API_KEY>';
$url = 'https://api.airparser.com/inboxes/<INBOX_ID>/upload-sync';
$filepath = './invoice.pdf';

$curl = curl_init();

curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'X-API-Key: ' . $apikey
));
curl_setopt($curl, CURLOPT_POST, true);

$meta = array(
  'foo' => 'bar',
  'my_id' => 42,
);
$metaJson = json_encode($meta);

curl_setopt($curl, CURLOPT_POSTFIELDS, array(
    'file' => curl_file_create($filepath, 'application/pdf', 'invoice.pdf'),
    'meta' => $metaJson
));

$response = curl_exec($curl);
curl_close($curl);

echo $response;
Risposta200 OK
{
  "doc_id": "64abc123def456...",
  "parsing_in_progress": false,
  "status": "parsed",
  "name": "invoice.pdf",
  "content_type": "application/pdf",
  "created_at": "2026-03-10T12:00:00.000Z",
  "processed_at": "2026-03-10T12:00:04.321Z",
  "json": {
    "invoice_number": "INV-001",
    "vendor": "Acme Corp",
    "total": 1250.00,
    "currency": "USD",
    "date": "2024-01-15"
  }
}

Recupera dati estratti

Recupera un documento tramite ID per ottenere stato di estrazione e risultati. Interroga questo endpoint o usa webhooks per sapere quando l'elaborazione è completa.

GET/documents/{document_id}
cURL
curl https://api.airparser.com/documents/doc_abc123 \
  -H "X-API-Key: YOUR_API_KEY"
Risposta200 OK
{
  "doc_id": "64abc123def456...",
  "parsing_in_progress": false,
  "status": "parsed",
  "name": "invoice.pdf",
  "content_type": "application/pdf",
  "created_at": "2026-03-10T12:00:00.000Z",
  "processed_at": "2026-03-10T12:00:04.321Z",
  "json": {
    "invoice_number": "INV-001",
    "vendor": "Acme Corp",
    "total": 1250.00,
    "date": "2024-01-15"
  }
}

Definisci schema di estrazione

Definisci quali campi estrarre. Supporta campi scalari, liste (per righe) ed enum.

POST/inboxes/{inbox_id}/schema
{
  "fields": [
    {
      "type": "scalar",
      "data": {
        "name": "invoice_number",
        "description": "Invoice reference number",
        "type": "string",
        "default_value": ""
      }
    },
    {
      "type": "list",
      "data": {
        "name": "items",
        "description": "List of items in the invoice",
        "attributes": [
          {
            "name": "description",
            "description": "Item description",
            "type": "string",
            "default_value": ""
          },
          {
            "name": "amount",
            "description": "Item amount",
            "type": "decimal",
            "default_value": "0.00"
          }
        ]
      }
    },
    {
      "type": "enum",
      "data": {
        "name": "payment_status",
        "description": "Current payment status",
        "values": ["paid", "pending", "overdue"]
      }
    }
  ]
}

Post-processing

Esegui codice Python sui dati estratti prima dell'invio alle integrazioni. Aggiungi logica di business, unisci campi, formatta valori.

Unisci campi
# Merge first and last name into full name
data['fullname'] = data['first_name'] + " " + data['last_name']

# Using f-strings (recommended)
data["fullname"] = f"{data['first_name']} {data['last_name']}"

# Using format() function
data['fullname'] = '{} {}'.format(data['first_name'], data['last_name'])
Logica condizionale
# Only process invoices above certain amount
if float(data.get('total_amount', 0)) > 1000:
    data['priority'] = 'high'
else:
    data['priority'] = 'normal'

# Add timestamp
import datetime
data['processed_at'] = datetime.datetime.now().isoformat()

Esplora tecniche avanzate ed esempi di post-processing:

Guida post-processing →Esempi di codice →

Webhooks

Airparser invia una richiesta POST al tuo endpoint quando l'estrazione è completa. Rispondi con 200 per confermare.

Passaggi di configurazione

  1. 1 Copia l'URL del tuo endpoint webhook dal tuo server o da un servizio come ngrok.
  2. 2 Vai su Integrations → Webhooks nel tuo account Airparser.
  3. 3 Clicca "Create a webhook" e incolla l'URL del tuo endpoint.
  4. 4 Testa il webhook con un documento di esempio per verificare l'integrazione.
import json
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    payload = request.data
    data = json.loads(payload)

    # Process the parsed data
    # data contains all extracted fields

    return {'success': True}

if __name__ == '__main__':
    app.run(port=4242)const express = require('express');
const app = express();

app.post('/webhook', express.raw({type: 'application/json'}), (request, response) => {
  const payload = request.body;
  const data = JSON.parse(payload);

  // Process the parsed data
  // data contains all extracted fields

  // Return 200 to acknowledge receipt
  response.send();
});

app.listen(4242, () => console.log('Running on port 4242'));<?php
$payload = @file_get_contents('php://input');
$data = json_decode($payload, true);

// Process the parsed data
// $data contains all extracted fields

// Always return 200 to acknowledge receipt
http_response_code(200);
echo "OK";

Risorse

Cerchi una panoramica non tecnica? Leggi Che cos'è una Document Extraction API : copre il concetto, i casi d'uso e come funziona l'API di Airparser senza esempi di codice.

Documentazione API completa

Riferimento API completo con tutti gli endpoint, parametri ed esempi.

Quick Start

Segui la guida passo passo per iniziare in pochi minuti.

Guida post-processing

Impara a trasformare i dati estratti con script Python.