Overview
The HANFA Integration allows your organization to automatically synchronize user licence information and educational records with the Croatian Financial Services Supervisory Agency (HANFA) API.
This integration uses secure mTLS (Mutual Transport Layer Security) authentication to ensure data is transmitted safely.
Accessing HANFA Integration Settings
Navigate to Organization Settings
Click on the Integrations tab
Locate the HANFA Integration panel
The integration status is displayed in the top-right corner:
🟢 Connected - Integration is active and configured
🟡 Not Connected - Integration needs configuration
Configuration Settings
1. HANFA API Base URL
Field: Base URL
Example: <https://api.hanfa.hr>
Description: The base endpoint URL for the HANFA API server. This URL is provided by HANFA and should be entered exactly as received in your integration documentation.
Required: ✅ Yes
Notes:
Must include the protocol (
<https://)>Do not include trailing slashes
Contact HANFA technical support if you don't have this URL
2. mTLS Certificate (.p12/.pfx)
Field: Certificate File Upload
Accepted formats: .p12, .pfx
Description:
This is the client certificate file used for mutual TLS authentication with the HANFA API. The certificate proves your organization's identity when communicating with HANFA servers.
Required: ✅ Yes (for initial setup)
How to use:
Click Choose File or Browse
Select the
.p12or.pfxcertificate file provided by HANFAThe file will be uploaded when you save the configuration
Notes:
Security: The certificate is stored securely on the server and encrypted
Current Certificate: If a certificate is already uploaded, you'll see a message showing the filename (e.g., "Current Certificate: hanfa_cert.p12")
Updating: To replace the certificate, simply upload a new file
Backup: Keep a secure backup copy of your certificate file
3. Certificate Password
Field: Certificate Password
Type: Password (masked)
Description:
The password that protects your mTLS certificate file. This password was set when the certificate was created by HANFA.
Required: ✅ Yes (for initial setup)
How to use:
Enter the password exactly as provided by HANFA
The password is masked with dots (••••) for security
Once saved, the password is encrypted and stored securely
Notes:
Already configured? If a password is already saved, you'll see: (encrypted)
Leave empty to keep existing password: When updating other settings, you don't need to re-enter the password
Forgotten password? Contact HANFA to issue a new certificate with a new password
4. Sync Licence Date from HANFA
Field: Toggle switch (ON/OFF)
Default: OFF
Description: When enabled, the system will automatically fetch and update user licence expiration dates from the HANFA API during synchronization.
How it works:
ON (Enabled):
During HANFA sync, the system queries HANFA for each user's licence status
User licence dates in SmartArena are automatically updated to match HANFA records
Ensures licence information is always current with HANFA's database
OFF (Disabled):
Licence dates are managed manually within SmartArena
No automatic updates from HANFA
Educational records are still synchronized
When to enable:
✅ Your organization wants HANFA to be the single source of truth for licence dates
✅ You have many users and manual licence management is time-consuming
✅ Licence dates change frequently and need to stay synchronized
When to disable:
❌ You manage licence dates internally and don't want HANFA to override them
❌ You're still testing the integration and want to prevent automatic updates
❌ Your organization has specific licence date requirements that differ from HANFA
5. Admin Email
Field: Email Address
Example: [email protected]
Description:
The email address where HANFA integration error notifications and alerts will be sent. This ensures your technical team is notified immediately if synchronization issues occur.
Required: ✅ Yes
Notifications sent to this address:
🔴 Sync Errors: Failed synchronization attempts with HANFA API
🔴 Authentication Failures: Certificate or connection issues
🔴 Data Validation Errors: When data doesn't meet HANFA requirements
⚠️ Warning Messages: Non-critical issues that may need attention
Best practices:
Use a monitored email address or distribution list
Consider using a team inbox (e.g.,
[email protected])Set up email filters to prioritize HANFA notifications
Regularly review notifications to catch issues early
Testing the Connection
Before saving your configuration, you can verify that the settings are correct using the Test Connection button.
How to Test:
Fill in all required fields (Base URL, Certificate, Password)
Click the Test HANFA Connection button
The system will attempt to connect to HANFA using the provided credentials
Wait for the test result (usually 5-15 seconds)
Test Results:
✅ Success:
Message: "Connection successful" or "HANFA connection successful"
Green alert box
Indicates: Your certificate, password, and URL are correct
Next step: Click Save to apply the configuration
❌ Failed:
Message: "Connection test failed" or specific error details
Red alert box
Common causes:
Incorrect certificate password
Invalid or expired certificate
Wrong API Base URL
Network connectivity issues
HANFA API server is down
Troubleshooting failed tests:
Double-check the certificate password (most common issue)
Verify the Base URL is exactly as provided by HANFA
Ensure the certificate file is not corrupted
Try re-uploading the certificate file
Contact HANFA technical support if issues persist
Saving the Configuration
Once all fields are configured and the connection test is successful:
Click the Save button at the bottom of the panel
A loading spinner will appear while settings are saved
You'll see a success notification: "HANFA integration settings updated successfully"
The page will redirect back to the Integrations overview
The HANFA integration status will change to Connected 🟢
Important:
All settings must be valid for the save to succeed
The system validates certificate format and password strength
If save fails, check the error message and correct the highlighted fields
How HANFA Synchronization Works
Once configured, the HANFA integration operates automatically:
1. User Licence Synchronization
System periodically queries HANFA API for licence status updates
User records with matching National ID (OIB) are updated
Licence expiration dates are synchronized (if enabled)
2. Educational Records Submission
When users complete courses, completion records are sent to HANFA
Each record includes:
User identification (OIB)
Course/education type
Completion date
Duration (in minutes)
Lecturer/instructor information
Additional notes (if configured)
3. Error Handling
Failed synchronization attempts are logged
Admin email receives notifications of errors
System automatically retries failed submissions
Detailed error logs are available for troubleshooting
Required User Information
For HANFA synchronization to work, users must have the following information in their SmartArena profile:
National ID (OIB)
Field: National ID
Format: 7-20 digits
Required: ✅ Yes (without this, users cannot sync with HANFA)
Validation: Must be unique within your organization
Location: User profile → Personal Information
Important:
The National ID must match exactly with HANFA's records
Invalid or missing OIB will prevent synchronization for that user
Users without OIB will be skipped during sync (with warning logged)
Troubleshooting
Connection Issues
Problem: "Connection test failed"
Solutions:
Verify Base URL is correct
Check certificate file is not corrupted
Confirm certificate password is accurate
Ensure your network allows outbound HTTPS connections to HANFA
Check with your IT department about firewall rules
Certificate Issues
Problem: "Invalid certificate password or corrupted certificate file"
Solutions:
Re-enter the certificate password carefully
Re-download the certificate from HANFA if available
Contact HANFA to verify password or request new certificate
Check that the file format is
.p12or.pfx
Synchronization Failures
Problem: Users not syncing with HANFA
Solutions:
Verify users have valid National ID (OIB) filled in
Check that OIB format is correct (7-20 digits)
Ensure OIB matches HANFA's records exactly
Review error notifications sent to admin email
Check HANFA sync logs for specific error messages
Licence Date Not Updating
Problem: Licence dates aren't being updated from HANFA
Solutions:
Ensure "Sync Licence Date from HANFA" is toggled ON
Verify the user's OIB matches HANFA records
Check that the user exists in HANFA's database
Review sync logs for specific user errors
Confirm HANFA API is returning licence date data
Security Best Practices
Certificate Storage:
Never share your HANFA certificate file
Keep backup in secure, encrypted storage
Limit access to authorized personnel only
Password Management:
Don't share the certificate password
Store password in a secure password manager
Change password if compromise is suspected (requires new certificate from HANFA)
Admin Email:
Use a monitored email address
Set up alerts for HANFA notification emails
Regularly review error notifications
Access Control:
Only authorized administrators should access HANFA settings
Implement proper user permissions in SmartArena
Audit who has access to integration settings
Getting Help
HANFA Technical Support
For API access, certificate issues, or HANFA-specific questions
Contact information provided in your HANFA integration agreement
Smart Arena Support
For configuration help within SmartArena
Questions about user setup or synchronization
Integration troubleshooting
Documentation
HANFA Integration Setup: Technical implementation details
HANFA Mapping Configuration: Course and field mapping setup
HANFA Commands Reference: Command-line tools for sync management
Appendix: Configuration Checklist
Use this checklist when setting up HANFA integration:
[ ] Obtain HANFA API Base URL from HANFA
[ ] Receive mTLS certificate file (.p12 or .pfx) from HANFA
[ ] Receive certificate password from HANFA
[ ] Determine admin email for notifications
[ ] Decide whether to enable automatic licence date sync
[ ] Enter all configuration settings in SmartArena
[ ] Test connection successfully
[ ] Save configuration
[ ] Verify integration status shows "Connected"
[ ] Ensure users have National ID (OIB) filled in
[ ] Monitor admin email for sync notifications
[ ] Verify first synchronization runs successfully
[ ] Review sync logs for any errors
[ ] Document configuration details for your organization
Glossary
mTLS (Mutual TLS): A security protocol where both the client (SmartArena) and server (HANFA) authenticate each other using certificates.
OIB (Osobni identifikacijski broj): Croatian personal identification number used to uniquely identify individuals.
Certificate Password: The password that unlocks your encrypted certificate file, allowing the system to use it for authentication.
Base URL: The root address of the HANFA API server (e.g.,
<https://api.hanfa.hr).>Sync/Synchronization: The automated process of exchanging data between SmartArena and HANFA systems.
Licence Date: The expiration date of a user's professional licence as recorded by HANFA.