Use Cases

All ceric use cases with scenarios description.

Overview

ceric supports three main use cases for processing ELSTER XML documents:

1. draft - Validate and preview XML documents without transmission

2. send - Validate and transmit documents with PDF generation

3. transmit - Transmit documents without PDF generation

For downloading data from the OTTER server, use the separate cotto binary.

Draft Use Case

Purpose

The draft use case validates XML documents and generates PDF previews without transmitting data to ELSTER servers. This is ideal for:

• Development and testing - Validate XML structure before production

• Client preview - Show customers what the final document will look like

• Quality assurance - Ensure XML meet ELSTER requirements

• Offline validation - Check documents without network connectivity

Command Syntax

ceric --pathXml <file> --dataType <type> [OPTIONS]

Examples

Basic Draft Operation

ceric --pathXml info.xml \
  --dataType Kontoinformation \
  --pathStorage /storage/ \
  --timestamp 202501011200450100

Draft with Custom Paths

ceric --pathXml examples/info.xml \
  --dataType Kontoinformation \
  --pathVendor /custom/eric/plugins/ \
  --pathStorage /custom/output/ \
  --timestamp 202501011200450100

PHP SDK Example

<?php
use Rechtlogisch\MiniEric\Ceric;
use Rechtlogisch\MiniEric\Dto\CericInput;

$ceric = new Ceric();
$result = $ceric->draft(new CericInput(
    dataType: 'Kontoinformation',
    pathXml: 'info.xml',
    pathStorage: '/storage/',
    timestamp: '202501011200450100'
));

if ($result->cericOutput->exitCode === '0') {
    echo "PDF generated: " . $result->cericOutput->pathOutputFile;
} else {
    echo "Error: " . $result->cericOutput->message;
}

Output

• PDF file - Generated preview document

• XML with header - Enhanced XML with ERiC header

• Validation results - Structured error and hint information

Send Use Case

Purpose

The send use case validates XML documents, transmits data to ELSTER servers, and generates PDFs. This is used for:

• Production submissions - Send official tax documents

• Client confirmations - Provide PDF receipts to clients

• Audit trails - Maintain records of transmitted documents

• Compliance - Meet regulatory requirements

Prerequisites

• Valid ELSTER certificate - Required for authentication

• Network connectivity - Must connect to ELSTER servers

• Proper data type - Must support print operations

Command Syntax

ceric --usecase send --pathXml <file> --dataType <type> [OPTIONS]

Examples

Basic Send Operation

ceric --pathXml info.xml \
  --dataType Kontoinformation \
  --usecase send \
  --pathStorage /storage/ \
  --timestamp 202501011200450100

Send with Environment Variables

export PATH_CERTIFICATE="/path/to/certificate.pfx"
export CERTIFICATE_PIN="your_pin"

ceric --pathXml info.xml \
  --dataType Kontoinformation \
  --usecase send \
  --pathStorage /storage/

Note: For complete environment variable configuration, see Environment Variables.

PHP SDK Example

<?php
use Rechtlogisch\MiniEric\Ceric;
use Rechtlogisch\MiniEric\Dto\CericInput;

$ceric = new Ceric();
$result = $ceric->send(new CericInput(
    dataType: 'Kontoinformation',
    pathXml: 'info.xml',
    pathStorage: '/storage/',
    timestamp: '202501011200450100'
));

if ($result->cericOutput->exitCode === '0') {
    echo "Document sent successfully!";
    echo "PDF: " . $result->cericOutput->pathOutputFile;
    echo "Server response: " . $result->cericOutput->serverResponse;
} else {
    echo "Send failed: " . $result->cericOutput->message;
}

Output

• PDF file - Generated confirmation document

• XML with header - Enhanced XML with ERiC header

• Process result - ERiC processing information

• Server response - ELSTER server confirmation

Transmit Use Case

Purpose

The transmit use case validates XML documents and transmits data to ELSTER servers without generating PDFs. This is ideal for:

• Postfach operations - Data retrieval requests and confirmations

• High-volume processing - When PDF generation is not needed

• Automated workflows - System-to-system communication

• Performance optimization - Faster processing without PDF generation

Command Syntax

ceric --usecase transmit --pathXml <file> --dataType <type> [OPTIONS]

Examples

Basic Transmit Operation

ceric --pathXml inbox-31-list.xml \
  --dataType PostfachAnfrage_31 \
  --usecase transmit \
  --pathStorage /storage/

Transmit Commercial Registration

ceric --pathXml gan.xml \
  --dataType Gewerbemeldung \
  --usecase transmit \
  --pathStorage /storage/

PHP SDK Example

<?php
use Rechtlogisch\MiniEric\Ceric;
use Rechtlogisch\MiniEric\Dto\CericInput;

$ceric = new Ceric();
$result = $ceric->transmit(new CericInput(
    dataType: 'PostfachAnfrage_31',
    pathXml: 'inbox-31-list.xml',
    pathStorage: '/storage/'
));

if ($result->cericOutput->exitCode === '0') {
    echo "Transmission successful!";
    echo "Server response: " . $result->cericOutput->serverResponse;
} else {
    echo "Transmission failed: " . $result->cericOutput->message;
}

Output

• XML with header - Enhanced XML with ERiC header

• Process result - ERiC processing information

• Server response - ELSTER server confirmation

• No PDF file - PDF generation is skipped

Download usecase (cotto binary)

Purpose

The download functionality is provided by the separate cotto binary, which retrieves data from the OTTER server using an object UUID. This is used for:

• Protocol retrieval - Download processing protocols

• Status checking - Verify document processing status

• Audit purposes - Access historical data

Command Syntax

cotto --objectUuid <uuid> [OPTIONS]

Examples

Basic Download Operation

cotto --objectUuid 41a42915-d8ba-45c7-89e6-6b875a853fc4 \
  --pathStorage /storage/

Download with Custom File Extension

cotto --objectUuid 41a42915-d8ba-45c7-89e6-6b875a853fc4 \
  --pathStorage /storage/ \
  --fileExtension xml

PHP SDK Example

<?php
use Rechtlogisch\MiniEric\Ceric;
use Rechtlogisch\MiniEric\Dto\CottoInput;

$ceric = new Ceric();
$result = $ceric->download(new CottoInput(
    objectUuid: '41a42915-d8ba-45c7-89e6-6b875a853fc4',
    pathStorage: '/storage/',
    fileExtension: 'xml'
));

if ($result->cericOutput->exitCode === '0') {
    echo "Download successful!";
    echo "File: " . $result->cericOutput->pathOutputFile;
} else {
    echo "Download failed: " . $result->cericOutput->message;
}

Output

• Downloaded file - Retrieved data file

• Server response - Download confirmation

• Process result - Download operation details

Data Type Compatibility

Data Type	Draft	Send	Transmit
Kontoinformation	✅*	✅	✅
ElsterFSE_EUn_{version}	✅	✅	✅
Gewerbemeldung	✅*	✅	✅
PostfachAnfrage_{version}	❌	❌	✅
PostfachBestaetigung_{version}	❌	❌	✅

• Generated PDF does not contain so called user data, so the main part of the PDF is blank, just header, footer (and transfer ticket with submission date/time) in printed on the PDF

Scenarios

Registration for tax purposes (EUn)

# 1. Validate tax return (draft with PDF preview)
ceric --pathXml fse.xml --dataType ElsterFSE_EUn_202401 --pathStorage /storage/

# 2. Send tax return
ceric --usecase send --pathXml fse.xml --dataType ElsterFSE_EUn_202401 --pathStorage /storage/

Commercial Registration Workflow (GAN)

# 1. Transmit registration (no PDF needed)
ceric --usecase transmit --pathXml kmv-gan.xml --dataType Gewerbemeldung --pathStorage /storage/

# Save TransferTicket from serverResponse
# Wait for about 5 minutes in test enviroment (and multiple hours on production)

# 2. List available protocols
ceric --usecase transmit --pathXml inbox-31-list.xml --dataType PostfachAnfrage_31 --pathStorage /storage/

# Search for TransferTicket and extract ReferenzId (uuid) for document and Id (id starts with be...)

# 3. Download protocol
cotto --objectUuid <data-uuid> --pathStorage /storage/

# 4. Confirm data receipt using id (within 24 hours!)
ceric --pathXml inbox-31-confirm.xml --dataType PostfachBestaetigung_31 --usecase transmit --pathStorage /storage/

Error Handling

Common Error Scenarios

1. Invalid data type for usecase

   • Error: Data type print not supported

   • Solution: Use appropriate usecase (or data type)

2. Missing certificate for send operations

   • Error: Could not load certificate

   • Solution: Set PATH_CERTIFICATE and CERTIFICATE_PIN

3. Invalid UUID for download

   • Error: Invalid UUID format

   • Solution: Use valid UUID v4 format

4. Network issues for send/transmit

   • Error: Server response contains errors

   • Solution: Check network connectivity and firewall

Best Practices

1. Always validate first - Use draft mode before production operations

2. Handle errors gracefully - Check exit codes and provide meaningful messages

3. Use appropriate use cases - Choose the right use case for your needs

4. Monitor logs - Check eric.log and otto.log for detailed information

5. Test with examples - Use provided XML examples for testing

Related Topics

• CLI Reference - Complete command-line reference

• Error Codes - Detailed error code reference

• XML Examples - Ready-to-use XML examples