n8n-nodes-eboo-ocr

Version: n8n

یک پکیج نود کاستوم (Custom Node) برای پلتفرم اتوماسیون فرآیندهای n8n، جهت ارتباط با سرویس OCR و تبدیل صوت به متن ایبو (Eboo).

این نود به شما اجازه می‌دهد فایل‌های تصویری (عکس و PDF) و فایل‌های صوتی/تصویری را به سرور ایبو ارسال کرده، متن آن‌ها را استخراج کنید و خروجی را به صورت فایل ورد (Word) یا متن خام دریافت نمایید.

✨ امکانات و قابلیت‌ها

• مدیریت ایمن اعتبارنامه: توکن API به صورت امن از طریق سیستم Credentials مدیریت n8n ذخیره می‌شود و در لاگ‌ها نمایان نمی‌شود.
• ارسال فایل انعطاف‌پذیر: امکان ارسال فایل از طریق لینک مستقیم (URL) و یا آپلود مستقیم فایل باینری (Binary Data) از نودهای قبلی.
• تبدیل هوشمند عکس و PDF: تبدیل به فایل ورد (با حفظ ساختار یا بدون آن)، فایل تکست (TXT)، و استخراج متن خام یا مختصات کلمات.
• دانلود خودکار خروجی: در عملیات تبدیل عکس/PDF، لینک فایل خروجی به صورت خودکار دانلود شده و به عنوان داده باینری (Binary File) در n8n تحویل داده می‌شود تا مستقیماً بتوان آن را در Google Drive، ایمیل یا تلگرام ارسال کرد.
• پشتیبانی از تبدیل صوت به متن: ارسال فایل‌های صوتی/تصویری با پشتیبانی از ۱۳ زبان مختلف، بررسی وضعیت پیشرفت تبدیل و لغو عملیات.
• مدیریت خطای پیشرفته: تشخیص دقیق خطاهای API (مثل عدم اعتبار کافی، فایل خراب، توکن نامعتبر و...) و نمایش آن‌ها به صورت خطای استاندارد در n8n.

🚀 نصب و راه‌اندازی

برای نصب این نود در n8n خود، مراحل زیر را دنبال کنید:

1. وارد پنل مدیریت n8n خود شوید.
2. از منوی سمت چپ به مسیر Settings > Community Nodes بروید.
3. روی دکمه Install کلیک کنید.
4. گزینه Enter npm package name را انتخاب کنید.
5. نام پکیج n8n-nodes-eboo-ocr را وارد کرده و روی Install کلیک کنید.
6. چند لحظه منتظر بمانید تا نصب کامل شود. نود "Eboo OCR" اکنون در لیست نودهای شما قابل دسترسی است.

🔑 تنظیم اعتبارنامه (Credentials)

پیش از استفاده از نود، باید توکن API حساب کاربری ایبو خود را در n8n ذخیره کنید:

1. یک نود Eboo OCR در ورک‌فلو خود قرار دهید.
2. در بخش Credential to connect with، روی دکمه Create New کلیک کنید.
3. نام اعتبارنامه (مثلاً Eboo API Token) را وارد کنید.
4. توکن API خود را که از پنل سایت ایبو دریافت کرده‌اید، در فیلد API Token قرار دهید.
5. روی Save کلیک کنید.

📖 راهنمای عملیات‌ها (Operations)

این نود به دو منبع (Resource) اصلی تقسیم شده است: File و Account.

۱. منبع File (عملیات روی فایل‌ها)

عملیات: Add File (ثبت فایل در سرور)

ابتدای هر کار، فایل باید در سرور ایبو ثبت شود تا FileToken دریافت کنید.

• Input Type:
  • From URL (FileLink): لینک مستقیم فایل را وارد کنید. (پشتیبانی از PDF, JPG, PNG, MP3, MP4 و...)
  • From Binary Data (Filehandle): فایل را از نود قبلی (مانند Read Binary File یا Webhook) دریافت و مستقیماً آپلود کند.
• خروجی: در صورت موفقیت، سرور FileToken، تعداد صفحات (برای PDF/عکس) یا مدت زمان فایل (برای صوت/ویدئو) و همچنین روش‌های مجاز تبدیل (ConvertMethods) را برمی‌گرداند.

عملیات: Convert Image/PDF to Word/Text (تبدیل عکس و پی‌دی‌اف)

با استفاده از FileToken دریافتی از مرحله قبل، فایل را به متن یا ورد تبدیل می‌کند.

• Method: روش تبدیل (عدد بین ۱ تا ۴). معمولاً روش 4 برای استخراج متن OCR استفاده می‌شود.
• Output Format: فرمت خروجی نهایی:
  • Default (Docx): فایل ورد
  • Keep Layout (Docx): فایل ورد با حفظ ساختار تصویر
  • TXT File: فایل متنی
  • Raw Text: چاپ متن خام در خروجی JSON
  • Raw Text JSON / Coordinates JSON: خروجی متنی با ساختار JSON و مختصات نقاط.
• Auto Download Output File: اگر فعال باشد (پیش‌فرض)، فایل خروجی (مثلاً فایل Docx) به صورت خودکار دانلود شده و در بخش Binary نود قرار می‌گیرد و آماده ارسال به نودهای دیگر است.

عملیات: Convert Audio to Text (تبدیل صوت به متن - آزمایشی)

تبدیل فایل‌های صوتی ثبت شده به متن.

• Language: زبان فایل صوتی (پیش‌فرض: فارسی fa). پشتیبانی از انگلیسی، عربی، ترکی، فرانسوی، آلمانی و...
• Reset Previous Data: در صورت فعال بودن، داده‌های تبدیل قبلی پاک شده و تبدیل از نو آغاز می‌شود.
• خروجی: در صورت شروع موفقیت‌آمیز، وضعیت ConvertStarted برگردانده می‌شود.

عملیات: Check Audio Conversion Status (بررسی وضعیت صوت)

برای دریافت میزان پیشرفت و متن استخراج شده از فایل صوتی.

• خروجی: وضعیت (مثلاً Converting)، درصد پیشرفت (Progress) و متن خروجی (Output).

عملیات: Cancel Audio Conversion (لغو تبدیل صوت)

توقف فرآیند تبدیل فایل صوتی که در حال انجام است.

عملیات: Delete File (حذف فایل)

حذف کامل فایل از سرور ایبو (پاکسازی حافظه و حریم خصوصی).

• خروجی: وضعیت DeleteDone.

۲. منبع Account (مدیریت حساب)

عملیات: Check Credit (مشاهده اعتبار باقیمانده)

مشاهده میزان اعتبار باقیمانده در پنل کاربری ایبو.

• خروجی:
  • OCRCredit: اعتبار تبدیل عکس و PDF (بر حسب صفحه)
  • AudioTranscribeCredit: اعتبار تبدیل صوت به متن (بر حسب ثانیه)

⚠️ نکات مهم امنیتی و کاربردی

• فایل‌های PDF: فایل‌های پی‌دی‌اف ارسالی حتماً باید بدون رمز عبور باشند.
• اولویت پارامترها: اگر همزمان لینک (FileLink) و فایل باینری (Filehandle) ارسال شود، سرور ایبو فقط لینک را در نظر می‌گیرد.
• مدیریت خطا: اگر به هر دلیلی اعتبار شما کافی نباشد (NoEnoughCredit) یا فایل خراب باشد (FileCorrupted)، نود در n8n به رنگ قرمز درآمده و پیام خطای دقیق را به شما نمایش می‌دهد تا در صورت فعال بودن Continue On Fail بتوانید خطا را در ورک‌فلو هندل کنید.

📝 لایسنس

این پروژه تحت لایسنس MIT منتشر شده است.

📞 پشتیبانی

برای گزارش باگ یا پیشنهاداتی در رابطه با کدهای این نود کاستوم، لطفاً از طریق بخش Issues در مخزن گیت‌هاب پروژه اقدام نمایید. برای مشکلات مربوط به سرویس API سایت ایبو، به پشتیبانی رسمی سایت مراجعه کنید.