Feature request: A generic invoice provider plugin structure

[talhakaanozkan]

Hi,

GrandNode2 has a clean plugin structure for payment and shipping providers, which makes adding new integrations straightforward. I couldn't find a similar structure for invoicing.

Many stores need to send invoices to external services (accounting software, invoicing platforms, electronic invoicing systems). Right now there is no standard way to plug these in.

Suggestion

1. Invoice provider interface: A common interface (e.g. IInvoiceProvider) that plugins can implement, covering basic operations such as create, send, cancel and get status.
2. Trigger setting: An admin option to choose when an invoice is created (order placed, order paid, order shipped, or manually).
3. Invoice record: Storing invoice data linked to the order, such as invoice number, status, date and a link to the document.
4. Admin panel: Showing invoice details on the order page, with actions like "resend" and "cancel".
5. Customer side: Letting customers download their invoice from the order details page.
6. Default provider: The existing PDF invoice could become the default provider, so nothing changes for stores that don't need an external service.

Questions

• Would you consider adding something like this to GrandNode2?
• If it's not planned soon, could you provide a sample invoice plugin template, similar to the existing payment and shipping plugins?

Thanks for the great work on GrandNode2!

[KrzysztofPajak]

Hi @talhakaanozkan, thanks for the detailed proposal. Invoicing integrations (accounting tools, national e-invoicing systems such as e-Fatura or KSeF) are a real gap, and we agree a standard extension point would be better than every plugin doing it its own way.

Some things already exist that cover part of this:

• Invoice record. The Document entity (Grand.Domain.Documents) already has Number, StatusId, DocDate, DueDate, TotalAmount, OutstandAmount, CurrencyCode, DownloadId and Link. It can be linked to an order with ReferenceId = Reference.Order and ObjectId = order.Id, and typed with DocumentType. We would rather build on it than add a second entity for the same thing.
• Customer side. Documents already show in the customer's account (My account → Documents), with a download when DownloadId is set.
• Triggers. OrderPlacedEvent, OrderPaidEvent, ShipmentSentEvent and OrderCancelledEvent are published today. A plugin can handle them and issue an invoice without any core changes.

A few things would need to be designed differently from the proposal:

1. Cancel vs. correction. In many jurisdictions an issued invoice cannot be cancelled, only corrected with a credit note. Refunds and partial refunds also need a correction document. The contract should model "issue correction", not "cancel".
2. Asynchronous delivery. External invoicing APIs are often slow or queue-based. Calling them inside the OrderPaidEvent handler would tie payment processing to a third-party service. A safer shape is to record a pending document on the event, then have a scheduled task deliver it with retries and track its status.
3. Keep the contract thin. Tax rules, numbering schemes and buyer data requirements differ a lot between countries. The core interface should hand the provider the order and let it map the data to its own format, rather than trying to model every country's tax rules.
4. Store and vendor scope. Numbering per store, and invoices per vendor in marketplace setups, should be part of the design from the start.

Suggested path: start with a sample invoice plugin built on the existing events and the Document entity, as you suggested in your second question. It needs no core changes, works today, and will show what a core IInvoiceProvider actually needs (likely Issue, IssueCorrection, GetStatus, GetDocument), plus a per-store trigger setting. Once one or two real integrations exist, we can promote that contract into core without having to guess.

If you are working on a specific integration (e-Fatura?), it would be a great first implementation. Feel free to share its requirements here.

[talhakaanozkan]

Thank you for your detailed and kind response. As you suggested, I’ll try to set up the e-invoice integration based on the documentation, and I’ll share any issues I run into along the way.