Annonser och synkronisering

Synkronisera bostadsannonser och redigera de innehållsfält som stöds.

REST-operationer och nyckelbehörigheter

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:

{"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":["<exact URL from the current gallery>"],"frontImageUrl":"<exact retained gallery URL>"}. 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.