কাস্টমার API

শুরু করুন

API কী অংশে একটি টেস্ট কী তৈরি করুন, সেটি আপনার সার্ভারে রাখুন এবং FAIRVALID_API_KEY ও FAIRVALID_BASE_URL সেট করুন। টেস্ট কী সংরক্ষিত @example.com ঠিকানার সাথে কাজ করে। এগুলো কোনো প্রোভাইডার কল করে না এবং কোনো ক্রেডিট ব্যবহার করে না।

curl -X POST "$FAIRVALID_BASE_URL/api/v1/jobs" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY" \
  -H "Idempotency-Key: my-import-2026-10-05" \
  -H "Content-Type: application/json" \
  -d '{"emails":["deliverable@example.com","pending@example.com"]}'

প্রোডাকশনের জন্য, submit স্কোপসহ একটি Live key তৈরি করুন এবং /api/v1/jobs বা /api/v1/verifications ব্যবহার করুন। জবের স্টেট ও ফলাফল পড়তে read স্কোপ যোগ করুন।

নতুন জব HTTP 202 এবং একটি UUID job_id ফেরত দেয়। মিলে যাওয়া পুনঃচেষ্টা একই জবসহ HTTP 200 ফেরত দেয়। রেসপন্সে version: v1, brand: FairValid এবং no-store হেডার থাকে।

কী ও খরচের সীমা

সার্ভার থেকে Authorization: Bearer fv_live_… বা Bearer fv_test_… পাঠান। সম্পূর্ণ সিক্রেট কেবল একবারই দেখানো হয়। লাইভ কী-তে submit, read এবং balance স্কোপ থাকতে পারে। বাতিল করা কী দিয়ে নতুন অনুরোধ করা যায় না। টেস্ট কী কেবল নিজস্ব সিমুলেটেড জব অ্যাক্সেস করতে পারে।

একটি লাইভ কী-এর আজীবন সীমায় ইতিমধ্যে ব্যবহৃত ক্রেডিট এবং গৃহীত অনন্য পরিচয়ের জন্য সংরক্ষিত ক্রেডিট গণনা করা হয়। এটি ওয়ার্কস্পেসে ক্রেডিট যোগ করতে পারে না। সীমা ছাড়িয়ে যাওয়া নতুন অনুরোধ কোনো জব তৈরি বা ক্রেডিট সংরক্ষণ না করেই HTTP 402 key_cap_reached ফেরত দেয়। সীমা কমালে নতুন কাজ আটকে যায়; গৃহীত কাজ চলতে থাকে।

লাইভ জবগুলো আপনার ওয়ার্কস্পেসের যাচাই কিউ ও ক্রেডিট ব্যালান্স ব্যবহার করে। কী-এর স্কোপ, কী-এর সীমা, ওয়ার্কস্পেস অ্যাক্সেস ও প্রসেসিং সীমা তবুও প্রযোজ্য। যাচাইগুলো প্রসেসিংয়ের জন্য গৃহীত হওয়ার সঙ্গে সঙ্গে ওয়ার্কস্পেসের ক্রেডিট সংরক্ষিত হয়; ফলাফলে ড্যাশবোর্ডের মতোই চার্জ ও ফেরতের নিয়ম প্রযোজ্য।

অপারেশনাল বিরতির সময় নতুন লাইভ সাবমিশন ক্রেডিট সংরক্ষণ না করেই HTTP 503 live_verification_unavailable ফেরত দিতে পারে। একই Idempotency-Key দিয়ে পরে আবার চেষ্টা করুন।

জব ও ফলাফল

curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"
curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID/results" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"

next_cursor-কে cursor কোয়েরি প্যারামিটার হিসেবে পাঠান। এতে মূল ফিল্টার ও সার্চ থাকে। ফিল্টারগুলো হলো all, valid, invalid, catch_all, unknown, still_checking এবং not_checked। লাইভ ফলাফল ও ক্রেডিটের অবস্থা ড্যাশবোর্ড স্ন্যাপশটের সঙ্গে মিলে যায়। জবের অবস্থা হতে পারে queued, running, paused, canceling, canceled বা completed। টেস্ট জব নির্ধারিতভাবে completed, pending, failed বা cancelled অবস্থা ফেরত দেয়।

ত্রুটি ও নিরাপদে পুনরায় চেষ্টা

প্রতিটি জব সাবমিশন এবং লাইভ একক-ঠিকানা সাবমিশনে অনুমোদিত অক্ষর, সংখ্যা, ডট, কোলন, আন্ডারস্কোর বা হাইফেন দিয়ে গঠিত ৮ থেকে ১২৮ অক্ষরের একটি Idempotency-Key পাঠান। অনিশ্চিত কোনো রেসপন্সের ক্ষেত্রে একই API কী, idempotency কী এবং normalized body দিয়ে পুনরায় চেষ্টা করুন। Replay শুধু ওই API কী-এর মধ্যে সীমাবদ্ধ; সেই ক্রেডেনশিয়াল বদলে আবার সাবমিট করলে আরেকটি রান তৈরি হতে পারে। পরিবর্তিত body-সহ একই idempotency কী ব্যবহার করলে HTTP 409 idempotency_conflict ফেরত আসে। কেবল তখনই নতুন কী ব্যবহার করুন যখন আপনি সত্যিই একটি নতুন রান চালাতে চান, যাতে আবার ক্রেডিট কাটা হতে পারে।

HTTP 401 মানে কী অনুপস্থিত, বাতিল করা হয়েছে বা প্রয়োজনীয় স্কোপ নেই। HTTP 422 অবৈধ ঠিকানা বা লিস্টের সীমা নির্দেশ করে। প্রতি ওয়ার্কস্পেসে প্রতি ঘণ্টায় ২০টি বা ৩০ দিনে ১০০টি নতুন জবের পর Test বাল্ক জব HTTP 429 ফেরত দেয়; হুবহু একই পুনঃচেষ্টায় তবুও মূল জবটিই ফেরত আসে। HTTP 503 মানে অনুরোধটি সাময়িকভাবে উপলব্ধ নয়; অনিশ্চিত সাবমিশনের পর 503 পেলে তা প্রমাণ করে না যে কোনো জব তৈরি হয়নি, তাই একই idempotency key দিয়ে আবার চেষ্টা করুন। ত্রুটিতে একটি কোড, বার্তা ও রিকোয়েস্ট ID থাকে।

ফ্রি স্যান্ডবক্স

টেস্ট কী শুধু এই ঠিকানাগুলো গ্রহণ করে: deliverable@example.com, undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com এবং error@example.com। এগুলো valid, invalid, catch-all, unknown, pending এবং unavailable ফলাফল সিমুলেট করে। বাল্ক টেস্ট জব লাইভ ভেরিফিকেশন বা ক্রেডিট লেজার স্পর্শ না করেই স্ট্যাটাস, ফলাফল, বাতিলকরণ ও রিপ্লে সমর্থন করে।

বাল্ক স্যান্ডবক্স জব ও সেগুলোর রিপ্লে রেকর্ড 30 দিন সংরক্ষিত থাকে। এই সময়ের পরে নতুন পরীক্ষার জন্য নতুন idempotency key ব্যবহার করুন।

মূল /api/v1/verifications টেস্ট-কী সিমুলেটর এর আগের 2026-10-01 রেসপন্স সংস্করণ ও camelCase ফিল্ড ব্যবহার করে। সংস্করণযুক্ত বাল্ক সিমুলেটরের জন্য /api/v1/jobs ব্যবহার করুন।

স্বাক্ষরিত ওয়েবহুক

Owner ও Manager ভূমিকার ব্যবহারকারীরা job.completed এবং job.canceled-এর জন্য HTTPS এন্ডপয়েন্ট কনফিগার করেন। একটি টেস্ট পিং test.ping ব্যবহার করে। জব পেলোডে একটি স্থায়ী ইভেন্ট আইডি, জব আইডি, অবস্থা, ঠিকানাবিহীন সারসংক্ষেপ, কাটা/ফেরত দেওয়া সংখ্যা এবং একটি ফলাফল URL থাকে। এগুলোতে কখনো ইমেইল ঠিকানা বা প্রোভাইডারের ডেটা থাকে না।

FairValid-Webhook-Id, FairValid-Webhook-Timestamp এবং FairValid-Webhook-Signature পড়ুন। সিগনেচারটি হলো fv1=, এরপর fv1\n{event ID}\n{Unix timestamp}\n-এর র বাইট ও তার ঠিক পরেই র JSON বডির ওপর গণনা করা ছোট হাতের HMAC-SHA256 hex। কনস্ট্যান্ট-টাইম তুলনা ব্যবহার করুন। আপনার ঘড়ির সময় থেকে পাঁচ মিনিটের বেশি ব্যবধানের টাইমস্ট্যাম্প প্রত্যাখ্যান করুন এবং স্থায়ী স্টোরেজে ইভেন্ট আইডি দিয়ে ডুপ্লিকেট বাদ দিন।

১০ সেকেন্ডের মধ্যে যেকোনো 2xx ফেরত দিন। ব্যর্থ বা অনিশ্চিত ডেলিভারি একই ইভেন্ট ID দিয়ে সর্বোচ্চ আটবার পুনরায় চেষ্টা করা হয়; ৩০ দিনের ইতিহাস দেখুন অথবা ম্যানুয়ালি আবার ডেলিভার করুন। রিডাইরেক্ট ও প্রাইভেট গন্তব্য প্রত্যাখ্যান করা হয়। রোটেশনের পরে নতুন চেষ্টাগুলোতে নতুন সিক্রেট ব্যবহৃত হয়। চলমান চেষ্টাগুলোর সিগনেচার যাচাই করতে আগের সিক্রেটটি ২৪ ঘণ্টা রেখে দিন।

চালানো যায় এমন উদাহরণ

রিপোজিটরিতে packages/contracts/examples/job.mjsএবং packages/contracts/examples/webhook-receiver.mjs রয়েছে। Node 22 ও একটি Test কী দিয়ে জব উদাহরণটি চালান। রিসিভারটি হুবহু raw body বাইট যাচাই করে এবং রোটেশনের সময় বর্তমান ও আগের উভয় সিক্রেট যাচাই করে। প্রোডাকশনে ব্যবহারের আগে এর সামনে HTTPS যোগ করুন এবং এর ইন-মেমরি ইভেন্ট-ID সেটের বদলে একটি টেকসই অ্যাটমিক স্টোর ব্যবহার করুন।

FAIRVALID_API_KEY=... FAIRVALID_BASE_URL=https://YOUR_FAIRVALID_HOST \
  node packages/contracts/examples/job.mjs