# Datenformate der Public API

Das [OpenAPI-Dokument](/openapi/public.v1.json) legt das Format jedes Felds fest. Diese Seite erklärt die, mit denen eine Integration sorgfältig umgehen muss.

## Geldbeträge

Jeder Geldbetrag ist ein Dezimal-String, nie eine JSON-Zahl, damit kein Client binäre Gleitkommazahlen summiert, die abdriften:

```json
{ "amount": "1250.50000000", "currency": "EUR" }
```

- Antworten schreiben jeden Betrag mit genau acht Nachkommastellen, einem Punkt und ohne Exponent.
- Anfragen senden einen Betrag ebenso, mit bis zu acht Nachkommastellen: `"1250.5"` und `"1250.50000000"` sind derselbe Betrag. Eine JSON-Zahl, ein Exponent oder ein Tausendertrennzeichen wird mit `400` abgelehnt.
- Ein Budgetbetrag wird auf den Cent genau gespeichert; ein Budgetbetrag mit mehr als zwei Nachkommastellen wird daher abgelehnt statt gerundet.
- Vergleiche Beträge nach Wert, nicht als Text: `"49"` und `"49.00000000"` sind gleich.
- Prozentwerte, Verhältnisse wie die Zuordnungsabdeckung, Wechselkurse und Verbrauchsmengen bleiben JSON-Zahlen.
- Der `thresholdValue` einer Kostenwarnung ist ein Dezimal-String, ob er ein Betrag oder ein Prozentwert ist, wie ihr `thresholdType` sagt.

## Datumsangaben und Monate

- Ein Datum ist `YYYY-MM-DD`, etwa `startDate`, `endDate` und der `chargePeriodStart` einer benutzerdefinierten Integration. Ein Abrechnungszeitraum ist ein Tag; eine Uhrzeit wird daher abgelehnt.
- Ein Prognosemonat ist `YYYY-MM`.
- Ein Zeitstempel wie `createdAt` ist ein Datum mit Uhrzeit nach ISO 8601.

## Währungen

Eine Währung ist ein ISO-4217-Code aus drei Großbuchstaben, etwa `EUR` oder `GBP`.

## IDs

Jedes Costfluent-Objekt wird über eine ID mit Präfix angesprochen, etwa `wsp_` für einen Workspace, `bud_` für ein Budget, `crp_` für einen Kostenbericht, `seg_` für ein Segment und `prv_` für eine Integration. Das Präfix sagt, was die ID bezeichnet, und die API lehnt eine ID der falschen Art ab. Behandle den Rest als undurchsichtig.

Ein Kosten-Batch an eine benutzerdefinierte Integration antwortet mit einer `batchId`, die mit `cbt_` beginnt: eine Quittung für diesen Batch, kein Upload, den du zurücklesen kannst.

## Bedingte Änderungen

Das Lesen eines Budgets antwortet mit einem `ETag`-Header, der Version des zurückgegebenen Budgets. Sende ihn als `If-Match` mit dem `PUT` zurück, das das Budget ändert:

```bash
curl --request PUT https://api.costfluent.com/v1/budgets/$BUDGET_ID \
  --header "Authorization: Bearer $COSTFLUENT_API_TOKEN" \
  --header "If-Match: \"774\"" \
  --header "Content-Type: application/json" \
  --data '{"amount": "15000"}'
```

Hat jemand das Budget nach deinem Lesen geändert, wird das `PUT` mit `412` und `precondition_failed` abgelehnt, und nichts ändert sich: Lies es erneut und entscheide dann. Ohne `If-Match` gewinnt der letzte Schreibzugriff.

## Wie es sich verhält

- Anlegen und Ändern eines Budgets antworten ebenfalls mit seinem neuen `ETag`.
- `If-Match: *` wendet die Änderung unabhängig von der Version an.
- Der Terraform-Provider sendet das `ETag` seines letzten Lesens; eine Änderung in Costfluent zwischen einem Plan und seinem Apply stoppt das Apply daher, statt überschrieben zu werden.

## Verwandte Seiten

- [Fehler](/de/api/errors)
- [Versionierung der Public API](/de/api/versioning)
- [API-Referenz](/api)