ingresso-group / slate Goto Github PK

This is a property on the Event object which indicates that the API will override any quantity specified in the Trolley calls and set the quantity of the add-on event to match the number of tickets selected for all parents.

Currently only the purchase_result.is_success and purchase_result.is_partial fields of a trolley are documented in the purchase.v1 docs
When a purchase fails it looks something like this:

            "purchase_result": {
                "success": false,
                "purchase_error": "unspecified",
                "failed_cv2": false,
                "failed_avs": false,
                "failed_3d_secure": false,
            }

Document the auth failure flags and the possible codes that can appear in purchase_error

Also, document the bundle purchase_result, which is slightly different

Following on from #25, Tech Support has added some additional comments to improve the new document.

https://accessoplc.sharepoint.com/:w:/r/sites/ingresso/_layouts/15/Doc.aspx?sourcedoc=%7B6D05F6F4-CD6A-475E-B36D-A8F54D99F7BF%7D&file=Quick%20start%20guide%20for%20Attractions%20Distributors%20.docx&action=default&mobileredirect=true

Acceptance criteria:

• Update document from Tech Supports input

Remove token_id from documentation and Postman examples, as people seem to be caopying and calling reserve with the example token_id we have currently in the examples.

The FIXME at https://github.com/ingresso-group/slate/blame/master/source/includes/_performances.md#L750

I think the lack of line break after must be causing the following code example to not generate

The performances for the curl examples don't have cost_range when calling the API today either.

For example event JYXY

We ought to discount_disallowed_seat_nos that can appear in the discount. The array of seat numbers a discount is not allowed to appear upon.

Update support email address from api to techsupport

The supported_barcode_types property of a purchase.v1 response is not documented as at writing.
It sits at the order level, and is an array.

Possibly values include

Though, in practise, it looks like we are currently only spitting out code128 and qr_code.
Need to check whether to document all of them or only a select set.

Currently the test.v1 endpoint is not documented, but it is one of the only ways a client can test their credentials are working before an availability or reserve call. The documentation expects there should be an anchor at this URI:

http://docs.ingresso.co.uk/#test

Documenting the endpoint, parameters and so on.

As attractions distributor,
I want a clear quick start guide to F13 documentation,
so that I can understand what I need to implement in order to achieve what I want.

Attractions distributors have complained (to Tech support), and commercial has echoed this, that our F13 API documentation (https://docs.ingresso.co.uk/) is hard to understand for distributors, especially those who sell predominantly attractions (not theatre). Our current documentation is more of a reference, it lacks guiding.

Please speak with Tech Support to get their input and more info on the complaints they received (e.g. distributor Rush49). Assess other good examples of API documentation (a few mentioned on Slack: https://ingressos.slack.com/archives/G5QQM9SCX/p1600358781013900):

• Stripe, e.g., https://stripe.com/docs/file-upload
  • Guide documentation such as the above exists on its own and also linked from the relevant API reference sections, e.g., https://stripe.com/docs/api/files
  • Task-based - how do I do something
  • Not constrained to a single endpoint, e.g., the above covers /files, /file_links, and /disputes
• https://api.slack.com/apis
  • Though their API is really big and there are lots of things you might want to do but, in a similar way to stripe, they have the reference, and then they also have those usage guides
  • the reference is structured not as one big long page unlike stripe’s and ours, because of that there’s lots to do fact
• https://developer.okta.com/docs/
  • I’ve just had a peek and okta have nice looking docs, with respect to their guides section e.g. click though to one of the Guides from the bottom
• https://vuejs.org/v2/guide/
  • The docs for Vue were always very nice. Lots of inline code examples, very clear explanations, good segmentation etc. I see now that you can even open a lot of the code examples in Scrimba, where you then get small a video explanation and can play directly with the code at any point.
• https://docs.github.com/en/rest/reference
  • I have found Github’s most recent docs v helpful
• http://zguide.zeromq.org/page:preface
  • I also always had a soft spot for the ZMQ guide (perhaps not useful as an example of good REST API docs, but a great example of making documentation interesting and fun, and teaching you something beyond the scope of the library 👍 )

Acceptance criteria:

• Tech Support's input is gathered;
• good API documentation examples assessed;
• a 'quick start guide' or other useful form of documentation produced

Other info:

Anecdotal evidence:

Josh,

I have the documentation and can spend forever reading it, but I need to start with some fundamentals that are not very clear in the docs.

A few questions merely as a starting point:

What are our test API credentials? (username and password)

How would we find all the merchant partners authorized for us to sell? I see an events API call but no "suppliers" or something else that indicates what companies have authorized us to sell their tickets via Ingresso.

It all seems very confusing, to be honest. Our entire system is based on merchants, partner companies whose events and activities we sell. Those merchants have deals, which perhaps equates to an 'event' in your system, but i am not sure.

I feel I need to have a videoconference with someone at Ingresso who knows some tech details who can describe to me in simple English the process by which we sign up new merchant partners, then populate our database with the deals they are allowing us to sell, then to be able to get the date/time combinations for their events, at least for those deals that are performance based.

Your API tends to return hundreds of fields, which is one reason this is so confusing. The documentation is of no value to me at all yet as it has to handle all the permutations, but I want to just get the simplest idea of implementation to start with.

Please let me know when and how we can set this up, I am not sure I will be able to make any progress until we get to that starting point.

Ben Cahan
Rush49.com