summaryrefslogtreecommitdiff
path: root/libeufin/api-nexus.rst
blob: 745182cf91bb246e598dd1c3c639df4a2da7c52a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
Nexus API
###########


HTTP API
========

Users Management
----------------

Users are the entity that access accounts.  They do not necessarily correspond
to the actual legal owner of an account.  Their main purpose in the nexus is
access management.

.. http:get:: <nexus>/users

  List users.

  **Required permission:** Administrator.

.. http:post:: <nexus>/users

  Create a new user.

  **Required permission:** Administrators.


Bank Account Management
-----------------------

.. http:get:: <nexus>/bank-accounts

  List bank accouts managed by nexus.


.. http:post:: <nexus>/bank-accounts

  List bank accouts managed by nexus.


.. http:get:: <nexus>/bank-accounts/{acctid}/history

  :query method: Method to query the bank transaction (cached, ebics, fints, ...)

  Query the transaction history of an account via the specified method.


.. http:get:: <nexus>/bank-accounts/{acctid}/payments

  List payments made with this bank account via nexus.

.. http:post:: <nexus>/bank-accounts/{acctid}/payments

  Initiate a payment.


Low-level EBICS API
-------------------

.. http:post:: <nexus>/ebics/subscribers/{id}/backup
  
  Ask the server to export the three keys, protected with passphrase.

  .. ts:def:: NexusEbicsBackupRequest
    
    interface NexusEbicsBackupRequest {
      passphrase: string;
    }


  .. ts:def:: NexusEbicsBackupResponse

    interface NexusEbicsBackupResponse {
      
      // The three passphrase-protected private keys in the PKCS#8 format

      authBlob: string; // base64
      encBlob: string; // base64
      sigBlob: string; // base64
      hostID: string;
      userID: string;
      partnerID: string;
      ebicsURL: string;
    }


.. http:post:: <nexus>/ebics/subscribers/{id}/restoreBackup
  
  Ask the server to restore the keys.  Always creates a NEW
  "{id}" account, and fails if it exists already.

  .. ts:def:: NexusEbicsRestoreBackupRequest

    interface NexusEbicsRestoreBackupRequest {
      
      // passphrase to decrypt the keys
      passphrase: string;

      // The three passphrase-protected private keys in the PKCS#8 format
      authBlob: string; // base64
      encBlob: string; // base64
      sigBlob: string; // base64
      hostID: string;
      userID: string;
      partnerID: string;
      ebicsURL: string;
    }

  .. ts:def:: NexusEbicsCreateSubscriber

.. http:post:: <nexus>/ebics/subscribers

  Create a new subscriber.  Create keys for the subscriber that
  will be used in later operations.

  .. ts:def:: NexusEbicsCreateSubscriber

    interface NexusEbicsCreateSubscriber {
      ebicsUrl: string;
      hostID: string;
      partnerID: string;
      userID: string;
      systemID: string?
    }


.. http:get:: <nexus>/ebics/subscribers

  List EBICS subscribers managed by nexus.


.. http:get:: <nexus>/ebics/subscribers/{id}

  Get details about an EBICS subscriber.

.. http:get:: <nexus>/ebics/subscriber/{id}/keyletter

  Get a formatted letter (mark-down) to confirm keys via ordinary mail.

.. http:post:: <nexus>/ebics/subscriber/{id}/sendIni

  Send INI message to the EBICS host.

.. http:post:: <nexus>/ebics/subscriber/{id}/sendHia

  Send HIA message to the EBICS host.

.. http:get:: <nexus>/ebics/subscriber/{id}/sendHtd

  Send HTD message to the EBICS host.

.. http:post:: <nexus>/ebics/subscriber/{id}/sync

  Synchronize with the EBICS server.  Sends the HPB message
  and updates the bank's keys.

.. http:post:: <nexus>/ebics/subscriber/{id}/sendEbicsOrder

  Sends an arbitrary bank-technical EBICS order.  Can be an upload
  order or a download order.

  .. ts:def:: NexusEbicsSendOrderRequest::

    interface NexusEbicsSendOrderRequest {
      // Bank-technical order type, such as C54 (query transactions)
      // or CCC (initiate payment)
      orderType: string;

      // Generic order parameters, such as a date range for querying
      // an account's transaction history.
      orderParams: OrderParams

      // Body (XML, MT940 or whatever the bank server wants)
      // of the order type, if it is an upload order
      orderMessage: string;
    }


.. http:post:: <nexus>/ebics/subscriber/{id}/ebicsOrders

  .. note::

    This one should be implemented last and specified better!

  Return a list of previously sent ebics messages together with their status.
  This allows retrying sending a message, if there was a crash during sending
  the message.