Set up and deploy the Dynamics 365 Commerce localization for Brazil

Article
09/29/2023

This article covers how to set up and deploy the Microsoft Dynamics 365 Commerce localization for Brazil.

The Dynamics 365 Commerce localization for Brazil includes several extensions of the following Commerce components: the Commerce runtime (CRT), Retail Server, and point of sale (POS). These extensions let you calculate Brazil-specific taxes, generate electronic fiscal documents for retail sales, print DANFE (Documento Auxiliar de Nota Fiscal Eletrônica) and CF-e-SAT (Cupom Fiscal Eletrônico - Sistema Autenticador e Transmissor de Cupons Fiscais Eletrônicos) fiscal receipts that have custom fields, manage Brazil-specific customer information, and issue sales in offline contingency mode where registration of electronic fiscal documents is postponed. For more information about the Commerce localization for Brazil, see Brazilian localization scope and Commerce localization for Brazil.

The extensions that are described in this article were developed based on the fiscal integration framework. For information about the fiscal integration functionality, see Overview of fiscal integration for Commerce channels. Electronic reporting (ER) is used to implement formats for Brazilian electronic fiscal documents.

Enable Brazil-specific Commerce functionality

This section describes how to configure Commerce headquarters settings that are specific to and recommended for Brazil. For more information, see the Commerce home page.

To enable and use the Brazil-specific functionality, you must configure the following settings in Commerce headquarters.

In the primary address of the legal entity, set the Country/region field to BRA (Brazil).
In the POS functionality profile of every store that is located in Brazil, set the ISO code field to BR (Brazil).
Go to System administration > Workspaces > Feature management, and then, on the All tab, enable the following feature keys:
- (Brazil) Commerce functionality that is specific to Brazil
- (Brazil) NFC-e synchronous processing
- Postponed registration of documents

Set up electronic reporting

You can download the ER configurations for the electronic fiscal documents from Microsoft Dynamics Lifecycle Services (LCS). For more information, see Import Electronic reporting (ER) configurations. You must download the latest versions of the configurations that are listed in the following procedure.

To set up electronic reporting in Commerce headquarters, follow these steps.

Go to Organization Administration > Workspaces > Electronic Reporting.
On the tile for the Microsoft configuration provider, select the ellipsis (...), and then select Set active.
On the tile, select Repositories.
Select the Global configuration repository, and then, on the Action Pane, select Open.
In the Connect to Regulatory Configuration Service dialog box, select Click here to connect to Regulatory Configuration Service, return to the dialog box, and then select OK.
Import the latest shared versions of the following data model, data model mapping, and format configurations:
- Fiscal documents mapping
- NF-e submit export format (BR)
- NF-e status request export format (BR)
- NF-e cancel export format (BR)
- NFC-e submit export format (BR)
- NFC-e contingency export format (BR)
- NFC-e fiscal documents mapping
- NFC-e fiscal documents validation format (BR)
- CF-e submit export format (BR)
- CF-e cancel export format (BR)
Go to Organization administration > Workspaces > Electronic reporting, and select Reporting configurations.
Select Fiscal documents mapping, and then set the Default model mapping option to No.
Select NFC-e fiscal documents mapping, and then set the Default model mapping option to Yes.
Go to Organization Administration > Setup > Brazilian parameters.
On the Retail tab, in the Format mapping field, select NFC-e fiscal documents validation format (BR).

Set up a fiscal establishment and NF-e federal parameters

To set up a fiscal establishment and NF-e (Nota Fiscal Eletrônica) federal parameters in Commerce headquarters, follow these steps.

Go to Organization administration > Organizations > Fiscal establishments > Fiscal establishment.
In the Tax registration numbers - CNPJ, IE & CCM field, enter the tax registration numbers. (CNPJ stands for Cadastro Nacional da Pessoa Jurídica, IE stands for Inscrição Estadual, and CCM stands for Cadastro de Contribuinte Mobiliário.)
In the Address of the establishment field, enter an address.
Set up CSC (Código de Segurança do Contribuinte) encryption by entering the CSC token and CSC alphanumeric code.
Select the appropriate digital certificate for authentication with the tax authority service and digital signing of fiscal documents.

Note

The certificate that is configured on the Fiscal establishment page is used for NFC-e (Nota Fiscal de Consumidor Eletrônica) documents that are issued in POS in offline contingency mode and then submitted for authorization through Commerce headquarters. To enable fiscal documents to be signed in offline contingency mode, you must install a certificate in the offline certificate storage of the POS. For more information, see Make a cash-and-carry sale of goods in offline contingency mode and Postponed registration of NFC-e issued in contingency mode.
Under NF-E WEB SERVICE, in the Environment field, select Testing or Production.
Under NFC-E WEB SERVICE, in the Environment field, select Testing or Production.
Specify the versions of the NF-e and NFC-e features.
Under NF-E WEB SERVICE, in the Authority field, enter the value used at NF-e federal parameters > Web services > Authority.
Under NFC-E WEB SERVICE, in the Authority field, enter the value used at NF-e federal parameters > Web services > Authority.
Go to Organization administration > Organizations > Fiscal establishments > Electronic fiscal documents > NF-e federal parameters.
Create new authorities for the required states, or use existing authorities.
For each state, turn on the NFC-e synchronous processing flag.
For each state, in the Internet address for NFC-e inquiry field, enter QR code URLs.
For each state, specify the endpoints for all web services of the appropriate environments.

Set up address books

To add the same address book for Brazilian customers, stores, and workers in Commerce headquarters, follow these steps.

Go to Retail and Commerce > Customers > All customers.
On the General tab, in the Address books field, add retail address books for customers as required.
Go to Retail and Commerce > Channels > Stores > All stores.
On the General tab, in the Customer address book and Employee address book fields, add the address books for the stores.
Go to Retail and Commerce > Employees > Workers.
On the Worker summary tab, in the Address books field, add the address books for workers.

Set up sales tax for POS

To set up sales tax for POS in Commerce headquarters, follow these steps.

Go to Tax > Indirect taxes > Sales tax > Sales tax codes.
Create the required sales tax codes for different tax types and taxation codes. Include sales tax codes for returns.
Go to Tax > Indirect taxes > Sales tax > Sales tax group.
Create sales tax groups for retail sales and returns, and add the sales tax codes that you just created.
Go to Retail and Commerce > Channels > Stores > All stores.
In the Sales tax group and Sales tax group for returns fields, select the sales tax groups that you just created.
Go to Tax > Indirect taxes > Sales tax > Item sales tax groups.
Create item sales tax groups for retail, and add the sales tax codes that you created earlier.
Go to Organization administration > Setup > Fiscal document source texts.
Create a fiscal document source text for retail tax burden. Set the Restriction field to External and the Fiscal information option to No.
Go to Organization administration > Setup > Brazilian parameters.
On the Retail tab, in the Text ID field, specify the source text for retail tax burden.
Go to Retail and Commerce > Products and categories > Released products by category.
Select the desired products, and set the following fields:
- On the Sell tab:
  - Item sales tax group
- On the Fiscal information tab:
  - Taxation origin
  - Product type
  - Fiscal classification code
  - Approximate federal tax percentage
  - Approximate state tax percentage
  - Approximate city tax percentage
Go to Tax > Setup > Sales tax > CFOP codes.
Set the Fiscal reference required option to No for CFOP (Código Fiscal de Operações e de Prestações) codes that are used for retail returns.

Set up a retail store

To set up a retail store in Commerce headquarters, follow these steps.

Go to Inventory management > Setup > Inventory breakdown > Warehouses.
Create warehouses for the stores, and specify addresses.
Go to Retail and Commerce > Channels > Stores > All stores.
Create the stores, and set the following fields:
- Prices include sales tax
- Sales tax group
- Sales tax group for returns
- Default customer
  
  Note
  
  The default customer should be included in the same address book as the store.
Set up payment methods for the stores that you created in the previous step.
Go to Retail and Commerce > Headquarters setup > Commerce scheduler.
Add the stores that you created earlier to the channel database that is used.
Go to Retail and Commerce > Channel setup > POS setup > Registers.
Create POS registers, and set the following Brazil-specific fields, depending on the fiscal operation mode:
- Fiscal operation mode – Select NFC-e or CF-e.
- NFC-e series – If you selected NFC-e in the Fiscal operation mode field, enter the NFC-e series.
- NFC-e contingency series – If you selected NFC-e in the Fiscal operation mode field, enter the NFC-e series for offline contingency mode.
- NF-e series – Enter the NF-e series to use when NF-e documents are issued for returns.
- Register number for CF-e – Enter the number of the POS register that is connected to SAT. This register number exists to comply with the numeroCaixa tag in the CF-e XML. Two or more POS registers can't have the same register number for CF-e.
Go to Retail and Commerce > Channel setup > POS setup > Devices.
Create and configure devices for the POS registers that you just created.
Go to Organization administration > Organizations > Organization hierarchies.
Select Retail Stores by Business Unit organization hierarchy, select View, select Edit > Insert retail channel, and add the stores that you created earlier to the appropriate business units in the hierarchy. Then publish the changes.
Assign the Retail POS posting purpose to the Retail Stores by Business Unit organization hierarchy.
Go to Retail and Commerce > Channel setup > Channel categories and product attributes.
Publish the channel updates.
Go to Retail and Commerce > Channel setup > POS profiles > Receipt profiles.
Create receipt layouts for DANFE, and add the layouts to the receipt profiles.
Create receipt layouts for CF-e-SAT and CF-e-SAT cancellation, and add the layouts to the receipt profiles.

Note

The default company of the user who creates the receipt setup should be the same legal entity where the language text setup is created. Alternatively, the same language text setup should be created in both the user's default company and the legal entity of the store that the receipt setup is created for.

In the receipt format designer, add Brazilian custom fields to the appropriate receipt section for every receipt format that is required. For more information about how to work with receipt formats, see Receipt templates and printing.

Set up the fiscal registration process

To set up the fiscal registration process in Commerce headquarters, follow these steps. For more information, see Set up the fiscal integration for Commerce channels.

Download configuration files for the fiscal document provider and the fiscal connector from the Commerce SDK:
1. Open the Dynamics 365 Commerce Solutions repository.
2. Open the last available release branch (for example, release/9.31).
3. Open src > FiscalIntegration > ElectronicFiscalDocumentsBrazil.
4. Download the fiscal connector configuration files at Configurations > Connectors (for example, the files for release/9.31):
  - SubmitConnector.xml
  - SatConnector.xml
  - ContingencyConnector.xml
5. Download the fiscal document provider configuration files at Configurations > DocumentProviders (for example, the files for release/9.31):
  - SubmitProvider.xml
  - SatProvider.xml
  - ContingencyProvider.xml
Go to Retail and Commerce > Headquarters setup > Parameters > Commerce shared parameters.
On the General tab, set the Enable fiscal integration option to Yes.
Go to Retail and Commerce > Channel setup > Fiscal integration > Fiscal connectors, and load the fiscal connector configuration files that you downloaded earlier.
Go to Retail and Commerce > Channel setup > Fiscal integration > Fiscal document providers, and load the fiscal document provider configuration files that you downloaded earlier.
Go to Retail and Commerce > Channel setup > Fiscal integration > Connector functional profiles.
For each document provider that you just loaded the configuration for, create connector functional profiles, and select the fiscal connectors that you loaded the configuration for earlier. Update data mapping settings as required. If settings for SAT are needed, set the Key Vault activation code secret name and POS Signature for SAT fields.
Go to Retail and Commerce > Channel setup > Fiscal integration > Connector technical profiles.
Create connector technical profiles, and select the fiscal connectors that you loaded the configuration for earlier. Update connection settings as required (for NFC-e, set the Connector type field to Internal). If settings for SAT are needed, set the Connector name field for the SAT device (Connector type = Local), and specify the SAT library path string. Include the name of the dynamic-link library (DLL) file.
Go to Retail and Commerce > Channel setup > Fiscal integration > Fiscal connector group.
Create fiscal connector groups, one for each connector functional profile that you created earlier (including SAT).
Go to Retail and Commerce > Channel setup > Fiscal integration > Registration process.
Create a registration process. As registration steps, select the fiscal connector groups that you just created.
Create a separate registration process for the SAT device.
Go to Retail and Commerce > Channel setup > POS setup > POS profiles > Functionality profiles.
Select the functionality profile that is linked to the store where the registration process should be activated, and then, on the Fiscal registration process FastTab, select the registration process number that you just created.
Create a separate functionality profile for the SAT device.
Go to Retail and Commerce > Channel setup > POS setup > POS profiles > Hardware profiles.
Select a hardware profile that is linked to the hardware station that the fiscal printer will be connected to.
Create a separate hardware profile for SAT device.
On the Fiscal peripherals FastTab, select the connector technical profile for each hardware profile.
Go to Retail and Commerce > Channel setup > POS setup > POS profiles > Hardware profiles.
Set up hardware profiles for printers.
On the Stores page, on the Hardware stations FastTab, add a setup for the hardware station. As required, configure IP addresses for the network printer that you configured earlier.

Customer information management

The Add customer information operation can be used to add Brazil-specific CNPJ or CPF (Cadastro de Pessoas Físicas) customer tax registration numbers and addresses to sales transactions. Customer information can be pulled from the customer record that is specified for the transaction, or it can be manually entered. The customer information can then be printed on DANFE and CF-e-SAT fiscal receipts and used for invoicing purposes.

To configure the Add customer information operation in Commerce headquarters, follow these steps.

Go to Retail and Commerce > Channel setup > POS setup > POS > Button grids.
Select the button grid where the operation should appear, and then open Button grid designer.
Add a button, and then, in the Action field, select Add customer information.

For more information about how to work with screen layouts and button grids, see Screen layouts for the point of sale (POS).

Enable customer searches based on tax registration numbers in POS

To enable customers to be searched for by CNPJ/CPF and CCM tax registration numbers in POS, follow these steps.

In Commerce headquarters, on the Commerce parameters page, on the POS search criteria tab, on the Customer search criteria FastTab, add a record.
In the new record, in the Customer search criteria field, select Tax registration number.
Select the Display as shortcut checkbox, but leave the Can be refined checkbox cleared.
On the Distribution schedules page, run the 1110 job.

Set up parameters for statements

Go to Organization administration > Number sequences.
Create and set up number sequences for retail statements for each store (operating unit).
On the References FastTab, add two references for the Retail store area: one where the Reference value is set to Statement number and one where it's set to Voucher.
Go to Retail and Commerce > Catalog and assortments.
Create an assortment that includes appropriate products.
On the Commerce channels tab, add the stores that you created earlier. Then select Publish.
Go to Retail and Commerce > Channel setup > Channel categories and product attributes, and publish channel updates.
Go to Sales and marketing > Setup > Returns > Disposition codes, and add a disposition code.
Go to Retail and commerce > Products and categories > Released products by category.
Select a product for the gift card, and then select the Blocked at register check box.
Go to Retail and Commerce > Headquarters setup > Parameters > Commerce parameters.
On the Customer orders tab, enter the disposition code that you added earlier.
On the Posting tab, set up the parameters for the gift card. These parameters include the Gift card company and Gift card product fields.

Configure a production environment

This section provides deployment guidance that will help you enable Commerce components of the Commerce localization for Brazil.

Note

Some steps in these procedures vary, depending on the product version that you're using. For more information, see What's new or changed in Dynamics 365 for Retail.

Use certificates for authentication with the tax authority service and digital signing of fiscal documents

A digital certificate for Application Object Server (AOS) must be stored in Azure Key Vault.

Digital certificates for Retail Server must be installed locally or stored in Key Vault. Both location types for Retail Server can also be configured simultaneously and used according to their priorities.

For more information about how to work with Key Vault storage, see Get started with Azure Key Vault and Set up the Azure Key Vault client.

You can also use the User-defined certificate profiles for retail stores feature that supports failover to offline when Key Vault or Commerce headquarters isn't available. This feature extends the Manage secrets for retail channels feature.

Note

To enable NFC-e documents to be signed in offline contingency mode, you must install a certificate in the offline certificate storage of the POS. For more information, see Make a cash-and-carry sale of goods in offline contingency mode and Postponed registration of NFC-e issued in contingency mode.

Configure certificates so that they can be used in Retail Server

The Brazilian tax service extension of Retail Server uses a certificate for authentication with the tax authority service and digital signing of fiscal documents. The settings for Retail Server certificates are controlled by certificate profiles.

To configure certificates so that they can be used in Retail Server, follow these steps.

Go to System administration > Setup > Certificate profiles.
Create a certificate profile for the appropriate legal entities.
For each legal entity, select Settings, and then follow these steps:
- For the local certificate, create a record where the Location type field is set to Local certificate. Then, in the Thumbprint field, enter a value.
- For the Key Vault certificate, create a record where the Location type field is set to Key Vault, and then select Key Vault certificate.

Certificates can be installed in the local certificate storage of the machine where Retail Server is deployed or in Key Vault. Alternatively, they can be installed in both location types and configured simultaneously so that they are used according to their priorities.

Configure a certificate in AOS

A certificate for authentication with the tax authority service is stored in Key Vault. This certificate is used in AOS to submit, through Commerce headquarters, NFC-e documents that were issued in POS in offline contingency mode. The certificate is also required for digital signing of "discard" and "cancellation by substitution" requests. Parameters of the certificate must be specified in the fiscal establishment settings.

To configure a certificate in AOS, follow these steps.

Go to Organization administration > Organizations > Fiscal establishments > Fiscal establishments.
Select the appropriate digital certificate for authentication with the tax authority service and digital signing of fiscal documents.

Note

After the setup is completed, the appropriate distribution jobs must be run in Commerce headquarters.

Set up the SAT activation code

The SAT activation code enables communication between the POS register and the SAT device. The SAT hardware attribute contains the activation code for the SAT serial number that was entered during SAT device activation. That SAT hardware attribute must be associated with the POS register.

To create the SAT hardware attribute, follow these steps.

Go to System administration > Setup > Key Vault parameters.
Create a record for the SAT activation code.
Add a secret that is named ActivationCode.
In the Secret field, enter value.
In the Secret type field, select Manual.

Configure CRT extension components

Warning

Because of limitations of the new independent packaging and extension model, it can't currently be used with this localization functionality. You must use the previous version of the Retail software development kit (SDK) on a developer virtual machine (VM) in LCS. (Microsoft plans to add support for localization functionality to the new independent packaging and extension model in later versions.)

To configure CRT extension components, follow these steps.

Find the extension configuration file for CRT.
- Commerce Scale Unit: The file is named Commerceruntime.ext.config, and it's located in the bin\ext folder under the Internet Information Services (IIS) Commerce Scale Unit site location.

<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ElectronicReporting" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ElectronicFiscalServiceBrazil" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ElectronicFiscalDocumentBrazil" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.TaxRegistrationIdBrazil" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.TaxServiceBrazil" />

Find the Web.config file for CRT.
- Commerce Scale Unit: The file is named Web.config, and it's located in the \RetailServer\webroot folder.

Update this Web.config file by adding the new extension library name in the extensionComposition section.

<extensionComposition>
    <add source="assembly" value="Microsoft.Dynamics.Retail.RetailServer.ElectronicFiscalDocumentBrazil" />
</extensionComposition>

Find the extension configuration file for Local CRT on Modern POS:
- Local CRT on Modern POS: The file is named CommerceRuntime.MPOSOffline.Ext.config, and it's located in the local CRT client broker location.

<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ElectronicReporting" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ElectronicFiscalDocumentBrazil.Offline" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ElectronicFiscalDocumentBrazil" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.TaxRegistrationIdBrazil" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.TaxServiceBrazil" />

Warning

Don't edit the Commerceruntime.config and CommerceRuntime.MPOSOffline.config files. These files aren't intended for any customizations.

Find the extension configuration file for Retail proxy on Modern POS:
- Retail proxy on Modern POS: The file is named RetailProxy.MPOSOffline.Ext.config, and it's located in the local CRT client broker location.

<retailProxyExtensions>
    <composition>
        <add source="assembly" value="Microsoft.Dynamics.Commerce.RetailProxy.ElectronicFiscalDocumentBrazil" />
    </composition>
</retailProxyExtensions>

Enable Hardware station extension components

Note

For more information, see Configure and install Retail hardware station.

SatBrazil component

To help ensure that the Hardware station loads the SAT extension component, you must set the corresponding assembly reference in the HardwareStation.Extension.config file that is located in the Assets folder in the Retail SDK.

<hardwareStationExtension>
    <composition>
        <add source="assembly" value="Microsoft.Dynamics.Commerce.HardwareStation.FiscalPeripherals.SatBrazil" />
    </composition>
</hardwareStationExtension>

Payments.Connector.Adyen.Device.Brazil component

To help ensure that the Hardware station loads the extension component for the Payment Connector for Adyen in POS for Brazil, you must set the corresponding assembly reference in the HardwareStation.Extension.config file that is located in the Assets folder in the Retail SDK.

<hardwareStationExtension>
    <composition>
        <add source="assembly" value="Microsoft.Dynamics.Commerce.Payments.Connector.Adyen.Device.Brazil" />
    </composition>
</hardwareStationExtension>

Enable Modern POS extension components

To enable Modern POS extension components, follow these steps.

Open the solution at RetailSdk\POS\ModernPOS.sln, and make sure that it can be compiled without errors. Additionally, confirm that you can run Modern POS from Visual Studio by using the Run command.

Note

Modern POS must not be customized. You must enable User Account Control (UAC), and you must uninstall previously installed instances of Modern POS as required.
Enable the extensions to be loaded by adding the following lines in the extensions.json file.
```
{
    "extensionPackages": [
        {
            "baseUrl": "Microsoft/ElectronicFiscalDocument.BR"
        },
        {
            "baseUrl": "Microsoft/TaxRegistrationId.BR"
        }
    ]
}
```
Note

For more information, and for samples that show how to include source code folders and enable extensions to be loaded, see the instructions in the readme.md file of the Pos.Extensions project.
Rebuild the solution.
Run Modern POS in the debugger, and test the functionality.

Enable Cloud POS extension components

To enable the Cloud POS extension components to be loaded in the extensions.json file, add the following lines in the appropriate part of the file.

{
    "extensionPackages": [
        {
            "baseUrl": "Microsoft/ElectronicFiscalDocument.BR"
        },
        {
            "baseUrl": "Microsoft/TaxRegistrationId.BR"
        }
    ]
}