Skip to content

Feature Add positions DTOs and enhance invoicing#32

Closed
kaspernowak wants to merge 2 commits into
codebar-ag:mainfrom
kaspernowak:feature/add-dtos-for-positions-and-enhance-invoicing
Closed

Feature Add positions DTOs and enhance invoicing#32
kaspernowak wants to merge 2 commits into
codebar-ag:mainfrom
kaspernowak:feature/add-dtos-for-positions-and-enhance-invoicing

Conversation

@kaspernowak

@kaspernowak kaspernowak commented Jun 15, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor

This PR introduces complete support for creating and sending invoices using structured DTOs, including all supported Bexio position types.

✅ What’s Included

  • New DTOs for all invoice position types:
    • AddDefaultPositionDTO
    • AddTextPositionDTO
    • ...and others under src/Dto/*
  • New request classes:
    • CreateAnInvoiceRequestNew
    • EditAnInvoiceRequestNew
    • SendAnInvoiceRequest
    • MarkAnInvoiceAsSentRequest
    • ...and Create, Edit, Delete, Fetch, and FetchList requests for all position types
  • New test coverage for the above requests and DTOs
  • Support for sending and marking invoices as sent via SendInvoiceDTO

💡 Usage Example

$invoiceDto = new CreateInvoiceDTO(
    title: 'Test',
    contact_id: $contacts->first()->id,
    // ...
    positions: [
        new AddTextPositionDTO(
            type: 'KbPositionText',
            text: (string) Str::uuid(),
            show_pos_nr: true
        ),
        new AddDefaultPositionDTO(
            type: 'KbPositionCustom',
            amount: 1,
            unit_id: $units->first()->id,
            account_id: 145,
            tax_id: $taxes->first()->id,
            text: Str::uuid(),
            unit_price: 100,
        ),
    ],
);

$invoice = $connector->send(new CreateAnInvoiceRequestNew(invoice: $invoiceDto))->dto();

$send = $connector->send(new SendAnInvoiceRequest(...));
$markAsSent = $connector->send(new MarkAnInvoiceAsSentRequest(...));

⚠️ Compatibility Note

The existing CreateAnInvoiceRequest class appears to be incompatible with the documented example due to a type mismatch in the filterPositions() method:

Argument #1 ($positions) must be of type Collection, array given

To avoid breaking changes, I've added new request classes (CreateAnInvoiceRequestNew, etc.) that work with the new DTO structure.
We may want to decide whether to:

  • Fix and maintain the old request for compatibility
  • Or deprecate it and focus solely on the updated approach

closes #7

@StanBarrows StanBarrows self-assigned this Jun 15, 2025
@StanBarrows
StanBarrows marked this pull request as draft June 15, 2025 17:11
@kaspernowak
kaspernowak marked this pull request as ready for review June 17, 2025 12:46
@kaspernowak
kaspernowak force-pushed the feature/add-dtos-for-positions-and-enhance-invoicing branch from 20011fd to 14fefa3 Compare June 20, 2025 12:37
@StanBarrows
StanBarrows requested a review from RhysLees June 30, 2025 22:46
@StanBarrows StanBarrows assigned RhysLees and unassigned StanBarrows Jun 30, 2025
@StanBarrows

StanBarrows commented Jul 2, 2025

Copy link
Copy Markdown
Contributor

@kaspernowak
We’ve just completed the OAuth PR and will take a closer look at this in the coming weeks.

@kaspernowak

kaspernowak commented Jul 2, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

@StanBarrows Thank you! Looking forward to it. I think this would have higher prio than #34, as the structured addresses won't really be required before December.

@kaspernowak kaspernowak mentioned this pull request Jul 2, 2025
Closed
@StanBarrows StanBarrows mentioned this pull request Jul 7, 2025
Closed
8 tasks
@kaspernowak

kaspernowak commented Jul 21, 2025

Copy link
Copy Markdown
Contributor Author

@StanBarrows @RhysLees do you have an estimate of when you would have time to take a closer look at this?

@StanBarrows

StanBarrows commented Jul 21, 2025

Copy link
Copy Markdown
Contributor

@kaspernowak
Can’t promise it 100%, but likely sometime in August or September.

It’s quite a big refactor, and we want to do it properly. I’ve planned around 2–3 days to review, adjust, and test it thoroughly.

But if that’s too long for you, feel free to create a fork and merge it there in the meantime.

@kaspernowak

kaspernowak commented Jul 21, 2025

Copy link
Copy Markdown
Contributor Author

@StanBarrows Thank you! Hopefully we won't need this before you have time to look at it, but otherwise we will run this from a fork.

Do you mean this is a big refactor due to that apps you support currently use the current invoice approach? I feel like this PR alone adds more additional features than it affects existing functionality, and therefore I also feel like this is a much smaller refactor than the OAuth2 PR, but I might be wrong.

@StanBarrows

StanBarrows commented Jul 21, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor

@kaspernowak

As far as I know, your PR was built as an addition so that we can support both methods. I’d first like to review the current Bexio API documentation myself, since we developed this approach some time ago, and then decide whether to keep both or drop the existing implementation. It would also make sense to check if any other updates are needed for other objects, as there are still open PRs that involve further API changes. I'm just not updated about any changes to the Bexio API the last couple of years.

After that, Rhys will likely review your entire PR and process it and then update the documentation accordingly.

All in all, I need to set aside time to properly look into this — and after that, it’s up to Rhys. With a major go-live coming up in early August, even finding a few hours a day is currently not feasible.

P.S. The OAuth integration — even with your PR as a reference — still took about two full working days to reach its current state. So the current PR is maybe not more complex in a technical way, but it involves more research and coordination with other people, which makes it feel more complex to me. And yeah, then I’ll also need to update all the projects where I’ve implemented the current state, to avoid technical debt. And since this isn’t covered by any customer budget, I’ll have to fit it into time slots where I have some capacity.

@kaspernowak

kaspernowak commented Jul 21, 2025

Copy link
Copy Markdown
Contributor Author

@StanBarrows I completely understand, thank you for the explanation.

@RhysLees RhysLees removed their assignment Aug 3, 2025
@kaspernowak

kaspernowak commented Sep 3, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Hello @StanBarrows, just checking in, do you think you will have the capacity to look at this during this month?
Also, is there anything I can do to help out?

@StanBarrows

StanBarrows commented Nov 28, 2025

Copy link
Copy Markdown
Contributor

Hey @kaspernowak

Thanks again for your initial work on this feature implementation. Quotes and the updated item-position handling are now implemented in the latest release:

https://github.com/codebar-ag/laravel-bexio/releases/tag/v13.5

Please review the changelog.md carefully if you are running this in production:
#57

I’ve created a new ToDo for the missing invoice requests and added it to the roadmap. We will likely tackle this when we polish the package for the upcoming Laravel 13 version and PHP 8.5:
#56

Best regards
Sebastian

@kaspernowak

kaspernowak commented Dec 2, 2025

Copy link
Copy Markdown
Contributor Author

@StanBarrows Thank you for the implementation!
I will test this soon when we will start implementing the invoicing logic.
Is it correctly understood that the only features missing from my PR, is the SendAnInvoiceRequest and MarkAnInvoiceAsSentRequest requests? In that case, I will create a fork from main and add these requests.
Would you want me to create a PR from my fork with these requests after I have battle tested them, without fixtures etc.? Or would you rather implement the remaining requests yourself?

@StanBarrows

StanBarrows commented Dec 3, 2025

Copy link
Copy Markdown
Contributor

@kaspernowak

I’ll add them next week at the latest together with #58.
The issue is that re-creating the invoice fixtures with the new Bexio setup takes ages. I had to create dedicated folders for the mixed requests required to prepare a test — for example, before you can send an invoice, it needs to be in the open state, and so on. It already took me quite a while just for the quotes, but yeah, I’ll get it done.

Cheers
Sebastian

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@RhysLees RhysLees Awaiting requested review from RhysLees

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Feature Request | Invoice Endpoints

3 participants

@kaspernowak @StanBarrows @RhysLees