Python के साथ 10 मिनट में 100 इनवॉइस कन्वर्ट करें (myocr SDK ट्यूटोरियल)

एक समर्पित Python SDK क्यों मायने रखता है

यदि आप Python में प्रोडक्शन OCR शिप कर रहे हैं, तो आपके पास तीन विकल्प हैं। आप कच्चे requests के साथ API को कॉल कर सकते हैं और बॉयलरप्लेट स्वयं लिख सकते हैं — ऑथ, रिट्राई, त्रुटि मैपिंग, async जॉब के लिए पोलिंग, signed-URL डाउनलोड। आप एक सामान्य OpenAPI जनरेटर का उपयोग कर सकते हैं जो काम करने वाला लेकिन बदसूरत क्लाइंट उत्पन्न करता है। या आप एक मेंटेन्ड SDK इंस्टॉल कर सकते हैं जो प्रोटोकॉल को अमूर्त करता है और आपको व्यावसायिक कोड लिखने देता है।

यह ट्यूटोरियल तीसरे विकल्प का उपयोग करता है: myocr-client, myocr.app के लिए आधिकारिक Python SDK। 11 मिनट में आप pip install से एक स्क्रिप्ट तक जाएंगे जो 100 PDF इनवॉइस को समानांतर में कन्वर्ट करती है, कोटा और OCR त्रुटियों को सुंदर ढंग से संभालती है, और प्रत्येक जॉब के समाप्त होने पर आपके ऐप को webhook के माध्यम से सूचित करती है।

आप क्या बनाएंगे

एकल Python स्क्रिप्ट जो:

• PDF इनवॉइस का फ़ोल्डर पढ़ती है (मिश्रित डिजिटल और स्कैन)
• उन्हें /v1/batch के माध्यम से async जॉब के रूप में सबमिट करती है
• API को पोल करती है या जब प्रत्येक जॉब समाप्त हो जाता है तब webhook सूचनाएं प्राप्त करती है
• स्ट्रक्चर्ड Excel फाइलें डाउनलोड करती है (विक्रेता, ग्राहक, आइटम, कुल, GST)
• कोटा थकावट, नेटवर्क blips और प्रति-फ़ाइल OCR त्रुटियों से क्रैश हुए बिना उबरती है

कुल: ~30 लाइन व्यावसायिक कोड, साथ ही एक webhook रिसीवर यदि आप push-आधारित डिलीवरी चाहते हैं।

आवश्यकताएं

• Python 3.8+
• myocr.app/account/api से एक API key (मुफ्त tier: 100 कॉल/महीना, कार्ड नहीं)
• परीक्षण PDF इनवॉइस का एक फ़ोल्डर — या SDK रिपो में नमूना फिक्स्चर का उपयोग करें

चरण 1: इंस्टॉल करें

pip install myocr-client

बस इतना ही। SDK केवल requests पर निर्भर है। कोई नेटिव एक्सटेंशन नहीं, कोई SDK-विशिष्ट रनटाइम नहीं।

चरण 2: अपनी पहली इनवॉइस कन्वर्ट करें (sync)

from myocr_client import MyOCRClient

client = MyOCRClient(api_key="sk_live_...")  # या MYOCR_API_KEY env var सेट करें

result = client.convert("invoice.pdf", model="invoice")
result.save("invoice.xlsx")
print(f"{result.pages_used} पृष्ठ → invoice.xlsx ({result.request_id})")

यह एक पूर्ण OCR कॉल है। convert() मेथड सिंक्रोनस है और 5 MB और 10 पृष्ठों से कम की फाइलों के लिए सबसे अच्छा है। लौटाए गए ConversionResult में content (बाइट्स), pages_used, मूल model, और एक request_id शामिल है जिसे आप सर्वर लॉग में grep कर सकते हैं।

चरण 3: बैच प्रोसेसिंग के लिए async पर स्विच करें

100 इनवॉइस के लिए, आप 100 अनुक्रमिक sync कॉल नहीं चाहते — यह सीरियल लेटेंसी है। इसके बजाय /v1/batch का उपयोग करें। SDK इसे client.batch() के रूप में उजागर करता है:

from pathlib import Path
from myocr_client import MyOCRClient

client = MyOCRClient()  # env से MYOCR_API_KEY

folder = Path("./invoices")
pdfs = sorted(folder.glob("*.pdf"))[:20]  # /v1/batch अधिकतम 20 फाइलें स्वीकार करता है

batch = client.batch([str(p) for p in pdfs], model="invoice")
print(f"{batch.jobs_created} जॉब बनाए, {len(batch.errors)} त्रुटियां")

done = batch.wait_all(timeout=600)
for job in done:
    if job.is_done:
        job.download(f"out/{job.request_id}.xlsx")
    else:
        print(f"विफल: {job.request_id} — {job.error_detail}")

तीन चीजें ध्यान दें। पहला, /v1/batch एंडपॉइंट प्रति कॉल अधिकतम 20 फाइलें स्वीकार करता है — 100 इनवॉइस के लिए, फ़ोल्डर को 5 बैच में विभाजित करें। दूसरा, wait_all() प्रत्येक जॉब को व्यक्तिगत रूप से एक्सपोनेंशियल बैकऑफ (1s → 2s → 4s → 8s → 15s कैप) के साथ पोल करता है, इसलिए 100 निष्क्रिय sleep(1) कॉल आपके रेट लिमिट को नहीं जलाते। तीसरा, यदि एकल फ़ाइल OCR निष्कर्षण में विफल हो जाती है, तो केवल वह Job failed में समाप्त होता है — अन्य सामान्य रूप से पूरे होते हैं।

चरण 4: 5 चंक्स में 100 इनवॉइस प्रोसेस करें

from pathlib import Path
from myocr_client import MyOCRClient

client = MyOCRClient()
folder = Path("./invoices")
all_pdfs = sorted(folder.glob("*.pdf"))
CHUNK = 20

out_dir = Path("./out"); out_dir.mkdir(exist_ok=True)

for i in range(0, len(all_pdfs), CHUNK):
    chunk = all_pdfs[i:i + CHUNK]
    print(f"\nबैच {i // CHUNK + 1}: {len(chunk)} फाइलें")
    batch = client.batch([str(p) for p in chunk], model="invoice")
    for job in batch.wait_all(timeout=900):
        target = out_dir / f"{job.request_id}.xlsx"
        if job.is_done:
            job.download(str(target))
            print(f"  ✓ {target.name} ({job.pages_used} पृष्ठ)")
        else:
            print(f"  ✗ {job.request_id}: {job.error_detail}")

print("\nहो गया।")

डिफ़ॉल्ट संगामिति के साथ मुफ्त-tier key पर कुल वॉल टाइम: 100 इनवॉइस के लिए लगभग 8-10 मिनट, OCR प्रोसेसिंग लेटेंसी द्वारा प्रभुत्व, आपके कोड द्वारा नहीं। उच्च संगामिति वाले paid प्लानों पर समान वर्कलोड 3-5 मिनट में पूरा होता है।

चरण 5: एक वयस्क की तरह त्रुटियों को संभालें

SDK प्रत्येक API त्रुटि कोड को एक टाइप्ड अपवाद में मैप करता है। रक्षात्मक रूप से कोड करें:

from myocr_client import (
    MyOCRClient,
    QuotaExceeded,
    OcrEngineError,
    RateLimited,
    InvalidApiKey,
    FileTooLarge,
)

client = MyOCRClient()

try:
    result = client.convert("invoice.pdf", model="invoice")
except QuotaExceeded as e:
    print(f"प्लान {e.current_plan}: {e.calls_used}/{e.calls_limit} कॉल उपयोग")
    print(f"अपग्रेड {e.upgrade_url}, रीसेट {e.reset_date}")
except FileTooLarge:
    print("convert() के बजाय create_job() का उपयोग करें — async पाथ पर स्विच करें")
except OcrEngineError:
    pass  # upstream OCR विफल, 30s बाद पुनः प्रयास सुरक्षित
except RateLimited:
    pass  # दुर्लभ: SDK 429 को स्वचालित रूप से 3 बार पुनः प्रयास करता है
except InvalidApiKey:
    raise SystemExit("अपनी API key घुमाएं — वर्तमान अमान्य है")

429 और 5xx प्रतिक्रियाओं पर ऑटो-रिट्राई (Retry-After का सम्मान) कच्चे requests कोड लिखने की तुलना में सबसे आम एर्गोनोमिक जीत है। यह "मैं अस्थिर नेटवर्क को संभालना भूल गया" प्रोडक्शन घटना से बचाता है।

चरण 6: webhooks पर स्विच करें (शून्य पोलिंग)

पोलिंग काम करती है लेकिन यह बातूनी है। यदि आपके पास सार्वजनिक रूप से उजागर करने योग्य HTTP एंडपॉइंट है, तो webhook डिलीवरी क्लीनर है। जॉब बनाते समय webhook_url पास करें:

batch = client.batch(
    pdfs,
    model="invoice",
    webhook_url="https://my.app/webhooks/myocr",
)
# प्रतीक्षा करने की आवश्यकता नहीं — आपका एंडपॉइंट प्रति जॉब एक POST प्राप्त करेगा

प्राप्त करने वाले पक्ष पर (Flask उदाहरण):

from flask import Flask, request
from myocr_client import verify_webhook_signature

app = Flask(__name__)
SECRET = "आपका-साझा-secret"

@app.route("/webhooks/myocr", methods=["POST"])
def myocr_webhook():
    body = request.get_data()  # महत्वपूर्ण: कच्चे बाइट्स, request.get_json() नहीं
    sig = request.headers.get("X-MyOCR-Signature", "")
    if not verify_webhook_signature(body, sig, SECRET):
        return "अमान्य हस्ताक्षर", 401

    event = request.get_json()
    request_id = event["data"]["request_id"]
    if event["event"] == "job.completed":
        ...  # result_url डाउनलोड, DB अपडेट, उपयोगकर्ता को सूचित
    elif event["event"] == "job.failed":
        ...  # error_detail लॉग, रिट्राई या ops अलर्ट
    return "", 200

दो गैर-स्पष्ट चीजें: (1) कच्चे बाइट्स पर हस्ताक्षर सत्यापित करें — यदि आप पार्स किए गए JSON को वापस सीरियलाइज़ करते हैं तो whitespace और कुंजी क्रम के कारण हस्ताक्षर मेल नहीं खाएगा; (2) webhooks में स्वचालित रिट्राई पॉलिसी सर्वर-साइड (1m → 5m → 30m → 2h) है, इसलिए चिंता न करें यदि आपका एंडपॉइंट संक्षेप में डाउन है।

चरण 7: सही मॉडल चुनें

SDK REST API द्वारा प्रदान किए गए वही छह प्रीबिल्ट मॉडल उजागर करता है। अपने दस्तावेज़ प्रकार के लिए सबसे विशिष्ट चुनें:

• invoice — आपूर्तिकर्ता इनवॉइस, आइटम, कुल, GST। इस ट्यूटोरियल का उपयोग।
• receipt — POS रसीदें, व्यापारी, आइटम, कुल। व्यय रिपोर्ट के लिए अच्छा।
• bank_statement — लेन-देन, दिनांक, डेबिट/क्रेडिट, चालू शेष।
• business_card — संपर्क, कंपनी, फ़ोन, ईमेल, पते।
• tables — विशेष मॉडल के बिना दस्तावेज़ों के लिए सामान्य तालिका निष्कर्षण।
• text — सादा OCR टेक्स्ट, कोई संरचना नहीं।

एक विशेष मॉडल का उपयोग करना एक असंरचित तालिका प्राप्त करने और टाइप किए गए Excel कॉलमों में पहले से ही पार्स किए गए विक्रेता / कुल / आइटम प्राप्त करने के बीच का अंतर है।

चरण 8: प्रोडक्शन चेकलिस्ट

वास्तविक वर्कलोड पर भेजने से पहले:

• dev में sk_test_* keys का उपयोग करें — वे rate-limited हैं लेकिन आपकी बिल योग्य कोटा का उपभोग नहीं करते
• MYOCR_API_KEY env var के माध्यम से सेट करें, कभी hardcode नहीं — SDK इसे स्वचालित रूप से पढ़ता है
• अपने secret manager को कॉन्फ़िगर करें webhook signing secret के लिए दोनों तरफ (myocr server और आपका receiver)
• हर कॉल पर request_id लॉग करें ताकि आप समर्थन टिकट खोलते समय सर्वर-साइड लॉग के साथ सहसंबंध कर सकें
• Job.wait() पर समझदार timeout सेट करें — डिफ़ॉल्ट 600s इनवॉइस के लिए ठीक है, 50+ पृष्ठों वाले बैंक स्टेटमेंट के लिए बढ़ाएं
• अपने error tracker में QuotaExceeded मॉनिटर करें — यह आपके प्लान को अपग्रेड करने का संकेत है इससे पहले कि यह काट ले

आगे कहाँ जाएं

पूर्ण API संदर्भ Scalar UI में है, प्रत्येक एंडपॉइंट के लिए कॉपी-पेस्ट उदाहरणों के साथ। SDK स्रोत कोड GitHub पर open source है — यदि आप इसे विस्तारित करना चाहते हैं तो client.py पढ़ें, या यदि आप एक लापता फीचर मिले तो एक issue खोलें।

यदि आप एक SaaS में एकीकृत कर रहे हैं जिसे OCR की आवश्यकता है, तो SDK हमारे Zapier, QuickBooks, और Xero एकीकरण के लिए भी अनुशंसित पाथ है (सभी इसका आंतरिक उपयोग करते हैं)।

एक स्क्रीन सारांश

# pip install myocr-client
import os
from myocr_client import MyOCRClient, QuotaExceeded

client = MyOCRClient()  # MYOCR_API_KEY env var

# Sync (≤5MB, ≤10 पृष्ठ):
client.convert("doc.pdf", model="invoice").save("out.xlsx")

# Async + batch (≤20 फाइलें/कॉल, ≤50MB प्रत्येक):
batch = client.batch(
    ["a.pdf", "b.pdf", "c.pdf"],
    model="invoice",
    webhook_url="https://my.app/webhooks/myocr",
)
for job in batch.wait_all(timeout=600):
    if job.is_done:
        job.download(f"out/{job.request_id}.xlsx")

वही पैटर्न Node.js / TypeScript में

JavaScript पसंद है? आधिकारिक myocr-client Node SDK में समान सतह, समान मेथड नाम (camelCase), टाइप किए गए अपवाद, शून्य runtime निर्भरता (Node 18+ नेटिव fetch / FormData / crypto उपयोग करता है)।

// npm install myocr-client
import { MyOCRClient } from 'myocr-client';

const client = new MyOCRClient();  // env से MYOCR_API_KEY

// Sync:
const r = await client.convert('invoice.pdf', { model: 'invoice' });
await r.save('invoice.xlsx');

// Async + batch:
const batch = await client.batch(['a.pdf', 'b.pdf', 'c.pdf'], { model: 'invoice' });
const done = await batch.waitAll({ timeoutMs: 600_000 });
for (const job of done) {
  if (job.isDone) await job.download(`out/${job.requestId}.xlsx`);
}

पीछे वही API, वही त्रुटि कोड (TS क्लासेस में मैप किए गए), वही webhook डिलीवरी और हस्ताक्षर सत्यापन। अपने stack के अनुकूल भाषा चुनें।

आज ही आज़माएं: myocr.app/account/api पर मुफ्त API key प्राप्त करें (कार्ड नहीं), pip install myocr-client (या npm install myocr-client), और 5 मिनट में अपना पहला बैच प्रोसेस करें।