Ansökningar på kundens webbplats
På den här sidan
- REST-operationer och nyckelbehörigheter
- Bygg ett ansökningsflöde på kundens webbplats
- 1. Läs det aktuella formuläret innan en ansökan samlas in.
- 2. Håll varje nyckel och åtkomsträtt åtskild.
- 3. Genomför den identitetsöverlämning som krävs och skicka sedan in en gång.
- 4. Läs kvittot innan du väljer vad som ska försökas igen.
- 5. Ladda upp deklarerade bytes och slutför.
- Återställ utifrån felkoden utan att skapa en andra ansökan.
- Håll privata uppgifter utanför offentliga cacheminnen
Samla in en ansökan, genomför identitetskontroller och återuppta dokumentuppladdningar säkert.
REST-operationer och nyckelbehörigheter
| Uppgift | Nyckelbehörigheter | Börja här |
|---|---|---|
| Använd kundserverns ansökningsbudget eller den värdbaserade eID-överlämningen | write:applications på en separat servernyckel | POST /api/v1/public/units/{slug}/application-eid/handoffs |
Bygg ett ansökningsflöde på kundens webbplats
Använd den versionerade REST-inlämningen när du erbjuder ett ansökningsformulär på din egen webbplats. Börja med den bekräftade API-adressen i anslutningsguiden. Flödet är separat från hyresvärdens ansökningsläsningar och MCP-verktyg; en företagsnyckel ersätter aldrig sökandens identitet eller samtycke.
1. Läs det aktuella formuläret innan en ansökan samlas in.
Läs GET /api/v1/public/units/{slug}/application-form?language=sv (även en eller es). Bevara returnerade unitSlug, listingPeriodId och det opaka värdet formVersion. Rendera publicerade inputSchema, villkorliga rules, policies.confirmations, dokumentkrav och identityGate; återskapa dem inte utifrån antaganden. Länka angivna integritets-/villkorssökvägar genom den bekräftade adressen till Homito-webbappen, inte API-adressen. Kontrollera canApply och unavailableReason; en formulärläsning skapar eller återöppnar inte en ansökningsomgång.
Använd POST /api/v1/public/units/{slug}/application-form/validate för återkoppling på ett utkast. Utkastsvalidering kontrollerar gemensamma fältregler, bekräftelser och deklarerad dokumentmetadata mot en skrivskyddad ögonblicksbild av formuläret. Den skapar ingen ansökan eller samtyckeslogg, kräver ingen inskickningsnyckel, verifierar inga filbytes och startar inget anrop till identitets- eller screeningleverantör. Den slutliga inlämningen valideras igen.
2. Håll varje nyckel och åtkomsträtt åtskild.
| Nyckel eller åtkomsträtt | Syfte | Gräns |
|---|---|---|
X-Homito-Customer-Key | En separat servernyckel med write:applications för kundens gemensamma inlämningsbudget och värdbaserade eID-överlämning | Endast på servern; samma företag som den annonserade lägenheten; ersätter inte sökandens åtkomsträtter |
X-Application-Submission-Key | En UUID v4 som skapas före första inlämningen | Behåll samma nyckel och accepterade anropskropp/filer efter ett förlorat svar; den är inte en Idempotency-Key för hyresvärds-API:t |
X-Application-Receipt | JSON med kind: "public", ursprunglig lägenhetsslug som target och ursprunglig inskickningsnyckel som key | Skicka i kvittoheadern, aldrig i en URL; den visar endast om inlämningen sparats och bilagornas status |
X-Application-Upload-Key | En separat åtkomsträtt skapad av 32 kryptografiskt slumpmässiga byte, kodade som 64 gemena hexadecimala tecken | Krävs för manifestets uppladdningsoperationer; ett kvitto, ansöknings-ID eller en företagsnyckel ersätter den inte |
Kundnyckeln ändrar företagets gemensamma trafikbudget; den ger inte åtkomst till ett annat företag och ersätter inte kvitto-/uppladdningsbehörigheter. En ogiltig bifogad nyckel avvisas i stället för att falla tillbaka på offentlig åtkomst. Förvara företagsnycklar på servern och håll alla åtkomsträtter utanför offentliga cacheminnen, URL:er, loggar och agentkonversationer. Bevara dem i besökarens skyddade formulärsession före första nätverksanropet.
3. Genomför den identitetsöverlämning som krävs och skicka sedan in en gång.
När identityGate.required är true använder du den publicerade värdbaserade eID-överlämningen. En administratör registrerar först kundens exakta HTTPS-callback genom det befintliga autentiserade kontrollplanet. På kundservern binder du slumpmässig state, en privat PKCE-verifierare och dess S256-utmaning till den aktuella besökarens skyddade formulärsession, aktuellt formulär/omgång och ursprunglig inskickningsnyckel. Skapa överlämningen på POST /api/v1/public/units/{slug}/application-eid/handoffs med samma företags servernyckel och det returnerade formulärkontraktet.
Spara överlämningens tillstånd före omdirigering till den returnerade auktoriserings-URL:en och respektera expiresAt. Vid den registrerade callbacken validerar du state mot samma besökares session; en global state-uppslagning räcker inte. Håll kod/verifierare privata, undertryck loggning av callbackens frågeparametrar och omdirigera direkt till en ren formulär-URL. En nyckel, ett konto, flaggan hasNoPersonalNumber eller ett klientpåstående kan inte kringgå obligatorisk eID.
Skicka POST /api/v1/applications som multipart/form-data med X-Homito-Application-Contract: 1 och ursprunglig X-Application-Submission-Key. Ange korrekt Content-Length; saknad eller avvikande längd avvisas. Inkludera unitSlug, listingPeriodId, formVersion och JSON-fälten i application. När det krävs skickar du det separata JSON-fältet identityHandoff med handoffId, code och codeVerifier; lägg det aldrig inuti application och exponera inte verifieraren i webbläsarkod. För en inlämning med överlämning skickar du dessutom exakt den ursprungliga kundnyckel som skapade överlämningen; en annan nyckel för samma företag kan inte ersätta den. Äldre JSON-inlämning ger inte detta versionerade kontrakt.
Använd formulärets documents.maxExternalBodyBytes för hela multipart-anropet. Filer som skickas direkt använder de publicerade bilagefälten; större dokument använder attachmentManifest utan direkta filer och med separat uppladdningsnyckel. Följ documents.manifestSchema, maxFiles, maxFileBytes, allowedMimeTypes och acceptedByteFormats, inklusive kraven för huvudsökande och varje medsökande. Ett manifest deklarerar avsedda filer; det bevisar inte att filerna tagits emot.
4. Läs kvittot innan du väljer vad som ska försökas igen.
Läs GET /api/v1/applications/receipt med ursprunglig kvittoheader. received betyder att ansökan sparats; granska dess separata attachments-status i stället för att skapa en ny inlämning. En identisk upprepning av en redan sparad inlämning returnerar ursprungligt kvitto innan ett förbrukat eller utgånget engångsbevis för identitet kontrolleras igen. unknown kan betyda att ansökan inte skickats, fortfarande behandlas eller återställts: använd begränsad väntan mellan försök och behåll identiskt anrop och ursprunglig nyckel vid upprepning. removed är slutgiltigt; stoppa gamla återförsök. Kvittoläsning ger inte rätt till sökandeprofil, dokumentnedladdning, screeningresultat eller beslut. notifications: unknown bevisar inte e-postleverans.
5. Ladda upp deklarerade bytes och slutför.
Alla fyra operationer nedan kräver ursprunglig X-Application-Upload-Key. Bevara varje uppladdnings-ID i manifestet samt ursprungliga filbytes/hashvärden vid avbrott.
| Operation | Vad den bekräftar |
|---|---|
GET /api/v1/applications/{applicationId}/uploads | Aktuell finalized-flagga och varje deklarerad fils status pending, received, expired eller stale |
POST /api/v1/applications/{applicationId}/uploads/{uploadId}/url | En kortlivad PUT-URL och exakta headers, eller ett redan received-resultat som inte behöver PUT |
POST /api/v1/applications/{applicationId}/uploads/{uploadId}/complete | Faktiska bytes, längd, SHA-256, byteformat/MIME och aktuell koppling till sökanden har kontrollerats och bilagan sparats |
POST /api/v1/applications/{applicationId}/finalize | Alla deklarerade dokument har sparats i det ordinarie dokumentlagret; annars avvisas operationen |
Ladda endast upp till exakt returnerad URL med dess exakta metod, headers och bytelängd. Skicka aldrig företagsnyckeln eller sökandens åtkomsträtter till objektlagringen, följ inga omdirigeringar och logga inte den signerade URL:en. En lyckad PUT är inte i sig ett slutförande. En uppladdningsproxy på kundservern undviker antagandet att direkt CORS från webbläsare till lagring är konfigurerad.
Efter ett förlorat PUT-svar försöker du först med complete för samma uppladdnings-ID innan du laddar upp igen. Vid upload_missing hämtar du en ny URL för samma ID, laddar upp ursprungliga bytes och slutför. En ny PUT-URL förnyar inte den underliggande uppladdningsrättens giltighet. Stanna när åtkomsträtten löpt ut eller kopplingen till sökande/omgång ändrats; en ändrad fil eller person kräver det uttryckligt auktoriserade rättelse-/kompletteringsflödet, inte en ny inskickningsnyckel eller ett ändrat accepterat manifest.
Återställ utifrån felkoden utan att skapa en andra ansökan.
| Fel | Nästa åtgärd |
|---|---|
eid_required (403) | Genomför det godkända värdbaserade identitetsflödet; hitta inte på en genväg |
form_version_changed / application_round_changed (409) | Läs om aktuellt kontrakt och be sökanden bekräfta ändrade uppgifter före en ny accepterad inlämning; bevara eventuellt befintligt kvitto |
submission_payload_changed (409) | Stäm av ursprunglig accepterad kropp/filer; skapa inte automatiskt en ny operation |
upload_subject_changed (409), inaktuell eller utgången uppladdningsåtkomst | Stoppa uppladdning/slutförande och använd auktoriserat kompletteringsflöde för aktuell sökande |
submission_removed (410) | Sluta försöka skicka den borttagna inlämningen igen |
| Fil-/formatvalideringsfel (400/411/413/415/422) | Rätta det rapporterade anrops- eller dokumentfelet före ett auktoriserat nytt försök |
| 429, 503 eller förlorat svar | Respektera Retry-After när det anges, behåll kontrollpunkten och läs kvitto/förlopp före ett nytt försök med ursprunglig nyckel |
application.submitted och application.intake_finalized är separata webhook-händelser. Verifiera och deduplicera dem enligt webhook-guiden och använd kvitto/förlopp för aktuellt tillstånd. Varken en händelse eller slutförandet bevisar e-postleverans, hyresbeslut eller genomförd screening. Håll sökandeuppgifter och uppladdnings-/kvittoåtkomsträtter utanför offentliga annonscacheminnen.
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.