Dokümanlar / Uç Noktalar

Doküman İndir

GET /api/v1/documents/{id}/download

Bu sayfada

Doküman İndir
Filigran ve fingerprint
Önbellekleme —
Dosya tipleri
HTML karakter kodlaması
İndirme yapısı
Yaygın hatalar

Doküman İndir

Dokümanın orijinal dosyasını müşteriye özel filigranla işaretleyip akış olarak döner. Filigran her istekte yeniden hesaplanır; dosya adı {güvenli başlık}.{uzantı} formatında Content-Disposition: attachment başlığı ile birlikte gelir.

Filigran ve fingerprint

Aynı doküman ID'si, müşteri başına farklı bir kopya olarak servis edilir. PDF'lerde içeriğe gömülü, HTML'lerde metaya yerleşik bir HMAC stamp'i bulunur. Yanıt başlığında bu stamp'in kimliği ekoyla döner:

X-Regvion-Document-Fingerprint: <opaque-hmac>

Müşteri destek talebinde "hangi kopyayı aldım?" sorusunu yanıtlamak için bu fingerprint'i quote edebilir. Fingerprint dosyaya zaten gömüldüğü için bu header ek bir şey sızdırmaz.

Resim (DocumentFormat.Image, PNG), Word (DocumentFormat.Word), zip paketi (DocumentFormat.Archive) ve tablo (DocumentFormat.Spreadsheet) biçimindeki belgelere filigran gömülmez — dosya değiştirilmeden servis edilir. İndirme kaydı yine tutulur ve X-Regvion-Document-Fingerprint başlığı yine döner; bu başlığın varlığı dosyanın filigranlandığı anlamına gelmez.

Önbellekleme — `private`

Yanıt Cache-Control: private, max-age=86400 döner. Filigran müşteriye özel olduğu için paylaşımlı CDN/proxy bu içeriği önbelleklememelidir. Tarayıcı kendi önbelleğinde 24 saat saklayabilir; müşteri A'nın aldığı bytes hiçbir zaman müşteri B'ye servis edilmemelidir.

Eğer kendi proxy/cache katmanınız varsa, Cache-Control: private header'ına saygı gösterdiğinden emin olun ya da bu uç noktayı tamamen bypass edin.

Dosya tipleri

DocumentFormat.Pdf → application/pdf, .pdf
DocumentFormat.Html → text/html; charset=…, .html — charset, dosyanın kendi bildirimini (BOM, <meta charset>, http-equiv=Content-Type pragması ya da XML bildirimi) yineler; dosya hiçbir şey bildirmiyorsa ya da bildirdiği etiket tarayıcının başlıktan farklı yorumlayacağı bir etiketse (unicode, utf-16, x-user-defined gibi) başlıkta charset bulunmaz
DocumentFormat.Image → image/png, .png
DocumentFormat.Word → dosyanın kendisine göre .doc (application/msword), .docx (application/vnd.openxmlformats-officedocument.wordprocessingml.document) ya da .rtf (application/rtf)
DocumentFormat.Archive → application/zip, .zip — paketin tamamı; içindeki tek bir dosya için Paket Dosyası İndir
DocumentFormat.Spreadsheet → dosyanın kendisine göre .xls (application/vnd.ms-excel) ya da .xlsx (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)
Diğer → application/octet-stream, .bin

Uzantı ve Content-Type dosyanın baytlarından doğrulanır: documentFormat alanı henüz 1 = Pdf gösteren eski bir kayıtta dosya aslında Word belgesi ya da zip paketiyse indirme yine doğru uzantı ve türle gelir.

HTML karakter kodlaması

HTML belgeler, indirilen dosya tek başına (tarayıcıda çift tıklayarak) açıldığında da doğru okunsun diye kendi kodlamasını bildiren biçimde servis edilir: kodlama bildirmeyen ve geçerli UTF-8 olan dosyalara <meta charset="utf-8" /> eklenir; bayt içeriği UTF-8 olduğu halde eski bir kod sayfası (ör. Windows-1254) bildiren dosyalarda bildirim utf-8 olarak düzeltilir. Bunun dışında dosya bayt bayt orijinaliyle aynıdır (filigran işaretleri hariç). Content-Type başlığında charset bulunduğunda her zaman dosyanın bildirimiyle aynıdır; başlık hiçbir zaman dosyayla çelişmez.

İndirme yapısı

API container'ı stateless tutmak için filigranlı dosyalar diskte saklanmaz — her istekte yeniden üretilir. PDF için tipik ek yük 100-500 ms, HTML için < 10 ms'dir. Bu uç nokta yüksek hacimli paralel indirmeler için tasarlanmamıştır; toplu indirme senaryolarında talep arasında 100-200 ms bekleme yeterlidir.

Yaygın hatalar

Doküman tamamlanmış olsa bile rawContentPath boşsa (scraping aşamasında dosya kaybolduysa) 404 döner. Kriz sonrası telafi için [email protected] adresine başvurun.
Bu çağrı oran sınırı için ayrı bir kategori altında sayılır (Api.Documents.Download tier izni). /account/usage byEndpoint kırılımında ayrı satır olarak görünür.

Parametreler

İsim	Konum	Tip	Zorunlu	Açıklama
`id`	Path	`uuid`	Evet	Doküman ID'si.

Yanıtlar

200 — Dosya akışı (Content-Type formata göre değişir; HTML için `charset` dosyanın kendi bildirimini yineler). Yanıt başlığında `X-Regvion-Document-Fingerprint` ile filigran kimliği döner.

404 — Doküman veya dosya bulunamadı.

⚠️ Sunucudan sunucuya — API anahtarınızı tarayıcıda paylaşmayın. Neden?

curl -X GET \
  "https://api.regvion.com/api/v1/documents/7a3f9e2c-4b8d-11ef-8a3c-0242ac120002/download" \
  -H "X-API-Key: rgv_live_REPLACE_WITH_YOUR_KEY"

const url = 'https://api.regvion.com/api/v1/documents/7a3f9e2c-4b8d-11ef-8a3c-0242ac120002/download';
const headers = {
  'X-API-Key': 'rgv_live_REPLACE_WITH_YOUR_KEY'
};

const response = await fetch(url, {
  method: 'GET',
  headers,
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const body = await response.json();
console.log(body.data);
console.log('Request ID:', body.meta.requestId);

import requests

url = "https://api.regvion.com/api/v1/documents/7a3f9e2c-4b8d-11ef-8a3c-0242ac120002/download"
headers = {"X-API-Key": "rgv_live_REPLACE_WITH_YOUR_KEY"}
response = requests.get(url, headers=headers)
response.raise_for_status()
body = response.json()
print(body["data"])
print("Request ID:", body["meta"]["requestId"])

using System.Net.Http;
using System.Net.Http.Json;
using System.Text;
using System.Text.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "rgv_live_REPLACE_WITH_YOUR_KEY");

var response = await client.GetAsync("https://api.regvion.com/api/v1/documents/7a3f9e2c-4b8d-11ef-8a3c-0242ac120002/download");
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(body.GetProperty("meta").GetProperty("requestId").GetString());

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$options = [
    'headers' => [
        'X-API-Key' => 'rgv_live_REPLACE_WITH_YOUR_KEY',
    ],
];

$response = $client->request('GET', 'https://api.regvion.com/api/v1/documents/7a3f9e2c-4b8d-11ef-8a3c-0242ac120002/download', $options);
$body = json_decode($response->getBody(), true);
echo 'Request ID: ' . $body['meta']['requestId'];

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();

HttpRequest.Builder b = HttpRequest.newBuilder()
    .uri(URI.create("https://api.regvion.com/api/v1/documents/7a3f9e2c-4b8d-11ef-8a3c-0242ac120002/download"))
    .header("X-API-Key", "rgv_live_REPLACE_WITH_YOUR_KEY")
    .GET();

HttpResponse<String> response = client.send(b.build(), HttpResponse.BodyHandlers.ofString());
System.out.println("Status: " + response.statusCode());
System.out.println(response.body());

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.regvion.com/api/v1/documents/7a3f9e2c-4b8d-11ef-8a3c-0242ac120002/download", nil)
    req.Header.Set("X-API-Key", "rgv_live_REPLACE_WITH_YOUR_KEY")

    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    var envelope struct {
        Data interface{} `json:"data"`
        Meta struct { RequestId string `json:"requestId"` } `json:"meta"`
    }
    json.NewDecoder(resp.Body).Decode(&envelope)
    fmt.Println("Request ID:", envelope.Meta.RequestId)
}

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://api.regvion.com/api/v1/documents/7a3f9e2c-4b8d-11ef-8a3c-0242ac120002/download')
request = Net::HTTP::Get.new(uri)
request['X-API-Key'] = 'rgv_live_REPLACE_WITH_YOUR_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(request)
end

body = JSON.parse(response.body)
puts "Request ID: #{body['meta']['requestId']}"

import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()

val builder = Request.Builder()
    .url("https://api.regvion.com/api/v1/documents/7a3f9e2c-4b8d-11ef-8a3c-0242ac120002/download")
    .addHeader("X-API-Key", "rgv_live_REPLACE_WITH_YOUR_KEY")

client.newCall(builder.build()).execute().use { response ->
    println("Status: ${'$'}{response.code}")
    println(response.body?.string())
}

import Foundation

var request = URLRequest(url: URL(string: "https://api.regvion.com/api/v1/documents/7a3f9e2c-4b8d-11ef-8a3c-0242ac120002/download")!)
request.httpMethod = "GET"
request.setValue("rgv_live_REPLACE_WITH_YOUR_KEY", forHTTPHeaderField: "X-API-Key")

let (data, response) = try await URLSession.shared.data(for: request)
if let http = response as? HTTPURLResponse { print("Status: \(http.statusCode)") }
print(String(data: data, encoding: .utf8) ?? "")

use reqwest::blocking::Client;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let mut req = client.get("https://api.regvion.com/api/v1/documents/7a3f9e2c-4b8d-11ef-8a3c-0242ac120002/download")
        .header("X-API-Key", "rgv_live_REPLACE_WITH_YOUR_KEY")
        ;
    let res = req.send()?;
    println!("Status: {}", res.status());
    println!("{}", res.text()?);
    Ok(())
}

$headers = @{
    'X-API-Key' = 'rgv_live_REPLACE_WITH_YOUR_KEY'
}

$response = Invoke-RestMethod -Uri 'https://api.regvion.com/api/v1/documents/7a3f9e2c-4b8d-11ef-8a3c-0242ac120002/download' -Method Get -Headers $headers

$response.data
Write-Host "Request ID:" $response.meta.requestId

Doküman İndir

Filigran ve fingerprint

Önbellekleme — private

Dosya tipleri

HTML karakter kodlaması

İndirme yapısı

Yaygın hatalar

Parametreler

Yanıtlar

200 — Dosya akışı (Content-Type formata göre değişir; HTML için `charset` dosyanın kendi bildirimini yineler). Yanıt başlığında `X-Regvion-Document-Fingerprint` ile filigran kimliği döner.

404 — Doküman veya dosya bulunamadı.

Önbellekleme — `private`