[Beta]Order and Shipment integration

[sandervanhooft]

Specifications

• API Version: v2

Describe the issue

I am preparing the Order and Shipment integrations in this fork/branch.

Any discussion on the development can take place here in this issue.

PR is here: #252.

Endpoints:

• [x] OrderEndpoint for /orders/*:
  • [x] create
  • [x] get
  • [x] list
  • [x] cancel
• [x] OrderLineEndpoint for /orders/*/lines/*
  • [x] cancelFor($orderId)
• [x] OrderRefundEndpoint for /orders/*/refunds/*
  • [x] create
  • [x] list
• [x] ShipmentEndpoint for orders/*/shipments/*
  • [x] createFor
  • [x] getFor
  • [x] listFor

Resources:

• [x] Order
  • [x] isStatusX()
  • [x] lines()
  • [x] shipments()
  • [x] getShipment()
  • [x] createShipment()
  • [x] ship()
  • [x] isCancelable()
  • [x] cancelLine()
  • [x] refunds()
  • [x] refund(...)
• [x] OrderCollection
• [x] OrderLine
  • [x] isStatusX()
  • [x] isTypeX()
  • [x] cancel()
  • [x] isCancelable()
• [x] OrderLineCollection
• [x] Shipment
  • [x] lines()
  • [x] order()
• [x] ShipmentCollection

Types:

• [x] OrderStatus:
  • [x] created
  • [x] paid
  • [x] authorized
  • [x] canceled
  • [x] refunded
  • [x] shipping
  • [x] completed
  • [x] void (dropped)
  • [x] expired
• [x] OrderLineStatus:
  • [x] created
  • [x] authorized
  • [x] paid
  • [x] canceled
  • [x] refunded
  • [x] shipped
  • [x] void
• [x] OrderLineType:
  • [x] physical
  • [x] discount
  • [x] digital
  • [x] shipping_fee
  • [x] store_credit
  • [x] gift_card
  • [x] surcharge

Documentation:

• [x] Update examples
  • [x] Order
  • [x] 26-new-order
  • [x] 27-handle-order-status-change
  • [x] 28-cancel-order
  • [x] 29-list-orders
  • [x] 30-cancel-order-line
  • [x] Shipment
  • [x] 31-ship-order-completely
  • [x] 32-ship-order-partially
  • [x] 33-get-order-shipment
  • [x] 34-list-order-shipments
• [x] Update official docs to include php examples (when php client released)
  • [x] Order
  • [x] create
  • [x] get
  • [x] cancel
  • [x] list
  • [x] cancel line
  • [x] create refund
  • [x] list refunds
  • [x] Shipment
  • [x] create
  • [x] get
  • [x] list

[sandervanhooft]

The response for OrderEndpoint.get/create/list includes order lines (lines).

@ndijkstra Should this be an OrderLineCollection resource?

It would be a first for this client to include a nested resource(collection) in a response. It would probably require overriding the rest_create method.

[ndijkstra]

The order lines are in the order response. The order line endpoint is only for canceling an order line

[sandervanhooft]

Ok, so no OrderLineCollection is necessary on the Order resource?

I'll update the plan above to only include the cancel method on OrderLine.

[ndijkstra]

I think that is correct. @Smitsel Can you check if this is ok?

[Smitsel]

I think it is, take for example the IssuerCollection. These are an include on the methods api. But its rather useful to make them value objects.

This way we can iterate the OrderLineCollection and create cool helper functions like:$orderline->cancel().

So please do add them :)

[Smitsel]

I can also see value for people implementing this library and typehint them for example.

[sandervanhooft]

Thanks @Smitsel ! I overlooked the IssuerCollection on the methods api. I'll look into that one for inspiration.

[sandervanhooft]

By the way, why are all properties defined explicitly on the resource classes? The tests are passing without. Is this for autocompletion?

[Smitsel]

Yes it is.

[sandervanhooft]

Are there any other relations I should be aware of, like to a customer entity?

I.e. the word "customer" is used a lot in the order docs, but there seems to be no relationship defined.

[sandervanhooft]

I'm assuming there's going to be a Order cancel (delete) api endpoint, right?

I.e.

curl -X DELETE https://api.mollie.com/v2/orders/ord_kEn1PlbGa \
       -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM"

[ndijkstra]

Correct. Docs coming soon 😇

[sandervanhooft]

OrderEndpoint ready (see backlog). Had to use some response fixtures and assertion helpers to keep the test file length in check. Reduced it from 1600+ lines to less than 600. Pfew 😓

[willemstuursma]

Had to use some response fixtures and assertion helpers to keep the test file length in check.

Yes, it is very important to remember that tests are software too, and they can massively benefit from abstractions just as the units under test.

[holtkamp]

@sandervanhooft just noted the incorrect casing of Stdclass, it should be stdClass

https://github.com/sandervanhooft/mollie-api-php/blob/02bc1988b91ef66cc28d6ada659f4fe10aa8c211/tests/Mollie/API/Endpoints/OrderEndpointTest.php#L335

[sandervanhooft]

Thanks @holtkamp! Interestingly though, the tests pass... Nevertheless, I'll convert StdClass into stdClass as suggested.

[willemstuursma]

Class names are case-insensitive in PHP @sandervanhooft, only the Composer autoloaders (PSR-0, PSR-4) are.

[sandervanhooft]

Working on the OrderResource statuses and status methods now.

Can someone with Order API domain knowledge check whether this test (link) is ok? If so I can continue with implementation.

(The docs are not ready for this yet, only stating "See Order status changes for details on the orders’ statuses.", but no link is provided / page is not available yet.)

[sandervanhooft]

Class names are case-insensitive in PHP @sandervanhooft, only the Composer autoloaders (PSR-0, PSR-4) are.

Good to know 😄

[Smitsel]

Hi Sander, the status fields are as described in the docs. So your status methods are correct.

What we ment with the "order status changes details" is the transitions between statuses. We will add a guide for this and update accordingly.

Take a look at the cancel order endpoint docs and you will understand why we want such a guide ;)

[sandervanhooft]

Ok @Smitsel ! So I'm going to assume there's no additional logic to implement than (pseudo):

public function isSomeStatus()
{
    return $this->status === ORDER_STATUS::SOME_STATUS;
}

[sandervanhooft]

Take a look at the cancel order endpoint docs and you will understand why we want such a guide ;)

Indeed I do 😆

Seems to me that there should be a isCancelable method on the OrderLine resource as well.

[sandervanhooft]

Perhaps this would require an additional isCancelable field in the Order API response? I noticed it on some other resources.

[sandervanhooft]

Ok, I'm mixing things up here. I think we need this isCancelable method both on the Order and the OrderLine.

I can probably implement the logic client side, but I think it's better to include a isCancelable field on both the Order and the OrderLine responses, to keep the logic where it belongs - server side.

---

Update: I've implemented Order.isCancelable() and OrderLine.isCancelable() with client side logic for now.

[sandervanhooft]

Like with the payment response, it has a isCancelable field.

[sandervanhooft]

@Smitsel Minor doc issue: the id is missing on the Order line details. (Link)

[sandervanhooft]

As you can see here: nearly done with the implementation!

I'd like to manually test this against the private beta api when it's available.

[sandervanhooft]

@ndijkstra @Smitsel @willemstuursma

Next steps:

• review WIP PR (don't merge yet) (Mollie )
• write examples (Sander)
• try examples as soon as API is ready (Sander)
• all works? Merge PR & release (Mollie)
• (update Laravel client (Sander))

[sandervanhooft]

I just read up on the Order docs. It seems the void status is dropped, and the expired status is new.

Is that correct?

[willemstuursma]

@sandervanhooft yes we are indeed re-considering some of the statuses

[sandervanhooft]

@willemstuursma Thanks. So it's not final yet? In that case I'll leave it alone for now.

[sandervanhooft]

Added the examples.

[sandervanhooft]

@ndijkstra @Smitsel @willemstuursma

Similar to the isCancelable field, I think there should be an isRefundable field on the Order response. What do you think?

[willemstuursma]

We'll create a field for the refundable amount probably.

[sandervanhooft]

@willemstuursma Then an isRefundable() helper would be nice

[sandervanhooft]

Order.lines can be accessed as OrderLine resources via the Order.lines() method.

Can we do the same with Refund.lines / Refund.lines()? Or is this is a slightly different resource than the OrderLine?

Update: Just talked with @ndijkstra. He's on this.

[sandervanhooft]

@Smitsel When you review this, be sure to keep an eye out for OAuth compatibility. I've not explicitly tested this.

[willemstuursma]

@sandervanhooft we want to merge this into a branch and create a pre-release, is that OK for you?

[sandervanhooft]

@willemstuursma Great idea!

I've just made some comments at the @Smitsel 's PR review #252 . And incorporated some of his remarks, minor new PR coming your way.

[sandervanhooft]

And received some feedback from @Smitsel already (thanks!). Will implement this, expect the PR later today.

[Smitsel]

I think we've got everything. If we still miss some stuff we can open a new issue :)