Agicap Integration Research — Consolidated

Date: 2026-04-01 Product: Agicap (https://agicap.com) Purpose: Evaluate full API surface for Orcha integration — invoice posting, pre-accounting, payment reconciliation Status: Research complete. Blocked on Agicap connection provisioning for live testing.

1. Executive Summary

Agicap's public API is more capable than initially documented. Through a combination of official documentation, reverse-engineering, and OpenAPI spec extraction, we have mapped the complete API surface across all 5 API modules.

Key findings:

• Invoice posting: YES — Business Documents v2 has write endpoints for invoices, POs, and credit notes (confirmed via reverse-engineering, blocked on connection provisioning)
• Payment reconciliation: YES — Treasury Bank Journal v1 exports structured journal entries with invoice references, supplier info, GL accounts, analytical codes, and payment dates. Data represents confirmed bank transactions.
• Pre-accounting outside Agicap: PARTIALLY — Invoice metadata can carry cost center/GL account info, but no standalone master data APIs exist. Agicap expects pre-accounting to happen inside Agicap or to receive pre-enriched invoice data.
• Bank statement access: YES — Banking Documents v1 allows downloading raw bank files (CAMT.053, MT940, etc.), but NOT for PSD2 connections.
• Beneficiary management: YES — Payments v2 has full CRUD for beneficiaries (suppliers with bank details).
• Payment initiation/status: NO — Payments v2 only routes payment files INTO Agicap. No API to query payment status or execution confirmation.

2. API Landscape

Five API Modules

Hosts:

• https://api.agicap.com — Public API (all modules)
• https://api.agicap.internal — Internal (listed in OpenAPI specs, not accessible)
• https://openapi.agicap.com — Legacy partner endpoint
• https://app.agicap.com/api — Internal application API (undocumented)

Authentication

• Token endpoint: POST https://api.agicap.com/public/auth/v1/token (or https://myaccount.agicap.com/connect/token per newer specs)
• Grant type: client_credentials
• Content-Type: application/x-www-form-urlencoded
• Scopes:
  • agicap:public-api — General API access
  • public-api:import_payment_files — Payment file routing
  • public-api:import_payment_files_with_signed_beneficiaries — Secured payment routing
  • public-api:manage-payment-beneficiaries — Beneficiary CRUD
• Token lifetime: ~3600 seconds
• Credential management: https://app.agicap.com/fr/app/organization-advanced-settings/public-api/clients

OpenAPI Specs

We extracted the complete OpenAPI 3.0 JSON specs for all modules from the developer portal. These are the authoritative API references:

Developer Portal

• URL: https://api.agicap.com/
• Type: JavaScript SPA — does NOT render for web scrapers
• Access: Requires authenticated browser session
• PDF Guide: https://api.agicap.com/treasury-bank-journal/detailed_documentation.pdf
• Postman Collection: https://www.postman.com/agicap-data-int/agicap-public/

3. Treasury Bank Journal v1 — Payment Reconciliation

Purpose: Export bank accounting entries as structured JSON for ERP/accounting system import.

Source: OpenAPI spec extracted from developer portal (complete, with examples).

Endpoints

Export Entry Schema (ExportedBankJournalEntryDto)

Each bank journal entry represents a confirmed bank transaction (money has moved).

Entry-level fields (bank side):

Counterpart fields (invoice/supplier side) — counterparts[] array:

Document fields (nested in counterpart) — document object:

Error Feedback

When reporting import errors via mark-as-not-imported, typed error categories are:

• UNKNOWN_JOURNAL_CODE
• UNKNOWN_ACCOUNTING_ACCOUNT
• UNKNOWN_THIRD_PARTY
• UNKNOWN_ANALYTICAL_CODE
• OTHER

Reconciliation Data Flow

Bank executes payment
    → Bank sends statement to Agicap (via EBICS/SWIFT/PSD2)
    → Agicap ingests statement, matches to invoices
    → Entry becomes "Ready to export"
    → Orcha calls POST /exports/{exportId}
    → Orcha receives structured JSON with:
        - paymentDate (actual bank transaction date)
        - amounts (debit/credit in original + accounting currency)
        - counterparts with:
            - supplier name + code + external ID
            - invoice number (documentReference)
            - source system ID (externalId) ← Orcha's own ID
            - GL account + type
            - cost centers (analyticalCodes)
            - tax key
    → Orcha matches against its own invoice records
    → Orcha calls mark-as-imported or mark-as-not-imported

Timing: Entries appear 1-3 business days after payment execution (depends on bank statement delivery frequency).

Constraints

• Max 5000 entries per export call
• Entries move from "Ready to export" → "Exported" and cannot be re-exported (but can be re-retrieved via GET)
• Cursor-based pagination with ISO 8601 timestamps
• No filtering by date range of payment — only by export date
• No webhooks — must poll

4. Banking Documents v1 — Raw Bank File Access

Purpose: Import and export raw bank statement files to/from Agicap.

Source: OpenAPI spec extracted from developer portal (complete).

Endpoints

Supported Formats

Import: CAMT.053, CAMT.052, N43, CFONB120, MT940, CBI, BAI2, ZIP (containing multiple files)

Export: Files are returned in their original format.

Key Limitation

"This API cannot be used to export banking data that is retrieved in Agicap via an Open Banking / PSD2 connection."

Only works for EBICS, SWIFT, EDITRAN, Host-to-Host, KONFIPAY, and PUBLIC_API connections.

Use Case for Orcha

This API is an alternative reconciliation path — download raw CAMT.053 files and parse them yourself. More work than using Treasury Bank Journal (which gives structured JSON), but gives you the raw bank data without Agicap's interpretation.

5. Business Documents v2 — Invoice Posting & Pre-Accounting

Purpose: Push invoices, POs, credit notes, quotes, and sales orders into Agicap for cash forecasting and receivables tracking.

Source: Official OpenAPI spec extracted from developer portal (complete, with examples).

Endpoints

All document types support GET (paginated list), POST (batch create), and PUT (batch update):

Additional endpoints:

• POST .../connections — Create a new connection (requires Agicap back-office activation)
• GET .../connections — List connections
• POST .../{id}/attach-readable — Upload PDF file to a document (Beta)
• DELETE .../{id}/unattach-readable — Remove PDF from a document (Beta)

Supplier/Client Invoice Schema (V2, from official OpenAPI)

Required fields for create (CreateSupplierInvoiceDtoV2):

Accounting fields (optional, for pre-accounting):

The accounting object is available on invoices and credit notes only (not on POs, quotes, or sales orders).

Optional fields:

Instalment fields (instalments[] array):

Status values by document type:

Pre-Accounting Capabilities

The official spec confirms that pre-accounting data CAN be pushed via the accounting object on invoices and credit notes:

{
  "externalId": "orcha-doc-uuid",
  "invoiceNumber": "INV-2024-001",
  "counterParty": { "id": "supplier-123", "name": "Lieferant GmbH" },
  "currency": "EUR",
  "amounts": { "totalAmount": 1190.00, "taxesAmount": 190.00, "dueAmount": 1190.00 },
  "accounting": {
    "accountCode": "70100",
    "accountNumber": "4200",
    "amount": 1190.00,
    "currency": "EUR"
  },
  "status": "due",
  "issueDate": "2024-01-15T00:00:00Z",
  "dueDate": "2024-02-15T00:00:00Z",
  "metadata": { "costCenter": "CC-MARKETING" },
  "erpIdentificationFields": { "sapDocNumber": "5100000123" }
}

What CAN be written for pre-accounting:

• GL account number (accounting.accountNumber) — YES, first-class field
• Third party account code (accounting.accountCode) — YES, first-class field
• Accounting amount in different currency (accounting.amount + accounting.currency) — YES
• Cost centers — via metadata (keys still unknown, need testing)
• ERP-specific fields — via erpIdentificationFields

What CANNOT be written:

• Chart of accounts definitions (no master data API)
• Cost center definitions (no master data API)
• Tax code definitions (no master data API)
• Line-level detail (no line items array on the DTO)

Important API Behavior

• Isolated repository: Documents pushed via API can ONLY be read/modified via API. They exist separately from documents created in the Agicap UI or imported via ERP connectors.
• No UI editing: Documents synced via API cannot be edited or deleted from the Agicap app. All status changes (e.g. marking as paid, deleting) must go through the API by updating status and dueAmount.
• Use case scope: The API is designed to sync unpaid or partially paid invoices to feed Agicap Treasury (cash forecasting) and Account Receivable (payment follow-up). Syncing paid invoice history is not required unless using the Analytics page.
• Sync frequency: Agicap recommends at least once before start of business day (users typically log in around 9am).
• Supported scenarios: Down payments, multiple instalments, partial payments, payments not yet matched to invoices.
• PDF upload (Beta): Invoice PDFs can be attached via attach-readable endpoint (multipart/form-data).

Connection Provisioning

Connections can be created via API with POST .../connections:

{
  "name": "Connection Name",
  "integrationName": "Integration Name",
  "source": "External integrator - Orcha"
}

Each new connection requires specific activation in Agicap's back-office system before documents become available in the Agicap app. This is a manual step by Agicap support.

6. Payments v2 — Payment File Routing + Beneficiaries

Purpose: Route externally-generated payment files into Agicap for bank submission, and manage beneficiaries.

Source: OpenAPI spec extracted from developer portal (complete).

Payment File Routing (write-only, no read/status)

Files are forwarded to the bank unmodified. Supports all standard banking XML/TXT formats.

No endpoints exist to:

• List executed payments
• Query payment status
• Get payment history
• Retrieve bank confirmations (PSR)

Beneficiary Management (full CRUD)

Beneficiary schema:

Note: Beneficiaries only contain identity + bank details. No GL account, cost center, or accounting information.

7. Card Expenses Bank Journal v1 — Corporate Card Expense Export

Purpose: Export pre-accounted card expense journal entries from Agicap's Business Spend Management module.

Source: Official OpenAPI spec extracted from developer portal (complete).

Product context: Agicap offers physical and virtual Mastercard corporate cards with built-in expense management — receipt capture via mobile app, per-card spending limits, approval workflows, auto-categorization to cost centers and chart of accounts, and pre-accounting. (Agicap Ausgabenmanagement)

Endpoint

Single read-only endpoint:

Query parameters:

• LastSynchronizationDate — ISO 8601 datetime, returns entries after this date
• PageSize / PageNumber — Standard pagination

Entry Schema (AccountingTransactionLine)

Each card expense journal entry is a simple debit/credit pair:

What's NOT in the schema (compared to Treasury Bank Journal)

• No externalId — no round-trip matching capability
• No document object — no invoice/receipt reference
• No analyticalCodes / dimensions — no cost center data
• No counterparts[] array — flat debit/credit structure, not multi-line
• No receipt/attachment data — cannot retrieve scanned receipts
• No card holder name — cannot identify which employee made the expense
• No expense category — only GL account numbers

Critical Workflow Dependency

From the API documentation:

"You need your accountant to prepare the journal entries and click on 'export to my accounting software' for them to be available from the API database."

Card expense entries are NOT automatically available via the API. An accountant must manually prepare and click export in the Agicap UI first. This is fundamentally different from the Treasury Bank Journal (which has automatic "Ready to export" entries).

Comparison with Treasury Bank Journal

Assessment for Orcha Integration

The card expense API provides enough data for a basic DATEV booking proposal (GL account + amount + merchant + date), but Orcha cannot add significant intelligence since:

1. Pre-accounting already happened inside Agicap
2. No receipt data flows through the API
3. No cost center / dimension data
4. Manual step required before data is available

Recommendation: Phase 2 add-on, not core integration. Focus on the AP invoice flow first.

8. Pre-Accounting Outside Agicap — Feasibility Analysis

The Question

Can Orcha perform pre-accounting (GL account assignment, cost center tagging, tax code assignment) and push the enriched data into Agicap, so the partner doesn't need to do pre-accounting in Agicap?

What Can Be Written

What Cannot Be Written

Assessment

Agicap is not designed to receive pre-accounting master data via API. The platform expects either:

1. Pre-accounting done inside Agicap — users set up chart of accounts, cost centers, categories, and tax rules in the Agicap UI, then Agicap's AI auto-categorizes incoming invoices
2. Master data synced from ERP via native connectors — Agicap's 400+ ERP integrations (SAP, NetSuite, etc.) sync chart of accounts, cost centers, and supplier data bidirectionally
3. Pre-enriched documents via API — push invoices with metadata that Agicap maps to its internal accounting structures (mechanism confirmed to exist, keys unknown)

For Orcha's use case: Option 3 is the path. Push invoices with metadata containing cost center and GL account information. The metadata dictionary is the bridge. But until a connection is provisioned, we cannot test which keys Agicap maps to analyticalCodes and accountingAccountNumber in the Treasury Bank Journal export.

9. Complete Capability Matrix

10. Recommended Integration Architecture

Phase 0 — Unblock (immediate)

1. Contact Agicap to provision a Business Documents connection for entity 211584
2. Extract Business Documents v2 OpenAPI spec from developer portal (same method as other specs)
3. Test metadata keys — once connection exists, push invoices with various metadata keys and check if they appear as analyticalCodes / accountingAccountNumber in Treasury Bank Journal exports
4. Rotate test credentials (Client ID MWKY9K5mrD)

Draft message for Agicap: see agicap-investigation-summary.md lines 161-173.

Phase 1 — Invoice Posting (Orcha → Agicap)

Orcha processes invoice
    → Orcha enriches with GL account, cost center, tax code
    → POST /business-documents/v2/.../supplier-invoices
        {
          externalId: "orcha-doc-uuid",
          invoiceNumber: "INV-2024-001",
          counterParty: { id: "supplier-123", name: "Lieferant GmbH" },
          amounts: { totalAmount: 1190.00, taxesAmount: 190.00, dueAmount: 1190.00 },
          status: "due",
          issueDate: "2024-01-15",
          dueDate: "2024-02-15",
          metadata: {
            "costCenter": "CC-MARKETING",
            "accountingAccount": "4200",
            "taxKey": "VSt19"
          }
        }

Phase 2 — Payment Reconciliation (Agicap → Orcha)

Poll: GET /treasury-bank-journal/v1/entities/{entityId}/exports?after={lastPollDate}&size=100
    → For each new export:
        GET /exports/{exportId}
        → For each entry:
            Match entry.counterparts[].document.externalId to Orcha document ID
            Extract: paymentDate, amounts, thirdPartyName, analyticalCodes
            Update Orcha document status to "paid"
        → POST /mark-as-imported with successful agicapUniqueIds
        → POST /mark-as-not-imported for any errors

Phase 3 — Beneficiary Sync (optional)

Orcha syncs supplier bank details → Payments v2 Beneficiaries API
    → Keeps Agicap beneficiary list in sync with Orcha supplier master data
    → Enables Agicap to validate IBANs and manage payment security

11. Open Questions for Agicap

Critical (blocks implementation)

1. How do we get a Business Documents connection provisioned for API integration?
2. How do we attach analytical dimensions (called "dimensions" in Agicap UI, exported as analyticalCodes in Treasury Bank Journal) to invoices pushed via Business Documents v2? Is it via metadata, erpIdentificationFields, or a separate mechanism?
3. What metadata keys map to accountingAccountNumber (GL accounts)?
4. Can thirdPartyCode be set via invoice metadata, or is it derived from counterParty.id?
5. Is there a sandbox/test environment?

Important (affects architecture)

6. What is the pricing for API access? Enterprise tier required?
7. What bank connection type does the partner use — EBICS or PSD2? (affects Banking Documents API availability)
8. How frequently do bank statements arrive in Agicap? (determines reconciliation latency)
9. Are there rate limits beyond the 5000 entries/export limit?

Nice-to-have

10. Is there a partner API program for direct integration?
11. Can Celigo's Import endpoints be called directly without Celigo?
12. Are there plans to add webhooks or payment status query endpoints?

12. Licensing & Access

13. Dead Ends (don't revisit)

• Chift: Agicap is a customer of Chift, not a connector. Cannot use Chift to bridge to Agicap.
• SFTP self-service: Doesn't exist. Custom-quoted professional services engagement.
• Agicap UI for API connections: "Banks and Integrations" only handles bank/EBICS connections, not API integration sources.
• Public API docs for write endpoints: Don't exist. Developer portal is a JS SPA.
• Connection creation via API: POST /connections on Business Documents returns 500.
• Standalone master data APIs: Categories, cost-centers, accounts, contacts, suppliers — all return 404.
• Zapier, Make, n8n, Workato, Tray.io, Merge.dev, Rutter: No native Agicap connectors.

14. Sources & References

Official Documentation

• Agicap Developer Portal (SPA, requires browser)
• Treasury Bank Journal PDF Guide
• Business Documents Guide
• Authentication Guide
• Postman Collection

OpenAPI Specs (extracted)

• Treasury Bank Journal v1 — complete (with examples and full schemas)
• Banking Documents v1 — complete
• Payments v2 — complete
• Business Documents v2 — complete (with examples and full schemas)
• Card Expenses Bank Journal v1 — complete

iPaaS

• Celigo Agicap Connector — Native connector with Import (write) support, ~$6k/yr
• Celigo Available Agicap APIs (403-gated)

Integration Partners

• Agicap DATEV Integration — Direct API export for German pre-accounting
• Agicap NetSuite Integration — Most documented ERP example
• Chift Case Study
• Agicap Partner Program

Previous Research (this repository)

• API Integration Research (2026-03-31) — Initial API landscape mapping
• Investigation Summary (2026-02-22) — Hands-on testing, DTO reverse-engineering
• Integration Research (2026-03-31) — Product features, DATEV, German integrations