इनवॉइस जेनरेशन API
अपने खुद के सर्वर से प्रोग्रामेटिक रूप से पेशेवर इनवॉइस PDF जेनरेट करें, जो आंतरिक सिस्टम, मार्केटप्लेस, या आपके खुद के SaaS उत्पाद के लिए उपयुक्त है।
1. प्रमाणीकरण#
app.invosend.com/settings/api-keys पर API की बनाएं। पेड वर्कस्पेस प्लान और ओनर भूमिका आवश्यक है।
हर रिक्वेस्ट में की को Authorization हेडर में Bearer टोकन के रूप में भेजें:
Authorization: Bearer isk_live_xxxxxxxxxxxxxxxxxxxxxxxx403 के साथ अस्वीकार किया जाता है। अगर वर्कस्पेस मुफ़्त प्लान पर है, सस्पेंड है, या समाप्त हो चुका है तो भी कीज़ अस्वीकार की जाती हैं।2. एंडपॉइंट#
बेस URL: https://app.invosend.com
मशीन-पठनीय API विवरण: OpenAPI 3.1 और Postman collection। इनमें से किसी को भी Postman, Insomnia या SDK जनरेटर में इम्पोर्ट करें।
3. रिक्वेस्ट बॉडी#
पूर्ण रिक्वेस्ट उदाहरण:
curl -X POST https://app.invosend.com/api/invoices/generate-external \
-H "Authorization: Bearer isk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"customer_name": "Acme Corp",
"customer_email": "billing@acme.com",
"items": [
{ "description": "Consulting Services", "quantity": 2, "price": 40000, "tax_rate": 11 }
],
"discount_total": 4000,
"currency": "INR",
"notes": "Thank you for your business."
}'रिकरिंग इनवॉइस का उदाहरण (पहला अभी, फिर हर महीने एक, कुल 6):
curl -X POST https://app.invosend.com/api/invoices/generate-external \
-H "Authorization: Bearer isk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"customer_name": "Acme Corp",
"customer_email": "billing@acme.com",
"items": [
{ "description": "Monthly retainer", "quantity": 1, "price": 200000 }
],
"currency": "INR",
"recurring_interval": "monthly",
"recurring_count": 6
}'Idempotency-Key हेडर जोड़ें (1-255 अक्षर, जैसे हर इनवॉइस के लिए बनाया गया UUID)। यदि पहला अनुरोध सफल रहा था, तो दोबारा प्रयास पर वही प्रतिक्रिया Idempotent-Replayed: true हेडर के साथ मिलती है, बिना दूसरा इनवॉइस बनाए या दूसरा क्रेडिट खर्च किए (credits_remaining पहली कॉल का मान होता है)। कुंजियां प्रति वर्कस्पेस 24 घंटे रखी जाती हैं। केवल सफल प्रतिक्रियाएं सहेजी जाती हैं, इसलिए विफल अनुरोध को उसी कुंजी से दोबारा भेजा जा सकता है।4. रिस्पॉन्स#
200 OK का मतलब है कि इनवॉइस बन गई और PDF जेनरेट हो गई:
{
"data": {
"id": "cjld2cjxh0000qzrmn831i7rn",
"invoice_number": "INV-1-202609-0016",
"pdf_url": "https://cdn.invosend.com/company/1/pdf/Invoice_INV_1_202609_0016_UNPAID_0da2beeabb.pdf",
"credits_remaining": 24,
"is_recurring": false,
"template": {
"id": "k3p9x2m7c0000abcd1234efgh",
"name": "Classic",
"source": "system_default"
}
}
}credits_remaining null होता है। id नीचे दिए गए अतिरिक्त एंडपॉइंट्स के लिए इस इनवॉइस की पहचान करता है। इस API से बनाई गई इनवॉइस वर्कस्पेस इनवॉइस सूची में भी दिखाई देती हैं और मैन्युअल रूप से बनाई गई इनवॉइस के समान इनवॉइस नंबर क्रम का उपयोग करती हैं। इनवॉइस नंबर INV-{वर्कस्पेस आईडी}-{YYYYMM}-{क्रम} जैसे दिखते हैं। रिकरिंग इनवॉइस के लिए रिस्पॉन्स में एक recurring ऑब्जेक्ट भी होता है: schedule_id, interval, occurrences, next_issue_date, end_date। recurring.schedule_id वही id है जो नीचे के रिकरिंग एंडपॉइंट में इस्तेमाल होती है।5. एरर कोड#
6. रेट लिमिट#
X-RateLimit-Limit और X-RateLimit-Remaining हेडर होते हैं। वर्कस्पेस API कोटा Invosend में मेंबरशिप प्लान के अनुसार सेट होते हैं। ज़्यादा प्रोडक्शन वॉल्यूम चाहिए? अपने वर्कस्पेस खाते से हमसे संपर्क करें। रद्द की गई कीज़ कीज़ की सीमा में नहीं गिनी जातीं।7. अतिरिक्त एंडपॉइंट्स#
वही API की generate-external के माध्यम से बनाई गई इनवॉइस को भी पढ़ और प्रबंधित कर सकती है:
generate-external में payment_gateway (और चाहें तो payment_account) सेट करें, फिर अपने ग्राहक को इनवॉइस का सार्वजनिक भुगतान पेज भेजें: https://app.invosend.com/p/invoice/{id}, जहाँ id वही है जो API लौटाता है। ग्राहक वहीं कनेक्टेड गेटवे से भुगतान करता है और इनवॉइस अपने आप paid मार्क हो जाता है। चेकआउट उसी पेज पर होता है; कॉल करने के लिए कोई अलग सार्वजनिक चेकआउट एंडपॉइंट नहीं है।8. Webhooks#
बार-बार पोल करने के बजाय एक HTTPS URL रजिस्टर करें; जब भी कोई इनवॉइस बदलता है, Invosend उस URL पर JSON बॉडी के साथ POST अनुरोध भेजता है। एंडपॉइंट सेटिंग्स > Webhooks में जोड़ें (वर्कस्पेस ओनर, API एक्सेस वाला प्लान, अधिकतम 5 एंडपॉइंट)। हर एंडपॉइंट का अपना साइनिंग सीक्रेट होता है, जो केवल एक बार दिखाया जाता है।
इवेंट डैशबोर्ड में बनाए गए और इस API से बनाए गए, दोनों तरह के इनवॉइस के लिए भेजे जाते हैं। आवर्ती सीरीज़ के टेम्पलेट कभी नहीं भेजे जाते।
हर इवेंट का ढांचा एक जैसा है। data.object इनवॉइस है, जिसका रूप GET /api/invoices/external/:id जैसा ही है; स्टेटस इवेंट में data.previous_status भी होता है:
{
"id": "evt_9f2c1b7a4e3d5c6b8a1f0e2d",
"object": "event",
"type": "invoice.paid",
"created": "2026-10-01T09:30:12.000Z",
"data": {
"object": {
"id": "cjld2cjxh0000qzrmn831i7rn",
"invoice_number": "INV-1-202610-0007",
"customer_name": "Acme Corp",
"customer_email": "billing@acme.com",
"currency": "USD",
"subtotal": 500,
"discount_total": 0,
"tax_rate": 0,
"tax_amount": 0,
"amount": 500,
"amount_paid": 500,
"amount_credited": 0,
"amount_received": 500,
"invoice_status": "paid",
"is_archived": false,
"is_recurring": false,
"recurring_interval": "none",
"issue_date": "2026-10-01T02:15:40.000Z",
"due_date": "2026-10-15",
"paid_at": "2026-10-01T09:30:11.000Z",
"pdf_url": "https://cdn.invosend.com/company/1/pdf/Invoice_INV_1_202610_0007_PAID.pdf",
"pdf_status": "ready"
},
"previous_status": "unpaid"
}
}हर अनुरोध में ये हेडर होते हैं। सत्यापन के लिए एंडपॉइंट के सीक्रेट से {t}.{रॉ बॉडी} का HMAC-SHA256 निकालें और उसे v1 से मिलाएं; यदि t 5 मिनट से पुराना हो तो अनुरोध अस्वीकार करें:
POST /your/webhook/url
Content-Type: application/json
Invosend-Event: invoice.paid
Invosend-Delivery: evt_9f2c1b7a4e3d5c6b8a1f0e2d
Invosend-Signature: t=1790847012,v1=5b1d...e9a2
// Node.js
import crypto from "crypto";
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(parts.t + "." + rawBody)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}2xx स्टेटस लौटाएं। अन्यथा अधिकतम 7 बार और प्रयास किया जाता है (1 मिनट, 5 मिनट, 30 मिनट, 2 घंटे, 6 घंटे, 12 घंटे और 24 घंटे बाद)। लगातार विफल होने वाला एंडपॉइंट बंद कर दिया जाता है और आपको सूचना मिलती है। कोई इवेंट एक से अधिक बार या क्रम से बाहर आ सकता है: डुप्लिकेट अनदेखा करने के लिए इवेंट id का उपयोग करें और invoice_status को अंतिम सच मानें। डिलीवरी लॉग 30 दिन रखे जाते हैं, और किसी भी इवेंट को सेटिंग्स > Webhooks से दोबारा भेजा जा सकता है।9. सीमाएं#
यह API जानबूझकर इनवॉइस जेनरेशन और हल्के इनवॉइस प्रबंधन तक सीमित है। निम्नलिखित अभी उपलब्ध नहीं हैं:
- Webhooks केवल इनवॉइस बनने, भुगतान होने, देय तिथि निकलने और रद्द होने को कवर करते हैं। संपादन या आर्काइव जैसे अन्य बदलाव नहीं भेजे जाते: वर्तमान स्थिति
GET /invoices/external/:idसे पढ़ें। - हर अनुरोध से बना इनवॉइस ईमेल से नहीं भेजा जाता: यह API केवल PDF बनाता है, इसे ग्राहक तक पहुँचाना आपकी ज़िम्मेदारी है (या डैशबोर्ड इस्तेमाल करें)। अपवाद रिकरिंग सीरीज़ हैं: शेड्यूलर द्वारा बनाया गया हर अगला इनवॉइस अपने आप
customer_emailपर भेजा जाता है। - बनने के बाद इनवॉइस में संपादन नहीं — इस API के माध्यम से केवल इसकी स्थिति और आर्काइव स्थिति बदली जा सकती है।
- भुगतान गेटवे समर्थन के लिए गेटवे का डैशबोर्ड में पहले से कनेक्ट होना ज़रूरी है; यह API इसे केवल इनवॉइस से जोड़ती है, यह अपने आप कोई गेटवे कनेक्ट नहीं करती।
- रिकरिंग सीरीज़ को API से पॉज़, फिर शुरू, बढ़ाया, नए समय पर तय और आगामी आवृत्तियों को छोड़ा जा सकता है, लेकिन उसकी सामग्री (आइटम, ग्राहक, राशि) एडिट नहीं की जा सकती और सीरीज़ को API से हटाया नहीं जा सकता; यह डैशबोर्ड में करें।
अक्सर पूछे जाने वाले प्रश्न#
मुझे Invosend API की कैसे मिलेगी?
app.invosend.com पर एक खाता बनाएं, वर्कस्पेस को पेड प्लान में अपग्रेड करें, फिर Settings > API Keys खोलें और Generate key पर क्लिक करें। रॉ की सिर्फ़ बनते समय एक बार दिखाई जाती है।
प्रत्येक इनवॉइस जेनरेशन API कॉल की लागत कितनी है?
हर सफल रिक्वेस्ट आपके वर्कस्पेस बैलेंस से 1 इनवॉइस क्रेडिट घटाती है। यह डैशबोर्ड के माध्यम से बनाई गई इनवॉइस के समान क्रेडिट पूल का उपयोग करता है।
इस API की रेट लिमिट क्या है?
वर्कस्पेस की रेट लिमिट आपके पेड प्लान की कॉन्फ़िगरेशन पर निर्भर करती है। ऊपर Rate Limit सेक्शन में हर प्लान की मौजूदा सीमा दी गई है।