# Sharing Documents > Show a stored document on your website: request its encrypted name with document/share and embed the viewer widget of ReportingCloud, from curl or ASP.NET Core. - **Product:** ReportingCloud - **Section:** Documentation - **Kind:** Topic - **Path:** ReportingCloud > Document Processing > Sharing Documents - **2255 words** - **Web URL:** https://docs.textcontrol.com/reporting-cloud/document-processing/sharing/ - **LLMs URL:** https://docs.textcontrol.com/reporting-cloud/document-processing/sharing/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/reporting-cloud/document-processing/sharing/llms-full.txt --- An invoice that a customer should see right after a purchase doesn't have to travel as an email attachment or a download: your website can show it in a document viewer. `GET /v1/document/share` returns an encrypted name for a document in your template storage, and the viewer widget of ReportingCloud displays the document under that name in any web page. Text Control introduced the endpoint and the widget in October 2017 as a beta feature, in the blog article [Sharing Documents with ReportingCloud](https://www.textcontrol.com/blog/2017/10/05/sharing-documents-with-reportingcloud/), and the feature left its beta in January 2018. ### How Sharing Works Sharing takes three steps: 1. The document is stored in the template storage of your account, like a template. 2. [GET /v1/document/share](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/share/get/llms-full.txt) returns the encrypted document name of the stored document. The name encodes where the document is stored. 3. A web page loads the viewer script from the portal and passes it the encrypted name. The viewer shows the document in a frame served by `portal.reporting.cloud`. The request takes one parameter: | Part of the request | Content | |---|---| | `templateName` | The name of the document in the template storage | | Response | `200`, the encrypted document name as a string | | Errors | `400` when the storage has no document of this name, `403` when the request is not authorized | The document is delivered by ReportingCloud from your storage; your web server only passes on the name. Every request carries an `Authorization` header, as [Authentication](https://docs.textcontrol.com/reporting-cloud/document-processing/authentication/llms-full.txt) describes. The reference marks `document/share` with no quota of its own, but the documents you keep in the storage for sharing count against the template storage quota of your plan together with your templates. [Plans and Licensing](https://docs.textcontrol.com/reporting-cloud/overview/licensing/llms-full.txt) lists the number each plan stores. ### Store a Created Document for Sharing `GET /v1/document/share` works with the names of the template storage only, so a document that a merge creates has to be stored before it can be shared. Merge with a return format that `POST /v1/templates/upload` accepts, DOC, DOCX, RTF or TX, and upload the result under a name of its own. The following commands assume that *merged.json* holds the response of a [POST /v1/document/merge](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/merge/post/llms-full.txt) request with `returnFormat=DOCX`, as the [Overview](https://docs.textcontrol.com/reporting-cloud/mail-merge/overview/llms-full.txt) of the Mail Merge section creates it: ```bash API=https://api.reporting.cloud/v1 AUTH="Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" # The first document of the merge response, still a Base64 string in a JSON string jq '.[0]' merged.json > document.json curl -X POST "$API/templates/upload?templateName=invoice-10001.docx" \ -H "$AUTH" \ -H "Content-Type: application/json" \ --data-binary @document.json ``` The commands work as follows: - The merge response is an array of Base64 strings, one per created document. `jq '.[0]'` takes the first one and keeps its quotes, which is the body that `templates/upload` expects. - The upload stores the document as *invoice-10001.docx*. Give every shared document a name of its own, because an upload replaces a stored file of the same name. A shared document stays in the storage until you delete it with `DELETE /v1/templates/delete`, as [Managing Templates](https://docs.textcontrol.com/reporting-cloud/document-processing/templates/#delete-a-template) shows. Delete the documents that no longer have to be shown, so that they don't fill the storage of your plan. ### Request the Encrypted Name The following command requests the encrypted name of the stored document: ```bash curl -H "$AUTH" "$API/document/share?templateName=invoice-10001.docx" ``` The response is the encrypted name in a JSON string, such as: ```json "jHjsdfhsdfjhaJhJHSF-HFhjusefhJH787fha-ahjasdhuzhKLJHLLKUjhdfadf8988" ``` `jq -r .` removes the quotes when a script processes the name further. The trial demo template works the same way: `templateName=sample_invoice.tx` shares *sample\_invoice.tx*. ### Show the Document in a Web Page The viewer is embedded with an element that holds the encrypted name in its `data-document` attribute and the script *reportingcloud.js* from the portal: ```html
``` The script, ReportingCloud Viewer 1.0, works as follows: - It looks for the element with the id `reportingcloud-documentviewer` and reads its `data-document` attribute. The id is fixed, so a page shows one shared document. - It adds a frame to the element that loads the viewer from `https://portal.reporting.cloud/viewer` with the encrypted name and allows full-screen mode. - The frame takes the full width and height of the element. Give the element a height, as the `style` attribute above does. - It runs once, when it has loaded. Place the `script` element after the viewer element, so that the element exists when the script looks for it. When the name is missing or not valid, the frame shows the message "Oops. We can't find what you're looking for." instead of the document. ### Share a Document With .NET The method `ShareDocument` of the NuGet package `TXTextControl.ReportingCloud` requests the encrypted name. Call it on your server, so that the API key never reaches the browser: the page only receives the name. The following ASP.NET Core MVC controller requests the name of *sample\_invoice.tx* and passes it to its view: ```csharp using Microsoft.AspNetCore.Mvc; using TXTextControl.ReportingCloud; public class InvoiceController : Controller { public IActionResult Show() { var rc = new ReportingCloud(Environment.GetEnvironmentVariable("REPORTINGCLOUD_API_KEY")); // The encrypted name of the stored document ViewData["DocumentName"] = rc.ShareDocument("sample_invoice.tx"); return View(); } } ``` The view *Views/Invoice/Show.cshtml* writes the name into the viewer element: ```cshtml
``` The code works as follows: - The `ReportingCloud` constructor takes the API key from the environment variable `REPORTINGCLOUD_API_KEY`. - `ShareDocument` calls `GET /v1/document/share` with the name of the stored document and returns the encrypted name as a string. A refused request throws an `ArgumentException` with the answer of the Web API as its message. The PHP SDK 4.0, the Java SDK and the Ruby SDK have no method for `document/share`. From these languages, send the `GET` request of the curl sample with the HTTP client of your application. ### Next Steps - [Managing Templates](https://docs.textcontrol.com/reporting-cloud/document-processing/templates/llms-full.txt): upload, list and delete the documents and templates of the storage. - [Overview](https://docs.textcontrol.com/reporting-cloud/mail-merge/overview/llms-full.txt): create the document that you share with a merge. - [Authentication](https://docs.textcontrol.com/reporting-cloud/document-processing/authentication/llms-full.txt): keep the API key on the server. - [Errors and Status Codes](https://docs.textcontrol.com/reporting-cloud/document-processing/errors/llms-full.txt): what a refused request means. --- ## Nearby - **Previous:** [Managing Templates](https://docs.textcontrol.com/reporting-cloud/document-processing/templates/llms-full.txt) - **Next:** [Spell Checking](https://docs.textcontrol.com/reporting-cloud/document-processing/spell-checking/llms-full.txt)