agents-store Electronic Documents (EDO) via Bank MCP
Manage electronic document exchange (EDO / ЕДО — Електронний Документообіг) with bank counterparties. EDO is the standard way Ukrainian companies exchange legally binding documents (invoices, acts, contracts) through their bank.
Practical Example
User asks: "покажи вхідні документи за березень"
Workflow:
- Detect intent: the user wants incoming (inbox) documents for March 2026. "Вхідні" means inbox — documents sent to the user's company by counterparties.
- Determine the OKPO/EDRPOU to use. If the user has multiple companies, ask which one. If only one is configured, use it automatically.
- Call
getEdocJournalInboxwithdateBegin=2026-03-01,dateEnd=2026-03-31. - Format results as a summary table:
Output:
Вхідні документи за березень 2026:
| # | Дата | Тип | Відправник (ЄДРПОУ) | Сума | Статус |
|---|------------|-------------|----------------------|------------|--------|
| 1 | 2026-03-05 | Рахунок | 12345678 | ₴25 000,00 | new |
| 2 | 2026-03-12 | Акт | 87654321 | ₴12 500,00 | signed |
| 3 | 2026-03-20 | Договір | 12345678 | — | new |
Знайдено 3 документи. 2 потребують уваги (статус: new).
- Proactively highlight documents needing action (status:
neworpartially_signed) — the user likely wants to know what requires their attention.
Tool Discovery
Search for EDO-related MCP tools using keywords: edoc, document, journal, inbox, outbox, sign.
Typical PrivatBank tools: getEdocJournalAll, getEdocJournalInbox, getEdocJournalOutbox, getEdocBase64, getEdocSignInfo, deleteEdocDocument.
Understanding OKPO / EDRPOU
Many EDO operations require an okpo parameter. This is the company's unique identifier in Ukraine's corporate registration system.
Why it matters: Ukraine assigns every legal entity an 8-digit code called EDRPOU (ЄДРПОУ — Єдиний державний реєстр підприємств та організацій України). In bank APIs, this code appears as the okpo parameter (OKPO is the statistical classification name for the same number). The system needs this code to know which company's documents you want to access — a single user may manage multiple companies.
- okpo identifies your company (sender/recipient in the document).
- relatedOkpo identifies the counterparty.
- If the user does not know their OKPO/EDRPOU, suggest checking bank account details or company registration documents.
Common Document Types
| Ukrainian Name | English | Description |
|---|---|---|
| Рахунок | Invoice | Bill requesting payment |
| Акт (виконаних робіт) | Act of completed works | Confirms services rendered; both parties sign |
| Договір | Contract | Formal agreement |
| Податкова накладна | Tax invoice (VAT) | Required for VAT-registered businesses |
| Видаткова накладна | Delivery note | Accompanies shipped goods |
| Додаткова угода | Supplementary agreement | Amendment to existing contract |
| Довіреність | Power of attorney | Authorizes acting on behalf of company |
When filtering by docType, use exact type strings from the bank's API. Query unfiltered first to discover available types.
Document Status Values
| Status | Meaning |
|---|---|
| new | Just received, not yet reviewed |
| signed | All required digital signatures applied |
| partially_signed | Some signatures missing |
| rejected | Explicitly rejected by a party |
| expired | Signing deadline passed |
| delivered | Delivered to recipient |
| read | Opened/viewed by recipient |
| processing | Being processed by the system |
| deleted | Marked for deletion |
Exact status strings vary by bank API — check actual response data.
Document Journals
Three journal views:
| View | Description | Tool keyword |
|---|---|---|
| All | All documents (inbox + outbox + in-process) | journal, all |
| Inbox | Incoming documents | inbox |
| Outbox | Outgoing documents | outbox |
Query Parameters
| Parameter | Required | Description | Format |
|---|---|---|---|
| dateBegin | Yes | Start date | YYYY-MM-DD |
| dateEnd | Yes | End date | YYYY-MM-DD |
| docType | No | Filter by document types | Array of strings |
| status | No | Filter by statuses | Array of strings |
| okpo | No | Your company ЄДРПОУ | Array of strings |
| relatedOkpo | No | Counterparty ЄДРПОУ | String |
| docSumFrom | No | Minimum amount | String |
| docSumTo | No | Maximum amount | String |
| sortBy | No | Sort field | doc_id, type, status, sending_time, receipt_time, last_modify_time, amount, doc_date, create_time, sender_okpo, recipient_okpo |
| orderBy | No | Sort direction | asc, desc |
| limit | No | Page size | String (number) |
| offset | No | Page offset | String (number) |
Document Operations
Get Document Content (Base64)
Retrieve the actual document file (typically PDF or XML), encoded as Base64.
- Parameters:
id(document ID),okpo(company ЄДРПОУ) - Returns: Base64-encoded document content
Handling Base64 content:
- Identify format — most EDO documents are PDF or XML. Check if the response includes a content type or filename.
- Decode to file — convert Base64 to binary and save with the appropriate extension.
- For PDFs — you cannot render them inline. Report metadata (type, size, sender, date) and offer to save the decoded file.
- For XML — parse to extract structured data (amounts, dates, counterparty info).
Get Signature Info
View digital signature (EDS / ЕЦП) details.
- Parameters:
id(document ID),okpo(company ЄДРПОУ) - Returns: Signer name, timestamp, certificate info, validity status
Delete Document
Remove a document from the journal. Confirm with the user before deleting — this action is irreversible, and the document cannot be recovered.
- Parameters:
id(document ID),okpo(company ЄДРПОУ) - Only documents in certain statuses (
new,rejected) may be deletable.
Workflow: Receive, Review, and Respond
Step 1 — List Inbox
Query the inbox journal for the desired date range:
Call: getEdocJournalInbox
Params: dateBegin=2026-03-01, dateEnd=2026-03-24
Display as a summary table sorted by date descending (newest first) — users typically care about recent documents.
Step 2 — View a Document
Fetch the content for a document the user wants to review:
Call: getEdocBase64
Params: id=<doc_id>, okpo=<your_company_okpo>
Report document details. If PDF, offer to decode and save.
Step 3 — Check Signatures
Verify who has signed and whether signatures are valid:
Call: getEdocSignInfo
Params: id=<doc_id>, okpo=<your_company_okpo>
Step 4 — Respond
Based on document status and signatures:
- If the document requires your signature and signing tools are available, proceed.
- If the document should be rejected, check if rejection is available.
- If informational only, confirm receipt.
Error Handling
| Error | Action |
|---|---|
| Document not found | Verify the ID; it may have been removed by the counterparty |
| Insufficient permissions | Check that okpo matches your company; user may need elevated permissions |
| OKPO mismatch | Verify which company OKPO to use; if user has multiple, ask |
| Invalid date range | Dates must be YYYY-MM-DD with dateBegin <= dateEnd |
| Empty journal | Widen date range or remove filters; confirm OKPO is correct |
| Rate limit / timeout | Retry once; inform user if the issue persists |
Display Guidelines
- Format amounts with
₴symbol and thousand separators:₴25 000,00. - Use Ukrainian decimal separator (comma):
12 500,50not12500.50. - Sort inbox by date descending (newest first) by default.
- For status values, show Ukrainian translation alongside raw status when the user communicates in Ukrainian.
- Mask OKPO codes if the user requests it (e.g.,
1234****).