[IMP] accouting/l10n_br: Adding information about credit usage in the Avalara integration .rst #13630

giri-odoo · 2025-06-09T13:24:06Z

To comply with legal requirements—especially consumer protection laws (Lei de Proteção ao Consumidor) — and to ensure full transparency with our users, we provide the following explanation of how credit consumption works in the Avalara integration.

robodoo · 2025-06-09T13:24:09Z

giri-odoo · 2025-06-09T13:24:26Z

@sclo-odoo @vbe-odoo

vbe-odoo

Hello @giri-odoo
Thanks for the PR with the improvements!

I left some comments as part of my pre-review, this PR will be reviewed by other teams after I conclude my review.

Help me improving the PR and commit title, you can take the PR done by @sclo-odoo here #12921
Example: [IMP] accouting/l10n_br: Adding NFC-e feature

That is the title convention needed. You can try using the GitHub desktop to make that edit, try here on the web-based GitHub, if close and create a new PR if those 2 steps weren't possible.

Thanks again!

content/applications/finance/fiscal_localizations/brazil.rst

vbe-odoo · 2025-06-09T16:35:06Z

content/applications/finance/fiscal_localizations/brazil.rst

+   - Correction letter (Carta de Correção)
+   - Invoice cancellation
+   - Other tax validations


Suggested change

- Correction letter (Carta de Correção)

- Invoice cancellation

- Other tax validations

- :ref:`Correction letter (Carta de Correção) <localizations/brazil/correction-letter>`

- :ref:`Invoice cancellation <localizations/brazil/invoice-cancellation>`

- :ref:`Sales Refund via Credit Note <localizations/brazil/credit-notes>`

- :ref:`Sales Complementary Invoice via Debit Note <localizations/brazil/debit-notes>`

- :ref:`Invalidate invoice number range <localizations/brazil/invalidate-invoice-number-range>`

- Other tax validations.

Please do the same for the NFS-e section.
Feel free to modify of add cases, but if we are gonna add the detailed consumption, it is better to add all scenarios where a credit is consumed, which is every time a API call is done, like in the added scenarios. I've added the links to the specific section within the User Doc as we have it, and it is good to refer the user to that section if needed.

For Credit Notes (sales refund) and Debit Notes (Sales Complementary), there's also a Tax Computation required, so maybe you would like to add that a Tax Computation will be consumed on those scenarios as well.
:ref:create an account in AvaTax <localizations/brazil/avatax-account>

vbe-odoo · 2025-06-09T16:35:50Z

content/applications/finance/fiscal_localizations/brazil.rst

+.. important::
+   The Avalara integration operates on a credit-based system, where each interaction with Avalara consumes 1 credit. Below are the main credit-consuming operations:
+
+   :guilabel:`Sales Application`:


Suggested changes on the NF-e section also applies here.

content/applications/finance/fiscal_localizations/brazil.rst

giri-odoo · 2025-06-09T18:49:13Z

@vbe-odoo Thanks for the feedback! I've already made all the changes.

vbe-odoo · 2025-06-09T20:19:40Z

Hello @giri-odoo, thanks for the changes.

Just a few remarks:

The E-Invoice for goods (NF-e) and E-Invoice for services (NFS-e) sections are not looking so nice when checking in runbot (you can check this by copiying the branch name giri-odoo-patch-1 > go to https://runbot.odoo.com/ > Access and wake up the Documentation build and then when on the user documentation > go to Fiscal Localizations > Brazil > there you can check your changes > Video.
PoS Section has the same problem.

Here are the images:

Thanks!
cc' @sclo-odoo

giri-odoo · 2025-06-10T19:58:16Z

Hi @vbe-odoo , I made the requested formatting changes. Please see the images. For some reason I couldn't identify, the initial text of the NFC-e is in bold. Do you have any idea why ?

Here the images:

vbe-odoo · 2025-06-10T21:18:45Z

Hi @giri-odoo I don't really know why it is bolded, and something else I could not identify why is not working, is the last link on the bullet points (- :ref:`Invalidate invoice number range <localizations/brazil/invalidate-invoice-number-range>) somehow that link is not showing up, but I think the guys from MKT could help us with this.

@samueljlieber hello 👋 !
Can you help me review this PR whenever you have some time?

Thanks! 🙏
cc' @sclo-odoo

giri-odoo · 2025-06-11T12:19:44Z

@vbe-odoo Thanks for your response and your help! I'll be standing by!

cc: @sclo-odoo

samueljlieber · 2025-06-13T18:56:11Z

Hi @giri-odoo! Thank you for your contribution! I took a quick look at the helpful information you've added, and there seems to be the same explination in two spots (in NF-e and NFS-e sections).

To avoid writing the same content twice, I suggest placeing this information in a single spot and then it can be referenced in multiple locations.

Since this information is about the Avalara integration, it makes sense to me to include this information in the Avalara integration section, what do you think?

I also suggest slightly modifying the formatting to utilize the note and example admonition blocks. And to try something different, we could use a flowchart to illustrate the credit consumption example:

View the RST code for this 👆

.. important::
   The Avalara integration works on a credit-based system, where each interaction with Avalara
   consumes 1 credit. Below are the main credit-consuming operations:

   **Sales application**

   - Tax calculation on quotations and sales orders.

   **Accounting application**

   - Tax calculation on invoices.
   - Electronic invoice submission (NF-e or NFS-e).

   **Occasional operations**: (each step is billed separately)

   - :ref:`Correction letter (Carta de Correção) <localizations/brazil/correction-letter>`
   - :ref:`Invoice cancellation <localizations/brazil/invoice-cancellation>`
   - :ref:`Sales refund via credit note <localizations/brazil/credit-notes>`
   - :ref:`Sales complementary invoice via debit note <localizations/brazil/debit-notes>`
   - :ref:`Invalidate invoice number range <localizations/brazil/invalidate-invoice-number>`
   - Other tax validations.

.. note::
   If taxes are calculated in **Sales** and later issue the invoice in **Accounting**, the
   calculation happens twice, consuming 2 credits.

.. example::

   .. graphviz::

      digraph avalara_credit_consumption {
         rankdir=TB;
         node [shape=box];

         "Sales order confirmed" -> "Invoice created" [label=" 1 credit (tax calculation)"];
         "Invoice created" -> "Invoice confirmed and submitted"
         [label=" 1 credit (tax calculation)"];
         "Invoice confirmed and submitted" -> "Credits summary"
         [label=" 1 credit (tax calculation)\n+\n 1 credit (submit invoice)"];
         "Credits summary"
         [label="Total: 4 credits", shape=ellipse, style=filled, fillcolor=lightgrey];
      }

Let me know your thoughts @giri-odoo @vbe-odoo and I am happy to discuss further and/or make a second commit with these changes! Thanks! :)

giri-odoo · 2025-06-18T13:11:56Z

Hi @samueljlieber! Thanks a lot for your suggestions — I really liked the idea of improving the structure and using flowcharts to explain the credit consumption logic.

That said, I believe it’s essential to keep the explanation of credit consumption inside each specific document type (NF-e, NFS-e).

Although the logic behind API consumption may look similar across different invoice types, in practice the context of each one matters a lot — especially for our clients, who often rely on this documentation to understand what they’re being charged for. Centralizing this information could create confusion for end users, and even lead to misinterpretations that go against consumer rights legislation in Brazil.

To ensure transparency and clarity, I’d prefer to keep the credit usage documented separately for each type of invoice. I fully agree with adopting note blocks, examples, and visual aids to improve readability.

In fact, according to Article 6, item III of the Brazilian Consumer Defense Code (CDC) — "the right to clear and adequate information about the different products and services, with correct specification of quantity, characteristics, composition, quality and price, as well as on the risks they present" — any additional charges or credit consumption must be explicitly communicated and contextualized. This reinforces the importance of keeping documentation precise and segmented.
🔗 Full text of the CDC (in Portuguese) - https://www.planalto.gov.br/ccivil_03/leis/l8078.htm

Happy to align further if needed. Thanks again for the great collaboration!

cc: @sclo-odoo

samueljlieber · 2025-06-18T13:20:51Z

Hi @giri-odoo, thank you for the additional context about compliance. I'll make a commit to keep the explanation of credit consumption inside each specific document type (NF-e, NFS-e), but with the updated format :)

samueljlieber

Made the formatting changes in c13084e, approving and passing to l10n doc review!

afma-odoo

Thank you @samueljlieber and @giri-odoo for this update!
I just added some suggestions, let me know if you have any questions! Thanks :)

content/applications/finance/fiscal_localizations/brazil.rst

afma-odoo · 2025-06-23T09:02:24Z

content/applications/finance/fiscal_localizations/brazil.rst

+.. example::
+
+   .. graphviz::
+
+      digraph avalara_credit_consumption {
+         rankdir=TB;
+         node [shape=box];
+
+         "Sales order confirmed" -> "Invoice created" [label=" 1 credit (tax calculation)"];
+         "Invoice created" -> "Invoice confirmed and submitted"
+         [label=" 1 credit (tax calculation)"];
+         "Invoice confirmed and submitted" -> "Credits summary"
+         [label=" 1 credit (tax calculation)\n+\n 1 credit (submit invoice)"];
+         "Credits summary"
+         [label="Total: 4 credits", shape=ellipse, style=filled, fillcolor=lightgrey];


I just have an error message for this, but I guess it's because it's not installed on my laptop ;)

Yes, this error is due to not having graphviz installed on your computer, however, I am now seeing the same issue on Runbot.

Although this seems to be possible, to avoid any issues with merging or translations of this graph, maybe it is best to avoid using graphviz.

I'll make a commit to use basic RST syntax to outline this flow.

samueljlieber · 2025-06-23T14:05:44Z

Thank you @afma-odoo, your suggestions were implemented in 498338e :)

afma-odoo

Great, thanks @samueljlieber for the update!
I approve it and ping be-doc-review for the final review :)
Thank you!

xpl-odoo

Very minor suggestions :)

content/applications/finance/fiscal_localizations/brazil.rst

To comply with legal requirements—especially consumer protection laws (Lei de Proteção ao Consumidor) — and to ensure full transparency with our users, we provide the following explanation of how credit consumption works in the Avalara integration. Co-authored-by: Valentino <vbe@odoo.com>

samueljlieber · 2025-06-24T15:12:26Z

Thanks @xpl-odoo! Implemented your suggestions in 91b5020 :)

xpl-odoo

Thanks @samueljlieber (and everyone else ;))
@robodoo r+

vbe-odoo self-requested a review June 9, 2025 14:37

vbe-odoo requested changes Jun 9, 2025

View reviewed changes

giri-odoo changed the title ~~Update brazil.rst~~ [IMP] accouting/l10n_br: Adding information about credit usage in the Avalara integration .rst Jun 9, 2025

vbe-odoo requested a review from samueljlieber June 12, 2025 12:58

samueljlieber force-pushed the giri-odoo-patch-1 branch from e2f20ab to c13084e Compare June 18, 2025 13:44

samueljlieber changed the base branch from 18.0 to 17.0 June 18, 2025 13:45

samueljlieber changed the base branch from 17.0 to 18.0 June 18, 2025 13:45

C3POdoo requested a review from a team June 18, 2025 14:03

samueljlieber approved these changes Jun 18, 2025

View reviewed changes

afma-odoo requested review from afma-odoo and removed request for a team June 20, 2025 08:26

afma-odoo requested changes Jun 23, 2025

View reviewed changes

samueljlieber force-pushed the giri-odoo-patch-1 branch from c13084e to 498338e Compare June 23, 2025 14:04

afma-odoo approved these changes Jun 23, 2025

View reviewed changes

afma-odoo requested a review from a team June 23, 2025 14:38

xpl-odoo requested changes Jun 23, 2025

View reviewed changes

samueljlieber force-pushed the giri-odoo-patch-1 branch from 498338e to 91b5020 Compare June 24, 2025 15:12

xpl-odoo approved these changes Jun 25, 2025

View reviewed changes

robodoo closed this in 84a0f6d Jun 25, 2025

robodoo temporarily deployed to merge June 25, 2025 09:25 Inactive

[IMP] accouting/l10n_br: Adding information about credit usage in the Avalara integration .rst #13630

[IMP] accouting/l10n_br: Adding information about credit usage in the Avalara integration .rst #13630

Uh oh!

Conversation

giri-odoo commented Jun 9, 2025 • edited by vbe-odoo Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robodoo commented Jun 9, 2025

Uh oh!

giri-odoo commented Jun 9, 2025

Uh oh!

vbe-odoo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vbe-odoo Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

vbe-odoo Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

giri-odoo commented Jun 9, 2025

Uh oh!

vbe-odoo commented Jun 9, 2025

Uh oh!

giri-odoo commented Jun 10, 2025

Uh oh!

vbe-odoo commented Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

giri-odoo commented Jun 11, 2025

Uh oh!

samueljlieber commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

giri-odoo commented Jun 18, 2025

Uh oh!

samueljlieber commented Jun 18, 2025

Uh oh!

samueljlieber left a comment

Choose a reason for hiding this comment

Uh oh!

afma-odoo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

afma-odoo Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

samueljlieber Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

samueljlieber Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

samueljlieber commented Jun 23, 2025

Uh oh!

afma-odoo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xpl-odoo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samueljlieber commented Jun 24, 2025

Uh oh!

xpl-odoo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

giri-odoo commented Jun 9, 2025 •

edited by vbe-odoo

Loading

vbe-odoo commented Jun 10, 2025 •

edited

Loading

samueljlieber commented Jun 13, 2025 •

edited

Loading

afma-odoo left a comment •

edited

Loading