Schreiben Sie uns
Suchen

Postkartenversand über die API / Programmierschnittstelle

Voraussetzung für den Versand von Postkarten über die EchtPost API ist, dass Sie neben einem API-Schlüssel eine Vorlage innerhalb Ihres EchtPost-Accounts angelegt haben. Aufgrund der unterschiedlichen Zeichenbeschränkungen je nach Schriftart ist es nicht möglich, eine Postkarte mit einem jeweils individuellen Text über die API anzulegen.

Den API-Schlüssel erstellen Sie innerhalb Ihres EchtPost-Accounts in den Account Einstellungen (Zahnrad rechts oben) und dann unter API-Schlüssel zum Datenaustausch.

Eine Vorlage für Ihre Postkarte erstellen Sie, indem Sie beginnen eine Postkarte zu schreiben. Dort wählen Sie zunächst ein Motiv aus und schreiben einen Grußtext auf die Rückseite. Um eine individuelle Anrede für die jeweils angeschriebenen Empfänger einzusetzen, können Sie {Anrede} als Platzhalter einsetzen. Dieser Platzhalter wird bei der Erstellung der Karte gegen Ihre voreingestellte Anrede (Account Einstellungen > Sprache, Standard-Anrede & mehr) ersetzt. Im Anschluss speichern Sie die Vorlage.

postkarte-als-vorlage-speichern.png 271.38 KB


Über Vorlagen verwalten in den Account Einstellungen finden Sie im Anschluss die individuelle ID Ihrer erstellten Vorlage.
vorlage-id-fuer-die-postkarten-api.png 27.56 KB



Für den Versand der Vorlage benötigen Sie dann nur einen Aufruf per JSON an unseren POST-Endpunkt. Sie haben dabei verschiedene Möglichkeiten, um den oder die Empfänger zu setzen. Die Grundstruktur des JSON-Aufrufs und ein Beispiel in Ruby on Rails sieht dabei exemplarisch wie folgt aus:

json_hash = {
  apikey: 'your-echtpost-api-key',
  card: {
    template_id: integer_id,
    deliver_at: '2024-03-15',
    notification_type: 'before_send', # optional; can also be 'after_send'
    notification_date: '2024-03-10', # optional
    notification_email: 'your-email@example.com', # optional
    contacts_attributes: [
      {
        company_name: 'EchtPost',
        first: 'Anne',
        name: 'Buch',
        street: 'Marktstr 10 - Gebäude E8',
        zip: '50968,
        city: 'Köln',
        country_code: 'DE'
      }
    ]
  }
}

RestClient::Request.execute(
  url: 'https://api.echtpost.de/v1/cards',
  method: :post,
  headers: { content_type: 'application/json' },
  payload: json_hash.to_json,
  verify_ssl: false
)

Versand an einen Kontakt mit Kontaktdaten

Um die Kontaktdaten direkt zu übergeben und den Kontakt nicht zuerst im EchtPost Adressbuch anlegen zu müssen, nutzen Sie den contact_attributes Parameter, wie in dem vorangehenden Beispiel. 

Versand an einen bestehenden EchtPost-Empfänger

Wenn der gewünschte Empfänger bereits als Kontakt in Ihrem EchtPost-Account angelegt ist, dann können Sie die ID des Kontaktes über den Parameter contact_id übergeben. Der Parameter contacts_attributes entfällt in diesem Fall. 

Versand an mehrere bestehende EchtPost-Empfänger

Um die Vorlage an mehrere Empfänger aus dem EchtPost Adressbuch zu versenden, übergeben Sie einen Array mit den gewünschten Contact IDs über den Parameter contact_ids. Der Parameter contacts_attributes entfällt in diesem Fall. 

Versand an die Kontakte einer Gruppe

Über den Parameter group_id können Sie die ID einer EchtPost Empfängergruppe übergeben. Die ID dieser Gruppe finden Sie in der URL, sobald Sie die Gruppe auf der Empfänger-Übersicht anwählen. 


Fehlercodes


400 Bad Request: Wenn falsche Daten wie eine ungültige template_id, contact_id oä übergeben werden, antwortet die API mit 400 BadRequest und gibt weitere Details zurück, wie zB das fehlerhafte Feld im Contact.

402 Payment Required: Wenn das vorhandene Guthaben in Ihrem Account nicht ausreicht, antwortet die API mit 402 Payment Required.