# Annonser och synkronisering Synkronisera bostadsannonser och redigera de innehållsfält som stöds. ## REST-operationer och nyckelbehörigheter | Uppgift | Nyckelbehörigheter | Börja här | | --- | --- | --- | | Läs publicerade och opublicerade annonser; synkronisera annonser | `read:properties`; `write:properties` för motsvarande ändring | `GET /api/v1/landlord/listings`, `GET /api/v1/landlord/listings/changes`, `PATCH /api/v1/landlord/listings/{unitId}/content`, `POST /api/v1/landlord/listings/{unitId}/media/uploads`, `POST /api/v1/landlord/listings/{unitId}/media/uploads/{uploadId}/complete`, `PATCH /api/v1/landlord/listings/{unitId}/media`, `PATCH /api/v1/landlord/listings/{unitId}/publication` | ## Läs in hela annonsbeståndet och återspela ändringar Vid fullständig annonssynkronisering bevarar du `syncCursor` från **första bootstrap-sidan** oförändrad tills alla bootstrap-sidor tillämpats på en tillfällig datamängd. Följ bootstrap-flödets `nextCursor` genom alla sidor; börja först därefter läsa `/api/v1/landlord/listings/changes` från den bevarade första cursorn. Tillämpa varje ändringssida atomiskt med dess `nextCursor`; fortsätt medan `hasMore=true`. Ersätt föregående cache först när hela bootstrap-inläsningen och den inledande ändringsåterspelningen lyckats. Webhooks väcker ändringsläsaren; periodisk polling fångar missade notifieringar. ## Ändra en befintlig annons namn eller lägenhetstext Använd ett lägenhets-ID som företagets annonsflöde returnerat. Med `write:properties` skickar du `PATCH /api/v1/landlord/listings/{unitId}/content` med en `Idempotency-Key` och följande JSON-kropp: ```json {"name":"Bright two-room apartment","otherFacts":"Two rooms and a kitchen with a balcony."} ``` Svaret är samma `{"listing": ...}`-projektion som vid detaljläsning av annonsen. `name` och `otherFacts` är de enda godkända fälten; båda är valfria strängar som trimmas, och minst ett måste anges. Gränserna är 200 respektive 10000 tecken, med en gräns på 64 KiB för anropskroppen. Utelämnade fält ändras inte. Tomt `name` tar bort det valfria lägenhetsnamnet. Tomt `otherFacts` tömmer lägenhetstexten, så att offentlig `description` faller tillbaka på lägenhetens äldre `facts` och därefter fastighetens beskrivning. Dessa reservkällor raderas inte. `null` och okända fält avvisas. Läs tillbaka resultatet och tillämpa annonsändringshändelser som vanligt. Återspelning kräver fortfarande nyckelns aktuella behörighet och ägarskap; ett senare avslag upphäver inte en tidigare lyckad operation. Olika operationsnycklar som ändrar samma fält följer principen att den sista skrivningen gäller; `listingVersion` är inte ett skrivvillkor här. Media, publicering, tillgänglighet och privata hyresgästfält kan inte ändras genom den här innehållsoperationen. Deras separata administrationsgränser gäller fortfarande. Innehållsändringen, den obligatoriska semantiska revisionsposten och återspelningsresultatet sparas atomiskt. Revisionsposten innehåller nyckel-/operations-ID:n och ändrade fältnamn, utan att lagra din nyckelhemlighet eller annonstexten i den posten. ## Ladda upp annonsbilder och publicera via API:t Aktivera en uttrycklig annonsfullmakt för exakt integrationsnyckel under **Inställningar → API & agenter**. Administratören loggar in igen med lösenord, passkey eller en eID-metod som är aktiverad i Homito och beviljar `media` och/eller `publication` med ett slutdatum. Aktiveringen använder den inloggade personens eget företagsmedlemskap och aktuella publiceringskrav. `createdBy`, jokerbehörighet, en ersättningsnyckel eller ett person-ID från klienten ersätter inte fullmakten. Den kan läsas eller återkallas på webbappens sessionsskyddade `/api/v1/settings/api-keys/{keyId}/listing-grant`; den adressen ligger inte på det externa API:ts adress. Varje operation nedan kräver `write:properties`, motsvarande delegerade rättighet och en egen `Idempotency-Key`. Behåll identisk nyckel och kropp efter ett avbrutet svar; återspelning kontrollerar aktuell behörighet innan kvittot lämnas ut. 1. Skicka `POST /api/v1/landlord/listings/{unitId}/media/uploads` med `{"images":[{"bytes":12345,"sha256":"<64 lowercase hexadecimal characters>","mimeType":"image/png"}]}`. Beräkna storlek och SHA-256 från originalfilens faktiska bytes. Gränser: tio bilder per reservation och fem MiB per bild. Reservationen gäller femton minuter; en returnerad PUT-adress gäller högst fem minuter. 2. Skicka exakt dessa bytes med PUT till returnerade `upload.url`, med **alla** värden i `upload.headers` och utan Homitos Authorization-header. Använd binär HTTP-uppladdning, avvisa omdirigeringar och kontrollera HTTP-resultatet före färdigställning. Det privata mellanlagrade objektet är ännu ingen annonsbild. Återspelning förlänger inte adresserna; skapa en ny reservation med ny operationsnyckel efter att tiden gått ut. 3. Skicka `POST /api/v1/landlord/listings/{unitId}/media/uploads/{uploadId}/complete` med `{}` eller `{"setAsFront":true}`. Servern verifierar faktisk längd, SHA-256, MIME, avkodning och pixelgräns, skriver en annan oföränderlig offentlig bild och sparar galleri, audit, ändringsjournal, beständig webhookavsikt och kvitto atomiskt. Läs tillbaka annonsen. GIF och animerad WebP kan behålla inbäddad metadata; fullständig metadatarensning utlovas inte. 4. Skicka `PATCH /api/v1/landlord/listings/{unitId}/publication` med `{"isPublic":true,"allocationMethod":"individual_assessment","creditCheckMode":"without_credit_check"}` för att publicera, eller `{"isPublic":false}` för att avpublicera. Fördelningsmetoden kan också vara `first_come`. Underhåll, företagsfrysning, omgångsregler och den delegerande personens aktuella publiceringskrav gäller fortfarande. Avpublicering behåller sitt befintliga undantag från publiceringens tillitskrav men kräver giltig nyckel, fullmakt, person, medlemskap och ägarskap. Godtyckliga sluggar, kreditupplysningar och privata hyresgästfält accepteras inte. Följ `listing.changed`/`listing.unpublished` genom det ordnade ändringsflödet. Övergivna råuppladdningar och ej anslutna härledda objekt har beständig schemalagd städning. Ett skrivkvitto visar ändring och leveransavsikt; kontrollera faktisk webhookleverans separat. När en godkänd exakt MCP-distribution annonserar dem anropar `homito.reserve_listing_media`, `homito.complete_listing_media` och `homito.set_listing_publication` samma REST-operationer med objekten `reservation`, `completion` respektive `publication`. Alla tar även `unitId` och `idempotencyKey`; färdigställning tar `uploadId`. Aktivera den vanliga lokala skrivgrinden; du godkänner varje anrop i MCP-klienten innan det skickas. Den binära PUT-uppladdningen är ett separat HTTP-anrop enligt instruktionerna som returnerats. Hantera befintliga bilder med `PATCH /api/v1/landlord/listings/{unitId}/media`: `{"removeUrls":[""],"frontImageUrl":""}`. Fälten kan skickas var för sig; använd `frontImageUrl:null` för att rensa det uttryckliga framsidesvalet. Operationen kan bara ta bort eller välja befintliga bilder, aldrig importera en ny adress. Borttagna hanterade bilder kan därefter städas fysiskt med databasens skydd. Motsvarande godkända MCP-verktyg är `homito.update_listing_gallery` med ett `gallery`-objekt och de vanliga skrivgrindarna. ## Fortsätt läsningar säkert Följ `nextCursor` tills värdet är `null` och behåll samma listoperation och filter. Använd en cursor endast med samma företag och listoperation. Förhandsgranskningar av importer, jobb och deras historik tillhör API-nyckeln som skapade dem, även vid åtkomst via jobb-ID. Ett grönt offentligt `/health`-svar verifierar inte i sig nyckeln eller företagsåtkomsten. ## Håll privata uppgifter utanför offentliga cacheminnen Håll personuppgifter, kvitton och uppladdningsåtkomsträtter utanför offentliga annonscacheminnen. Hyresgäst- och ansökningsläsningar returnerar avsiktligt begränsade operativa projektioner; dra inga slutsatser om utelämnade privata fält eller screeningbedömningar. Skilj null/okända värden från noll eller ett slutfört resultat. ## Använd den publicerade kontraktsversionen Använd API-versionen och livscykeln i API-referensen, varje operations scheman samt eventuell nödvändig formulär- eller resursversion när en integration uppdateras. Bevara opaka versioner oförändrade och lås en godkänd MCP-release. Händelsenamn kommer från samma katalog som API:t; ankomstordning och en produktversion ersätter inte aktuell återläsning av resursen.