blob: 0184c405f3e6ea54a531e6c72d5e6d088798c678 [file] [log] [blame]
swagger: '2.0'
info:
title: Unternehmen
description: Diese Schnittstelle ist Teil der [oK](http://www.openkonsequenz.de) Quellsystem-API.
version: Revision 1 (CIM 17v07)
contact:
name: BTC AG
url: http://www.btc-ag.com
email: openk@btc-ag.com
license:
name: Eclipse Public License 1.0
url: https://www.eclipse.org/legal/epl-v10.html
host: api.openk.de
schemes:
- http
basePath: /source-system/common/contact-data
produces:
- application/xml
paths:
/organisations:
get:
summary: Die Schnittstelle gibt alle Unternehmen und ihre Beschreibungen zurück. Dies sind natürliche oder juristische Personen oder rechtlich unselbstständige Organisationseinheiten. Beispiele hierfür sind z. B. Anlagenbetreiber oder Anlageneigentümer für Einspeiser. Darin enthalten sind Kontaktinformationen, wie bspw. Adressen, Telefonnummern sowie Web- und E-Mail-Adressen.
parameters:
- name: revision
in: query
description: Version, die den Nachrichtenaustausch definiert. Dies ist nicht die CIM-Version.
required: true
type: integer
format: int32
minimum: 1
maximum: 1
- name: timestamp
in: query
description: Zeitpunkt, an dem die Nachricht versendet wurde (in UTC gemäß ISO-8601-Format YYYY-MM-DDTHH:mm:ss.SSSZ).
required: false
type: string
format: date-time
pattern: '^([0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|30|31)T(([0-1][0-9])|(2[0-3]))(:[0-5][0-9]){2}\.[0-9]{3}Z)$'
- name: source
in: query
description: Eindeutige Bezeichnung des Senders der Nachricht.
required: false
type: string
- name: user-id
in: query
description: Eindeutige Kennung des angemeldeten Nutzers (Sender).
required: false
type: string
- name: message-id
in: query
description: Eindeutige Kennung dieser Nachricht. Generiert vom Sender der Nachricht.
required: false
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
responses:
200:
description: Die Liste aller Unternehmensanschriften.
schema:
$ref: '#/definitions/ResponseMessage'
400:
description: Die Schnittstelle wurde mit ungültigen Parametern aufgerufen.
500:
description: Es trat ein allgemeiner Fehler bei der Verarbeitung der Anfrage auf.
definitions:
### specific definitions ######################################################
Organisation:
description: Das Unternehmen.
type: object
properties:
mRID:
description: eindeutige Kennung des Unternehmens.
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
name:
description: Name des Unternehmens.
type: string
minLength: 1
maxLength: 64
description:
description: Beschreibung des Unternehmens.
type: string
minLength: 1
maxLength: 2048
Names:
description: Referenzen auf alternative Namen.
type: array
minItems: 0
items:
$ref: '#/definitions/Name'
xml:
wrapped: true
electronicAddress:
$ref: '#/definitions/Organisation.electronicAddress'
phone1:
$ref: '#/definitions/Organisation.phone1'
phone2:
$ref: '#/definitions/Organisation.phone2'
postalAddress:
$ref: '#/definitions/Organisation.postalAddress'
streetAddress:
$ref: '#/definitions/Organisation.streetAddress'
required:
- mRID
xml:
name: Organisation
Organisation.electronicAddress:
description: Die elektronische Adresse des Unternehmens.
type: object
properties:
ElectronicAddress:
$ref: '#/definitions/ElectronicAddress'
required:
- ElectronicAddress
Organisation.phone1:
description: Die Telefonnummer des Unternehmens.
type: object
properties:
TelephoneNumber:
$ref: '#/definitions/TelephoneNumber'
required:
- TelephoneNumber
Organisation.phone2:
description: Die alternative Telefonnummer des Unternehmens.
type: object
properties:
TelephoneNumber:
$ref: '#/definitions/TelephoneNumber'
required:
- TelephoneNumber
Organisation.postalAddress:
description: Die Postanschrift des Unternehmens.
type: object
properties:
StreetAddress:
$ref: '#/definitions/StreetAddress'
required:
- StreetAddress
Organisation.streetAddress:
description: Die Hausanschrift des Unternehmens.
type: object
properties:
StreetAddress:
$ref: '#/definitions/StreetAddress'
required:
- StreetAddress
Organisations:
description: Auflistung der Unternehmen.
type: array
items:
$ref: '#/definitions/Organisation'
xml:
wrapped: true
Payload:
description: Der Inhalt der CIM-Antwortnachricht.
type: object
properties:
Organisations:
$ref: '#/definitions/Organisations'
required:
- Organisations
### common definitions ######################################################
ElectronicAddress:
description: Elektronische Adresse.
type: object
properties:
email1:
description: E-Mail-Adresse.
type: string
minLength: 0
maxLength: 256
email2:
description: Alternative E-Mail-Adresse.
type: string
minLength: 0
maxLength: 256
web:
description: URL.
type: string
minLength: 0
maxLength: 1024
Header_Reply:
description: Der Kopf der CIM-Nachricht.
type: object
properties:
Verb:
description: Hinweis, um welche Art von Nachricht es sich handelt.
type: string
default: reply
Noun:
description: Hinweis auf den Nachrichteninhalt.
type: string
Revision:
description: Version, die den Nachrichtenaustausch definiert. Dies ist nicht die CIM-Version.
type: integer
format: int32
minimum: 3
maximum: 3
Timestamp:
description: Zeitpunkt, an dem die Nachricht versendet wurde (in UTC gemäß ISO-8601-Format YYYY-MM-DDThh:mm:ss.sssZ).
type: string
format: date-time
pattern: '^([0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|30|31)T(([0-1][0-9])|(2[0-3]))(:[0-5][0-9]){2}\.[0-9]{3}Z)$'
Source:
description: Eindeutige Bezeichnung des Senders der Nachricht.
type: string
User:
$ref: '#/definitions/User'
MessageID:
description: Eindeutige Kennung dieser Nachricht. Generiert vom Sender der Nachricht.
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
required:
- Verb
- Noun
- Revision
- Timestamp
- Source
- MessageID
xml:
name: Header
Name:
description: alternativer Name
type: object
properties:
name:
description: ein alternativer Name (z. B. Kennung aus dem Quellsystem)
type: string
minLength: 1
maxLength: 256
NameType:
$ref: '#/definitions/Name.NameType'
required:
- name
- NameType
xml:
name: Name
Name.NameType:
properties:
NameType:
$ref: '#/definitions/NameType'
xml:
name: NameType
NameType:
description: Namenstyp
type: object
properties:
name:
description: Name des Namestyps
type: string
minLength: 1
maxLength: 256
description:
description: Beschreibung des Namestyps
type: string
minLength: 1
maxLength: 2048
NameTypeAuthority:
$ref: '#/definitions/NameType.NameTypeAuthority'
required:
- name
- NameTypeAuthority
xml:
name: NameType
NameType.NameTypeAuthority:
properties:
NameTypeAuthority:
$ref: '#/definitions/NameTypeAuthority'
xml:
name: NameTypeAuthority
NameTypeAuthority:
description: Vergabestelle des Namestyps
type: object
properties:
name:
description: Name der Vergabestelle des Namestyps
type: string
minLength: 1
maxLength: 256
description:
description: Beschreibung des Namestyps
type: string
minLength: 1
maxLength: 2048
required:
- name
xml:
name: NameTypeAuthority
Reply_OK:
description: Die Antwort der CIM-Nachricht.
type: object
properties:
Result:
description: Antworttext
type: string
default: OK
required:
- Result
xml:
name: Reply
ResponseMessage:
description: Die CIM-Antwortnachricht.
type: object
properties:
Header:
$ref: '#/definitions/Header_Reply'
Reply:
$ref: '#/definitions/Reply_OK'
Payload:
$ref: '#/definitions/Payload'
required:
- Header
- Reply
- Payload
StreetAddress:
description: Postanschrift
type: object
properties:
poBox:
description: Postfach
type: string
minLength: 0
maxLength: 16
postalCode:
description: Postleitzahl
type: string
minLength: 0
maxLength: 16
streetDetail:
$ref: '#/definitions/StreetAddress.streetDetail'
townDetail:
$ref: '#/definitions/StreetAddress.townDetail'
StreetAddress.streetDetail:
description: Detailinformationen zur Straße.
type: object
properties:
StreetDetail:
$ref: '#/definitions/StreetDetail'
required:
- StreetDetail
StreetAddress.townDetail:
description: Detailinformationen zum Ort.
type: object
properties:
TownDetail:
$ref: '#/definitions/TownDetail'
required:
- TownDetail
StreetDetail:
description: Straße
type: object
properties:
name:
description: Straßenname
type: string
minLength: 1
maxLength: 256
number:
description: Hausnummer
type: string
minLength: 1
maxLength: 256
xml:
name: StreetDetail
TelephoneNumber:
description: Telefonnummer
type: object
properties:
cityCode:
description: Ortsvorwahl
type: string
minLength: 0
maxLength: 32
dialOut:
description: Amtsvorwahl
type: string
minLength: 0
maxLength: 32
extension:
description: Durchwahl
type: string
minLength: 0
maxLength: 32
internationalPrefix:
description: Ländervorwahl
type: string
minLength: 0
maxLength: 32
localNumber:
description: Telefonnummer
type: string
minLength: 0
maxLength: 32
TownDetail:
description: Stadt
type: object
properties:
country:
description: Land
type: string
minLength: 0
maxLength: 256
name:
description: Name
type: string
minLength: 0
maxLength: 256
stateOrProvince:
description: Bundesland
type: string
minLength: 0
maxLength: 256
User:
properties:
userId:
description: Eindeutige Kennung des angemeldeten Nutzers (Empfänger).
type: string
xml:
name: UserID
required:
- UserID