title: Documents description: Cost-document lifecycle: list, search, add, update, delete, recognize, sync.

Documents¶

Cost-document lifecycle: list, search, add, update, delete, recognize, sync.

Read tools¶

Tool	Summary
`get_document_id_list`	Discover all document IDs in one (year, month) folder, grouped by kind.
`get_documents_by_id`	Fetch full document records for a set of IDs, grouped by kind.
`list_documents`	List recently-added cost documents (invoices, receipts) for a company.
`list_recognized_documents`	Fetch the OCR-processed document data for a set of OCR origin IDs (SS08).
`search_documents`	Find a specific document by ID, document number, contractor NIP, or GUID.

Write tools¶

Mutates customer data

Calls under this heading change the SaldeoSMART account. Confirm intent before invoking from an autonomous agent.

Tool	Summary
`add_documents`	Upload cost documents (PDF, image, etc.) to a (year, month) folder (SS05).
`add_recognize_document`	Upload a single document and trigger OCR in one round-trip (AE01).
`correct_documents`	Overwrite OCR-extracted fields on already-uploaded documents (AE02).
`delete_documents`	Delete documents by Saldeo document_id (SS16).
`import_documents`	Bulk-import structured documents with full archival metadata (3.0).
`merge_document_dimensions`	Set dimension values on existing documents (SS20).
`recognize_documents`	Trigger OCR recognition on previously-uploaded documents (SS06).
`sync_documents`	Push accounting numbering / status back to Saldeo (SS13).
`update_documents`	Edit existing documents (SS17).

API reference¶

add_documents ¶

add_documents(company_program_id: str, documents: list[DocumentAddInput]) -> MergeResult | ErrorResponse

Upload cost documents (PDF, image, etc.) to a (year, month) folder (SS05).

Each entry pairs a folder with one local file. The file is read at invocation time, base64-encoded, and uploaded as the matching attmnt_N form field; <ATTMNT> in the XML carries the integer reference, <ATTMNT_NAME> carries the display name (defaults to the file's basename when not overridden in :class:Attachment).

add_recognize_document ¶

add_recognize_document(company_program_id: str, document: DocumentAddRecognizeInput) -> DocumentAddRecognizeResult | ErrorResponse

Upload a single document and trigger OCR in one round-trip (AE01).

Saldeo accepts one binary attachment per request. Returns an ocr_origin_id you can later pass to list_recognized_documents once recognition completes. Costs OCR credits from the wallet — status=INSUFFICIENT_FUND if the account is out.

correct_documents ¶

correct_documents(company_program_id: str, documents: list[DocumentCorrectInput]) -> MergeResult | ErrorResponse

Overwrite OCR-extracted fields on already-uploaded documents (AE02).

Each entry pins a document by document_id and supplies the corrected field values. self_learning=True tells Saldeo's recognizer to remember the correction for next time the same vendor's document arrives.

delete_documents ¶

delete_documents(company_program_id: str, document_ids: list[int]) -> MergeResult | ErrorResponse

Delete documents by Saldeo document_id (SS16).

⚠ Destructive. Each ID is removed in Saldeo.

get_document_id_list ¶

get_document_id_list(company_program_id: str, year: Year, month: Month) -> DocumentIdGroups | ErrorResponse

Discover all document IDs in one (year, month) folder, grouped by kind.

Use this as the first step of paginated browsing — call with a specific month, then get_documents_by_id with the buckets you care about. For a "last 10 days" scan, use list_documents instead.

Saldeo op: document.getidlist (3.0).

Parameters:

Name	Type	Description	Default
`company_program_id`	`str`	External program ID of the company.	required
`year`	`Year`	4-digit year of the folder.	required
`month`	`Month`	Month of the folder, 1–12.	required

Returns:

Type	Description
`DocumentIdGroups \| ErrorResponse`	DocumentIdGroups with eight ID buckets (contracts, invoices_cost,
`DocumentIdGroups \| ErrorResponse`	invoices_internal, invoices_material, invoices_sale, orders,
`DocumentIdGroups \| ErrorResponse`	writings, other_documents). Empty buckets are present but empty.

get_documents_by_id ¶

get_documents_by_id(company_program_id: str, contracts: list[int] | None = None, invoices_cost: list[int] | None = None, invoices_internal: list[int] | None = None, invoices_material: list[int] | None = None, invoices_sale: list[int] | None = None, orders: list[int] | None = None, writings: list[int] | None = None, other_documents: list[int] | None = None) -> DocumentList | ErrorResponse

Fetch full document records for a set of IDs, grouped by kind.

Pair with get_document_id_list (3.0 paginated browsing). Pass only the buckets you care about — omit unused ones. Saldeo op: document.listbyid (3.0).

Parameters:

Name	Type	Description	Default
`company_program_id`	`str`	External program ID of the company.	required
`contracts`	`list[int] \| None`	Optional list of contract document IDs from `get_document_id_list`.	`None`
`invoices_cost`	`list[int] \| None`	Optional list of cost-invoice document IDs.	`None`
`invoices_internal`	`list[int] \| None`	Optional list of internal-invoice document IDs.	`None`
`invoices_material`	`list[int] \| None`	Optional list of material-invoice document IDs.	`None`
`invoices_sale`	`list[int] \| None`	Optional list of sale-invoice document IDs.	`None`
`orders`	`list[int] \| None`	Optional list of order document IDs.	`None`
`writings`	`list[int] \| None`	Optional list of writing document IDs.	`None`
`other_documents`	`list[int] \| None`	Optional list of other-kind document IDs. Each bucket defaults to None (omitted from the request); pass only the buckets you care about.	`None`

Returns:

Type	Description
`DocumentList \| ErrorResponse`	DocumentList — flat list of full document records (the per-bucket
`DocumentList \| ErrorResponse`	grouping from the request is not preserved in the response).

import_documents ¶

import_documents(company_program_id: str, documents: list[DocumentImportInput]) -> MergeResult | ErrorResponse

Bulk-import structured documents with full archival metadata (3.0).

The richest write endpoint Saldeo exposes — accepts up to 50 documents per request, each with the source file, header metadata, optional currency override, dimensions, line items, payments, and up to 5 supporting attachments. Use document.add instead for a simple upload-only flow without the structured fields.

Per-document attachments (the source file + each supporting DocumentImportAttachmentInput) are uploaded as attmnt_N form fields; the XML references each by index.

list_documents ¶

list_documents(company_program_id: str, policy: DocumentPolicy = 'LAST_10_DAYS') -> DocumentList | ErrorResponse

List recently-added cost documents (invoices, receipts) for a company.

Use this for a fast "what's new" scan. For lookup by a specific identifier, prefer search_documents. For paginated browsing of a single month, use get_document_id_list + get_documents_by_id (3.0 endpoints).

Parameters:

Name	Type	Description	Default
`company_program_id`	`str`	External program ID of the company. Get one from `list_companies` if unknown.	required
`policy`	`DocumentPolicy`	Which documents to return: - LAST_10_DAYS — all documents added in the last 10 days (default) - LAST_10_DAYS_OCRED — only OCR-processed docs from last 10 days - SALDEO — only documents marked for export from SaldeoSMART UI	`'LAST_10_DAYS'`

Returns:

Type	Description
`DocumentList \| ErrorResponse`	DocumentList with each document's IDs, dates, monetary fields,
`DocumentList \| ErrorResponse`	contractor, and items. On failure, ErrorResponse — see
`DocumentList \| ErrorResponse`	docs/ERROR_CODES.md.

list_recognized_documents ¶

list_recognized_documents(company_program_id: str, ocr_origin_ids: list[int]) -> DocumentList | ErrorResponse

Fetch the OCR-processed document data for a set of OCR origin IDs (SS08).

Parameters:

Name	Type	Description	Default
`company_program_id`	`str`	External program ID of the company.	required
`ocr_origin_ids`	`list[int]`	IDs returned by a prior `document.recognize` call. Saldeo requires at least one — there's no "list everything" mode.	required

Returns the same DocumentList shape as list_documents. The richer nested data (articles, OCR origins, dimensions, KSeF) is dropped to keep the response LLM-friendly; reach for the lower-level client if needed.

merge_document_dimensions ¶

merge_document_dimensions(company_program_id: str, documents: list[DocumentDimensionInput]) -> MergeResult | ErrorResponse

Set dimension values on existing documents (SS20).

Each entry pins one document and the dimension code/value pairs to set. The dimensions referenced must already exist (use merge_dimensions).

recognize_documents ¶

recognize_documents(company_program_id: str, documents: list[RecognizeOptionInput]) -> MergeResult | ErrorResponse

Trigger OCR recognition on previously-uploaded documents (SS06).

Saldeo returns OCR_ORIGIN_IDs you can later pass to list_recognized_documents once the recognition completes.

search_documents ¶

search_documents(company_program_id: str, document_id: int | None = None, number: str | None = None, nip: str | None = None, guid: str | None = None) -> DocumentList | ErrorResponse

Find a specific document by ID, document number, contractor NIP, or GUID.

Use this for precise lookup. For a recent-activity scan, use list_documents instead.

Parameters:

Name	Type	Description	Default
`company_program_id`	`str`	External program ID of the company.	required
`document_id`	`int \| None`	Saldeo's internal numeric ID. At least one of document_id / number / nip / guid must be set.	`None`
`number`	`str \| None`	The document's printed number (e.g. "FV/1/2024").	`None`
`nip`	`str \| None`	The contractor's VAT number — narrows by counterparty.	`None`
`guid`	`str \| None`	Saldeo's stable per-document UUID.	`None`

Returns:

Type	Description
`DocumentList \| ErrorResponse`	DocumentList (typically 0 or 1 document, sometimes more if number
`DocumentList \| ErrorResponse`	matches multiple). On failure, ErrorResponse.

sync_documents ¶

sync_documents(company_program_id: str, syncs: list[DocumentSyncInput]) -> MergeResult | ErrorResponse

Push accounting numbering / status back to Saldeo (SS13).

Used by ERP integrations to tell Saldeo "we booked this document under register X with number Y" so the Saldeo UI can show the right state. Each entry must identify the document either by saldeo_id or by the triple (contractor_program_id, document_number, issue_date).

update_documents ¶

update_documents(company_program_id: str, documents: list[DocumentUpdateInput]) -> MergeResult | ErrorResponse

Edit existing documents (SS17).

Only set the fields you want to change — everything left as None is preserved on the server side.