Welcome to our Integration Manual
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.
Integration Diagram
iFrame Information
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 parameters from your website URL or from script data-attributes 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="INSERT-YOUR-DIV-ID-HERE"</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="INSERT-YOUR-CLIENTUSERID-HERE" data-processId="INSERT-YOUR-PROCESSID-HERE"></script>
Example
https://exampleSite.com?clientUserGuid=dc9c06-gg1c3d4-2dcb0a-185e7a-0b9387c&processId=457f600322624a599da9e0d65c128b4e
Parameters
processId – 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 Post Messages
The message has a Process structure with this data:
{
"Process":{
"Id":"TESTMODEc6e0c4e84b238106d8c2f1910",
"IsProcessed":false,
"CreatedOn":"2025-10-18T09:37:50Z",
"IsReadyToSend":true,
"IsTestMode":true,
"isATLoginDone":true,
"isSSLoginDone":true,
"isBdPLoginDone":true,
"IsDocStepDone":false
},
"PersonalTaxData": {
"Nif": "112123031",
"Name": "ANTONIO MARIA MONTEIRO",
"Gender": "MASCULINO",
"BirthDate": "1983-10-27T00:00:00Z",
"Nationality": "PORTUGUESA",
"FinanceService": {
"Number": "123122232",
"Location": "Belas"
},
"Address": {
"Street": "Avenida Maria Luísa Costa Machado Faria e Maia N.20",
"PostalCode": "9560-314 Cabouco",
"Country": "PORTUGAL",
"CountryAlpha3Code": "PRT",
},
"Contacts": {
"Email": "<span
data-original-string='4NYUwwocb8soijYFDoX0cA==7acNXCNiffQ2mRLO3G/nGjWYkq2HTRSdVkB3nrT1mG0UQ8='
class='apbct-email-encoder'
title='This contact has been encoded by Anti-Spam by CleanTalk. Click to decode. To finish the decoding make sure that JavaScript is enabled in your browser.'>an<span class="apbct-blur">**************</span>@<span class="apbct-blur">***</span>il.com</span>",
"EmailStatus": "Fiabilizado",
"Phone": "968848777",
"PhoneStatus": "Fiabilizado"
},
"BankInformation": {
"Iban": "PT50001088233372181854802",
"IbanStatus": "IBAN Confirmado",
"SWIFT_BIC": "MPIOPTPL",
"InstitutionName": "NOVO BANCO, S.A.",
"InstitutionCode": "0007"
},
"Birthplace": {
"Country": "PORTUGAL",
"CountryAlpha3Code": "PRT",
"County": "PORTO",
"District": "PORTO",
"Parish": "BOAVISTA"
},
"NonHabitualResident": {
"StartingYear": 2022,
"FinishingYear": 2032,
"CountryResidence": "BRASIL"
},
},
}
To receive this events, add this javascript to your page
window.addEventListener('message', (event) => {
if (event.data && event.data.Process) {
console.log(event.data.Process)
}
if (event.data && event.data.PersonalTaxData) {
console.log(event.data.PersonalTaxData)
}
});
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.
In addition to that user information we also send a JSON entity with the process status:
ProcessInformation: {
ProcessId: YOUR PROCESS ID,
StartDateTime:"",
SentDateTime:"",
CallerLogLevel1:"",
CallerLogLevel2:"",
IsTestMode:false,
EntryURL: URL_FROM_ORIGINAL_WEBSITE
IsAllServicesRunned:true/false (If all services returned)
}
Test Users
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=112123031&niss=11951619107
nif=144080540&niss=13971183917
nif=185936059&niss=11459237611
nif=245896660&niss=15965539501
nif=531489957&niss=25314899575
For example, a test request could be structured as: &isTestMode=true&nif=185936059&niss=11321856270
This setup allows for safe testing without affecting live data, ensuring a seamless experience during the development phase.
Available Configurations
This chapter outlines the various fields available for client configurations in hAPI backoffice system. Each field plays a crucial role in managing client data and ensuring compliance with relevant regulations.
Name: The name of the client for identification purposes.
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.
Endpoint Test Configuration: The endpoint user and token to be used only for test users.
Data Encryption Password: The password used for encrypting client data.
Iframe Domains Allowed: A list of domains permitted to embed content via iframe.
Callback Configuration
After we collect all the data we will send the information through the methods. You can choose Email + SFTP or Webhook, of just SFTP or Webhook.
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). In case of delivery failure (by SFTP or Webhook) we retry every 10 minutes unitl we get success or 3 repeats. Our SFTP and Webhook requests are made through an static IP – 35.207.159.11
Email
Information could be sent by email, to a list of emails;
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.
SFTP
We can send information do an SFTP server. We can configure the endpoint, the port, username and password do access, and the destination folder;
We will create a zip file with the name processID_YYYYMMDDHHMMSS
WEBHOOK
We can send information to a webhook. This webhook can be protected with an APIKEY sent in the header request in a parameter named “Authorization” or “Authentication”;
The ZIP file will be sent the the body as a binary;
The processId 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
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.
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:
ActivityStartCertificate.pdf
(CertificadoAtividade.pdf)
BankAccountsDataBaseCertificate.pdf (BaseDadosContasBancariasCertificado.pdf)
BuildingBookCertificate.pdf
(CadernetaPredial.pdf)
CentralCreditRegisterCertificate.pdf
(CertificadoCentralResponsabilidadesCredito.pdf)
EnergyCertificatePDFResume.pdf
(ResumoCertificadoEnergetico.pdf)
FamilyHouseHoldCertificate.pdf
(AgregadoFamiliarCertificado.pdf)
HouseRentContractReceiptCertificate.pdf
(RecibodeRenda.pdf)
IRSNonDebtCertificate.pdf
(CertidaoNaoDividaIRS.pdf)
InsolvencyProceedingPDF.pdf
(ProcessoInsolvencia.pdf)
NegativeLandRegistryCertificate.pdf
(ProcessoInsolvencia.pdf)
PDFATIbanProof.pdf
(IBANAutoridadeTributariaComprovativo.pdf)
PDFOfPersonalTaxData.pdf
(DadosFiscaisPessoais.pdf)
PDFOfTheFirstSalary.pdf
(PrimeiroSalario.pdf)
PDFOfTheLastSalary.pdf
(UltimoSalario.pdf)
PDFSSIbanProof.pdf
(IBANSegurancaSocialComprovativo.pdf)
TaxAddressCertificate.pdf
(CertidaoDomicilioFiscal.pdf)
TaxDeclarationCertificate_year.pdf
(DeclaracaoIRSCertificado_year.pdf)
TaxLiquidationDeclarationCertificate_year.pdf
(LiquidacaoIRSCertificado_year.pdf)
PersonalDataSSCertificate.pdf
(CertidaoDadosPessoaisSegurancaSocial.pdf)
MonthlyContributoryCareerCertificate_year.pdf
(CertidaoCarreiraContributivaMensal_year.pdf)
YearlyContributoryCareerCertificate_year.pdf
(CertidaoCarreiraContributivaAnual_year.pdf)
SSNonDebtCertificate.pdf
(CertidaoNaoDividaSS.pdf)
For further details on how to retrieve and manage these documents, please refer to our API documentation here.