HubSpot + SAP Business One integration

Business One is the ERP that small manufacturers and distributors grow into and then never leave. It is usually installed rather than subscribed, it usually runs on a server managed by the SAP partner who sold it, and the person who understands it best often works for that partner rather than for you. All three of those facts shape this project more than the API does.

The business problem is ordinary. Sellers want to know what an account has ordered, what is still open and whether the last invoice was paid, without phoning the office. Operations wants the sales team to stop promising delivery dates that ignore what is actually on order. Neither group is going to get a Business One client licence, so the information has to move to where they already work.

What makes the project unusual is access. The Service Layer runs on the company’s own server on a port, and the hosting partner decides whether that port is reachable from outside. Sometimes the answer is yes and the project is a straightforward keyed sync. Often the answer is no, and no amount of architecture argument changes it. Scoping this system starts with one question asked of the right person: can we reach the Service Layer, and if not, what can you schedule instead. Every later decision follows from the answer.

Five objects do the work. Business partners become HubSpot companies, the contact people hanging off each partner become HubSpot contacts, sales orders become deals, invoices land on a custom object and items become products.

Everything moves one way. Business One is the system of record for the customer and for every document in the chain, and a portal that can edit a posted invoice is a liability rather than a feature. Where a write back is genuinely needed, it belongs in a second phase with its own review step.

Keys come from the document, not the name. Business partners key on the partner code, orders and invoices on the document number, items on the item code. One extra rule matters here and catches people out: a Business One installation can hold more than one company database, and document numbering restarts in each one. The key is therefore the document number scoped by the company database, never the number alone, or two companies will overwrite each other’s orders.

Two shapes, chosen by what the host allows.

Where the Service Layer is reachable, a service authenticates with a Login call carrying the company database, a user name and a password. SAP documents no HTTP Basic header here. The call returns a session identifier and sets a session cookie, the session times out, and a Logout call ends it, so the service renews rather than assuming it survives. It then reads each entity set on a schedule and upserts into HubSpot as batches keyed on the document identifiers, followed by a separate association pass. State is a watermark per entity held by the service, so a restart resumes rather than reloads.

Where it is not reachable, the same service reads files instead. The host schedules an export to an SFTP drop, one file per object plus a manifest of row counts. The load service collects each file, hashes it so a repeated drop is ignored, validates the rows, quarantines the ones that fail with a readable reason, and runs the same batch upsert and association pass as the API route. The manifest is the reconciliation: rows loaded against rows exported, reported every run rather than checked when somebody complains.

The deciding factor is whether you can get an API route at all, and who has to agree to it, rather than budget or object count.

If the Service Layer is open, a service we build gives you the freshest data and the most control, and it is the only route that can write anything back later. If it is closed, a scheduled export feeding a load service gives you the same object model a day behind, and it needs nothing from the host except a job and a file drop.

The third route is a third-party connector from the marketplace. It suits a standard mapping and a team that wants nobody on call, at the cost of owning neither the runtime nor the roadmap. What we steer away from is a general purpose automation platform: it still needs the same firewall exception, and it bills per task once it has it.

1. Scope. The first call includes whoever hosts the system. We establish the release, whether the Service Layer is reachable, how many company databases exist and what can be scheduled.
2. Architect. We fix the object list, the keys, the delete signal and the file format, and write them down as a contract the hosting partner can implement.
3. Build. The load service is written against sample exports and a test company, with a portal allowlist in place from the first commit.
4. Validate. We reconcile counts and open order totals against a Business One report, then walk the differences with the operations lead.
5. Operate. We watch every run against its manifest, keep the replay endpoint available, and re-agree the export whenever Business One is upgraded.