Blocking and Unlocking
Blocking an account stops its operation until the cause is regularized, and unlocking lets it operate again. This page explains the block (BlockAccount), the unlock (UnlockAccount), the justifications and the retry rules when the block is due to a BC Protege+ restriction.
Block
BlockAccount blocks the account according to the reason and the applicable rule. A blocked account does not operate until it is regularized. Fits may also block the account due to a registration, document, regulatory, security or risk restriction. See Account Status and Pending Documents.
BlockAccount: Request fields
Besides the Method, PartnerId and BusinessUnitId fields, common to all requests, BlockAccount uses the fields below.
In the Requirement column, Mandatory means the field must be sent, Optional means it can be omitted, and Conditional means it depends on another field, as stated in the Description.
| Field | Requirement | Description |
|---|---|---|
| Justification | Mandatory | Reason for the block, an integer from 0 to 6. |
| Account | Mandatory | Object with the data that identify the account. |
| Account.OwnerTaxNumber | Mandatory | Valid CPF or CNPJ of the holder. |
| Account.AccountKey | Conditional | Account identifier. Required if Account.Banks is not sent. If both are sent, the AccountKey takes precedence in the search. |
| Account.Banks | Conditional | Object alternative to the AccountKey, required if the AccountKey is not sent. When used to locate the account, it must contain the four bank fields below. |
| Account.Banks.Bank | Conditional | Bank, numeric text with up to 4 characters. Required when Banks is sent. |
| Account.Banks.BankBranch | Conditional | Branch, numeric text with up to 10 characters. Required when Banks is sent. |
| Account.Banks.BankAccount | Conditional | Account, numeric text with up to 20 characters. Required when Banks is sent. |
| Account.Banks.BankAccountDigit | Conditional | Account digit, numeric text with up to 2 characters. In this method, letters are not accepted. Required when Banks is sent. |
The values of Justification are listed in the Code Mapping, in the section Block reason. The BlockAccount and UnlockAccount values are independent.
BlockAccount response
When the block is completed, the account changes to the Blocked condition. The response returns only Success, as text ("true" or "false", not a boolean), and Message. The success message is listed in the Success Catalogue. The errors returned by these methods are listed in the Error Catalogue, in the section BlockAccount and UnlockAccount.
Unlock
UnlockAccount requests the unlock of a blocked account. For justifications 0 to 5, Fits checks that the account is blocked and that there is a block record made by BlockAccount. If the account is not blocked, the request is rejected. If the justification is 0 to 5 and there is no block record made by BlockAccount, the request is rejected with EXC0016.
The justification is required. The values of Justification are listed in the Code Mapping, in the section Unlock justification. The value 6 requests a new validation by BC Protege+, with asynchronous processing.
UnlockAccount: Request fields
Besides the Method, PartnerId and BusinessUnitId fields, common to all requests, UnlockAccount uses the field below.
| Field | Requirement | Description |
|---|---|---|
| Justification | Mandatory | Reason for the unlock, an integer from 0 to 6. |
UnlockAccount response
The response returns only Success, as text ("true" or "false", not a boolean), and Message. The success messages are listed in the Success Catalogue and the errors in the Error Catalogue, in the section BlockAccount and UnlockAccount.
Unlocking an account blocked by BC Protege+
To request a new validation by BC Protege+, the BU calls UnlockAccount with justification 6 (Protege+) on a blocked account. There is no automatic retry: each attempt is a new request from the BU, and Fits queries BC Protege+ again. The result is asynchronous: the initial response does not confirm that the account was unlocked. If there is no restriction, the unlock proceeds. If there is one, it is denied, and the customer must check and regularize the protection on the gov.br environment before a new request. To learn when BC Protege+ is checked and what the BU receives in each case, see BC Protege+.
| Rule | Value |
|---|---|
| Interval between attempts | Defined per BU, in the parameter "Intervalo de tentativas para consulta Protege+" (interval between Protege+ query attempts) |
| Attempt limit | Defined per BU, per account, in the parameter "Limite de tentativas por conta para consulta Protege+" (attempt limit per account for the Protege+ query) |
| After the limit is exceeded | New calls are restricted for the time defined per BU in the parameter "Tempo de restrição após ultrapassar o limite de tentativas para consulta Protege+" (restriction time after exceeding the attempt limit) |
| What counts as an attempt | Every call, even if the account remains blocked |
If the parameter is not configured for the account, Fits uses the same parameter configured for the ownership.
flowchart TD
A["The BU calls UnlockAccount with the justification"] --> B{"Is the account blocked?"}
B -- No --> C["Request rejected"]
B -- Yes --> D{"Is the justification 6?"}
D -- No --> E{"Is there a block record made by BlockAccount?"}
E -- No --> F["Request rejected"]
E -- Yes --> G["Account unlocked"]
D -- Yes --> H["New Protege+ check, processed asynchronously"]
H --> I{"Is there a Protege+ restriction?"}
I -- No --> J["Unlock proceeds. Track it by querying the account"]
I -- Yes --> K["Unlock denied, the BU receives a notice and the customer regularizes on gov.br"]
The diagram below shows the Protege+ retry rules. Each UnlockAccount call with justification 6 counts as an attempt, and the interval, the limit and the restriction time are defined per BU, with no fixed values.
flowchart TD
A["The BU calls UnlockAccount with justification 6"] --> B["The call counts as an attempt"]
B --> C{"Has the minimum interval since the previous attempt passed?"}
C -->|No| D["New attempt only after the interval defined per BU"]
C -->|Yes| E{"Was the account attempt limit exceeded?"}
E -->|No| F["New Protege+ check proceeds"]
E -->|Yes| G["New calls restricted for the time defined per BU"]
How to track the result
A successful API response only confirms that the request was received. Track the change of the account condition through the account webhook or query the account with GetAccount. Consider the account unlocked only after the final return. For justification 6, a denial generates a notice, but an approval must be tracked by querying the account with GetAccount.
How to handle blocks and unlocks
- Query the account and confirm that it is blocked before requesting the unlock.
- Choose the justification that describes the reason for the unlock, and use 6 only to request a new BC Protege+ check.
- In a Protege+ case, guide the customer to regularize the protection on gov.br before trying again, and respect the interval and the attempt limit defined for the BU.
- Store the USN and relate it to the original request, together with the TaxNumber, the account, the method, the payload, the response and the webhooks.
- Release the account in the BU system only after the final return.
Updated 11 days ago

