# Plan your integration Source: https://developer.avalara.com/products/e-invoicing/integration-guides/elr/planning-your-elr-integration/ Guide: E-Invoicing and Live Reporting # Plan your integration This section provides an overview of the Avalara ELR certification requirements that your integration can enable to provide a meaningful value-added service to your customers. If you’re a Technology Partner, review the E-Invoicing and Live Reporting (ELR) functional requirements your integration must support to achieve ELR certification and deliver value to your customers. Important Avalara’s Technical Partner Services team provides integration support to signed Technology Partners based on the partner’s commitment to develop in accordance with the core requirements. Make sure that all relevant teams are familiar with these requirements before starting development. Partners must provide a solution design document outlining how they’ll meet the core requirements before development begins. Support from Avalara’s Technical Partner Services team for Avalara-Included partners is limited to the best practices described in this guide. ## Core features The sections below group the core functional requirements your integration must support to achieve certification. These categories align with the structure of this guide. Note In this guide, a "**User**" refers to anyone who has been granted access (by the user) to the Avalara tenant and the ERP or business system tenant connected to the ELR service, including any connector middleware, to perform the required functionality. Users need some level of technical or functional knowledge to use the functionality provided. This definition makes sure that users can go live without relying on the connector development team. If such dependencies are identified during the functional review, Avalara won’t grant certification. Review each section to plan your integration, and refer to the related sections for more detail on each requirement. ## Administration and utilities This section describes the requirements for the configuration windows of your integration. Name Type Description Comments [E-Invoicing configurations settings](/elr/itp2024635582944#dih2178068865768 "Learn how to design the E-Invoicing configurations window for ELR connection setup.") Required Users must be able to: - Select the environment to connect to. - Authenticate to the ELR API using one of the available authentication methods. [Test ELR connection](/elr/itp2024635582944#ekc1380494581900 "Learn how to design a connection test to validate ELR authentication and connectivity.") Required Users must be able to: - Test their authentication credentials - Confirm they’re connected to the ELR API [Connection in ELR](/elr/itp2024635582944#itp2024635582944 "Learn how to design connection settings that allow users to configure, test, and manage ELR integration.") Required Users must be able to: - Enable the connection to the ELR API - Disable the connection to the ELR API [Map business system companies to Avalara companies](/elr/wuh0036552797422/ "Use a company management interface to map business system companies to Avalara companies and store mappings securely.") Required Users must be able to: - View all companies available in the Avalara tenant - Select a company record from the business system - Map the selected record to an existing Avalara company - Store and access this mapping within the integration - Store the business system company reference with the Avalara company reference Your integration may not be the only one used by the Avalara tenant, so users and the business system need visibility into existing companies. [Add a company from your system](/elr/jbx3870177174830/ "Use your integration to create an Avalara company from an unmapped company in your business system.") Suggested Users should be able to: - Select a company record from the business system - Add the company to the Avalara tenant using those details The implementation should check and warn if the company already exists, whether added by this integration or another. [Mandate configuration](/elr/gmm9816215272304/ "Understand how to configure country mandates and define rules and mappings for document processing in ELR.") Required Users must be able to: - Define the logic or decision matrix to determine when a `countryMandate` applies to a record (such as an invoice, credit note, aggregated report, consolidated invoice, or payment record) for a specific company or entity - Define which `dataFormats` apply to the selected mandate - Select a default or customized mapping for all document types available for the mandate - Use fields from any defined record types in the mandate determination execution settings to configure the decision logic Prepopulated, editable logic sets are acceptable and encouraged. The same mandate configuration may also be used to manage inbound documents. Output data format definition Conditional Within the mandate configuration, users can: - Define which field on the customer (buyer) record contains the preferred output data format - Select from a list of available output data formats if the application controls the customer record schema Required if you implement the Document Lifecycle > Dynamic output data format feature. [Expose activation process status](/elr/tod1095092594511#ojj3148387155158 "Learn how to display mandate activation status in your ELR integration.") Required Users must be able to: View the status of each activation process that has been started The connector will implement a dedicated Activation Monitoring section within the configuration interface. This section will query the ELR Activation API to retrieve and show the current status of each selected mandate per company. [Block mandate usage through activation status](/elr/tod1095092594511#dhi9933810400202 "Learn how to prevent document submission when mandate activation is incomplete.") Required The integration must block the sending of a document through a `countryMandate` if the activation process status for the company isn’t Complete The connector will perform a presubmission validation check against the current activation status of the selected mandate and company. This check occurs just before a document (such as an invoice or credit note) is submitted through the ELR API. If the activation status isn’t Complete, the connector will: - Prevent document submission - Show a clear, user-friendly message indicating the reason. For example, “Can’t submit invoice – activation for Germany mandate is still in progress.” [Settings](/elr/rls9390510603572/ "Learn how to configure connector-level settings for mandate determination and log management in ELR.") Conditional (see Comments) Users can: - Configure how often the mandate determination logic runs - Define the event or action that triggers the process Required when the application supports outbound documents such as invoices or credit notes. Mandate determination execution Required Users must be able to: - Select events across supported record types (such as invoice, credit note, payment record, aggregated report, or consolidated invoice) that trigger the mandate determination process. - Configure both automated and manual triggering using the available settings and documentation. This must not be limited to invoices and credit notes. [View mandate mappings](/elr/rfa1635419604313#igr8573290714461 "Learn how users can view and manage mandate mappings in ELR.") Required Users must be able to view the default or suggested mappings for each document type and `countryMandate` supported by the integration Retrieve relevant input fields by `countryMandate` Required Users must be able to: - Select a `countryMandate` - View the data input fields required to support the selected `countryMandate` Use this endpoint to prepare default mappings for each document type so users can review and update them. Don’t use this endpoint to generate input documents at runtime. This requirement goes hand in hand with the Customizable mandate mappings requirement. [Customizable mandate mappings](/elr/rfa1635419604313#sds7368311942022 "Learn how users can customize mandate mappings in ELR.") Required Users must be able to: - Clone existing mappings, including value transformations - Edit mappings to support ERP or application-specific customization - Save mappings for reuse - Add required, conditional, or optional input fields where needed Prepopulated, editable mappings are acceptable. A "user" refers to any authorized individual with access to the relevant systems to configure these mappings. User Guide Required Users must be able to: - Access documentation that explains how to configure, use, and maintain the integration - Access links to related native functionality used by the integration - Understand how and why these features are used together Provide Avalara with a public link to the user guide or a nonpublic document containing the same information. API logs Required Users must be able to: - Access logs that include raw request and response data (headers and body) for all ELR API calls - Use logs to troubleshoot issues The integration can define how long logs are retained. For example, 1 week or 1 month. Document your log management approach, including how long data is retained. ## **Document lifecycle** This section describes requirements for how documents are submitted to the Avalara ELR service. Name Type Description Comment Endpoint [Submit the document](/elr/rkz5197923133334/ "Submit a document to Avalara E-Invoicing and Live Reporting using the SubmitDocument endpoint.") Required Users must be able to: - Submit a document using the input data that they’ve specified for a given e-invoicing mandate or specification - Resubmit a document manually when needed The integration must support validation and the Mandate Determination Execution process to handle resubmission scenarios. Note This functionality is required even if your system is AP-only, as you must support responses to received documents through `ApplicationResponse`. Dynamic output data format Suggested Users can: - Request a specific output data format for a document - Select from the list of supported output formats for the determined document mandate [Get the status of the sent document](/elr/enf3558404166902/ "Retrieve the status and event details of a submitted document in ELR.") Required Users must be able to: - View the processing status of a submitted document - View any related error messages - Access this information through the business system APIs so it’s available to connected applications Store `responseKey` and `responseValue` pairs [Response key and document retrieval in ELR](/elr/pse9014344707594/ "Understand how to retrieve document status, store response data, and manage document outputs in ELR.") Required Users must be able to: - View error messages - View `responseKey` and `responseValue` pairs - Store `responseKey` and `responseValue` pairs on the business system document record - Make this data accessible programmatically to other applications This ensures users can use other applications to prepare PDF templates and include `responseValues`. The data must also be available to the mapping process described under Customizable mandate mappings. [Download the document](/elr/xzy0852591847769/ "Download documents and available formats from ELR.") Required Users must be able to: - View all available formats for a document within the application - Store these formats so that other applications connected to the business system can retrieve them programmatically - Use these formats in related business processes outside of the integration To help manage storage costs, you can provide configuration options in Mandate Configuration so users can define which formats to automatically download for each mandate. Receive an `ApplicationResponse` Required Users must be able to: - View the updated business status of a document - See updates when a document is responded to by the buyer or updated by the seller Import inbound document to client application Conditional Users can: - Import an inbound document into the ERP or purchasing system without manual data entry - Select and modify an inbound mapping within mandate configuration using customizable mandate mappings Required if your application supports AP (purchase) documents. Import inbound document automation Suggested Users can configure the frequency on which an automated process to import the inbound document is run. This may already be existing functionality. Prepopulated default/suggested values are acceptable. Only relevant for applications that support AP (purchase) documents. ## **Server audit clarity and installation requirements** **Name** **Type** **Description** **Comment** **Endpoints/models** Pass connector identifier Required Integrations must include the connector ID as a signature in all requests made to the ELR API. Avalara provides this value at the start of the project. The value will be provided by Partner Launch Services for signed Technology Partners and Avalara-Included partners. This isn’t required for requests to the Authorization server. Error handling Required The system shouldn’t generate errors except those caused by normal (but invalid) user input. These errors must be logged and displayed clearly. Installation experience Required Users must have a simple and reliable installation experience, supported by the user guide. The installation video should be easy to follow and provide enough detail for [Certified Implementation Partners (CIPs)](https://www.avalara.com/us/en/partners/partner-programs/avalara-implementation-certification.html) to install the ELR integration successfully.