Gratis setup bij jaarabonnementen

Nu inschrijven!
Plan een demo

Plaatsbeschrijvingen

Home

> API-referentie >

Eindpunten >

Plaatsbeschrijvingen

API-referentie: plaatsbeschrijving-endpoints

De API’s voor plaatsbeschrijvingen beheren gestructureerde plaatsbeschrijvingsbestanden: rapporten, kamers, kamerfoto’s, transcriptie-naar-HTML transformatie, DOCX-export en tokengebaseerde fotolevering.

Huidige endpoints

Reports

Gebruik deze groep voor plaatsbeschrijving-workflows die kamertranscripties en foto’s verzamelen, kamernotities omzetten naar nette HTML en een volledig DOCX-rapport exporteren. Beschermde AnswerPal API-endpoints maken gebruik van JWT Bearer-authenticatie met het TicketAccess-beleid en vereisen de SchedulesOfCondition-abonnementsfunctie. Tokengebaseerde fotodownloads zijn de publieke uitzondering.

  • GET /api/PlaceDescriptionReports – Bearer JWT (TicketAccess)
    Toon een lijst met rapporten voor de huidige klant. Ondersteunt paginering via pageNumber en pageSize, optionele sortering via sortBy/sortOrder, en search op adres, dossiernummer of klantnamen.
  • POST /api/PlaceDescriptionReports – Bearer JWT (TicketAccess)
    Maak een rapport voor de huidige klant en medewerker aan. Document- en onderwerpverwijzingen moeten bij de huidige klant horen.
  • GET /api/PlaceDescriptionReports/{id} – Bearer JWT (TicketAccess)
    Toon één rapport met zijn kamers geordend op sortOrder en kamer-ID.
  • PUT /api/PlaceDescriptionReports/{id} – Bearer JWT (TicketAccess)
    Werk rapportmetadata, documentreferenties, transform-topic en hero-fototoken bij.
  • DELETE /api/PlaceDescriptionReports/{id} – Bearer JWT (TicketAccess)
    Verwijder een rapport dat eigendom is van de huidige klant. Geeft 204 No Content terug als het verwijderd is.
  • GET /api/PlaceDescriptionReports/{id}/export/docx – Bearer JWT (TicketAccess)
    Genereer een DOCX-bestand op basis van de rapporttemplate. Query-opties bepalen de fotopositie en of foto’s worden opgenomen.

Rapportvoorbeelden

Rapporten tonen

GET /api/PlaceDescriptionReports?pageNumber=1&pageSize=10&search=Brussels
Authorization: Bearer {token}

200 OK
{
  "items": [
    {
      "placeDescriptionReportID": 123,
      "caseNumber": "PD-2026-001",
      "clientNames": "Example client",
      "address": "Example street 1",
      "dateCreatedUtc": "2026-06-05T09:30:00Z"
    }
  ],
  "totalCount": 1,
  "totalPages": 1
}

Rapport aanmaken

POST /api/PlaceDescriptionReports
Authorization: Bearer {token}
Content-Type: application/json

{
  "clientNames": "Example client",
  "caseNumber": "PD-2026-001",
  "description": "Move-in condition report",
  "landlords": "Example landlord",
  "tenants": "Example tenant",
  "address": "Example street 1",
  "reportDate": "2026-06-05",
  "lexiconDocumentID": 45,
  "instructionsDocumentID": 46,
  "transformTopicID": 12
}

Rapportvelden

Rapport aanmaken/bijwerken body

  • clientNames
    Optionele klantnamen, maximaal 512 tekens. Wordt opgenomen in zoekopdrachten.
  • caseNumber
    Optioneel dossier- of referentienummer, maximaal 255 tekens. Wordt als DOCX-bestandsnaam gebruikt indien ingevuld.
  • description
    Optionele vrije tekst voor rapportomschrijving. Wordt ook als DOCX-placeholder ingevuld.
  • landlords, tenants
    Optionele partijennamen, elk maximaal 512 tekens.
  • address
    Optioneel adres, maximaal 512 tekens. Komt voor in zoekopdrachten en DOCX-placeholders.
  • reportDate
    Optionele datum, gebruikt in rapportmetadata en DOCX-export.
  • lexiconDocumentID, instructionsDocumentID
    Optionele document-ID’s. Beide moeten bij de huidige klant horen. Het lexicondocument is optioneel voor transformatie; instructies worden op het rapport opgeslagen.
  • transformTopicID
    Optionele topic-ID voor transcripttransformatie. Indien niet ingevuld wordt het klanttopic met de naam Place description Room geprobeerd.
  • heroPhotoAccessToken
    Optioneel stringtoken dat verwijst naar de foto die als ‘hero image’ bij DOCX-export wordt gebruikt.

Rapport lezen/detail response

  • placeDescriptionReportID, customerID
    Rapportidentiteit en eigenaar.
  • createdByCustomerRepID, customerRepID
    Identiteit van medewerker opgeslagen bij aanmaken.
  • dateCreatedUtc, dateUpdatedUtc
    Audit-tijdstempels.
  • rooms
    Slechts in detailresponses. Bevat kamer-DTO’s geordend op sortOrder en kamer-ID.

DOCX-export query

  • photoPlacement
    Optioneel. Toegestane waarden zijn onder andere perRoom, per-room, atEnd en at-end. Standaard is perRoom.
  • includePhotos
    Optionele boolean. Standaardwaarde is true.
  • excludeHeroPhoto
    Optionele boolean. Standaard is true zodat de hero-foto niet wordt herhaald bij de kamerfoto’s.

DOCX-export

GET /api/PlaceDescriptionReports/{id}/export/docx retourneert application/vnd.openxmlformats-officedocument.wordprocessingml.document. De bestandsnaam is gebaseerd op caseNumber indien beschikbaar, anders PlaceDescription-{id}.docx.

Toegang en gedrag

Authenticatie en toegangscontrole

  • Beschermde endpoints
    Rapport-, kamer- en kamerfoto-management gebruikt TicketAccess policy en SchedulesOfCondition feature access.
  • Openbare afbeeldingslevering
    GET /api/PlaceDescriptionPhotos/{accessToken:guid} is Public. Toegang wordt gecontroleerd via het GUID-token in de URL.

Eigendom en validatie

  • Klanttoewijzing
    Alle beschermde lees- en schrijfacties zijn beperkt tot het klant-ID van de geauthenticeerde token. Ontbrekende of vreemde rapporten, kamers en foto’s geven 404 als resultaat.
  • Rapportverwijzingen
    Document-ID’s en transform-topic-ID’s moeten tot de huidige klant behoren, anders resulteert het in een 400.
  • DOCX-template
    DOCX-export geeft 404 bij een ontbrekend rapport en 500 als de serverside DOCX-template ontbreekt.

AI-transformatie

  • Promptbronnen
    Transformatie combineert topicprompt-documenten, het optionele lexicon-document, kamernaam en transcriptRaw. Topicdocumenten met SpecialTopic = All worden uitgesloten.
  • OpenAI-vereisten
    De klant moet beschikken over een OpenAI API-sleutel en een actief e-mailcompatibel model. Fotoprompts vereisen bovendien beeldinvoerondersteuning.
  • Gegenereerde output
    De gegenereerde HTML wordt opgeslagen op de kamer als transcriptHtml en wordt bij DOCX-export gebruikt indien beschikbaar.
GET /api/PlaceDescriptionReports?pageNumber=1&pageSize=10&search=Brussels
Authorization: Bearer {token}

200 OK
{
  "items": [
    {
      "placeDescriptionReportID": 123,
      "caseNumber": "PD-2026-001",
      "clientNames": "Example client",
      "address": "Example street 1",
      "dateCreatedUtc": "2026-06-05T09:30:00Z"
    }
  ],
  "totalCount": 1,
  "totalPages": 1
}
POST /api/PlaceDescriptionReports
Authorization: Bearer {token}
Content-Type: application/json

{
  "clientNames": "Voorbeeldklant",
  "caseNumber": "PD-2026-001",
  "description": "Plaatsbeschrijving bij intrede",
  "landlords": "Voorbeeldverhuurder",
  "tenants": "Voorbeeldhuurder",
  "address": "Voorbeeldstraat 1",
  "reportDate": "2026-06-05",
  "lexiconDocumentID": 45,
  "instructionsDocumentID": 46,
  "transformTopicID": 12
}
POST /api/PlaceDescriptionRooms/456/transform
Authorization: Bearer {token}
Content-Type: application/json

{
  "topicId": 12,
  "includePhotosInPrompt": true,
  "overrideModelId": 7,
  "force": true
}
POST /api/PlaceDescriptionRooms/456/photos
Authorization: Bearer {token}
Content-Type: multipart/form-data

files: kitchen-1.jpg
files: kitchen-2.webp
PUT /api/PlaceDescriptionRooms/456/photos/reorder
Authorization: Bearer {token}
Content-Type: application/json

{
  "photoIds": [901, 902, 903]
}

Kamers en transformatie

Endpoint voor kamers slaan ruwe transcriptienotities, gegenereerde HTML en volgorde per rapport op.

  • GET /api/PlaceDescriptionReports/{reportId}/rooms – Bearer JWT (TicketAccess)
    Somt kamers op voor een rapport dat eigendom is van de huidige klant. Kamers worden geordend op sortOrder, daarna op kamer-ID.
  • POST /api/PlaceDescriptionReports/{reportId}/rooms – Bearer JWT (TicketAccess)
    Voegt een kamer toe aan een rapport. Indien sortOrder ontbreekt, krijgt deze de volgende volgorde toegewezen.
  • PUT /api/PlaceDescriptionRooms/{roomId} – Bearer JWT (TicketAccess)
    Wijzigt kamernaam, volgorde en transcriptievelden.
  • DELETE /api/PlaceDescriptionRooms/{roomId} – Bearer JWT (TicketAccess)
    Verwijdert een kamer in het bezit van de huidige klant.
  • POST /api/PlaceDescriptionRooms/{roomId}/transform – Bearer JWT (TicketAccess)
    Transformeert transcriptRaw en optionele kamerfoto’s naar duidelijke semantische HTML met de OpenAI-configuratie van de klant, topicdocumenten en rapportlexicon.

Voorbeeld kamertransformatie

POST /api/PlaceDescriptionRooms/456/transform
Authorization: Bearer {token}
Content-Type: application/json

{
  "topicId": 12,
  "includePhotosInPrompt": true,
  "overrideModelId": 7,
  "force": true
}

Kamer-velden

Body voor aanmaken/wijzigen kamer

  • name
    Optionele kamernaam, maximaal 255 tekens.
  • sortOrder
    Optionele volgorde binnen het rapport. Bij aanmaak wordt automatisch de volgende volgorde toegekend als dit veld ontbreekt.
  • transcriptRaw
    Optionele rauwe transcriptie of notities. Transformatie leest deze waarde uit.
  • transcriptHtml
    Optionele HTML-transcriptie. De transformatie overschrijft dit veld met nieuw gegenereerde HTML.

Transform body

  • topicId
    Optionele override voor transform-topic. Dit topic moet van de huidige klant zijn. Indien afwezig, wordt het topic van het rapport of standaardtopic gebruikt.
  • includePhotosInPrompt
    Wanneer waar, worden kamerfoto’s toegevoegd aan de prompt voor OpenAI. Het gekozen model moet beeldinvoer ondersteunen.
  • overrideModelId
    Optionele override voor actief model. Dit model moet gedeeld zijn of eigendom van de klant, en compatibel met de e-mailgebruiksslot.
  • force
    Geaccepteerd door de DTO voor clients die een expliciete transform-flag nodig hebben. Het huidig endpoint voert transform uit bij aanroep.

Transform resultaat

  • roomId
    Getransformeerde kamer-ID.
  • transcriptHtml
    Gegenereerde HTML-uitvoer. De service instrueert het model om uitsluitend HTML te retourneren. Review-markeringen worden gemarkeerde spans.
  • lastTransformedAtUtc
    UTC-tijdstip na succesvolle transformatie.
  • modelIdUsed
    Gebruikte model-ID voor de OpenAI Responses-aanroep.

Foto's

Foto-endpoints

  • GET /api/PlaceDescriptionRooms/{roomId}/photos – Bearer JWT (TicketAccess)
    Lijst met foto’s voor een kamer. Rijen bevatten bestandsnaam, contenttype, toegangstoken, volgorde en afmetingen.
  • POST /api/PlaceDescriptionRooms/{roomId}/photos – Bearer JWT (TicketAccess)
    Upload één of meerdere kamerfoto’s als multipart form-veld files. De API accepteert JPEG-, PNG- en WebP-afbeeldingen.
  • PUT /api/PlaceDescriptionRooms/{roomId}/photos/reorder – Bearer JWT (TicketAccess)
    Vervangt de volgorde van alle foto’s in de kamer met een volledige photoIds-lijst.
  • DELETE /api/PlaceDescriptionRoomPhotos/{photoId} – Bearer JWT (TicketAccess)
    Verwijdert één kamerfoto die eigendom is van de huidige klant.
  • GET /api/PlaceDescriptionPhotos/{accessToken:guid} – Public tokenized download
    Download opgeslagen afbeeldingsbytes via het toegangstoken. De response gebruikt het opgeslagen contenttype of application/octet-stream.

Foto-velden en uploadregels

Uploadregels foto’s

  • files
    Multipart form-veld met één of meer afbeeldingsbestanden. Lege requests geven een 400-resultaat.
  • Contenttypes
    Toegestane contenttypes zijn image/jpeg, image/png en image/webp.
  • Grootte en afmetingen
    Requestlimiet: 25 MB. Elk bestand mag niet leeg zijn, maximaal 5 MB, langste zijde ≤ 2048 px, kortste zijde ≤ 768 px.
  • Volgorde
    Geüploade foto’s worden toegevoegd na de huidige hoogste sortOrder.

Foto read-response

  • placeDescriptionRoomPhotoID, placeDescriptionRoomID
    Foto- en kamer-ID.
  • fileName, contentType
    Opgeslagen bestandsnaam en MIME-type.
  • accessToken
    GUID-token voor /api/PlaceDescriptionPhotos/{accessToken:guid}.
  • sortOrder, widthPx, heightPx
    Weergave-/ordermetadata uit de geüploade afbeelding gehaald.
  • dateCreatedUtc
    Tijdstip waarop de foto werd toegevoegd.

Reorder body

  • photoIds
    Vereiste lijst met foto-ID’s. Moet exact iedere huidige foto voor de kamer bevatten; gedeeltelijke of foutieve lijsten geven 400.

Gerelateerde API’s: Documenten beheren het lexicon en instructiedocumenten, Topics beheert transformprompt-documenten, en File/Tickets beslaan de bredere supportflow buiten plaatsbeschrijvingsrapporten.

Enkel GET /api/PlaceDescriptionPhotos/{accessToken:guid} is anoniem. Alle rapport-, kamer-, fotobeheer-, transform- en exportroutes vereisen JWT Bearer-authenticatie met TicketAccess.

Het endpoint gebruikt topicId uit de request als deze is opgegeven, anders het rapport transformTopicID, anders het klanttopic met de naam Place description Room. Het topic moet toegekend zijn aan de huidige klant.

photoPlacement bepaalt of foto's per kamer of aan het einde worden weergegeven. includePhotos is standaard true en excludeHeroPhoto is standaard true.

Inhoudstafel

AnswerPal: AI-gedreven oplossingen voor klantenservice die je ondersteuning en communicatie moeiteloos versterken.

Snelle links

Contact

Voor ondersteunings-, commerciële en partnervragen kunt u mailen naar [email protected]

AnswerPal
Bisschoppenhoflaan 380
2100 Antwerpen
België

+32.36416685

BE 0862.692.858

Sociale media