Skip to content

Integration · explainer

What Is an API? How Business Systems Exchange Data

An API is an agreed way for software to ask other software for data or an action. For anyone asking “what is an API”, a web API takes a request and sends a reply. API integration puts those calls into a business process, with field mapping and checks for failures.

Beezr · Published · 8 min read

Sandline, our example company, runs this on Beezr → see how

On this page

“Can’t the order just go straight into accounting?”

Monday morning. Hana finds another approved Northbay Hotels order waiting to be retyped.

Karim says, “They have an API.” Hana still has her coffee to finish.

So, what is an API? And what work hides inside that “just”? Let's follow the order, the reply and the things that go wrong.

What is an API in plain English?

An API is an agreed way for software to ask other software for something. It stands for application programming interface.

The request might fetch an order or create an invoice. AWS's introduction explains this exchange.

Think of a waiter. You order from the menu. You don't walk into the kitchen and move the pans.

The catch is the menu. Does it offer the job you need? What details must you send, and what may you ask for?

We'll use web APIs here. AWS lists other types too.

Ask at the service hatch An order for 40 boxes of NG-200 asks the API to create an invoice. The contract requires customer, item, quantity and tax code. Accounting returns a reference or an error. NG-20040 boxesInvoice requestAPIAccountinginternal workCustomer · itemQuantity · tax codeReference / error
Ask at the service hatch An order for 40 boxes of NG-200 asks the API to create an invoice. The contract requires customer, item, quantity and tax code. Accounting returns a reference or an error. NG-20040 boxesInvoicerequestAPICustomer · itemQuantity · tax codeReference / error
The interface tells the caller what it may ask for and what it must provide.

What is an API call or endpoint?

An API call is one request. An endpoint is the web address that receives it. The method says what kind of job you're asking for.

Method Meaning in HTTP Semantics
GET Retrieves a representation: a view of the thing requested.
POST Submits content for processing.

The address alone isn't enough. Which fields are required? Who may call it, and what counts as success?

Ask Karim to show the invoice job in the docs. Which fields go out? What comes back?

A way to write the contract What it covers
OpenAPI Paths, operations, request bodies, responses and security needs.

If the plan is to send the whole order and see, stop there. You still need to match the fields.

How does an approved order reach accounting?

Northbay Hotels orders 40 boxes of NG-200, nitrile gloves. Sara holds the sales order in Beezr. Hana approves it.

The workflow calls accounting through an Integration Hub action or outgoing REST API step. It saves the accounting reference and posting status on the record.

This accounting API is fictional. So are /invoices and INV-88.

The order goes out; the reply comes back
SaraBeezrHanaAccounting
  1. Sara → BeezrSend the sales order for approval
  2. Hana → BeezrApprove the sales order
  3. Beezr → AccountingPOST /invoices, customer reference, NG-200, quantity 40, tax code
  4. Accounting ⇢ Beezr201 Created, invoice reference INV-88
  5. Save the accounting reference and posting status on the record
  6. Beezr → AccountingAlternative: POST /invoices without a required tax code
  7. Accounting ⇢ Beezr422 Unprocessable Content, tax code required
  8. Fix the field mapping before trying again
  9. Beezr → AccountingAlternative: POST /invoices with an expired key
  10. Accounting ⇢ Beezr401 Unauthorized
  11. This fictional provider expires keys; fix the credentials first

These codes have meanings set by RFC 9110. The provider writes its own error text, like “tax code required”.

Code Meaning
201 The request created one or more new resources.
401 The request lacks valid authentication credentials.
422 The server understands the content and its syntax, but can't process its instructions.

Sandline · example

The gloves match; the accounting item doesn't

Hana sees 40 boxes on the approved order. Accounting needs its own item reference, not “nitrile gloves”. Karim maps the product field and checks that quantity still means boxes.

The first try lacks a tax code. Beezr's REST step stops on an error reply by default. The failed attempt leaves no half-posted ledger entry in this example.

Karim fixes the mapping. The reply returns INV-88, which the workflow saves. Hana can now trace the order to its accounting entry.

Mapping means choosing which source value fills each field at the destination. Settle the meaning before the call.

Sandline value Accounting needs Question to settle
Customer Accounting customer reference Does it exist there?
Product NG-200 Accounting item reference Who maintains the catalogue link?
Quantity 40, unit box Quantity in the accounting unit A box or one glove?
Approved order reference Source reference Can Hana trace it back?
Tax treatment Accepted tax code Who maintains this when accounting changes?

Have the person who owns the accounting result review this sheet. A valid request can still describe the wrong purchase. Hana should check before the first live posting.

An order becomes a traceable invoice Northbay Hotels: approved NG-200, 40 boxes. Map customer, item, quantity and tax code. POST /invoices returns 201 and INV-88, saved to the order; a 422 for missing tax code requires correcting the mapping. BeezrNorthbay HotelsNG-200 · 40 boxesApprovedCustomer → referenceNG-200 → item40 boxes → quantityTax treatment → tax codeINV-88POST /invoices201 + INV-88 → save422 → correct tax mapping
An order becomes a traceable invoice Northbay Hotels: approved NG-200, 40 boxes. Map customer, item, quantity and tax code. POST /invoices returns 201 and INV-88, saved to the order; a 422 for missing tax code requires correcting the mapping. BeezrNorthbay HotelsNG-200 · 40 boxesApprovedCustomer → referenceNG-200 → item40 boxes → quantityTax treatment → tax codePOST /invoicesINV-88201 + INV-88 → save422 → correct tax mapping
The round trip needs field meaning and a saved accounting reference.

What is an API key?

An API key is a value that identifies the app calling a service. It doesn't identify the person behind that app. Google's guidance warns that keys obscure end users in audit logs.

The service decides what that app may do.

Think of a staff badge for the connection. A copy works for whoever holds it.

Our rule: keep secret keys out of emails, screenshots and shared documents. Give the owner a safe place to store and replace them.

Google also says to restrict keys. Keep them out of client code and repositories. To rotate one, create its replacement, switch over, then delete the old key.

Each system calling Beezr can have its own key. You can pause one without touching the others. Those keys are separate from the credentials Beezr presents to accounting.

Which connection should Karim choose?

Option Where it fits The catch
Integration Hub action A documented action fits, like QuickBooks Online's create invoice Check its inputs; a connector doesn't cover every vendor operation.
REST API workflow step The API offers the job you need Karim owns mapping, credentials and replies.
Vendor SDK in custom code A developer wants supported libraries and tools The code still needs upkeep and business checks.

Choose the job, then the connection

  • If a connector action fits → start there. Check fields and the returned reference.
  • If only the API offers the operation → use an outgoing REST step. Assign its upkeep.
  • If no suitable operation exists → review other methods. See the integration guide.

What if the reply never comes back?

Accounting might create an invoice, then lose the reply. Beezr sees a timeout. Sending again might create a second invoice.

Our rule: give each invoice you mean to create its own key. Use that same key if you retry.

Before a resend by hand, Karim checks whether the invoice exists. No reply doesn't mean nothing happened.

How Beezr does it

Keep the reply with the work. Save the destination reference and posting status on the record. Workflow run history shows steps, timings and errors. Check both to see what happened to Hana's order.

Myth / Reality

“They have an API, so we’re done.” You still need field meanings, credentials, approval rules and someone to fix failures.

Our take

Our take. Ask who owns tomorrow's failed order. Someone must notice it, fix the cause and judge whether a resend is safe.

Ask the team to show missing tax data and a lost reply. Check where credentials live, who replaces them and where Hana sees the reference.

The store can tell Sandline when an event happens. Shopify webhooks send that notice to an address you subscribe. See what can go wrong in webhooks, APIs and polling.

Key takeaways

  • If you're technical: settle mapping, success and safe retries first.
  • If you're not: ask to see a failed order and its owner.
  • Save the accounting reference so finance can check it.
  • A key grants caller access; approval rules govern business authority.

Connect Sandline's sales order to accounting in Beezr

Build one approved-order path with a visible result.

  1. Prepare Sales Orders with customer, product, quantity and accounting-reference fields.
  2. Add approval before posting, using an approval task.
  3. Set up the call with an Integration Hub connection and action, or mapped REST step.
  4. Save the reply as reference and posting status. Review run errors.
  5. Review REST retries, timeouts and the receiving API's support for an idempotency key.
See how Beezr does itTalk to us

Questions readers ask

API vs SDK: what's the difference?

The API is the menu. The SDK helps a developer use it. Neither decides how your work should flow.

Term Meaning
SDK, software development kit Tools including libraries and debuggers. It often includes an API. See AWS.
What makes an API call safe to retry?

A repeat has the same intended effect as one try. That's what idempotent means.

HTTP rule Detail from RFC 9110
Idempotent methods PUT, DELETE and safe methods such as GET. POST isn't listed.

Don't auto-retry unless you know it's safe. You can also retry if you can tell the first try was never applied. Take this care when creating an invoice with POST.

How does Beezr retry REST calls?
REST setting Behaviour
Connection and reply timeouts Configurable.
Retries Off by default; once enabled, apply to 429 and server errors 500, 502, 503 and 504.

Each try sends the same idempotency key. Does the other side use it to stop repeats? Ask before you rely on it.

What is API integration?

It puts calls into a work process. You match fields and deal with failed calls. A webhook sends an event notice and can use HTTP too. You still need to decide who owns the result.

Sandline Supplies is a fictional example company.

Sources

  1. What is an API? · AWS · undated
  2. OpenAPI Specification v3.1.1 · OpenAPI Initiative · 2024-10-24
  3. RFC 9110: HTTP Semantics · IETF / RFC Editor · 2022-06
  4. Best practices for managing API keys · Google Cloud · undated
  5. SDK vs API · AWS · undated
  6. About webhooks · Shopify · undated

Related guides

Your process, made concrete.

Let's talk

Show us how the work runs today. We'll work through what to build with you.

Talk to us