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"
}

🔐 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"
}

📍 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

🌳 Company Tree Navigation

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

1. Check the validationErrors object for specific field errors
2. Verify data types match the expected format
3. Ensure required fields are present and not empty
4. Validate string lengths against MinLength/MaxLength constraints
5. Check allowed values for enum-like fields
6. Verify email formats for email fields
7. 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:

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

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