commit dc14e15872f11d583a0a6d76945d28fb8c2f324a
parent c17dd7bb97171ebc8a4e7c39d4ef8bf6846de371
Author: Antoine A <>
Date: Thu, 18 Dec 2025 17:22:12 +0100
ebisync: add submit documentation
Diffstat:
5 files changed, 268 insertions(+), 8 deletions(-)
diff --git a/core/api-ebisync.rst b/core/api-ebisync.rst
@@ -0,0 +1,135 @@
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2025 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+=================
+Taler EbiSync API
+=================
+
+.. contents:: Table of Contents
+ :local:
+
+Version History
+---------------
+
+The current protocol version is ``v0``.
+
+Introduction
+------------
+
+LibEuFin EbiSync API.
+
+
+Config
+------
+
+.. http:get:: /config
+
+ Return the protocol version and configuration information about the bank.
+ This specification corresponds to ``current`` protocol being version **v11**.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ Response is a `Config`.
+
+ **Details:**
+
+ .. ts:def:: Config
+
+ interface Config {
+ // Name of the API.
+ name: "taler-ebisync";
+
+ // libtool-style representation of the Bank protocol version, see
+ // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+ // The format is "current:revision:age".
+ version: string;
+
+ // SPA display version to be used in user interfaces.
+ spa_version: string;
+ }
+
+Web UI
+------
+
+The web UI served under ``/``.
+
+Submit
+------
+
+.. http:get:: /submit
+
+ Obtains a list of the orders that can be used.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The server responds with a `ListSubmitOrders` object.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
+
+ **Details:**
+
+ .. ts:def:: ListSubmitOrders
+
+ interface ListSubmitOrders {
+ orders: SubmitOrder[];
+ }
+
+ .. ts:def:: SubmitOrder
+
+ interface SubmitOrder {
+ // EBICS order id to uniquely identify this order
+ id: string;
+
+ // EBICS order description provided by the EBICS server
+ description: string;
+ }
+
+.. http:post:: /submit
+
+ Submit an file to the EBICS server using a chosen order.
+
+ **Request:**
+
+ :formparam file: The file to submit.
+ :formparam order: The is of the EBICS order to use.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ Response is a `SubmitResponse`.
+ :http:statuscode:`400 Bad request`:
+ Input data was invalid.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid or missing credentials.
+ :http:statuscode:`403 Forbidden`:
+ Missing rights.
+ :http:statuscode:`409 Conflict`:
+ EBICS server validation error.
+ :http:statuscode:`502 Bad Gateway`:
+ EBICS server connection error.
+
+ **Details:**
+
+ .. ts:def:: SubmitResponse
+
+ interface SubmitResponse {
+ // EBICS upload order ID
+ order: string;
+ }
+\ No newline at end of file
diff --git a/core/index.rst b/core/index.rst
@@ -49,6 +49,7 @@ describe the JSON objects used in our REST APIs.
index-bank-apis
api-donau
api-observability
+ api-ebisync
.. toctree::
:hidden:
diff --git a/libeufin/ebisync-manual.rst b/libeufin/ebisync-manual.rst
@@ -101,18 +101,20 @@ Services, users, groups and file system hierarchy
The *libeufin-ebisync* package will create several system users
to compartmentalize different parts of the system:
-* ``libeufin-ebisync``: runs the EBICS fetcher.
+* ``libeufin-ebisync``: runs all LibEuFin EbiSync components.
* ``postgres``: runs the PostgreSQL database (from *postgresql* package).
The package will deploy systemd service files in
``/usr/lib/systemd/system/`` for the various components:
+* ``libeufin-ebisync-httpd.service``: http server for the Sync API.
* ``libeufin-ebisync-fetch.service``: worker daemon that retrieves files via EBICS and upload them to a destination.
-* ``libeufin-ebisync.target``: main target for EbiSYnc to be operational.
+* ``libeufin-ebisync.target``: main target for EbiSync to be operational.
The deployment creates the following key locations in the system:
* ``/etc/libeufin-ebisync/``: configuration files.
+* ``/run/libeufin-ebisync/``: contains the UNIX domain sockets for inter-process communication (IPC).
* ``/var/lib/libeufin-ebisync/``: serves as the $HOME for libeufin-ebisync and contains the EBICS authentication keys.
Database setup
@@ -239,6 +241,36 @@ The following command will finish the fetcher setup process:
$ sudo -u libeufin-ebisync libeufin-ebisync setup -c /etc/libeufin-ebisync/libeufin-ebisync.conf
+Submit source setup
+===================
+
+EbiSync API
+-----------
+
+The following snippet shows the mandatory configuration values:
+
+.. code-block:: ini
+ :caption: /etc/libeufin-ebisync/conf.d/ebisync-submit.conf
+
+ [ebisync-submit]
+ SOURCE = ebisync-api
+
+Some configuration values are sensitive and must be written to a secret configuration file that is only accessible to the ``libeufin-ebisync`` user.
+
+.. code-block:: ini
+ :caption: /etc/libeufin-ebisync/secrets/ebisync-submit.secret.conf
+
+ [ebisync-submit]
+ AUTH_METHOD = basic
+ USERNAME = admin
+ PASSWORD = password
+
+The following command will finish the fetcher setup process:
+
+.. code-block:: console
+
+ $ sudo -u libeufin-ebisync libeufin-ebisync setup -c /etc/libeufin-ebisync/libeufin-ebisync.conf
+
Fetching files
==============
@@ -292,4 +324,37 @@ The ``--transient`` flag makes the command sync only
once and return immediately afterwards. Without the flag, EbiSync
will download at the frequency specified in the configuration or when it receive real time notifications.
-The ``--debug-ebics $SAVEDIR`` flag will cause EBICS transactions steps and payloads to be stored in ``$SAVEDIR/$YYYY-MM-DD`` where ``$YYYY-MM-DD`` represents the date when the download took place. This is mostly useful for debugging.
-\ No newline at end of file
+The ``--debug-ebics $SAVEDIR`` flag will cause EBICS transactions steps and payloads to be stored in ``$SAVEDIR/$YYYY-MM-DD`` where ``$YYYY-MM-DD`` represents the date when the download took place. This is mostly useful for debugging.
+
+Submittings files
+=================
+
+If the ``ebisync-api`` source is configured, submission is triggered by using the API.
+
+Deployment
+==========
+
+Reverse Proxy Setup
+-------------------
+
+By default if ``ebisync-api`` is used as a source, the ``libeufin-ebisync-httpd`` service listens for HTTP connections
+on localhost. To make the service publicly available, a reverse
+proxy such as nginx should be used. We strongly recommend to configure nginx
+to use TLS.
+
+The ``libeufin-ebisync`` package ships with a sample configuration that can be
+enabled in nginx:
+
+.. code-block:: shell-session
+
+ # vim /etc/nginx/sites-available/libeufin-ebisync
+ < ... customize configuration ... >
+ # ln -s /etc/nginx/sites-available/libeufin-ebisync /etc/nginx/sites-enabled/libeufin-ebisync
+ # systemctl reload nginx
+
+Launching
+---------
+
+.. code-block:: console
+
+ $ sudo systemctl start taler-ebisync.target
+\ No newline at end of file
diff --git a/manpages/libeufin-ebisync.1.rst b/manpages/libeufin-ebisync.1.rst
@@ -17,7 +17,7 @@ Synopsis
[**--version**]
COMMAND [ARGS...]
-Subcommands: **dbinit**, **setup**, **fetch**, **config**
+Subcommands: **dbinit**, **setup**, **fetch**, **serve**, **config**
Description
@@ -83,8 +83,8 @@ Its options are as follows:
**-h** \| **--help**
Print short help on options.
-ebics-fetch
------------
+fetch
+-----
This subcommand fetches ISO20022 files from the bank and store them at a configured destination.
@@ -107,6 +107,24 @@ Fetches of new documents are executed at 'FREQUENCY' or any time a real-time EBI
**-h** \| **--help**
Print short help on options.
+serve
+-----
+
+This command starts the HTTP server.
+
+Its options are as follows:
+
+**-c** \| **--config** *config_file*
+ Specifies the configuration file.
+**-L** \| **--log** *LOGLEVEL*
+ Configure logging to use LOGLEVEL.
+**--check**
+ Check whether an API is in use (if it's useful to start the HTTP server). Exit with 0 if at least one API is enabled, otherwise 1.
+**--debug-ebics** *log_dir*
+ Log EBICS transactions steps and payload at log_dir.
+**-h** \| **--help**
+ Print short help on options.
+
.. include:: ../frags/common-config-cli.rst
SEE ALSO
diff --git a/manpages/libeufin-ebisync.conf.5.rst b/manpages/libeufin-ebisync.conf.5.rst
@@ -73,7 +73,7 @@ CHECKPOINT_TIME_OF_DAY
At what time HH:MM of day should ``fetch`` perform a checkpoint.
DESTINATION
- Where should the ebics file be stored? This can only be azure-blob-storage.
+ Where should the ebics file be stored? This can either be ``azure-blob-storage`` or ``none``.
AZURE_API_URL
Azure API account base url
@@ -87,6 +87,46 @@ AZURE_ACCOUNT_KEY
AZURE_COUNTAINER
Which Azure Blob Storage container to use
+SUBMIT OPTIONS
+--------------
+
+The following configuration value(s) belong to the “[ebisync-submit]” section.
+
+SOURCE
+ Where does the ebics file come from? This can either be ``ebisync-api`` or ``none``
+
+AUTH_METHOD
+ Authentication scheme for api sources, this can either be ``basic``, ``bearer`` or ``none``.
+
+USERNAME
+ User name for ``basic`` authentication scheme.
+
+PASSWORD
+ Password for ``basic`` authentication scheme.
+
+TOKEN
+ Token for ``bearer`` authentication scheme.
+
+HTTP SERVER OPTIONS
+-------------------
+
+The following configuration value(s) belong to the “[ebisync-httpd]” section.
+
+SERVE
+ This can either be ``tcp`` or ``unix``.
+
+PORT
+ Port on which the HTTP server listens, e.g. 9967.
+ Only used if ``SERVE`` is ``tcp``.
+
+BIND_TO
+ Which IP address should we bind to? E.g. ``127.0.0.1`` or ``::1``for loopback. Can also be given as a hostname.
+ Only used if ``SERVE`` is ``tcp``.
+
+UNIXPATH
+ Which unix domain path should we bind to?
+ Only used if ``SERVE`` is ``unix``.
+
DATABASE OPTIONS
----------------
