taler-docs

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

api-ebisync.rst (3500B)

      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       // URN of the implementation (needed to interpret 'revision' in version).
     78       implementation: string;
     79 
     80       // SPA display version to be used in user interfaces.
     81       spa_version: string;
     82     }
     83 
     84 Web UI
     85 ------
     86 
     87 The web UI served under ``/``.
     88 
     89 Submit
     90 ------
     91 
     92 .. http:get:: /submit
     93 
     94   Obtains a list of the orders that can be used.
     95 
     96   **Response:**
     97 
     98   :http:statuscode:`200 OK`:
     99     The server responds with a `ListSubmitOrders` object.
    100   :http:statuscode:`401 Unauthorized`:
    101     Invalid or missing credentials.
    102   :http:statuscode:`403 Forbidden`:
    103     Missing rights.
    104 
    105   **Details:**
    106 
    107   .. ts:def:: ListSubmitOrders
    108 
    109     interface ListSubmitOrders {
    110       orders: SubmitOrder[];
    111     }
    112 
    113   .. ts:def:: SubmitOrder
    114 
    115     interface SubmitOrder {
    116       // EBICS order id to uniquely identify this order
    117       id: string;
    118 
    119       // EBICS order description provided by the EBICS server
    120       description: string;
    121     }
    122 
    123 .. http:post:: /submit
    124 
    125   Submit an file to the EBICS server using a chosen order.
    126 
    127   **Request:**
    128 
    129   :formparam file: The file to submit.
    130   :formparam order: The is of the EBICS order to use.
    131 
    132   **Response:**
    133 
    134   :http:statuscode:`200 OK`:
    135     Response is a `SubmitResponse`.
    136   :http:statuscode:`400 Bad request`:
    137     Input data was invalid.
    138   :http:statuscode:`401 Unauthorized`:
    139     Invalid or missing credentials.
    140   :http:statuscode:`403 Forbidden`:
    141     Missing rights.
    142   :http:statuscode:`409 Conflict`:
    143     EBICS server validation error.
    144   :http:statuscode:`502 Bad Gateway`:
    145     EBICS server connection error.
    146 
    147   **Details:**
    148 
    149   .. ts:def:: SubmitResponse
    150 
    151     interface SubmitResponse {
    152       // EBICS upload order ID
    153       order: string;
    154     }