Automation Guide

Introduction

This guide provides a comprehensive overview of how to automate your efsta Cloud Portal operations using our REST API. The API follows a hierarchical structure where Organizations contain Companies, which contain Locations, which contain Registers.

System Hierarchy

🏢 Organization (O)
├── 🏪 Company (C)
    ├── 📍 Location (L)
        └── 🖥️ Register (E)

Key Concepts

API Key Authentication: All requests require a valid API key
Permission-Based Access: Operations require specific permissions
Hierarchical Structure: Parent-child relationships between entities

Authentication & Setup

1. Get Your API Key

Before starting, ensure you have a valid API key for authentication. If you do not yet have an API key, you can request one from an organization via the portal.

2. Test Authentication

GET /User/Active
Headers:
  api_key: your-api-key-here

3. Create Organization

Start by creating the top-level organization structure. Since this only happens once per country, it can also be done via the portal.

POST /Organization
Content-Type: application/json
api_key: your-api-key-here

{
  "ownerCompanyId": 1,
  "name": "My Retail Chain",
  "address": "123 Business Street",
  "city": "Berlin",
  "zip": "10115",
  "countryCode": "DE",
  "invoiceEmailAddress": "billing@mycompany.com"
}

🔐 Required Permission: ManageCompany on the owner company

Onboarding Process

Step 1: Create Company

Creates a company under your organization.

POST /Company
Content-Type: application/json
api_key: your-api-key-here

{
  "ownerCompanyId": {organizationId},
  "name": "Store Location Berlin",
  "address": "456 Store Avenue",
  "city": "Berlin",
  "zip": "10115",
  "countryCode": "DE",
  "taxId": "DE123456789",
  "taxIdType": "VAT",
  "invoiceEmailAddress": "berlin@mycompany.com",
  "countryProperties": {
    "DE_WIdNr": "DE123456789-00001"
  }
}

info

The field countryProperties is optional but the property DE_WIdNr will be a mandatory field for german companies as of 01.01.2027.

🔐 Required Permission: ManageCompany on the organization

Step 2: Create Location

Creates a location under your company.

POST /Location
Content-Type: application/json
api_key: your-api-key-here

{
  "ownerCompanyId": {companyId},
  "name": "Main Store Berlin",
  "address": "456 Store Avenue",
  "city": "Berlin",
  "zip": "10115",
  "countryCode": "DE"
}

🔐 Required Permission: ManageCompany on the company

Step 3: Add Company Contacts

Set up contact persons for the company.

POST /Company/Contact
Content-Type: application/json
api_key: your-api-key-here

{
  "companyId": {companyId},
  "realName": "John Doe",
  "emailAddress": "john.doe@mycompany.com",
  "phoneNumber": "+49 30 12345678",
  "contactType": "TechnicalContact"
}

Contact Types: InvoiceContact, TechnicalContact, CommercialContact, ElsterContact

Step 4: Invite Users

Invite users to access the company with specific roles.

POST /User/Invite
Content-Type: application/json
api_key: your-api-key-here

{
  "companyId": {companyId},
  "emailAddress": "manager@mycompany.com",
  "role": "ADMIN"
}

info

Permissions are inherited downwards in the hierarchy.

Available Roles:

ADMIN: Full system access (ReadCompany, ManageCompany, ManageRegister, ManageUsers, ManageBill, Purchase, ExportData, ReadRegister)
EDITOR: Management without purchasing (ReadCompany, ManageCompany, ManageRegister, ManageUsers, ManageBill, ExportData, ReadRegister)
DATAFISCAL: Basic company management and export fiscal data (ReadCompany, ManageCompany, ReadRegister, ExportData)
DATAVIEWER: Read-only with export fiscal data (ReadCompany, ReadRegister, ExportData)
FISCAL: Basic company management (ReadCompany, ManageCompany, ReadRegister)
VIEWER: Read-only access (ReadCompany, ReadRegister)

Step 5: Purchase Products (Optional)

If you need to purchase products for your setup.

POST /Purchase
Content-Type: application/json
api_key: your-api-key-here

{
  "companyId": {companyId},
  "invoiceCompanyId": {companyId},
  "recipientEmailAddress": "admin@mycompany.com",
  "recipientEmailRealName": "Admin User",
  "customerReference": "AUTO-SETUP-2024",
  "items": [
    {
      "id": {productId},
      "amount": 1,
      "amountAssignment": "Register"
    }
  ]
}

Information

For more information about the items, please contact efsta support.

Management Operations

Viewing Data

🌳 Get Company Tree Structure

GET /Company/{companyId}/Tree?getOrganizations=true&getCompanies=true&getLocations=true&getRegisters=true
api_key: your-api-key-here

🔍 Search for Entities

PUT /Company/Search
Content-Type: application/json
api_key: your-api-key-here

{
  "searchText": "Berlin",
  "limit": 50,
  "offset": 0,
  "orderByField": "name",
  "orderDescending": false
}

🔔 Get Company Notifications

GET /Company/{companyId}/Notifications?languageCode=en-US
api_key: your-api-key-here

Updating Data

✏️ Update Company Information

PUT /Company/{companyId}
Content-Type: application/json
api_key: your-api-key-here

{
  "name": "Updated Company Name",
  "address": "New Address",
  "city": "New City",
  "zip": "12345",
  "countryCode": "DE",
  "taxId": "DE987654321",
  "invoiceEmailAddress": "new-billing@mycompany.com",
  "countryProperties": {
    "DE_WIdNr": "DE123456789-00001"
  }
}

info

The field countryProperties is optional but the property DE_WIdNr will be a mandatory field for german companies as of 01.01.2027.

📍 Update Location

PUT /Location/{locationId}
Content-Type: application/json
api_key: your-api-key-here

{
  "name": "Updated Location Name",
  "address": "New Location Address",
  "city": "New City",
  "zip": "54321",
  "countryCode": "DE"
}

Register Management

🔍 Search Registers

PUT /Register/Search
Content-Type: application/json
api_key: your-api-key-here

{
  "searchText": "REG-001",
  "ownerCompanyId": {companyId},
  "limit": 100,
  "offset": 0
}

🔄 Update Register Software

PUT /Register/{registerNumber}/UpdateSoftware/{release}
api_key: your-api-key-here

User Management

👤 Get Company Users

GET /User/Invited?companyId={companyId}
api_key: your-api-key-here

Data Export

🚀 Start Export

POST /Export/{companyId}
Content-Type: application/json
api_key: your-api-key-here

{
  "registerNumber": "00000004ZP6",
  "from": "2024-01-01T00:00:00Z",
  "till": "2024-12-31T23:59:59Z",
  "exportType": "Journal_Archive_Json"
}

Export Types:

Journal_Archive_Json
Transactions_CS
AT_DEP_7_RKSV
AT_DEP_131_BAO
DE_DSFinVK
DE_TSE_Export_Journal
DE_GoBD
FR_Fiscal
FR_Grand_Totals
PT_SAFT
SI_Export

📋 Get Export List

GET /Export/{companyId}/List
api_key: your-api-key-here

💾 Download Export

GET /Export/{ticketNr}
api_key: your-api-key-here

Fiscal Operations (Germany)

📊 Get Reporting List

GET /Fiscal/DE/Reporting/List/{companyId}
api_key: your-api-key-here

📈 Get Reporting Data

GET /Fiscal/DE/Reporting/Data/{guid}
api_key: your-api-key-here

📝 Create and Submit Report

POST /Fiscal/DE/Reporting/{guid}?acceptDisclaimer=true
api_key: your-api-key-here

📊 Get Report State

GET /Fiscal/DE/Reporting/State/{guid}
api_key: your-api-key-here

📄 Download Report

GET /Fiscal/DE/Reporting/{guid}?acceptDisclaimer=true
api_key: your-api-key-here

Offboarding Process

Step 1: Deactivate Registers

PUT /Register/{registerNumber}/Deactivate?deactivateAfterYear=2024
api_key: your-api-key-here

info

If "deactivateAfterYear" is not sent, then the register is deactivated immediately.
Registers must not be in "DATA_PENDING" state
Main Registers with active subregisters cannot be deactivated
Already deactivated registers cannot be reanimated

Step 2: Deactivate Locations

PUT /Location/{locationId}/Deactivate?deactivateAfterYear=2024&forceSubDeactivation=true
api_key: your-api-key-here

info

If "deactivateAfterYear" is not sent, then the register is deactivated immediately.
If "forceSubDeactivation" is sent, all subordinate entities will also be deactivated

Step 3: Deactivate Companies

PUT /Company/{companyId}/Deactivate?deactivateAfterYear=2024&forceSubDeactivation=true
api_key: your-api-key-here

info

If "deactivateAfterYear" is not sent, then the register is deactivated immediately.
If "forceSubDeactivation" is sent, all subordinate entities will also be deactivated

Step 4: Remove User Access

Remove user access from companies.

DELETE /User/DeleteAccess?companyId={companyId}&userId={userId}
api_key: your-api-key-here

info

The rights will also be deleted at all structures below.
Rights inherited from above cannot be deleted.

Advanced Features

🛡️ Permission Testing

Test user permissions before performing operations.

GET /Permission/{companyId}?permissionType=ManageCompany
api_key: your-api-key-here

Available Permission Types:

ReadCompany: View company information
ManageCompany: Edit company settings
ReadRegister: View register information
ManageRegister: Configure registers
Purchase: Place purchases
ExportData: Export archive data
ManageUsers: Manage users
ManageBill: Manage billing configurations

Get the complete organizational hierarchy.

GET /Company/{companyId}/Tree?getOrganizations=true&getCompanies=true&getLocations=true&getRegisters=true
api_key: your-api-key-here

🛒 Purchase Management

View purchase history and manage orders.

GET /Purchase/{companyId}/List?fromDate=20240101&tillDate=20241231
api_key: your-api-key-here

Best Practices

1. Error Handling

Always check response status codes and handle errors gracefully:

{
  "success": false,
  "errorCode": "PERMISSION_DENIED",
  "errorMessage": "Insufficient permissions to perform this operation"
}

2. Pagination

Use pagination for large result sets:

{
  "limit": 100,
  "offset": 0,
  "orderByField": "name",
  "orderDescending": false
}

3. Rate Limiting

Implement appropriate delays between requests to avoid rate limiting.

4. Data Validation

Always validate input data before sending requests.

5. Logging

Log all API interactions for debugging and audit purposes.

Common Validation Scenarios

Example Company Creation Validation

// Valid request
{
  "ownerCompanyId": 1234,
  "name": "My Company",
  "address": "123 Main Street",
  "city": "Berlin",
  "zip": "10115",
  "countryCode": "DE",
  "taxId": "DE123456789",
  "taxIdType": "VAT"
}

//  Invalid request - Missing required fields
{
  "ownerCompanyId": 0,        // Must be >= 2
  "name": "",                 // Required, min length 2
  "countryCode": "INVALID"    // Must be exactly 2 characters
}

Validation Response:

{
  "success": false,
  "errorCode": "VALIDATION_FAILED",
  "errorMessage": "One or more validation errors occurred.",
  "validationErrors": {
    "OwnerCompanyId": ["Value must be at least 2."],
    "Name": ["Value is required and must be at least 2 characters long."],
    "CountryCode": ["Value must be exactly 2 characters long."]
  }
}

Validation Error Codes

Error Code	Description	Common Causes
`VALIDATION_FAILED`	Custom validation rules failed	Business logic violations, invalid data formats
`MODEL_VALIDATION_FAILED`	Model binding or attribute validation failed	Missing required fields, invalid data types
`BAD_Request`	General request format issues	Malformed JSON, missing parameters

Debugging Validation Issues

Check the validationErrors object for specific field errors
Verify data types match the expected format
Ensure required fields are present and not empty
Validate string lengths against MinLength/MaxLength constraints
Check allowed values for enum-like fields
Verify email formats for email fields
Test with minimal valid data first, then add complexity

Error Handling

Common Error Codes

Error Code	Description	Action
`ACCESS_DENIED`	Invalid API key or access grant	Check API key validity
`PERMISSION_DENIED`	Insufficient permissions	Verify user permissions
`COMPANY_NOT_FOUND`	Company ID doesn't exist	Check company ID
`VALIDATION_FAILED`	Request data validation failed	Check request format
`REGISTER_NOT_FOUND`	Register number doesn't exist	Verify register number
`EXPORT_TICKET_NOT_FOUND`	Export ticket doesn't exist	Check ticket number

📊 HTTP Status Codes

Status	Meaning	Description
200	OK	Operation successful
400	Bad Request	Invalid request data
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
409	Conflict	Business rule violation
422	Unprocessable Entity	Validation failed

Conclusion

This guide provides a comprehensive overview of automating your efsta Cloud Portal operations. Remember to:

Always test with small datasets first
Implement proper error handling
Follow the hierarchical structure (Organization → Company → Location → Register)
Respect permission requirements
Keep your API keys secure

For additional support or questions, please refer to the full API documentation or contact our support team.

Introduction​

System Hierarchy​

Key Concepts​

Authentication & Setup​

1. Get Your API Key​

2. Test Authentication​

3. Create Organization​

Onboarding Process​

Step 1: Create Company​

Step 2: Create Location​

Step 3: Add Company Contacts​

Step 4: Invite Users​

Step 5: Purchase Products (Optional)​

Management Operations​

Viewing Data​

🌳 Get Company Tree Structure​

🔍 Search for Entities​

🔔 Get Company Notifications​

Updating Data​

✏️ Update Company Information​

📍 Update Location​

Register Management​

🔍 Search Registers​

🔄 Update Register Software​

User Management​

👤 Get Company Users​

Data Export​

🚀 Start Export​

📋 Get Export List​

💾 Download Export​

Fiscal Operations (Germany)​

📊 Get Reporting List​

📈 Get Reporting Data​

📝 Create and Submit Report​

📊 Get Report State​

📄 Download Report​

Offboarding Process​

Step 1: Deactivate Registers​

Step 2: Deactivate Locations​

Step 3: Deactivate Companies​

Step 4: Remove User Access​

Advanced Features​

🛡️ Permission Testing​

🌳 Company Tree Navigation​

🛒 Purchase Management​

Best Practices​

1. Error Handling​

2. Pagination​

3. Rate Limiting​

4. Data Validation​

5. Logging​

Common Validation Scenarios​

Example Company Creation Validation​

Validation Error Codes​

Debugging Validation Issues​

Error Handling​

Common Error Codes​

📊 HTTP Status Codes​

Conclusion​

Introduction

System Hierarchy

Key Concepts

Authentication & Setup

1. Get Your API Key

2. Test Authentication

3. Create Organization

Onboarding Process

Step 1: Create Company

Step 2: Create Location

Step 3: Add Company Contacts

Step 4: Invite Users

Step 5: Purchase Products (Optional)

Management Operations

Viewing Data

🌳 Get Company Tree Structure

🔍 Search for Entities

🔔 Get Company Notifications

Updating Data

✏️ Update Company Information

📍 Update Location

Register Management

🔍 Search Registers

🔄 Update Register Software

User Management

👤 Get Company Users

Data Export

🚀 Start Export

📋 Get Export List

💾 Download Export

Fiscal Operations (Germany)

📊 Get Reporting List

📈 Get Reporting Data

📝 Create and Submit Report

📊 Get Report State

📄 Download Report

Offboarding Process

Step 1: Deactivate Registers

Step 2: Deactivate Locations

Step 3: Deactivate Companies

Step 4: Remove User Access

Advanced Features

🛡️ Permission Testing

🌳 Company Tree Navigation

🛒 Purchase Management

Best Practices

1. Error Handling

2. Pagination

3. Rate Limiting

4. Data Validation

5. Logging

Common Validation Scenarios

Example Company Creation Validation

Validation Error Codes

Debugging Validation Issues

Error Handling

Common Error Codes

📊 HTTP Status Codes

Conclusion