@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Sync for Commerce
@base https://api.codat.io
@version 1.1
@auth ApiKey Authorization in header
@endpoints 22
@hint download_for_search
@toc config(5), companies(11), sync(3), clients(1), meta(2)

@group config
@endpoint GET /config/sync/commerce/{commerceKey}/{accountingKey}/start
@required {commerceKey: str, accountingKey: str}
@optional {merchantIdentifier: str}
@returns(200) {url: str}
@errors {400, 401, 402, 403, 404, 429, 500, 503}

@endgroup

@group companies
@endpoint GET /companies
@optional {page: int(int32)=1, pageSize: int(int32)=100, query: str, orderBy: str}
@returns(200)
@errors {400, 401, 402, 403, 404, 429, 500, 503}

@endpoint POST /companies
@required {name: str}
@optional {description: str, tags: map}
@returns(200)
@errors {400, 401, 402, 403, 429, 500, 503}

@endpoint GET /companies/{companyId}/connections
@required {companyId: str(uuid)}
@optional {page: int(int32)=1, pageSize: int(int32)=100, query: str, orderBy: str}
@returns(200)
@errors {400, 401, 402, 403, 404, 429, 500, 503}

@endpoint POST /companies/{companyId}/connections
@required {companyId: str(uuid)}
@optional {platformKey: str}
@returns(200) {id: str(uuid), integrationId: str(uuid), integrationKey: str, sourceId: str(uuid), sourceType: str, platformName: str, linkUrl: str(uri), status: str, lastSync: str, created: str, dataConnectionErrors: [map]?, connectionInfo: map?}
@errors {401, 402, 403, 404, 429, 500, 503}

@endpoint PATCH /companies/{companyId}/connections/{connectionId}
@required {companyId: str(uuid), connectionId: str(uuid)}
@optional {status: str(PendingAuth/Linked/Unlinked/Deauthorized)}
@returns(200) {id: str(uuid), integrationId: str(uuid), integrationKey: str, sourceId: str(uuid), sourceType: str, platformName: str, linkUrl: str(uri), status: str, lastSync: str, created: str, dataConnectionErrors: [map]?, connectionInfo: map?}
@errors {401, 402, 403, 404, 429, 500, 503}

@endpoint PUT /companies/{companyId}/connections/{connectionId}/authorization
@returns(200) {id: str(uuid), integrationId: str(uuid), integrationKey: str, sourceId: str(uuid), sourceType: str, platformName: str, linkUrl: str(uri), status: str, lastSync: str, created: str, dataConnectionErrors: [map]?, connectionInfo: map?}
@errors {401, 402, 403, 404, 429, 500, 503}

@endgroup

@group config
@endpoint GET /config/companies/{companyId}/sync/commerce
@required {companyId: str(uuid)}
@returns(200) {companyId: str(uuid), accountingSoftwareCompanyName: str, enable: bool, configured: bool, schedule: map{selectedFrequency: str, frequencyOptions: [str], startDate: str, syncHour: int, timeZone: str}, configuration: map{countryCode: str, mapSettings: map{outputFormat: str}, sales: map{syncSales: bool, accounts: map?, invoiceStatus: map{selectedInvoiceStatus: str?, invoiceStatusOptions: [str]?}, salesCustomer: map{selectedCustomerId: str?, customerOptions: [map]?}, taxRates: map?, newTaxRates: map{accountingTaxRateOptions: [map]?, commerceTaxRateOptions: [map]?, taxRateMappings: [map]?, selectedDefaultZeroTaxRateId: str?, defaultZeroTaxRateOptions: [map]?}, grouping: map{groupingPeriod: map, groupingLevels: map}}, payments: map{syncPayments: bool, accounts: map?}, newPayments: map{syncPayments: bool, accounts: map?}, fees: map{feesSupplier: map{selectedSupplierId: str?, supplierOptions: [map]?}, syncFees: bool, accounts: map?}}}
@errors {401, 402, 403, 404, 429, 500, 503}

@endpoint POST /config/companies/{companyId}/sync/commerce
@required {companyId: str(uuid)}
@returns(200) {companyId: str(uuid), accountingSoftwareCompanyName: str, enable: bool, configured: bool, schedule: map{selectedFrequency: str, frequencyOptions: [str], startDate: str, syncHour: int, timeZone: str}, configuration: map{countryCode: str, mapSettings: map{outputFormat: str}, sales: map{syncSales: bool, accounts: map?, invoiceStatus: map{selectedInvoiceStatus: str?, invoiceStatusOptions: [str]?}, salesCustomer: map{selectedCustomerId: str?, customerOptions: [map]?}, taxRates: map?, newTaxRates: map{accountingTaxRateOptions: [map]?, commerceTaxRateOptions: [map]?, taxRateMappings: [map]?, selectedDefaultZeroTaxRateId: str?, defaultZeroTaxRateOptions: [map]?}, grouping: map{groupingPeriod: map, groupingLevels: map}}, payments: map{syncPayments: bool, accounts: map?}, newPayments: map{syncPayments: bool, accounts: map?}, fees: map{feesSupplier: map{selectedSupplierId: str?, supplierOptions: [map]?}, syncFees: bool, accounts: map?}}}
@errors {400, 401, 402, 403, 404, 409, 429, 500, 503}

@endpoint GET /config/integrations
@optional {page: int(int32)=1, pageSize: int(int32)=100, query: str, orderBy: str}
@returns(200)
@errors {400, 401, 402, 403, 429, 500, 503}

@endpoint GET /config/integrations/{platformKey}/branding
@required {platformKey: str}
@returns(200) {logo: map{full: map{image: map{src: str(uri), alt: str}}, square: map{image: map{src: str(uri), alt: str}}}, button: map{default: map{image: map{src: str(uri), alt: str}}, hover: map{image: map{src: str(uri), alt: str}}}, sourceId: str(uuid)}
@errors {401, 402, 403, 404, 429, 500, 503}

@endgroup

@group sync
@endpoint GET /sync/commerce/config/ui/text
@required {locale: str(en-us/fr-fr)}
@returns(200)
@errors {401, 402, 403, 429, 500, 503}

@endpoint PATCH /sync/commerce/config/ui/text
@required {locale: str(en-us/fr-fr)}
@returns(200)
@errors {400, 401, 402, 403, 429, 500, 503}

@endgroup

@group clients
@endpoint GET /clients/{clientId}/config/ui/accounts/platform/{platformKey}
@returns(200) {visibleAccounts: [str]?}
@errors {401, 402, 403, 404, 429, 500, 503}

@endgroup

@group sync
@endpoint POST /sync/commerce/config/ui/accounts/platform/{platformKey}
@required {platformKey: str}
@optional {visibleAccounts: [str]}
@returns(200) {visibleAccounts: [str]?}
@errors {400, 401, 402, 403, 404, 429, 500, 503}

@endgroup

@group companies
@endpoint POST /companies/{companyId}/sync/commerce/latest
@required {companyId: str(uuid)}
@optional {syncTo: str}
@returns(200) {syncDateRangeUtc: map{start: str, finish: str}, companyId: str(guid), commerceSyncId: str(guid), syncStatusCode: int(int32), syncStatus: str?, errorMessage: str?, syncExceptionMessage: str?, syncUtc: str, dataConnections: [map]?, dataPushed: bool}
@errors {400, 401, 402, 403, 404, 429, 500, 503}

@endgroup

@group meta
@endpoint POST /meta/companies/{companyId}/sync/commerce/historic
@required {companyId: str(uuid), dateRange: map{start!: str, finish!: str}}
@returns(200) {syncDateRangeUtc: map{start: str, finish: str}, companyId: str(guid), commerceSyncId: str(guid), syncStatusCode: int(int32), syncStatus: str?, errorMessage: str?, syncExceptionMessage: str?, syncUtc: str, dataConnections: [map]?, dataPushed: bool}
@errors {400, 401, 402, 403, 404, 429, 500, 503}

@endpoint GET /meta/companies/{companyId}/sync/commerce/status
@required {companyId: str(uuid)}
@returns(200) {companyId: str(uuid), commerceSyncId: str(guid), syncId: str(uuid), syncStatusCode: int(int32), syncStatus: str?, errorMessage: str?, syncExceptionMessage: str?, syncUtc: str, dataPushed: bool, dataConnections: [map]?}
@errors {401, 402, 403, 404, 429, 500, 503}

@endgroup

@group companies
@endpoint GET /companies/{companyId}/sync/commerce/syncs/lastSuccessful/status
@required {companyId: str(uuid)}
@returns(200) {companyId: str?, syncId: str?, syncStatusCode: int(int32), syncStatus: str?, errorMessage: str?, syncExceptionMessage: str?, syncUtc: str, dataPushed: bool}
@errors {401, 402, 403, 404, 429, 500, 503}

@endpoint GET /companies/{companyId}/sync/commerce/syncs/latest/status
@required {companyId: str(uuid)}
@returns(200) {companyId: str?, syncId: str?, syncStatusCode: int(int32), syncStatus: str?, errorMessage: str?, syncExceptionMessage: str?, syncUtc: str, dataPushed: bool}
@errors {401, 402, 403, 404, 429, 500, 503}

@endpoint GET /companies/{companyId}/sync/commerce/syncs/{syncId}/status
@required {companyId: str(uuid), syncId: str(uuid)}
@returns(200) {companyId: str?, syncId: str?, syncStatusCode: int(int32), syncStatus: str?, errorMessage: str?, syncExceptionMessage: str?, syncUtc: str, dataPushed: bool}
@errors {401, 402, 403, 404, 429, 500, 503}

@endpoint GET /companies/{companyId}/sync/commerce/syncs/list/status
@required {companyId: str(uuid)}
@returns(200)
@errors {401, 402, 403, 404, 429, 500, 503}

@endgroup

@end