Diese Dokumentation beschreibt die Zahlen-mit-Code.com API und bietet darüber hinaus Codebeispiele in verschiedenen Programmiersprachen für eine einfache Einbindung.
Die Zahlen-mit-Code.com API ist eine REST-API, die es Entwicklern ermöglicht, den Girocode in ihre Anwendungen zu integrieren.
Auf eine erfolgreiche API
Anfrage wird der fertige QR-Code als PNG Grafik oder im „Base 64 Code“ Format zurückgeliefert.
Dieser Code lässt sich in allen gängigen
Programmiersprachen als Grafik ausgeben und so in einer beliebigen Anwendung / Rechnungssoftware auf der Rechnung / dem Zahlschein platzieren.
Die
Antworten der API sind als JSON formatiert.
Die Zahlen-mit-Code.com API wird von einem Gateway bereitgestellt, der sich unter https://zahlen-mit-code.com/api befindet.
In den
Anfragebeispielen in dieser Dokumentation verwenden wir Platzhaltervariablen wie {apiurl}, um auf die Zahlen-mit-Code.com API-URL zu verweisen, {iban} um
z.B.: auf die IBAN des Zahlungsempfängers und {user} bzw. {secret}, um auf den API user sowie das secret zu verweisen.
Nutzer der Zahlen-mit-Code.com API
können ihre privaten API-Schlüssel unter info@zahlen-mit-code.com
anfordern oder schnell und unkompliziert einen Testzugang (siehe weiter unten) erhalten.
Die von der API zurückgegebenen QR-Code Daten im „Base 64 Code“ Format können für einen einfachen Test z.B.: mit https://base64.guru/converter/decode/image in ein Bild umgewandelt und dann mit einer Banking App abgescannt werden. (Die Anführungszeichen vor und hinter dem Base 64 Code müssen hier gelöscht werden.)
{apiurl}?user={user}&secret={secret}&iban={iban}&bic={bic}&paymentrecipient={zahlungsempfaenger}&purpose={verwendungszweck}&amount={betrag}
Parameter | Beschreibung |
---|---|
apiurl | Die Zahlen-mit-Code API URL: https://zahlen-mit-code.com/api |
user | Kennung des API Nutzers, siehe API user und secret |
secret | Privater Schlüssel des API Nutzers, siehe API user und secret |
iban | IBAN des Zahlungsempfängers |
bic | BIC des Zahlungsempfängers |
paymentrecipient | Name des Zahlungsempfängers (Gültigen SEPA Zeichensatz beachten!) |
purpose | Verwendungszweck der Überweisung (Gültigen SEPA Zeichensatz beachten!) |
amount | Betrag der Überweisung in € mit Punkt als Dezimaltrennzeichen. Achtung: Beträge mit mehr als 2 Nachkommastellen werden von der API gerundet. |
imageformat | Optional: Das gewünschte Bildformat. Erlaubte Werte: "png" oder "base64". Ohne diesen Parameter wird standardmäßig Base64 zurückgegeben. |
Die Daten werden als JSON-Objekt zurückgeliefert.
Parameter | Beschreibung |
---|---|
response_code | Statuscode der Anfrage, z.B.: 200 für einen erfolgreichen Aufruf. |
response_desc | Informationen zum Aufruf bzw. zu Fehlern. |
qr_data | QR-Code als PNG im „Base 64 Code“ Format. |
https://zahlen-mit-code.com/api?user=testuserx&secret=verysecretkey&iban=DE12345678912345678912&bic=12345678912&paymentrecipient=Peter%20Muster&purpose=TEST&amount=11.51
{
"qr_data":"data:image\/png;base64,iVBORw0KGgoAAAANSUhEUgAAAbIAAAGaCAYAAABqjMZHAAAACXBIWXMAAAsTAAALEwEAmpwYAAAgAElEQVR4",
"response_code":200,
"response_desc":"QR_Data"
}
Der QR-Code wird im Erfolgsfall als PNG-Bild zurückgeliefert, nur im Fehlerfall werden Daten als JSON-Objekt zurückgeliefert:
Parameter | Beschreibung |
---|---|
response_code | Fehlercode der Anfrage, z.B.: 401 für einen fehlerhaften Aufruf. |
response_desc | Informationen zum Aufruf bzw. zu Fehlern. |
qr_data | NULL |
https://zahlen-mit-code.com/api?user=testuserx&secret=verysecretkey&iban=DE12345678912345678912&bic=12345678912&paymentrecipient=Peter%20Muster&purpose=TEST&amount=11.51&imageformat=png
{
"qr_data":null,
"response_code":401,
"response_desc":"Wrong user or secret"
}
Sie können einen API Testzugang erhalten, indem Sie hier Ihre E-Mail Adresse eingeben. User und secret werden umgehend verschickt und sind für 6 Stunden gültig. Nach Ablauf der Zugangsdaten können hier neue Daten angefordert werden.
Falls Sie Tests und Integration abgeschlossen haben und einen permanenten API Zugang benötigen, kontaktieren Sie uns bitte unter: info@zahlen-mit-code.com
$apiUrl = "{apiurl}?user={user}&secret={secret}&iban={iban}&bic={bic}&paymentrecipient={zahlungsempfaenger}&purpose=".$verwendungszweck."&amount=".$rechnungsbetrag;
$client = curl_init($apiUrl);
curl_setopt($client,CURLOPT_RETURNTRANSFER,true);
$response = curl_exec($client);
$response = json_decode($response);
if($response->response_code == 200 && $response->response_desc == "QR_Data"){
echo "<img width='280' height='280' src='$response->qr_data' alt='Bezahlcode' />";
}
curl_close($client);
using System;
using System.IO;
using System.Net.Http;
using Newtonsoft.Json.Linq;
class Program
{
static void Main()
{
// Set your API parameters
// Make sure you use imageformat=png here. If you want to use Base64 you need a Base64 decoding library
string apiUrl = "https://zahlen-mit-code.com/api?user=testuserx&secret=verysecretkey&iban=DE12345678912345678912&bic=12345678912&paymentrecipient=Peter%20Muster&purpose=TEST&amount=11.51&imageformat=png";
using (HttpClient client = new HttpClient())
{
// Perform the HTTP request
HttpResponseMessage response = client.GetAsync(apiUrl).Result;
// Check for errors
if (!response.IsSuccessStatusCode)
{
Console.WriteLine($"HTTP request failed: {response.StatusCode} - {response.ReasonPhrase}");
}
else
{
// Read the response content
byte[] responseData = response.Content.ReadAsByteArrayAsync().Result;
// Check if the content type is JSON
if (IsJson(response.Content.Headers.ContentType.MediaType))
{
// Parse JSON response
try
{
string jsonString = System.Text.Encoding.UTF8.GetString(responseData);
JObject jsonResponse = JObject.Parse(jsonString);
// Check if the response_code is set
if (jsonResponse["response_code"] != null)
{
// Handle error case
Console.WriteLine($"Error response: Code {jsonResponse["response_code"]}, Desc: {jsonResponse["response_desc"]}");
}
else
{
// Save image to a file
File.WriteAllBytes("qr_code.png", Convert.FromBase64String(jsonResponse["qr_data"].ToString()));
Console.WriteLine("Image saved to 'qr_code.png'");
}
}
catch (Exception ex)
{
Console.WriteLine($"Error parsing JSON: {ex.Message}");
}
}
else
{
// Save image directly to a file
File.WriteAllBytes("qr_code.png", responseData);
Console.WriteLine("Image saved to 'qr_code.png'");
}
}
}
}
static bool IsJson(string contentType)
{
// Simple check for JSON content type
return contentType.StartsWith("application/json", StringComparison.OrdinalIgnoreCase);
}
}
Dieser C#-Code verwendet HttpClient, um die HTTP-Anfrage zu senden, und Newtonsoft.Json, um die JSON-Antwort zu analysieren. Die Bilddaten werden direkt mit
File.WriteAllBytes in eine Datei gespeichert.
#include <iostream>
#include <fstream>
#include <string>
#include <curl/curl.h>
#include <nlohmann/json.hpp>
size_t WriteCallback(void* contents, size_t size, size_t nmemb, std::string* output) {
size_t total_size = size * nmemb;
output->append(static_cast<char*>(contents), total_size);
return total_size;
}
bool isJson(const std::string& data) {
// Simple check for JSON content type based on the first character
return data.size() > 0 && (data[0] == '{' || data[0] == '[');
}
int main() {
// Set your API parameters
// Make sure you use imageformat=png here. If you want to use Base64 you need a Base64 decoding library
std::string apiUrl = "https://zahlen-mit-code.com/api?user=testuserx&secret=verysecretkey&iban=DE12345678912345678912&bic=12345678912&paymentrecipient=Peter%20Muster&purpose=TEST&amount=11.51&imageformat=png";
// Initialize libcurl
CURL* client = curl_easy_init();
if (client) {
// Set the URL
curl_easy_setopt(client, CURLOPT_URL, apiUrl.c_str());
// Set to receive the response as a string
curl_easy_setopt(client, CURLOPT_WRITEFUNCTION, WriteCallback);
std::string response_data; // Declare response_data here
curl_easy_setopt(client, CURLOPT_WRITEDATA, &response_data);
// Perform the HTTP request
CURLcode res = curl_easy_perform(client);
// Check for errors
if (res != CURLE_OK) {
fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res));
}
else {
// Check if the content type is JSON
if (isJson(response_data)) {
// Parse JSON response
nlohmann::json jsonResponse;
try {
jsonResponse = nlohmann::json::parse(response_data);
}
catch (const nlohmann::json::parse_error& e) {
std::cerr << "Error parsing JSON: " << e.what() << std::endl;
return 1; // Exit with an error code
}
// Check if the response_code is set
if (jsonResponse.find("response_code") != jsonResponse.end()) {
// Handle error case
std::cout << "Error response: Code " << jsonResponse["response_code"] << ", Desc: " << jsonResponse["response_desc"] << std::endl;
}
else {
// Save image to a file
std::ofstream imageFile("qr_code.png", std::ios::out | std::ios::binary);
if (imageFile.is_open()) {
imageFile.write(jsonResponse["qr_data"].dump().c_str(), jsonResponse["qr_data"].dump().size());
imageFile.close();
std::cout << "Image saved to 'qr_code.png'" << std::endl;
}
else {
std::cerr << "Unable to open file for writing." << std::endl;
}
}
}
else {
// Save image directly to a file
std::ofstream imageFile("qr_code.png", std::ios::out | std::ios::binary);
if (imageFile.is_open()) {
imageFile.write(response_data.c_str(), response_data.size());
imageFile.close();
std::cout << "Image saved to 'qr_code.png'" << std::endl;
}
else {
std::cerr << "Unable to open file for writing." << std::endl;
}
}
}
// Clean up
curl_easy_cleanup(client);
}
return 0;
}
Private Sub Detailbereich_Format(Cancel As Integer, FormatCount As Integer)
Dim objRequest As Object
Dim strUrl As String
Dim blnAsync As Boolean
Dim strResponse As String
Set objRequest = CreateObject("MSXML2.XMLHTTP")
strUrl =
"{apiurl}?user={user}&secret={secret}&iban={iban}&bic={bic}&paymentrecipient={zahlungsempfaenger}&purpose=ReNr.%20" & Rechnungsnummer &
"&amount=" & Rechnungsbetrag
blnAsync = True
With objRequest
.Open "GET", strUrl, blnAsync
.setRequestHeader "Content-Type", "application/json"
.Send
'spin wheels whilst waiting for response
While objRequest.ReadyState <> 4
DoEvents
Wend
strResponse = .ResponseText
End With
strQuote = Chr$(34)
stringrepl = "{" & strQuote & "qr_data" & strQuote & ":" & strQuote & "data:image\/png;base64,"
Text64 = Replace(strResponse, stringrepl, "")
stringrepl2 = strQuote & "," & strQuote & "response_code" & strQuote & ":200," & strQuote & "response_desc" & strQuote
& ":" & strQuote & "QR_Data" & strQuote & "}"
Text64 = Replace(Text64, stringrepl2, "")
Text64 = Replace(Text64, "\", "")
Set FS = CreateObject("Scripting.FileSystemObject")
Dim strTempPath As String
strTempPath = "c:\QRZahlung\QR" & Rechnungsnummer & ".png"
If FS.FileExists(strTempPath) Then
Kill strTempPath
End If
'save byte array to temp file
Open strTempPath For Binary As #1
Put #1, 1, DecodeBase64(Text64)
Close #1
Me![BildFeld].Picture = "c:\QRZahlung\QR" & Rechnungsnummer & ".png"
End Sub
Private Function DecodeBase64(ByVal strData As String) As Byte()
'Verweis auf Microsoft XML, v3.0 notwendig
Dim objXML As Object 'MSXML2.DOMDocument
Dim objNode As Object 'MSXML2.IXMLDOMElement
'get dom document
Set objXML = CreateObject("MSXML2.DOMDocument")
'create node with type of base 64 and decode
Set objNode = objXML.createElement("b64")
objNode.DataType = "bin.base64"
objNode.Text = strData
DecodeBase64 = objNode.nodeTypedValue
'clean up
Set objNode = Nothing
Set objXML = Nothing
End Function
Nach Anlage 3 des DFÜ Abkommens sind für SEPA Zahlungen folgende Zeichen erlaubt: