# RHypernova All-in-One OCR API Integration

This document is for fintech organizations that want to use RHypernova OCR inside their own application with one token and one API contract.

## Product Contract

- UI embed SDK: `GET https://api.rhypernova.com/api/v1/ocr/embed.js`
- Main OCR API: `POST https://api.rhypernova.com/api/v1/ocr/run`
- Usage API: `GET https://api.rhypernova.com/api/v1/ocr/usage`
- Token header: `Authorization: Bearer ORG_TOKEN`
- Optional token header: `X-RHypernova-OCR-Token: ORG_TOKEN`
- UI mount div: `<div id="allinoneocr"></div>`
- Optional field mapping: `data-fields="account_number: Account Number,customer_name: Customer Name"`
- Optional client target API label: `data-target-api="https://client.example.com/api/forms/loan-application"`
- Optional new-tab fallback label: `data-open-label="Open OCR in new tab"`
- Optional fallback disable flag: `data-open-link="false"`

Every OCR tool is selected by `feature_key`, for example `image-to-text`, `pdf-to-text`, `scanned-pdf`, `searchable-pdf`, `batch-ocr`, or `bulk-processing`.

## Billing Model

1. Client buys an OCR API plan from the RHypernova API dashboard.
2. RHypernova issues an organization token after payment.
3. Client uses the token in the embedded UI or direct API calls.
4. Backend tracks usage by hashed token ID.
5. Successful OCR actions are counted as billable units.
6. Billing can be calculated from `GET /api/v1/ocr/usage`.

## HTML / JavaScript Embed

```html
<div id="allinoneocr"></div>
<script
  src="https://api.rhypernova.com/api/v1/ocr/embed.js"
  data-token="ORG_TOKEN"
  data-api-base="https://api.rhypernova.com/api/v1/ocr"
  data-frontend-url="https://app.rhypernova.com"
  data-fields="account_number: Account Number,customer_name: Customer Name,amount: Amount"
  data-target-api="https://client.example.com/api/forms/loan-application"
  data-open-label="Open OCR in new tab"
  data-feature="image-to-text">
</script>
```

The OCR UI stays inside the same container where the client places `#allinoneocr`. The SDK creates an absolute iframe URL using browser APIs and adds a direct new-tab fallback link by default. It does not require the client to build OCR screens, Angular services, React services, or custom upload workflows.

## Embed Script Attributes

Use these attributes to tell the SDK where to mount the OCR UI, which OCR workflow to open, and how to label the client integration:

- `src`: Loads the RHypernova embed SDK from the OCR API service.
- `data-token`: Organization token issued after payment. The SDK passes this token to OCR API calls for authentication and usage billing.
- `data-api-base`: Base URL of the OCR API, for example `https://api.rhypernova.com/api/v1/ocr`.
- `data-frontend-url`: Base URL of the RHypernova frontend that hosts the embedded OCR screen.
- `data-fields`: Optional field mapping requested by the client, for example account number, customer name, IFSC, or amount. The embedded UI uses this to show mapped OCR values and JSON for form/API fill.
- `data-target-api`: Optional label for the client's own API or form endpoint, for example `https://client-bank.example.com/api/forms/loan-application`. RHypernova does not automatically post to this URL from the browser; it is shown as integration context so the client knows where the mapped JSON is expected to go in their workflow.
- `data-feature`: Selects the OCR workflow to open first. Example: `image-to-text` opens the image OCR screen. Other values can include `pdf-to-text`, `scanned-pdf`, `searchable-pdf`, `batch-ocr`, or `bulk-processing`.
- `data-open-label`: Optional text for the fallback link under the iframe. Example: `Open OCR in new tab`.
- `data-open-link`: Optional flag to hide the fallback link. Set `data-open-link="false"` only if the client does not want the new-tab option.

## Auto-Fill Client Forms

Clients can define the fields they want from a scanned form, KYC document, invoice, or bank statement:

```html
<script
  src="https://api.rhypernova.com/api/v1/ocr/embed.js"
  data-token="ORG_TOKEN"
  data-fields="account_number: Account Number,ifsc_code: IFSC Code,customer_name: Customer Name"
  data-target-api="https://client-bank.example.com/api/customer-onboarding">
</script>
```

After OCR, the embedded UI shows mapped fields as key/value rows and JSON. The client can copy or post that JSON into their own database/API workflow.

## React Embed

```tsx
useEffect(() => {
  const s = document.createElement('script');
  s.src = 'https://api.rhypernova.com/api/v1/ocr/embed.js';
  s.dataset.token = 'ORG_TOKEN';
  s.dataset.apiBase = 'https://api.rhypernova.com/api/v1/ocr';
  s.dataset.frontendUrl = 'https://app.rhypernova.com';
  document.body.appendChild(s);
}, []);
return <div id="allinoneocr" />;
```

## Angular Embed

```ts
ngAfterViewInit() {
  const s = document.createElement('script');
  s.src = 'https://api.rhypernova.com/api/v1/ocr/embed.js';
  s.dataset['token'] = 'ORG_TOKEN';
  s.dataset['apiBase'] = 'https://api.rhypernova.com/api/v1/ocr';
  s.dataset['frontendUrl'] = 'https://app.rhypernova.com';
  document.body.appendChild(s);
}
```

```html
<div id="allinoneocr"></div>
```

## Vue Embed

```vue
<template><div id="allinoneocr"></div></template>
<script setup>
import { onMounted } from 'vue';
onMounted(() => {
  const s = document.createElement('script');
  s.src = 'https://api.rhypernova.com/api/v1/ocr/embed.js';
  s.dataset.token = 'ORG_TOKEN';
  s.dataset.apiBase = 'https://api.rhypernova.com/api/v1/ocr';
  document.body.appendChild(s);
});
</script>
```

## Angular Direct Iframe Note

Use the SDK snippet above for Angular apps whenever possible. If a client chooses to bind the OCR frame URL directly to an Angular `<iframe [src]>`, Angular requires a trusted resource URL:

```ts
constructor(private sanitizer: DomSanitizer) {}

safeFrameUrl = this.sanitizer.bypassSecurityTrustResourceUrl(
  'https://app.rhypernova.com/ocr/embed/image-to-text?apiBase=https%3A%2F%2Fapi.rhypernova.com%2Fapi%2Fv1%2Focr&token=ORG_TOKEN'
);
```

```html
<iframe [src]="safeFrameUrl" title="RHypernova OCR"></iframe>
```

Without this sanitizer step, Angular may show a blank iframe even though opening the same URL in a new browser tab works.

## Direct API: Python

```python
import requests

files = {"file": open("statement.pdf", "rb")}
data = {"feature_key": "pdf-to-text", "language": "eng", "page_selection": "all"}
headers = {"Authorization": "Bearer ORG_TOKEN"}
res = requests.post("https://api.rhypernova.com/api/v1/ocr/run", files=files, data=data, headers=headers)
print(res.json())
```

## Direct API: JavaScript

```js
const form = new FormData();
form.append('feature_key', 'image-to-text');
form.append('file', fileInput.files[0]);
const res = await fetch('https://api.rhypernova.com/api/v1/ocr/run', {
  method: 'POST',
  headers: { Authorization: 'Bearer ORG_TOKEN' },
  body: form
});
console.log(await res.json());
```

## Direct API: Java

```java
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.rhypernova.com/api/v1/ocr/usage"))
  .header("Authorization", "Bearer ORG_TOKEN")
  .GET()
  .build();
HttpResponse<String> res = HttpClient.newHttpClient().send(request, BodyHandlers.ofString());
System.out.println(res.body());
```

## Direct API: .NET

```csharp
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "ORG_TOKEN");
using var form = new MultipartFormDataContent();
form.Add(new StringContent("image-to-text"), "feature_key");
form.Add(new StreamContent(File.OpenRead("kyc.png")), "file", "kyc.png");
var res = await client.PostAsync("https://api.rhypernova.com/api/v1/ocr/run", form);
Console.WriteLine(await res.Content.ReadAsStringAsync());
```

## Usage Check

```bash
curl -H "Authorization: Bearer ORG_TOKEN" \
  https://api.rhypernova.com/api/v1/ocr/usage
```

## Recommended Client Flow

- Use embedded UI when the fintech client wants a ready OCR screen inside their product.
- Use `POST /run` directly when the client wants server-to-server OCR automation.
- Use `GET /usage` for billing, usage analytics, and invoice reconciliation.
- Rotate tokens per organization and per environment (`sandbox`, `production`).