Skip to the article

Connect Holded

Create an API token in Holded, connect it with the currency of your books, pull the chart of accounts and the tags, disconnect or change the key, and change the company by unconfiguring the ERP.

Where to find it:your-organization.conta.financeERPRules

Conta Finance sends your ledger to Holded as journal entriesThe record of a transaction in the accounting system: a debit and a credit for each movement.. You connect Holded with an API key, not with a sign-in page. The key belongs to the whole organization: one key, stored once, and every person with Read and edit access sends with it. The connection is the first step. After it, you map categories to ledger accounts, then you send a date range.

Before you start

  • You need Read and edit access to the organization. With Read only access, you can open the ERP page, but you cannot connect or disconnect. See Roles and access levels.
  • To change the company, you need Full access. See Change the company.
  • Only one ERP can be set up. When QuickBooks Online or Universal ERP is already set up, a person with Full access must unconfigure it first.
  • You need a Holded user who can create API tokens. A Holded API key belongs to the Holded account (the company), not to a person.
  • The organization sends to one Holded company, the one that the key belongs to.

Create the API token in Holded

  1. In Holded, open Settings, then Developers, then Credentials.
  2. Select Add API Token, and create a v2 token. A v1 key does not work.
  3. Give the token these permissions:
    • accounting:chart-of-accounts.read
    • accounting:daily-ledger.read
    • accounting:daily-ledger.write
  4. Optional: add account:tags.read. With it, Conta reads your Holded tags as classes. Without it, the list of classes stays empty, and everything else works.
  5. Copy the key. Keep it in a safe place until you paste it in Conta.

Connect the key

  1. Open ERP in the sidebar. While no ERP is set up, the page shows one card for each ERP. Select Holded.
  2. On the Rules tab, paste the key in API key. To check what you pasted, select Show the key.
  3. In Books currency, pick USD, EUR or GBP. Pick the currency your Holded company keeps its books in.
  4. Optional: write a Company name. It is a label for Conta only. If you leave it empty, the card shows Holded.
  5. Select Connect Holded.

Conta sends the key to Holded to check it. If Holded accepts it, a message says Holded is connected. If not, the message says why, and Conta keeps nothing:

  • Holded does not know the key. Check that you copied all of it, and that nobody deleted it in Holded.
  • The key lacks a permission. The message lists the permissions to give the token.
  • The organization already has a key. Disconnect first, then connect again.

Under the message, Conta shows what Holded answered, in Holded's own words.

What the connection card shows

The card at the top of the Rules tab shows the same to everyone:

  • A key is stored. The card shows the name of the company, the day the key was connected, the currency of the books, and the last four characters of the key, as API key ending in ••••1234. A person with Read and edit access also sees Disconnect.
  • The company is set, and the key was disconnected. A person with Read and edit access sees the form again, with the name and the currency that were kept. A person with Read only access sees that no key is stored.
  • Nothing is set up. A person with Read and edit access sees the form. A person with Read only access sees that Holded is not connected.

Conta never shows the full key, and it never shows it again after you connect. The form is always empty.

Nobody needs a connection of their own. When a key is stored, every person with Read and edit access can refresh the accounts and send. The ERP column and the ERP filter of the Transactions page follow the same key.

Read the chart of accounts

Right after you connect, Conta has not read anything from Holded yet. The rules pick from a copy of the accounts, so someone must read them first.

  1. On the Chart of accounts card, select Refresh accounts.
  2. Wait for the message that says what changed: how many accounts and classes Conta added, updated and removed.

Conta reads two lists from Holded:

  • The accounts. The id of an account is its number, such as 57200001. Holded does not say if an account is an asset, a liability or an expense, so Conta reads it from the number, with the Spanish general chart of accounts (PGC). Each slot of a rule then offers only the accounts that belong on its side of the books. Conta does not classify the accounts that can sit on either side, such as 551 and 559, or the accounts of groups 8 and 9. A slot does not offer them. If your company uses its own numbering, some accounts may not appear in the slots.
  • The classes. They are the tags of your Holded account. A rule can tag its lines with one tag. If the key lacks account:tags.read, or the account has no tags, the list is empty.

Select Refresh accounts again when you add, rename or archive an account, or when you add a tag in Holded. A refresh replaces the copy. It does not change your rules. If a rule names an account that is gone, the rule stays as it is, a warning lists it, and its documents are blocked until you pick another account.

What a sent entry looks like in Holded

A document you send becomes one entry in the daily ledger of Holded. Two things differ from QuickBooks Online:

  • There is no link to the entry. Holded has no page for one entry, so the Sync tab shows no link to open it. Conta writes the reference of the document at the start of the notes of the entry. In Holded, search for that reference to find the entry.
  • Holded numbers the entry itself. Conta cannot set the number, so the Sync tab shows the id that Holded gave in place of a document number.

Holded has no sandbox. A key always points at a real company, so every send writes real entries.

The quota of the Holded API

Each call to Holded counts against the quota of your Holded plan. A small plan allows few calls each month, and a refresh and a send use several. When the monthly quota is used up, Holded refuses every call until it renews. A message tells you when this happens, and says to try again after the quota renews or to move to a plan with a larger quota. When you send too many calls in one minute, the message gives the seconds to wait, and the next send can try again.

When Holded refuses a send because of the limit, Conta stops there. It does not try the documents that are left, and it does not mark them as refused. The result says how many are left and how long to wait. Select Send to Holded again after that time, and the send goes on from the first document that was not sent.

When the result of a send is not known

Sometimes Holded may create an entry and the answer is lost: the connection drops, the request times out, or Holded answers with an error or with a message Conta cannot read. Conta cannot know if the entry exists, and Holded cannot detect a duplicate. So Conta does not send that document again by itself. It stays in the Error view with a message that tells you to check the daily ledger in Holded.

  1. In Holded, open the daily ledger and search for the reference of the document.
  2. If the entry is there, leave it. If it is not, in the Error view select Take this attempt back out, so the next send writes it again on the document, then Take the attempt back out. Nothing is deleted in Holded.
  3. Select Send to Holded again. Conta sends the document once.

Do not take the document back out before you check. A new send creates a second entry.

Disconnect

  1. On the connection card, select Disconnect.
  2. In Disconnect Holded?, select Disconnect.

What changes:

  • Conta deletes the API key, for the whole organization. Nobody can refresh or send until a key is connected again.
  • The company, the pulled chart of accounts, the rules, the settings and the record of the documents sent stay. The ERP column of the Transactions page stays.

What does not change:

  • The key stays alive in Holded. Holded has no call to revoke a key. If nobody uses the key any more, delete it in Holded, in the same Credentials page.
  • The entries already in Holded stay there. Disconnecting deletes nothing in Holded.

Change the key

A key can be replaced only after you disconnect it. Use it when the key was deleted in Holded, or when you want to rotate it.

  1. Create a new token in Holded, with the same permissions. See Create the API token in Holded.
  2. In Conta, select Disconnect, then confirm.
  3. Paste the new key in API key, and select Connect Holded.
  4. Delete the old key in Holded.

This time, the form shows the name and the currency of the company that Conta kept. It does not ask for them again. After you connect, a message says that the name and the currency stay as they were.

Change the company

The organization sends to one company. To send to another Holded company, to change the currency of the books, or to move to another ERP, unconfigure the ERP, then connect again. Only a person with Full access can unconfigure the ERP. See Roles and access levels.

If the old company must stay clean, take its entries back out first. On the Sync tab, select Take it back out of the ERP for each document, as Send to the ERP describes. After you unconfigure, Conta has no record of those entries, so it cannot take them out for you.

  1. Open ERP in the sidebar. The page opens on the ERP of the organization.
  2. At the top right, select Unconfigure ERP.
  3. In Unconfigure Holded?, read the list. It gives the number of each thing that Conta deletes, and it says that the API key is deleted.
  4. Select Delete and unconfigure.

Afterwards, ERP in the sidebar shows one card for each ERP. The first range you send to the new company writes every document again.