Collection Integration with Accounting Systems

1. Purpose and Scope

This document describes how accounting/ERP systems integrate with the Sunbay Collection Platform to enable:

The integration is designed as one-way data ingestion into Sunbay:

Invoicing data can be provided to Sunbay via two primary mechanisms:

This document focuses on:

2. High-Level Architecture

3. Data Model and Mapping

3.1 Core Entities

Each invoice record provided to Sunbay (via API or Google Sheets) is mapped to internal invoice and recipient entities. The following fields are used by the current collection implementation.

3.2 Example Unpaid Invoices Response (Customer Endpoint → Sunbay)

Sunbay expects the customer integration endpoint (described in section 5) to return a list of unpaid invoices.
The example below shows the expected shape of a single invoice object in the invoices array.

Example response payload:

{
  "invoices": [
    {
      "invoiceNumber": "2025-0001",
      "invoiceId": "12345",
      "customerName": "Example Seller Sp. z o.o.",
      "customerId": "54321",
      "customerCountryCode": "PL",
      "customerAddress": "Street 1, 00-000 City, Country",
      "customerPhoneNumber": "+48123456789",
      "customerEmail": "john.doe@example.com",
      "customerEmailCc": "accounting@example.com",
      "issueDate": "2025-12-01T00:00:00Z",
      "dueDate": "2025-12-25T00:00:00Z",
      "amount": 199.99,
      "currency": "PLN",
      "bankAccount": "PL00105000997603123456789123",
      "invoiceUrl": "https://example.com/invoices/2025-0001.pdf",
      "customFields": {
        "contractNumber": "AKG321"
      }
    }
  ]
}

Sunbay maps the invoices array from the customer endpoint to its internal invoice and recipient models using the fields described in section 3.1.

4. End-to-End Process Flows

4.1 Single Collection Flow

  1. Sunbay ingests invoices from configured data sources
    • API-based integration: Sunbay calls the configured Invoicing/Collections API on an agreed schedule (e.g. every 15 minutes, hourly, daily) and requests invoices that are new or updated since the last sync.
    • Google Sheets–based integration: Sunbay reads invoices from a configured sheet that is populated from exported accounting data.
  2. Validation and mapping in Sunbay (single process)
    • Sunbay validates mandatory fields for single flows (customer name, invoice number, customer contact data, etc.).
    • Invalid or incomplete records are flagged in Sunbay for review and are not sent for collection until corrected.
  3. Creation of collection items and notifications in Sunbay
    • For each valid invoice, Sunbay creates an internal single collection item.
    • Collection steps (email/SMS) are scheduled per invoice; each notification relates to exactly one invoice and uses that invoice’s data for placeholders and attachments.
  4. Status visibility
    • Collection statuses are visible in Sunbay and can be used for reconciliation and reporting.
    • The accounting/ERP system remains the system of record for financial postings; Sunbay does not update accounting entries.

4.2 Recurring Collection Flow

  1. Sunbay ingests invoices for recurring flows
    • Invoices are imported for a recurring collection flow using the same invoice structure as for single flows.
  2. Validation and mapping in Sunbay (recurring process)
    • Sunbay validates mandatory fields for recurring flows (invoice number, customer contact data, bank account, etc.).
    • Invalid or incomplete records are flagged in Sunbay for review and are not sent for collection until corrected.
  3. Grouping logic for recurring collections
    • Sunbay groups invoices by recipient using CustomerId.
    • For each customer, Sunbay creates a recurring collection condition instance which aggregates all unpaid invoices.
  4. Recurring handling and notification pattern in Sunbay
    • When recurring conditions are scheduled and executed, Sunbay sends one notification per recipient rather than per invoice.
    • Email notifications contain a table of all invoices included in the condition instance, along with an aggregated summary (for example total amount due per currency).
    • SMS notifications can include a comma-separated list of invoice numbers in the message body, representing all invoices covered by that recurring reminder.
  5. Status and reporting
    • Collection statuses are visible in Sunbay and can be used for reconciliation and reporting.
    • The accounting/ERP system remains the system of record for financial postings; Sunbay does not update accounting entries.

5. Integration Interface (API-Based Source)

5.1 Endpoint Overview

For direct API integration, Sunbay expects a REST-style HTTP(S) API exposed by the accounting system or an integration layer. Typical pattern:

The API should return a list of unpaid invoices and MAY support filters and paging, for example:

The exact filtering and pagination strategy is decided and implemented by the integrating company.

5.2 Request Example (POST)

{
  "pageSize": 500,
  "pageNumber": 1
}

5.3 Response Example

The response body contains an invoices array with invoice objects in the shape described in section 3.2. For example:

{
  "invoices": [
    {
      "invoiceNumber": "2025-0001",
      "invoiceId": "12345",
      "customerName": "Example Seller Sp. z o.o.",
      "customerId": "54321",
      "customerCountryCode": "PL",
      "customerAddress": "Street 1, 00-000 City, Country",
      "customerPhoneNumber": "+48123456789",
      "customerEmail": "john.doe@example.com",
      "customerEmailCc": "accounting@example.com",
      "issueDate": "2025-12-01T00:00:00Z",
      "dueDate": "2025-12-25T00:00:00Z",
      "amount": 199.99,
      "currency": "PLN",
      "bankAccount": "PL00105000997603123456789123",
      "invoiceUrl": "https://example.com/invoices/2025-0001.pdf",
      "customFields": {
        "contractNumber": "AKG321"
      }
    }
  ]
}

5.4 Error Responses

Standard HTTP status codes and a structured error body are recommended, for example:

Error body example:

{
  "errorCode": "INVALID_PARAMETER",
  "message": "fromDate must be a valid ISO 8601 date.",
  "correlationId" : "47d96e4c-314c-45cc-a979-1c0928729169"
}

6. Security

6.1 Transport Security

6.2 Authentication and Authorization

For API-based integrations, several options are supported; the final choice aligns with the organisation’s security policies:

In all cases:

6.3 Data Protection

6.4 Logging and Audit

6.5 Secrets Management

6.6 Infrastructure and Data Processing

7. Idempotency, Retries, and Robustness

7.1 Idempotency

To avoid duplicate processing in API-based integrations:

7.2 Retries

7.3 Correlation and Troubleshooting

8. Scheduling and Time Handling

9. Non-Functional Requirements

10. Onboarding and Configuration Checklist

11. Open Questions for Integrating Teams

To tailor this integration to a specific environment, the following aspects are typically clarified during onboarding:

  1. Authentication model (API-based)
    • Preferred mechanism for Sunbay calling integration APIs: API key or OAuth2 client credentials.
  2. Network topology
    • Whether access will be over the public internet with IP allowlisting, or via VPN/private connectivity.
  3. Data model specifics
    • Which fields (e.g. in SAP or other accounting systems) map to InvoiceId, InvoiceNumber, etc.
  4. Eligibility rules
    • Conditions that determine that an invoice is eligible for collection (e.g. status, days overdue, dunning level, manual flags).
  5. Volume expectations
    • Expected daily and peak volumes of invoices to be collected.
    • Specific time windows (e.g. end-of-month) with significantly higher volume.
  6. Error handling preferences
    • Behaviour when an API or sheet-based source contains a mixture of valid and invalid invoices:
      • Ignore invalid entries and continue, or fail the batch/page and require correction and retry.

Clarifying these points allows Sunbay to finalise configuration and proceed with implementation and end-to-end testing of collection flows.