DEV Community: BeeL.

Designing an API when half your users are agents

BeeL. — Tue, 28 Jul 2026 08:30:00 +0000

A growing share of the traffic hitting our API isn't typed by anyone. Not scripts either — agents: a model reading the docs, writing an integration, calling endpoints to check its own work, and retrying whenever something comes back ambiguous.

Most of that is fine. What it exposes is your defaults, and a lot of ours turned out to have been chosen casually.

The stakes are unusually literal in our case, because our writes are permanent by law. This is an invoicing API for Spain: every production invoice becomes a fiscal record, hashed and chained to the one before it and submitted to the tax agency. You can't delete one. You can only issue a second record stating the first was wrong, and that one is permanent too.

So we spent a while rethinking the surface for a caller that never gets tired. Most of what came out has nothing to do with tax.

Agents don't make mistakes once

A developer who runs the wrong command feels it immediately, stops, and thinks. An agent that runs the wrong command has already run it eleven more times while it works out what the error message meant. Whatever your worst-case single call is, an agent will find it and multiply it.

So the first thing we did was make the dangerous environment opt-in rather than default. Our CLI runs against sandbox unless you pass --live. And crucially, a live key in the environment doesn't quietly upgrade you:

export BEEL_API_KEY=beel_sk_live_...
beel invoices issue inv_123          # error, not a silent production write
beel invoices issue inv_123 --live   # explicit

That error looks unhelpful if you read it as a human. It's exactly right if you read it as an agent, because the agent's next move is to reason about the flag rather than to discover afterwards that it filed forty invoices with the tax agency.

The same logic pushed us to attach an Idempotency-Key to every POST automatically. Retrying is what agents do when something looks ambiguous, and they retry faster than a human can intervene.

Machine-readable errors beat readable ones

Prose errors are a trap. An agent parsing "something went wrong, please check your configuration" will guess, and its guess will be confident.

We ended up with two channels. Data goes to stdout as JSON, so it pipes into jq. Errors go to stderr, also as JSON, carrying a code, a message, an HTTP status and a request ID. On top of that, exit codes are typed by class rather than being 0-or-1:

Exit code	Meaning
`0`	Success
`2`	Usage or config error
`3`	Auth
`4`	Not found
`5`	Validation
`6`	Rate limit
`7`	Server error

The distinction that matters is between "retry this" and "stop, you're wrong". A 6 means back off. A 5 means the payload is wrong and hammering it will never help. Collapsing both into 1 is what produces those loops where an agent tries the same broken request twenty times.

Don't make the model guess your surface

The usual failure mode with tooling is a hand-maintained command list that drifts from the actual API. An agent reads it, believes it, and calls something that no longer exists.

Our commands are derived from the OpenAPI spec at build time, and there's one command that dumps the whole surface as JSON:

beel commands            # { command, signature, description, method, path } for everything
beel invoices create --help

One call, whole API, no scraping of help text. And because the spec is bundled with the installed version rather than fetched live, there's an obvious hole: an endpoint newer than your CLI. So there's a generic escape hatch that doesn't pretend otherwise.

beel request POST /v1/customers --data @customer.json

We've come to treat an escape hatch as a requirement rather than a nicety in agent tooling. The alternative is a model that concludes something is impossible because a wrapper hasn't caught up.

Plugins go stale, which makes agents confidently wrong

We ship a Claude Code plugin. The obvious version of that is to bake the API reference into the plugin, and the obvious version is wrong: the day you publish it, it starts decaying, and a stale reference is worse than no reference because it reads authoritative.

What's local now is only the part that doesn't change: authentication, idempotency, the response envelope, the invoice lifecycle. Endpoints, schemas and event names get fetched from the docs at the moment they're needed. We publish /llms.txt and /llms-full.txt for exactly that, plus the raw OpenAPI spec.

The split turns out to be a decent rule of thumb. Invariants can live in the tool. Anything with a version number should be fetched.

There's a related detail we like more than it probably deserves: beel docs search downloads the docs once, caches them, and filters on your machine. The agent gets the matching section, and the query — which often contains the shape of whatever the user is building — never reaches our servers.

Verification is the whole game

The part that changed our defect rate wasn't the docs. It was that an agent can prove an integration works before anyone ships it.

npx @beel_es/cli invoices create --data @invoice.json
npx @beel_es/cli invoices get <invoice_id>

With a test key, a model can create invoices, trigger the resulting events, and confirm a webhook receiver actually handles them, all against a sandbox that's free and unlimited. No throwaway scripts, no "looks right to me" as the last check before production.

That's the argument for a free, unlimited, genuinely complete sandbox that we'd underrated: it isn't a generosity feature, it's the thing that lets an automated caller close its own feedback loop.

The part I'd take to any API

If you're building something an agent might call, the questions worth asking are pretty small in number. Can a single call do irreversible damage, and is it reachable by default? Can a caller distinguish "retry" from "stop" without reading English? Can it discover your surface in one call? And can it verify its own work somewhere that doesn't count?

We had to answer those because our writes are permanent by law. Most APIs get to answer them because a customer will otherwise wake up to a mess. The list is the same either way.

If you want to see how any of it is wired up, the docs are at docs.beel.es, sandbox included. And we'd like to hear how other teams are handling the retry-loop problem in particular — it's the one we're least confident we've solved.

What Spain's Verifactu law actually does to your backend

BeeL. — Mon, 27 Jul 2026 15:50:42 +0000

Spain is putting a hash chain behind every invoice, and almost everything written about it so far has been written for accountants. This is the version for whoever has to ship it.

The deadlines are January 1, 2027 for companies and July 1, 2027 for sole traders. If you read something last year that said 2026, that was true until RD-ley 15/2025 moved the whole calendar back twelve months. Software vendors have been on the hook since July 2025, which is a detail worth holding on to if you sell a product that issues invoices for other people.

At BeeL., we sell an API for this, so read the rest with that in mind.

The requirement

Each invoice your software issues has to produce a registro de facturación de alta: a record containing a defined set of fields, hashed with SHA-256, where the hash of each record folds in the hash of the one before it. One chain per issuing tax ID, growing forever, never edited.

Cancelling an invoice is not a delete. It's a second record type, a registro de anulación, which goes into the same chain. Same for corrections, which come in two flavours depending on whether you're amending a difference or replacing the original document. The printed invoice carries a QR code with verification data, plus the string VERI*FACTU if you're in submitting mode.

Then you either push each record to the tax agency as it happens, or you keep everything locally under stricter signing and retention rules and hand it over when asked.

Written down like that, it reads like an afternoon of work. A hash function, a previous_hash column, an HTTP call.

Where the estimate falls apart

The chain is strictly sequential, so two workers issuing invoices for the same tax ID at the same time are racing for the same link. You need a lock per issuer, or a queue, or both, and either way concurrent issuance stops being free.

Retries are worse than they look. A failed submission that you retry carelessly either duplicates a record or breaks the chain, and a broken chain isn't something you fix with a migration script. It's a tax record. The recovery path is procedural, not technical.

The transport is a different era of software. XML over web services, digital certificates, environments that go down, error codes you have to classify as retryable or terminal before you can write sensible handling.

The edge cases are most of the work: multiple VAT rates on one invoice, exemptions, non-subject operations, recargo de equivalencia, intra-community customers, tax ID validation, invoice series.

And if you're a platform issuing on behalf of your customers, none of the above is singular. You have one chain per client tax ID, each with its own certificate, its own state, its own stuck submissions at 3am.

One more thing that surprises people: article 201 bis of the general tax law doesn't only point at the business issuing invoices. A vendor selling non-compliant invoicing software is looking at up to €150,000 per year per product. If your SaaS issues invoices for third parties, you are that vendor, whether or not it says so anywhere in your positioning.

Three ways out

You can build it yourself against the tax agency. Full control, no per-invoice cost, and a multi-month project followed by permanent maintenance every time a spec changes. Worth it if invoicing is your product rather than a thing your product has to do.

You can put an off-the-shelf invoicing tool in the loop. Fine when the volume is low and a human is doing the clicking; awkward when your backend needs to emit thousands of invoices a month without anyone opening a browser.

Or you can hand the fiscal part to an API and keep a POST in your own code. You trade work for a dependency, which is the same trade you already made for payments.

What the third option looks like

import { BeeL } from '@beel_es/sdk';

const beel = new BeeL({ apiKey: process.env.BEEL_API_KEY });

const invoice = await beel.invoices.create({
  customer: {
    nif: 'B12345678',
    name: 'Cliente SL',
    email: 'facturas@cliente.es',
  },
  lines: [
    { description: 'Pro plan, July 2026', quantity: 1, unitPrice: 49.00, taxRate: 21 },
  ],
});

Hashing, chaining, QR generation and submission happen behind that call, and the resulting state arrives on a signed webhook. If you already bill through Stripe, the charge itself can be the trigger, so there's even less of your code involved.

Test keys are prefixed beel_sk_test_ and the sandbox has no limits, so the whole flow is buildable before anyone pays anything.

Three things Verifactu is not

It isn't the B2B e-invoicing mandate from the Crea y Crece law. Different regulation, different timeline, and complying with one does nothing for the other.

It doesn't cover the whole country the same way. The Basque Country and Navarre run on their own regional rules, TicketBAI among them.

And it isn't SII. If you're already reporting VAT through Suministro Inmediato de Información, your obligations differ.

Why 2026 is the good year to do this

Right now, submitting is voluntary. You can integrate, keep the chain clean from invoice number one, and debug in an environment where nothing you get wrong is a sanctionable event.

The alternative is doing it next December, at the same time as everyone else who waited, with every vendor's support queue full.

If you're somewhere in this already, I'm curious how you're issuing invoices today and what's blocking you. The sandbox at beel.es doesn't ask for a card if you want to poke at it first.