[#302] Insufficient Documentation for Admin API "book"

Bug Reports
,
1

Migrated from Redmine #302 | Author: Stephan Bönnemann
Status: New | Priority: Immediate, there is BUG! | Created: 2018-12-11

I’m trying to create a booking via the Admin API as per: API documentation | SimplyBook.me Online Scheduling

Unfortunately the documentation is awry, unclear, and ambiguous, especially when it comes to the use of “additionalFields”.
I have tried every way imaginable to name or format additionalFields, I even inspected how you do it for the user API in your example code (Simplybook.me API example), or how the simplybook booking itself does it.

Nothing is a working at all and the error message remains unchanged no matter what I do: “Error: XXX - ‘’ was not found in the haystack,Value is required and can’t be empty”

Please provide an example RPC payload, or even better update your documentation with sufficient examples/documentation, and not just a few notes where the rest is up to the user to guess.

Thanks

2

Redmine Admin wrote:

you need to call getAdditionalFields and then use field id for API documentation | SimplyBook.me Online Scheduling

"additional_fields": [{
     "value": "on",
     "field_name": "201a89517de509f6b3a60858918faac3",
     "field_title": "Include washing",
     "field_position": "4",
     "field_type": "checkbox",
     "field_id": "4"
   }],
3

Redmine Admin wrote:

on PHP additiaonal data should looks as following

array(
'e28064f09a75d91c503f81a0cda3f71e'=> 'value for field 1',
'fa23c732e6a0b3caf9aa29b7909b1a44'=> 2
)
4

Stephan Bönnemann wrote:

None of this is working and I tried it before.

As I said, please provide we with a working and tested JSON RPC payload. So I can see what I need to send.

{
  "method": "book",
  "jsonrpc": "2.0",
  "params": {
    "eventId": "4",
    "unitId": "7",
    "clientId": "61",
    "startDate": "2018-12-12",
    "startTime": "13:00:00",
    "endDate": "2018-12-12",
    "endTime": "13:30:00",
    "additionalFields": {
      "d6866d5e68e267608e189eaf855c59c0": "TEST NAME"
    }
  },
  "id": "78858914-e3d9-4993-acf5-3582d85407de"
}
5

Dmytro Bondarev wrote:

Please use non named parameters:
@{
“method”: “book”,
“jsonrpc”: “2.0”,
“params”: [“4”, “7”, “61”, “2018-12-12”, “13:00:00”, “2018-12-12”, “13:30:00”, {“d6866d5e68e267608e189eaf855c59c0”: “TEST NAME”}
],
“id”: “78858914-e3d9-4993-acf5-3582d85407de”
}@

6

Stephan Bönnemann wrote:

Ordered arguments are giving me almost the same error unfortunately: “Error: name - Value is required and can’t be empty” (Without the haystack thing)

7

Dmytro Bondarev wrote:

Which endpoint url do you use?
Please provide raw HTTP request with headers.

8

Stephan Bönnemann wrote:

I’m successfully using the /admin API for other methods, such as getAdditionalFields, addClient, getFirstWorkingDay, etc. all of which are working just fine.
This makes me highly doubtful that this error has anything to do with endpoints or http headers, but – well – here they are.

POST https://user-api.simplybook.me/admin

content-type: application/json
X-Company-Login: myCompany
X-User-Token: myToken

  • above payload.

I’m really wondering what the issue is here? Why is this not documented correctly, why can’t you yourself tell me how it’s supposed to work, why is it that I randomly can’t use named arguments without any hint in the docs, etc.
Even if the format you suggested here would be working, how is anyone supposed to guess that format? I’m really wondering if anyone is using this method successfully at all.

It shouldn’t be too hard to say in which format the backend expects these fields … but apparently it is.

This is extremely frustrating and it’s killing a bunch of time, that simplybook was supposed to safe, not waste.

9

Stephan Bönnemann wrote:

I just checked: If I make all additional fields optional, then booking an appointment works. That means it’s definitely not an issue with endpoints or headers or anything.

It’s simply a question of what the format is you expect, and it would be extremely helpful if you could first find out and then tell me.

Sending the additionalFields in your proposed format doesn’t make them show up on SimplyBook, so I suppose it’s not correct – unfortunately.

10

Dmytro Bondarev wrote:

Hello!

Why is this not documented correctly, why can’t you yourself tell me how it’s supposed to work, why is it that I randomly can’t use named arguments without any hint in the docs, etc.

The documentation is correct please check

As described in documentation book($eventId, $unitId, $clientId, $startDate, $startTime, $endDate, $endTime, $clientTimeOffset, $additional, $count, $batchId, $recurringData)
And you pass $eventId, $unitId, $clientId, $startDate, $startTime, $endDate, $endTime, $additional, you are missing one argument - clientTimeOffset (pass zero if you are in the same timezone).

I sent you example how you should pass arguments.
Please check documentation again there is format description and API explorer where you can check API calls.

11

Stephan Bönnemann wrote:

Dmitry Bondarev wrote:

Hello!

Why is this not documented correctly, why can’t you yourself tell me how it’s supposed to work, why is it that I randomly can’t use named arguments without any hint in the docs, etc.

The documentation is correct please check
Company administration service methods - Company administration service methods - SimplyBook.me

Cool, that seems like documentation that is better. Only question is why that’s so hard to find then. In my initial post I told you I’m using: API documentation | SimplyBook.me Online Scheduling and that is definitely incorrect in many ways.

As described in documentation book($eventId, $unitId, $clientId, $startDate, $startTime, $endDate, $endTime, $clientTimeOffset, $additional, $count, $batchId, $recurringData)
And you pass $eventId, $unitId, $clientId, $startDate, $startTime, $endDate, $endTime, $additional, you are missing one argument - clientTimeOffset (pass zero if you are in the same timezone).

I sent you example how you should pass arguments.

Your example above is also missing the clientTimeOffset ¯_(ツ)_/¯

Please check documentation again there is format description and API explorer where you can check API calls.

Following the documentation link you sent me it’s working. It’s even working with named arguments, but ONLY if I also pass clientTimeOffset, which is not reflected in the error message, nor in the docs.

The field is called additional, not additionalFields. I attached screenshots to illustrate that this wrong in both documentations.

On top of that the format of the additional object itself is not documented anywhere, and it’s entirely up for the user to guess it.

If you want to remain on your standpoint that the documentation is sufficient here, and If you don’t want to admit the slightest shortcoming on your side, that’s not at all understandable.
Even if you weren’t objectively wrong about that, I’m a customer, and a very experienced API integrator. If you don’t want to listen to someone telling you about your problems here, then you’ll soon enough find out where that leads you as a business.

This incident and the overall API quality/documentation make use extremely doubtful whether simplybook was the right choice for our business.

12

Stephan Bönnemann wrote:

The upload function of this bug tracker doesn’t work …

But you should definitely see them, so here you go:

!https://user-images.githubusercontent.com/908178/49858504-62ba6e00-fdf5-11e8-9af7-559711e23f8b.png!

!https://user-images.githubusercontent.com/908178/49858653-d3fa2100-fdf5-11e8-889b-b412a7b81c79.png!

13

Dmytro Bondarev wrote:

Your example above is also missing the clientTimeOffset ¯_(ツ)_/¯
i sent you example how to pass arguments.

Following the documentation link you sent me it’s working. It’s even working with named arguments, but ONLY if I also pass clientTimeOffset, which is not reflected in the error message, nor in the docs.

It works because you pass argumants in the same order and object was converted to array, that is why it works also with additionalFields or additional (it does not matter how you call it, because it will be converted to array). THat is why i suggested to use array arguments instead of object.

And of course our documentation far away from excellent, sorry for that, but these parts explained in our documentation and examples.