# piv.day API Reference Full reference for the piv.day REST API: every endpoint, request body, response shape, error code and webhook. Exported from https://piv.day/api/docs for use with AI assistants. --- ## Getting started Business प्लान पर REST API। Bearer टोकन, JSON, idempotent एंडपॉइंट, अनुमानित एरर कोड। नीचे दस्तावेज़ में प्रत्येक एंडपॉइंट के लिए अनुरोध और प्रतिक्रिया उदाहरण दिए गए हैं। ### Base URL ``` https://app.piv.day/api/v1 ``` सभी एंडपॉइंट इस प्रीफ़िक्स के अंतर्गत हैं। एक ही वातावरण — कोई अलग staging होस्ट नहीं। ### प्रमाणीकरण ``` Authorization: Bearer YOUR_API_KEY ``` कुंजियाँ dashboard में `सेटिंग्स → API Keys` अनुभाग में बनाई जाती हैं। प्रत्येक कुंजी में बारीक अनुमतियाँ होती हैं (नंबर पढ़ना, SMS भेजना, proxy खरीदना आदि)। किसी समझौते किए गए टोकन को एक क्लिक में बदला जा सकता है — टीम को दोबारा onboard करने की आवश्यकता नहीं। ### खाता **200 OK** ``` curl https://app.piv.day/api/v1/account \ -H "Authorization: Bearer YOUR_API_KEY" ``` **एक उपयोगिता एंडपॉइंट — वर्तमान खाते का बैलेंस और email। यह जाँचने के लिए उपयोगी है कि कुंजी काम कर रही है और प्रमाणीकरण सही तरीके से कॉन्फ़िगर किया गया है।** ``` { "success": true, "data": { "user_id": "usr-uuid-...", "balance": 150.50, "email": "u***@example.com", "team_id": null, "is_team_member": false } } ``` GET /api/v1/account ### प्रतिक्रिया प्रारूप ``` { "success": true, "data": { ... } } ``` सभी प्रतिक्रियाएं JSON हैं। त्रुटि पर `success` = `false` होता है और body में `error.code` और `error.message` होते हैं। ### Rate limits **प्रत्येक API key के लिए प्रति मिनट 100 अनुरोध। यह सीमा सभी एंडपॉइंट के लिए साझा है। ट्रैफ़िक स्पाइक के लिए अधिक क्षमता चाहिए? Telegram सपोर्ट को लिखें, हम सीमा बढ़ा देंगे। सीमा पार होने पर `429 RATE_LIMITED` और `Retry-After` हेडर मिलता है — अगले अनुरोध से पहले कितने सेकंड प्रतीक्षा करें।** ``` HTTP/1.1 429 Too Many Requests Retry-After: 12 { "success": false, "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded, retry in 12s" } } ``` 429 Too Many Requests ## नंबर नंबर खरीदें, नवीनीकरण करें और पुनर्स्थापित करें। SMS प्राप्त करें और भेजें। Google QR सत्यापन शुरू करें। webhook के माध्यम से इवेंट सदस्यता लें। ### देशों और कीमतों की सूची `GET /api/v1/numbers/countries` खरीद के लिए उपलब्ध देश वर्तमान मूल्य और SMS क्षमताओं के साथ लौटाता है। सभी मूल्य आपकी सदस्यता छूट सहित हैं। **Response fields** | Field | Type | Description | | --- | --- | --- | | `country_code` | string | दो-अक्षर ISO देश कोड (जैसे `SE`)। | | `price_per_month` | number | आपके प्लान की अंतिम कीमत — खरीद पर वास्तव में जो चार्ज होगा। Premium / Business छूट पहले से लागू हैं। | | `base_price` | number | बिना छूट के मूल्य (Free प्लान)। तुलना के लिए लौटाया जाता है — देखने के लिए कि सदस्यता कितनी बचत करती है। | | `can_send_sms` | boolean | क्या इस नंबर से आउटबाउंड SMS भेजना समर्थित है। | | `can_receive_sms` | boolean | क्या इनबाउंड SMS समर्थित है। | | `sms_send_price` | number\|null | आउटबाउंड SMS मूल्य, प्लान छूट भी लागू है। `null` जब इस देश से भेजना समर्थित नहीं है। | **curl** ```bash curl https://app.piv.day/api/v1/numbers/countries \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": [ { "country_code": "SE", "price_per_month": 4.00, "base_price": 5.00, "can_send_sms": true, "can_receive_sms": true, "sms_send_price": 0.25 }, { "country_code": "GB", "price_per_month": 3.00, "base_price": 3.00, "can_send_sms": true, "can_receive_sms": true, "sms_send_price": 0.20 } ] } ``` ### खाते के नंबरों की सूची `GET /api/v1/numbers` देश, स्थिति द्वारा फ़िल्टर और नंबर या कस्टम नाम द्वारा खोज के साथ खाता नंबरों का एक पेज लौटाता है। **Query parameters** | Field | Type | Description | | --- | --- | --- | | `limit` | integer | पेज आकार (डिफ़ॉल्ट 50, अधिकतम 200)। | | `offset` | integer | पेजिनेशन ऑफसेट। | | `country` | string | ISO देश कोड फ़िल्टर। | | `status` | string | `active`, `expired`, `pending_restore` में से एक। | | `search` | string | फ़ोन नंबर या कस्टम नाम में सबस्ट्रिंग खोज। | **curl** ```bash curl "https://app.piv.day/api/v1/numbers?country=SE&status=active&limit=10" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "numbers": [ { "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o", "phone_number": "+46764794425", "country_code": "SE", "status": "active", "created_at": "2026-05-01T10:00:00Z", "expires_at": "2026-05-31T10:00:00Z", "auto_renew": false, "custom_name": "Office line", "purchased_at": "2026-05-01T10:00:00Z", "next_renewal_date": "2026-05-31T10:00:00Z", "tags": ["support"], "can_send_sms": true, "can_receive_sms": true } ], "pagination": { "total": 1, "limit": 10, "offset": 0 } } } ``` ### ID द्वारा एक नंबर प्राप्त करें `GET /api/v1/numbers/{piv_num_id}` पूर्ण नंबर रिकॉर्ड: स्थिति, तिथियां, ऑटो-नवीनीकरण, टैग, अनुमत SMS दिशाएं। **Errors** | Code | HTTP | When it fires | | --- | --- | --- | | `NUMBER_NOT_FOUND` | 404 | नंबर मौजूद नहीं है या खाते का नहीं है। | **curl** ```bash curl https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o", "phone_number": "+46764794425", "country_code": "SE", "status": "active", "created_at": "2026-05-01T10:00:00Z", "expires_at": "2026-05-31T10:00:00Z", "auto_renew": false, "custom_name": "Office line", "purchased_at": "2026-05-01T10:00:00Z", "next_renewal_date": "2026-05-31T10:00:00Z", "tags": ["support"], "can_send_sms": true, "can_receive_sms": true } } ``` ### एक नंबर खरीदें `POST /api/v1/numbers/purchase` चयनित देश में एक नंबर निर्दिष्ट अवधि के लिए खरीदता है। राशि खाते के बैलेंस से डेबिट होती है। `piv_num_id` लौटाता है जो सभी बाद के नंबर ऑपरेशन में उपयोग होता है। **Request body** | Field | Type | Description | | --- | --- | --- | | `country_code` * | string | ISO देश कोड। | | `duration_months` * | integer | महीनों में किराया अवधि (न्यूनतम 1)। | | `auto_renew` * | boolean | खरीद के तुरंत बाद ऑटो-नवीनीकरण चालू करें। | | `custom_name` | string | नंबर के लिए वैकल्पिक मानव-अनुकूल नाम। | **Errors** | Code | HTTP | When it fires | | --- | --- | --- | | `COUNTRY_NOT_AVAILABLE` | 400 | देश उपलब्ध नहीं है या इसके लिए कोई मूल्य नहीं है। | | `NO_NUMBERS_AVAILABLE` | 400 | अभी अनुरोधित देश में कोई मुफ़्त नंबर नहीं है। | | `INSUFFICIENT_BALANCE` | 402 | खरीद के लिए बैलेंस में पर्याप्त धनराशि नहीं है। | | `VALIDATION_ERROR` | 400 | अनुरोध बॉडी में अमान्य फ़ील्ड। | **curl** ```bash curl -X POST https://app.piv.day/api/v1/numbers/purchase \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "country_code": "SE", "duration_months": 1, "auto_renew": false, "custom_name": "My Sweden Number" }' ``` **200 OK** ```json { "success": true, "cost": 5.00, "numbers": [ { "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o", "country_code": "SE", "phone_number": "+46764794425", "created_at": "2026-05-01T10:00:00Z", "expires_at": "2026-05-31T10:00:00Z", "auto_renew": false, "custom_name": "My Sweden Number" } ] } ``` ### नंबर नवीनीकरण करें `POST /api/v1/numbers/{piv_num_id}/renew` एक सक्रिय नंबर को निर्दिष्ट अवधि के लिए विस्तारित करता है। कॉल के समय लागत डेबिट होती है। **Request body** | Field | Type | Description | | --- | --- | --- | | `duration_months` * | integer | कितने महीने जोड़ने हैं। | **Errors** | Code | HTTP | When it fires | | --- | --- | --- | | `NUMBER_NOT_FOUND` | 404 | नंबर मौजूद नहीं है या खाते का नहीं है। | | `COUNTRY_NOT_AVAILABLE` | 400 | नंबर के देश के लिए कोई मूल्य नहीं मिला। | | `INSUFFICIENT_BALANCE` | 402 | नवीनीकरण के लिए पर्याप्त धनराशि नहीं है। | **curl** ```bash curl -X POST https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/renew \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "duration_months": 1 }' ``` **200 OK** ```json { "success": true, "data": { "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o", "phone_number": "+46764794425", "old_expires_at": "2026-05-31T10:00:00Z", "new_expires_at": "2026-06-30T10:00:00Z", "cost": 5.00 } } ``` ### नंबर अपडेट करें `PATCH /api/v1/numbers/{piv_num_id}` वर्तमान में केवल कस्टम नाम अपडेट किया जा सकता है। **Request body** | Field | Type | Description | | --- | --- | --- | | `custom_name` * | string | नंबर के लिए नया नाम। | **Errors** | Code | HTTP | When it fires | | --- | --- | --- | | `NUMBER_NOT_FOUND` | 404 | नंबर मौजूद नहीं है या खाते का नहीं है। | | `VALIDATION_ERROR` | 400 | अनुरोध बॉडी में अमान्य मान। | **curl** ```bash curl -X PATCH https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "custom_name": "Support line" }' ``` **200 OK** ```json { "success": true, "data": { "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o", "phone_number": "+46764794425", "country_code": "SE", "status": "active", "custom_name": "Support line", "auto_renew": false, "expires_at": "2026-05-31T10:00:00Z", "tags": [] } } ``` ### ऑटो-नवीनीकरण प्रबंधन `PATCH /api/v1/numbers/{piv_num_id}/auto-renewal` नंबर का ऑटो-नवीनीकरण चालू या बंद करता है। सक्षम होने पर, समाप्ति से 24 घंटे पहले स्वचालित रूप से नवीनीकरण डेबिट होता है। यदि बैलेंस कम हो, नंबर समाप्त हो जाएगा; इसे `POST /numbers/restore` के माध्यम से 7 दिनों में पुनर्प्राप्त किया जा सकता है। **Request body** | Field | Type | Description | | --- | --- | --- | | `auto_renew` * | boolean | ऑटो-नवीनीकरण फ्लैग का नया मान। | **curl** ```bash curl -X PATCH https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/auto-renewal \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "auto_renew": true }' ``` **200 OK** ```json { "success": true, "data": { "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o", "phone_number": "+46764794425", "auto_renew": true } } ``` ### समाप्त हो चुके नंबर पुनर्स्थापित करें `POST /api/v1/numbers/restore` 7-दिन की विंडो के भीतर समाप्त हो चुके नंबर पुनः प्राप्त करता है। `piv_num_id` की एक array पास करें — नंबर SMS इतिहास और सेटिंग्स के साथ वापस आते हैं। पुनर्स्थापना की लागत नया नंबर खरीदने से अधिक है (पुनर्स्थापना गुणक शामिल है) — पुष्टि से पहले Dashboard में सटीक आंकड़े दिखते हैं। प्रत्येक नंबर का अंतिम स्थिति `number.restore_completed` webhook के माध्यम से आती है; असफल नंबरों के लिए रिफंड स्वचालित रूप से बैलेंस में जमा होता है। **Request body** | Field | Type | Description | | --- | --- | --- | | `piv_num_ids` * | string[] | पुनर्स्थापित करने के लिए नंबर ID की array। | **Errors** | Code | HTTP | When it fires | | --- | --- | --- | | `NO_RESTORABLE_NUMBERS` | 404 | दिए गए किसी भी नंबर को पुनर्स्थापित नहीं किया जा सकता (7-दिन की विंडो समाप्त हो गई या वे आपके नहीं हैं)। | | `INSUFFICIENT_BALANCE` | 402 | पुनर्स्थापना के लिए पर्याप्त धनराशि नहीं है। | **curl** ```bash curl -X POST https://app.piv.day/api/v1/numbers/restore \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "piv_num_ids": [ "vzPA1-kHKSg-EAL7e-Jqd3o", "abc12-defgh-ijklm-nopqr" ] }' ``` **200 OK** ```json { "success": true, "queued": 2, "skipped": 0, "total_charged": 9.00, "numbers": [ { "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o", "phone_number": "+46764794425", "status": "pending" } ] } ``` ### नंबर का SMS इतिहास `GET /api/v1/numbers/{piv_num_id}/sms` नंबर के लिए इनबाउंड और आउटबाउंड संदेश उल्टे कालानुक्रमिक क्रम में लौटाता है। **Query parameters** | Field | Type | Description | | --- | --- | --- | | `limit` | integer | कितने संदेश लौटाने हैं (डिफ़ॉल्ट 50, अधिकतम 200)। | | `offset` | integer | पेजिनेशन ऑफसेट। | **curl** ```bash curl "https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms?limit=20" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "messages": [ { "id": "42", "from_number": "+46764794425", "to_number": "+14155551234", "message_body": "Hello from piv.day", "direction": "outbound", "status": "delivered", "received_at": "2026-05-22T11:30:00Z" }, { "id": "41", "from_number": "+14155551234", "to_number": "+46764794425", "message_body": "Hey, got your message!", "direction": "inbound", "status": "received", "received_at": "2026-05-22T11:35:00Z" } ], "pagination": { "total": 2, "limit": 20, "offset": 0 } } } ``` ### SMS भेजें `POST /api/v1/numbers/{piv_num_id}/sms/send` उन देशों के लिए उपलब्ध जहां आउटबाउंड अनुमत है (जैसे CA, GB, SE)। संदेश लागत भेजने के समय डेबिट होती है। **Request body** | Field | Type | Description | | --- | --- | --- | | `to_number` * | string | अंतर्राष्ट्रीय प्रारूप (E.164) में प्राप्तकर्ता नंबर। | | `message_body` * | string | संदेश पाठ। GSM-7 और UCS-2 समर्थित हैं। | **Errors** | Code | HTTP | When it fires | | --- | --- | --- | | `NUMBER_NOT_FOUND` | 404 | नंबर मौजूद नहीं है या खाते का नहीं है। | | `NUMBER_EXPIRED` | 403 | नंबर पहले से समाप्त हो चुका है। | | `NUMBER_NOT_ACTIVE` | 400 | नंबर ऐसी स्थिति में है जो भेजने की अनुमति नहीं देती। | | `INSUFFICIENT_BALANCE` | 402 | भेजने के लिए पर्याप्त धनराशि नहीं है। | | `INVALID_MESSAGE_FORMAT` | 400 | संदेश बॉडी अनुमत लंबाई से अधिक है या प्रतिबंधित वर्ण शामिल हैं। | **curl** ```bash curl -X POST https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/sms/send \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to_number": "+14155551234", "message_body": "Hello from piv.day" }' ``` **200 OK** ```json { "success": true, "data": { "message_id": "42", "from_number": "+46764794425", "to_number": "+14155551234", "message_body": "Hello from piv.day", "status": "queued", "created_at": "2026-05-22T11:30:00Z" } } ``` ### Google QR सत्यापन चलाएं `POST /api/v1/numbers/{piv_num_id}/verify` प्रदत्त URL का उपयोग करके Google QR सत्यापन शुरू करता है। परिणाम — सफलता या विफलता — verify.completed या verify.failed webhook के माध्यम से आता है। कार्य कतारबद्ध होने पर लागत डेबिट होती है। **Request body** | Field | Type | Description | | --- | --- | --- | | `gv_url` * | string | पूर्ण Google सत्यापन URL (Google के पेज से लिया गया)। | **Errors** | Code | HTTP | When it fires | | --- | --- | --- | | `NUMBER_NOT_FOUND` | 404 | नंबर मौजूद नहीं है या आपका नहीं है। | | `NUMBER_NOT_ACTIVE` | 400 | नंबर सक्रिय नहीं है। | | `SMS_DISABLED` | 400 | इस नंबर के लिए SMS भेजना अक्षम है। | | `INSUFFICIENT_BALANCE` | 402 | सत्यापन के लिए पर्याप्त धनराशि नहीं है। | | `PROXY_DEAD` | 502 | Proxy अनुपलब्ध — बैलेंस वापस किया गया। | | `QUEUE_FULL` | 503 | कतार भरी है, बाद में प्रयास करें — बैलेंस वापस किया गया। | | `SERVER_UNAVAILABLE` | 503 | ऑटोमेशन सर्वर अनुपलब्ध — बैलेंस वापस किया गया। | **curl** ```bash curl -X POST https://app.piv.day/api/v1/numbers/vzPA1-kHKSg-EAL7e-Jqd3o/verify \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "gv_url": "https://gv.google.com/..." }' ``` **202 Accepted** ```json { "success": true, "message": "Verification initiated" } ``` ## प्रॉक्सी दर्जनों देशों में आवासीय IPv6। बल्क खरीद, नवीनीकरण, Restore जो समान login और पासवर्ड बनाए रखता है, आवश्यक फ़ॉर्मेट में export। ### सर्वर सूची `GET /api/v1/proxy/servers` उपलब्ध proxy सर्वर और उनकी कीमतें। **curl** ```bash curl https://app.piv.day/api/v1/proxy/servers \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "servers": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "EU-DE-01", "country": "DE", "socks5_port": 1080, "http_port": 3128, "price_per_proxy": 0.50 }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "EU-NL-01", "country": "NL", "socks5_port": 1080, "http_port": 3128, "price_per_proxy": 0.45 } ] } } ``` ### ऑर्डर सूची `GET /api/v1/proxy/orders` आपके proxy ऑर्डर की सूची, स्टेटस या खोज के आधार पर फ़िल्टर करने की सुविधा के साथ। **Query parameters** | Field | Type | Description | | --- | --- | --- | | `limit` | integer | पेज आकार। डिफ़ॉल्ट 100, अधिकतम 500। | | `offset` | integer | पेजीनेशन ऑफ़सेट। | | `status` | string | स्टेटस फ़िल्टर: `active`, `expired`। | | `search` | string | ऑर्डर में खोज। | **curl** ```bash curl "https://app.piv.day/api/v1/proxy/orders?status=active&limit=20" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "orders": [ { "id": "ord-uuid-...", "country": "DE", "quantity": 10, "price_per_proxy": 0.50, "price_total": 5.00, "status": "active", "purchased_at": "2026-01-01T00:00:00Z", "expires_at": "2026-02-01T00:00:00Z" } ], "pagination": { "total": 1, "limit": 20, "offset": 0 } } } ``` ### एक ऑर्डर प्राप्त करें `GET /api/v1/proxy/orders/{id}` किसी विशेष ऑर्डर का विवरण प्राप्त करें, जिसमें proxy क्रेडेंशियल्स की सूची शामिल है। **curl** ```bash curl https://app.piv.day/api/v1/proxy/orders/ord-uuid-... \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "order": { "id": "ord-uuid-...", "country": "DE", "quantity": 10, "price_per_proxy": 0.50, "price_total": 5.00, "status": "active", "purchased_at": "2026-01-01T00:00:00Z", "expires_at": "2026-02-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "items": [ { "login": "user1", "password": "pass1", "host": "185.1.2.3", "socks5_port": 1080, "http_port": 3128, "ipv6": "2a00:1:2:3::1" } ] } } } ``` ### प्रॉक्सी खरीदें `POST /api/v1/proxy/purchase` चुने हुए सर्वर पर proxy खरीदें। एक अनुरोध N proxy के साथ एक ऑर्डर बनाता है (अधिकतम 500)। Bulk ऑर्डर नहीं हैं — अधिक की आवश्यकता होने पर method को पुनः कॉल करें। **Request body** | Field | Type | Description | | --- | --- | --- | | `server_id` * | string | `GET /proxy/servers` से सर्वर ID। | | `quantity` * | integer | कितने proxy खरीदें (1–500)। | | `months` * | integer | किराये की अवधि महीनों में (1–12)। | **Errors** | Code | HTTP | When it fires | | --- | --- | --- | | `INSUFFICIENT_BALANCE` | 402 | पर्याप्त धनराशि नहीं। | | `NOT_FOUND` | 404 | Proxy सर्वर नहीं मिला या निष्क्रिय है। | | `VALIDATION_ERROR` | 400 | अमान्य अनुरोध बॉडी। | **curl** ```bash curl -X POST https://app.piv.day/api/v1/proxy/purchase \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "server_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "quantity": 5, "months": 1 }' ``` **200 OK** ```json { "success": true, "data": { "order": { "id": "ord-uuid-...", "country": "DE", "quantity": 5, "price_total": 2.50, "status": "active", "expires_at": "2026-02-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "items": [ { "login": "user1", "password": "pass1", "host": "185.1.2.3", "socks5_port": 1080, "http_port": 3128, "ipv6": "2a00:1:2:3::1" }, { "login": "user2", "password": "pass2", "host": "185.1.2.3", "socks5_port": 1080, "http_port": 3128, "ipv6": "2a00:1:2:3::2" } ] } } } ``` ### ऑर्डर नवीनीकृत करें `POST /api/v1/proxy/orders/{id}/renew` किसी सक्रिय proxy ऑर्डर को कुछ महीनों के लिए बढ़ाएं। **Request body** | Field | Type | Description | | --- | --- | --- | | `months` * | integer | कितने महीने जोड़ने हैं। | **curl** ```bash curl -X POST https://app.piv.day/api/v1/proxy/orders/ord-uuid-.../renew \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "months": 1 }' ``` **200 OK** ```json { "success": true, "data": { "order_id": "ord-uuid-...", "cost": 5.00, "new_expires_at": "2026-03-01T00:00:00Z" } } ``` ### समाप्त ऑर्डर का Restore `POST /api/v1/proxy/orders/{id}/restore` दोबारा खरीदारी के बिना समाप्त Proxy ऑर्डर को वापस लाएं। Login, password, IPv6 addresses, देश और बाइंडिंग — वही रहते हैं। अवधि 1 महीने के लिए बढ़ जाती है। Antidetect को दोबारा कॉन्फ़िगर करने की ज़रूरत नहीं। **curl** ```bash curl -X POST https://app.piv.day/api/v1/proxy/orders/ord-uuid-.../restore \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "order_id": "ord-uuid-...", "quantity": 10, "total_cost": 5.00, "expires_at": "2026-03-01T00:00:00Z" } } ``` ### प्रॉक्सी सूची निर्यात करें `GET /api/v1/proxy/orders/{id}/export` ऑर्डर की proxy क्रेडेंशियल्स को टेक्स्ट सूची के रूप में export करें (login:password@host:port)। **Query parameters** | Field | Type | Description | | --- | --- | --- | | `format` | string | Export फ़ॉर्मेट: `socks5`, `http` या `both` (डिफ़ॉल्ट `socks5`)। | **curl** ```bash curl "https://app.piv.day/api/v1/proxy/orders/ord-uuid-.../export?format=socks5" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "content": "user1:pass1@1.2.3.4:1080\nuser2:pass2@1.2.3.4:1080", "filename": "piv-day-proxy-ord-uuid--socks5.txt", "format": "socks5", "count": 2 } } ``` ## डोमेन KYC के बिना खोज और पंजीकरण, स्वचालित Cloudflare और SSL, API के माध्यम से DNS रिकॉर्ड और NS सर्वर प्रबंधन। ### उपलब्धता जांच `GET /api/v1/domains/search` यह जांचें कि कोई डोमेन उपलब्ध है या नहीं और इसे रजिस्टर करने में कितना खर्च आता है। **Query parameters** | Field | Type | Description | | --- | --- | --- | | `q` * | string | खोजने के लिए डोमेन नाम, उदाहरण: `mysite.com`। | **curl** ```bash curl "https://app.piv.day/api/v1/domains/search?q=mysite.com" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "domain": "mysite.com", "available": true, "create_price": 12.50, "renew_price": 12.50, "currency": "USD" } } ``` ### डोमेन सूची `GET /api/v1/domains` आपके पंजीकृत डोमेन की सूची, फ़िल्टरिंग के साथ। **Query parameters** | Field | Type | Description | | --- | --- | --- | | `limit` | integer | रिकॉर्ड की संख्या। डिफ़ॉल्ट: 100, अधिकतम: 500। | | `offset` | integer | पेजिनेशन के लिए ऑफसेट। | | `status` | string | डोमेन स्थिति: `active`, `pending`, `expired`। | | `cloudflare` | string | Cloudflare स्थिति के अनुसार फ़िल्टर करें: `true` या `false`। | | `auto_renew` | string | ऑटो-रिन्यू के अनुसार फ़िल्टर करें: `true` या `false`। | | `search` | string | डोमेन नाम से खोजें। | **curl** ```bash curl "https://app.piv.day/api/v1/domains?status=active&limit=20" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "domains": [ { "id": "dom-uuid-...", "domain_name": "mysite.com", "status": "active", "registered_at": "2026-01-01T00:00:00Z", "expires_at": "2027-01-01T00:00:00Z", "auto_renew": true, "cloudflare_enabled": true, "cloudflare_status": "active", "ssl_type": "lets_encrypt", "ssl_status": "active", "ssl_mode": "full", "ssl_expires_at": "2026-04-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ], "pagination": { "total": 1, "limit": 20, "offset": 0 } } } ``` ### डोमेन रजिस्टर करें `POST /api/v1/domains` एक नया डोमेन रजिस्टर करें। अनुरोध async है — ट्रैकिंग के लिए `queue_id` लौटाता है। Cloudflare चालू: `nameservers` न पास करें; वैकल्पिक रूप से `dns_records` और `ssl_mode` पास कर सकते हैं। Cloudflare बंद: `dns_records` या `ssl_mode` न पास करें; `nameservers` आवश्यक है (कम से कम 2)। हम Cloudflare के nameservers कभी नहीं बताते। **Request body** | Field | Type | Description | | --- | --- | --- | | `domain` * | string | रजिस्टर करने के लिए डोमेन नाम, उदाहरण: `mysite.com`। | | `period` * | integer | पंजीकरण अवधि वर्षों में (1–10)। | | `cloudflare` * | boolean | डोमेन को Cloudflare से स्वचालित रूप से कनेक्ट करें। | | `auto_renew` * | boolean | ऑटो-रिन्यू सक्षम करें। | | `ssl_mode` | string | `flexible` \| `full` \| `strict`। केवल `cloudflare: true` के साथ। | | `nameservers` | string[] | `cloudflare: false` के साथ आवश्यक (≥2 NS)। `cloudflare: true` के साथ वर्जित। | | `dns_records` | object[] | प्रारंभिक DNS रिकॉर्ड। केवल `cloudflare: true` के साथ। | **Errors** | Code | HTTP | When it fires | | --- | --- | --- | | `DOMAIN_NOT_AVAILABLE` | 400 | डोमेन पंजीकरण के लिए उपलब्ध नहीं है। | | `INSUFFICIENT_BALANCE` | 402 | पर्याप्त धनराशि नहीं है। | | `VALIDATION_ERROR` | 400 | अनुरोध बॉडी अमान्य है। | **Cloudflare चालू** ```bash curl -X POST https://app.piv.day/api/v1/domains \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "mysite.com", "period": 1, "cloudflare": true, "auto_renew": true, "ssl_mode": "full", "dns_records": [ { "type": "A", "name": "@", "content": "1.2.3.4", "proxied": true } ] }' ``` **Cloudflare बंद — अपने NS** ```bash curl -X POST https://app.piv.day/api/v1/domains \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "mysite.com", "period": 1, "cloudflare": false, "auto_renew": false, "nameservers": ["ns1.myhost.com", "ns2.myhost.com"] }' ``` **202 Accepted** ```json { "success": true, "data": { "queue_id": "que-uuid-...", "domain": { "id": "dom-uuid-...", "domain_name": "mysite.com", "status": "purchasing", "period": 1, "cloudflare_enabled": true, "auto_renew": true, "ssl_mode": "full", "created_at": "2026-01-01T00:00:00Z" } } } ``` ### पंजीकरण कतार की स्थिति `GET /api/v1/domains/queue/{id}` डोमेन पंजीकरण या नवीनीकरण कतार प्रविष्टि की स्थिति जांचें। `completed` स्थिति पर प्रतिक्रिया में पहले से पूरा डोमेन कार्ड होता है — `/domains/{id}` के लिए अलग अनुरोध की जरूरत नहीं। **curl** ```bash curl https://app.piv.day/api/v1/domains/queue/que-uuid-... \ -H "Authorization: Bearer YOUR_API_KEY" ``` **pending / processing** ```json { "success": true, "data": { "queue_id": "que-uuid-...", "domain": "mysite.com", "status": "pending" } } ``` **completed — पूरा कार्ड** ```json { "success": true, "data": { "queue_id": "que-uuid-...", "status": "completed", "domain": { "id": "dom-uuid-...", "domain_name": "mysite.com", "status": "active", "registered_at": "2026-01-01T12:00:00Z", "expires_at": "2027-01-01T12:00:00Z", "auto_renew": true, "cloudflare_enabled": true, "cloudflare_status": "active", "ssl_type": "lets_encrypt", "ssl_status": "active", "ssl_mode": "full", "ssl_expires_at": "2026-04-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T12:00:00Z", "dns_records": [ { "name": "@", "type": "A", "content": "1.2.3.4", "ttl": 1, "priority": null, "proxied": true } ] } } } ``` ### एक डोमेन प्राप्त करें `GET /api/v1/domains/{id}` पंजीकृत डोमेन की पूरी जानकारी प्राप्त करें। `nameservers` फ़ील्ड केवल तब मौजूद होता है जब `cloudflare_enabled: false`। **curl** ```bash curl https://app.piv.day/api/v1/domains/dom-uuid-... \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "domain": { "id": "dom-uuid-...", "domain_name": "mysite.com", "status": "active", "registered_at": "2026-01-01T12:00:00Z", "expires_at": "2027-01-01T12:00:00Z", "auto_renew": true, "cloudflare_enabled": true, "cloudflare_status": "active", "ssl_type": "lets_encrypt", "ssl_status": "active", "ssl_mode": "full", "ssl_expires_at": "2026-04-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T12:00:00Z", "dns_records": [ { "name": "@", "type": "A", "content": "1.2.3.4", "ttl": 1, "priority": null, "proxied": true }, { "name": "www", "type": "CNAME", "content": "mysite.com", "ttl": 1, "priority": null, "proxied": true } ] } } } ``` ### डोमेन नवीनीकृत करें `POST /api/v1/domains/{id}/renew` डोमेन पंजीकरण नवीनीकृत करें। ट्रैकिंग के लिए `queue_id` लौटाता है। **Request body** | Field | Type | Description | | --- | --- | --- | | `period` * | integer | कितने वर्षों के लिए नवीनीकृत करें। | **curl** ```bash curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../renew \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "period": 1 }' ``` **202 Accepted** ```json { "success": true, "data": { "queue_id": "que-uuid-...", "domain_id": "dom-uuid-...", "expires_at": "2027-01-01T12:00:00Z" } } ``` ### ऑटो-रिन्यू टॉगल `POST /api/v1/domains/{id}/auto-renew` डोमेन का ऑटो-रिन्यूअल चालू या बंद करें। **Request body** | Field | Type | Description | | --- | --- | --- | | `auto_renew` * | boolean | नया फ्लैग मान। | **curl** ```bash curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../auto-renew \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "auto_renew": true }' ``` **200 OK** ```json { "success": true, "data": { "id": "dom-uuid-...", "auto_renew": true } } ``` ### डोमेन DNS रिकॉर्ड `GET /api/v1/domains/{id}/dns` डोमेन के DNS रिकॉर्ड की सूची (Cloudflare के माध्यम से)। **curl** ```bash curl https://app.piv.day/api/v1/domains/dom-uuid-.../dns \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "records": [ { "id": "rec-uuid-...", "type": "A", "name": "@", "content": "1.2.3.4", "ttl": 1, "priority": null, "proxied": true } ] } } ``` ### DNS रिकॉर्ड जोड़ें `POST /api/v1/domains/{id}/dns` नया DNS रिकॉर्ड बनाएं। **Request body** | Field | Type | Description | | --- | --- | --- | | `type` * | string | रिकॉर्ड प्रकार: `A`, `AAAA`, `CNAME`, `MX`, `TXT` आदि। | | `name` * | string | रिकॉर्ड नाम, उदाहरण: `@` या `subdomain`। | | `content` * | string | रिकॉर्ड मान। | | `ttl` | integer | TTL सेकंड में (`1` = स्वतः)। | | `proxied` | boolean | Cloudflare के माध्यम से प्रॉक्सी करें। | **curl** ```bash curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../dns \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "A", "name": "@", "content": "1.2.3.4", "ttl": 1, "proxied": true }' ``` **201 Created** ```json { "success": true, "data": { "record": { "id": "rec-uuid-...", "type": "A", "name": "@", "content": "1.2.3.4", "ttl": 1, "priority": null, "proxied": true } } } ``` ### DNS रिकॉर्ड अपडेट करें `PUT /api/v1/domains/{id}/dns/{recordId}` ID के आधार पर मौजूदा DNS रिकॉर्ड अपडेट करें। केवल पास किए गए फ़ील्ड ओवरराइट होते हैं। **curl** ```bash curl -X PUT https://app.piv.day/api/v1/domains/dom-uuid-.../dns/rec-uuid-... \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "5.6.7.8" }' ``` ### DNS रिकॉर्ड हटाएं `DELETE /api/v1/domains/{id}/dns/{recordId}` ID के आधार पर DNS रिकॉर्ड हटाएं। **curl** ```bash curl -X DELETE https://app.piv.day/api/v1/domains/dom-uuid-.../dns/rec-uuid-... \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Cloudflare सक्षम करें `POST /api/v1/domains/{id}/cloudflare` डोमेन के लिए Cloudflare सक्षम करें। हम Cloudflare nameservers नहीं देते — डेलीगेशन हमारी तरफ से सेट किया जाता है। इस endpoint के माध्यम से Cloudflare अक्षम करना समर्थित नहीं है। **curl** ```bash curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../cloudflare \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "enabled": true }' ``` **200 OK** ```json { "success": true, "data": { "domain_id": "dom-uuid-...", "ssl_mode": "flexible" } } ``` ### NS सर्वर सेट करें `POST /api/v1/domains/{id}/ns-servers` डोमेन के लिए कस्टम NS सर्वर सेट करें। **curl** ```bash curl -X POST https://app.piv.day/api/v1/domains/dom-uuid-.../ns-servers \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "nameservers": ["ns1.example.com", "ns2.example.com"] }' ``` **200 OK** ```json { "success": true, "data": { "nameservers": [ { "nameserver": "ns1.example.com", "order_index": 1 }, { "nameserver": "ns2.example.com", "order_index": 2 } ] } } ``` ## Whites niche और tier के अनुसार white-page जनरेशन। प्रत्येक साइट अद्वितीय है। बिना पुनः-जनरेशन के domain और संपर्क बदलें। ### Tier सूची `GET /api/v1/whites/tiers` कीमतों के साथ उपलब्ध जनरेशन tier। `price` प्रति-जनरेशन मूल्य है जो आपके खाते के अनुसार (सदस्यता लागू) पहले से समायोजित है, एक संख्या। `quality: "premium"` अधिक महंगा है (बनाने के समय गणना)। Blog केवल `v2_tier3` पर: पहले 3 लेख शामिल हैं, प्रत्येक अतिरिक्त (20 तक) `extra_article_price` पर शुल्क। **curl** ```bash curl https://app.piv.day/api/v1/whites/tiers \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "tiers": [ { "tier_key": "v2_tier1", "name": "Landing", "generator_version": "v2", "min_articles": 0, "max_articles": 0, "price": 3.00, "extra_article_price": null }, { "tier_key": "v2_tier2", "name": "Multi-page", "generator_version": "v2", "min_articles": 0, "max_articles": 0, "price": 6.00, "extra_article_price": null }, { "tier_key": "v2_tier3", "name": "Full + Blog", "generator_version": "v2", "min_articles": 3, "max_articles": 20, "price": 10.00, "extra_article_price": 1.50 } ] } } ``` ### White सूची `GET /api/v1/whites` फ़िल्टरिंग के साथ आपके जनरेशन jobs की सूची। **Query parameters** | Field | Type | Description | | --- | --- | --- | | `limit` | integer | पृष्ठ आकार। डिफ़ॉल्ट 100, अधिकतम 500। | | `offset` | integer | पेजिनेशन offset। | | `status` | string | `queued` \| `processing` \| `done` \| `failed`। | | `tier_key` | string | `v2_tier1` \| `v2_tier2` \| `v2_tier3`। | **curl** ```bash curl "https://app.piv.day/api/v1/whites?status=done&limit=20" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "whites": [ { "id": "job-uuid-...", "name": "My White", "status": 10, "tier_key": "v2_tier3", "quality": "standard", "niche": "IT Consulting", "country": "DE", "language": "de", "domain": "mysite.com", "result_url": null, "created_at": "2026-01-01T00:00:00Z" } ], "pagination": { "total": 1, "limit": 20, "offset": 0 } } } ``` ### जनरेशन शुरू करें `POST /api/v1/whites` white-page जनरेशन job को queue में डालें। भुगतान तुरंत लिया जाता है। अंतिम स्थिति `white.completed` / `white.failed` webhook के माध्यम से आती है या `GET /whites/{id}` से जांची जा सकती है। **Request body** | Field | Type | Description | | --- | --- | --- | | `name` * | string | Job का नाम (2–20 अक्षर)। | | `tier_key` * | string | `v2_tier1` \| `v2_tier2` \| `v2_tier3`। | | `niche` * | string | साइट का niche (25 अक्षरों तक)। | | `country` * | string | देश कोड (ISO 3166-1 alpha-2)। | | `language` * | string | साइट की प्राथमिक भाषा (ISO 639-1)। | | `quality` | string | `standard` \| `premium` (डिफ़ॉल्ट `standard`)। | | `languages` | string[] | भाषाओं की सूची। पहली कीमत में शामिल है; हर अतिरिक्त भाषा के लिए अधिक शुल्क। | | `domain` | string | पूरा domain (उदा. `example.com`)। कोई auto-completion नहीं। | | `email` | string | पूरा email (उदा. `info@example.com`)। कोई auto-completion नहीं। | | `phone` | string | संपर्क फ़ोन। | | `address` | string | कंपनी का पता। | | `legal_name` | string | कानूनी नाम। | | `style_hint` | string | डिज़ाइन शैली (Random, Minimal, Corporate, आदि)। | | `keywords` | string[] | SEO कीवर्ड। | | `banned_words` | string[] | कंटेंट में प्रतिबंधित शब्द। | | `blog_count` | integer | Blog लेखों की संख्या 3–20। केवल `v2_tier3` के लिए। 3 से अधिक लेखों पर अतिरिक्त शुल्क। | | `contacts_mode` | string | `same` \| `template`। | | `contacts_template` | string | संपर्क पृष्ठ template (`contacts_mode=template` होने पर)। | | `facebook` | string | Facebook पेज का पूरा URL। | | `instagram` | string | Instagram प्रोफ़ाइल का पूरा URL। | | `linkedin` | string | LinkedIn प्रोफ़ाइल का पूरा URL। | | `youtube` | string | YouTube चैनल का पूरा URL। | | `tiktok` | string | TikTok प्रोफ़ाइल का पूरा URL। | **Errors** | Code | HTTP | When it fires | | --- | --- | --- | | `INSUFFICIENT_BALANCE` | 402 | पर्याप्त धनराशि नहीं। | | `INVALID_TIER` | 400 | उस key वाला कोई tier नहीं मिला। | | `VALIDATION_ERROR` | 400 | अमान्य request body। | **curl** ```bash curl -X POST https://app.piv.day/api/v1/whites \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Tech Blog DE", "tier_key": "v2_tier3", "niche": "IT Consulting", "country": "DE", "language": "de", "quality": "premium", "languages": ["de", "en"], "domain": "techblog-de.com", "email": "info@techblog-de.com", "phone": "+49 30 123456", "address": "Berliner Str. 1, 10115 Berlin", "legal_name": "TechBlog GmbH", "style_hint": "Корпоративный", "keywords": ["IT", "consulting", "cloud"], "banned_words": ["cheap", "free"], "blog_count": 8, "contacts_mode": "same", "facebook": "https://facebook.com/techblogde", "instagram": "https://instagram.com/techblogde", "linkedin": "https://linkedin.com/company/techblogde" }' ``` **200 OK** ```json { "success": true, "data": { "status": "queued", "white": { "id": "job-uuid-...", "name": "Tech Blog DE", "status": 0, "tier_key": "v2_tier3", "quality": "premium", "niche": "IT Consulting", "country": "DE", "language": "de", "domain": "techblog-de.com", "result_url": null, "created_at": "2026-01-01T00:00:00Z" } } } ``` ### एक white प्राप्त करें `GET /api/v1/whites/{id}` जनरेशन job की वर्तमान स्थिति प्राप्त करें। **curl** ```bash curl https://app.piv.day/api/v1/whites/job-uuid-... \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "white": { "id": "job-uuid-...", "name": "Tech Blog DE", "status": 10, "tier_key": "v2_tier3", "quality": "premium", "niche": "IT Consulting", "country": "DE", "language": "de", "domain": "techblog-de.com", "result_url": null, "created_at": "2026-01-01T00:00:00Z" } } } ``` ### Archive डाउनलोड करें `GET /api/v1/whites/{id}/download` तैयार white-page archive का एक अल्पकालिक signed link प्राप्त करें। Link ~5 मिनट के लिए वैध है (देखें `expires_at`)। यदि समाप्त हो गया — बस `/download` फिर से कॉल करें, हम नया जारी करेंगे। यदि white page अभी तक जनरेट नहीं हुई, `409 NOT_READY` लौटाता है। **Query parameters** | Field | Type | Description | | --- | --- | --- | | `format` | string | Archive format। डिफ़ॉल्ट `php`। | **Errors** | Code | HTTP | When it fires | | --- | --- | --- | | `NOT_READY` | 409 | White page अभी भी जनरेट हो रही है — `white.completed` के बाद पुनः प्रयास करें। | **curl** ```bash curl "https://app.piv.day/api/v1/whites/job-uuid-.../download?format=php" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **200 OK** ```json { "success": true, "data": { "url": "https://strg.piv.day/download//?format=php&token=&filename=.zip", "filename": "example.com_2026-05-28_DE_en.zip", "format": "php", "expires_at": "2026-05-28T14:46:00Z" } } ``` ### Domain और संपर्क बदलें `POST /api/v1/whites/{id}/config` बिना पुनः-जनरेशन के white-page में कंपनी के संपर्क डेटा को अपडेट करें। **curl** ```bash curl -X POST https://app.piv.day/api/v1/whites/job-uuid-.../config \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "company": "My Brand", "domain": "newdomain.com", "email": "info@newdomain.com", "phone": "+49 30 123456", "address": "Berliner Str. 1, Berlin", "legal": "My Brand GmbH" }' ``` ## Webhooks हम आपके URL पर JSON बॉडी के साथ एक सामान्य POST भेजते हैं। सभी इवेंट के लिए फ़ॉर्मेट एक जैसा है: `event_type`, `timestamp` और एक `data` ब्लॉक। आपके सर्वर को 5 सेकंड के भीतर किसी भी 2xx के साथ जवाब देना चाहिए। ``` POST Content-Type: application/json User-Agent: piv.day-webhook/1.0 { "event_type": "", "timestamp": "2026-05-22T12:34:56Z", "data": { ... } } ``` **Retries.** नॉन-2xx या टाइमआउट पर — 1s / 2s / 4s बैकऑफ़ के साथ 3 तक पुनः प्रयास। पूरा डिलीवरी इतिहास dashboard के API keys पेज पर उपलब्ध है। यदि तीनों फेल हो जाएं — इवेंट को failed के रूप में चिह्नित किया जाता है और इसे मैन्युअल रूप से पुनः भेजा जा सकता है। **Security.** HTTPS एंडपॉइंट का उपयोग करें। हर अनुरोध `User-Agent: piv.day-webhook/1.0` हेडर के साथ आता है। Webhook URL को API key प्रोफ़ाइल में कॉन्फ़िगर किया जाता है। ### All events | Event | When it fires | | --- | --- | | `sms.received` | एक विश्वसनीय प्रेषक ने आपके किसी नंबर पर अभी-अभी SMS भेजा। | | `sms.status_updated` | एक आउटबाउंड SMS की स्थिति बदल गई — डिलीवर हुआ, फेल हुआ, आदि। | | `number.restore_completed` | एक बैच Restore पूरा हो गया — अंतिम विवरण यहाँ आता है। | | `verify.completed` | Google खाता सत्यापन सफलतापूर्वक पूरा हो गया। | | `verify.failed` | कुछ गलत हो गया — Google ने इसे स्वीकार नहीं किया। | | `proxy.expires_soon` | Proxy ऑर्डर समाप्त होने में लगभग तीन दिन बाकी हैं। | | `domain.registered` | पंजीकरण ऑर्डर सफलतापूर्वक पूरा हुआ — डोमेन सक्रिय है। | | `domain.failed` | ऑर्डर पूरा नहीं हुआ — सामान्य कारण: नाम अभी-अभी किसी ने ले लिया। | | `domain.expires_soon` | डोमेन समाप्त होने में लगभग एक सप्ताह बाकी है। | | `white.completed` | White जनरेशन कार्य सफलतापूर्वक पूरा हुआ। | | `white.failed` | कार्य विफल हुआ — धनराशि बैलेंस में वापस आती है। | ### आपके नंबर पर आने वाला SMS **`sms.received`** अक्सर ये विज्ञापन नेटवर्क के सत्यापन कोड होते हैं। Payload में कच्चा टेक्स्ट और स्वचालित रूप से पहचाना गया कोड (जब मौजूद हो) दोनों शामिल होते हैं — आप इसे बिना parsing के सीधे अपने workflow में भेज सकते हैं। ज्ञात स्पैम प्रेषकों के SMS वेबहुक से नहीं भेजे जाते। ```json { "event_type": "sms.received", "timestamp": "2026-05-22T12:34:56Z", "data": { "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o", "text": "Your verification code is 123456", "code": "123456", "country": "SE", "received_at": "2026-05-22T12:34:56Z" } } ``` ### भेजे गए SMS की स्थिति बदल गई **`sms.status_updated`** उपयोगी है जब आप अपने नंबर से पुष्टिकरण भेजते हैं और जानना चाहते हैं कि वे वास्तव में पहुंचे या नहीं। यदि स्थिति failed है, तो carrier का त्रुटि कोड और संदेश payload में होते हैं। ```json { "event_type": "sms.status_updated", "timestamp": "2026-05-22T12:34:56Z", "data": { "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o", "message_id": "42", "old_status": "sent", "new_status": "delivered", "error_code": null, "error_message": null } } ``` ### नंबर पुनर्स्थापना पूर्ण हुई **`number.restore_completed`** दो सूचियाँ शामिल हैं — कौन से नंबर वापस आए और कौन से नहीं। फेल हुए नंबरों के लिए वापस की गई राशि भी payload में है। स्क्रिप्ट के लिए सुविधाजनक: समझना आसान है कि फिर से क्या मांगना है। ```json { "event_type": "number.restore_completed", "timestamp": "2026-05-22T12:34:56Z", "data": { "restored": [ { "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o", "phone_number": "+46764794425", "country": "SE" } ], "failed": [ { "piv_num_id": "abc12-defgh-ijklm-nopqr", "phone_number": "+46123456789", "country": "SE", "refunded": 7.50 } ], "total_restored": 1, "total_failed": 1, "total_refunded": 7.50 } } ``` ### Google QR सत्यापन सफल हुआ **`verify.completed`** यदि प्रक्रिया के दौरान कोड वाला SMS आया — वह पहले से यहाँ है, अलग से fetch करने की जरूरत नहीं। captured_phone और captured_message में वह है जो Google ने भेजा। ```json { "event_type": "verify.completed", "timestamp": "2026-05-22T12:34:56Z", "data": { "task_id": 12, "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o", "status": "sms_sent", "captured_phone": "+14155551234", "captured_message": "Your Google verification code is 123456", "sms_message_id": 42, "sms_status": "queued" } } ``` ### Google QR सत्यापन विफल हुआ **`verify.failed`** error_code बताता है क्या हुआ — timeout, अस्वीकृति, अमान्य URL। विफल सत्यापन के लिए राशि स्वचालित रूप से बैलेंस में वापस आती है। ```json { "event_type": "verify.failed", "timestamp": "2026-05-22T12:34:56Z", "data": { "task_id": 12, "piv_num_id": "vzPA1-kHKSg-EAL7e-Jqd3o", "status": "failed", "error_code": "VERIFY_TIMEOUT", "error_message": "Verification timed out" } } ``` ### Proxy जल्द समाप्त होगी **`proxy.expires_soon`** उन लोगों के लिए जो स्वचालित रूप से नवीनीकरण नहीं करते: पहले से देख लें और तय करें — कैंपेन बढ़ाएं या बंद करें। पूरी तरह स्वचालित नवीनीकरण के लिए POST /proxy/orders/{id}/renew से जोड़ें। ```json { "event_type": "proxy.expires_soon", "timestamp": "2026-05-22T12:34:56Z", "data": { "order_id": "ord-uuid-...", "country": "DE", "quantity": 10, "expires_at": "2026-05-25T00:00:00Z" } } ``` ### डोमेन पंजीकृत हुआ **`domain.registered`** यदि खरीद के समय आपने Cloudflare और SSL का अनुरोध किया था, तो दोनों पहले से सक्रिय हैं — cloudflare_enabled स्थिति दिखाता है। आप तुरंत DNS रिकॉर्ड जोड़ सकते हैं या साइट deploy कर सकते हैं। ```json { "event_type": "domain.registered", "timestamp": "2026-05-22T12:34:56Z", "data": { "domain_id": "dom-uuid-...", "domain_name": "mysite.com", "registered_at": "2026-05-22T12:34:56Z", "expires_at": "2027-05-22T12:34:56Z", "cloudflare_enabled": true } } ``` ### डोमेन पंजीकरण विफल हुआ **`domain.failed`** error फ़ील्ड में मानव-पठनीय कारण है। राशि बैलेंस में वापस आती है। दूसरा नाम चुनें और दोबारा ऑर्डर करें। ```json { "event_type": "domain.failed", "timestamp": "2026-05-22T12:34:56Z", "data": { "domain_id": "dom-uuid-...", "domain_name": "mysite.com", "error": "Domain is no longer available" } } ``` ### डोमेन जल्द समाप्त होगा **`domain.expires_soon`** जब ऑटो-नवीनीकरण बंद हो तब उपयोगी: डोमेन redemption में जाने से पहले मैन्युअल रूप से नवीनीकरण करने का समय मिलता है। auto_renew फ़्लैग बताता है कि हस्तक्षेप जरूरी है या नहीं। ```json { "event_type": "domain.expires_soon", "timestamp": "2026-05-22T12:34:56Z", "data": { "domain_id": "dom-uuid-...", "domain_name": "mysite.com", "expires_at": "2026-05-29T00:00:00Z", "auto_renew": false } } ``` ### White जनरेट हुआ **`white.completed`** आर्काइव GET /whites/{id}/download के माध्यम से उपलब्ध है। यदि White के लिए डोमेन सेट था, तो sitemap और contacts पहले से उससे जुड़े हुए हैं — deploy के लिए तैयार। ```json { "event_type": "white.completed", "timestamp": "2026-05-22T12:34:56Z", "data": { "job_id": "job-uuid-...", "name": "My White", "tier_key": "t1", "country": "DE" } } ``` ### White जनरेशन विफल हुई **`white.failed`** error फ़ील्ड कारण बताता है। POST /whites के माध्यम से तुरंत नया कार्य शुरू करें — कोई नुकसान नहीं। ```json { "event_type": "white.failed", "timestamp": "2026-05-22T12:34:56Z", "data": { "job_id": "job-uuid-...", "name": "My White", "error": "Generation failed" } } ``` ## Error codes सभी त्रुटियाँ एक ही प्रारूप में लौटाई जाती हैं: HTTP स्टेटस + `error.code` फ़ील्ड + `error.message` में पठनीय संदेश। ```json { "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Not enough balance: required $5.00, available $1.20" } } ``` | Code | HTTP | When it fires | | --- | --- | --- | | `UNAUTHORIZED` | 401 | Key अनुपस्थित है, समाप्त हो गई है या रद्द कर दी गई है। | | `INSUFFICIENT_PERMISSIONS` | 403 | Key के पास इस कार्य के लिए आवश्यक scope नहीं है। | | `PERMISSION_DENIED` | 403 | अकाउंट-स्तरीय एक्सेस इस कार्य की अनुमति नहीं देता (उदा. फ़ीचर अक्षम है)। | | `VALIDATION_ERROR` | 400 | अनुरोध का body अमान्य है। संदेश बताता है कि कौन सा फ़ील्ड और क्यों। | | `NUMBER_NOT_FOUND` | 404 | नंबर मौजूद नहीं है या इस अकाउंट का नहीं है। | | `NUMBER_EXPIRED` | 403 | नंबर समाप्त हो गया है — Restore का उपयोग करें (7 दिनों के भीतर) या नया खरीदें। | | `NUMBER_NOT_ACTIVE` | 400 | नंबर ऐसी स्थिति में है जो इस ऑपरेशन की अनुमति नहीं देती। | | `INSUFFICIENT_BALANCE` | 402 | इस ऑपरेशन के लिए पर्याप्त धनराशि नहीं है। | | `INVALID_MESSAGE_FORMAT` | 400 | SMS का body बहुत लंबा है या उसमें अस्वीकृत वर्ण हैं। | | `COUNTRY_NOT_AVAILABLE` | 400 | यह देश खरीदारी या नवीनीकरण के लिए उपलब्ध नहीं है। | | `NO_NUMBERS_AVAILABLE` | 400 | चुने गए देश में अभी कोई मुफ़्त नंबर उपलब्ध नहीं है। | | `NO_RESTORABLE_NUMBERS` | 404 | दिए गए सभी नंबर अब पुनर्स्थापित नहीं किए जा सकते। | | `RATE_LIMITED` | 429 | Rate limit पार हो गई। `Retry-After` हेडर में दिए गए समय तक प्रतीक्षा करें। | | `INTERNAL_ERROR` | 500 | हमारी तरफ से कुछ गलत हो गया। अगर यह बार-बार हो — सपोर्ट से संपर्क करें। |