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

  * Namen der Services
    * **hibiscus.xmlrpc.sepasammelüberweisung** Für den Zugriff auf SEPA-Sammel-Überweisungen
    * **hibiscus.xmlrpc.sepasammellastschrift** Für den Zugriff auf SEPA-Sammel-Lastschriften

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

===== Schlüssel-Namen des Auftragskopfes =====

^ Bezeichnung      ^ Beschreibung                               ^
| name             | Bezeichnung des Sammelauftrages (Freitext) |
| konto            | ID des Kontos                              |
| termin           | Ausführungstermin im Format dd.mm.yyyy     |
| batchbook        | Legt fest, ob die Buchungen als Einzelaufträge in den Kontoauszügen erscheinen sollen (Werte: null/true/false) |
| buchungen        | Liste der enthaltenden Buchungen (Array)   |
| ||
| **Schlüssel-Namen der enthaltenen Buchungen** ||
| betrag           | Betrag der Buchung im Locale-spezifischen Format des Systems |
| blz              | BIC des Gegenkontos                        |
| kontonummer      | IBAN des Gegenkontos                       |
| name             | Inhaber-Name des Gegenkontos               |
| verwendungszweck | Verwendungszweck (Array)                   |

Für den Auftragskopf bei SEPA-Sammelüberweisungen existieren zusätzlich noch die folgenden Schlüssel-Namen:

^ Bezeichnung      ^ Beschreibung                                                  ^
| pmtinfid         | Payment-Information ID (erscheint als KREF im Kontoauszug)    |

Für die enthaltenen Buchungen bei SEPA-Sammelüberweisungen existieren zusätzlich noch die folgenden Schlüssel-Namen:

^ Bezeichnung      ^ Beschreibung                                                  ^
| endtoendid       | Ende-zu-Ende Referenz                                         |
| purposecode      | SEPA Purpose Code                                             |


Für den Auftragskopf bei SEPA-Sammellastschriften existieren zusätzlich noch die folgenden Schlüssel-Namen:

^ Bezeichnung      ^ Beschreibung                                                  ^
| sequencetype     | Sequenz-Typ (FRST,RCUR,FNAL,OOFF)                             |
| sepatype         | Lastschrift-Art (CORE,COR1,B2B)                               |
| targetdate       | Fälligkeitsdatum im Format dd.mm.yyyy (Vorlaufzeit beachten!) |
| pmtinfid         | Payment-Information ID (erscheint als KREF im Kontoauszug)    |

Für die enthaltenen Buchungen bei SEPA-Sammellastschriften existieren zusätzlich noch die folgenden Schlüssel-Namen:

^ Bezeichnung      ^ Beschreibung                                                  ^
| endtoendid       | Ende-zu-Ende Referenz                                         |
| purposecode      | SEPA Purpose Code                                             |
| mandateid        | Mandats-Referenz                                              |
| creditorid       | Gläubiger-Identifikation                                      |
| sigdate          | Unterschriftsdatum des Mandats im Format dd.mm.yyyy           |

Generell gilt bei SEPA-Aufträgen: Nur eine Zeile Verwendungszweck mit maximal 140 Zeichen.
Beachte bitte ausserdem, dass ggf. eine extra Vereinbarung mit der Bank nötig ist, um den Parameter "batchbook" mit den Wert "false" (für Einzelbuchung in den Kontoauszügen) verwenden zu dürfen. Normalerweise sollte hier kein Wert eingetragen werden. Das Batchbook-Flag wird dann nicht an die Bank übertragen. Diese entscheidet dann nach ihren Standardvorgaben, wie die Buchungen im Kontoauszug erscheinen.

===== 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



==== Auftrag anlegen ====

<code java>
public String create(Map<String,String> 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

=== Code-Beispiele ===

== Java ==

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

Map params = new HashMap();
params.put("name","Test");
params.put("termin","15.01.2011");
params.put("konto","1");
        
List buchungen = new ArrayList();

for (....) {
  Map buchung = new HashMap();
  buchung.put("betrag","1,50");
  buchung.put("name","Max Mustermann");
  buchung.put("blz","12345678");
  buchung.put("kontonummer","DE1234567890");

  buchung.put("verwendungszweck","Test");
  buchungen.add(buchung);
}
params.put("buchungen",buchungen);
        
Object result = client.execute("hibiscus.xmlrpc.sepasammelueberweisung.create",new Object[]{params});
// Object result = client.execute("hibiscus.xmlrpc.sepasammellastschrift.create",new Object[]{params});
System.out.println(result);
</code>

== PHP ==

<code php>
$buchungen = array();

for (...)
{
  $buchung = new xmlrpcval(array(
               "betrag"           => new xmlrpcval("1,50","string"),
               "name"             => new xmlrpcval("Max Mustermann","string"),
               "blz"              => new xmlrpcval("12345678","string"),
               "kontonummer"      => new xmlrpcval("DE1234567890","string"),
               "verwendungszweck" => new xmlrpcval("Test","string")
             ),"struct");
  array_push($buchungen,$buchung);
}

$params = new xmlrpcval(
  array(
    "name"      => new xmlrpcval("Test","string"),
    "termin"    => new xmlrpcval("15.01.2011","string"),
    "konto"     => new xmlrpcval("1","string"),
    "buchungen" => new xmlrpcval($buchungen,"array"),
  ),"struct");
    
$msg = new xmlrpcmsg("hibiscus.xmlrpc.sepasammelueberweisung.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.sepasammelueberweisung.delete",new Object[]{"13"});
// Object result = client.execute("hibiscus.xmlrpc.sepasammellastschrift.delete",new Object[]{"13"});
System.out.println(result);
</code>


== PHP ==

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