Agicap Integration Feasibility Analysis

Date: 2026-02-22 Status: API exploration complete -- write endpoints confirmed, connection provisioning required

Summary

Agicap's Business Documents API supports write operations for invoices, purchase orders, and credit notes. These endpoints are not publicly documented but were discovered via Celigo's native connector and confirmed by direct API testing.

Confirmed Write Endpoints (both v1 and v2 tested)

Base URL: https://api.agicap.com/public/business-documents/{v1|v2}/entities/{entityId}/connections/{connectionId}/

Valid status values:

• Supplier invoices: none, draft, due, paid, cancelled, deleted, paymentExecuted
• Client invoices: none, draft, due, paid, cancelled, deleted

NOT available as separate write endpoints: categories, cost-centers, accounts, contacts, suppliers, expected-transactions, payment-orders (all return 404)

V2 DTO Schema (reverse-engineered via validation errors)

V2 is recommended -- richer schema with more fields. Both v1 and v2 coexist.

V1 required fields: externalId, currency, amounts.totalAmount, status V2 adds: invoiceNumber/purchaseOrderNumber/creditNoteNumber, issueDate, dueDate (invoices only), counterParty.id, amounts.taxesAmount, amounts.dueAmount

Optional fields (confirmed parsed by DTO via type-error testing):

The metadata field is the most likely mechanism for pushing cost centers and GL accounts as key-value pairs (e.g., {"costCenter": "CC-001", "glAccount": "4200"}). The exact key names recognized by Agicap need to be confirmed with a live connection.

Fields confirmed NOT on the DTO (silently ignored): description, costCenter (as top-level), category, account, tags, lineItems, notes, paymentTerms, reference, lines, items, allocations, payments, attachments, supplier, contact, bankAccount, paymentMethod

Request format: Array of DTOs, e.g.:

[{
  "externalId": "orcha-001",
  "invoiceNumber": "INV-2024-001",
  "currency": "EUR",
  "amounts": {"totalAmount": 119.00, "taxesAmount": 19.00, "dueAmount": 119.00},
  "status": "draft",
  "issueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "counterParty": {"id": "supplier-001", "name": "Test Supplier GmbH"},
  "paymentDate": null,
  "metadata": {"costCenter": "CC-001", "glAccount": "4200"}
}]

Connection Requirement (Blocker)

Write endpoints require a valid connectionId (GUID format) in the URL path. This represents a configured integration source in Agicap.

Current state: Entity 211584 has zero connections (GET /connections returns []). All invoice POST attempts return HTTP 500 because the backend crashes on non-existent connection IDs.

Connection creation endpoint (POST /entities/{entityId}/connections) exists and expects a CreateConnectionDto wrapped in {"dto": {...}}, but always returns HTTP 500 regardless of field combinations tested. This endpoint appears to require internal Agicap provisioning or partner-level access.

Implication: To push invoices, a connection must first exist for the entity. It can likely be created through:

1. Agicap UI: Forecast page > cogwheel > "Banks and integrations" > "Connect a bank" > set up any integration. Pre-built connectors (NetSuite, Xero, Spendesk, etc.) auto-create a connection during setup.
2. Partner connector like Celigo creating the connection during its setup flow
3. Agicap onboarding/support setting up a custom integration source
4. Agicap's internal admin UI

To try yourself: In your Agicap test account, go to the Forecast page, click the cogwheel icon, navigate to "Banks and integrations", and try adding any integration. Once added, check GET /connections again to see if a connection ID appears.

Open questions:

• What metadata keys does Agicap recognize for cost centers and GL accounts? (can only test once a connection exists)
• Whether Agicap persists arbitrary metadata keys or only specific predefined ones
• What happens when you POST invoices via v2 to a live connection -- do they appear in Agicap's UI?

Auth

• OAuth 2.0 Client Credentials flow
• Token endpoint: POST https://api.agicap.com/public/auth/v1/token
• Scope: agicap:public-api
• Token lifetime: 3600 seconds

Questions Investigated

Agicap API Landscape

Three API Layers

Public API Products (6 confirmed)

Key Links

• Developer Portal: https://api.agicap.com/
• Auth Guide: https://api.agicap.com/guides/authentication
• Business Documents Guide: https://api.agicap.com/guides/business_documents (JS SPA, not scrapable)
• Business Documents v2 Details: https://api.agicap.com/api-details/business-documents-v2 (JS SPA, not scrapable)
• Treasury Bank Journal PDF: https://api.agicap.com/treasury-bank-journal/detailed_documentation.pdf
• Legacy Docs: https://openapi.agicap.com/docs/index.html
• Postman (new): https://www.postman.com/agicap-data-int/workspace/agicap-public/documentation/16057249-07e739b2-d2f7-4437-82fa-7ca0d290336b
• Partner Program: https://agicap.com/en/partners/become-partner/

Agicap UI Navigation

• Integration setup: Forecast page > cogwheel icon (top-right) > "Banks and integrations" > "Connect a bank"
• API credentials: Organization settings > Advanced settings > API settings > "Generate new credentials"

Write API Verification

Phase 1: Web Research (no write endpoints found publicly)

After 40+ targeted searches across Postman collections, GitHub, Celigo docs, and community notebooks: all publicly documented POST endpoints are functionally read/export triggers. All community code samples (7 Jupyter notebooks) are read-only.

Phase 2: Celigo Discovery (write capability confirmed)

Celigo's native Agicap connector confirmed "Import" (write) support, revealing that write endpoints exist on the same api.agicap.com infrastructure.

Phase 3: Direct API Testing (endpoints confirmed, connection blocker found)

Confirmed write endpoints via HTTP 400 validation errors (proving the endpoints exist and parse requests):

POST /public/business-documents/v1/entities/{entityId}/connections/{connectionId}/supplier-invoices
POST /public/business-documents/v1/entities/{entityId}/connections/{connectionId}/client-invoices
POST /public/business-documents/v1/entities/{entityId}/connections/{connectionId}/purchase-orders
POST /public/business-documents/v1/entities/{entityId}/connections/{connectionId}/client-credit-notes
POST /public/business-documents/v1/entities/{entityId}/connections/{connectionId}/supplier-credit-notes

Confirmed via validation error responses:

• entityId must be numeric (not UUID or OAuth Client ID)
• connectionId must be GUID format
• Request body is array of DTOs: [{...}]
• Required fields: externalId, currency, amounts.totalAmount, status
• Status validation: none, draft, due, paid, cancelled, deleted (client) + paymentExecuted (supplier)
• Backend is .NET/C# with DTO types like CreateSupplierInvoiceDto, CreateClientInvoiceDto, etc.

Confirmed NOT available (all return 404): categories, cost-centers, accounts, contacts, suppliers, expected-transactions, payment-orders, settings, integrations, sources

Confirmed read endpoints:

• GET /public/treasury-bank-journal/v1/entities/{entityId}/exports?size=N&after=DATE -- works, returns {items:[], cursor:{...}}
• GET /public/business-documents/v1/entities/{entityId}/connections -- works, returns []
• POST /public/treasury-bank-journal/.../exports -- returns 405 (GET only)

Connection creation blocker:

• POST /entities/{entityId}/connections expects {"dto": <CreateConnectionDto>} but returns HTTP 500 for all field combinations
• Connection must be provisioned by Agicap (likely during partner onboarding)

SFTP Investigation

SFTP is a custom-quoted professional services engagement, not self-service.

From Agicap's Terms & Conditions (Section 3.2.2):

"Any specific request which requires a significant amount of time may be the subject of a separate quotation (such as, for example, implementation of an SFTP server, importing a high volume of historical data...)"

• No publicly documented file formats, field mappings, or templates
• Agicap themselves consider SFTP inferior to API (per Chift case study)
• Likely supports: CAMT.053, CAMT.052, MT940, pain.001, CSV (for banking data)

Chift Investigation

Chift CANNOT bridge Orcha to Agicap.

Agicap is a customer of Chift, not a connector within Chift's ecosystem. There is no "Agicap connector" in Chift's 129-connector catalog. Chift bridges SaaS apps to accounting tools (Sage, Xero, etc.), not between SaaS apps.

[Accounting Tools] <--Chift--> [Agicap]
 (Sage, Pennylane,               (uses Chift to
  Cegid, Horus, etc.)             pull/push data)

Even as a Chift customer, Orcha would access accounting tools, NOT Agicap itself.

Celigo Deep Dive

Key Revelation

Celigo's native Agicap connector (November 2024) supports:

The "Import" support confirms Agicap's API HAS write endpoints that aren't publicly documented. The Celigo connector uses the same OAuth 2.0 Client Credentials auth as the public API.

What can be written?

The definitive list is at https://docs.celigo.com/hc/en-us/articles/30494721329051-Available-Agicap-APIs (behind Cloudflare, couldn't be scraped). Likely writable objects based on Agicap's data model:

• Expected transactions (core to cash flow forecasting)
• Banking documents
• Invoices / pre-accounting data
• Supplier accounts

Celigo as Middleware

Orcha (Clojure/JVM)
  -> HTTP call to Celigo API (Bearer token auth)
    -> Celigo transforms/validates
      -> Celigo calls Agicap API (native connector)
        -> Response flows back (synchronous for imports/exports)

Capabilities:

• Full REST API (api.integrator.io) for programmatic control
• Synchronous import/export invocation
• Webhook listeners and API Builder for custom endpoints
• ~1M requests/hour rate limit

Celigo Pricing

Flat-rate, no per-transaction fees. 33-47% discounts common in negotiation.

Celigo Assessment for Orcha

Pros: Native Agicap connector with confirmed write support, full API for programmatic control, built-in error handling/retry/monitoring, EU (Germany) deployment, HTTP mode escape hatch for any Agicap endpoint.

Cons: ~$6k+/year minimum for a single integration, adds third-party dependency, cloud-only (not self-hostable), not code-first, vendor lock-in, debugging across three systems.

How Data Gets INTO Agicap Today

Recommended Path Forward

Critical Next Step: Get a Connection Provisioned

The write API endpoints are confirmed working, but they require a connectionId that must be provisioned by Agicap. Without this, no data can be pushed.

Immediate Actions

1. Contact Agicap via partner program (https://agicap.com/en/partners/become-partner/) -- request:
   • A provisioned "connection" for entity 211584 (or guidance on how to create one)
   • Full API documentation for the Business Documents write endpoints
   • List of optional fields on invoice DTOs (cost center, GL account, etc.)
2. Alternative: Use Celigo -- Celigo's native connector likely auto-provisions the connection during its setup flow. The free tier (2 endpoints, 1 flow) could be used to:
   • Create a working connection
   • Discover optional invoice fields
   • Test end-to-end invoice creation

Medium-Term

3. Decide on architecture: Direct API integration vs. Celigo middleware
4. Test optional fields: Once a connection exists, send invoices with cost center, GL account, supplier, and other optional fields to see which are persisted
5. Rotate API credentials: The current test credentials (Client ID MWKY9K5mrD) were used in this exploration and should be rotated

Architecture Decision

Recommended: Direct API integration. The endpoints work, the auth is standard OAuth 2.0, the DTO format is straightforward. The only missing piece is connection provisioning. Build a native Clojure integration module following Orcha's existing DATEV/Maesn pattern (config.edn, integrations namespace, Malli schemas, KMS encryption, audit trail).

If Agicap won't provision connections directly, use Celigo's free tier to create the connection, then call the Agicap API directly from Orcha (bypassing Celigo for ongoing operations).

Direct API Testing Log

Test Account

• Entity ID: 211584
• Auth: OAuth 2.0 Client Credentials, scope agicap:public-api
• Token endpoint: POST https://api.agicap.com/public/auth/v1/token
• Token lifetime: 3600 seconds

Successful Calls

Validation Error Responses (confirming endpoint existence)

Error Responses

Sources

Agicap Official

• Developer Portal
• Authentication Guide
• Treasury Bank Journal Guide
• Treasury Bank Journal PDF
• Legacy API Docs
• Integration Marketplace
• Banking & ERP Connectivity
• Banking Networks, Protocols & Formats
• Partner Program
• General Terms & Conditions

Celigo

• Agicap Connection Setup
• Available Agicap APIs (behind auth)
• November 2024 Release Notes
• API Builder
• Flow Invoke
• Import Invoke API
• Webhooks
• Pricing

Chift

• Agicap Case Study
• Documentation
• Connectors

Community

• Postman Collection (new)
• Postman Collection (legacy)
• jupyter-naas Agicap Notebooks
• API Tracker - Agicap