Zum Hauptinhalt springen

Create simplified address

POST 
/company/address/simple

Erstelle eine neue Adresse auf vereinfachte Weise, indem du ausschließlich Koordinaten und grundlegende Daten verwendest.
Dieser Endpunkt ist für Fälle optimiert, in denen die genauen Koordinaten bekannt sind und eine Adresse schnell erstellt werden muss, ohne die Komplexität von Google Maps-Daten.

Ablauf der Operation:

  1. Authentifizierung über gültiges JWT
  2. Validierung der minimalen Pflichtfelder (lat, lng, name, company_name)
  3. Automatische Reverse-Geocodierung aus den Koordinaten
  4. Automatische Erstellung der vollständigen Adresse
  5. Zuordnung zur Firma des Benutzers
  6. Rückgabe der erstellten Adresse

Vorteile dieses Endpunkts:

  • Erfordert nur 4 Pflichtfelder gegenüber ~15 beim Standard-Endpunkt
  • Automatische Geocodierung aus Koordinaten
  • Nutzt die bewährte Logik des Massenimport-Systems wieder
  • Behält dieselbe Datenqualität wie die normale Erstellung bei

Typische Anwendungsfälle:

  • Mobile Apps mit GPS
  • Integration von Drittsystemen mit Koordinaten
  • Schnelle Erstellung aus interaktiven Karten
  • Vereinfachte Massenerstellung

Beispielanfrage:

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

{
  lat: 40.416775,
  lng: -3.703790,
  name: Hauptsitz,
  company_name: CargoOffer SL,
  phone: +34912345678,
  isDefault: false
}

Beispiel für erfolgreiche Antwort:

\{
  _id: 507f1f77bcf86cd799439011,
  name: Hauptsitz,
  company_name: CargoOffer SL,
  phone: +34912345678,
  street: Calle de Alcalá, 42,
  city: madrid,
  zipcode: 28014,
  country: es,
  location: \{
    type: Point,

<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","properties":{"lat":{"type":"number","description":"Breitengrad in Dezimalgrad (WGS84)","minimum":-90,"maximum":90,"example":40.416775},"lng":{"type":"number","description":"Länge in Dezimalgrad (WGS84)","minimum":-180,"maximum":180,"example":-3.70379},"name":{"type":"string","description":"Beschreibender Name der Adresse","minLength":3,"maxLength":100,"example":"Oficina Central"},"company_name":{"type":"string","description":"Firmenname der Gesellschaft an dieser Adresse","minLength":2,"maxLength":100,"example":"CargoOffer SL"},"phone":{"type":"string","description":"Kontakttelefon (optional, internationales Format empfohlen)","maxLength":20,"example":"+34912345678"},"isDefault":{"type":"boolean","description":"Geben Sie an, ob dies die Hauptadresse des Unternehmens sein wird.","default":false,"example":false}},"required":["lat","lng","name","company_name"],"example":{"lat":40.416775,"lng":-3.70379,"name":"Oficina Central","company_name":"CargoOffer SL","phone":"+34912345678","isDefault":false}},"example":{"lat":40.416775,"lng":-3.70379,"name":"Oficina Central","company_name":"CargoOffer SL","phone":"+34912345678","isDefault":false}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Adresse erfolgreich erstellt.","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"}}},"headers":{}},"400":{"description":"Validierungsfehler - Fehlende Pflichtfelder oder ungültiges Format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["MISSING_FIELD_LAT","MISSING_FIELD_LNG","MISSING_FIELD_NAME","MISSING_FIELD_COMPANY_NAME","INVALID_COORDINATES"],"example":"MISSING_FIELD_LAT"}}}}},"headers":{}},"401":{"description":"Authentifizierungsfehler – Ungültiges Token oder Unternehmen nicht gefunden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["USER_NOT_FOUND","CIA_NOT_FOUND"],"example":"CIA_NOT_FOUND"}}}}},"headers":{}},"404":{"description":"Benutzer nicht gefunden.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"USER_NOT_FOUND"}}}}},"headers":{}},"500":{"description":"Interner Serverfehler","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["CANNOT_SAVE_ADDRESS","INTERNAL_ERROR"],"example":"CANNOT_SAVE_ADDRESS"}}}}},"headers":{}}}}
>
  
</StatusCodes>