Report Filing Service

RetrieveProtocols

RetrieveSync

Represents a request to retrieve protocols.

The following routes are available for this service:
POST	/sync/elma/protocols/retrieve

**RetrieveProtocolsBase** Parameters:
Name	Parameter	Data Type	Required	Description
SearchCriteria	form	SearchCriteria	Yes	The parameters to search for protocols.
Credential	form	ElmaCredential	Yes	The credential to gain access on the ELMA server.
StagingEnabled	form	bool?	No	Should operations be staged on the ELMA server? true: operations are executed on the Test ELMA server. false: operations are executed on the Live (Production) ELMA server.

**SearchCriteria** Parameters:
Name	Parameter	Data Type	Required	Description
Name	form	string	No	Full or partial name of the item (report or protocol) to search.
Designation	form	Verfahren?	No	TThe ELMA product designation.

**Verfahren** Enum:
CC
CS
DC
FC
FS
FA
KM

**ElmaCredential** Parameters:
Name	Parameter	Data Type	Required	Description
Id	form	string	Yes	The unique identifier of this instance. This identifer is only relevant in the context of data storage and retrieval.
Certificate	form	PemCertificate	Yes	The security certificate to authenticate the user and grant access to the ELMA server. This certificate is generated from the BZSt-issued *.pfx BOP certificate. More details on BOP (BZSt-Online Portal - https://www.elster.de/bportal/start)
AuthSteuernummer	form	string	Yes	The BZSt (Bundeszentralamt für Steuern) - tax number of the user. 11-character text field that may only consist of two capital letters and 9 digits (0-9). The fiscal authority BZSt provides this number during registration at the BOP (BZSt-Online Portal - https://www.elster.de/bportal/start). The number is available in the private area of the BOP user account under "My BOP" under the "Registration Information"
AccountId	form	string	Yes	The account identifier of a BZSt-Online Portal (BOP) user. 10-character text field that may only contain numbers (0-9).
Password	form	string	Yes	The password to protect the certificate from unauthorized access.

**PemCertificate** Parameters:
Name	Parameter	Data Type	Required	Description
Id	form	string	Yes	The unique identifier (e.g. the file name) of the certificate.
Content	form	string	Yes	The PEM-encoded content of the certificate.
Description	form	string	No	The description of the certificate.
Tags	form	List<string>	No	Tags to label or identify the certificate.

**RetrievalResponse** Parameters:
Name	Parameter	Data Type	Required	Description
Protocols	form	List<Elma>	No	Processing logs that indicate the status of submitted reports.
Files	form	List<BinaryFile>	No	Other artefacts including the auxillary files from the BZSt.
ResponseStatus	form	ResponseStatus	No	The status of the response.

**Elma** Parameters:
Name	Parameter	Data Type	Required	Description
Id	form	string	Yes	The unique identifier of this instance. This identifer is only relevant in the context of data storage and retrieval.
SchemaLocation	form	string	No	The location of the XML Schema to use for the root namespace.
Verfahren	form	Verfahren?	Yes	The type of reporting process.
ElmaKom	form	ElmaKom	Yes	The communication section of the ELMA report document.
ElmaProtokoll	form	ElmaProtokoll	No	The communication section of the ELMA report document.
ElmaFehler	form	ElmaFehler	No	The communication section of the ELMA report document.

**ElmaKom** Parameters:
Name	Parameter	Data Type	Required	Description
ElmakomVersion	form	string	Yes	The version number of the ELMAKOM definition.
ElmaHeader	form	ElmaHeader	Yes	The header part of the ELMAKOM definition.
ElmaVerfahren	form	ElmaVerfahren	Yes	The process part of the ELMAKOM definition.

**ElmaHeader** Parameters:
Name	Parameter	Data Type	Required	Description
DatenArt	form	DatenArt	Yes	The process-specific report type of an ELMA document.It distinguishes by the type of input.
AuthSteuernummer	form	string	Yes	The BZSt (Bundeszentralamt für Steuern) - tax number of the user. 11-character text field that may only consist of two capital letters and 9 digits (0-9). The fiscal authority BZSt provides this number during registration at the BOP (BZSt-Online Portal - https://www.elster.de/bportal/start). The number is available in the private area of the BOP user account under "My BOP" under the "Registration Information"
AccountId	form	string	Yes	The account identifier of a BZSt-Online Portal (BOP) user. 10-character text field that may only contain numbers (0-9).
ErstellungsDatum	form	DateTime?	No	The time of creation.Corresponds to the time, at which the user created a file.
KundeneigeneId	form	string	No	User custom ID.This field can be filled with internal reference information of the user.
UUID	form	Guid?	No	Data transfer identifier.Hexadecimal formatted number. Example: 550e8400-e29b-11d4-a716-446655440000
Verarbeitungslauf	form	Verarbeitungslauf	No	Distinguishes between test and live data transfer.

**DatenArt** Enum:
ELMA_CC
ELMA_CCRM
ELMA_CRS
ELMA_CRSRM
ELMA_DC
ELMA_DCRM
ELMA_FC
ELMA_FCRM

**Verarbeitungslauf** Enum:
PRODUKTIONSLAUF
TESTLAUF

**ElmaVerfahren** Parameters:
Name	Parameter	Data Type	Required	Description
Inhalt	form	Object	No	The content of process-specific definition.

**ElmaProtokoll** Parameters:
Name	Parameter	Data Type	Required	Description
Dateiname	form	string	No	File name of the processed input ELMA report.
AuthSteuernummer	form	string	Yes	The BZSt (Bundeszentralamt für Steuern) - tax number of the user. 11-character text field that may only consist of two capital letters and 9 digits (0-9). The fiscal authority BZSt provides this number during registration at the BOP (BZSt-Online Portal - https://www.elster.de/bportal/start). The number is available in the private area of the BOP user account under "My BOP" under the "Registration Information"
AccountId	form	string	Yes	The account identifier of a BZSt-Online Portal (BOP) user. 10-character text field that may only contain numbers (0-9).
VerarbeitungsDatum	form	DateTime?	No	Date on which the request was processed by ELAN (ELMA receiving server at BZSt).
VerarbeitungsZeit	form	DateTime?	No	Time of processing by ELAN (ELMA receiving server at BZSt).
Status	form	Status	No	The status code of the ELMA process.
StatusText	form	string	No	A brief description of the status.
StatusDetail	form	string	No	A detailed information on the status.
KundeneigeneId	form	string	No	User custom ID.This field can be filled with internal reference information of the user.
UUID	form	Guid?	No	Data transfer identifier.Hexadecimal formatted number. Example: 550e8400-e29b-11d4-a716-446655440000

**Status** Enum:
Name	Value
ELMA_GLOBAL_UNBEKANNT	0
ELMA_OK	8000
ELMA_PARSER_FEHLER	8001
ELMA_UNGUELTIGE_KODIERUNG	8002
ELMA_UNGUELTIGE_DATEINAME	8003
ELMA_FALSCHE_BZSTNR_ODER_ACCOUNTID	8004
ELMA_SIGNATUR_DATEI_FEHLT	8005
ELMA_SIGNATUR_PRUEFUNG_FEHLERHAFT	8006
ELMA_NOTWENDIGE_FACHLICHE_BERECHTIGUNGEN_FEHLEN	8007
ELMA_FREISCHALTUNG_FEHLT	8008
ELMA_SPERRE_VORHANDEN	8009
ELMA_DATEINAME_BEREITS_VERWENDET	8010
ELMA_DATEIINHALT_IDENTISCH	8011
ELMA_BZSTNR_ODER_ACCOUNTID_STIMMT_NICHT_UBEREIN	8012
ELMA_TESTDATEN	8013

**ElmaFehler** Parameters:
Name	Parameter	Data Type	Required	Description
Dateiname	form	string	No	File name of the processed input ELMA report.
AuthSteuernummer	form	string	Yes	The BZSt (Bundeszentralamt für Steuern) - tax number of the user. 11-character text field that may only consist of two capital letters and 9 digits (0-9). The fiscal authority BZSt provides this number during registration at the BOP (BZSt-Online Portal - https://www.elster.de/bportal/start). The number is available in the private area of the BOP user account under "My BOP" under the "Registration Information"
AccountId	form	string	Yes	The account identifier of a BZSt-Online Portal (BOP) user. 10-character text field that may only contain numbers (0-9).
VerarbeitungsDatum	form	DateTime?	No	Date on which the request was processed by ELAN (ELMA receiving server at BZSt).
VerarbeitungsZeit	form	DateTime?	No	Time of processing by ELAN (ELMA receiving server at BZSt).
FehlerID	form	Status	No	The status code of the ELMA process.
FehlerText	form	string	No	A brief description of the error status.
FehlerProzess	form	string	No	A detailed information on the status.
KundeneigeneId	form	string	No	User custom ID.This field can be filled with internal reference information of the user.
UUID	form	Guid?	No	Data transfer identifier.Hexadecimal formatted number. Example: 550e8400-e29b-11d4-a716-446655440000

**BinaryFile** Parameters:
Name	Parameter	Data Type	Required	Description
Metadata	form	FileMetadata	No	The attributes of the file.
Name	form	string	No	The name of the file without information on its directory path.

**FileBase** Parameters:
Name	Parameter	Data Type	Required	Description
Content	form	byte[]	No	The raw data content of the file.

**FileMetadata** Parameters:
Name	Parameter	Data Type	Required	Description
Name	form	string	No	The name of the file. For files, gets the name of the file. For directories, gets the name of the last directory in the hierarchy if a hierarchy exists; otherwise, the name of the directory.
FullName	form	string	No	The full path of the directory or file.
LastAccessTime	form	DateTime	No	The time the current file or directory was last accessed.
LastAccessTimeUtc	form	DateTime	No	The name of the file.
LastWriteTime	form	DateTime	No	The time when the current file or directory was last written to.
LastWriteTimeUtc	form	DateTime	No	The time, in coordinated universal time (UTC), when the current file or directory was last written to.
Length	form	long	No	The size, in bytes, of the current file.
UserId	form	int	No	The size, in bytes, of the current file.
GroupId	form	int	No	The file group id.
OthersCanRead	form	bool	No	A value that indicates whether the others can read from this file.
GroupCanExecute	form	bool	No	A value that indicates whether the group members can execute this file.
GroupCanWrite	form	bool	No	A value that indicates whether the group members can write into this file.
GroupCanRead	form	bool	No	A value that indicates whether the group members can read from this file.
OwnerCanExecute	form	bool	No	A value that indicates whether the owner can execute this file.
OwnerCanWrite	form	bool	No	A value that indicates whether the owner can write into this file.
OwnerCanRead	form	bool	No	A value that indicates whether the owner can read from this file.
OthersCanExecute	form	bool	No	A value that indicates whether others can read from this file.
OthersCanWrite	form	bool	No	A value that indicates whether others can write into this file.
Extensions	form	Dictionary<string, string>	No	Extensions to the file attributes.

To override the Content-type in your clients, use the HTTP Accept Header, append the .jsv suffix or ?format=jsv

HTTP + JSV

The following are sample HTTP requests and responses. The placeholders shown need to be replaced with actual values.

POST /sync/elma/protocols/retrieve HTTP/1.1 
Host: reportfiling.pwc.de 
Accept: text/jsv
Content-Type: text/jsv
Content-Length: length

{
	searchCriteria: 
	{
		name: String,
		designation: CC
	},
	credential: 
	{
		id: String_String,
		certificate: 
		{
			id: String,
			content: String,
			description: String,
			tags: 
			[
				String
			]
		},
		authSteuernummer: String,
		accountId: String,
		password: String
	},
	stagingEnabled: False
}

HTTP/1.1 200 OK
Content-Type: text/jsv
Content-Length: length

{
	protocols: 
	[
		{
			id: String,
			schemaLocation: String,
			verfahren: CC,
			elmaKom: 
			{
				elmakomVersion: String,
				elmaHeader: 
				{
					datenArt: ELMA_CC,
					authSteuernummer: String,
					accountId: String,
					erstellungsDatum: 0001-01-01,
					kundeneigeneId: String,
					uuid: 00000000000000000000000000000000,
					verarbeitungslauf: PRODUKTIONSLAUF
				},
				elmaVerfahren: 
				{
					inhalt: {}
				}
			},
			elmaProtokoll: 
			{
				dateiname: String,
				authSteuernummer: String,
				accountId: String,
				verarbeitungsDatum: 0001-01-01,
				verarbeitungsZeit: 0001-01-01,
				status: ELMA_GLOBAL_UNBEKANNT,
				statusText: String,
				statusDetail: String,
				kundeneigeneId: String,
				uuid: 00000000000000000000000000000000
			},
			elmaFehler: 
			{
				dateiname: String,
				authSteuernummer: String,
				accountId: String,
				verarbeitungsDatum: 0001-01-01,
				verarbeitungsZeit: 0001-01-01,
				fehlerID: ELMA_GLOBAL_UNBEKANNT,
				fehlerText: String,
				fehlerProzess: String,
				kundeneigeneId: String,
				uuid: 00000000000000000000000000000000
			}
		}
	],
	files: 
	[
		{
			metadata: 
			{
				name: String,
				fullName: String,
				lastAccessTime: 0001-01-01,
				lastAccessTimeUtc: 0001-01-01,
				lastWriteTime: 0001-01-01,
				lastWriteTimeUtc: 0001-01-01,
				length: 0,
				userId: 0,
				groupId: 0,
				othersCanRead: False,
				groupCanExecute: False,
				groupCanWrite: False,
				groupCanRead: False,
				ownerCanExecute: False,
				ownerCanWrite: False,
				ownerCanRead: False,
				othersCanExecute: False,
				othersCanWrite: False,
				extensions: 
				{
					String: String
				}
			},
			name: String,
			content: AA==
		}
	],
	responseStatus: 
	{
		errorCode: String,
		message: String,
		stackTrace: String,
		errors: 
		[
			{
				errorCode: String,
				fieldName: String,
				message: String,
				meta: 
				{
					String: String
				}
			}
		],
		meta: 
		{
			String: String
		}
	}
}