Hivebuy

Connect a Hivebuy company to keep purchasing and accounting in step: pull approved invoices with their line items and tax rows for booking, maintain the supplier master, and report back onto a purchase order when it has been ordered, delivered or invoiced in your other system. metamorphOS calls Hivebuy to do the work, and Hivebuy notifies metamorphOS by webhook when an invoice is created.

What you can do

• Companies: list the Hivebuy companies your API key may work in. Every other action needs one of these company ids.
• Invoices: list a company’s invoices, filtered by status, supplier number, invoice or due date, change date and payment state, and read one invoice by id. Each invoice comes back complete, with its line items, tax rows, matched purchase orders and file links.
• Suppliers: list suppliers, read one, create one, and change one. This is how an ERP vendor number reaches Hivebuy, in the supplier’s External supplier number.
• Purchase orders: list orders, read one with its items and status history, and set an order’s status. Setting a status is the only write the transactional side of Hivebuy accepts.
• Invoice events: start a process when Hivebuy creates an invoice.

Before you start

You need:

• A Hivebuy company, and a user who is an active member of it.
• The External API feature enabled for that company. Without it every call is refused, even with a valid key.
• The host name of your Hivebuy installation, for example app.hivebuy.de.

Set up Hivebuy

1. Sign in to Hivebuy as the user the connector should act as.

2. Create an API key for the versioned API. A key created for Hivebuy’s older API does not work here, so create a new one even if you already have one.

3. Give the key its scopes. The connector needs:

   • master-data:read and master-data:write for suppliers.
   • transactional:read for invoices and purchase orders, and transactional:write for setting a purchase order status.

   A key that only reads gets a permission error the first time a process tries to write.

4. Copy the key. You will paste it into metamorphOS in the next step.

Connect in metamorphOS

Activate the Hivebuy connector from the marketplace, add an account, and provide:

• Host: the host name of your Hivebuy installation, without https://, for example app.hivebuy.de.
• API key: the key you created. Each account can use a different key, so separate accounts can point at different Hivebuy installations.

Until you enter a valid key the connector stays unauthenticated. To check the credential, run List Companies: it needs no other input and returns the company ids the key may use. Note the id you want; every other action takes it as its Company id.

Receive invoice events

To start a process when Hivebuy creates an invoice, register the connector’s webhook URL in Hivebuy and give metamorphOS the endpoint’s signing secret.

1. Copy the webhook URL. On the Hivebuy connector’s page in metamorphOS, find Invoice Created under Webhook URLs and choose Copy URL. It ends in invoice-created.
2. Add the endpoint in Hivebuy. In Hivebuy’s webhook settings, add an endpoint with that URL and subscribe it to the invoice.created event only. The delivery carries the invoice itself and no event name, so an endpoint that received other events would hand them to the wrong trigger.
3. Copy the signing secret. Open the new endpoint in Hivebuy and copy its signing secret. It starts with whsec_.
4. Store the secret on the credential. In metamorphOS, open the Hivebuy credential’s menu and choose Set webhook signing secret, then paste the value exactly as Hivebuy shows it. You can also enter it in Webhook signing secret when you add the credential. Until it is set, the credential shows Needs webhook secret.
5. Deploy the process after the secret is stored. A process subscribed to Invoice Created, for example the Hivebuy Invoice Created Test process, picks up the secret when it is deployed. If you store or change the secret later, redeploy the process.

To check the setup, create an invoice in Hivebuy and confirm that a new instance of the subscribed process appears in Monitor. metamorphOS rejects any delivery whose signature does not match.

Good to know

• The company id in the action decides which company you touch, not the key’s default company. One key can be a member of several companies and address each of them.
• Deleting a supplier hides it, it does not remove it. A deleted supplier disappears from the supplier list but is still returned by Get Supplier, with its deletion date filled in. Check that date before you treat a supplier as active.
• Invoice file links expire after ten minutes. Download an attachment in the same run that fetched the invoice, and do not store the link.
• An invoice’s change date only tracks the invoice itself. Editing a line item, a tax row or a purchase order link does not move it, so a process that only asks for invoices changed since yesterday will miss those edits. Run a full pass over the open invoices on a schedule as well.
• Without a status filter, invoices classified as “not an invoice” or “wrong” are left out of the invoice list. Ask for those statuses explicitly when you want them.
• Invoices cannot be given a status from outside. The transactional side is read-only apart from a purchase order’s status.
• Hivebuy allows 60 requests a minute per key. Above that, calls are refused until the minute is over.