Architecture

REST API

The FS-CD Adapter provides a REST API for synchronous operations with SAP FS-CD.

While asynchronous event-driven data transfer ensures consistency across systems, the REST API supports data retrieval and synchronous operations when needed.

The Spring FscdAdapterRestController implements the API and provides endpoints for:

  • Insurance Objects: Create, update and retrieve insurance objects representing policies, claims, and commissions in SAP FS-CD.

  • Documents: Create and retrieve documents (accounting records) associated with insurance objects.

  • Business Locks: Create, retrieve, update, and delete business locks on insurance objects to control payment processing in FS-CD.

  • SEPA Mandates: Create and retrieve SEPA payment mandates associated with insurance objects.

  • Account Information: Query account balances and dunning information for business partners and insurance objects.

  • Change Policyholder: Transfer open items from an old to a new policyholder in SAP FS-CD.

The REST API is documented using OpenAPI Specification 3 (OAS3) and can be queried at {adapter-base-url}/v3/api-docs or at the path configured via property springdoc.api-docs.path (/rest/openapi in the reference implementation).

Response Format and Error Handling

All endpoints use JSON for request and response payloads.

All response payloads are wrapped in a Result<T> object which allows immediate error feedback without hidden retry mechanisms or caching.

A Result<T> object consists of the following fields:

  • data: The requested data (for successful GET requests) or null

  • messages: List of error messages. An empty list indicates a successful operation.

Example Response:

{
  "data": [{
    "reference": {
      "partnerNo":"100000082",
      "referenceNo": "10011",
      "type": "RESERVE-RES"
    },
    "businessObjectNo": "10011",
    "description": "Claim Reserve"
  }],
  "messages": []
}

HTTP Status Codes

The API uses standard HTTP status codes:

200 OK

Request successful, response contains data or confirmation.

400 Bad Request

Validation error or invalid request parameters.

500 Internal Server Error

SAP communication failures or other unexpected errors, check logs for details.

REST API Client

In addition, the module de.faktorzehn..fscd-adapter:fscd-adapter-extapi-client provides a java client FscdAdapterClient to consume the REST API in a type-safe manner without manually constructing HTTP requests.

The client can be auto-configured using FscdAdapterClientAutoConfiguration of module de.faktorzehn..fscd-adapter:fscd-adapter-autoconfigure.