Skip to the content
doroutes
Menu

DoRoutes API · version 1

Accounting

GET/v1/accounting/callback/{provider}

Finish signing in to a package

Where the package sends the browser after sign-in; no tenant key or session, as the sealed state names the firm. Redirects to the admin UI's Settings → Accounting with connected={provider}, or with error saying why.

Parameters

  • providerstring, in the path, required
  • codestring, in the query
  • statestring, in the query, required
  • errorstring, in the query

Response 302

To the admin UI.

GET/v1/admin/accounting

The accounting connection

Needs the accounting.manage permission. The firm's connection that isn't disconnected (null when there is none), the packages offered and how many syncs failed.

Response 200 · object

The connection.

  • accountingAccountingOverview, required
    • connectionAccountingConnection or null, required
      • idinteger (int64), required
      • providerstring, required

        One of: xero quickbooks sage zoho wave

      • org_namestring, required
      • statusstring, required

        One of: active needs_reconnect

      • mappedboolean, required
      • mappingAccountingMapping or null, required
        • tax_codesobject, required

          By VAT rate: standard, reduced, zero, exempt, none.

        • sales_accountstring, required
        • bank_accountsobject, required

          By payment method: bank_transfer, card, cash, cheque and other, and paypal for a firm taking PayPal (a PayPal payment pushed with none fails, saying so).

      • sync_fromstring (date)
      • connected_atstring, required
    • providersarray of string, required
    • failuresinteger, required
Example response 200
{
  "accounting": {
    "connection": {
      "id": 0,
      "provider": "xero",
      "org_name": "string",
      "status": "active",
      "mapped": true,
      "mapping": {
        "tax_codes": {},
        "sales_account": "string",
        "bank_accounts": {}
      },
      "sync_from": "date",
      "connected_at": "string"
    },
    "providers": [
      "string"
    ],
    "failures": 0
  }
}

Response 401 · Error

No tenant key, or no valid session.

  • errorobject, required
    • codestring, required

      A short machine-readable name, such as not_found.

    • messagestring, required

      What went wrong, for people.

  • request_idstring, required

    Matches the X-Request-ID response header.

Example response 401
{
  "error": {
    "code": "string",
    "message": "string"
  },
  "request_id": "string"
}

Response 403 · Error

The session may not do this.

Fields as in The accounting connection

Response 500 · Error

Something failed on our side.

Fields as in The accounting connection

DELETE/v1/admin/accounting

Disconnect the accounting package

Needs the accounting.manage permission. Nothing more is pushed; what is in the package stays. Connecting the same organisation again resumes with its mapping.

Response 200 · object

The connection.

  • accountingAccountingOverview, required
    • connectionAccountingConnection or null, required
      • idinteger (int64), required
      • providerstring, required

        One of: xero quickbooks sage zoho wave

      • org_namestring, required
      • statusstring, required

        One of: active needs_reconnect

      • mappedboolean, required
      • mappingAccountingMapping or null, required
        • tax_codesobject, required

          By VAT rate: standard, reduced, zero, exempt, none.

        • sales_accountstring, required
        • bank_accountsobject, required

          By payment method: bank_transfer, card, cash, cheque and other, and paypal for a firm taking PayPal (a PayPal payment pushed with none fails, saying so).

      • sync_fromstring (date)
      • connected_atstring, required
    • providersarray of string, required
    • failuresinteger, required
Example response 200
{
  "accounting": {
    "connection": {
      "id": 0,
      "provider": "xero",
      "org_name": "string",
      "status": "active",
      "mapped": true,
      "mapping": {
        "tax_codes": {},
        "sales_account": "string",
        "bank_accounts": {}
      },
      "sync_from": "date",
      "connected_at": "string"
    },
    "providers": [
      "string"
    ],
    "failures": 0
  }
}

Response 401 · Error

No tenant key, or no valid session.

Fields as in The accounting connection

Response 403 · Error

The session may not do this.

Fields as in The accounting connection

Response 500 · Error

Something failed on our side.

Fields as in The accounting connection

GET/v1/admin/accounting/connect/{provider}

Where to sign in to a package

Needs the accounting.manage permission. The package's sign-in address, carrying a sealed state that names the firm, the staff member and the package, good for 10 minutes. The package sends the browser back to /v1/accounting/callback/{provider}.

Parameters

  • providerstring, in the path, required

Response 200 · object

The address.

  • connectobject, required
    • urlstring, required
Example response 200
{
  "connect": {
    "url": "string"
  }
}

Response 401 · Error

No tenant key, or no valid session.

Fields as in The accounting connection

Response 403 · Error

The session may not do this.

Fields as in The accounting connection

Response 404 · Error

Not found, or not yours.

Fields as in The accounting connection

Response 500 · Error

Something failed on our side.

Fields as in The accounting connection

GET/v1/admin/accounting/lists

The package's tax codes and accounts

Needs the accounting.manage permission. What the firm maps its VAT rates, sales and payment methods to, read from the package.

Response 200 · object

The lists.

  • listsAccountingLists, required
    • tax_codesarray of object, required
      • idstring, required
      • namestring, required
    • sales_accountsarray of object, required
      • idstring, required
      • namestring, required
    • bank_accountsarray of object, required
      • idstring, required
      • namestring, required
Example response 200
{
  "lists": {
    "tax_codes": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "sales_accounts": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "bank_accounts": [
      {
        "id": "string",
        "name": "string"
      }
    ]
  }
}

Response 401 · Error

No tenant key, or no valid session.

Fields as in The accounting connection

Response 403 · Error

The session may not do this.

Fields as in The accounting connection

Response 404 · Error

Not found, or not yours.

Fields as in The accounting connection

Response 409 · Error

It clashes with what is stored.

Fields as in The accounting connection

Response 500 · Error

Something failed on our side.

Fields as in The accounting connection

PUT/v1/admin/accounting/mapping

Map the firm to its package

Needs the accounting.manage permission. A tax code for each VAT rate the firm uses, the sales account and a bank account for each payment method. With sync_from (a date), documents sent from then, and their payments, are queued unless queued already.

Request body · object

  • mappingAccountingMapping, required
    • tax_codesobject, required

      By VAT rate: standard, reduced, zero, exempt, none.

    • sales_accountstring, required
    • bank_accountsobject, required

      By payment method: bank_transfer, card, cash, cheque and other, and paypal for a firm taking PayPal (a PayPal payment pushed with none fails, saying so).

  • sync_fromstring (date)
Example request
{
  "mapping": {
    "tax_codes": {},
    "sales_account": "string",
    "bank_accounts": {}
  },
  "sync_from": "date"
}

Response 200 · object

The connection.

  • accountingAccountingOverview, required
    • connectionAccountingConnection or null, required
      • idinteger (int64), required
      • providerstring, required

        One of: xero quickbooks sage zoho wave

      • org_namestring, required
      • statusstring, required

        One of: active needs_reconnect

      • mappedboolean, required
      • mappingAccountingMapping or null, required
        • tax_codesobject, required

          By VAT rate: standard, reduced, zero, exempt, none.

        • sales_accountstring, required
        • bank_accountsobject, required

          By payment method: bank_transfer, card, cash, cheque and other, and paypal for a firm taking PayPal (a PayPal payment pushed with none fails, saying so).

      • sync_fromstring (date)
      • connected_atstring, required
    • providersarray of string, required
    • failuresinteger, required
Example response 200
{
  "accounting": {
    "connection": {
      "id": 0,
      "provider": "xero",
      "org_name": "string",
      "status": "active",
      "mapped": true,
      "mapping": {
        "tax_codes": {},
        "sales_account": "string",
        "bank_accounts": {}
      },
      "sync_from": "date",
      "connected_at": "string"
    },
    "providers": [
      "string"
    ],
    "failures": 0
  }
}

Response 400 · Error

The request is not valid.

Fields as in The accounting connection

Response 401 · Error

No tenant key, or no valid session.

Fields as in The accounting connection

Response 403 · Error

The session may not do this.

Fields as in The accounting connection

Response 404 · Error

Not found, or not yours.

Fields as in The accounting connection

Response 500 · Error

Something failed on our side.

Fields as in The accounting connection

GET/v1/admin/accounting/failures

Syncs that failed

Needs the accounting.manage permission. Newest first, on the current connection.

Response 200 · object

The failures.

  • failuresarray of AccountingFailure, required
    • idinteger (int64), required
    • kindstring, required

      One of: invoice credit_note payment payment_removed

    • invoice_idinteger (int64), required
    • numberstring, required
    • errorstring, required
    • failed_atstring, required
Example response 200
{
  "failures": [
    {
      "id": 0,
      "kind": "invoice",
      "invoice_id": 0,
      "number": "string",
      "error": "string",
      "failed_at": "string"
    }
  ]
}

Response 401 · Error

No tenant key, or no valid session.

Fields as in The accounting connection

Response 403 · Error

The session may not do this.

Fields as in The accounting connection

Response 500 · Error

Something failed on our side.

Fields as in The accounting connection

POST/v1/admin/accounting/sync/{id}/retry

Try a failed sync again

Needs the accounting.manage permission. From now, as if new.

Parameters

  • idstring, in the path, required

Response 200 · object

Queued.

  • retryingboolean, required
Example response 200
{
  "retrying": true
}

Response 400 · Error

The request is not valid.

Fields as in The accounting connection

Response 401 · Error

No tenant key, or no valid session.

Fields as in The accounting connection

Response 403 · Error

The session may not do this.

Fields as in The accounting connection

Response 404 · Error

Not found, or not yours.

Fields as in The accounting connection

Response 500 · Error

Something failed on our side.

Fields as in The accounting connection