Create a project
Aufruf, Parameter, Antwort und Fehler von POST /v1/projects.
Zuletzt aktualisiert:
Creates a new-build project. The body is the OpenImmo 2.0 project; the headline in data.texts is its name. metadata.source.offererMarketingKey must be unique among the projects of the office (409 reference_already_exists). status is ours: the name of one of the office's project states; without it the project starts in the first. Send Idempotency-Key to make a retry safe. Needs write access to projects.
Braucht den Scope propose und mindestens die Stufe write auf projects.
Aufruf
POST https://api.athaus.ai/v1/projectsParameter
Kopf
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
Athaus-Version | string | nein | Optional and carries nothing a client needs: the version is the path. Accepted when it says v1 or 1. Any other value is a 400 api_version_unsupported. |
Idempotency-Key | string | nein | Makes a retry safe: the same key with the same body returns the first answer and writes nothing twice. A random value of at least 128 bits, for example a UUID, 1 to 255 characters. The key is kept for 24 hours and scoped to the API key and this operation. The same key with a different body is a 422; while the first request still runs it is a 409. Only successful answers are kept: after an error the key is free again. |
Rumpf
JSON mit Content-Type: application/json. Ein Feld, das die API nicht kennt, ist ein 400, und errors[].name nennt das Feld. Der Rumpf ist Pflicht.
| Feld | Typ | Beschreibung |
|---|---|---|
data | object | |
data.estateType | string | Eines von NEW_BUILD_PROJECT, NEW_HOME_PROJECT. |
data.estateSubType | string | object | null | any | |
data.distributionType | string | Eines von BUY, RENT, BUY_RENT. |
data.units | object | |
data.units.numberOfUnits | number | 0 bis 999999. |
data.units.priceFrom | number | 0 bis . |
data.units.priceTo | number | 0 bis . |
data.units.livingSpaceFrom | number | 0 bis . |
data.units.livingSpaceTo | number | 0 bis . |
data.units.numberOfRoomsFrom | number | 0 bis . |
data.units.numberOfRoomsTo | number | 0 bis . |
data.units.furnishingLevel | string | Eines von NOT_PROVIDED, STANDARD, UPSCALE, FULL. |
data.units.provisionType | string | Eines von PROVISION_FREE, PROVISION_FOR_BUYER, NOT_PROVIDED. |
data.units.provisionPercent | number | 0 bis . |
data.units.provisionIsVatIncluded | string | Eines von YES, NO, NOT_PROVIDED. |
data.units.soldOutPercentage | number | 0 bis . |
data.location | object | |
data.location.postalcode | string | |
data.location.city | string | |
data.location.street | string | |
data.location.houseNumber | string | |
data.location.unit | string | |
data.location.staircase | string | |
data.location.floorNumber | integer | -5 bis 999. |
data.location.entrance | string | |
data.location.state | string | |
data.location.country | string | Eine von 249 Angaben der Liste im Standard. |
data.location.geometry | object | |
data.location.geometry.type | string | Immer Point. |
data.location.geometry.coordinates | number[] | |
data.location.showAddress | boolean | Vorgabe true. |
data.location.locationNote | map<string> | |
data.program | object | |
data.program.projectStatus | string | Eines von CONSTRUCTION_START, PROJECT_ENDED. |
data.deliveryDate | string | |
data.structure | object | |
data.structure.building | object | |
data.structure.building.numberOfFloors | integer | 1 bis 999. |
data.texts | object | |
data.texts.headline | map<string> | |
data.texts.description | map<string> | |
data.texts.features | map<string> | |
data.texts.extendedInformation | map<string> | |
data.texts.area | map<string> | |
data.links | object | |
data.links.externalLinks | object[] | |
data.links.externalLinks[].url | string | |
data.links.externalLinks[].urlType | string | Eines von MAP, MOVIE, PANORAMA, REVOCATION_INSTRUCTION, OFFERER_DETAIL_PAGE. |
data.links.externalLinks[].title | string | |
data.links.virtualTours | object[] | |
data.links.virtualTours[].url | string | |
data.links.virtualTours[].provider | string | |
data.links.virtualTours[].title | string | |
data.contact | object | |
data.contact.salutation | string | Eines von Mr, Mrs, Miss, Ms, Mx, Sir, Dame, Dr, Cllr, Lady, Lord. |
data.contact.firstName | string | |
data.contact.lastName | string | |
data.contact.name | string | |
data.contact.emailAddress | string | |
data.contact.phoneNumber | string | |
data.contact.mobilePhoneNumber | string | |
data.contact.imageURL | string | |
data.contact.userHomepage | string | |
data.contact.postalCode | string | |
data.contact.city | string | |
data.contact.street | string | |
data.contact.houseNumber | string | |
data.contact.country | string | |
data.contact.preferredContactType | string | Eines von ANONYMOUS, BY_PHONE, BY_EMAIL, OWN_WEBSITE. |
data.contact.contactNote | map<string> | |
data.contact.displayedInformation | object | |
data.contact.displayedInformation.mainContactPerson | object | |
data.contact.displayedInformation.additionalContactPerson | object | |
metadata | object | |
metadata.source | object | |
metadata.source.offererMarketingKey | string | |
metadata.source.offererEstateId | string | |
metadata.portalWebKey | string | |
status | string | Ours, not OpenImmo: the name of one of the office's project states, for example Sales. Without it a new project starts in the first state of the office. |
Beispiel
curl -X POST "https://api.athaus.ai/v1/projects" \
-H "Authorization: Bearer ath_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"data":{"estateType":"NEW_BUILD_PROJECT","estateSubType":null,"distributionType":"BUY","units":{"provisionType":"PROVISION_FREE"},"location":{"postalcode":"04107","city":"Leipzig","street":"Kantstrasse","houseNumber":"37","country":"DEU","geometry":{"type":"Point","coordinates":[12.3731,51.3397]}},"texts":{"headline":{"de":"Waldstadt Suites"},"description":{"de":"Dreißig Wohnungen am Park."}}},"metadata":{"source":{"offererEstateId":"PRJ-7","offererMarketingKey":"PRJ-7"}},"status":"Vertrieb"}'Antwort
Bei Erfolg kommt 202 mit ProjectReceipt.
ProjectReceipt
| Feld | Typ | Beschreibung |
|---|---|---|
requestId | string | |
projectId | string | |
externalProjectId | string | |
warnings | object[] | |
warnings[].type | string | |
warnings[].message | string |
Köpfe der Antwort
| Kopf | Beschreibung |
|---|---|
Request-Id | Identifies this request. Quote it in a support request. |
Athaus-Version | The API version of this response: v1. |
Athaus-Release | The release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it. |
RateLimit-Policy | The quota policy of the bucket that applies. |
RateLimit | Remaining quota and seconds until the bucket is full again. |
Idempotent-Replayed | true when this is the stored answer to an earlier request with the same Idempotency-Key. |
Fehler
Jeder Fehler kommt als Problem Details. Verzweige auf code, nicht auf title oder detail.
| Status | Codes | Bedeutung |
|---|---|---|
400 | api_version_unsupported, invalid_body | Invalid request. |
401 | unauthorized | Missing or invalid API key. |
403 | insufficient_permissions, plan_required | The key lacks a right, or the plan does not include API access. |
404 | not_found | Nothing under this ID. |
409 | The request conflicts with the state of the resource (for example a duplicate), or with an idempotency key. | |
413 | payload_too_large | The request body is larger than 512 KB. |
415 | invalid_input | The request body is not JSON. Send Content-Type: application/json. |
422 | idempotency_key_reused | The idempotency key was already used with a different request body. |
429 | rate_limited | Rate limit exceeded. |
500 | internal_error | Server error. |
Weiter lesen
REST-API: Anmeldung mit einem API-Key
Jeder Aufruf von /v1 trägt einen API-Key als Bearer-Token. Wo du ihn bekommst, welche Scopes er trägt und was nicht geht.
REST-API: Fehler als Problem Details
Jeder Fehler von /v1 ist ein Problem nach RFC 9457 mit echtem HTTP-Status, einem Code zum Verzweigen und einer Request-Id für den Support.