Build a custom integration

You can connect any system to BIRP today, with your own code and the operations of this documentation. This page gives the order to follow and the rules that keep a sync safe.

Before you start

• An API key with the scopes your system needs. See Create your first key and Scopes.

• A server that runs your code and keeps the key as a secret. See Keep your key safe.

• A place in your system to keep, for each record, its BIRP id next to your own id.

Order of operations

1. Call GET /v1/me and check the company, the key and its scopes.

2. Read the data you refer to: warehouses, categories and, if you invoice, tax codes.

3. Push your products, each with its external id. See Sync a product catalogue into BIRP.

4. Push or match your customers. See Match and update customers.

5. Create orders as your system receives them. See Receive orders from a shop.

6. Read the stock levels your shop shows. See Keep a shop's stock in step with BIRP.

7. If your system bills, create invoices and record payments. See Create and issue invoices.

Read changes with updated_since

The lists of products, categories, customers, warehouses, orders and invoices take updated_since. Keep the time your last read started, and ask only for what changed since then.

Read every page of the answer with the cursor, as Pagination and filtering shows. Stock levels have no updated_since: read the levels of the products you sell.

Write safely

• Send a new Idempotency-Key with every write, and the same key with its retries. See Idempotency.

• Prefer the upserts by external id. They create or update, so running a sync twice does no harm.

• Send large syncs in batches of up to 100 items. See Batch operations.

Link records with external ids

Give each record the id it has in your system, with a source that names your system, such as erp. You can then find the record by source and external_id, whether or not you kept its BIRP id.

References and external ids explains the rules, and how one record can carry the ids of two sources.

What to log

• For every error: the method, the path, the status, the code and the request_id.

• The idempotency key of each write, so you can retry it.

• Never the API key, and never whole bodies with customer data.

Choose the integration of the key

When you create a key, BIRP asks which integration it is for. BIRP uses the answer for statistics only: a key works the same with any value.

Related

• first-key
• sync-products
• handling-errors
• references-and-external-ids