{"openapi":"3.1.0","info":{"title":"Fintray Extract","description":"Invoice images and PDFs in, structured JSON out. The integration guide, limits, versioning and changelog are at https://api.fintray.ro/docs.","version":"0.1.0"},"servers":[{"url":"https://api.fintray.ro"}],"paths":{"/v1/whoami":{"get":{"tags":["keys"],"summary":"Whoami","description":"Which tenant and mode a key belongs to — the first call a vendor\nmakes to check their key works, and whether it is a sandbox one.","operationId":"whoami_v1_whoami_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"fintray-version","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fintray-Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Whoami V1 Whoami Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/documents":{"post":{"tags":["documents"],"summary":"Create Document","operationId":"create_document_v1_documents_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"fintray-version","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fintray-Version"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"200":{"description":"mode=sync and the read finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","buyer_vat"],"properties":{"file":{"type":"string","format":"binary"},"buyer_vat":{"type":"string","description":"Required. The VAT number of the company that received the invoice — your customer. A Romanian CUI (with or without RO) must pass its check digit; another EU number needs its country prefix.","example":"RO12345678"},"buyer_name":{"type":"string","maxLength":200},"external_id":{"type":"string","maxLength":128,"description":"Your reference; not unique."},"mode":{"type":"string","enum":["async","sync"],"default":"async"},"retention":{"type":"string","enum":["standard","zero"],"default":"standard"},"webhook_url":{"type":"string","format":"uri"},"metadata":{"type":"string","description":"A JSON object of up to 20 scalars."}}}},"application/json":{"schema":{"type":"object","required":["file_base64","buyer_vat"],"properties":{"file_base64":{"type":"string","format":"byte"},"filename":{"type":"string"},"buyer_vat":{"type":"string","description":"Required. The VAT number of the company that received the invoice — your customer. A Romanian CUI (with or without RO) must pass its check digit; another EU number needs its country prefix.","example":"RO12345678"},"buyer_name":{"type":"string","maxLength":200},"external_id":{"type":"string","maxLength":128,"description":"Your reference; not unique."},"mode":{"type":"string","enum":["async","sync"],"default":"async"},"retention":{"type":"string","enum":["standard","zero"],"default":"standard"},"webhook_url":{"type":"string","format":"uri"},"metadata":{"type":"object","maxProperties":20}}}}}}},"get":{"tags":["documents"],"summary":"List Documents","operationId":"list_documents_v1_documents_get","parameters":[{"name":"external_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"fintray-version","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fintray-Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/documents/{document_id}":{"get":{"tags":["documents"],"summary":"Get Document","operationId":"get_document_v1_documents__document_id__get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"fintray-version","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fintray-Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["documents"],"summary":"Delete Document","description":"Erase the document: file, extraction and everything describing it. The\nbilling row (status, pages, dates) stays (FAC-384).","operationId":"delete_document_v1_documents__document_id__delete","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"fintray-version","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fintray-Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/documents/{document_id}/webhook":{"post":{"tags":["documents"],"summary":"Redeliver Webhook","description":"Send the document's event again (FAC-382).","operationId":"redeliver_webhook_v1_documents__document_id__webhook_post","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"fintray-version","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fintray-Version"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage":{"get":{"tags":["documents","usage"],"summary":"Usage","description":"What the tenant is billed on this month (or `month=YYYY-MM`): live\ndocuments read and their pages. Sandbox documents are counted, never billed.","operationId":"usage_v1_usage_get","parameters":[{"name":"month","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}$"},{"type":"null"}],"title":"Month"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"fintray-version","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fintray-Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"webhooks":{"document.succeeded":{"post":{"tags":["webhooks"],"summary":"document.succeeded","description":"Sent to the document's `webhook_url`, else the account's, when a document has been read. GET\n`data.url` with your key for the extraction.","operationId":"document_succeeded","parameters":[{"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.\" + raw body)>`. Reject a mismatch, or a `t` more than 5 minutes away from now.","required":true,"schema":{"type":"string","title":"Fintray-Signature","description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.\" + raw body)>`. Reject a mismatch, or a `t` more than 5 minutes away from now."},"name":"Fintray-Signature","in":"header"},{"description":"The same on every retry of one event: deduplicate on it.","required":true,"schema":{"type":"string","title":"Fintray-Event-Id","description":"The same on every retry of one event: deduplicate on it."},"name":"Fintray-Event-Id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}},"required":true},"responses":{"200":{"description":"Received. Any 2xx counts as delivered."},"default":{"description":"Anything else, a 4xx included, is retried with growing delays for 24 hours."}}}},"document.failed":{"post":{"tags":["webhooks"],"summary":"document.failed","description":"Sent when a document could not be read; `data.error.code` says why (see the error codes).","operationId":"document_failed","parameters":[{"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.\" + raw body)>`. Reject a mismatch, or a `t` more than 5 minutes away from now.","required":true,"schema":{"type":"string","title":"Fintray-Signature","description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.\" + raw body)>`. Reject a mismatch, or a `t` more than 5 minutes away from now."},"name":"Fintray-Signature","in":"header"},{"description":"The same on every retry of one event: deduplicate on it.","required":true,"schema":{"type":"string","title":"Fintray-Event-Id","description":"The same on every retry of one event: deduplicate on it."},"name":"Fintray-Event-Id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}},"required":true},"responses":{"200":{"description":"Received. Any 2xx counts as delivered."},"default":{"description":"Anything else, a 4xx included, is retried with growing delays for 24 hours."}}}}},"components":{"schemas":{"Bank":{"properties":{"iban":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Iban"},"bic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bic"},"bank_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bank Name"}},"type":"object","title":"Bank"},"Document":{"properties":{"id":{"type":"string","title":"Id"},"object":{"type":"string","const":"document","title":"Object","default":"document"},"status":{"type":"string","enum":["queued","processing","succeeded","failed"],"title":"Status"},"mode":{"type":"string","enum":["live","test"],"title":"Mode"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename"},"mime_type":{"type":"string","title":"Mime Type"},"pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages"},"created_at":{"type":"string","title":"Created At"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finished At"},"error":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"type":"null"}]},"schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schema Version"},"retention":{"type":"string","enum":["standard","zero"],"title":"Retention"},"result_deleted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Deleted At"},"document":{"anyOf":[{"$ref":"#/components/schemas/Invoice"},{"type":"null"}],"description":"The extraction, once succeeded and not yet expired."},"fields":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/FieldAssessment"},"type":"object"},{"type":"null"}],"title":"Fields","description":"Per field path (e.g. `vendor.vat_number`): how far to trust it. See confidence rules."},"warnings":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Warnings","description":"Codes to look at before booking: totals_mismatch, vendor_vat_missing, vendor_vat_unverified, invoice_date_in_future, buyer_vat_mismatch (not addressed to the buyer_vat sent), buyer_is_vendor (issued by it)."}},"type":"object","required":["id","status","mode","mime_type","created_at","retention"],"title":"Document"},"DocumentList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Document"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"DocumentList"},"Error":{"properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","title":"Error"},"Event":{"properties":{"type":{"type":"string","enum":["document.succeeded","document.failed"],"title":"Type"},"created_at":{"type":"string","title":"Created At"},"data":{"$ref":"#/components/schemas/EventDocument"}},"type":"object","required":["type","created_at","data"],"title":"Event","description":"What app/webhooks.py sends (FAC-382): it names the document and carries no extraction."},"EventDocument":{"properties":{"id":{"type":"string","title":"Id"},"object":{"type":"string","const":"document","title":"Object","default":"document"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"status":{"type":"string","enum":["succeeded","failed"],"title":"Status"},"url":{"type":"string","title":"Url","description":"Where to GET the document, with your key."},"error":{"anyOf":[{"$ref":"#/components/schemas/EventError"},{"type":"null"}],"description":"On `document.failed` only: the code. The message is on the document."}},"type":"object","required":["id","status","url"],"title":"EventDocument"},"EventError":{"properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"}},"type":"object","title":"EventError"},"FieldAssessment":{"properties":{"confidence":{"type":"string","enum":["high","medium","low"],"title":"Confidence"}},"type":"object","required":["confidence"],"title":"FieldAssessment"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Invoice":{"properties":{"vendor":{"$ref":"#/components/schemas/Vendor","default":{}},"customer":{"$ref":"#/components/schemas/Party","default":{}},"invoice_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Number"},"invoice_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invoice Date","description":"ISO 8601 date."},"due_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Due Date","description":"Only when printed; never computed from payment terms."},"po_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Po Reference"},"delivery_note_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivery Note Number"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"ISO 4217; lei is RON."},"exchange_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Exchange Rate","description":"As printed: RON per one unit of exchange_rate_currency."},"exchange_rate_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exchange Rate Currency"},"line_items":{"items":{"$ref":"#/components/schemas/Line"},"type":"array","title":"Line Items","default":[]},"subtotal":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Subtotal","description":"Net, before VAT, after a document-level discount."},"vat_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Vat Amount"},"discount_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Discount Amount"},"total_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Amount","description":"Gross, VAT included."},"prepaid_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prepaid Amount"},"amount_due":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount Due"},"payment_terms":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Terms"},"bank_details":{"$ref":"#/components/schemas/Bank","default":{}},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"quality_flags":{"$ref":"#/components/schemas/QualityFlags","default":{"low_confidence_fields":[]}}},"type":"object","title":"Invoice"},"Line":{"properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"quantity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quantity"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit"},"unit_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Unit Price","description":"Price of one unit; quantity × unit_price = total."},"vat_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Vat Rate","description":"Percent, e.g. 21."},"total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total","description":"The line's net amount as printed."},"lot_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lot Number"},"origin_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin Country"},"po_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Po Reference"},"delivery_note_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivery Note Number"},"details":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Details"}},"type":"object","title":"Line"},"Party":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"vat_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Number"}},"type":"object","title":"Party"},"QualityFlags":{"properties":{"overall_confidence":{"anyOf":[{"type":"string","enum":["high","medium","low"]},{"type":"null"}],"title":"Overall Confidence"},"low_confidence_fields":{"items":{"type":"string"},"type":"array","title":"Low Confidence Fields","default":[]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","title":"QualityFlags"},"Usage":{"properties":{"object":{"type":"string","const":"usage","title":"Object","default":"usage"},"period":{"additionalProperties":{"type":"string"},"type":"object","title":"Period"},"documents":{"type":"integer","title":"Documents"},"pages":{"type":"integer","title":"Pages"},"failed_documents":{"type":"integer","title":"Failed Documents"},"sandbox_documents":{"type":"integer","title":"Sandbox Documents"}},"type":"object","required":["period","documents","pages","failed_documents","sandbox_documents"],"title":"Usage"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"Vendor":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"vat_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Number"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"}},"type":"object","title":"Vendor"}}},"tags":[{"name":"keys","description":"Check a key, and whether it is a sandbox one."},{"name":"documents","description":"Submit an invoice, read its extraction, delete it."},{"name":"usage","description":"What the account is billed on."},{"name":"webhooks","description":"What we send your endpoint when a document finishes."}]}