पुन: उपयोग योग्य दस्तावेज़ प्राप्त करें

नया Document कैप्चर फ़्लो शुरू करने से पहले यह जाँचने के लिए इस एंडपॉइंट का उपयोग करें कि उपयोगकर्ता के पास पहले से पुन: उपयोग के लिए कोई दस्तावेज़ उपलब्ध है या नहीं। यदि कोई दस्तावेज़ मिलता है, तो कैप्चर चरण को छोड़ने के लिए उसका documentId सीधे POST /processes/v1 (Document प्रकार) में पास किया जा सकता है।

एंडपॉइंट

वातावरण	URL
Production	GET https://api.id.unico.app/documents/v1
Sandbox	GET https://api.id.uat.unico.app/documents/v1

अनुरोध

हेडर

हेडर	मान
Authorization	Bearer <access_token> (देखें प्रमाणीकरण)
APIKEY	दस्तावेज़ कैप्चर और पुनरुपयोग सक्षम किया गया प्रावधानित API कुंजी।

क्वेरी पैरामीटर

पैरामीटर	प्रकार	आवश्यक	विवरण
code	string	हाँ	उपयोगकर्ता पहचानकर्ता (CPF या CURP, बिना फ़ॉर्मेटिंग के)।
type	string	हाँ	क्वेरी करने के लिए दस्तावेज़ प्रकार। स्वीकृत मान: BR_RG, BR_CNH, BR_CIN, BR_PASSPORT।

नोट

ऊपर दिए गए type मान केवल इस एंडपॉइंट के लिए विशिष्ट हैं। इन्हें निम्नलिखित से भ्रमित न करें:

• POST अनुरोधों में subject.duiType — DUI_TYPE_* उपसर्ग का उपयोग करता है और व्यक्ति की पहचान करता है, दस्तावेज़ प्रकार की नहीं (उदा., DUI_TYPE_BR_CPF)।
• प्रतिक्रिया में documentType — पूर्ण रजिस्ट्री पथ का उपयोग करता है (उदा., unico.moja.dictionary.br.cnh.v2.Cnh)।

उदाहरण

cURL

curl -X GET "https://api.id.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const params = new URLSearchParams({ code: '12345678909', type: 'BR_CNH' });
const res = await fetch(
  `https://api.id.unico.app/documents/v1?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const data = await res.json();
// data.items[0].documentId → pass to POST /processes/v1 for reuse

प्रतिक्रियाएँ

200 OK

{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}

फ़ील्ड	प्रकार	विवरण
items	array	उपयोगकर्ता के लिए मिले पुन: उपयोग योग्य दस्तावेज़ों की सूची। यदि दिए गए code और type के लिए कोई पुन: उपयोग योग्य दस्तावेज़ नहीं मिला तो खाली array।
items[].documentType	string	दस्तावेज़ प्रकार पहचानकर्ता। संभावित मान: unico.moja.dictionary.br.rg.v2.Rg, unico.moja.dictionary.br.cnh.v2.Cnh, unico.moja.dictionary.br.cin.v1.Cin, unico.moja.dictionary.br.passaporte.v1.Passaporte।
items[].documentId	string	दस्तावेज़ पहचानकर्ता। दस्तावेज़ का पुन: उपयोग करने के लिए POST /processes/v1 में document.documentId में यह मान पास करें।

403 Forbidden

Bearer टोकन या APIKEY अनुपस्थित, समय-सीमा समाप्त, या अमान्य है।

429 Too Many Requests

Rate limit reached. When your system receives an HTTP 429 error, you must implement mechanisms to prevent cascading failures and avoid worsening the restriction.

Best practices:

• Cool-down period (backoff): Immediately halt or throttle subsequent requests from your system. Do not continuously retry failed requests in a tight loop.
• Queueing & throttling: Buffer or queue outgoing requests on your end to control the traffic flow before re-sending them.
• Exponential backoff with jitter: When retrying, increase the waiting time exponentially between attempts (e.g., 1 s, 2 s, 4 s, 8 s) and add a small random delay ("jitter") to prevent a herd effect where all queued requests retry at the exact same millisecond.

चेतावनी

Continuously hitting a rate-limited endpoint without backing off can prolong the restriction period and severely impact your system's operational throughput. Properly throttling requests on your side ensures a smoother, more resilient integration.

For default limits, increase requests and additional details, see Rate Limits.

पुन: उपयोग के लिए documentId का उपयोग

documentId प्राप्त करने के बाद, कैप्चर को छोड़ने के लिए इसे Document प्रोसेस अनुरोध में पास करें:

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker"
  },
  "document": {
    "purpose": "onboarding",
    "authProcessId": "<biometric-process-id>",
    "documentId": "doc-abc-123"
  }
}

फ़ील्ड	विवरण
document.purpose	इस दस्तावेज़ प्रोसेस का व्यावसायिक उद्देश्य। स्वीकृत मान: creditprocess, carpurchase, paybypaycheck, onboarding, fgts। ये मान Document API के लिए विशिष्ट हैं और बायोमेट्रिक SDK के purpose enum से भिन्न हैं।
document.authProcessId	इस उपयोगकर्ता के लिए पहले बनाए गए बायोमेट्रिक प्रोसेस का ID (POST /processes/v1 से)।
document.documentId	इस एंडपॉइंट की प्रतिक्रिया से प्राप्त दस्तावेज़ ID। यह प्रदान किए जाने पर, document.files को छोड़ा जा सकता है — प्लेटफ़ॉर्म स्वचालित रूप से पहले कैप्चर किए गए दस्तावेज़ को पुनः प्राप्त करता है।

पूर्ण Document प्रोसेस अनुरोध स्कीमा के लिए, देखें Document प्रोसेस बनाएँ।

त्रुटि कोड

400 Bad Request

कोड	संदेश	विवरण
20507	O parâmetro subject.code é inválido.	गलत प्रारूप या गैर-मौजूद पहचानकर्ता मान (CPF या CURP)।
20002	O parâmetro APIKey não foi informado.	APIKEY हेडर अनुपस्थित।
20001	O parâmetro authtoken não foi informado.	प्रमाणीकरण टोकन हेडर अनुपस्थित।

403 Forbidden

कोड	संदेश	विवरण
30020	The provided authorization token does not have permission to perform this action.	टोकन के पास दस्तावेज़ सेल्फ़ी तक पहुँचने की अनुमति नहीं है।
30017	User does not have permission to perform this action.	गलत प्रारूप JWT या उपयोगकर्ता के पास यह ऑपरेशन करने की अनुमति नहीं है।
10502	O token informado está expirado.	समय-सीमा समाप्त एक्सेस टोकन।
10501	O token informado é inválido.	अमान्य प्रमाणीकरण टोकन।
10201	O AppKey informado é inválido.	अनुपस्थित या गैर-मौजूद APIKEY।

404 Not Found

कोड	संदेश	विवरण
99987	Attachment not found.	दस्तावेज़ से संबंधित अनुलग्नक नहीं मिला।
50001	The process is not found.	प्रदान किए गए पैरामीटर के लिए कोई दस्तावेज़ नहीं मिला।

500 Internal Server Error

कोड	संदेश	विवरण
99999	Internal failure! Try again later.	सर्वर-साइड प्रोसेसिंग त्रुटि।