@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Sync for Expenses API
@base https://api.codat.io
@version prealpha
@auth ApiKey Authorization in header
@endpoints 13
@toc companies(13)

@endpoint GET /companies/{companyId}/sync/expenses/config
@desc Get company configuration
@returns(200) {bankAccount: map{id: str}, supplier: map{id: str}, customer: map{id: str}} # Success
@errors {401: Your API request was not properly authorized., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again.}

@endpoint POST /companies/{companyId}/sync/expenses/config
@desc Set company configuration
@required {bankAccount: map{id: str}, supplier: map{id: str}, customer: map{id: str}}
@returns(200) {bankAccount: map{id: str}, supplier: map{id: str}, customer: map{id: str}} # Success
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again.}

@endpoint GET /companies/{companyId}/sync/expenses/mappingOptions
@desc Mapping options
@returns(200) {expenseProvider: str?, accounts: [map]?, trackingCategories: [map]?, taxRates: [map]?} # Success
@errors {401: Your API request was not properly authorized., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again.}

@endpoint POST /companies/{companyId}/sync/expenses/syncs
@desc Initiate sync
@optional {datasetIds: [str(uuid)]}
@returns(202) {syncId: str(uuid)} # Returns the newly created SyncId
@errors {400: If model is incorrect, 404: If company not found, 422: If the specified company does not have a valid set of DataConnections setup}

@endpoint GET /companies/{companyId}/sync/expenses/syncs/lastSuccessful/status
@desc Last successful sync
@returns(200) {companyId: str?, syncId: str?, syncStatusCode: int(int32), syncStatus: str?, errorMessage: str?, syncExceptionMessage: str?, syncUtc: str, dataPushed: bool} # Success
@errors {401: Your API request was not properly authorized., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again.}

@endpoint GET /companies/{companyId}/sync/expenses/syncs/latest/status
@desc Latest sync status
@returns(200) {companyId: str?, syncId: str?, syncStatusCode: int(int32), syncStatus: str?, errorMessage: str?, syncExceptionMessage: str?, syncUtc: str, dataPushed: bool} # Success
@errors {401: Your API request was not properly authorized., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again.}

@endpoint GET /companies/{companyId}/sync/expenses/syncs/list/status
@desc List sync statuses
@returns(200) Success
@errors {401: Your API request was not properly authorized., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again.}

@endpoint GET /companies/{companyId}/sync/expenses/syncs/{syncId}/status
@desc Get Sync status
@required {syncId: str(uuid) # Unique identifier for a sync.}
@returns(200) {companyId: str?, syncId: str?, syncStatusCode: int(int32), syncStatus: str?, errorMessage: str?, syncExceptionMessage: str?, syncUtc: str, dataPushed: bool} # Success
@errors {401: Your API request was not properly authorized., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again.}

@endpoint GET /companies/{companyId}/sync/expenses/syncs/{syncId}/transactions
@desc Get Sync transactions
@required {syncId: str(uuid) # Unique identifier for a sync.}
@optional {page: int(int32)=1 # Page number. [Read more](https://docs.codat.io/using-the-api/paging)., pageSize: int(int32)=100 # Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging).}
@returns(200) Success
@errors {401: Your API request was not properly authorized., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again.}

@endpoint GET /companies/{companyId}/sync/expenses/syncs/{syncId}/transactions/{transactionId}
@desc Get Sync Transaction
@required {syncId: str(uuid) # Unique identifier for a sync., transactionId: str(uuid) # The unique identifier for your SMB's transaction.}
@returns(200) Success
@errors {401: Your API request was not properly authorized., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again.}

@endpoint POST /companies/{companyId}/sync/expenses/data/expense-transactions
@desc Create expense-transactions
@optional {items: [map{id!: str(uuid), type!: str, issueDate!: str, currency!: str, currencyRate: num, contactRef: map, merchantName: str, lines: [map], notes: str}]}
@returns(200) {datasetId: str(uuid)} # OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again.}
@example_request {"items":[{"id":"4d7c6929-7770-412b-91bb-44d3bc71d111","type":"Payment","issueDate":"2021-05-21T00:00:00+00:00","currency":"GBP","currencyRate":1.18,"contactRef":{"id":"f5244103-5223-4b0a-857f-50566ac86c11","type":"Supplier"},"merchantName":"Amazon UK","lines":[{"netAmount":110.42,"taxAmount":14.43,"taxRateRef":{"id":"77a32ee2-60c7-4ab9-917a-bd82e2e43a26"},"accountRef":{"id":"9aa5b894-1be9-4f97-96cd-ffde90766b3e"},"trackingRefs":[{"id":"dde5b35f-5d33-40bd-a34f-ee529f4c785c"}]}],"notes":"APPLE.COM/BILL - 09001077498 - Card Ending: 4590"}]}

@endpoint PUT /companies/{companyId}/sync/expenses/expense-transactions/{transactionId}
@desc Update expense-transactions
@required {type: str(Payment/Refund/Reward/Chargeback/TransferIn/TransferOut/AdjustmentIn/AdjustmentOut) # The type of transaction., issueDate: str # Date the transaction was recorded.}
@optional {currency: str # Currency the transaction was recorded in., currencyRate: num # Rate to convert the total amount of the payment into the base currency for the company at the time of the payment.  Currency rates in Codat are implemented as the multiple of foreign currency units to each base currency unit.    It is not possible to perform the currency conversion with two or more non-base currencies participating in the transaction. For example, if a company's base currency is USD, and it has a bill issued in EUR, then the bill payment must happen in USD or EUR.  Where the currency rate is provided by the underlying accounting platform, it will be available from Codat with the same precision (up to a maximum of 9 decimal places).   For accounting platforms which do not provide an explicit currency rate, it is calculated as `baseCurrency / foreignCurrency` and will be returned to 9 decimal places.  ## Examples with base currency of GBP  | Foreign Currency | Foreign Amount | Currency Rate | Base Currency Amount (GBP) | | :--------------- | :------------- | :------------ | :------------------------- | | **USD**          | $20            | 0.781         | £15.62                     | | **EUR**          | €20            | 0.885         | £17.70                     | | **RUB**          | ₽20            | 0.011         | £0.22                      |  ## Examples with base currency of USD  | Foreign Currency | Foreign Amount | Currency Rate | Base Currency Amount (USD) | | :--------------- | :------------- | :------------ | :------------------------- | | **GBP**          | £20            | 1.277         | $25.54                     | | **EUR**          | €20            | 1.134         | $22.68                     | | **RUB**          | ₽20            | 0.015         | $0.30                      |, contactRef: map{id: str, contactType: str}, merchantName: str # Name of the merchant where the purchase took place, lines: [map{netAmount!: num, taxAmount!: num, taxRateRef: map, accountRef!: map, trackingRefs: [map]}] # Array of transaction lines., notes: str # Any private, company notes about the transaction.}
@returns(202) {syncId: str} # Accepted
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 422: The requests made can't be processed. This may be due to differences in platform support., 429: Too many requests were made in a given amount of time. Wait a short period and then try again.}

@endpoint POST /companies/{companyId}/sync/expenses/syncs/{syncId}/transactions/{transactionId}/attachments
@desc Upload attachment
@returns(200) {companyId: str(uuid), id: str, transactionId: str} # OK
@errors {400: The request made is not valid., 401: Your API request was not properly authorized., 404: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted., 429: Too many requests were made in a given amount of time. Wait a short period and then try again.}

@end