API

फ़ॉर्म फ़ॉरवर्डिंग (webhook)

हर पूरा हुआ फ़ॉर्म अपनी API पर पाएँ

परिचय

जब कोई व्यक्ति बातचीत में फ़ॉर्म पूरा करता है, तो TBit जवाबों के साथ आपकी API call कर सकता है। इसके दो मोड हैं। जाँचें और फ़ॉरवर्ड करें (जब फ़ॉर्म में डॉक्यूमेंट माँगे जाते हैं तब यही सुझाया जाता है): TBit अटैच किए गए डॉक्यूमेंट्स को vision से पढ़ता है, उन्हें व्यक्ति की बताई जानकारी से मिलाता है, उसे नतीजा बताता है और, सिर्फ़ तभी जब सब मेल खाए, प्रोफ़ाइल को retries के साथ आपके URL पर POST करता है। सीधी call: फ़ॉर्म पूरा होते ही TBit उसके values आपके URL पर POST करता है, बिना जाँच और बिना retries के।

इसे कैसे सेट करें

इन तीनों में से कोई भी रास्ता फ़ॉर्म पर एक ही सेटिंग लिखता है (उसका closing action):

Canvas (newui.tbit.app): फ़ॉर्म → फ़ॉर्म की पंक्ति खोलें → “पूरा होने पर फ़ॉरवर्ड करें…”। पहले से भरा एक फ़ॉर्म मोड, destination URL, एक वैकल्पिक token और payload प्रोफ़ाइल पूछता है।
MCP (Claude, ChatGPT…): manage_form, action=set_forward के साथ, list_forms से मिला form_id, mode, url, token और profile। बदलाव का प्रस्ताव आता है और आप उसे कन्फ़र्म करते हैं।
प्लेटफ़ॉर्म ऐप: फ़ॉर्म → एडिट → closing action → API। यह low-level व्यू है: डॉक्यूमेंट validator का URL, TBit के secret वाला bearer और X-Tbit-Forward-* headers।

उदाहरण: MCP से सेट करें

json

manage_form
{
  "action": "set_forward",
  "form_id": "6917da72ed0bc91ea5532858",
  "mode": "validate_forward",
  "url": "https://api.tunegocio.com/tbit/perfiles",
  "token": "<tu bearer>",
  "profile": "generic"
}

मोड 1 · डॉक्यूमेंट जाँचें और फ़ॉरवर्ड करें

फ़्लो

1. व्यक्ति फ़ॉर्म पूरा करता है (डॉक्यूमेंट्स के लिए फ़ाइल फ़ील्ड्स के साथ)। 2. TBit हर डॉक्यूमेंट पढ़ता है, नाम और नंबर निकालता है और उन्हें बताई गई जानकारी से मिलाता है। 3. व्यक्ति को एक मैसेज मिलता है: सब मेल खाता है, कोई अंतर है (और क्या दोबारा भेजना है) या फ़ाइल पढ़ी नहीं जा सकी। 4. अगर नतीजा MATCH है, तो TBit आपके URL पर POST करता है।

हम कौन-से headers भेजते हैं

`Content-Type`	application/json
`Authorization`	Bearer <token que configuraste> (solo si hay token)
`X-Bot-Provider`	tbit
`X-Event-Type`	profile.completed
`X-Tbit-Form-Data-Id`	<id de la respuesta, para deduplicar>

Payload (generic प्रोफ़ाइल)

fields में फ़ॉर्म के हर जवाब दिए गए फ़ील्ड को उसके नाम से भेजा जाता है; document_validation में हर डॉक्यूमेंट का नतीजा आता है। अगर TBit ने आपकी कंपनी के लिए अलग प्रोफ़ाइल बनाई है, तो body उसी data contract को फ़ॉलो करता है और प्रोफ़ाइल का नाम वही है जो आपको दिया गया था।

Retries और idempotency

जितनी जल्दी हो सके 2xx से जवाब दें (10 s का timeout)। 500, 502, 503, 504 या नेटवर्क एरर पर TBit 30 s, 2 min, 10 min और 1 h बाद फिर से कोशिश करता है। बाकी कोड पर retry नहीं होता। Retries मेमोरी में रहते हैं: अगर बीच में इंजन रीस्टार्ट हो जाए तो वे खो जाते हैं, इसलिए अपना endpoint at-least-once मानकर बनाएँ और formDataId से duplicate हटाएँ (यह X-Tbit-Form-Data-Id header में भी आता है)।

json

{
  "formDataId": "6aabbe45706082120e74fc75",
  "agentId": "6aaab0521c2b87a579ccc624",
  "activityId": "6aabbe3c58181a93243f7298",
  "fields": {
    "Nombre completo": "Ana Pérez",
    "Cédula": "1032456789",
    "Gasto en alimentación": 900,
    "Foto del DNI": { "kind": "file", "url": "https://api.tbit.app/media/…/dni.jpeg" }
  },
  "document_validation": {
    "verdict": "MATCH",
    "results": [
      { "field": "Foto del DNI", "document_kind": "dni", "verdict": "MATCH",
        "checks": { "full_name": true, "document_number": true } }
    ]
  }
}

मोड 2 · सीधी call

फ़ॉर्म पूरा होते ही TBit एक JSON POST करता है जिसमें हर फ़ील्ड की एक key (फ़ॉर्म में उसका नाम) और साथ में formId, agentId और formDataId होते हैं। ऑथेंटिकेशन वही होता है जो आपने सेट किया: Bearer (Authorization: Bearer …), Basic (Authorization: Basic …) या API key (X-API-Key header), और आपके बताए अतिरिक्त headers। कोई retry नहीं होता: फ़ेल हुई call फ़ेल ही रहती है।

json

{
  "Nombre completo": "Ana Pérez",
  "Cédula": "1032456789",
  "Gasto en alimentación": 900,
  "formId": "6917da72ed0bc91ea5532858",
  "agentId": "6aaab0521c2b87a579ccc624",
  "formDataId": "6aabbe45706082120e74fc75"
}

Calls की जाँच

हर call उसकी request, response, HTTP कोड और कोशिशों के साथ दर्ज होती है। TBit की टीम इन्हें canvas के Developer पैनल में देखती है और आपके साथ इनकी समीक्षा कर सकती है; अपने logs के लिए, अपनी तरफ़ formDataId दर्ज करें।