API-Dokumentation

Erste Schritte

1. Melden Sie sich an oder legen Sie ein Konto an und erzeugen Sie unter API-Zugang einen Schlüssel.
2. Schicken Sie den Schlüssel bei jedem Aufruf im Header „Authorization“ mit.
3. Legen Sie eine Anfrage an. Sie gehört sofort Ihrem Konto und erscheint auch unter „Meine Anfragen“.

Basis-URL

https://mailingbid.com/api/v1

Anmeldung

Authorization: Bearer mb_live_…

Format

JSON (UTF-8), Datumswerte als JJJJ-MM-TT

Grenzen

120 Aufrufe pro Minute und Schlüssel; 60 neue Anfragen pro Stunde und Konto

Behandeln Sie den Schlüssel wie ein Passwort: nur auf dem Server, nie im Browser oder in einer App. Ein Schlüssel lässt sich jederzeit widerrufen.

Endpunkte

Anfrage anlegen

Pflicht sind mindestens ein Land mit Menge (tranches) und mindestens ein Teil (positions). Alles andere ist optional und lässt sich später ergänzen.

Ohne Angabe gelten dieselben Vorgaben wie im Formular: Titel aus dem Auflieferdatum, Angebotsfrist in 5 Werktagen, Leistungen Produktion, Lettershop und Auflieferung. Kontaktdaten und Sprache kommen aus Ihrem Konto. Die Antwort ist 201 mit der gespeicherten Anfrage.

Für Anfragen über die API gelten unsere AGB.

curl -X POST https://mailingbid.com/api/v1/requests \
  -H "Authorization: Bearer $MAILINGBID_API_KEY" \
  -H "Content-Type: application/json" \
  --data @anfrage.json

Beispiel: anfrage.json

{
  "title": "Frühjahrsmailing 2027",
  "defaultPostingDate": "2027-03-12",
  "tranches": [
    {
      "country": "AT",
      "quantity": 30000
    },
    {
      "country": "CZ",
      "quantity": 10000,
      "postProduct": "standard"
    }
  ],
  "positions": [
    {
      "type": "envelope",
      "format": "C6/5",
      "paperGsm": 80,
      "spec": {
        "window": "left"
      }
    },
    {
      "type": "letter",
      "format": "A4",
      "colors": "4/4",
      "spec": {
        "fold": "wrap_dl",
        "personalization": "address"
      }
    },
    {
      "type": "payment_slip",
      "spec": {
        "standards": {
          "AT": "at_sepa",
          "CZ": "cz_pk_a"
        },
        "execution": "attached"
      }
    }
  ],
  "serviceScope": [
    "production",
    "lettershop",
    "posting"
  ],
  "contractingParty": "agency",
  "onBehalfOf": "Organisation A",
  "iso27001Required": false
}

Antwort (gekürzt)

{
  "request": {
    "id": 123,
    "status": "received",
    "title": "…",
    "offerDeadline": "2027-01-15",
    "serviceScope": ["production", "lettershop", "posting"],
    "url": "https://mailingbid.com/anfragen/123",
    …
  },
  "tranches": [{ "id": 401, "country": "AT", "quantity": 30000, … }],
  "positions": [{ "id": 901, "type": "envelope", "format": "C6/5", … }],
  "offers": [],
  "files": [],
  "decision": null,
  "details": { "editable": true, "lock": null }
}

Felder der Anfrage

Länder und Mengen (tranches)

Teile des Mailings (positions)

Zahlscheine haben kein Format, Papier oder Farbe: Das folgt aus dem Standard des Landes. Der Server lehnt solche Angaben ab.

Anfragen und Angebote abrufen

GET /api/v1/requests liefert alle Anfragen Ihres Kontos mit Status und Zahl der veröffentlichten Angebote. GET /api/v1/requests/ID liefert eine Anfrage vollständig.

curl https://mailingbid.com/api/v1/requests \
  -H "Authorization: Bearer $MAILINGBID_API_KEY"

Angebote erscheinen, sobald wir sie veröffentlicht haben: mit Anbieter, abgedeckten Teilen und Ländern, der Ausführung je Teil (positionConformity: wie angefragt oder abweichend, mit Beschreibung), Preiszeilen nach Art (Gesamtpreis ohne Porto oder Preis je Teil, Porto getrennt), der Portoaussage (postageStatement: separate oder not_offered), Gesamtsumme, Gültigkeit, Preisgleitklausel, Zahlungsbedingungen, Inklusivleistungen und Anmerkungen. Bei älteren Angeboten sind positionConformity und postageStatement null. Beträge sind in Cent; EUR und CZK werden nie zusammengezählt. Mehrere Angebote eines Anbieters sind Varianten: variantLabel nennt den Namen der Alternative (null beim ersten Angebot), variantGroup ist bei allen Angeboten desselben Anbieters dieselbe Zahl (null bei von uns erfassten Angeboten). Bei der Auswahl ist je Anbieter nur eine Variante möglich.

Status einer Anfrage:

• received – eingegangen
• in_progress – in Bearbeitung, Angebote werden eingeholt
• offers_available – Angebote liegen vor
• closed – entschieden

Die Auswahl der Angebote ist verbindlich und erfolgt deshalb im Browser unter der Anfrage-URL (Feld url).

Details ergänzen

PATCH /api/v1/requests/ID nimmt dieselben Felder wie beim Anlegen, alle optional: Fehlt ein Feld, bleibt es unverändert; null leert es.

curl -X PATCH https://mailingbid.com/api/v1/requests/123 \
  -H "Authorization: Bearer $MAILINGBID_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ "paymentTerms": "30", "notes": "…" }'

tranches und positions werden als Ganzes ersetzt und immer zusammen geschickt. Bestehende Einträge behalten ihre id: Schicken Sie die id mit, um einen Eintrag zu ändern; ohne id entsteht ein neuer, fehlende werden gelöscht.

Ändern geht, solange die Anfrage eingegangen oder in Bearbeitung ist und noch kein Angebot veröffentlicht wurde; danach antwortet der Server mit 409 details_locked.

Erlaubte Werte

Dieselben Werte liefert GET /api/v1/catalogue als JSON.

colors

4/0, 4/4, 1/0, 1/1, special

serviceScope

production, lettershop, posting

contractingParty

ngo, agency, company

postProduct

standard, sponsoring_mail (AT), info_mail, euro_mail, postaim (IE), charity_acquisition_post (IE), other

spec.standards

at_sepa (AT), at_donation (AT), de_donation (DE), de_sepa (DE), cz_pk_a (CZ), sk_poukaz (SK), qr_only

country

AT, CZ, SK, DE, PL, BE, BG, HR, CY, DK, EE, FI, FR, GR, HU, IE, IT, LV, LT, LU, MT, NL, PT, RO, SI, ES, SE, IS, LI, NO, CH

Fehler

Fehler kommen mit passendem HTTP-Status und einem stabilen Code in data.code. Bei validation_error steht unter data.issues, welches Feld nicht passt.

{
  "statusCode": 400,
  "statusMessage": "…",
  "data": {
    "code": "validation_error",
    "issues": { "fieldErrors": { "tranches": ["…"] } }
  }
}

Gut zu wissen

• Dateien (z. B. Druckdaten-Muster) laden Sie über die Detailseite der Anfrage im Browser hoch.
• Die verbindliche Auswahl eines Angebots treffen Sie im Browser.
• Die Eingangsbestätigung jeder Anfrage geht an die E-Mail-Adresse Ihres Kontos, auch wenn Sie eine andere Kontaktadresse angeben.
• Anbieter sehen bis zur Vergabe weder Ihren Namen noch Ihre Organisation oder Kontaktdaten.

Lieber ohne Programmierung? Nutzen Sie das Anfrageformular.