eScanX API-viite

Kaikki mitä tarvitset älykkään asiakirja-OCR-rajapintamme integroimiseen sovelluksiisi.

Tunnistautuminen

Tunnista API-pyyntösi X-API-Key-otsikolla. Hanki API-avaimesi hallintapaneelista rekisteröitymisen jälkeen.

Sisällytä API-avaimesi jokaiseen pyyntöön:

# Sample: list async jobs (any authenticated endpoint works the same way)
curl https://api.escanx.com/api/v1/jobs \
  -H "X-API-Key: YOUR_API_KEY"

API-leikkikenttä

Kokeile poimintapäätepistettä livenä. Valitse asiakirjatyyppi, liitä API-avaimesi, lataa tiedosto ja suorita oikea pyyntö.

Asiakirjojen poiminta

Poimi rakenteellista dataa asiakirjoista (kuitit, laskut jne.) älykkään OCR-moottorimme avulla.

Pyyntö

Lähetä yksi asiakirja multipart/form-data -muodossa. Voit lisätä Idempotency-Key-otsakkeen, jolloin uudelleenyritys hakee saman poiminnan eikä veloita kahdesti.

Tiukka tyypitys: polku kertoo odottamasi asiakirjatyypin. Toisen tyyppinen asiakirja hylätään virheellä 422 — sitä ei koskaan muunneta. Käytä asynkronisia töitä, jos haluat parhaan yrityksen muunnoksen.

curl -X POST https://api.escanx.com/api/v1/extract/receipt \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@receipt.jpg"

Vastaus

Extraction-objekti on sisäkkäinen ja asiakirjatyyppikohtainen — vaihda asiakirjatyyppiä yltä nähdäksesi kunkin rakenteen.

{
  "success": true,
  "request_id": "req_abc123def456",
  "extraction_id": "ext_9f3c1a7b2d84",
  "processing_time_ms": 1250,
  "document_type": "receipt",
  "extraction": {
    "merchant": {
      "name": "Helsinki Market",
      "address": {
        "city": "Helsinki",
        "country_code": "FI"
      },
      "business_id": "1234567-8"
    },
    "buyer": {
      "name": "Aurora Digital Oy",
      "business_id": "7788990-1"
    },
    "transaction": {
      "date": "2025-01-15",
      "time": "14:30",
      "receipt_number": "A-4471"
    },
    "items": [
      {
        "line_number": 1,
        "description": "Coffee 250g",
        "quantity": 1,
        "unit_price": 4.9,
        "item_total": 4.9
      }
    ],
    "financial": {
      "subtotal": 43.1,
      "tax": [
        {
          "rate": 25.5,
          "amount": 4.75
        }
      ],
      "tax_total": 4.75,
      "total": 47.85,
      "currency": "EUR"
    },
    "payments": [
      {
        "method": "card",
        "card_type": "Visa",
        "card_last4": "4242",
        "amount": 47.85
      }
    ],
    "loyalty": {
      "card_number": "9012345678",
      "points_earned": 12,
      "points_balance": 340
    },
    "metadata": {
      "sub_type": "grocery",
      "confidence": {
        "overall": 0.97
      }
    }
  },
  "error": null,
  "credit_cost": 1,
  "item_count": 1
}

Tämän päätepisteen virheet

Poimintahistoria

Jokainen synkroninen poiminta tallennetaan. Näillä päätepisteillä haet tuloksen myöhemmin uudelleen, palaudut 504-virheestä ja tarkastelet ajamiasi poimintoja.

Listaa poiminnat

Listaa synkroniset poimintasi. Samat suodattimet ja vastausrakenne kuin GET /jobs.

Kohteen kentät

curl "https://api.escanx.com/api/v1/extractions?status=completed&page_size=20" \
  -H "X-API-Key: YOUR_API_KEY"

Hae poiminta

Yksi poiminta tuloksineen, haettavissa koko säilytysajan. Näin haet tuloksen POST /extract -kutsun 504-virheen jälkeen. Yhä käynnissä oleva poiminta selvitetään lukuhetkellä; lopputilaa edeltävät vastaukset sisältävät Retry-After: 3 -vihjeen kyselytahdista.

curl https://api.escanx.com/api/v1/extractions/EXTRACTION_ID \
  -H "X-API-Key: YOUR_API_KEY"

Poimintatilastot

Synkronisten poimintojesi koontimäärät. Vastaa GET /jobs/stats -päätepistettä.

Peruuta poiminta

Peruuta vain kun poiminta on vielä jonossa moottorilla. Yhteyden katkaiseminen ei ole peruutus — ajo suoritetaan loppuun historiaan ja veloitetaan normaalisti.

Säilytys

Tulokset ja lähetetyt tiedostot säilytetään API-säilytysajan verran, muokattavissa organisaation asetuksissa ja rajattuna pakettisi mukaan. expires_at lasketaan lukuhetkellä, joten asetuksen muutos vaikuttaa olemassa oleviin tietueisiin heti molempiin suuntiin. Poistetut resurssit vastaavat 404.

Asynkroniset työt

Lähetä asiakirjoja asynkroniseen poimintaan. Ihanteellinen suurille tiedostoille tai erätyönkuluille, joissa välitöntä tulosta ei tarvita.

Lähetä työ

Lähetä 1–20 asiakirjaa taustakäsittelyyn yhdellä pyynnöllä. Palauttaa 202-vastauksen, jossa on yksi jonossa oleva työ per tiedosto.

Kaikki tai ei mitään: jokainen tiedosto validoidaan ja koko erän jonokapasiteetti tarkistetaan ennen kuin mitään luodaan. Mikä tahansa rikkomus hylkää koko pyynnön ja nimeää virheellisen tiedoston.

Työt muuntavat aina: document_type on pyytämäsi tulosmuoto, ja toisen tyyppinen asiakirja luetaan sellaisena kuin se on ja palautetaan siinä muodossa. Tiukka tyypitys koskee vain synkronista /extract-päätepistettä.

curl -X POST https://api.escanx.com/api/v1/jobs/invoice \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@invoice-1.pdf" \
  -F "files=@invoice-2.pdf"

202-vastaus

Lähetyksen virheet

Tarkista työn tila

Pollaa työn tilaa kunnes se saavuttaa lopullisen tilan.

curl https://api.escanx.com/api/v1/jobs/JOB_ID \
  -H "X-API-Key: YOUR_API_KEY"

Lopputilan vastaukset sisältävät expires_at-kentän. Sen jälkeen tietue ja tallennettu tiedosto poistetaan ja tämä päätepiste palauttaa 404. Ikkuna on API-säilytysasetuksesi, muokattavissa organisaation asetuksissa.

Webhookit

Pollauksen sijaan anna webhook_url työtä lähettäessäsi. Päätepisteesi vastaanottaa POST-pyynnön kun työ valmistuu tai epäonnistuu. Vastaus sisältää webhook_secret-avaimen pyyntöjen allekirjoitusten vahvistamiseen.

# Submit with webhook notification (webhook_url is a query parameter,
# applied to every job in the batch)
curl -X POST "https://api.escanx.com/api/v1/jobs/invoice?webhook_url=https://your-app.com/webhooks/escanx" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@invoice-1.pdf" \
  -F "files=@invoice-2.pdf"

Tallenna työn lähetysvastauksessa palautettu webhook_secret. Käytä sitä vahvistaaksesi, että saapuvat webhook-pyynnöt ovat eScanX:ltä.

Listaa työt

Listaa poimintatyösi valinnaisilla suodattimilla.

Peruuta työ

Peruuta työ, joka on vielä jonossa. Kun käsittely alkaa, työ suoritetaan loppuun, ja myöhäinen peruutus palauttaa 400 JOB_CANCELLATION_FAILED.

Yritä työ uudelleen

Yritä epäonnistunutta työtä uudelleen. Kasvattaa poimintayritystä ja palauttaa työn jonoon. Väärä tila tai loppuun käytetyt yritykset palauttavat 400 JOB_RETRY_FAILED.

Työtilastot

Töidesi koontimäärät ja jäljellä oleva jonokapasiteetti.

curl https://api.escanx.com/api/v1/jobs/stats \
  -H "X-API-Key: YOUR_API_KEY"

Käyttötilastot

Tarkista API-käyttösi, kiintiösi ja jäljellä olevat kutsut nykyisellä laskutusjaksolla.

curl "https://api.escanx.com/api/v1/usage?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

Vastaus

Terveystarkistukset

Seuraa API:n tilaa elävyys- ja valmiuspäätepisteillä. Tunnistautumista ei vaadita.

Elävyystarkistus

Palauttaa OK jos API-palvelin on käynnissä.

curl https://api.escanx.com/health

Valmiustarkistus

Palauttaa OK jos API ja kaikki riippuvuudet (tietokanta) ovat valmiita palvelemaan pyyntöjä.

curl https://api.escanx.com/health/ready

Virheiden käsittely

API käyttää standardeja HTTP-tilakoodeja. Virhevastaukset noudattavat RFC 7807 problem+json -muotoa litteillä kentillä.

Virhevastauksen muoto

Validointivirheet (422)

Validointivirheet palauttavat 422-koodin ja detail-taulukon — yksi merkintä jokaista virheellistä kenttää kohti, kukin sisältäen sijainnin, viestin ja tyypin.

HTTP-tilakoodit

Pyyntörajoitukset

API-pyynnöt ovat rajoitettuja API-avainkohtaisesti reilun käytön ja alustan vakauden varmistamiseksi.

Miten se toimii

Pyyntörajoitukset sovelletaan API-avainkohtaisesti. Rajoituksen ylittyessä pyynnöt palauttavat HTTP 429.

Pyyntörajoitusten käsittely

Toteuta eksponentiaalinen odotus kun saat 429-vastauksen.

async function extractWithRetry(file, documentType, maxRetries = 3) {
  const formData = new FormData()
  formData.append('file', file)

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(`https://api.escanx.com/api/v1/extract/${documentType}`, {
      method: 'POST',
      headers: { 'X-API-Key': 'YOUR_API_KEY' },
      body: formData
    })

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || '5'
      await new Promise(r => setTimeout(r, parseInt(retryAfter) * 1000))
      continue
    }

    return await response.json()
  }
  throw new Error('Max retries exceeded')
}

SDK:t ja kirjastot

Viralliset SDK:t suosituille ohjelmointikielille ovat tulossa pian. Käytä toistaiseksi REST API:amme suoraan millä tahansa HTTP-asiakkaalla.

# Upload an invoice and extract structured data
curl -X POST https://api.escanx.com/api/v1/extract/invoice \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@invoice.pdf"

# Check your API usage
curl https://api.escanx.com/api/v1/usage \
  -H "X-API-Key: YOUR_API_KEY"