Limite și versiuni

Ce acceptă API-ul, cât de repede, și ce vă garantăm când contractul se schimbă. Istoricul schimbărilor e în changelog.

Limite

Ce	Limita	Peste ea
Mărimea fișierului	14 MiB	`413 file_too_large`
Pagini într-un PDF	50	`413 too_many_pages`
Formate	PDF, JPEG, PNG, GIF, WebP	`415 unsupported_file_type`
Trimiteri pe cheie	120 / min	`429 rate_limited`, cu `Retry-After` în secunde
Rafală de trimiteri pe cheie	20	la fel
Documente citite în același timp, pe cont	2	celelalte așteaptă la rând, fără eroare
Așteptarea cu `mode=sync`	30 s	răspunsul e `202`; continuați cu `GET` sau webhook
Consumul lunar (chei live)	cel din contract	`402 quota_exceeded`, până la luna următoare sau până îl mărim
`external_id`	128 de caractere	`400 invalid_request`
`metadata`	20 de chei, 500 de caractere fiecare	`400 invalid_request`
`buyer_name`	200 de caractere	`400 invalid_request`
`limit` la `GET /v1/documents`	200 (implicit 50)	`400 invalid_request`
Păstrarea unui `Idempotency-Key`	24 h	aceeași cheie e apoi o cerere nouă

Cheile sandbox au aceeași limită de rată, dar nu consumă nimic și nu primesc niciodată 402.

Webhook-uri. Un răspuns trebuie să vină în 10 s; o redirecționare nu e urmată, ci socotită eșec. Un eveniment nelivrat e reîncercat după 1 min, 5 min, 30 min, 2 h, 6 h, 8 h, 8 h (puțin peste 24 h în total), apoi se oprește; îl cereți din nou cu POST /v1/documents/{id}/webhook. Semnătura are o toleranță de 5 minute față de ceasul dumneavoastră.

Versiuni

Versiunea contractului e o dată, în antetul Fintray-Version. Versiunea curentă e 2026-10-19.

O cheie rămâne pe versiunea curentă în momentul creării ei. O cerere poate numi altă versiune suportată în antetul Fintray-Version; una pe care n-o servim primește 400 unsupported_version.
Răspunsul spune mereu, în același antet, pe ce versiune a fost construit.
Prefixul /v1 din URL nu se schimbă odată cu versiunile.

Ce garantăm într-o versiune

Pe versiunea cheii dumneavoastră nu:

scoatem și nu redenumim un câmp din cerere, din răspuns sau din eveniment;
schimbăm tipul sau înțelesul unui câmp, al unui nivel de încredere ori al unui cod;
facem obligatoriu un câmp opțional al cererii;
schimbăm statusul HTTP sau error.code cu care răspundem într-o situație existentă.

Ce se poate adăuga fără o versiune nouă

Integrarea trebuie să treacă peste ce nu cunoaște:

endpoint-uri noi și câmpuri opționale noi în cerere;
câmpuri noi în răspuns și în eveniment;
coduri noi în warnings și coduri de eroare noi;
tipuri noi de eveniment webhook: răspundeți cu 2xx și ignorați-le.

Citirea însăși se îmbunătățește în timp: un model sau o regulă nouă poate citi mai corect același fișier, deci valorile pot diferi de la o trimitere la alta. Înțelesul lui high, medium și low rămâne același.

Când apare o versiune nouă

O anunțăm pe e-mail contactului tehnic al fiecărui cont, cu ce se schimbă și ce aveți de făcut, și o trecem în changelog.
Cheia dumneavoastră rămâne pe versiunea veche. O încercați trimițând Fintray-Version cu versiunea nouă, întâi cu cheia sandbox. Când sunteți gata, vă dăm o cheie nouă, care e pe versiunea nouă.
O versiune veche e servită cel puțin 12 luni după ce apare cea care o înlocuiește, iar data opririi o anunțăm cu cel puțin 90 de zile înainte.