इनवॉइस जेनरेशन API

अपने खुद के सर्वर से प्रोग्रामेटिक रूप से पेशेवर इनवॉइस PDF जेनरेट करें, जो आंतरिक सिस्टम, मार्केटप्लेस, या आपके खुद के SaaS उत्पाद के लिए उपयुक्त है।

1. प्रमाणीकरण#

app.invosend.com/settings/api-keys पर API की बनाएं। पेड वर्कस्पेस प्लान और ओनर भूमिका आवश्यक है।

हर रिक्वेस्ट में की को Authorization हेडर में Bearer टोकन के रूप में भेजें:

Authorization: Bearer isk_live_xxxxxxxxxxxxxxxxxxxxxxxx
गायब, गलत फ़ॉर्मैट, अमान्य, या रद्द की गई API कीज़ को 403 के साथ अस्वीकार किया जाता है। अगर वर्कस्पेस मुफ़्त प्लान पर है, सस्पेंड है, या समाप्त हो चुका है तो भी कीज़ अस्वीकार की जाती हैं।

2. एंडपॉइंट#

POST/api/invoices/generate-external

बेस URL: https://app.invosend.com

मशीन-पठनीय API विवरण: OpenAPI 3.1 और Postman collection। इनमें से किसी को भी Postman, Insomnia या SDK जनरेटर में इम्पोर्ट करें।

3. रिक्वेस्ट बॉडी#

फ़ील्डटाइपआवश्यकविवरण
customer_namestringहांक्लाइंट या इनवॉइस प्राप्तकर्ता का नाम।
customer_emailstringनहींमान्य ईमेल पता। इस कॉल से बनाया गया इनवॉइस ईमेल से नहीं भेजा जाता (यह API ईमेल नहीं भेजता)। रिकरिंग इनवॉइस के लिए आवश्यक: इसके बाद बनने वाला हर इनवॉइस इसी पते पर भेजा जाता है।
customer_tax_idstringनहींक्लाइंट का कर पंजीकरण नंबर (इंडोनेशिया में NPWP, अधिकतम 40 अक्षर)। इनवॉइस पर क्लाइंट के पते के नीचे छपता है।
itemsarrayहांविवरण, quantity > 0, और price >= 0 वाला कम से कम 1 मान्य आइटम।
items[].descriptionstringनहींप्रोडक्ट या सेवा का नाम। खाली होने पर Item इस्तेमाल होता है।
items[].quantitynumberहांइकाइयों की संख्या, अधिकतम 2 दशमलव के साथ (जैसे 1.5 घंटे), 0.01 से 999,999 तक।
items[].pricenumberहांप्रति इकाई मूल्य।
items[].discountnumberनहींप्रति आइटम छूट राशि। डिफ़ॉल्ट 0।
currencystringनहींIDR या USD जैसा करेंसी कोड। डिफ़ॉल्ट IDR।
tax_ratenumberनहींछूट के बाद उप-योग से गणना किया गया टैक्स प्रतिशत। डिफ़ॉल्ट 0।
due_datestringनहींफ़ॉर्मैट YYYY-MM-DD। जेनरेशन के 14 दिन बाद डिफ़ॉल्ट।
notesstringनहींइनवॉइस पर दिखाई जाने वाली अतिरिक्त टिप्पणियां।
items[].unitstringनहींमात्रा के बगल में दिखाया गया यूनिट लेबल, जैसे pcs या hour।
items[].tax_ratenumberनहींप्रति-आइटम टैक्स प्रतिशत ओवरराइड (0-100)। उस आइटम के लिए इनवॉइस-स्तरीय tax_rate उपयोग करने हेतु छोड़ दें।
discount_totalnumberनहींइनवॉइस-स्तरीय छूट। यह टैक्स से पहले घटाई जाती है, इसलिए टैक्स छूट के बाद की राशि पर लगता है (आइटमों में उनके मूल्य के अनुपात में बाँटी जाती है)। डिफ़ॉल्ट 0।
templatestringनहींउपयोग किए जाने वाले इनवॉइस टेम्पलेट की ID। उपलब्ध टेम्पलेट GET /api/invoices/external/templates से देखें। न देने पर सेटिंग्स में चुना गया डिफ़ॉल्ट टेम्पलेट, फिर Invosend का डिफ़ॉल्ट उपयोग होता है।
document_languagestringनहींइनवॉइस दस्तावेज़ (PDF और ईमेल) के शब्दों की भाषा: en (डिफ़ॉल्ट), id, es, fr, de, nl, it, pt, zh, ja, hi, ar (इंडोनेशियाई, स्पेनिश, फ़्रेंच, जर्मन, डच, इतालवी, ब्राज़ीली पुर्तगाली, सरलीकृत चीनी, जापानी, हिन्दी, अरबी)। कोई अन्य मान त्रुटि के साथ अस्वीकार कर दिया जाता है। सादा अंतर्निहित लेआउट, जो केवल तब उपयोग होता है जब कोई टेम्पलेट नहीं होता, हमेशा अंग्रेज़ी में होता है।
custom_payment_notesstringनहींPDF पर दिखाए जाने वाले अतिरिक्त भुगतान निर्देश।
footer_textstringनहींPDF के नीचे दिखाया गया छोटा टेक्स्ट।
is_recurringbooleanनहींरिकरिंग सीरीज़ बनाता है। यह इनवॉइस पहला है; अगले इनवॉइस शेड्यूल के अनुसार अपने आप बनते हैं और customer_email पर भेजे जाते हैं, हर एक में 1 इनवॉइस क्रेडिट लगता है। इसके लिए रिकरिंग इनवॉइस फ़ीचर वाला प्लान, साथ ही recurring_interval और customer_email ज़रूरी हैं।
recurring_intervalstringनहींसीरीज़ कितनी बार दोहराई जाएगी: weekly, fortnightly, monthly, quarterly, semi-annually, yearly में से एक। is_recurring के true होने पर आवश्यक।
recurring_countintegerनहींसीरीज़ में इनवॉइस की कुल संख्या, इस पहले सहित: 2 से 121 तक की पूर्ण संख्या। डिफ़ॉल्ट 4। इस फ़ील्ड या recurring_end_date में से एक ही इस्तेमाल करें, दोनों नहीं।
recurring_end_datestringनहींवह तारीख जिसके बाद और इनवॉइस नहीं बनेंगे, YYYY-MM-DD प्रारूप में, भविष्य की। इस फ़ील्ड या recurring_count में से एक ही इस्तेमाल करें, दोनों नहीं।
payment_gatewaystringनहींmidtrans, xendit, stripe, paypal, razorpay, mollie में से एक। गेटवे वर्कस्पेस में पहले से कनेक्ट होना चाहिए।
payment_accountstringनहींइनवॉइस से जोड़ने के लिए मौजूदा भुगतान खाते (बैंक विवरण) की ID।

पूर्ण रिक्वेस्ट उदाहरण:

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. एरर कोड#

स्टेटसकारण
400ज़रूरी फ़ील्ड गायब या अमान्य हैं: customer_name, खाली items, कोई मान्य आइटम नहीं, अपरिचित payment_gateway, इस वर्कस्पेस के लिए कनेक्ट न किया गया payment_gateway, या रिकरिंग इनवॉइस में recurring_interval या customer_email का न होना, अथवा अमान्य recurring_count / recurring_end_date। PDF न बन पाने पर भी यही स्टेटस मिलता है: अनुरोध दोबारा भेजें (कोई क्रेडिट नहीं कटता)।
402वर्कस्पेस का invoice_credits बैलेंस खाली है। जारी रखने के लिए क्रेडिट टॉप-अप करें।
403Authorization हेडर गायब है या गलत फ़ॉर्मैट में है, API की अमान्य है या रद्द है, या वर्कस्पेस प्लान में API एक्सेस शामिल नहीं है।
403 (आवर्ती)is_recurring सेट किया गया था लेकिन वर्कस्पेस प्लान में आवर्ती इनवॉइस शामिल नहीं है।
409उसी Idempotency-Key वाला अनुरोध अभी प्रोसेस हो रहा है। थोड़ी देर बाद दोबारा प्रयास करें।
422यह Idempotency-Key किसी भिन्न अनुरोध बॉडी के साथ पहले उपयोग हो चुकी है। नए इनवॉइस के लिए नई कुंजी इस्तेमाल करें।
429रेट लिमिट पार हो गई। रेट लिमिट सेक्शन देखें।

6. रेट लिमिट#

स्कोपलिमिट
प्रति वर्कस्पेस (सभी API अनुरोध मिलाकर)Professional 10/min · Specialist 20/min · Business 30/min · Enterprise 60/min
प्रति IP पता (सभी API अनुरोध मिलाकर)30 रिक्वेस्ट/मिनट
प्रति वर्कस्पेस सक्रिय API कीज़Professional 3 · Specialist 5 · Business 10 · Enterprise 20
इनवॉइस बनाना और पढ़ने/प्रबंधन वाले एंडपॉइंट एक ही सीमा साझा करते हैं। सफल रिस्पॉन्स में X-RateLimit-Limit और X-RateLimit-Remaining हेडर होते हैं। वर्कस्पेस API कोटा Invosend में मेंबरशिप प्लान के अनुसार सेट होते हैं। ज़्यादा प्रोडक्शन वॉल्यूम चाहिए? अपने वर्कस्पेस खाते से हमसे संपर्क करें। रद्द की गई कीज़ कीज़ की सीमा में नहीं गिनी जातीं।

7. अतिरिक्त एंडपॉइंट्स#

वही API की generate-external के माध्यम से बनाई गई इनवॉइस को भी पढ़ और प्रबंधित कर सकती है:

मेथडपाथविवरण
GET/api/invoices/externalइस वर्कस्पेस के लिए इनवॉइस सूचीबद्ध करता है। ?status= और ?page=/?pageSize= क्वेरी पैरामीटर समर्थित हैं।
GET/api/invoices/external/templatesवे इनवॉइस टेम्पलेट सूचीबद्ध करता है जिन्हें आप template में दे सकते हैं, साथ में यह कि आपका प्लान उन्हें अनुमति देता है या नहीं और कौन-सा डिफ़ॉल्ट है।
GET/api/invoices/external/:idइसकी id (जो generate-external द्वारा लौटाया गया मान है) से एक इनवॉइस प्राप्त करें।
PUT/api/invoices/external/:id/statusइनवॉइस स्थिति अपडेट करें। बॉडी: { "status": "paid" } (unpaid, paid, overdue, cancelled में से एक)।
PUT/api/invoices/external/:id/archiveकिसी इनवॉइस को आर्काइव करें या अनआर्काइव करें। बॉडी: { "is_archived": true }।
POST/api/invoices/external/:id/pdfPDF URL को फिर से प्राप्त करें, ज़रूरत होने पर इसे फिर से जेनरेट करते हुए। पुनः जेनरेशन को फ़ोर्स करने के लिए बॉडी: { "force": true }।
GET/api/invoices/external/recurringरिकरिंग सीरीज़ की सूची। ?status= (active, paused, completed) और ?page=/?pageSize= समर्थित हैं।
GET/api/invoices/external/recurring/:idएक सीरीज़ प्राप्त करें (generate-external से मिला recurring.schedule_id) और उसकी सभी आवृत्तियां: तिथि, स्थिति और हर आवृत्ति से बना इनवॉइस id।
PUT/api/invoices/external/recurring/:id/statusसीरीज़ को पॉज़ या फिर शुरू करें। बॉडी: { "status": "paused" } या { "status": "active" }। फिर शुरू करने के लिए रिकरिंग इनवॉइस वाला प्लान चाहिए।
PUT/api/invoices/external/recurring/:id/extendआख़िरी आवृत्ति के बाद और आवृत्तियां जोड़ें। बॉडी: { "count": 3 } या { "end_date": "2027-12-31" }।
PUT/api/invoices/external/recurring/:id/frequencyसीरीज़ कितनी बार दोहराई जाए यह बदलें; अभी तक न बनी आगामी आवृत्तियां बदल दी जाती हैं। बॉडी: { "frequency": "monthly", "start_date": "2027-01-01", "count": 6 } (count की जगह end_date भी दे सकते हैं; start_date भविष्य की होनी चाहिए)।
POST/api/invoices/external/recurring/:id/skipएक आगामी आवृत्ति हटाएं। बॉडी: { "date": "2027-01-01" }। जिस आवृत्ति से इनवॉइस बन चुका है उसे हटाया नहीं जा सकता।
ऑनलाइन भुगतान लेने के लिए 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 से बनाए गए, दोनों तरह के इनवॉइस के लिए भेजे जाते हैं। आवर्ती सीरीज़ के टेम्पलेट कभी नहीं भेजे जाते।

इवेंटकब भेजा जाता है
invoice.createdइनवॉइस बनाया जाता है। हो सकता है PDF अभी तैयार न हो, इसलिए pdf_url null हो सकता है।
invoice.paidस्टेटस paid हो जाता है (आपके द्वारा, API से, या ऑनलाइन भुगतान से)।
invoice.overdueस्टेटस overdue हो जाता है (देय तिथि के बाद अपने-आप, या मैन्युअल रूप से)।
invoice.cancelledस्टेटस cancelled हो जाता है।

हर इवेंट का ढांचा एक जैसा है। 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));
}
10 सेकंड के भीतर कोई भी 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 सेक्शन में हर प्लान की मौजूदा सीमा दी गई है।