API Dokumentation
Unsere Programmierschnittstelle ist als
RESTful Web Service umgesetzt. Für die Authentifizierung muss der
API-Schlüssel im Anfrageheader als X-ApiKey
übergeben werden. Für den Schreibzugriff muss
jedoch das entsprechende Benutzerrecht vom Administrator freigeschaltet werden. Der API-Schlüssel
steht in der Benutzerverwaltung zur Verfügung.
Es besteht nur die Möglichkeit Pressemitteilungen, Bilder, Pressemappen und Pressekontakte
einzutragen (POST) und diese auszulesen (GET). Es können nur eigene Pressemappen und Pressekontakte
ausgelesen werden (Diese Einschränkung gilt nicht für Pressemitteilungen und zugehörige Bilder).
Die HTTP-Methoden DELETE und PUT werden im Moment nicht unterstützt.
Der Server antwortet im Datenformat JSON. Wenn eine neue
Ressource erstellt wurde, befindet sich ihre URL im Location
-Header der
Antwort und der Status-Code ist 201 (Created)
. Wird eine existierende Ressource erfolgreich angefordert,
ist der Status-Code 200 (OK)
. Bei ungültigen Parametern ist der Status-Code 422 (Unprocessable Entity)
und der Contentbereich enthält detaillierte Angaben über die Ursache. Eine Übersicht der HTTP
Status-Codes ist hier zu finden.
URLs und Parameter
Die URL setzt sich aus der Hostadresse https://www.businessportal24.com
und der URI
zusammen.
URI |
Methode |
Zweck |
Parameter und Ausgabe |
/service/pressreleases |
GET |
Verzeichnis Pressemitteilungen |
Name |
Beschreibung |
Standardwert |
Beispielwerte |
languages[] |
Sprachen (als Sprachcode) |
(alle) |
de, en |
categories[] |
Kategoriecodes (siehe unten) |
(alle) |
1 |
limit |
Anzahl der Ergebnisse limitieren (max. 50) |
20 |
|
offset |
Startoffset |
0 |
|
|
/service/pressreleases |
POST |
Pressemitteilung erstellen |
Name |
Pflichtangabe |
Beschreibung |
press_release[company_id] |
ja |
Die ID der Pressemappe |
press_release[title] |
ja |
Titel |
press_release[text] |
ja |
Inhalt der Pressemitteilung. Kein HTML möglich, aber Escape-zeichen |
press_release[teaser_end] |
|
Offset des Zeichens, bei dem der Teaser endet. Startoffset ist 0, Standardwert ist 300 |
press_release[category_id] |
ja |
Kategorie (siehe unten) |
press_release[language] |
ja |
Sprachcode (siehe unten) |
pressrelease[backlink_url] |
ja |
Ihr Link zu uns |
pressrelease[contacts_list][] |
|
IDs der Pressekontakte |
|
/service/pressreleases/1 |
GET |
Daten zu einer Pressemitteilung anfordern |
Beispielausgabe:
{ "id": "1"
, "title": "Hallo Welt"
, "text": "Teaser.\r\n\r\nInhalt der Pressemitteilung...."
, "category_id": "1"
, "teaser_end": "6"
, "language": "de"
, "view_url": "https://www.businessportal24.com/de/hallo-welt.html"
, "company":
{ "view_url": "https://www.businessportal24.com/de/presskit/1/mustermann-gmbh.html"
, "name": "Mustermann GmbH"
}
}
|
/service/pressreleases/1/images |
GET |
Verzeichnis Bilder |
Name |
Standardwert |
Beschreibung |
Beispielwerte |
limit |
Anzahl der Ergebnisse limitieren (max. 50) |
20 |
|
offset |
Startoffset |
0 |
|
|
/service/pressreleases/1/images |
POST |
Bild erstellen |
Name |
Pflichtangabe |
Beschreibung |
press_release_image[title] |
ja |
Titel |
press_release_image[description] |
ja |
Beschreibung |
press_release_image[copyright] |
ja |
Urheberrechtliche Angaben |
press_release_image[check_copyright] |
ja |
Muss 1 sein, Bestätigung, dass Sie über alle erforderlichen Rechte hinsichtlich der von Ihnen in die Datenbank des Anbieters eingestellten Inhalte verfügen. |
press_release_image[is_preview_image] |
|
1, wenn das Bild für die Vorschau verwendet werden soll, ansonsten 0. 0 ist Standardwert |
press_release_image[image] |
ja |
Muss als File übergeben werden. Siehe Beispiel |
|
/service/pressreleases/1/images/1 |
GET |
Daten zu einem Bild anfordern |
Beispielausgabe:
{ "id": "1"
, "title": "Pixel"
, "description": "1x1 Pixel"
, "copyright": "creative commons license"
, "check_copyright": "1"
, "image_file_url": "https://www.businessportal24.com/de/primage/download/1"
}
|
/service/users/me/companies |
GET |
Verzeichnis Pressemappen (bzw. Firmen und Agenturen) |
Name |
Standardwert |
Beschreibung |
Beispielwerte |
limit |
Anzahl der Ergebnisse limitieren (max. 50) |
20 |
|
offset |
Startoffset |
0 |
|
|
/service/users/me/companies |
POST |
Pressemappe für eine Firma/Agentur erstellen |
Name |
Pflichtangabe |
Beschreibung |
company[name] |
ja |
Name der Firma/Agentur |
company[address] |
ja |
Adresse |
company[country_id] |
ja |
Länder-ID (siehe unten) |
company[phone] |
ja |
Telefonnummer |
company[fax] |
|
Faxnummer |
company[email] |
ja |
E-Mail Adresse |
company[website] |
ja |
URL des Internetauftritts |
company[logo] |
|
Firmenlogo, muss als Datei übergeben werden (siehe Beispiel) |
|
/service/users/me/companies/1 |
GET |
Daten zur Pressemappe anfordern |
|
/service/users/me/companies/1/contacts |
GET |
Verzeichnis Pressekontakte |
Name |
Standardwert |
Beschreibung |
Beispielwerte |
limit |
Anzahl der Ergebnisse limitieren (max. 50) |
20 |
|
offset |
Startoffset |
0 |
|
|
/service/users/me/companies/1/contacts |
POST |
Pressekontakt für eine Pressemappe erstellen |
Name |
Pflichtangabe |
Beschreibung |
contact[salutation_id] |
ja |
Anrede: 1 für Herr, 2 für Frau |
contact[title] |
|
Titel |
contact[first_name] |
ja |
Vorname |
contact[last_name] |
|
Nachname |
contact[responsibility] |
|
Zuständigkeit (Beischreibung als Text) |
contact[phone] |
|
Telefonnummer |
contact[fax] |
|
Faxnummer |
contact[email] |
ja |
E-Mail Adresse |
|
/service/users/me/companies/1/contacts/1 |
GET |
Daten zu einem Pressekontakt anfordern |
|
Programmbeispiel
Das folgende Beispiel verwendet PHP mit der Erweiterung
pecl_http. Es zeigt, wie man eine
Pressemitteilung mit Bild importiert, für die eine eigene Pressemappe und ein eigener Pressekontakt
erstellt wird.
<?php
$apiKey = '';
$host = 'https://www.businessportal24.com';
$baseUrl = $host .'/service';
$r = new HttpRequest;
$r->setOptions(array(
'headers' => array('X-ApiKey' => $apiKey)
));
//Hilfsfunktionen
//------------------------------------------------------
class HttpErrorException extends Exception {}
function processError(HttpRequest $r) {
$data = json_decode($r->getResponseBody());
if ($data == null) {
throw new Exception('invalid server response');
}
throw new HttpErrorException(strval($data), $r->getResponseCode());
}
function createResource(HttpRequest $r, $url, $params = null, $files = null) {
$r->setMethod(HttpRequest::METH_POST);
$r->setUrl($url);
if ($params !== null) {
$r->setPostFields($params);
}
if ($files !== null) {
$r->setPostFiles($files);
}
$r->send();
if ($r->getResponseCode() != 201) {
processError($r);
} else {
return $r->getResponseHeader('Location');
}
}
function readResource(HttpRequest $r, $url, $params = null) {
$r->setMethod(HttpRequest::METH_GET);
$r->setUrl($url);
$r->setQueryData($params);
$r->send();
if ($r->getResponseCode() != 200) {
processError($r);
} else {
$ret = json_decode($r->getResponseBody());
if ($ret == null) {
throw new Exception('invalid server-response');
}
return $ret;
}
}
//------------------------------------------------------
//Pressemappe erstellen
$companyUrl = createResource($r, $baseUrl.'/users/me/companies', array(
'company' => array(
'name' => 'Mustermann GmbH',
'address' => 'Musterstr. 42, 4711 Whateverest',
'country_id' => 177,
'phone' => '12345',
'email' => 'Pressekontakt@example.com',
'website' => 'www.example.com'
)
));
//Pressemappe einlesen
$company = readResource($r, $companyUrl);
//Pressekontakt erstellen
$contactUrl = createResource($r, $companyUrl.'/contacts', array(
'contact' => array(
'salutation_id' => 1,
'first_name' => 'Max',
'last_name' => 'Mustermann',
'phone' => '0815',
'email' => 'Max.Mustermann@example.com'
)
));
//Pressekontakt einlesen
$contact = readResource($r, $contactUrl);
//Pressemitteilung erstellen
$pressReleaseUrl = createResource($r, $baseUrl .'/pressreleases', array(
'press_release' => array(
'company_id' => $company->id,
'title' => 'Hallo Welt',
'text' => "Teaser.\r\n\r\nInhalt der Pressemitteilung....",
'teaser_end' => 6,
'backlink_url' => 'https://www.example.com/press-releases/hallo-welt',
'category_id' => 1,
'language' => 'de',
'contacts_list' => array($contact->id)
)
));
//Bild zur Pressemitteilung hinzufügen
createResource($r, $pressReleaseUrl .'/images',
array('press_release_image' => array(
'title' => 'Pixel',
'description' => '1x1 Pixel',
'copyright' => 'creative commons license',
'check_copyright' => true
'is_preview_image' => true
)),
array('press_release_image' => array(
'name' => 'image',
'type' => 'image/gif',
'file' => dirname(__FILE__).'/pixel.gif'
))
);
?>
Hier ein PHP Beispiel, das cURL verwendet.
$apiKey = '';
$host = 'https://www.businessportal24.com';
$baseUrl = $host .'/service';
$r = curl_init();
curl_setopt($r, CURLOPT_HTTPHEADER, array(
'X-ApiKey: '. $apiKey
));
curl_setopt($r, CURLOPT_RETURNTRANSFER, true);
curl_setopt($r,CURLINFO_HEADER_OUT,TRUE);
//Hilfsfunktionen
//------------------------------------------------------
class HttpErrorException extends Exception {}
// Quelle: https://stackoverflow.com/questions/3772096/posting-multidimensional-array-with-php-and-curl
function http_build_query_for_curl( $arrays, &$new, $prefix = null ) {
if ( is_object( $arrays ) ) {
$arrays = get_object_vars( $arrays );
}
foreach ( $arrays AS $key => $value ) {
$k = isset( $prefix ) ? $prefix . '[' . $key . ']' : $key;
if ( is_array( $value ) || is_object( $value ) ) {
http_build_query_for_curl( $value, $new, $k );
} else {
$new[$k] = $value;
}
}
}
function sendRequest ($r) {
$resp = curl_exec($r);
if (curl_errno($r) > 0) {
throw new Exception('HTTP request failed. cURL error: '. curl_errno($r));
}
return $resp;
}
function processError($response, $code) {
echo $response;
$data = json_decode($response);
if ($data == null) {
throw new Exception("Invalid server response ($code): \r\n". $response);
}
throw new HttpErrorException($response, $code);
}
function createResource($r, $url, $params = array()) {
curl_setopt($r, CURLOPT_POST, true);
curl_setopt($r, CURLOPT_HTTPGET, false);
curl_setopt($r, CURLOPT_URL, $url);
$postData = array();
http_build_query_for_curl($params, $postData);
curl_setopt($r, CURLOPT_POSTFIELDS, $postData);
curl_setopt($r, CURLOPT_HEADER, true);
$resp = sendRequest($r);
$respArray = explode("\r\n\r\n", $resp);
if(curl_getinfo($r, CURLINFO_HTTP_CODE) != 201) {
processError($resp, curl_getinfo($r, CURLINFO_HTTP_CODE));
}
$headers = is_array($respArray) && isset($respArray[count($respArray) - 2])
? explode("\r\n", $respArray[count($respArray) - 2])
: array()
;
foreach ($headers as $header)
{
$headerKV = explode(": ", $header);
if (strtolower($headerKV[0]) == 'location')
{
$location = $headerKV[1];
}
}
if (!isset($location))
{
throw new Exception('Location header is undefined');
}
return $location;
}
function readResource($r, $url) {
curl_setopt($r, CURLOPT_POST, false);
curl_setopt($r, CURLOPT_HTTPGET, true);
curl_setopt($r, CURLOPT_URL, $url);
curl_setopt($r, CURLOPT_HEADER, false);
$resp = sendRequest($r);
if(curl_getinfo($r, CURLINFO_HTTP_CODE) != 200) {
processError($resp, curl_getinfo($r, CURLINFO_HTTP_CODE));
} else {
$ret = json_decode($resp);
if ($ret == null) {
throw new Exception('invalid server-response');
}
return $ret;
}
}
//------------------------------------------------------
//Pressemappe erstellen
$companyUrl = createResource($r, $baseUrl.'/users/me/companies', array(
'company' => array(
'name' => 'Mustermann GmbH'. uniqid(),
'address' => 'Musterstr. 42, 4711 Whateverest',
'country_id' => 177,
'phone' => '12345',
'email' => 'Pressekontakt@example.com',
'website' => 'www.example.com'
)
));
//Pressemappe einlesen
$company = readResource($r, $companyUrl);
//Pressekontakt erstellen
$contactUrl = createResource($r, $companyUrl.'/contacts', array(
'contact' => array(
'salutation_id' => 1,
'first_name' => 'Max',
'last_name' => 'Mustermann',
'phone' => '0815',
'email' => 'Max.Mustermann@example.com'
)
));
//Pressekontakt einlesen
$contact = readResource($r, $contactUrl);
//Pressemitteilung erstellen
$pressReleaseUrl = createResource($r, $baseUrl .'/pressreleases', array(
'press_release' => array(
'company_id' => $company->id,
'title' => 'Hallo Welt',
'text' => "Teaser.\r\n\r\nInhalt der Pressemitteilung....",
'teaser_end' => 6,
'backlink_url' => 'https://www.example.com/press-releases/hallo-welt',
'category_id' => 1,
'language' => 'de',
'contacts_list' => array($contact->id)
)
));
//Bild zur Pressemitteilung hinzufügen
createResource($r, $pressReleaseUrl .'/images',
array('press_release_image' => array(
'title' => 'Pixel',
'description' => '1x1 Pixel',
'copyright' => 'creative commons license',
'check_copyright' => 1,
'is_preview_image' => 1,
'image' => "@". dirname(__FILE__).DIRECTORY_SEPARATOR. 'test.png;type=image/png'
))
);
curl_close($r);
Appendix
Sprachcodes
ID |
Name |
de | Deutsch |
de_CH | Deutsch (Schweiz) |
de_AT | Deutsch (Österreich) |
en | Englisch (UK / USA) |
en_IO | Englisch (British Indian Ocean Territory) |
en_CA | Englisch (Kanada) |
fr | Französisch |
fr_MG | Französisch (Madagaskar) |
es | Spanisch |
es_CL | Spanisch (Chile) |
it | Italienisch |
ro | Romänisch |
pt | Portugiesisch |
pt_BR | Portugiesisch (Brasilien) |
nl | Niederländisch |
pl | Polnisch |
tr | Türkisch |
cs | Tschechisch |
ru | Russisch |
uk | Ukrainisch |
zh | Chinesisch |
Kategorien
ID |
Name |
1 | Handel |
2 | IT |
3 | Finanzen |
4 | Reisen |
5 | Kultur |
6 | Politik |
7 | Medizin |
8 | Sport |
9 | Motor/Verkehr |
10 | Haus |
11 | Mode |
12 | Sonstiges |
Länder
ID |
Name |
1 | Afghanistan |
2 | Netherlands |
3 | Netherlands Antilles |
4 | Albania |
5 | Algeria |
6 | American Samoa |
7 | Andorra |
8 | Angola |
9 | Anguilla |
10 | Antigua and Barbuda |
11 | United Arab Emirates |
12 | Argentina |
13 | Armenia |
14 | Aruba |
15 | Australia |
16 | Azerbaijan |
17 | Bahamas |
18 | Bahrain |
19 | Bangladesh |
20 | Barbados |
21 | Belgium |
22 | Belize |
23 | Benin |
24 | Bermuda |
25 | Bhutan |
26 | Bolivia |
27 | Bosnia and Herzegovina |
28 | Botswana |
29 | Brazil |
30 | United Kingdom |
31 | Virgin Islands, British |
32 | Brunei |
33 | Bulgaria |
34 | Burkina Faso |
35 | Burundi |
36 | Cayman Islands |
37 | Chile |
38 | Cook Islands |
39 | Costa Rica |
40 | Djibouti |
41 | Dominica |
42 | Dominican Republic |
43 | Ecuador |
44 | Egypt |
45 | El Salvador |
46 | Eritrea |
47 | Spain |
48 | South Africa |
49 | Ethiopia |
50 | Falkland Islands |
51 | Fiji Islands |
52 | Philippines |
53 | Faroe Islands |
54 | Gabon |
55 | Gambia |
56 | Georgia |
57 | Ghana |
58 | Gibraltar |
59 | Grenada |
60 | Greenland |
61 | Guadeloupe |
62 | Guam |
63 | Guatemala |
64 | Guinea |
65 | Guinea-Bissau |
66 | Guyana |
67 | Haiti |
68 | Honduras |
69 | Hong Kong |
70 | Svalbard and Jan Mayen |
71 | Indonesia |
72 | India |
73 | Iraq |
74 | Iran |
75 | Ireland |
76 | Iceland |
77 | Israel |
78 | Italy |
79 | East Timor |
80 | Austria |
81 | Jamaica |
82 | Japan |
83 | Yemen |
84 | Jordan |
85 | Christmas Island |
86 | Yugoslavia |
87 | Cambodia |
88 | Cameroon |
89 | Canada |
90 | Cape Verde |
91 | Kazakstan |
92 | Kenya |
93 | Central African Republic |
94 | China |
95 | Kyrgyzstan |
96 | Kiribati |
97 | Colombia |
98 | Comoros |
99 | Congo |
100 | Congo, The Democratic Republic of the |
101 | Cocos (Keeling) Islands |
102 | North Korea |
103 | South Korea |
104 | Greece |
105 | Croatia |
106 | Cuba |
107 | Kuwait |
108 | Cyprus |
109 | Laos |
110 | Latvia |
111 | Lesotho |
112 | Lebanon |
113 | Liberia |
114 | Libyan Arab Jamahiriya |
115 | Liechtenstein |
116 | Lithuania |
117 | Luxembourg |
118 | Western Sahara |
119 | Macao |
120 | Madagascar |
121 | Macedonia |
122 | Malawi |
123 | Maldives |
124 | Malaysia |
125 | Mali |
126 | Malta |
127 | Morocco |
128 | Marshall Islands |
129 | Martinique |
130 | Mauritania |
131 | Mauritius |
132 | Mayotte |
133 | Mexico |
134 | Micronesia, Federated States of |
135 | Moldova |
136 | Monaco |
137 | Mongolia |
138 | Montserrat |
139 | Mozambique |
140 | Myanmar |
141 | Namibia |
142 | Nauru |
143 | Nepal |
144 | Nicaragua |
145 | Niger |
146 | Nigeria |
147 | Niue |
148 | Norfolk Island |
149 | Norway |
150 | Côte d’Ivoire |
151 | Oman |
152 | Pakistan |
153 | Palau |
154 | Panama |
155 | Papua New Guinea |
156 | Paraguay |
157 | Peru |
158 | Pitcairn |
159 | Northern Mariana Islands |
160 | Portugal |
161 | Puerto Rico |
162 | Poland |
163 | Equatorial Guinea |
164 | Qatar |
165 | France |
166 | French Guiana |
167 | French Polynesia |
168 | Réunion |
169 | Romania |
170 | Rwanda |
171 | Sweden |
172 | Saint Helena |
173 | Saint Kitts and Nevis |
174 | Saint Lucia |
175 | Saint Vincent and the Grenadines |
176 | Saint Pierre and Miquelon |
177 | Germany |
178 | Solomon Islands |
179 | Zambia |
180 | Samoa |
181 | San Marino |
182 | Sao Tome and Principe |
183 | Saudi Arabia |
184 | Senegal |
185 | Seychelles |
186 | Sierra Leone |
187 | Singapore |
188 | Slovakia |
189 | Slovenia |
190 | Somalia |
191 | Sri Lanka |
192 | Sudan |
193 | Finland |
194 | Suriname |
195 | Swaziland |
196 | Switzerland |
197 | Syria |
198 | Tajikistan |
199 | Taiwan |
200 | Tanzania |
201 | Denmark |
202 | Thailand |
203 | Togo |
204 | Tokelau |
205 | Tonga |
206 | Trinidad and Tobago |
207 | Chad |
208 | Czech Republic |
209 | Tunisia |
210 | Turkey |
211 | Turkmenistan |
212 | Turks and Caicos Islands |
213 | Tuvalu |
214 | Uganda |
215 | Ukraine |
216 | Hungary |
217 | Uruguay |
218 | New Caledonia |
219 | New Zealand |
220 | Uzbekistan |
221 | Belarus |
222 | Wallis and Futuna |
223 | Vanuatu |
224 | Holy See (Vatican City State) |
225 | Venezuela |
226 | Russian Federation |
227 | Vietnam |
228 | Estonia |
229 | United States |
230 | Virgin Islands, U.S. |
231 | Zimbabwe |
232 | Palestine |
233 | Antarctica |
234 | Bouvet Island |
235 | British Indian Ocean Territory |
236 | South Georgia and the South Sandwich Islands |
237 | Heard Island and McDonald Islands |
238 | French Southern territories |
239 | United States Minor Outlying Islands |