TenderNed: API naar HubSpot
Overzicht van welke informatie we uit de TenderNed Aankondigingen-API (TNS) en XML-API halen, en hoe die wordt weggeschreven naar HubSpot (Deals, Companies, Contacts).
Aankondigingen-API (TNS)
Publieke, onbeveiligde API: GET /papi/tenderned-rs-tns/v2/publicaties. Gebruikt voor discovery en eerste vulling van de cache.
| API-veld | Omschrijving | HubSpot (Deal / Company / Contact) | Opmerkingen |
|---|---|---|---|
| publicatieId | Uniek publicatienummer | synchub_publicatie_id | Unieke koppeling; gebruikt voor ID link. |
| aanbestedingNaam | Titel van de aanbesteding | dealname | — |
| opdrachtBeschrijving | Korte omschrijving | synchub_beschrijving | — |
| publicatieDatum | Datum van publicatie | synchub_publicatiedatum | — |
| sluitingsDatum | Uiterste inschrijfdatum | closedate, synchub_sluitingsdatum | — |
| typePublicatie | AAO, AAW, REC, AGO, GUN, VBE, MAC, VAK, VOR, INT | synchub_publicatietype | — |
| opdrachtgeverNaam | Naam aanbestedende dienst | Company: name | — |
| procedure | OPE, BEP, ONH, enz. | synchub_procedure | — |
| typeOpdracht | L=Leveringen, D=Diensten, W=Werken | synchub_type_opdracht | — |
| europees | Europese aanbesteding | synchub_europees | — |
| link.href | URL naar de aankondiging | synchub_tenderned_url | — |
| isVroegtijdigeBeeindiging | Vroegtijdige beëindiging (VBE) | synchub_is_ingetrokken | VBE → synchub_is_ingetrokken = true |
| tsenderNaam / tsenderLink | Extern platform (bv. Mercell, Negometrix) | synchub_tsender_naam, synchub_tsender_link | — |
XML-API (UBL/E-Forms)
Beveiligde API: GET /papi/tenderned-rs-tns/v2/publicaties/{id}/public-xml. Bevat uitgebreide gegevens (opdrachtgever, contact, CPV, percelen, gunning, intrekking).
| XML-pad / element | Omschrijving | HubSpot (Deal / Company / Contact) |
|---|---|---|
| ProcurementProject.Name | Naam opdracht | dealname |
| ProcurementProject.Description | Uitgebreide omschrijving | description |
| MainCommodityClassification, AdditionalCommodityClassification | CPV-codes (hoofd + aanvullend) | synchub_cpv_code |
| TenderingProcess.ProcedureCode | Procedurecode | synchub_procedure |
| ProcurementProject.ProcurementTypeCode | Type opdracht (Supplies/Services/Works) | synchub_type_opdracht |
| RequestedTenderTotal.EstimatedOverallContractAmount | Geschatte contractwaarde | amount, synchub_geschatte_waarde |
| TenderSubmissionDeadlinePeriod.EndDate | Sluitingsdatum inschrijving | closedate, synchub_sluitingsdatum |
| ContractingParty.Party / EformsExtension.Organizations.Company | Opdrachtgever: naam, KvK, website, adres | Company: name, synchub_kvk, domain, address |
| Company.Contact (in extensions) | Contactpersoon: naam, e-mail, telefoon | Contact: firstname, lastname, email, phone, company |
| ProcurementProjectLot | Percelen (aantal, details in notitie) | synchub_percelen_aantal, note |
| BuyerTypeCode (in extensions) | Type aanbestedende dienst | synchub_type_aanbestedende_dienst |
| ChangedNoticeIdentifier, ReasonDescription | Rectificatie: reden, originele publicatie | synchub_rectificatie |
| SettledContract.Tenderer, AwardDate | Gunning: gegund aan, datum | synchub_gegund_aan, synchub_gunningsdatum |
| CancellationDate, CancellationReasonCode | Intrekking: datum, reden | synchub_is_ingetrokken, synchub_intrekkingsdatum, synchub_intrekkingsreden |
| RegulatoryDomain | Europees (RegulatoryDomain 2014) | synchub_europees |
HubSpot objecten
Per aanbesteding worden een Deal, één Company (opdrachtgever) en optioneel één of meer Contacts aangemaakt en gekoppeld.
| Object | Velden | Doel |
|---|---|---|
| Deal | dealname, description, amount, closedate, dealstage, pipeline + alle synchub_* | Eén Deal per originele aanbesteding. Update-publicaties (REC, AAW, INT) werken de originele Deal bij. |
| Company | name, synchub_kvk, domain, address (street, city, postalCode, country) | Eén Company per opdrachtgever; deduplicatie op synchub_kvk. |
| Contact | firstname, lastname, email, phone, company (opdrachtgever) | Contactpersonen bij de opdrachtgever; gekoppeld aan Deal en Company. |
Filteropties
Via de HubSpot Settings UI kun je precies bepalen welke aanbestedingen worden gesynchroniseerd. Combineer meerdere filters voor gerichte resultaten.
CPV Codes zoeken
De CPV Code Picker maakt het eenvoudig om relevante aanbestedingscategorieën te vinden en selecteren.
- Zoek op trefwoord (bijv. 'software', 'IT', 'bouw') of CPV code
- Filter op divisie (45=Bouw, 72=IT, 79=Zakelijke diensten, etc.)
- Voeg codes handmatig toe voor specifieke behoeften
- Gebruik kortere codes (bijv. '72') voor bredere matching
Type publicatie
Filter op het type TenderNed-publicatie. Dit zijn de ruwe publicatietypes van de TenderNed API. Standaard worden alle types gesynchroniseerd.
| Code | Omschrijving | Verwerking |
|---|---|---|
| AAO | Aankondiging van een opdracht — de originele publicatie | Nieuwe Deal met alle details (contactpersonen, opdrachtgever, deadline, waarde). |
| AAW | Aankondiging van een wijziging — wijziging op een bestaande aanbesteding | Werkt de originele Deal bij. Verwijst via XML naar het originele publicatie-ID. |
| REC | Rectificatie — correctie op een eerdere publicatie | Werkt de originele Deal bij met de gecorrigeerde informatie. |
| AGO | Aankondiging gegunde opdracht — bericht dat de opdracht is gegund | Aparte Deal met gunningsinformatie (winnaar, gunningsdatum). Verwijst niet terug naar origineel AAO. |
| GUN | Gunning — formele gunningsbeslissing | Werkt de originele Deal bij als er een verwijzing is, anders aparte Deal. |
| VBE | Vroegtijdige beëindiging — de aanbesteding is voortijdig gestopt | Aparte Deal. Markeert dat de aanbesteding is beëindigd. |
| MAC | Marktconsultatie — verkenning voorafgaand aan een aanbesteding | Nieuwe Deal. Geeft aan dat er een verkenningsfase loopt. |
| VAK | Vooraankondiging — eerste melding van een geplande aanbesteding | Nieuwe Deal. Vroege indicator van een komende aanbesteding. |
| VOR | Vooraankondiging — variant vooraankondiging | Nieuwe Deal. Alternatieve vorm van vooraankondiging. |
| INT | Intrekking — aanbesteding is ingetrokken | Werkt de originele Deal bij. Markeert de aanbesteding als ingetrokken. |
Update-publicaties (REC, AAW, INT) verwijzen via de TenderNed XML naar het originele publicatie-ID. SyncHub zoekt de originele Deal op en werkt deze bij — er worden geen dubbele Deals aangemaakt. Als het origineel nog niet in de database staat, wordt het automatisch opgehaald van TenderNed.
Categorieën
- Originele publicaties (nieuwe Deal): AAO, AGO, MAC, VAK, VOR, VBE
- Update-publicaties (bijwerking bestaande Deal): REC, AAW, INT
Sluitingsdatum filter
Bepaal of alleen aanbestedingen met een toekomstige sluitingsdatum worden gesynchroniseerd.
| Optie | Omschrijving |
|---|---|
| Alleen toekomstige | Alleen aanbestedingen waarvan de sluitingsdatum nog niet is verstreken (aanbevolen) |
| Alle aanbestedingen | Ook aanbestedingen met verstreken sluitingsdatum synchroniseren |
Let op: bestaande deals in HubSpot worden altijd bijgewerkt, ook als de filters veranderen. Dit zorgt ervoor dat wijzigingen (zoals rectificaties of intrekkingen) correct worden doorgevoerd.
Publicatiedatum filter
Beperk de import tot aanbestedingen die gepubliceerd zijn op of na een specifieke datum. Dit is handig als u bijvoorbeeld alleen recente aanbestedingen wilt importeren.
Selecteer een datum in het datumveld. Alleen aanbestedingen die op of na deze datum zijn gepubliceerd op TenderNed worden geïmporteerd. Laat het veld leeg om geen publicatiedatum-filter toe te passen.
Voorbeeld: als u 2024-01-01 selecteert, worden alleen aanbestedingen van 2024 en later geïmporteerd.
Dit filter werkt alleen voor nieuwe imports. Eerder gesynchroniseerde deals worden altijd bijgewerkt, ongeacht de publicatiedatum.
Updates & notities
Updates op TenderNed-publicaties (REC, AAW, INT) worden vertaald naar gerichte wijzigingen op de bestaande HubSpot-Deal. De Deal fase wordt hierbij nooit automatisch gewijzigd.
- Diff-based notes: alleen gewijzigde velden worden getoond in een notitie op de Deal.
- Altijd een link naar de TenderNed-detailpagina van de update-publicatie.
- Rectificaties (REC) tonen reden + impact, geen volledige beschrijving.
- Origineel automatisch ophalen: als een update verwijst naar een origineel dat niet in de database staat (bijv. van vóór 2020), wordt het automatisch opgehaald van TenderNed.
- Geen dubbele Deals: update-publicaties worden altijd gekoppeld aan de bestaande originele Deal.
- Deal fase behouden: bij updates wordt de Deal fase nooit automatisch gewijzigd — je behoudt volledige controle.
Volledige property mapping
Hieronder staat exact welke TenderNed-informatie naar welke HubSpot-eigenschap wordt geschreven. Alle TenderNed-specifieke eigenschappen staan in de groep "SyncHub - TenderNed". Alleen dealname, amount, closedate, pipeline en dealstage zijn standaard HubSpot-eigenschappen.
Standaard HubSpot-eigenschappen
| TenderNed Bron | HubSpot Property | Type | Mogelijke waarden / formaat |
|---|---|---|---|
| Titel aanbesteding | dealname | Tekst | Vrije tekst |
| Geschatte waarde | amount | Getal | Bedrag in EUR |
| Sluitingsdatum | closedate | Datum | YYYY-MM-DD |
| — | pipeline | Pipeline | SyncHub TenderNed |
| Publicatietype | dealstage | Deal fase | Alleen bij aanmaak ingesteld |
Custom eigenschappen (SyncHub - TenderNed)
| TenderNed Bron | HubSpot Property | Type | Mogelijke waarden / formaat |
|---|---|---|---|
| Publicatie ID | synchub_publicatie_id | Tekst (uniek) | bijv. TN-2025-12345 |
| URL op TenderNed | synchub_tenderned_url | Tekst | Link naar aankondiging |
| Omschrijving opdracht | synchub_beschrijving | Tekstveld (groot) | Vrije tekst |
| CPV-codes | synchub_cpv_code | Tekst | bijv. 72000000, 45000000 |
| Publicatiedatum | synchub_publicatiedatum | Datum | YYYY-MM-DD |
| Sluitingsdatum | synchub_sluitingsdatum | Datum+tijd | ISO 8601 |
| Type publicatie | synchub_publicatietype | Multi-select | AAO, AAW, REC, AGO, GUN, VBE, MAC, VAK, VOR, INT |
| Type opdracht | synchub_type_opdracht | Select | Werken, Leveringen, Diensten |
| Afgeleid van CPV-codes | synchub_aard_opdracht | Select | Bouwopdracht, Civiel, Installatie, Sloop, Onderhoud, Advies, ICT, Facilitair, Andere |
| Proceduretype | synchub_procedure | Select | Openbaar, Niet-openbaar, Dialoog, Innovatie, Onderhandeling, Onderhandeling zonder |
| Type aanbestedende dienst | synchub_type_aanbestedende_dienst | Select | Rijksoverheid, Lokale overheid, Publiekrechtelijk, Speciale sector, Europees, Andere |
| Is gerectificeerd | synchub_rectificatie | Checkbox | Ja / Nee |
| Naam gegunde partij | synchub_gegund_aan | Tekst | Vrije tekst |
| Datum gunning | synchub_gunningsdatum | Datum | YYYY-MM-DD |
| Is ingetrokken | synchub_is_ingetrokken | Checkbox | Ja / Nee |
| Datum intrekking | synchub_intrekkingsdatum | Datum | YYYY-MM-DD |
| Reden intrekking | synchub_intrekkingsreden | Tekstveld (groot) | Vrije tekst |
| Geschatte contractwaarde | synchub_geschatte_waarde | Getal | Bedrag in EUR |
| Europese aanbesteding | synchub_europees | Checkbox | Ja / Nee |
| Digitale inschrijving | synchub_digitaal | Checkbox | Ja / Nee |
| Extern platform | synchub_tsender_naam | Tekst | bijv. Mercell, Negometrix |
| Link extern platform | synchub_tsender_link | Tekst | URL |
| Aantal percelen | synchub_percelen_aantal | Getal | 0, 1, 2, ... |
| Verwachte startdatum | synchub_aanvang_opdracht | Datum | YYYY-MM-DD |
| Verwachte einddatum | synchub_voltooiing_opdracht | Datum | YYYY-MM-DD |
Enumeraties worden automatisch gemapt: TenderNed codes (bijv. OPE, BEP, W, D) worden vertaald naar leesbare Nederlandse labels in HubSpot.
Datums worden geconverteerd van het TenderNed formaat naar YYYY-MM-DD (datum) of ISO 8601 (datum+tijd).
Type Publicatie is een multi-select: bij een update (bijv. REC op AAO) worden beide types getoond (AAO;REC), zodat je de geschiedenis van een aanbesteding kunt zien.
De sluitingsdatum wordt zowel in de standaard closedate als in synchub_sluitingsdatum gezet. Dit zorgt ervoor dat de pipeline-weergave in HubSpot correct werkt.
Alle custom eigenschappen worden aangemaakt in de groep 'SyncHub - TenderNed'. Bij de eerste synchronisatie worden ontbrekende eigenschappen automatisch aangemaakt.
Aantekeningen (Notes)
Bij elke synchronisatie worden gestructureerde aantekeningen (notes) aangemaakt en gekoppeld aan de Deal, Company en Contact(en).
Bij aanmaak van een Deal
Bij de eerste synchronisatie van een aanbesteding wordt een uitgebreide aantekening aangemaakt met alle beschikbare informatie:
- Volledige beschrijving van de opdracht
- Overzicht van percelen (nummer, titel, beschrijving, CPV-codes per perceel)
- Gegevens opdrachtgever (naam, adres, KvK, website)
- Contactpersonen (naam, e-mail, telefoon)
- Extern platform (naam + link, bijv. Mercell)
Bij updates (REC, AAW, INT, GUN)
Bij een update-publicatie wordt een update-aantekening aangemaakt met bovenaan een opvallend alert-blok en daaronder de gewijzigde velden (diff-based):
- Opvallend alert-blok: gele banner met type update en datum — direct zichtbaar in de HubSpot tijdlijn (bijv. "Rectificatie ontvangen voor deze aanbesteding")
- Type update (bijv. Rectificatie, Aankondiging van een wijziging)
- Datum van de update-publicatie
- Reden van wijziging (indien beschikbaar)
- Gewijzigde velden met oude → nieuwe waarde
- Voorbeeld: "Sluitingsdatum: 15-03-2025 → 22-03-2025"
Bundeling van updates
Meerdere updates op dezelfde dag worden gebundeld in één aantekening, gescheiden door een horizontale lijn. Dit voorkomt een overvolle tijdlijn.
- Nieuwe Deal → uitgebreide aantekening met beschrijving, percelen, opdrachtgever, contactpersonen
- Update-publicatie → diff-aantekening met alleen gewijzigde velden (oud → nieuw)
- Meerdere updates op dezelfde dag → gebundeld in 1 aantekening
- Aantekeningen worden gekoppeld aan Deal, Company en Contact(en)
Verwerkingsflow
SyncHub verwerkt aanbestedingen in een slimme pipeline. 1) Discovery (dagelijks): nieuwe aanbestedingen worden opgehaald en toegevoegd aan de centrale database. 2) JSON-verrijking (continu): alle tenders krijgen CPV-codes via de snelle publieke API. 3) Slimme XML-verrijking (continu): alleen tenders die matchen met actieve klantfilters worden volledig verrijkt via de XML-API — dit bespaart ~96% aan API-calls. 4) Tenant-sync: matchende tenders worden als Deal + Company + Contact(s) naar HubSpot geschreven. Fallback: bij nieuwe filterwijzigingen worden ontbrekende XML-details on-demand opgehaald.