NCF Manager Module
##################

The ncf_manager module manages Dominican Republic fiscal receipt numbers
for Tryton invoices.

It provides NCF/e-CF types, fiscal sequence management, invoice fiscal fields,
NCF assignment on posting, and fiscal preparation for debit and credit notes.

Installing
**********

Install the package and activate the module in the database::

    pip install unpaismejor_ncf_manager
    trytond-admin -d <database> -u ncf_manager

Publishing
**********

The included Gitea Actions workflow builds and publishes the package to the
Gitea PyPI registry from version-series branches such as ``7.0``.

Configure this repository secret:

* ``REGISTRY_PASSWORD``

The module assigns fiscal numbers transactionally from ``ir.sequence.strict``.
It does not sign or transmit e-CF documents; transmission remains the explicit
responsibility of an electronic invoicing connector.

Version compatibility
*********************

The 7.0 and 8.0 series share the same fiscal models, workflows, importer,
validations and tests.  Only the module registration, packaging metadata and
report XML required by each Tryton series remain version-specific.

Authorization workflow
**********************

NCF authorizations follow the protected workflow ``Draft → Active →
Finished``.  Create the authorization and its fiscal lines in draft, then use
the **Activate** button.  A line can select an existing strict sequence or ask
the module to create one on activation from its authorized range.  Activation
checks company, fiscal type, prefix, padding, validity, availability and range
overlap.  Incoming supplier documents and outgoing customer documents use
independent numbering authorities, so overlap is enforced only within the
same document direction.  The last issued number automatically finishes the
line.  Finishing an authorization closes every remaining active line without
reusing numbers.

Legacy migration lines keep their original technical sequence immutable after
activation.  Prefix selection is enforced while a line is in draft and fiscal
activation performs the same server-side validation; closing a protected
historical line therefore does not invalidate already-linked invoices.

Electronic fiscal numbers are only reserved by this module.  Activating an
E-series authorization never signs or transmits an e-CF to DGII.

Importing DGII authorizations
*****************************

Use **NCF Manager → Import DGII Authorization** to load an authorization
downloaded from the DGII Virtual Office.  XML, CSV and the HTML table exported
with an ``.xls`` extension are supported and detected from their content.
The importer creates an independent workflow record for every ``NUM_AUTOR``.
The same ``NUM_SOL`` may therefore appear in several records without modifying
an authorization that is already active; file names are not used as fiscal
identifiers.  It validates
approval status, company name, NCF type, prefix, range and approved quantity,
and stores the original file, SHA-256, user and import date for audit.

Imports are idempotent.  Reimporting an equivalent CSV, XML or XLS record does
not create another line, while different fiscal data for an existing
authorization is rejected.  The safe default leaves the result in draft so
the first number can be reviewed.  Immediate activation is explicit and still
does not transmit electronic documents.