Zum Hauptinhalt springen

Update address

PUT 
/company/address/

Aktualisiert die Daten einer bestehenden Adresse, die durch das Feld '_id' im Body der Anfrage identifiziert wird.

Ablauf der Operation:

  1. Authentifizierung mittels gültigem JWT
  2. Validierung des obligatorischen Feldes '_id' im Body
  3. Überprüfung, dass die Adresse zum Unternehmen des Benutzers gehört
  4. Validierung von Feldern und Formaten
  5. Verarbeitung der Google Maps-Daten (Reverse Geocoding)
  6. Falls is_default=true, wird jede bestehende Hauptadresse deaktiviert
  7. Speicherung der Änderungen in der Datenbank
  8. Rückgabe der aktualisierten Adresse

Wichtige Merkmale:

  • Die Adress-ID muss im Feld '_id' des Body gesendet werden
  • Erfordert einen gültigen JWT-Token mit Administrator-/Editor-Berechtigungen
  • Feld 'name' ist obligatorisch (3-100 Zeichen)
  • Google Maps-Daten müssen enthalten:
    • formatted_address: Vollständig formatierte Adresse
    • geometry.location: Koordinaten {lat, lng}
  • Falls is_default=true, wird jede bestehende Hauptadresse deaktiviert

Beispielanfrage:

PUT /company/address
Authorization: Bearer {token}
Content-Type: application/json

{
  _id: 507f1f77bcf86cd799439011,
  name: Aktualisiertes Logistiklager,
  company_name: CargoOffer SL,
  phone: +34912345678,
  addressGoogleMaps: {
    formatted_address: Calle de la Logística, 123, 28045 Madrid, Spanien,
    geometry: {
      location: {
        lat: 40.123456,
        lng: -3.987654
      }
    }
  },
  is_default: false
}

Beispiel für erfolgreiche Antwort:

\{
  _id: 507f1f77bcf86cd799439011,
  name: Aktualisiertes Logistiklager,
  company_name: CargoOffer SL,
  phone: +

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","description":"Erforderliche Daten zum Erstellen einer neuen Adresse","required":["name","addressGoogleMaps"],"properties":{"_id":{"type":"string","description":"Eindeutige ID der zu aktualisierenden Adresse","example":"507f1f77bcf86cd799439011"},"name":{"type":"string","description":"Beschreibender Name der Adresse (3-100 Zeichen)","example":"Almacén Logístico"},"company_name":{"type":"string","description":"Firmenname des Unternehmens an dieser Adresse (optional)","example":"CargoOffer SL"},"phone":{"type":"string","description":"Telefonnummer im internationalen Format (optional)","example":"+34912345678"},"addressGoogleMaps":{"type":"object","description":"Google Maps-Daten für Geolokalisierung","properties":{"formatted_address":{"type":"string","description":"Vollständig formatierte Adresse","example":"Calle de la Logística, 123, 28045 Madrid, España"},"geometry":{"type":"object","properties":{"location":{"type":"object","properties":{"lat":{"type":"number","format":"float","description":"Breitengrad in Dezimalgrad","example":40.123456},"lng":{"type":"number","format":"float","description":"Länge in Dezimalgrad","example":-3.987654}},"required":["lat","lng"]}},"required":["location"]}},"required":["formatted_address","geometry"]},"is_default":{"type":"boolean","description":"Geben Sie an, ob dies die Hauptadresse des Unternehmens sein wird.","example":false}},"example":{"_id":"507f1f77bcf86cd799439011","name":"Almacén Logístico","company_name":"CargoOffer SL","phone":"+34912345678","addressGoogleMaps":{"formatted_address":"Calle de la Logística, 123, 28045 Madrid, España","geometry":{"location":{"lat":40.123456,"lng":-3.987654}}},"is_default":false},"title":"CreateAddressRequest"},"example":{"_id":"64917511ef73c37ccae60bc4","name":"Almacén Logístico Actualizado","company_name":"CargoOffer SL","phone":"+34912345678","addressGoogleMaps":{"formatted_address":"Calle de la Logística, 123, 28045 Madrid, España","geometry":{"location":{"lat":40.123456,"lng":-3.987654}}},"isDefault":false}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Adresse erfolgreich aktualisiert","content":{"application/json":{"schema":{"type":"object","description":"Stellt eine physische Adresse dar, die einem Unternehmen für Lade-/Entladevorgänge zugeordnet ist.\n**Funktionalität**:  - Ursprungsort (ETL – Expected Time of Loading) oder Zielort (ETD – Expected Time of Delivery) in Transportauktionen - Wird unternehmensspezifisch gespeichert und ist in mehreren Vorgängen wiederverwendbar - Bei der Erstellung automatisch über die Google Maps API geokodiert - Vor dem Löschen wird die Verwendung in aktiven Auktionen/Lieferungen überprüft\n**Modell**: `src/features/models/address.model.js`\n**Controller**: `src/features/company/address/controller.js`","properties":{"_id":{"type":"string","description":"MongoDB-Eindeutigkeitskennung der Adresse (24 hexadezimale Zeichen). Wird automatisch vom System bei der Erstellung der Adresse generiert. Wird als Referenz in Auktionsmodellen (auction.etl_address, auction.etd_address) und Lieferungen (delivery.etl_address, delivery.etd_address) verwendet.","pattern":"^[a-f0-9]{24}$","example":"507f1f77bcf86cd799439011"},"name":{"type":"string","description":"Beschreibender Name oder benutzerdefinierter Alias für den Standort, der vom Benutzer vergeben wird. Wird zur schnellen Identifizierung in Listen und zur Adressauswahl verwendet. **Erforderlich** - Mindestens 3 Zeichen, maximal 100. Beispiele: Lager Nord, Zentrale, Kunde ABC - Werk Madrid.","minLength":3,"maxLength":100,"example":"Oficina Central"},"company_name":{"type":"string","description":"Firmenname oder Handelsname des Unternehmens an diesem Standort. **Erforderlich** – Erscheint in offiziellen Dokumenten (CMR, Verträge). Kann vom Namen der Hauptgesellschaft abweichen, wenn es sich um eine Kunden-/Lieferantenadresse handelt. Mindestens 2 Zeichen, maximal 100.","minLength":2,"maxLength":100,"example":"CargoOffer SL"},"phone":{"type":"string","description":"Telefonnummer für die logistische Koordination an dieser Adresse. **Optional** - Empfohlenes internationales Format (E.164 mit +Ländercode). Wird von Transportunternehmen zur Ankunftsbestätigung und zur Lösung von Problemen verwendet. Validierung nach Muster: 9-15 Ziffern.","pattern":"^\\+?[0-9]{9,15}$","maxLength":20,"example":"+34912345678"},"street":{"type":"string","description":"Vollständige Straße mit Hausnummer, automatisch generiert aus addressGoogleMaps. Format: Straßenname, Hausnummer. Wird für die Anzeige und CSV-Exporte verwendet. Legacy-Feld kombiniert (siehe street_address + street_number für getrennte Felder).","example":"Calle Ejemplo 123"},"street_address":{"type":"string","description":"Straßenname ohne Hausnummer (separates Feld). Aus der Google Maps API-Antwort geparst (route-Komponente).","example":"Calle de Alcalá"},"street_number":{"type":"string","description":"Straßennummer als eigenständiges Feld. Aus der Google Maps API-Antwort geparst (street_number-Komponente).","example":"42"},"city":{"type":"string","description":"Kleinbuchstaben-normalisierte Stadt, automatisch aus Koordinaten über die Google Maps Geocoding API extrahiert. Wird in Suchfiltern und zur Gruppierung von Adressen nach Gebieten verwendet. Typ: locality oder administrative_area_level_2 von Google Maps.","example":"madrid"},"state":{"type":"string","description":"Staat, autonome Gemeinschaft oder Verwaltungsregion (normalisiert in Kleinbuchstaben). Entnommen aus administrative_area_level_1 von Google Maps. Optional – Kann in Ländern ohne regionale Gliederung leer sein.","example":"comunidad de madrid"},"zipcode":{"type":"string","description":"Postleitzahl gemäß dem Format des jeweiligen Landes. Entnommen aus der postal_code-Komponente der Google Maps API. Wird für Gebietsvalidierungen und Tarifberechnungen verwendet.","example":"28045"},"country":{"type":"string","description":"ISO 3166-1 alpha-2-Ländercode in GROSSBUCHSTABEN (2 Buchstaben). **Kritisch** für: TaxID-Validierung, Kennzeichenformat, Tarifberechnung, ADR-Beschränkungen. Wird aus der country-Komponente (short_name) der Google Maps API extrahiert. Muss mit den aktiven Ländern in der Collection 'countries' übereinstimmen.","pattern":"^[A-Z]{2}$","example":"ES"},"neighborhood":{"type":"string","description":"Stadtteil oder Gebiet innerhalb der Stadt (optional). Entnommen aus 'neighborhood' oder 'sublocality' von Google Maps. Wird für die Genauigkeit in großen städtischen Gebieten verwendet.","example":"centro"},"province":{"type":"string","description":"Provinz oder provinziale Verwaltungseinheit. Entnommen aus administrative_area_level_2 von Google Maps (in Ländern mit Provinzen). Optional – Relevant hauptsächlich in Spanien, Italien usw.","example":"madrid"},"location":{"type":"object","description":"Geografische Koordinaten im GeoJSON Point-Format gemäß RFC 7946 Standard. Referenzsystem: WGS84 (EPSG:4326). **ERFORDERLICH** – Wird von MongoDB für georäumliche Abfragen verwendet ($near, $geoWithin). **KRITISCH**: Die Reihenfolge im Koordinaten-Array ist [Längengrad, Breitengrad] (X, Y) – NICHT vertauschen. Verwendung in: Entfernungsberechnung, optimale Routenplanung, Validierung von Servicegebieten.","required":["type","coordinates"],"properties":{"type":{"type":"string","enum":["Point"],"description":"GeoJSON-Geometrietyp. Für Adressen muss dies immer Point sein. Andere Typen (LineString, Polygon) sind in diesem Kontext nicht gültig.","example":"Point"},"coordinates":{"type":"array","description":"Array aus zwei Zahlen: [Längengrad, Breitengrad] in Dezimalgrad. **KRITISCHE REIHENFOLGE**: Längengrad zuerst (X-Achse, -180 bis 180), Breitengrad danach (Y-Achse, -90 bis 90). Gültiges Beispiel: [-3.70379, 40.416775] = 3.70° West, 40.41° Nord (Madrid). **HÄUFIGER FEHLER**: Vertauschen der Reihenfolge führt zu falschen Berechnungen. Verwendung in: model.find({location: {$near: {$geometry: {type: 'Point', coordinates: [lng, lat]}}}})","items":{"type":"number"},"minItems":2,"maxItems":2,"example":[-3.70379,40.416775]}}},"placeId":{"type":"string","description":"Einzigartige und unveränderliche Google Place ID für diesen Standort. Verwendet für: Reverse Geocoding, Validierung von Änderungen, Abruf aktualisierter Details. Format: Alphanumerische Zeichenfolge, beginnend typischerweise mit ChIJ. Persistiert, um wiederholte Geocodierungen zu vermeiden (API-Kosteneinsparung).","example":"ChIJi-AoYTIoQg0RnHvWosEVABQ"},"name_address":{"type":"string","description":"Vollständige formatierte Adresse, generiert von Google Maps (formatted_address). Enthält: Straße, Hausnummer, Postleitzahl, Stadt, Land im lokalen Format. Verwendung: Anzeige für Benutzer, Exporte, offizielle Dokumente. Nicht manuell bearbeitbar – wird automatisch neu generiert, wenn Koordinaten aktualisiert werden.","example":"Calle de Alcalá, 42, 28014 Madrid, España"},"isDefault":{"type":"boolean","description":"Gibt an, ob dies die Haupt-/Standardadresse des Unternehmens ist. **Einschränkung**: Pro Unternehmen kann nur eine Adresse mit isDefault=true existieren. Wenn isDefault=true für eine Adresse gesetzt wird, wird die vorherige Adresse mit diesem Flag automatisch auf false gesetzt. Verwendung in: Autovervollständigung von Formularen, Standardadresse für neue Auktionen. Auch gespeichert in: company.address_default (Referenz auf die _id dieser Adresse).","default":false,"example":true},"can_be_deleted":{"type":"boolean","description":"Dynamisch zur Abfragezeit berechnetes Flag (nicht in der Datenbank gespeichert). **false**: Die Adresse wird in aktiven Auktionen oder Lieferungen referenziert (status != canceled/delivered). **true**: Die Adresse hat keine Abhängigkeiten und kann sicher gelöscht werden. Berechnet in: controller.get() durch Prüfung der Anzahl von Auktionen/Lieferungen, bei denen etl_address oder etd_address == this._id. Verhindert: Versehentliches Löschen von Adressen, die in Verwendung sind, was zu verwaisten Daten führen würde.","example":false},"destinations":{"type":"array","description":"Array häufig angefahrener Ziele mit vorberechneten Routen von dieser Adresse. **Optimierung**: Vermeidet wiederholtes Neuberechnen von Routen, verbessert die Leistung bei der Auktionssuche. Befüllt durch: nächtlichen Cron-Job oder bei Bedarf für häufig auftretende Adresspaare. Verwendet in: Endpunkt /company/minimal für Kosten-/Entfernungsberechnungen ohne externe API-Aufrufe. Struktur: [{address: ObjectId, minimalRoute: {distance: Number(km), timeCost: Number(min)}}]","items":{"type":"object","properties":{"address":{"type":"string","description":"ObjectId der Zieladresse","example":"507f1f77bcf86cd799439012"},"minimalRoute":{"type":"object","properties":{"distance":{"type":"number","description":"Berechnete Entfernung in Kilometern (über Routen-API)","example":523.7},"timeCost":{"type":"number","description":"Geschätzte Reisezeit in Minuten (unter Berücksichtigung der Durchschnittsgeschwindigkeit)","example":360}}}}}}},"required":["_id","name","location","isDefault","can_be_deleted"],"title":"Address"},"example":{"status":200,"data":{"location":{"type":"Point","coordinates":[-8.995213099999999,42.5668541]},"_id":"64917511ef73c37ccae60bc4","name":"Almacén Logístico Actualizado","company_name":"CargoOffer SL","phone":"+34912345678","city":"ribeira","state":"galicia","country":"españa","zipcode":"15960","street_number":"117","street_address":"Estrada Deán Norte","province":"A Coruña","placeId":"ChIJLdx3TsE5Lw0Rmh7qsvQUqII","name_address":"Estrada Deán Norte, 117, 15960 Ribeira, A Coruña, España","destinations":[],"createdAt":"2024-10-02T18:24:37.606Z","deleted":false}}}},"headers":{}},"400":{"description":"Ungültige Eingabedaten","headers":{}},"401":{"description":"Nicht autorisiert (ungültiges oder fehlendes JWT-Token)","headers":{}},"403":{"description":"NOT_ALLOWED - Die Adresse gehört nicht zu diesem Unternehmen","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"NOT_ALLOWED"}}}}},"headers":{}},"404":{"description":"Adresse nicht gefunden","headers":{}}}}
>
  
</StatusCodes>