Hi! I wanted to post this bug report in the community portal, but I seems like I need additional permissions to do so, so I'll post my report there, since it's partially about spec too.

While doing the integration with xero I encountered an easily reproducible behavior that doesn't look correct, especially given that it behaves different for different content type.

Here is an xml payload:

<PurchaseOrders>
  <PurchaseOrder>
    <Contact>
      <ContactID>BROKEN</ContactID>
    </Contact>
    <Date>2020-04-28T14:00:00</Date>
    <LineAmountTypes>Exclusive</LineAmountTypes>
    <LineItems>
      <LineItem>
        <Description>Coffee Cup</Description>
        <Quantity>4.3400</Quantity>
        <UnitAmount>395.00</UnitAmount>
        <AccountCode>300</AccountCode>
      </LineItem>
      <DeliveryDate>2020-04-30</DeliveryDate>
      <Reference>1234</Reference>
      <DeliveryAddress>Hamburg</DeliveryAddress>
      <AttentionTo>John Doe</AttentionTo>
      <Telephone>+88885</Telephone>
    </LineItems>
  </PurchaseOrder>
</PurchaseOrders>

Since contact id is invalid I get a response with status 400 and body:

<ApiException xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <ErrorNumber>14</ErrorNumber>
    <Type>PostDataInvalidException</Type>
    <Message>Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).</Message>
</ApiException>

If I switch to json and send a body like this:

{
	"PurchaseOrders":
	[
		{
			"Contact":
			{
				"ContactID":"BROKEN"
			},
			
			"LineItems":[
				{"Description":"Tomatoes","Quantity":1,"ItemCode":"DevD"},
				{"Description":"Potatoes","Quantity":1,"ItemCode":"GB1-White"},
				{"Description":"Water","Quantity":1,"ItemCode":"PMD"}
			],
			"DeliveryDate":"2020-04-30",
			"Reference":"1234",
			"DeliveryAddress":"Hamburg",
			"AttentionTo":"John Doe",
			"Telephone":"+888885"
		}
	]
}

api responds with 500 status and body is never sent, hence a client that was generated base on openapi spec hangs forever. Given a correct account number the same payload works fine.

Unfotunately, json is the only format mentioned in the spec, so it's not possible to work it around by generating a client using a different content type.

One more note. It appears that purchase orders endpoint supports not only arrays but individual objects as well. So it's possible to send a payload like this:

{
	"Contact":
	{
		"ContactID":"BROKEN",
		"PaymentTerms":{"Bills":{},"Sales":{}},
		"BatchPayments":{},
		"Balances":{
			"AccountsReceivable":	{},"AccountsPayable":{}
		}
	},
	
	"LineItems":[
		{"Description":"Tomatoes","Quantity":1,"ItemCode":"DevD"},
		{"Description":"Potatoes","Quantity":1,"ItemCode":"GB1-White"},
		{"Description":"Water","Quantity":1,"ItemCode":"PMD"}
	],
	"DeliveryDate":"2020-04-30",
	"Reference":"1234",
	"DeliveryAddress":"Hamburg",
	"AttentionTo":"John Doe",
	"Telephone":"+888885"
}

In case of correct payload purchase orders are created, otherwise a correct error is returned:

{
  "ErrorNumber": 14,
  "Type": "PostDataInvalidException",
  "Message": "JSON for post data was invalid,Error converting value \"BROKEN\" to type 'System.Guid'. Path 'Contact.ContactID', line 4, position 23."
}

Unfortunately this payload is not described in openapi and hence generated clients do not provide a way to submit this payload.

Expected behvaior: I would expect to get a 200 status code with an array of purchase orders. For the ones with incorrect account number I would expect to see an error as describe in the documentation:

If you are entering many purchase orders in a single API call then we recommend you utilise the summarizeErrors parameter which provides a response format that shows validation errors for each purchase order. Note that each Purchase Order is returned with a status element which will either contain the value OK or ERROR. If a purchase order has an error then one or more validation errors will be returned.

The XML interface provides creating multiple items at a time - like Invoice, CreditNote or Payment. I cant see an equivalent with the open-api versions. Is this something we can expect ?

Are the same API limits in place for openAPI as there are for XML ?

Thanks

I have been looking at the deletePayment operation ID, and some things about it are a little unclear to me. It seems to not quite make up its mind whether it is an update or a delete, and that results in some inconsistencies in code generated from the API description. I think it needs to go one way or the other.

The deletePayment operation is a POST that takes a payment ID as a path parameter. Putting aside the fact that it's not a DELETE method, that should be all that is needed to instruct a deletion.

However, the operation then requires a #/components/schemas/Payments schema as a payload. That is the same schema needed to create a payment in the first place, so it seems that this delete is actually an update. Except that only the status can be changed (from what I can see when experimenting), and the status can only be changed to DELETED.

This is given as an example in the API description:

{
    "Payments": [
        {
            "Status": "DELETED"
        }
    ]
}

I'm not even sure if this example is correct, since it shows an array of payments, none of which are individually identified. This below works in practice though, not the example:

{
   "Status": "DELETED"
}

So:

• If this is a deletePayment operation, that only deletes payments, then the payload should perhaps be a fixed (constant) structure and not defined as a whole Payment schema. That would help in automated code generation immensely. However, so far as OpenAPI is concerned, you have "taken up" this method and endpoint for this single operation, and in theory - for a valid OpenAPI description - could not use it again if you wanted another operation there - i.e. updating, undeleting.
• If this is actually an update payment operation, that happens to only allow the status to be updated for now, then maybe it should be renamed to updatePayment. That would help to understand how this endpoint works.

I've not tried to see if the operation can be used to undelete a deleted payment, and if it can, it would open up further questions.

I'm happy to provide a PR, but need to know what the original intention was here.

Developer validated this is supported by API.
XeroAPI/xero-node#401 (comment)

Check if Overpayment as PDF is also valid

Hi

Overpayments seem to be missing the reference field.
(Similar to a previous issue for Prepayments, #139).

[edit]
Looks like there's still an issue with Prepayment references. The reference field appears to contain the prepayment number, while there's no actual field for the prepayment number and the real reference is missing.

Here is just one example, but it is in many places.

Contacts can be fetched in bulk using the IDs query parameter and supplying a comma-delimited list of contact IDs. The OpenAPI description (in particular the accounting API v2.0) does not define this.

The query parameter for the contact IDs is defined:

        {
          "in" : "query",
          "name" : "IDs",
          "description" : "Filter by a comma separated list of ContactIDs. Allows you to retrieve a specific set of contacts in a single call.",
          "schema" : {
            "type" : "string"
          }
        }

No validation middleware or code generator is going to be able to handle this parameter as anything other than a plain string. Parsing the IDs from into and comma-delimited lists is then left up to the application domain, when this is plainly something that should be handled by the API client.

Using this as the parameter description changes all that:

        {
          "in" : "query",
          "name" : "IDs",
          "description" : "Filter by a comma separated list of ContactIDs. Allows you to retrieve a specific set of contacts in a single call.",
          "schema" : {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1
          },
          "explode": false,
          "style": "form"
        }

Now generated code accepts an array of contact IDs. The generated code knows that this array is to be serialised into a comma-delimited list, and does so automatically. Any request validation layer knows this too and can check the parameter is appropriatly formatted. The schema can go further by defining the item format as a uuid, then even more validation can be done.

That is all for free, out of the box. Code generators know how to use it. Message validators know how to use it. The application does not need to mess around with serialising lists of IDs into strings that ONLY the API transport needs to know anything about.

Is this something - i.e. the extra steps in the OpenAPI description to define the reality of these parameters - you would be prepared to support?

Hi,

I've gone through the official developer documentation (https://developer.xero.com/documentation/api/api-overview) for several of the Accounting API resources. There appears to be mention of the POST method for several endpoints, however the API specification here shows that the PUT method is the only one offered.

An example of this would be the /Contacts#bulk endpoint. Should this endpoint, and others like it, have a 'POST' method implemented?

Thanks.

Creating a single bank feed connection returns the pending result as status code 202 Accepted not the 201 Created as defined in the OpenAPI description.

https://github.com/XeroAPI/Xero-OpenAPI/blob/master/xero_bankfeeds.yaml#L113

I ave not tried this creating multiple bank feed connections in one request, so there may be other response status codes at play which I am not seeing in other situations, so I can't say a 201 is never returned. Issue #378 hints that it may be a 200 with mixed results, but I can only guess.

Expected Behavior

The pending bank feed connection response should be delivered as a HTTP 201 according to the OpenAPI description, indicating it has been accepted but not yet processed. This is what the generated code expects. If the request contains a number of requests, then the response could contain a number of different resues - pending, created and errors - and I have no idea what the HTTP status code would be in that case.

Current Behavior

The correct PENDING response is returned, with the arguably correct 202 Accepted response.

Possible Solution

• The OpenAPI description is fixed to show the payload for a 202 response.
• Maybe remove the 201 response from the OpenAPI description if it is never returned.
• I have a hunch there are other response status codes in play for responses containing a mix of results. I could discover them by experiment, but that doesn't tell me what the responses were planned to be.

Steps to Reproduce (for bugs)

1. Make POST request to createFeedConnections operation for a single bank feed connection, for a connection that should be valid.
2. Observe the result: 202 with the FeedConnections schema payload, but without the pagination property.

Context

Your Environment

• Version used:
• Browser Name and version:
• Operating System and version (desktop or mobile):
• Link to your project:

The readme refers to using SwaggerHub to browse the spec, so I was wondering if there were any plans to have an official copy of the spec hosted there? There are at least 4 unofficial versions uploaded by other developers, and I think it could end up leading to some confusion

Hi @jenksguo - wondering if this field should be typed as is-money. Currently rolling into ruby for the money types to have proper BigDecimal format, but this seems like it should just be: type: number format: double

        Quantity:
          description: LineItem Quantity
          type: number
          format: double
          x-is-money: true

The path parameter for the getStatement operation has a different name in the two places it is declared. In the clients we generate from this, the statementId parameter does not work as a result.

https://github.com/XeroAPI/Xero-OpenAPI/blob/master/xero_bankfeeds.yaml#L512

Expected Behavior

Code generates as expected - the defined path parameter gets inserted into the path template as expected.

Current Behavior

This fragment of generated code illustrates the problem:

        $resourcePath = '/Statements/{statementID}'; // <--- placeholder is not proper camelCase
...
            $resourcePath = str_replace(
                '{' . 'statementId' . '}', // <--- matching on camelCase
                ObjectSerializer::toPathValue($statementId),
                $resourcePath
            );

In this generated code, using a case-insensitive match should work around this issue, but there are a hundred other languages and tools that need this to be consistent.

Possible Solution

Change the statementID path template placeholder to statementId here:

https://github.com/XeroAPI/Xero-OpenAPI/blob/master/xero_bankfeeds.yaml#L512

Steps to Reproduce (for bugs)

Context

Your Environment

• Version used:
• Browser Name and version:
• Operating System and version (desktop or mobile):
• Link to your project:

Hi,

I am hitting oauth2 limitation as screenshot below

However, I checked the my Connected App section as below:

I don't see other connected app other than the Square one.

Is it a bug?

See: https://developer.xero.com/documentation/api/organisation

From the documentation:

If possible, we recommend you limit filtering to the following optimised elements Status, InvoiceID, InvoiceNumber, Date, Reference, Contact.ContactID, Contact.Name, Contact.ContactNumber and Type. The most efficient queries are simple "==" on these fields.

The current spec doesn't allow the ContactNumber to be set when initialising the Contact.

The OpenAPI Specification specifies the description language that describes a REST API. So this repository should probably be:

An OpenAPI description of the Xero API

The latest OpenAPI spec (2.1.2) added the summarizeErrors flag when batch-adding Payments, and this has since been included in the NetStandard API (https://github.com/XeroAPI/Xero-NetStandard/releases/tag/v2.2.0).

However, the generated Payment model class lacks the StatusAttributeString property that is needed when using summarizeErrors=false.

The OpenAPI description lists the response to the /FeedConnections endpoint being a 201 with pager metadata. I am receiving a 200 rather than a 201, resulting in my client throwing an exception with the unexpected status code. The body payload is correct, so I have a workaround extracting that from the response outside of the client.

https://github.com/XeroAPI/Xero-OpenAPI/blob/master/xero_bankfeeds.yaml#L113

The human-readable documentation lists 200 as the response, so it seems the OpenAPI description is the odd one out.

https://developer.xero.com/documentation/bank-feeds-api/feed-connections#Get%20Feed%20Connections

Expected Behavior

Current Behavior

Get a 200 with a correct payload {"pagination":{"page":1,"pageCount":0,"pageSize":20,"itemCount":0},"items":[]}

The 200 may only be related to an empty set of items; I have not tried it with a non-empty set yet.

Possible Solution

Fix the response code in the OpenAPI description. I have not put a PR together for this yet, as I have not tested other cases, so am not certain that both 200 and 201 are valid responses, which would require a different fix to the OpenAPI description.

Steps to Reproduce (for bugs)

1. Call /FeedConnections with a bankfeeds scope.
2. Get paged payload with a 201 response (according to OpenAPI description).
3. Get a 200 instead (consistent with other documentation).

Context

I'm using my own generated client (with camelCase objects rather than snakeCase).

Your Environment

• Version used:
• Browser Name and version:
• Operating System and version (desktop or mobile):
• Link to your project:

Based on this issue.
XeroAPI/Xero-NetStandard#154

Need to validate the API functionality.

In the old wrapper (line 24) there are reports available for Bank Statements. These don't appear to be in the OpenAPI definition and are also missing from the official docs.

Is this an oversight or are they obsolete / being phased out?

We have 13 update endpoints which include passing a unique ID. They all currently require passing an object that contains an array populated by a single object. This functions properly across all 6 SDK languages. So, this isn't a bug per-se. The API accepts both a single object and an array containing a single object.

Assuming all 13 of the routes accept a single object, we could modify the OpenAPI spec on these 13 "update" methods to accept a single object instead of an object with array containing a single object.

This would be a breaking change for any developers currently using these methods in our 6 SDKs (major versioning required), updates to unit tests and 6 companion apps that demonstrate how to use them. Also, updates to meta data used to generate our SDK documentation with runnable code examples.

If I recall, the reasoning behind using the array vs, the single object is that Xero's API returns an array of objects even when performing a GET with a unique ID.

For developers who've just retrieved an Invoice, they could modify that object already inside the array and pass it to an update method without having to create a new Invoice object and populate it. Perhaps this is not common and should be discounted as a reason.

We are interested in hearing from developers about how important this request is and if there is anything specific about your use case or programming language that makes this more acute.

Thanks for your input

Hi,

I used open API generator to generate Go code and invoice is not parsed properly. There seems a bug for UpdatedDateUTC

Generated Part of Go Code
// Invoice struct for Invoice
type Invoice struct {
        ....
	// Last modified date UTC format
	UpdatedDateUTC time.Time `json:"UpdatedDateUTC,omitempty"`
	....
}

https://developer.xero.com/documentation/api/invoices

UpdatedDateUTC | Last modified date UTC format

but in the demo, it seem invalid format in json

"UpdatedDateUTC": "\/Date(1518685950940+0000)\/",

the error message I got

err: parsing time ""\/Date(1229650679057+0000)\/"" as ""2006-01-02T15:04:05Z07:00"": cannot parse "\/Date(1229650679057+0000)\/"" as "2006"

There are a number of errors listed here:

https://github.com/XeroAPI/Xero-OpenAPI/blob/master/bankfeeds-yaml/Xero_bankfeeds_1.0.0_swagger.yaml#L819

We just got an additional error message 'feed-already-co...' (sorry, only got the first bit of the message before an exception on the OpenAPI client was throw). I am guessing this is saying "[another] feed already connected to this bank account",

The scenario was: creating a bank feed for a bank sort-code/account number, matching an account that already existed, and that already had a bank account.

(That should never normally happen, but the online bank system happened to give us the same account details by random from both sandbox and production, so we accept it is reasonable that this fails. However, it's just that the error code is not listed in the OpenAPI spec that I am mainly raising. We can work around this in the meantime by checking the bank account exists first and checking if it has a feed.)

I'll come back with more details, but just as a placeholder for now, here is an overview.

Creating a bank feed connection, I got a rejection with a 400 error. The OpenAPI description shows no response payload for a 400. This is the payload I got:

{
   "items":[
      {
         "accountToken":"c12345-cld6et3q6...sw8w4",
         "status":"REJECTED",
         "error":{
            "type":"feed-already-connected-in-current-organisation",
            "title":"Feed Connection Failed",
            "status":409,
            "detail":"The AccountToken, AccountNumber or AccountId is already connected to another Xero Bank Account in the selected Xero Organisation."
         }
      }
   ]
}

Note status in the payload is 409, but the HTTP response was 400.

This message format is not consistent with anything I can see in the OpenAPI description.

The response is also inconsistent with the human-readable documentation. It is the items array wrapper which appears to be new in the API implementation, but not documented. The 400 being returned instead of a 409 makes sense if there is a list of errors, since each error could have a different status, and so they all need collecting under a single HTTP response status code.

https://developer.xero.com/documentation/bank-feeds-api/feed-connections-errors

Expected Behavior

Current Behavior

Possible Solution

Fix the OpenAPI description :-)

Steps to Reproduce (for bugs)

Context

Your Environment

• Version used:
• Browser Name and version:
• Operating System and version (desktop or mobile):
• Link to your project:

accounting-yaml/xero_accounting.yaml:2638 states that the IDs must be UUIDs. This is incorrect as not only Contact IDs but Contact Numbers (external identifiers; custom strings) are accepted by the API as well.

type: number
format: decimal

may be required

This will allow generators such as csharp to generate the fields as a 'decimal' which is more precise than a 'double'. If currencies are 'doubles' bugs may occur with lack of precision.

Related issue in Xero-NetStandard repo.
XeroAPI/Xero-NetStandard#124

XeroAPI/xero-python#34

Possible Solution

We should remove the maxlength attribute from the reference property.

The Accounting API Type property for the BatchPayment model is defined as a string with no limits. The description of this property identifies two values it can be set to:

PAYBATCH for bill payments or RECBATCH for sales invoice payments

It is useful to defined properties like this with enum values, as this helps when generating code from the spec - all the constants (handy when filtering) and validation comes for free.

See:

https://github.com/XeroAPI/Xero-OpenAPI/blob/master/accounting-yaml/Xero_accounting_2.0.0_swagger.yaml#L18640

The current spec for the BankSummary report doesn't match what is documented here:
https://developer.xero.com/documentation/api/reports#BankSummary

https://developer.xero.com/documentation/api/contacts#summary-only

When set to true, this returns lightweight fields, excluding computation-heavy fields from the response, making the API calls quick and efficient.

XeroAPI/xero-node#523

Hi there,

I am wondering is there a plan to include reference # in the Prepayment response?
Or is there an alternative to get this info?

Cheers

Hi @jenksguo ,

Where can I write new this function correctly?

Thanks.

Missing LineItemID

Could you please consider adding the LineItemID to the CreditNotes in the future.

On the demo sample data you may run the following:

https://api.xero.com/api.xro/2.0/creditnotes/694c1f99-8085-416c-9ace-40f911303229

As you can see on BankTransactions this has been added already

https://api.xero.com/api.xro/2.0/BankTransactions/b9d7c42c-506a-4e56-a8a1-a41330580834

I'm not quite sure that this is the right place for this bug report, but I can't find a better place, so here we go! I'm using the PHP client library, but the same results will happen with any client.

--

I'm tracking when payees deposit checks (and they are reconciled) by doing $xero->getPayments() each day and tracking which ones the IsReconciled flag flips on during that day. Each Payment is related to one Invoice, and this works great.

However I've hit a problem with inconsistent behaviour where several invoices are paid with a single transaction. Here's a very abridged output from my getPayments() call:

[0] => XeroAPI\XeroPHP\Models\Accounting\Payment Object	(
	[invoice] => XeroAPI\XeroPHP\Models\Accounting\Invoice Object (
		[type] => ACCPAY
		[contact] => ...
		[line_items] => ...
		[date] => ...
		[invoice_number] => 1517
		[status] => PAID
		[total] => 435
		[invoice_id] => 987ddb2a-2271-46f8-a420-0b4cf53b188f
		[payments] => Array (
			[0] => XeroAPI\XeroPHP\Models\Accounting\Payment Object(
				[invoice] => 
				[credit_note] => 
				[prepayment] => 
				[overpayment] => 
				[invoice_number] => 
				[credit_note_number] => 
				[account] => 
				[code] => 
				[date] => DateTime Object(
					[date] => 2020-04-16 19:00:00.000000
					[timezone_type] => 3
					[timezone] => America/Chicago
				)
				[currency_rate] => 1
				[amount] => 435
				[reference] => 29172
				[is_reconciled] => 
				[status] => 
				[payment_type] => 
				[updated_date_utc] => 
				[payment_id] => 75421a0a-b356-45e7-ab0f-129e261c1132
				[bank_account_number] => 
				[particulars] => 
				[details] => 
				[has_account] => 
				[has_validation_errors] => 
				[validation_errors] => 
			)
		[amount_due] => 0
		[amount_paid] => 435
		[fully_paid_on_date] => DateTime Object (
			[date] => 2020-04-16 19:00:00.000000
			[timezone_type] => 3
			[timezone] => America/Chicago
		)
		[amount_credited] => 
		[updated_date_utc] => DateTime Object (
			[date] => 2020-04-17 14:05:41.000000
			[timezone_type] => 3
			[timezone] => America/Chicago
		)
	)
	[date] => DateTime Object (
		[date] => 2020-04-16 19:00:00.000000
		[timezone_type] => 3
		[timezone] => America/Chicago
	)
	[currency_rate] => 1
	[amount] => 435
	[reference] => 29172
	[is_reconciled] => 
	[status] => AUTHORISED
	[payment_type] => ACCPAYPAYMENT
	[updated_date_utc] => DateTime Object (
		[date] => 2020-04-17 14:05:41.000000
		[timezone_type] => 3
		[timezone] => America/Chicago
	)
	[payment_id] => 99193d93-bfea-4ab5-bb44-e05c4c43f296
	[has_account] => 1
)

As you can see, this has returned a Payment (99193d93-bfea-4ab5-bb44-e05c4c43f296) which clears an Invoice (987ddb2a-2271-46f8-a420-0b4cf53b188f).

Confusingly however, this Invoice lists a single Payment, but the Payment, but with a different GUID (75421a0a-b356-45e7-ab0f-129e261c1132).

Looking in the Xero web interface, that GUID (75421a0a-b356-45e7-ab0f-129e261c1132) is referred to as a bankTransactionID, and the title on the page is "Batch Payment".

$xero->getPayment('75421a0a-b356-45e7-ab0f-129e261c1132'); returns nothing
$xero->getBankTransaction('75421a0a-b356-45e7-ab0f-129e261c1132'); returns nothing
$xero->getBatchPayments($date, '', 'UpdatedDateUTC'); returns nothing

It appears at that whatever object is represented by GUID 75421a0a-b356-45e7-ab0f-129e261c1132 is invisible from the API. In practice this appears to be some sort of psuedo-payment which groups together several other Payments (but isn't a BatchPayment).

The actual problem that this is causing is around the IsReconciled flag. In this case, the money has changed hands and been reconciled. Going through the web interface to see the "payment" 75421a0a-b356-45e7-ab0f-129e261c1132 shows it as reconciled. However this information doesn't seem to propagate out to the individual Payment which is accessible through the API - you can see is_reconciled above is showing blank.

My expected behaviour is that when an Invoice payment is reconciled, that all relevant Payment objects show as reconciled.

Any updates on if Workflow Max v3 api would make it into this specification?

Expected Behavior

Contact schema Address Type should only have POBOX & STREET enum options.
Organisation Address Type can have POBOX, STREET & DELIVERY

Current Behavior

Both Contact and Organisation share the same Address Type Enum options.

Possible Solution

Separating the two address type enums in OAS.

Steps to Reproduce (for bugs)

1. Create an contact with address type of DELIVERY
2. the address will be "swallowed"

The yaml document is missing the schema-type for the Pagination-schema:

Pagination:
  properties:
    page:
      type: integer
      example: 1
      description: Page number which specifies the set of records to retrieve. Example - https://api.xero.com/bankfeeds.xro/1.0/Statements?page=2 to get the second set of the records. When page value is not a number or a negative number, by default, the first set of records is returned.
    pageSize:
      type: integer
      example: 10
      description: Page size which specifies how many records per page will be returned (default 50). Example - https://api.xero.com/bankfeeds.xro/1.0/Statements?pageSize=100 to specify page size of 100.
    pageCount:
      type: integer
      example: 1
      description: Number of pages available
    itemCount:
      type: integer
      example: 2
      description: Number of items returned

The Setup endpoint documented here: https://developer.xero.com/documentation/api-guides/conversions isn't included within the specification. Can it be included?

It seems that when using the Invoices endpoint the applied credit/overpayments/credits date returned via JSON and XML is different based on how the an individual invoice is requested.

A direct invoice request returns the "allocation" date as the invoice date whereas other type of querystring request (which is what the https://github.com/XeroAPI/xero-php-oauth2 uses as it's uri request type) returns the date the "creditnote / prepayment or overpayment was originally created not allocated.

Is this on purpose for any reason?

For example:
https://api.xero.com/api.xro/2.0/invoices/4766401f-5957-4a0e-9e55-54b79bc543bb
results in the "allocations" being returned with each date being the same as the invoice date

however https://api.xero.com/api.xro/2.0/Invoices?IDs=4766401f-5957-4a0e-9e55-54b79bc543bb returns the "allocations" with their original creation date.

Hi guys,

I would like to know if below if it is possible to happen:

1. An invoice without a contact
2. An invoice has a 'deleted' contact so I can't get this contact from the contact list API request
3. Is the contact info of an invoice a snapshot of time?

I am trying to round off the edge cases and please advise.

When getting a single contact, if the resource can't be found, the API doesn't return usable JSON data. Instead it returns a string.

For example:
https://api.xero.com/api.xro/2.0/Contacts/some-imaginary-uuid

Response:
The resource you're looking for cannot be found

Please update this so the response is in a format consistent with the rest of the API, such as:

{ "Status": "Not Found", "Errors": [ { "Message": "The resource you're looking for cannot be found" } ] }

...or something 🙂

Allocations seem to be missing the standard error handling properties:

• There's no summarizeErrors parameter for put method.
• There's no StatusAttributeString or ValidationErrors properties for the schema.

The schema is also missing the CreditNote property (and similar for Prepayment etc).

Hi

We are using the Accounting API via a library generated using swagger codegen. All working well apart from the field UpdatedDateUTC. In the OpenAPI file this is defined as a a string of type date-time. According to OpenAPI this means the string should RFC3339 format. That's somethign like this 1985-04-12T23:20:50.52Z.

However when we query for example GET Accounts. The value for this field looks like for example "/Date(1576107758447+0000)" The number in there seems to be the number of milliseconds since UNIX epoch.

The effect of this is that the unserialisation of the response fails as it can't turn that string into a in this case PHP DateTime.

I see that the current format for dates isn't likely to change https://developer.xero.com/documentation/api/requests-and-responses so I think the only solution currently would be to remove the format line from all the UTC fields.

Let me know what you think.

Regards

Steve

We currently have a plural createPayments PUT action as well as a singular createPayment POST action.
The singular POST action doesn't really serve any purpose over the plural PUT action, so I would like to suggest replacing it with updateOrCreatePayments. The primary purpose of this would be to allow bulk deleting multiple payments in one call (this is not something that is shown in the Xero API docs, but it still works as expected).
It would also provide some consistency with other endpoints which use the same actions.

Xero API, by default, only support 2 decimal points.

?unitdp=4 param can be used to use unit price/amount with 4 decimal points e.g. POST invoices - https://api.xero.com/api.xro/2.0/Invoices?unitdp=4

See Rounding in Xero for more info

This started as an issue on our PHP SDK
XeroAPI/xero-php-oauth2#53

To summarize, at this time all Accounting endpoints are tagged "Accounting" in the yaml file and when code is generated all operations (methods) are put into the same AccountingApi class. With so many endpoints and actions you can perform the AccountingApi class is large.

Changing how operations are tagged is fairly simple, but will have ripple effects across SDKs, documentation and sample code. So, this is not a change that we will be implementing at this time but will consider along with other requests that result in major refactoring of assets.

I'd like to hear what ppl think about this idea? Do you like creating a singleton (AccountingApi) and working with that or would you like to create an instance of AccountApi, ContactApi, InvoiceApi, etc?

Alternatively, we could group based on scope and not endpoint.
https://developer.xero.com/documentation/oauth2/scopes

• transactions, reports, settings, contacts, journals

In the above scenerio 'TransactionsApi class would have all the banktransactions, banktransfer,creditnote, invoice, overpayment, payment, etc together.

Look forward to hearing ppl's thoughts.

All API endpoints require you pass the Xero Tenant ID into each method call.

Example ...
$api->getContacts($tenantId);
$api->getContact($tenantId, $contactId);
$api->createContactsContacts($tenantId, $contactsList);

We made this choice due to since an access token is user based now and can be used to connect to 1 to N Xero orgs. Many apps are used by Accountants who will leverage multi-org authentication in the future and passing the Tenant Id into a method allows developers to create a Singleton of the AccountingApi class and then loop over an array of orgs and pass in unique tenant ids.

The proposed alternative pattern (PHP example

Set the tenantId on the configuration like the access token

$config = Configuration::getDefaultConfiguration();
$config->setHost('https://api.xero.com/api.xro/2.0);
$config->setAccessToken($accessToken);
$config->setTenantId($tenantId);

Reasoning
Right now we have to keep track of the tenantId and inject it from somewhere, every time we want to use the API, that means that in a system where we use dependency injection (e.g. Laravel) we can't just inject an instance of AccountingApi that's preconfigured, we need to inject the AccountingApi instance and either load the tenantId from a cache, or inject something else that knows about it.

Discussion
We are opening this topic up for discussion. We know different languages and developers have different preferences and want to hear both pro and con view points on this.

To set expectations around these discussions, we are focused on stability around SDKs and therefore no decision will be made on large scale requests like this until end of 2020.

Right now there is not specific type declared so ends up being an array of generic objects, would be nice to have it be an array of Strings to make the response easier to work with.

see https://developer.xero.com/documentation/api/reports

Using the CreditNoteID filter we get responses with lots of null fields.

Using the Where filter instead (filtering by date in our case) we get responses that are correctly populated, for the exact same credit note.

Observed using the Java SDK.

The BatchPaymentDetails model includes a property details that is limited to 18 UTF-8 characters. This field is used when creating batch payments to be used as the bank payment reference, which is also limited to 18 limited ASCII characters as a limitation in the Bacs service.

The issue is that the details field in the Xero GUI is not limited to 18 characters, and so blows up the API XeroAPI\XeroPHP\Models\Accounting\BatchPaymentDetails model on receipt of a batch payment response here:

https://github.com/XeroAPI/xero-php-oauth2/blob/master/lib/Models/Accounting/BatchPaymentDetails.php#L318

and marked as invalid here:

https://github.com/XeroAPI/xero-php-oauth2/blob/master/lib/Models/Accounting/BatchPaymentDetails.php#L217

The same may also happen for other generated languages, but I haven't looked.

I haven't experimented with the details field enough to determine the maximum length that a user can enter, but I guess the API description needs to specify the real maxium length. It is acceptable that the application - if it needs to use the details as a Bacs reference - truncates the string to 18 characters, since it also needs to transform the UTF-8 string to the limited ASCII characters that Bacs accepts anyway.

This is where it is defined:

https://github.com/XeroAPI/Xero-OpenAPI/blob/master/xero_accounting.yaml#L18997

As title