AthausDoku

Create the units of a project

Aufruf, Parameter, Antwort und Fehler von POST /v1/projects/{externalProjectId}/units.

Zuletzt aktualisiert:

Creates up to 500 units in one call, each a listing of the project: it takes the address, texts, energy data and commission from the project, and the listing operations change it afterwards. The call is all or nothing: if any item is refused, nothing is created and errors names every refused item by its position (units[3].unit). A unit number already in the project, upper and lower case alike, is 409 unit_already_exists; a number twice in the call is 400; a reference another listing carries is 409 reference_already_exists; a status that does not fit the project is 409 unit_status_invalid. A repeat of the same body with a new Idempotency-Key creates nothing and answers 409 (reference_already_exists when the units name references, else unit_already_exists), and errors names the units that exist; a repeat with the same key answers the first answer again. A project holds at most 1000 units: a call that would pass that is 409 project_unit_limit_exceeded and changes nothing. The units count against the plan's listings (403 plan_required). Creating does not publish. Needs write access to projects.

Braucht den Scope propose und mindestens die Stufe write auf projects.

Aufruf

POST https://api.athaus.ai/v1/projects/{externalProjectId}/units

Parameter

Pfad

NameTypPflichtBeschreibung
externalProjectIdstringjaYour reference of the project: the value of metadata.source.offererMarketingKey. A project without one has its own projectId here, and the projectId always works in the path. 1 to 128 letters, digits, dots, underscores or hyphens, not starting or ending with a dot.

Kopf

NameTypPflichtBeschreibung
Athaus-VersionstringneinOptional 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-KeystringneinMakes 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.

FeldTypBeschreibung
unitsobject[]
units[].externalListingIdstringYour reference of the listing the unit becomes (its metadata.source.offererMarketingKey). Without it the listing has only its own listingId.
units[].unitstringThe unit number, the listing's data.location.unit. Unique in the project, upper and lower case alike.
units[].buildingstringThe house or building within the project.
units[].floorinteger-5 bis 200.
units[].roomsnumberbis 50.
units[].livingSpacenumberSquare metres.
units[].pricenumberEuros; for a rental project the monthly base rent.
units[].statusstringOurs, not OpenImmo. A rental project knows free, option, reserved and rented; a project for sale knows free, option, reserved and sold. Eines von free, option, reserved, sold, rented.

Beispiel

curl -X POST "https://api.athaus.ai/v1/projects/PRJ-1-ext/units" \
  -H "Authorization: Bearer ath_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"units":[{"externalListingId":"PRJ-7-WE-1","unit":"WE 1","building":"A","floor":1,"rooms":3,"livingSpace":78.5,"price":429000},{"externalListingId":"PRJ-7-WE-2","unit":"WE 2","building":"A","floor":2,"rooms":2,"livingSpace":54,"price":319000,"status":"option"}]}'

Antwort

Bei Erfolg kommt 202 mit ProjectUnitsReceipt.

ProjectUnitsReceipt

FeldTypBeschreibung
requestIdstring
projectIdstring
externalProjectIdstring
listingsobject[]The listings the call created or moved, in the order of the request.
listings[].listingIdstring
listings[].externalListingIdstring
listings[].unitstring
warningsobject[]
warnings[].typestring
warnings[].messagestring

Köpfe der Antwort

KopfBeschreibung
Request-IdIdentifies this request. Quote it in a support request.
Athaus-VersionThe API version of this response: v1.
Athaus-ReleaseThe release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it.
RateLimit-PolicyThe quota policy of the bucket that applies.
RateLimitRemaining quota and seconds until the bucket is full again.
Idempotent-Replayedtrue 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.

StatusCodesBedeutung
400api_version_unsupported, invalid_bodyInvalid request.
401unauthorizedMissing or invalid API key.
403insufficient_permissions, plan_requiredThe key lacks a right, or the plan does not include API access.
404not_foundNothing under this ID.
409unit_already_exists, reference_already_exists, unit_status_invalid, project_unit_limit_exceeded, idempotency_key_in_use, idempotency_outcome_unknownThe request conflicts with the state of the resource (for example a duplicate), or with an idempotency key.
413payload_too_largeThe request body is larger than 512 KB.
415invalid_inputThe request body is not JSON. Send Content-Type: application/json.
422idempotency_key_reusedThe idempotency key was already used with a different request body.
429rate_limitedRate limit exceeded.
500internal_errorServer error.

Weiter lesen

Auf dieser Seite