DEV Community: Rostyslav Havryliuk

A HubSpot app card for the Polish company registry, with plain fetch and no SOAP library

Rostyslav Havryliuk — Mon, 19 Oct 2026 09:17:48 +0000

Every CRM in Poland has the same chore. A sales rep adds a company, opens the public REGON search in another tab, pastes the tax ID (NIP), and copies name, address, REGON and activity codes field by field. Typos included.

I built a small demo that removes that step in HubSpot: a card on the company record with one button, "Pobierz z GUS" (fetch from GUS). It reads the NIP from the record, asks the national REGON registry, shows a diff of what would change, and writes only after the user clicks "Zapisz" (save). The save also leaves a note on the company timeline listing the fields that came from the registry.

A short recording of the flow (manual copying first, then the card) is in the original post: https://polaczone.pl/poradniki/dane-z-gus-w-hubspot-karta-firmy/

This post is about the parts that were not obvious: the registry speaks SOAP 1.2 with MTOM, and HubSpot has opinions about where your backend runs.

Where the backend lives

HubSpot app cards are React components rendered by HubSpot. They cannot call arbitrary URLs. You get two options:

Serverless functions inside the HubSpot project. Since platform version 2026.03 they are back for apps, but an app that contains them can only be installed in an account with an Enterprise subscription. A developer test account works for building, real customers on Free or Starter would not be able to install it.
hubspot.fetch() to your own backend. The URL must be HTTPS and listed in permittedUrls.fetch in the app config (entries are prefixes). HubSpot signs every request and appends portalId, userId and appId to the query string.

The registry made the choice easy. GUS asks for the IP addresses your requests will come from when you apply for a production key, and the session id it returns is only accepted from the IP that created it. A serverless runtime with a random egress IP fights both. So the backend is a small Node service on a VPS with a static IP, behind Caddy, and the card talks to it through hubspot.fetch.

Talking to GUS without a SOAP library

The service is BIR 1.2 (the REGON API). Three calls cover the flow: Zaloguj (log in with the key, get a session id), DaneSzukajPodmioty (search by NIP), DanePobierzPelnyRaport (full report for a REGON, for example BIR12OsPrawna and BIR12OsPrawnaPkd for legal entities). GUS runs a public test environment with a published key, so you can build all of this before you have a production key.

A request is a SOAP 1.2 envelope with WS-Addressing headers. The session id does not go into the envelope, it goes into an HTTP header called sid:

const envelope =
  '<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"' +
  ' xmlns:ns="http://CIS/BIR/PUBL/2014/07" xmlns:dat="http://CIS/BIR/PUBL/2014/07/DataContract">' +
  '<soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">' +
  `<wsa:To>${endpoint}</wsa:To>` +
  '<wsa:Action>http://CIS/BIR/PUBL/2014/07/IUslugaBIRzewnPubl/DaneSzukajPodmioty</wsa:Action>' +
  '</soap:Header><soap:Body>' +
  '<ns:DaneSzukajPodmioty><ns:pParametryWyszukiwania>' +
  `<dat:Nip>${nip}</dat:Nip>` +
  '</ns:pParametryWyszukiwania></ns:DaneSzukajPodmioty>' +
  '</soap:Body></soap:Envelope>';

const res = await fetch(endpoint, {
  method: 'POST',
  headers: { 'Content-Type': 'application/soap+xml; charset=utf-8', sid },
  body: envelope,
  signal: AbortSignal.timeout(10_000),
});

The response is multipart/related (MTOM). You do not need a MIME parser for it: the useful part is the text between <DaneSzukajPodmiotyResult> and its closing tag. That text is an XML document escaped as a string, so you unescape it once and get a flat <root><dane>…</dane></root>, one <dane> block per row. A regex over flat elements is enough here, there is no nesting to speak of.

Things that cost me time:

GetValue is on a different contract. Everything else uses the IUslugaBIRzewnPubl action namespace. GetValue (for example StatusSesji, to check whether the session is still alive) lives on http://CIS/BIR/2014/07/IUslugaBIR/GetValue. Sending it with the public action returns ActionNotSupported.
An empty result is not always "company not found". It can also mean an expired session. When a search comes back empty, ask StatusSesji, log in again if it is 0, and retry once before you tell the user nothing was found.
Postal codes come in two formats. The search returns 00-925, the full report returns 00925.
Names can contain markup. GUS itself warns that names may carry HTML or SQL fragments, so every value is stripped and trimmed before it goes anywhere near a CRM.
Sole traders are a different report. A search row with Typ F is a natural person running a business. The legal-entity report does not apply, the card shows a warning, and the data is treated as personal data.
Status needs dates, not a flag. "Active", "suspended" or "deregistered" is derived from the suspension, resumption, end and deregistration dates in the report.

Verifying HubSpot's signature

hubspot.fetch requests carry X-HubSpot-Signature-v3 and X-HubSpot-Request-Timestamp. The signature is an HMAC-SHA256 over method, full URL, raw body and timestamp, keyed with the app's client secret, base64 encoded. Two details: a specific set of percent-encoded characters in the URL must be decoded before hashing, and requests older than five minutes should be rejected.

const expected = createHmac('sha256', clientSecret)
  .update(method + decodeUri(publicBaseUrl + req.url) + rawBody + timestamp)
  .digest();
const given = Buffer.from(signatureHeader, 'base64');
const ok = given.length === expected.length && timingSafeEqual(given, expected);

The full URL means the public one, including the query parameters HubSpot appended, not whatever your reverse proxy forwards. If verification fails on every request, that is the first thing to check.

The write path

The card never writes on its own. "Pobierz z GUS" calls GET /gus/lookup?nip=…, the backend returns normalized registry data plus the matching HubSpot property values, and the card renders a three-column table: field, current value in HubSpot, value from GUS. Changed rows are bold, the old value is struck through, unchanged rows are muted.

"Zapisz" sends only the changed fields to POST /gus/apply. The backend accepts a fixed whitelist of property names, PATCHes the company through the CRM API, and creates a note associated with it. If the PATCH succeeds and the note fails, the response still says the data was saved, because telling the user "nothing was saved" would make them click again and write twice.

What it does not do yet

The demo covers GUS only. A production integration also pulls the KRS extract for companies (board, capital), CEIDG for sole traders, and the VAT white list. It runs on new companies through webhooks and rechecks existing customers on a schedule. Those parts, the limits and the session rules are written up in more detail in a Polish guide to the REGON API: https://polaczone.pl/poradniki/dane-firmy-z-gus-po-nip-api-bir/

The HubSpot integration itself is described here: https://polaczone.pl/integracje/hubspot-gus-krs/

KSeF: Poland's e-invoicing API will break your store. Here is where

Rostyslav Havryliuk — Wed, 23 Sep 2026 11:22:59 +0000

Poland made B2B e-invoicing mandatory. Biggest companies from 1 February 2026, everyone else from 1 April 2026. Invoices to companies now go through KSeF, a government system. Not a PDF you email. An XML the state accepts or rejects.

Two dates that get lost in summaries. Receiving invoices through KSeF is mandatory for everyone from 1 February 2026, the April deferral covers issuing only. So your purchase invoices have to be pulled from the API earlier than you have to push your own. And until the end of 2026 the smallest sellers can stay outside: invoiced sales of 10,000 zł gross or less per month, lost from the invoice that crosses it. B2C sales and receipts do not count toward that threshold. (dates and legal basis, Ministry of Finance)

I integrate stores and SaaS with this. Here is what actually breaks. Facts below are current as of September 2026, KSeF 2.0 API.

Most of your invoices do not go there

B2C invoices are voluntary. The Ministry says so in its own FAQ. Mandatory means invoices to companies. The trigger is one field: the buyer's tax ID, the NIP. (Ministry FAQ)

Neither Shopify nor Stripe collects it by default. Stripe Checkout has tax ID collection and supports Polish VAT numbers, it is just off unless you turn it on. Shopify exposes tax IDs in B2B and through checkout customisation. Either way somebody has to enable it, map it, and decide what happens when it is missing.

So the first question is not "which API". It is "does our checkout ask for a NIP, where does it land, and what do we do when a customer asks for a company invoice after the order". Answer that first.

Out of scope too: OSS and IOSS, pro formas, internal notes, fiscal receipts with a NIP up to 450 zł until the end of 2026.

Do not call the API per order

The rate limit docs describe an online store as a separate case. The recommendation: collect invoices and send them in batches, for example every 5 minutes. (API limits, CIRFMF/ksef-api)

That answers most limit questions. Numbers as published in September 2026:

1 MB per invoice
10,000 invoices per session
50 ZIP files per batch, 100 MB per package before encryption
interactive sending: 10/s, 30/min, 180/h
over the limit: 429 plus Retry-After, and the block grows if you keep pushing

Limits count per (context, IP). Test runs roughly 10x higher than production, which is why this surfaces after launch. Check the current numbers in that repo before you size anything, they move between API versions.

Also: the retrieval API is for syncing to your database. Polling faster than every 15 minutes gets you blocked. So does fetching invoices one by one instead of using export.

Midnight will flip your invoices into offline mode

If the issue date P_1 is earlier than the day KSeF accepts the file, the invoice becomes "offline24" automatically. You did not set a flag. It just happens. Now you owe a send deadline. (automatic offline mode)

Worse: batch sessions count the moment the session opens, interactive sessions count the moment each invoice is sent. A batch opened at 23:59 saves the day. An interactive one does not.

Run your nightly job at 2am, not at midnight.

Retries create second invoices

KSeF blocks duplicates on three fields: seller NIP, document type, invoice number. Duplicate comes back as 440. Uniqueness holds for ten years. (invoice verification)

This saves you on retries. On one condition: the invoice number must be stable.

Generate the number at send time and a retry makes a new one. KSeF sees two different invoices. Two KSeF numbers. Two live invoices for one order. The only fix is a credit note to zero.

There is no idempotency key in the API. Build it yourself:

persist the invoice number with the order before the first send
store the SHA-256 of the XML, computed before encryption
read the session status before any retry, including the list of rejected invoices

Out-of-order numbering is fine, by the way. The Ministry says so directly. A rejected invoice sent later does not need a correction.

Your queue is not FIFO

A credit note must carry the KSeF number of the original. So a credit note for an offline invoice waits until the original gets its number.

Same-day refunds are normal in e-commerce. Your queue needs that dependency, or it will fail in week one.

Two more:

correction notes are gone since February 2026, everything goes through the seller
there is no cancel; wrong buyer NIP means credit note to zero and a new invoice

Rejected means it never existed

No invoice, no number, nothing in the records. You cannot correct it. You send a fixed file.

In your system the order looks invoiced. The customer waits for a document that does not exist. If rejections only go to a log, nobody notices for a week. Send them to a human.

KSeF checks the schema, UTF-8 without BOM, the issue date not being in the future, the NIP checksum (production only, so this one survives your tests), sizes and hashes.

It does not check your math. Wrong totals get accepted.

Offline modes: one flag, four deadlines, and two QR codes

Mode	Triggered by	Send by
offline24	you, no reason needed	next business day
unavailability	KSeF	next business day after it ends
failure	KSeF	7 business days after it ends
total failure	minister	no obligation

The mode itself is one boolean in the request. The deadline math is yours.

The part that is not one boolean is the visualisation. Any invoice used outside KSeF needs a QR code, and an offline invoice needs two: KOD I, which encodes the verification URL, issue date, seller NIP and a hash of the file, and KOD II, which proves you issued it, and which has to be signed with a KSeF certificate. Once the invoice reaches KSeF, you are back to one code with the KSeF number under it. (QR codes)

So offline support means: requesting and storing a certificate, signing locally, and rendering one or two codes depending on state. Budget for it separately.

In 2026 the Ministry did not declare a single KSeF failure. Go-live pain was in the national login services.

Small stuff that eats a day

buyer NIP in the wrong field means the buyer never sees the invoice, even though it was accepted
the KSeF number is 35 chars with a checksum, validate it locally
the XML is the invoice, the PDF is a picture of it
access tokens live minutes, the auth challenge expires in 10
product names go into XML as they are, so your HTML entities will break the file

The currency trap

There was supposed to be a KSeF-specific exchange rate rule. It was repealed before it came into force. The general rule still applies.

But the consolidated text of the VAT act was published before the repeal, so the dead rule is still printed there as future law. Plenty of articles repeat it.

If someone shows you a "new KSeF rate rule", check their date. And confirm your case with a tax advisor, not with a blog post.

Penalties

Statutory start is January 2027. In September 2026 the Ministry announced a deferral to the end of 2027, and that announcement says a law still has to be written. (Ministry announcement, 16 September 2026)

So: not a fact yet. The obligation to use KSeF was never deferred.

If you are an agency outside Poland

A Polish VAT number alone does not put your client in scope. What matters is a seat or a fixed establishment in Poland taking part in the transaction. The Ministry published guidance on that in January 2026 and still asks for case-by-case assessment.

Budget it as real work: collect a NIP, keep numbers stable, own a queue with retries and dependencies, surface rejections, handle offline QR, write the KSeF number back to the order.

If you are wiring a Shopify, WooCommerce or Stripe setup to KSeF and you hit one of these, write to me and I will tell you what it takes: polaczone.pl. The Polish version of this guide, with the same sources, is here.