====== XML-RPC: Einzel-Aufträge ======

  * Namen der Services
    * **hibiscus.xmlrpc.sepaueberweisung** Für den Zugriff auf SEPA-Überweisungen
    * **hibiscus.xmlrpc.sepalastschrift** Für den Zugriff auf SEPA-Lastschriften

Die Funktionen für Überweisungen und Lastschriften sind identisch, lediglich die Service-Namen unterscheiden sich.

===== Schlüssel-Namen =====

^ Bezeichnung      ^ Beschreibung                           ^
| konto            | ID des Kontos                          |
| termin           | Ausführungstermin im Format dd.mm.yyyy |
| blz              | BIC des Gegenkontos                    |
| kontonummer      | IBAN des Gegenkontos                   |
| name             | Inhaber-Name des Gegenkontos           |
| betrag           | Betrag des Auftrages im Locale-spezifischen Format des Systems  |
| verwendungszweck | Verwendungszweck (Array)               |
| ausgefuehrt      | Auftragsstatus (true/false)            |


Für SEPA-Überweisungen existieren zusätzlich noch die folgenden Schlüssel-Namen:

^ Bezeichnung      ^ Beschreibung                                                  ^
| endtoendid       | Ende-zu-Ende Referenz                                         |
| pmtinfid         | Payment-Information ID (erscheint als KREF im Kontoauszug)    |
| purposecode      | SEPA Purpose Code                                             |

Für SEPA-Lastschriften existieren zusätzlich noch die folgenden Schlüssel-Namen:

^ Bezeichnung      ^ Beschreibung                                                  ^
| endtoendid       | Ende-zu-Ende Referenz                                         |
| pmtinfid         | Payment-Information ID (erscheint als KREF im Kontoauszug)    |
| purposecode      | SEPA Purpose Code                                             |
| mandateid        | Mandats-Referenz                                              |
| creditorid       | Gläubiger-Identifikation                                      |
| sigdate          | Unterschriftsdatum des Mandats im Format dd.mm.yyyy           |
| sequencetype     | Sequenz-Typ (FRST,RCUR,FNAL,OOFF)                             |
| sepatype         | Lastschrift-Art (CORE,COR1,B2B)                               |
| targetdate       | Fälligkeitsdatum im Format dd.mm.yyyy (Vorlaufzeit beachten!) |

Generell gilt bei SEPA-Aufträgen: Nur eine Zeile Verwendungszweck mit maximal 140 Zeichen.

===== Zeichensatz =====

Es ist zu beachten, dass die Zeichenketten insbesondere Namen und Verwendungszwecke im ISO-8859-1 Zeichensatz übermittelt werden. UTF-8 Umlaute werden z.B. abgelehnt.  
In PHP kann UTF-8 mittels utf8_decode umgewandelt werden.

===== Verfügbare Funktionen =====


==== Liste der Schlüsselnamen ermitteln ====

<code java>
public Map<String,String> createParams() throws RemoteException;
</code>

  * Name der Funktion: **createParams**
  * Liste der Parameter <keine>
  * Rückgabe-Wert: **struct** Ein leeres Struct, welches lediglich die o.g. Schlüssel, jedoch noch keine Werte enthält. Das Struct kann als Vorlage für neue Aufträge verwendet werden


==== Liste der Aufträge ermitteln ====

<code java>
public List<Map> find(String text, String von, String bis) throws RemoteException;
</code>

  * Name der Funktion: **find**
  * Liste der Parameter
    - **String** Suchbegriff (darf leer sein)
    - **String** Start-Datum des Termins im Format "dd.mm.yyyy" oder "yyyy-mm-dd" (darf leer sein)
    - **String** End-Datum des Termins im Format "dd.mm.yyyy" oder "yyyy-mm-dd" (darf leer sein)
  * Rückgabe-Werte: **array<struct>** (Liste mit "struct"-Elementen) \\ Liste der gefundenen Aufträge. Jedes Element der Liste enthält einen Auftrag in Form eines Struct mit den o.g. Schlüsseln


=== Code-Beispiele ===

== Java ==

<code java>
String[] params = new String[]{"test",
                               "01.01.2009",
                               "31.12.2011"
                              };
Object[] l = (Object[]) client.execute("hibiscus.xmlrpc.sepaueberweisung.find",params);
// Object[] l = (Object[]) client.execute("hibiscus.xmlrpc.sepalastschrift.find",params);

for (Object o:l)
{
  System.out.println(o);
}
</code>


== PHP ==

<code php>

$params = array(new xmlrpcval("test","string"),
                new xmlrpcval("01.01.2009","string"),
                new xmlrpcval("31.12.2011","string"));

$msg = new xmlrpcmsg("hibiscus.xmlrpc.sepaueberweisung.find",$params);
// $msg = new xmlrpcmsg("hibiscus.xmlrpc.sepalastschrift.find",$params);

$response = $client->send($msg);

$value = $response->value();
 
for ($i=0;$i<$value->arraySize();$i++)
{
  $job = $value->arrayMem($i);
  print("ID            : ".$job->structMem("id")->scalarVal()."\n");
  print("Quellkonto ID : ".$job->structMem("konto")->scalarVal()."\n");
  print("Termin        : ".$job->structMem("termin")->scalarVal()."\n");
  print("Ausgeführt    : ".$job->structMem("ausgefuehrt")->scalarVal()."\n");
  print("Name          : ".$job->structMem("name")->scalarVal()."\n");
  print("IBAN          : ".$job->structMem("kontonummer")->scalarVal()."\n");
  print("BIC           : ".$job->structMem("blz")->scalarVal()."\n");
  print("Betrag        : ".$job->structMem("betrag")->scalarVal()."\n");

  $zweck = $job->structMem("verwendungszweck");
  for ($k=0;$k<$zweck->arraySize();$k++)
  {
    $line = $zweck->arrayMem($k);
    print("  ".$line->scalarVal()."\n");
  }
  print("\n");
}
</code>



==== Liste der Aufträge ermitteln (veraltet) ====

| **deprecated** Diese Funktion existiert aus Gründen der Abwärtskompatibilität weiterhin. \\ Verwende künftig jedoch bitte die Funktion **[[develop:xmlrpc:einzelauftrag#liste_der_auftraege_ermitteln|find]]** mit dem "struct"-Parameter - die neue Funktion liefert zudem detailliertere Rückgabe-Werte. |

<code java>
public String[] list() throws RemoteException;
</code>

  * Name der Funktion: **list**
  * Verwendung: Liefert eine Liste aller Aufträge
  * Liste der Parameter: <keine>
  * Rückgabe-Werte: **array<string>** (Liste mit "String"-Elementen) \\ Liste der gefundenen Aufträge. Die Werte in jeder Zeile sind durch Doppelpunkte getrennt.\\ \\ Aufbau der Zeilen <code><konto_id>:<iban>:<bic>:<name>:<zweck>:<leer>:<betrag></code>


=== Code-Beispiele ===

== Java ==

<code java>
Object[] list = (Object[]) client.execute("hibiscus.xmlrpc.sepaueberweisung.list",(Object[])null);
// Object[] list = (Object[]) client.execute("hibiscus.xmlrpc.sepalastschrift.list",(Object[])null);
for (Object o:list)
{
  System.out.println(o);
}
</code>


== PHP ==

<code php>
$msg = new xmlrpcmsg("hibiscus.xmlrpc.sepaueberweisung.list");
// $msg = new xmlrpcmsg("hibiscus.xmlrpc.sepalastschrift.list");
$response = $client->send($msg);
$value = $response->value();

for ($i=0;$i<$value->arraySize();$i++)
{
  print($value->arrayMem($i)->scalarVal()."\n");
}
</code>


==== Auftrag anlegen ====

<code java>
public String create(Map auftrag) throws RemoteException;
</code>

  * Name der Funktion: **create**
  * Liste der Parameter
    - **struct** Struct mit den Eigenschaften des Auftrages. Als Schlüssel sind die o.g. Schlüssel-Namen zu verwenden.
  * Rückgabe-Wert
    * bei [[develop:xmlrpc#null-support_aktivieren_deaktivieren|xmlrpc.supports.null]]=true: **OK** = return NULL, **FEHLER** = return Fehlertext
    * bei [[develop:xmlrpc#null-support_aktivieren_deaktivieren|xmlrpc.supports.null]]=false: **OK** = return ID, **FEHLER** = throws Exception

Beim Anlegen einer SEPA-Überweisung wird die IBAN mit dem Schlüssel "konto" und die BIC mit dem Schlüssel "blz" übergeben.

=== Code-Beispiele ===

== Java ==

<code java>
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.util.HashMap;

Map params = new HashMap();
params.put("betrag","1,50");
params.put("termin","15.01.2011");
params.put("konto","1");
params.put("name","Max Mustermann");
params.put("blz","12345678");
params.put("kontonummer","DE1234567890");

params.put("verwendungszweck","Test");

Object result = client.execute("hibiscus.xmlrpc.sepaueberweisung.create",new Object[]{params});
// Object result = client.execute("hibiscus.xmlrpc.sepalastschrift.create",new Object[]{params});
System.out.println(result);
</code>


== PHP ==

<code php>
$params = new xmlrpcval(
  array(
    "betrag"           => new xmlrpcval("1,50","string"),
    "termin"           => new xmlrpcval("15.01.2011","string"),
    "konto"            => new xmlrpcval("1","string"),
    "name"             => new xmlrpcval("Max Mustermann","string"),
    "blz"              => new xmlrpcval("12345678","string"),
    "kontonummer"      => new xmlrpcval("DE1234567890","string"),
    "verwendungszweck" => new xmlrpcval("Test","string"),
  ),"struct");
    
$msg = new xmlrpcmsg("hibiscus.xmlrpc.sepaueberweisung.create",array($params));
// $msg = new xmlrpcmsg("hibiscus.xmlrpc.sepalastschrift.create",array($params));
$response = $client->send($msg);
print($response->value()->scalarval());
</code>


==== Auftrag anlegen (veraltet) ====

| **deprecated** Diese Funktion existiert aus Gründen der Abwärtskompatibilität weiterhin. \\ Verwende künftig jedoch bitte die Funktion **[[develop:xmlrpc:einzelauftrag#auftrag_anlegen|create]]** mit dem "struct"-Parameter - die neue Funktion bietet zudem detailliertere Parameter. |

<code java>
public String create(String kontoID, String kto, String blz, String name, String zweck, String zweck2, double betrag, String termin, String type) throws RemoteException;
</code>

  * Name der Funktion: **create**
  * Liste der Parameter
    - **String** ID des Kontos
    - **String** IBAN des Gegenkontos
    - **String** BIC des Gegenkontos
    - **String** Inhaber-Name des Gegenkontos
    - **String** Verwendungszweck (max. 140 Zeichen)
    - **String** frei lassen
    - **double** Betrag als Dezimalzahl(!)
    - **String** Ausführungstermin im Format "dd.mm.yyyy" oder "yyyy-mm-dd"
    - **String** frei lassen
  * Rückgabe-Wert
    * bei [[develop:xmlrpc#null-support_aktivieren_deaktivieren|xmlrpc.supports.null]]=true: **OK** = return NULL, **FEHLER** = return Fehlertext
    * bei [[develop:xmlrpc#null-support_aktivieren_deaktivieren|xmlrpc.supports.null]]=false: **OK** = return ID, **FEHLER** = throws Exception



=== Code-Beispiele ===

== Java ==

<code java>
Object[] params = {
  "1",              // ID des Kontos
  "DE1234567890",   // IBAN des Gegenkontos
  "12345678",       // BIC des Gegenkontos
  "Max Mustermann", // Inhaber-Name des Gegenkontos
  "Zweck",          // Verwendungszweck, maximal 140 Zeichen
  "",               // frei lassen
  1.5d,             // Betrag
  "15.01.2011",     // Ausfuehrungstermin
  "",               // frei lassen
};

Object result = client.execute("hibiscus.xmlrpc.sepaueberweisung.create",params);
// Object result = client.execute("hibiscus.xmlrpc.sepalastschrift.create",params);
System.out.println(result);
</code>


== PHP ==

<code php>
$params = array(
  new xmlrpcval("1","string"),              // ID des Kontos
  new xmlrpcval("DE1234567890","string"),   // IBAN des Gegenkontos
  new xmlrpcval("12345678","string"),       // BIC des Gegenkontos
  new xmlrpcval("Max Mustermann","string"), // Inhaber-Name des Gegenkontos
  new xmlrpcval("Zweck","string"),          // Verwendungszweck, maximal 140 Zeichen
  new xmlrpcval("","string"),               // frei lassen
  new xmlrpcval(1.5,"double"),              // Betrag (Achtung: Punkt statt Komma, da Variable vom Typ double!)
  new xmlrpcval("15.01.2011","string"),     // Ausfuehrungstermin
  new xmlrpcval("","string")                // frei lassen
);
    
$msg = new xmlrpcmsg("hibiscus.xmlrpc.sepaueberweisung.create",$params);
// $msg = new xmlrpcmsg("hibiscus.xmlrpc.sepalastschrift.create",array($params));
$response = $client->send($msg);
print($response->faultString());
print($response->value()->scalarval());
</code>


==== Auftrag löschen ====

<code java>
public String delete(String id) throws RemoteException;
</code>

  * Name der Funktion: **delete**
  * Liste der Parameter
    - **String** ID des zu löschenden Auftrages
  * Rückgabe-Wert
    * bei [[develop:xmlrpc#null-support_aktivieren_deaktivieren|xmlrpc.supports.null]]=true: **OK** = return NULL, **FEHLER** = return Fehlertext
    * bei [[develop:xmlrpc#null-support_aktivieren_deaktivieren|xmlrpc.supports.null]]=false: **OK** = return ID, **FEHLER** = throws Exception

=== Code-Beispiele ===

== Java ==

<code java>
Object result = client.execute("hibiscus.xmlrpc.sepaueberweisung.delete",new Object[]{"13"});
// Object result = client.execute("hibiscus.xmlrpc.sepalastschrift.delete",new Object[]{"13"});
System.out.println(result);
</code>


== PHP ==

<code php>
$msg = new xmlrpcmsg("hibiscus.xmlrpc.sepaueberweisung.delete",array(new xmlrpcval("13","string")));
// $msg = new xmlrpcmsg("hibiscus.xmlrpc.sepalastschrift.delete",array(new xmlrpcval("13","string")));
$response = $client->send($msg);
print($response->value()->scalarval());
</code>