taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

api-ebisync.rst (3383B)

      1 ..
      2   This file is part of GNU TALER.
      3 
      4   Copyright (C) 2025 Taler Systems SA
      5 
      6   TALER is free software; you can redistribute it and/or modify it under the
      7   terms of the GNU Affero General Public License as published by the Free Software
      8   Foundation; either version 2.1, or (at your option) any later version.
      9 
     10   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
     11   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     12   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
     13 
     14   You should have received a copy of the GNU Affero General Public License along with
     15   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     16 
     17 =========================
     18 Taler EbiSync RESTful API
     19 =========================
     20 
     21 .. contents:: Table of Contents
     22   :local:
     23 
     24 Version History
     25 ---------------
     26 
     27 The current protocol version is **v0**.
     28 
     29 * Nothing depends on the ebisync API at this point.
     30 
     31 **Version history:**
     32 
     33 * ``v0``: Initial version.
     34 
     35 **Upcoming versions:**
     36 
     37 * None anticipated.
     38 
     39 **Ideas for future version:**
     40 
     41 * ``vXXX``: marker for features not yet targeted for release
     42 
     43 
     44 
     45 Introduction
     46 ------------
     47 
     48 LibEuFin EbiSync API.
     49 
     50 
     51 Config
     52 ------
     53 
     54 .. http:get:: /config
     55 
     56   Return the protocol version and configuration information about the bank.
     57   This specification corresponds to ``current`` protocol being version **v0**.
     58 
     59   **Response:**
     60 
     61   :http:statuscode:`200 OK`:
     62     Response is a `Config`.
     63 
     64   **Details:**
     65 
     66   .. ts:def:: Config
     67 
     68     interface Config {
     69       // Name of the API.
     70       name: "taler-ebisync";
     71 
     72       // libtool-style representation of the Bank protocol version, see
     73       // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
     74       // The format is "current:revision:age".
     75       version: string;
     76 
     77       // SPA display version to be used in user interfaces.
     78       spa_version: string;
     79     }
     80 
     81 Web UI
     82 ------
     83 
     84 The web UI served under ``/``.
     85 
     86 Submit
     87 ------
     88 
     89 .. http:get:: /submit
     90 
     91   Obtains a list of the orders that can be used.
     92 
     93   **Response:**
     94 
     95   :http:statuscode:`200 OK`:
     96     The server responds with a `ListSubmitOrders` object.
     97   :http:statuscode:`401 Unauthorized`:
     98     Invalid or missing credentials.
     99   :http:statuscode:`403 Forbidden`:
    100     Missing rights.
    101 
    102   **Details:**
    103 
    104   .. ts:def:: ListSubmitOrders
    105 
    106     interface ListSubmitOrders {
    107       orders: SubmitOrder[];
    108     }
    109 
    110   .. ts:def:: SubmitOrder
    111 
    112     interface SubmitOrder {
    113       // EBICS order id to uniquely identify this order
    114       id: string;
    115 
    116       // EBICS order description provided by the EBICS server
    117       description: string;
    118     }
    119 
    120 .. http:post:: /submit
    121 
    122   Submit an file to the EBICS server using a chosen order.
    123 
    124   **Request:**
    125 
    126   :formparam file: The file to submit.
    127   :formparam order: The is of the EBICS order to use.
    128 
    129   **Response:**
    130 
    131   :http:statuscode:`200 OK`:
    132     Response is a `SubmitResponse`.
    133   :http:statuscode:`400 Bad request`:
    134     Input data was invalid.
    135   :http:statuscode:`401 Unauthorized`:
    136     Invalid or missing credentials.
    137   :http:statuscode:`403 Forbidden`:
    138     Missing rights.
    139   :http:statuscode:`409 Conflict`:
    140     EBICS server validation error.
    141   :http:statuscode:`502 Bad Gateway`:
    142     EBICS server connection error.
    143 
    144   **Details:**
    145 
    146   .. ts:def:: SubmitResponse
    147 
    148     interface SubmitResponse {
    149       // EBICS upload order ID
    150       order: string;
    151     }