## What is CACAO? CACAO is a system maintained by the Tax Administration for receiving and maintaining files with accounting data of taxpayers. ## What does CACAO stands for? CACAO is a Spanish acronym for *Sistema de **C**onsulta y **A**lmacenamiento de Datos **C**ontables y **A**poyo **O**rganizativo*, which translates to "System for Consulting and Storing Accounting Data and Organizational Support." ## Login to the CACAO system Use the `Start CACAO` button located in the center of the system homepage, or click on the `Start CACAO` option in the upper right corner to access the authenticated area of the CACAO system. > **Attention!** > The CACAO system allows secure access in several ways. By clicking on `Sign in with Google`, `Sign in with Microsoft` or `Sign in with Facebook`, the user can log in using his or her account with these providers, without the need to create a password specific to CACAO. **This is the recommended model for access.** To access CACAO using a login/password, please contact the Tax Administration. ## The Sidebar menu All functionalities of the CACAO system can be accessed through the sidebar menu. > **Attention!** > The sidebar menu is located on the upper left corner, identified by 3 stacked bars. After logging in to CACAO, or selecting the `Home` option in the sidebar menu, a card interface will be presented with shortcuts to CACAO's most commonly used features. ## Role-Based Access Control The CACAO system implements a Role Base Access Control. **Not all functions are available to all roles**. If you don't have access to a function that you need, please make contact with the Tax Administration.

## How to upload documents Use the `Upload Documents` option located in the sidebar menu. Once the `Upload Documents` has been selected, it is necessary to indicate what type of document will be sent to CACAO. The 'Document Template' dropdown menu shows all the possible types of documents that CACAO can receive and validate. > **Attention!** > Sending documents of models that do not exist in CACAO, or choosing a model different from the one that represents the file that will be sent, will cause the rejection of the document by CACAO. Select from the dropdown menu which type of file you want to send. The `Upload file` button will become available. When you select the `Upload file' button, the functionality for choosing which file to send will open. The functionality to choose the file is dependent on the Operating System that is being used on the user's equipment. Please refer to your operating system manual if you have questions about how to use this feature. After selecting the file, a window will open to confirm that you want to send the file. Select `Yes` to send the file, or `No` to go back. Once the file is sent, the CACAO system will inform you if the operation was successful. ## Checking the uploaded files and their situation. In order to check the uploaded files or to check the validation status of each of them, use the `All Uploads` option located in the sidebar menu. A table with all the documents uploaded will be presented. This table shows: * The **User** who uploaded the file * The **Taxpayer ID** to whom the file refers * The **Tax Period** the file refers * The **Template** indicating the type of file sent * The **Upload date/time** * The **Situation** of the file. The possible situations are: * **Received** - The file has been received by CACAO * **Accepted** - The validation process accepted to begin reviewing the file * **Valid** - The file has been validated and its format comply with the document template * **Invalid** - The file has been rejected for not complying with the document template * **Pending** - The file is waiting for another file to be uploaded, in order to the ETL process to begin * **Processed** - The ETL process has been executed on this file * **Replaced** - This file has been replaced by another file. > **Attention!** > CACAO applies **two** sequential processes: > * _File validation_, when CACAO validates each file against the document template. > * _Data extraction, transformation, and loading (ETL)_, when CACAO reads the data from the validated files, performs various calculations and transformations, and stores the results on its own database. > > For more information on documents templates, please refer to the `Managing Document Templates` entry of this user manual. There are also 3 functions available for each upload: * Show the **situation history**, identified by a `file` icon * Show the **error messages**, if any, that occurred during the file validation, identified by a `warning sign` icon * **Download** the file, identified by a `floppy disk`icon

## CACAO users´ list To list and manage the CACAO users, select the `Users` option located in the sidebar menu. A table with all the users will be presented. This table shows: * The **User name** * The **login** information for the user * The **Profile** assigned to the user * The **Taxpayer ID** of the user There are also 2 functions available for each user: * **Edit** user information, identified by a `paper and pencil` icon * **Delete** user from CACAO, identified by a `trash` icon ## User Creation To create a new user, select the `New User` button on the bottom left of the users´ table. > **Attention!** > Although it is possible to manually create a user, its advisable to always use `Sign in with Google`, `Sign in with Microsoft` or `Sign in with Facebook`, which automatically creates the CACAO user. An interface for inserting the users´ information is displayed. After fulfilling all required information, select the `Add user` button. ## Editing user information The same interface for creating a user can be used for editing the user´s information. After changing the desired information, select the `Save` button. ## Deleting a user To delete a user from CACAO, select the `trash` icon next to the desired user on the Users´ table. A confirmation dialog will be presented. Select `Yes`to delete the user, or `No` to cancel the operation. > **Attention!** > The user´s deletion procedure cannot be undone. If necessary, the user will have to be recreated.

## CACAO Taxpayer´s list To list and manage the Taxpayers, select the `Taxpayers` option located in the sidebar menu. A table with all the Taxpayers will be presented. This table shows: * The **Taxpayer ID** * The Taxpayers **name** There are also 2 functions available for each Taxpayers: * **Edit** Taxpayer information, identified by a `paper and pencil` icon * **Delete** Taxpayer from CACAO, identified by a `trash` icon ## Taxpayer Creation To create a new user, select the `New Taxpayer` button on the bottom left of the Taxpayer´s table. An interface for inserting the Taxpayer information is displayed. After fulfilling all required information, select the `Add Taxpayer` button. ## Editing Taxpayer information The same interface for creating a Taxpayer can be used for editing the Taxpayer´s information. After changing the desired information, select the `Save` button. ## Deleting a Taxpayer To delete a Taxpayer from CACAO, select the `trash` icon next to the desired Taxpayer on the Taxpayer´s table. A confirmation dialog will be presented. Select `Yes`to delete the Taxpayer, or `No` to cancel the operation. > **Attention!** > The Taxpayer´s deletion procedure cannot be undone. If necessary, the Taxpayer will have to be recreated.

## What's the purpose of a Vertical and Horizontal Analysis? The vertical and horizontal analysis allows the visualization of the state of a single taxpayer. The data source for these analyses is the journal uploaded by the Taxpayer. The **vertical analysis** presents the financial statement for the period so that level 1 of the statement (Category) equals 100%, and then the percentage that each element of item 2 (subcategory) represents of this 100% is presented, and so on. For instance: |Level|Category|SubCategory |Comparison| |-|-|-|-| |**1**|**Asset**||**100%**| |2|Asset|Cash and Cash Equivalents|66,67%| |2|Asset|Inventory|33,33%| The **horizontal analysis** compares two periods side by side, including a third column that shows how much the second period represents in relation to the first, which is considered 100%. For instance: |Level|Category|SubCategory|First Period|Second Period|Comparison| |-|-|-|-|-|-| |**1**|**Asset**||**1500**|**1050**|**70%**| |2|Asset|Cash and Cash Equivalents|1000|450|45%| |2|Asset|Inventory|500|600|120%| It is also possible to perform **both analyses** simultaneously. In this situation, after the information for the first period, there will be the vertical comparison column. After the information for the second period, there will be the horizontal comparison. |Level|Category|SubCategory|First Period|Vertical Comparison|Second Period|Horizontal Comparison| |-|-|-|-|-|-|-| |**1**|**Asset**||**1500**|**100%**|**1050**|**70%**| |2|Asset|Cash and Cash Equivalents|1000|66,67%|450|45%| |2|Asset|Inventory|500|33,33%|600|120%| ## Using the Vertical and Horizontal Analysis To use the vertical and horizontal analysis, select the `Analysis` option located at the sidebar menu, then select `Vertical and Horizontal Analysis`. It's mandatory to select a Taxpayer by its *name* or *Taxpayer Id* from the **Name** menu. You can scroll the list of taxpayers or input the name or taxpayer id. The next step is to choose the analysis type. It's possible to choose from: * **Vertical** analysis * **Horizontal** analysis * **Both** vertical and horizontal analysis The third step is to select the **base period**. The base period is the first period in all comparisons. In the fourth step, it must be select the periodicity of the analysis. This selection controls the periods that will be compared to the base period. The last step is to select the levels of the chart of accounts that will be displayed: * **Level 1** - only the category will be shown * **Level 2** - both category and subcategory will be shown * **Level 3** - The category, subcategory and account will be shown It's possible to show accounts with *zero* balance, selecting the `Show accounts with ZERO balance`option. With all the selections made, select `Search` to retrieve the data and the analysis desired.

## What's the purpose of a General Analysis? The General Analysis allows you to evaluate the result of a group of taxpayers. The data source for the general analysis can be the journal sent by the taxpayers, or the statement of income for the year. With this analysis, it is possible to graphically visualize the behavior patterns of the taxpayers, as well as identify those with discrepant behavior. For a given group of taxpayers that share a common qualifier, the general analysis shows for each entry of the Journal/Declared Income Statement a **boxplot** representing the dispersion of the taxpayers. > **Attention!** > The qualifiers are defined by the Tax Administration and may differ for each jurisdiction. The **boxplot** is a method for graphically demonstrating the locality, spread and skewness groups of numerical data through their quartiles. On CACAO, the boxplot shows: * **Minimum** (Q0 or 0th percentile): the lowest data point in the data set excluding any outliers * **Maximum** (Q4 or 100th percentile): the highest data point in the data set excluding any outliers * **Median** (Q2 or 50th percentile): the middle value in the data set * **First quartile** (Q1 or 25th percentile): it is the median of the lower half of the dataset. * **Third quartile** (Q3 or 75th percentile): it is the median of the upper half of the dataset. * **Outliers**: data points that differ significantly from the rest of the dataset are plotted as individual points beyond the whiskers on the boxplot. If you hover your mouse pointer over a boxplot on CACAO, a tooltip will be shown with the detailed information represented by the boxplot. Whenever a outlier is identified, it will be shown on the boxplot as a **dot**, and the taxypayer identification for this outlier will also be detailed on the auxiliary table next to the boxplots. The image containing all boxplots can be downloaded selecting the `...` button on the upper right of the boxplot area. The data on the auxiliary table can be downloaded selecting the `XLS` button on the lower left corner of the table. ## Using the General Analysis To use the General analysis, select the `Analysis` option located at the sidebar menu, then select `General Analysis`. The first step for the General Analysis is to choose the qualifier for the taxpayer's group that will be subjected to the analysis. That's achievable scrolling through the **Qualifiers** menu. Once the Qualifier is selected, the qualifier value must be chosen from the **Qualifier Values** menu. The third step is selecting the data source, which can be: * The data calculated by CACAO from the **Journal** of each taxpayer * The data submitted by the taxpayer on the **Declared Income Statment** The last step is to choose the base period for creating the General Analysis, on the **Base Period** menu. With all the selections made, select `Search` to retrieve the data and the analysis desired.

## What's the purpose of the Income Statement Analysis? The Income Statement Analysis compares the information provided by the Taxpayer, in the Income Statement file sent to the Tax Administration, against the information calculated by CACAO with the data available from the daily Journal sent by the taxpayer. Differences between the two information might indicate errors on the information provided by the Taxpayer. ## Using the Income Statement Analysis To use the General analysis, select the `Analysis` option located at the sidebar menu, then select `Income Statement Analysis`. On the **Name** menu, select the taxpayer that will be subjected to the analysis. On the **Base Period** menu, select the year whose income statement will be compared. With all the selections made, select `Search` to retrieve the data and the analysis desired. A table will be shown with the following information on each row: * The **statement** analyzed * The data **declared** by the taxpayer on the Income Statement * The data **calculated** by CACAO from the journal * The **difference** between the two values, if any.

## What is the purpose of the Taxpayer view? The Taxpayer view presents a summary of different informations regarding a selected taxpayer and the state of his business. For a given taxpayer, the **Taxpayer view** shows, if exists: * The **Equity Stake** the taxpayers has on other businesses * The **Shareholders** of the selected taxpayer * Regarding the **Revenue Net Sales and Services and Gross Profit**, the declared values and the ones calculated by CACAO from the journal * The amount of **Tax Provisions** * The **Major Expenses** of the taxpayer * The taxpayer's **Major Customers and Suppliers** ## Using the Taxpayer view To use the General analysis, select the `Analysis` option located at the sidebar menu, then select `Taxpayer view`. On the **Name** menu, select the taxpayer that will be subjected to the analysis. On the **Base Period** menu, select the year whose income statement will be compared. With all the selections made, select `Search` to retrieve the data and the analysis desired.

## What is the purpose of the Accounting Flows analysis? The **Accounting Flows** analysis graphically shows the _double-entry bookkeeping_ used by the taxpayer to create the journal presented to the Tax Administration. Each financial transaction is recorded in at least two different ledger accounts, one being a **credit entry** and the other being a **debit entry**. Multiple credits or debits entries may exist on a single financial transaction, given that the sum of all credits of a transaction equals the sum of all its debits. Each transaction is represented by an _arrow_ starting from the account being **credited** and ending on the account being **debited**. If multiple financial transactions starts and ends on the same accounts, its values are summed and the arrow connecting the two accounts gets thicker. > **Attention!** > The **thicker** an arrow connecting two accounts are, the greater the sum of the financial transactions connecting the two accounts. ## Using the Accounting Flows analysis To use the General analysis, select the `Analysis` option located at the sidebar menu, then select `Accounting Flows`. On the **Name** menu, select the taxpayer that will be subjected to the analysis. In order to select the period of the analysis, select the start date on the **Initial Date** menu, and the end date on the **Final Date** menu. With all the selections made, the accounting flows will be shown. > **Attention!** > If will **hover** the mouse over an arrow, the sum of the financial transactions connecting the two accounts will be show. ### Filters The **Accounting Flows** has two main filters: **selected account** and **value range**. If you click on a single account, only the arrows connecting this account will be shown. The moment you click anywhere on the accounting flows, all arrows available return. On the upper side of the accounting flows, there is a dispersion graphic where each **dot** represents an arrow. The dots are displayed accordingly to its value, and the x-axis of the graphic represents all possible values. Changing the position of the left and right bar of the graphic along its x-axis controls which arrows are displayed. > **Attention!** > Both filters can be used simultaneously.

## What are Interpersonal Relationships? Usually a taxpayer has multiple relationships with other persons, who are taxpayers themselves. A legal entity might have a director, a natural person might have an accountant, and so on. Registering those interpersonal relationships allows for one taxpayer to submit or access data to CACAO on behalf of another taxpayer. ## Interpersonal Relationships list To list and manage the Interpersonal Relationships, select the `Interpersonal Relationships` option located at the sidebar menu. A table with a list of interpersonal relationships will be shown. For each relationship in the list, the following are available: * **Referring Person**, which indicates the "origin" of the relationship * **Referred Person**, which indicates the "destiny" of the relationship * The **Relationship Type**, such as _accountant_ or _legal representative_ * An indication if the relationship was **removed** from the pool of active interpersonal relationships * A `trash` icon for removing a relationship. > **Atention!** > CACAO must store all interpersonal relationships in order to create a _log_ for auditing purposes. That way, a relationship is never **removed** from the system, but only put on a inactive state that does not allow any further access to the *Referring Person* data by the *Referred Person*. ## Interpersonal Relationship Creation To create a new Interpersonal Relationship, select the `New Interpersonal Relationship` button on the bottom left of the Interpersonal Relationship's table. A interface for inserting the Interpersonal Relationships information is displayed. After fulfilling all required information, select the `Save` button. ## Editing user information CACAO does not allows editing an Interpersonal Relationship. You must remove the relationship using the `Trash` icon than create a new one.

## What is the purpose of Domain Tables in CACAO? Some of the data that a Tax Administration receives must adhere to a specific domain in order to be proper validated. For instance, there are different sets of standards that govern financial reporting and accounting, and the Tax Administration must establish which ones will be accepted and validated. The **Domain Tables** functionality allows the Tax Administration to define sets of custom domains for the data that will be included in the files to be uploaded by the taxpayer to CACAO. The domain is the collection of all of the objects in a system. In CACAO, a domain specifies all the possible values a given data may represent. ## Domain Tables examples One of the most simple specific domain necessary for a accounting data is the **nature** of a financial transaction. Usually this domain contains only two values: _debit_ or _credit_. Setting up a **Financial Transaction nature** domain with only the _debit_ and _credit_ values informs CACAO that any other value for this domain must not be accepted, and the the file uploaded to CACAO will be rejected. > **Attention!** > In CACAO, domain tables are **language sensitive**. So it the Tax Administration is running CACAO on a multilanguage environment, the domain tables must indicate all possible values for each language accepted. For instance, a **Financial Transaction nature** domain table might looks as the following: > |Entry Key|Entry Language|Entry Description| > |-|-|-| > |D|English|Debit| > |C|English|Debit| > |D|Spanish|Débito| > |C|Spanish|Crédito| Other example of a specific domain is the accounting standard used. A Tax Administration might accept both IFRS (International Financial Reporting Standards) or GAAP (Generally Accepted Accounting Principles), and as such CACAO must be configured with two domain tables, one for each standard. For instance: **IFRS Account Category Domain Table excerpt** |Entry Key|Entry Language|Entry Description| |-|-|-| |1|English|Asset| |1|Spanish|Activo| |2|English|Equity| |2|Spanish|Patrimonio Neto| |3|English|Liability| |3|Spanish|Pasivo| **GAAP Account Category Domain Table excerpt** |Entry Key|Entry Language|Entry Description| |-|-|-| |1|English|Asset| |1|Spanish|Activo| |2|English|Liability| |2|Spanish|Passivo| |3|English|Equity| |3|Spanish|Patrimonio Neto| Close inspection of the two domain tables shows that IFRS and GAAP uses the same account category code for **Asset**, but different codes for **Liabilities** and **Equities**. Without the domain tables definitions, CACAO would not be able to understand those differences. ## Managing the Domain Tables To manage the Domain Tables, select the `Domain Tables` option located at the sidebar menu. A table will be shown with all the Domain tables already registered in CACAO. For each domain table, it will be shown: * The **Name** of the domain table * The **Version** of the domain table * The **Group** that the domain table is part of * A `pen and paper` icon representing the **Edit Domain table** function * A `trash` icon representing the **Delete Domain table** function > **Attention!** > If you click on a Domain table, or on the `pen and paper` icon, both actions will take you to the **Edit Domain Table** function. In order to create a new **Domain Table**, select the `New Domain Table` button on the lower left corner of the Domain tables list. On the **New Domain Table** page, insert the name of the domain table on the **Name** menu, the version of the table on the **Version** menu, and the group (if any) that the domain table belongs on the **Group** menu. Select the `Save` button to create the Domain Table. In order to add the entries to the domain table, insert the entry label on the **Entry Key** menu, select the language of the entry on the **Entry Language** menu, and insert the entry description on the **Entry Description** menu. Select the `Add` button to insert the entry on the Domain Table. > **Attention!** > In order to persist the changes to the domain tables (changes to the table name, version or group, and inserts, deletes or edit of table entries), you must select the `Save` button. Otherwise the changes will be lost. The same procedure for adding entries can be used to edit informations on the domain table.

## What are Document Templates in CACAO? CACAO is a system for receiving and maintaining files with accounting data of taxpayers. In order to correctly receive files and validate them, CACAO must know beforehand its layout and how to interpret its data. The **Document Templates** are available after selecting the `Document Templates` option from the sidebar menu. > **Attention!** > Each of the document templates available on the `Upload Documents` functionality must be informed and specified on the `Document Templates` option prior to its use. A **Document Template** contains the following information: * The **Name** of the template * The **Version** of the template, used to keep a historical log of the template modifications * The **Periodicity** that the information must be sent by the Taxpayers to the Tax Administration * A **group** identification to consolidate different templates regarding a common goal * If the template is **Active**, meaning that its possible to upload files with this template * It the template is **Required**, meaning that for CACAO to properly assess the accounting data, a file with this template must be submitted * A list of **Fields**. For each field of the template, it must be informed: * Field **Name** * The **type** of the information of the field * The **Mapping** of the information to specific information expected by CACAO * If the information: * contains **Personal data** * is **required** of **optional** * must be **unique** inside the file * A **description** of the field The **type** of the field indicates the format that CACAO must expect when reading the field. CACAO understand different types, such as: * **Character**: a string of alphanumeric characters * **Integer**: a number without decimal divisions, such as "12" * **Decimal**: a number that accepts decimal divisions, such as "12,34" * **Boolean**: a field containing only "true" or "false" * **Date/Time**: information with a date *and* a time * **Date**: a date containing day, month and year * **Month**: the identification of a single month * **Domain Specific**: a special type of field defined by the Tax Administration * **Nested Structure**: a field composed by other fields > **Attention!** > For more information regarding the **Domain Specific** field type, please refer to the `Domain Tables` entry on this user manual. The **mapping** of a field matches its information with one of the specific information expected by CACAO: * Any Field (when the field does not have a specific mapping) * Taxpayer ID * Tax Year * Tax Semester * Tax Month * Tax Day * Tax Due Value * Tax Code * Tax The following table shows a small example of a Field list from a Chart of Accounts: |Name|Type|Mapping|Personal Data|Required|Unique|Description| |-|-|-|-|-|-|-| |Identification|Character|Taxpayer ID|Yes|Yes|Yes|Taxpayer Identification Number| |Year|Integer|Tax Year|No|Yes|Yes|Fiscal year of this financial reporting| |Address|Character|Any Field|No|No|No|Taxpayer work address| ## Document Inputs Each Document Template must have at least one **Document Input** in order to be submitted to CACAO. A Document input shows CACAO how to find the fields of a Document Template within a specific file format. CACAO can read the following file formats, that can be used as Document Inputs: * **CSV** - Comma separated values * **XML** - Extensible Markup Language * **XLS** - Excel spreadsheets * **JSON** - JavaScript Object Notation * **PDF** - PDF forms * **DOC** - Microsoft Word Each input type has its own characteristics. CACAO tries its best to match the content of the files with the fields defined by the Document Template. The match may take place in multiple ways. CACAO has a sequence of trials and only if none of them succeeds, it returns a validation error. The following list shows the different (and sequential) trials: - **First Trial**: using regular expressions, tries to extract values from the file name (ex: the file name contains the taxpayer id and tax year) - **Second Trial**: extract the values from the row index (row position) - **Third Trial**: extract the values from the column index (column position) - **Fourth Trial**: using regular expressions, tries to match the name of the columns from the files with the Document Template fields Not every trial is suited for all the file formats. For example, the **Third Trial** trial is not suitable for **JSON** and **XML** types, since one cannot determine column positions as we would in a **CSV** file. One must remember this is the order of trials. For instance, if the file name does not match the regular expressions defined in the **First Trial** trial, the **Second Trial** trial will be executed. This sequence is field-wise, it reinitializes for each Document Template's fields attempt of matching. For instance, if the taxpayer id was extracted from the column index (**Third Trial**), for the tax year the sequence begins from the **First Trial**, trying to extract from the file name. ## Managing Document Templates On the bottom left of the **Document Templates** list is a button labeled `Manage Templates`. Select this button if you want to: * Create a Document Template from scratch * Use one of CACAO Archetypes * Edit on of the existing templates After selecting the `Manage Template` option, CACAO will shown three new options: `Empty Document Template`, for creating document templates from scratch, `Archetype`, that will list all available archetype for you to choose from, and `Existing Document Template`, that will show a list of existing document templates. ## Create a Document Template After selecting the `Empty Document Template` option, the **New Document Template** for will be shown. To explain how create a **Document Template**, its easier step by step. At the **New Document Template** form, you must provide: * **Document name**: the name of the template. * **Version**: for version, you may start with something like _1.0_. When you are creating a evolution over an existing one, without removing the previous template, you would probably choose another version number (e.g. 1.1, 2.0 and so on). * **Active**: You should remember to click on ‘ACTIVE’ toggle button to make it available for use once it’s complete. You should only _activate_ a template after you have completed all the steps regarding fields and inputs configurations. * **Periodicity**: This is where you inform to CACAO if there is some periodicity for receiving files. * **Group**: This is where you inform a name to group up other related templates together. * **Required**: This field is only useful if you have more than one template grouped together (i.e.: with the same ‘group’ name). A _required_ template is one that must be present to proceed parsing other templates of the same group. At the bottom of the **New Document Template** form, you will create the **template fields**. This is the final structure your data will have once it has passed through all data processing phases (i.e. validation, extract, transform and load). For each field you need to press the `New Template Field` button and fill in the field specification. A ** Template Field** form will be shown, where you must provide the required information. Some advice: * The **field name** must not correspond to the file contents. You are free to choose something meaningful for the purpose of data analysis. You should think about all the other files that you would eventually like to store in this same table, possibly coming from other taxpayers or other periods. You should try to keep it simple and not to include something very specific to a particular taxpayer or a particular file. * The **field type** should match what is expected for each field. There are only a few options to select from. For example, fields containing dates should indicate _Date_ for the **Field Type**. This is relevant for the purpose of _data validation_. CACAO will try to validate the data according to their field types. It’s very flexible though. Different formats are allowed for each of them. * The **field mapping** is only necessary for that information that are treated in special ways by CACAO. For instance, if the fields represents the identification of the taxpayer, a specific mapping must be chosen (the ‘taxpayer ID’). For all the other fields without special information you may keep _no mapping_, which means they will be treated as _generic data types_. * The **required** flag is used for declaring some field as mandatory. If some field is configured as **required**, the file contents are considered if they provide some valid data for those fields. All the other fields are considered _optional_, in which case they may be absent. * The **personal data** flag is used only for documentation purposes, to easily identify among all the collected data which ones should be considered as _personal data_ (things like names, identification numbers, addresses, etc.). In various jurisdictions _personal data_ have tighter control. * The **file uniqueness** flag is used for determining which field (or a combination of multiple fields) should be used as _uniqueness criteria_. If eventually another uploaded file matches the same criteria, the contents from the previous one will be automatically deleted from the database. For example, if we are considering the _taxpayer id_ as the _uniqueness criteria_, it means that any other file we upload regarding the same taxpayer will fully replace the previous one. This may not be the case for other templates. For example, if you want to hold different data for the same taxpayer regarding different years, you should point out an additional field (maybe one called ‘year’) as also being a _file uniqueness_ criteria (both the _taxpayer id_ **AND** the _year_). Please note that any additional criteria must somehow be informed in each incoming file. Once you have provided all the information regarding a template, click the `Save` button to store these definitions in CACAO. > **Attention!** > Remember to always select the `Save` button in order to persist any changes made to the **Document Template**. ## Creating a Document Input for a Document Template In the previous step we defined the ** Document template**, which accounts for the final structure of our data. In this step we need to inform to CACAO the means for retrieving this information out of the incoming files. This is what we call **Document Input**. For each template you may inform multiple alternative ways (multiple document inputs). First, select the template we just created at the previous step, and then click over the `Document Inputs`. Select the `New Document Input`. Various Document Input options will be show. You must fill the following form accordingly to the Document Input select. A few advice: * The choices you may have to configure depend on the file format you chose as **input**. In this step by step we are configuring an Excel file format as input, so we have several choices regarding Excel concepts (e.g.: sheets, rows, columns and cells). If we were configuring a different file format (e.g., some ‘TEXT/CSV’ file or some ‘XML’ file), the options would be different and fewer. * There are several options to configure because CACAO is very flexible. But you don’t have to provide all of them. You should focus on only those criteria that match your needs. * Each field may come from different parts of the file. Therefore, you provide independent configurations for each one. * Since there are so many options, it may be hard to properly configure it for the first time. This is a way to reason about all the possible choices: * Is the information gathered from the original filename or is it informed inside the file contents? If it’s coming from the filename, you should only inform for the field the **Filename expression** criteria and ignore all the other criteria. In general, it will be gathered from the file contents. But if you want, you may indicate that some information must be provided as the filename itself – in this case, someone uploading files should pay attention to the names of the files they are uploading. * Is the information gathered from one particular sheet? If there is only one sheet of interest for a particular field, you should provide either the sheet name (as **Sheet Expression** criteria) or the 0-based sheet position in the file (as **Sheet Index** criteria). If the information may come from any sheet, you should keep both sheet-related criteria empty. * Is the information gathered from one particular column? If there is only one column of interest for a particular field, you may inform this in different ways: * If the column position is fixed and if it’s known beforehand, you may either inform the 0-based column position as the **Column Index** criteria (e.g: _0_ for the first column), or the _Excel-like column range expression_ as the **Cell Name/Expression** criteria (e.g.: _A:A_ for the first column). The option **Column Index** expects that one line of the table contains _column titles_, so the first row of the table will be ignored. The option **Cell Name/Expression** doesn’t make this assumption, so all rows will be treated as data. Please note that if the incoming file does not match exactly the same expected column order (e.g. if it eventually included or suppressed other columns, shifting the desired column to the right or to the left), this will ruin the column ordering, thus preventing this file from being successfully validated. * If the information comes from a particular column, but you want to give some flexibility to the column position (maybe the column position may vary from file to file), you may provide in the **Column Expression** criteria some text that should match the _column title_ of interest. In this case it’s expected that one line of the table contains _column titles_. These are the texts that will be matched with the provided expression. For example, if the data contains 3 columns and if the first line contains the cells Date, Taxpayer and Amount, and if the provided **Column Expression** is Amount, only the third column will be considered for the field. If eventually another file changes the column order (let’s say the second file informs the Amount as the first column) it will be properly parsed by CACAO, since it’s looking for the column whose title matches the provided text expression. * Is the information gathered from one particular row? If there is only one row of interest for a particular field, you may inform this as the 0-based **Row Index** criteria. The first cell of the row will be discarded (it will be treated as some sort of data ‘label’). All the remaining cells of the provided row will be considered as data for that field. * If none of the above criteria match your needs, you may use the ‘Cell Name/Expression’ for your criteria in one of the different ways: * The **Cell Name/Expression** may refer to some _name_ you provided in Excel file. Please note that _named cell_ is a feature specific to Excel. You may give _names_ to any particular cell or to any range of multiple cells – and this is performed in Excel file itself. For example, you could indicate in Excel file that one particular column corresponds to the name Amount. If this is the case, you may inform the same name (in this case, the name _Amount_) as the **Cell Name/Expression** criteria. Doing this way, CACAO will locate in Excel for all cells whose names are declared as provided. * The **Cell Name/Expression** may refer to some _cell address_. For example, A1 is a valid cell address that corresponds to the first column and the first row. You could also provide something like A1:C3 to refer to multiple cells (in this case, to all the cells spanning over the first 3 columns and 3 rows). You could also write an expression like _A:A_ to refer to an entire column (in this case, the first column). There are many other possibilities regarding **cell range expressions**. * The **Cell Name/Expression** may also refer to some kind of _regular expression_ including a _group capture_ syntax to extract specific information from cell contents, wherever they occur. This is a very advanced topic and may be useful for those situations where the contents must be extracted from inside individual cells spread over the workbook sheets. As you can see, there are many different options of file layouts that can be mapped into CACAO. Some of them are very simple to represent (like those ones that have some sort of **static table structure** and some may require the use of some advanced techniques like _regular expressions_. The option `ACCEPT PARTIALLY INVALID FILES` makes it possible to accept incoming files whose contents may not satisfy all the criteria (the ones related to **required** fields). If the ‘ACCEPT PARTIALLY INVALID FILES’ is turned on, the _invalid lines_ will be simply ignored from the outcome – but we will still be able to know about their existence if we check the situation of importing such file. > **Attention!** > Remember to always select the `Save` button in order to persist any changes made to the **Document Input**. > **Attention!** > If you chose to use an **Archetype**, you can see how it handles Document Inputs, as a real working example. ## Archetype In order to facilitate the creation of Document Templates, CACAO ships some document template **Archetypes**. Those Archetype are pre-filled document templates, for a common set of accounting documents, each with a complete set of fields. CACAO's archetypes are: * Chart of Accounts * General Ledger * Income Statement * Opening Balance * Shareholding * Generic To use the Archetypes to kickstart a Document Template creation, select the `Document Templates` option located at the sidebar menu. Then select the `Manage Templates` option on the lower left of the Document Templates list, and finally select the `Archetype` card. After selecting the desired archetype, CACAO will show the **Edit Document Template** interface. From this point, its possible to further customize the Document Template. ## Editing existing Document Templates There are two options to select a template for editing : (1) selecting a template from the **Document Template** list shown after selecting the `Document Templates` option from the sidebar menu, or (2) selecting a template from the `Existing Document Template` option after selecting the `Manage template` button. The difference between the 2 previous approaches are: * (1) this approach shows all the details of the document template, but it's blocked for edition. You have to select the `Edit` button to access the **Edit Document Template** form. * (2) this approach leads you directly to the **Edit Document Template** form. Once the **Edit Document Template** form is displayed, there are no more differences between the approaches. > **Attention!** > Remember to always select the `Save` button in order to persist any changes made to the **Document Template**. To **edit** a Document Template, use the same concepts and procedures for creating a new Document Template.

## What are API and why CACAO have them? An **application programming interface** (API) is a connection between computers or between computer programs. It is a type of software interface, offering a service to other pieces of software. In contrast to a user interface, which connects a computer to a person, an **API** connects computers or pieces of software to each other. It is not intended to be used directly by a person (the end user) other than a computer programmer who is incorporating it into software. CACAO expose different API in order to allow taxpayers' information systems to connect directly to CACAO, and execute all actions, such as file uploading, automatically. CACAO's API also allows other information systems from the Tax Administration to interact and share information between them without human intervention. > **Attention!** > All CACAO's API adhere to the same Role Based Access Control that the user interface implements. **Not all API are available to all roles.** > If you don't have access to a API that you need, please make contact with the Tax Administration. ## Configuring an Access Token **Before** using any of the CACAO's API, you must create a **access token**. This token will replace the user/password information in order to login on CACAO and access the desired functionality. To create an access token, select the `CACAO Configurations` option located at the sidebar menu. Then select the `Token API Configuration`. An interface for managing your access token will be displayed, with the following options: * **View generated token** shows you the token that you have already created (if any) * **Generate a new token** creates a new token or replaces the previous one * The **Delete token** options deletes your token from CACAO Please, **keep this token information a secret**. Do not share or publish this information. > **Attention!** > If you believe your token has been disclosed or compromised, you must access the `Token API Configuration` option and delete it. > All actions authenticated by the token is of the sole responsibility of its owner. The Tax Administration **do not** have access to the tokens. ## Available API To list all available API, select the `CACAO Configurations` option located at the sidebar menu. Then select `CACAO API Documentation`. A _Swagger_ interface will be shown. For each API available, _Swagger_ shows the description of the API, its parameters and responses. > **Attention!** > You **must append** your authentication token to the API parameters in order to access them outside the Swagger environment. For instance, suppose your authentication token is **12345678-abcd-efgh-ijkl-123456789012** and that CACAO is hosted at **wwwcacao.host**. > A command line to access the API that lists all available document templates would be like: > > `curl -X GET "https://wwwcacao.host/api/template" -H "accept: application/json" -H "Authorization: api-key 12345678-abcd-efgh-ijkl-123456789012"` > > where **"Authorization: api-key cbc1d881-b8bc-4e2d-b236-c168b01fc692"** is the parameter that must be included in the header of the API call.