Integration Manual
1. Summary
The hAPI API is designed around REST principles. Our API features intuitive, resource-oriented URLs, accepts form-encoded request bodies, and returns JSON-encoded responses, utilizing standard HTTP response codes, authentication methods, and verbs.
You can utilize the hAPI API in test mode, ensuring no changes to your live data or interactions with external services. The API key used for authentication determines whether the request operates in live mode or test mode.
Please note that the hAPI API does not support bulk updates; you can only process one object per request.
The hAPI API may vary for each account as we continually release new versions and customize functionalities.
2. Integration Diagram
3. Iframe Integration
- To use our Iframe you can create a landing page on your infrastructure and simply add the code bellow script tag.
<script src="https://storage.googleapis.com/hapipublicresources/scripts/hapiiframe_current.js"</script>
- These code will read the URL parameters from your website and add them to the iframe.
- Add this script on the container that you want to insert the iframe, or use data-containerid attribute to insert the iframe inside that element.
<script src="https://storage.googleapis.com/hapipublicresources/scripts/hapiiframe_current.js" data-containerid="div-Id"</script>
- Parameters can be passed as data attributes (data-[parameter name] in the iframe script, similar to the data-clientuserguid example. These data attributes will override URL parameters.
<script src="https://storage.googleapis.com/hapipublicresources/scripts/hapiiframe_current.js" data-clientuserguid="xxxxxxxx-xxxxxx-xxxxxxx-xxxxxxxx"data-guid="zzzzzz-zzzzz-zzzzz"></script>
https://exampleSite.com?clientuserguid=xxxxxxx-xxxxxx-xxxxxxx-xxxxxxxx&guid=zzzzzz-zzzzz-zzzzz
4. Parameters
Guid – Text that is used to identify the process and is returned on the callback. (Minimum 10 characters)
NIF – NIF to pre fill the form with the Tax Number
NISS – NISS to pre fill the form with the Social Security number
cmdPhoneNumber – Phone number to pre fill the form with the Chave Móvel Digital number
callerLogLevel2 – Used to identify the client or department (usefull in reports and to split costs and reports)
isTestMode – Used to test. If True the form are disabled. Just press the Authenticate button and you can use mock data
clientUserGUID – Id that identifies your user. Ask one to hAPI team. If you add it on the script below you don’t need to add it on the page URL.
clientId – Id that identifies you as hAPI client. Ask yours to hAPI team. If you add it on the script below you don’t need to add it on the page URL.
sourceURL – Used to identify the full URL from the main page, when used on Iframe.
data-containerid – Id of the HTML element where you want to place the iframe. If not set will add to the body.
StepsConfig – String that allows to configure the screen elements display. Could be 1 2 or 3 to show AT (1), SS (2), Upload docs (3). Ex: If set as 13 it will show only AT and Upload docs steps.
<script src="https://storage.googleapis.com/hapipublicresources/scripts/hapiiframe_current.js"</script>
5. JSON information
For detailed information on JSON responses and the structure of our API, clients can refer to our comprehensive documentation available at hAPI Swagger UI here
This resource provides clear examples and specifications for all endpoints, ensuring that you have the necessary guidance to effectively integrate and utilize our services
6. Attachments Information
Our API service facilitates the collection of various documents. For a complete overview of all documents collected by our API service, please visit the provided link containing dummy documents for demonstration purposes only.
These documents are not representative of real data but serve as examples to help you understand the types of information our API can handle
Below is a comprehensive list of all document types collected by our service:
BankAccountsDataBaseCertificate.pdf - more info
BuildingBookCertificate.pdf - more info
CentralCreditRegisterCertificate.pdf - more info
EnergyCertificatePDFResume.pdf - more info
FamilyHouseHoldCertificate.pdf - more info
HouseRentContractReceiptCertificate.pdf - more info
IRSNonDebtCertificate.pdf - more info
InsolvencyProceedingPDF.pdf - more info
NegativeLandRegistryCertificate.pdf - more info
PDFATIbanProof.pdf - more info
PDFOfPersonalTaxData.pdf - more info
PDFOfTheFirstSalary.pdf - more info
PDFOfTheLastSalary.pdf - more info
PDFSSIbanProof.pdf - more info
TaxAddressCertificate.pdf - more info
TaxDeclarationCertificate_year.pdf - more info
TaxLiquidationDeclarationCertificate_year.pdf - more info
PersonalDataSSCertificate.pdf - more info
MonthlyContributoryCareerCertificate_year.pdf - more info
YearlyContributoryCareerCertificate_year.pdf - more info
7. Users Test
To facilitate user testing, clients can enable test mode by using the parameter &IsTestMode=true. Additionally, if needed, clients can include the parameters NIF and NISS to specify user identification
We have configured in our container 5 different users with different data
NIF=144080540&NISS=12345678901
NIF=185936059&NISS=11321856271
NIF=245896660&NISS=10987654321
NIF=112123031&NISS=11121230311
NIF=531489957&NISS=25314899575
This setup allows for safe testing without affecting live data, ensuring a seamless experience during the development phase.
8. Available Configurations
Email: The email address associated with the client, used for communication and notifications. If filled in, all processes will be sent to this email.
Intro HTML: Custom HTML content used for introductory messages or information displayed to the client. This text will appear on top of the page, after the header.
Text Consent AT: Text that describes consent requirements specific to Tax Authority.
Text Consent SS: Text that describes consent requirements specific to Social Security (SS).
Cookies Policy HTML Content: The HTML content outlining the client’s cookie policy.
Consent Main Block Title: The title for the main consent section, which outlines user permissions and agreements.
Text Consent Main Block: Detailed text regarding the consent terms presented to the user.
Process Conclusion Text: A message displayed to the client upon completion of a process.
Client URL Page: The URL that directs to the client-specific page within the application. The Landing page that have the Iframe
Is Show Steps after Previous Success: Determines if the next steps should be displayed after a successful action. If true the SS login will only appear after AT successful Login, and Additional Documents after SS successful login.
Is Show Cookies Policy: Indicates whether the cookies policy should be shown to the client.
Get Last Tax Declaration With Liquidation Proof: A toggle for retrieving the last tax declaration along with proof of liquidation. If true, and the last tax declaration don’t have liquidation declaration, we will try to collect the previous year one is Get Tax Declaration With Liquidation Proof (need getTaxDeclarationLiquidationRelation service active).
Get Two Tax Declarations: If checked, our service will attempt to collect the last two tax declarations for the client.
Use Single and No Dependents as Default: Specifies whether the default setting should apply to single clients without dependents. If set to true, our service will use “single and no dependents” to calculate net salary in cases where family household information is missing.
Has CMD Login on AT: Indicates if the client has Chave Móvel Digital login for Tax Authority.
Has CMD Login on SS: Indicates if the client has Chave Móvel Digital login for Social Security.
Is CMD Default Option: Specifies if Chave Móvel Digital is the default option for the client.
Number of Months of Income to Return: Defines how many months of income data should be returned for the client. If ‘6’ we will grab information of incomes and payments from last 6 months.
Number of Months to Get Expenses: Specifies how many months of expense data should be retrieved. If ‘6’ we will grab information of expenses from last 6 months.
Green Receipts Months Number: The number of months for which green receipts should be considered. If ‘6’ we will grab information of green receipts and invoices from last 6 months.
Remove Fields: A field that allows specifying which fields should be removed from JSON outputs.
Waiting Time Before Send Data (in Seconds): The time to wait before sending data, measured in seconds.
Page Redirect URL: The URL to redirect the client after the successful login.
Data Endpoint: The endpoint used for data retrieval or submission, where we will deliver information on clients servers.
Data Endpoint User: The username associated with the data endpoint.
Data Endpoint Token: The token used for authenticating requests to the data endpoint.
Data Encryption Password: The password used for encrypting client data.
Iframe Domains Allowed: A list of domains permitted to embed content via iframe.
9. Callback Configuration
The information will be sent after X (configurable) seconds. If we take more than that time, we will send a second third … package will all the information collected (its cumulative).
Email subject will be the users NIF;
Information can be encrypted with a shared password. In these case, the subject will be the process ID.
We will create a zip file with the name processID_YYYYMMDDHHMMSS
The ZIP file will be sent the the body as a binary;
The processId (GUID) will be sent as a “guid” parameter at the end of the URL and on the Header as “CallerProcessId”
The Content-Type will be application/zip. The Accept-Encoding nad Accept-Language will be sent as *
The request will be sent by our server with fixed IP
10. CSS customization
CSS can be customized by us, or if you prefer you can send us a CSS link and we add it to our iframe page.