Dokumentace API

Začínáme

1. Přihlaste se nebo si založte účet a vytvořte klíč v sekci Přístup k API.
2. Klíč posílejte při každém volání v hlavičce „Authorization“.
3. Založte poptávku. Hned patří Vašemu účtu a objeví se i v sekci „Moje poptávky“.

Základní URL

https://mailingbid.com/api/v1

Přihlášení

Authorization: Bearer mb_live_…

Formát

JSON (UTF-8), data ve tvaru RRRR-MM-DD

Limity

120 volání za minutu na klíč; 60 nových poptávek za hodinu na účet

Zacházejte s klíčem jako s heslem: jen na serveru, nikdy v prohlížeči ani v aplikaci. Klíč lze kdykoli zrušit.

Endpointy

Založení poptávky

Povinná je alespoň jedna země s množstvím (tranches) a alespoň jeden díl (positions). Vše ostatní je nepovinné a lze to doplnit později.

Bez údajů platí stejné výchozí hodnoty jako ve formuláři: název podle data podání, lhůta pro nabídky za 5 pracovních dní, služby výroba, lettershop a podání na poště. Kontaktní údaje a jazyk se převezmou z Vašeho účtu. Odpověď je 201 s uloženou poptávkou.

Pro poptávky zadané přes API platí naše VOP.

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

Příklad: anfrage.json

{
  "title": "Jarní mailing 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": "Organizace A",
  "iso27001Required": false
}

Odpověď (zkráceně)

{
  "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 }
}

Pole poptávky

Země a množství (tranches)

Díly mailingu (positions)

Poštovní poukázky nemají formát, papír ani barevnost: ty vyplývají ze standardu země. Server takové údaje odmítne.

Stažení poptávek a nabídek

GET /api/v1/requests vrátí všechny poptávky Vašeho účtu se stavem a počtem zveřejněných nabídek. GET /api/v1/requests/ID vrátí jednu poptávku celou.

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

Nabídky se objeví, jakmile je zveřejníme: s dodavatelem, pokrytými díly a zeměmi, provedením jednotlivých dílů (positionConformity: jak bylo poptáno, nebo s odchylkou a jejím popisem), cenovými řádky podle druhu (celková cena bez poštovného, nebo cena za každý díl; poštovné zvlášť), prohlášením o poštovném (postageStatement: separate, nebo not_offered), celkovou částkou, platností, cenovou doložkou, platebními podmínkami, tím, co je v ceně, a poznámkami. U starších nabídek jsou positionConformity a postageStatement null. Částky jsou v haléřích nebo centech; EUR a CZK se nikdy nesčítají. Více nabídek jednoho dodavatele jsou varianty: variantLabel obsahuje název alternativy (u první nabídky null), variantGroup je u všech nabídek téhož dodavatele stejné číslo (u nabídek, které zadáváme sami, null). Při výběru lze od každého dodavatele zvolit jen jednu variantu.

Stav poptávky:

• received – přijata
• in_progress – zpracovává se, nabídky se získávají
• offers_available – nabídky jsou k dispozici
• closed – rozhodnuto

Výběr nabídek je závazný, proto probíhá v prohlížeči na adrese poptávky (pole url).

Doplnění podrobností

PATCH /api/v1/requests/ID přijímá stejná pole jako založení, všechna nepovinná: chybějící pole zůstane beze změny, null ho vymaže.

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 a positions se nahrazují jako celek a posílají se vždy spolu. Stávající položky si ponechají své id: pošlete id, chcete-li položku změnit; bez id vznikne nová, chybějící se smažou.

Měnit lze, dokud je poptávka přijata nebo se zpracovává a není zveřejněna žádná nabídka; potom server odpoví 409 details_locked.

Povolené hodnoty

Stejné hodnoty vrací GET /api/v1/catalogue ve formátu 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

Chyby

Chyby přicházejí s odpovídajícím stavem HTTP a stabilním kódem v data.code. U validation_error je v data.issues uvedeno, které pole nesedí.

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

Dobré vědět

• Soubory (např. ukázky tiskových dat) nahrajete v prohlížeči na stránce s podrobnostmi poptávky.
• Závazný výběr nabídky provedete v prohlížeči.
• Potvrzení o přijetí každé poptávky chodí na e-mail Vašeho účtu, i když uvedete jinou kontaktní adresu.
• Dodavatelé do zadání zakázky neuvidí Vaše jméno, organizaci ani kontaktní údaje.

Raději bez programování? Použijte formulář poptávky.