Dokumentation der API

Suchprofile und Treffer für Ausschreibungen

Ihr Team beschreibt in einem Suchprofil, welche öffentlichen Ausschreibungen es sucht, und Stonewake prüft veröffentlichte Bekanntmachungen nach einer festen Regel gegen dieses Profil, ohne jedes Modell. Jeder Treffer erklärt jedes Kriterium seines Profils und nennt die Bekanntmachung, auf der er beruht. Profile und Treffer stehen über die API und Assistenten mit KI über MCP zur Verfügung. Auf der Seite Ausschreibungen im Dashboard sieht Ihr Team seine Treffer, jeden mit Link zu seiner Bekanntmachung, pflegt seine Suchprofile und lädt seine Portalexporte hoch, und eine Analystin oder ein Analyst übernimmt dort einen Treffer ins Deal Book oder legt ihn beiseite. Profile werden über das Dashboard und seine API Routen /tenders/profiles und /tenders/matches gepflegt, und nur dort werden Durchläufe gestartet, Treffer verworfen und ins Deal Book übernommen. Wer Profile pflegt, Durchläufe startet oder Treffer verwirft, braucht eine angemeldete Sitzung im Dashboard als Analystin oder Analyst eines Teams mit dem Modul Deal Book, und diese Routen gehören nicht zu /v1. Für die Übernahme ins Deal Book gilt dasselbe.

Woher die Bekanntmachungen stammen

Die Bekanntmachungen stammen aus TED, dem Tenders Electronic Daily der Europäischen Union, heute die Bekanntmachungen von Auftraggebern in Deutschland. Jede Bekanntmachung wird so gespeichert, wie TED sie veröffentlicht, und jeder Treffer verweist auf die Seite der Bekanntmachung bei TED.

Ihre Bank kann auch eigene Bekanntmachungen einbringen, aus den Exporten, die sie hochlädt (Exporte aus Vergabeportalen), und, sobald dieser Weg eingeschaltet ist, aus den Benachrichtigungen der Suchagenten ihrer eigenen Portalzugänge (Eigene Quellen). Sie bleiben bei Ihrem Team. Ihre Profile prüfen sie nach derselben Regel, und jede Bekanntmachung aus einer Benachrichtigung ist außerdem ein Treffer, den der Suchagent des Portals selbst ausgewählt hat. Ein solcher Treffer verweist auf die Seite der Bekanntmachung im Portal.

Was ein Profil verlangt

Ein Profil nennt mindestens einen CPV Code oder eine NUTS Region. Es kann jedes der übrigen Kriterien hinzufügen, und ein Kriterium, das es leer lässt, wird nicht geprüft.

CPV Codes. Ein Code umfasst jeden Code unter ihm im CPV Baum, daher umfasst 45000000 (Bauarbeiten) auch 45233120.
NUTS Regionen. Eine Region umfasst jede Region unter ihr, daher umfasst DE2 (Bayern) auch DE212 (München). Die Extra Regio Codes bezeichnen keine Region und können nicht verlangt werden.
Wertspanne in EUR, eine Untergrenze, eine Obergrenze oder beide, jeweils eingeschlossen. Verglichen wird der geschätzte Auftragswert, den die Bekanntmachung nennt, oder der Wert des vergebenen Auftrags, wenn sie keine Schätzung nennt. Ein Wert in einer anderen Währung wird nie umgerechnet.
Verfahrensarten, zum Beispiel offenes Verfahren, nicht offenes Verfahren oder Verhandlungsverfahren mit vorherigem Aufruf zum Wettbewerb.
Rechtsformen des Auftraggebers, zum Beispiel Kommunalbehörde, zentrale Regierungsbehörde oder Einrichtung des öffentlichen Rechts.
Arten der Bekanntmachung, zum Beispiel Vorinformation, Auftragsbekanntmachung oder Bekanntmachung vergebener Aufträge.
Tage bis zur Angebotsfrist, die wenigsten Tage, die noch bleiben müssen, gezählt ab dem Tag des Durchlaufs. Bekanntmachungen des Bekanntmachungsservice (oeffentlichevergabe.de) nennen keine Angebotsfrist, daher lässt ein Profil mit diesem Kriterium sie unbestimmt, nie ein Treffer.
Suchbegriffe, jeweils ein Wort oder mehrere. Ein Suchbegriff trifft den Titel oder die Beschreibung der Bekanntmachung als ganze Wörter, nachdem Umlaute ausgeschrieben und Akzente entfernt sind, daher treffen sich Türen, TÜREN und tueren gegenseitig, während Tür nie Türen trifft. Ein Suchbegriff aus mehreren Wörtern trifft nur diese Wörter in Folge. Der Treffer nennt das Feld, in dem er den Suchbegriff gefunden hat, und die Wörter so, wie die Bekanntmachung sie schreibt.

Jeder Code muss in seiner amtlichen eForms Codeliste stehen. Ein Profil mit einem Code außerhalb der Liste wird mit einem Satz abgelehnt, der den Code nennt. Jedes Profil nennt außerdem seinen Zweck, die Finanzierung eines Projekts oder die Bank als Bieterin, und ob es aktiv ist.

Wie eine Bekanntmachung geprüft wird

Jedes Kriterium, das das Profil setzt, wird für sich geprüft und hat eines von drei Ergebnissen.

Treffer. Die Bekanntmachung nennt einen Wert, den das Profil verlangt, oder einen Code unter einem verlangten.
Kein Treffer. Die Bekanntmachung nennt das Feld, und nichts, was sie nennt, passt. Bei Suchbegriffen nennt sie Titel und Beschreibung, und keines von beiden enthält einen Suchbegriff.
Unbekannt. Die Bekanntmachung nennt das Feld nicht, nennt nur einen weiteren Code (zum Beispiel nur das Land, wo das Profil eine Region verlangt), nennt einen Ort, der überall liegen kann, nennt einen Code, den keine amtliche Liste führt, oder nennt einen Wert in einer anderen Währung.

Nennt eine Bekanntmachung mehrere Codes für ein Kriterium, ist es ein Treffer, sobald einer davon trifft. Eine Bekanntmachung ist nur dann ein Treffer, wenn jedes Kriterium ihres Profils trifft. Ein einziges Kriterium ohne Treffer macht sie zu keinem Treffer, und eine Bekanntmachung mit einem unbekannten Kriterium und keinem verfehlten bleibt offen. Eine offene Bekanntmachung wird nie als Treffer gezeigt.

Treffer

Ein Profil führt einen Treffer je Vergabeverfahren. Trifft eine spätere Bekanntmachung desselben Verfahrens ebenfalls, zum Beispiel eine Berichtigung oder die Bekanntmachung vergebener Aufträge, geht der Treffer auf diese Bekanntmachung über, und ein Treffer, den Ihr Team verworfen hat, bleibt verworfen. Für jedes Kriterium nennt der Treffer das Ergebnis, das gelesene Feld der Bekanntmachung, was die Bekanntmachung dort nennt und was das Profil verlangt, und er enthält die Bekanntmachung selbst mit ihrer Seite bei TED und ihrer Datensatznummer. Eine Analystin oder ein Analyst kann einen Treffer über POST /tenders/matches/{match_id}/dismiss verwerfen, und jede Änderung wird im Prüfprotokoll festgehalten.

Jede Bekanntmachung, die nach dem Speichern eines Profils eintrifft, wird kurz nach ihrer Speicherung selbsttätig gegen das Profil geprüft, solange es aktiv ist; ein pausiertes Profil setzt dort fort, wo es stehen geblieben ist, sobald es wieder aktiv ist. Eine Analystin oder ein Analyst kann ein Profil außerdem über POST /tenders/profiles/{profile_id}/run über höchstens 31 Tage der Veröffentlichung starten, zum Beispiel um auf die Zeit vor dem Profil zurückzublicken. Der Durchlauf nennt, wie viele Bekanntmachungen er geprüft hat und für jedes Kriterium ohne Treffer, wie viele Bekanntmachungen es verfehlt oder offen gelassen haben und warum. Ein Durchlauf prüft höchstens 50.000 Bekanntmachungen und sagt es, wenn er dort endet.

Ins Deal Book

Eine Analystin oder ein Analyst übernimmt einen Treffer mit Ins Deal Book übernehmen auf der Seite Ausschreibungen ins Deal Book, oder über POST /tenders/matches/{match_id}/to-deal-book. Nur ein neuer Treffer, den jedes Kriterium seines Profils bestätigt, wird übernommen. Ebenso ein neuer Treffer, den der Suchagent Ihrer Bank auf einem Portal ausgewählt hat. Ein Treffer, den Ihr Team beiseitegelegt hat, nie, und ein zweites Übernehmen ändert nichts. Kein Modell wird bei diesem Schritt verwendet.

Zitierte Belege. Der Deal zitiert die Bekanntmachung selbst. Seine Quelle sind die Felder der Bekanntmachung, wie sie sie nennt, die Art der Bekanntmachung, Titel, Vergabestelle, geschätzter Wert oder Zuschlagswert, Angebotsfrist, Tag der Veröffentlichung und Kennung, mit dem Link zur Bekanntmachung bei TED oder auf Ihrem Portal, und sein Befund nennt die Bekanntmachung in einem festen Satz.
Phase. Eine Vorinformation ergibt Geplant, eine Auftragsbekanntmachung Ausschreibung offen und eine Bekanntmachung vergebener Aufträge Auftrag vergeben, jeweils in den Phasen Ihres Desks. Eine spätere Bekanntmachung bringt einen Deal nur voran, nie zurück.
Ein Verfahren, ein Deal. Ein Treffer zu einem Vergabeverfahren, das Ihr Deal Book schon enthält, kommt zu diesem Deal, ob ein anderes Ihrer Suchprofile es übernommen hat, eine Bekanntmachung aus Ihrem eigenen Portalbereich mit demselben Verfahren oder derselben Veröffentlichungsnummer bei TED zuerst übernommen wurde oder ein Befund der Recherche schon die Seite der Bekanntmachung bei TED zitiert. Zwei Verfahren kommen so nie auf einen Deal, und enthalten schon zwei Deals dasselbe Verfahren, wartet der Treffer, bis eine Analystin oder ein Analyst sie zusammenführt.
Auf der Seite des Deals. Ein Deal mit einer Ausschreibung zeigt eine Zeile mit der Angebotsfrist und dem Link zur Bekanntmachung.

Jede Übernahme wird im Prüfprotokoll festgehalten.

Personen

Die Zuschlagsempfänger eines Auftrags werden auf einem Treffer nie gezeigt, weder ihre Namen noch ihre Kennungen. Ein Auftraggeber wird nur genannt, wenn jede Rechtsform des Auftraggebers, die die Bekanntmachung nennt, eine öffentliche ist. Ein von einem öffentlichen Auftraggeber subventionierter Auftrag, eine Einrichtung mit besonderen oder ausschließlichen Rechten oder ein Auftragnehmer im Verteidigungsbereich kann eine natürliche Person sein, daher werden in diesen Fällen Namen und Kennungen des Auftraggebers zurückgehalten, und der Treffer sagt es. Die Beschreibung der Bekanntmachung wird nicht gezeigt. Ihr Titel wird gezeigt, außer der Auftraggeber wird zurückgehalten und der Titel wiederholt seinen Namen oder seine Kennung, und ihre Seite bei TED ist immer verlinkt.

Über die API und MCP

GET /v1/tenders/profiles, GET /v1/tenders/matches, GET /v1/tenders/matches/{match_id} und GET /v1/tenders/deals/{deal_id}, die Treffer eines Deals, liefern diese Lesesichten für Ihr eigenes Team. Die MCP Werkzeuge tender_profiles und tender_matches lesen sie für einen Assistenten mit KI, tender_matches mit deal_id für einen Deal. Keine der beiden Schnittstellen schreibt ein Profil, startet einen Durchlauf oder übernimmt einen Treffer ins Deal Book, und keine liefert, wer ein Profil angelegt oder einen Treffer verworfen hat. Ein Treffer aus dem eigenen Portalbereich trägt portal_notice statt notice und sagt in decided_by, ob ein Suchprofil oder der Suchagent des Portals ihn ausgewählt hat, und kein Portalzugang, keine Adresse und kein Schlüssel wird ausgeliefert.