Mandate configuration

This section describes the functionality required for users to set up which Avalara countryMandate they want to use through your integration.

For each countryMandate, users must be able to:

Set up a mandate configuration for any countryMandate returned by GetMandates
Define the conditions that a document must meet to be sent through that countryMandate
Configure these conditions without depending on the team building the integration
Use default configurations provided by your integration, while still being able to edit them
Select the mapping files or processes used to produce the input document format when a countryMandate is selected

The mapping files or processes will likely be managed in a separate UI, but users must be able to select them within the mandate configuration.

Note

Your document lifecycle workflow evaluates a document against all configured conditions at runtime to determine which countryMandate to use.

Solution design suggestion

Design a mandate configuration interface that allows users to specify when a countryMandate should apply to a document for a specific company or entity.

Users should be able to:

Choose between default mappings that apply standard rules
Select customized mappings that match their specific requirements

Include a validation mechanism that detects duplicate or conflicting rules. The system should alert users to any issues before they finalize their configurations.

Example

Below is an example JSON representation of a mandate configuration. This example shows how a mandate configuration can be structured.

{
  "erpCompanyRef": "1",
  "...": "the rest of the business system company object",
  "elrCompanyAndMandateData": {
    "companyId": "60bb5c7a-53a3-4db7-85b6-d9b072efc212",
    "companyName": "Malaysian Company",
    "mandateConfigurations": [
      {
        "countryMandate": "MY-B2B-EINVOICE",
        "countryCode": "MY",
        "registrationData": {
          "id": "ae2fe5b5-1206-46fd-8ab1-517762f0ae65",
          "code": "Completed",
          "message": "The mandate has been activated and is ready for invoice/note/document submissions",
          "schemeId": "9932",
          "identifier": "GB987654321"
        },
        "enabled": false,
        "useWhen": {
          "and": [
            {
              "path": "$.counterParty.billingAddress.country",
              "operator": "in",
              "value": ["MY"]
            },
            {
              "path": "$.counterParty.custom_123",
              "operator": "!==",
              "value": "Public Procurement"
            }
          ]
        },
        "mappingFiles": [
          {
            "dataFormat": "ubl-invoice",
            "dataFormatVersion": "2.1",
            "pathToMapping": "/default/ubl_invoice_MY.liquid",
            "useWhen": {
              "path": "$.documentType",
              "operator": "in",
              "value": ["INV"]
            }
          },
          {
            "dataFormat": "ubl-creditnote",
            "dataFormatVersion": "2.1",
            "pathToMapping": "/default/ubl_creditnote_MY.liquid",
            "useWhen": {
              "path": "$.documentType",
              "operator": "in",
              "value": ["CN"]
            }
          }
        ]
      }
    ]
  }
}