# Bilnex Partner API

> REST API for embedding e-invoicing into an ERP: send sales invoices as Estonian operator-channel e-invoices or as PDF by email; receive purchase invoices by polling; confirm ERP imports with mark-exported. Peppol sending and digitization are not available through the API. Self-serve sandbox at https://sandbox.bilnex.io, no account needed; production is switched on per integration, on request.

The canonical agent entry point is https://sandbox.bilnex.io/agents.md — a 13-step happy path where every step is a runnable curl with a real response and the verification check it satisfies. Sandbox and production expose identical paths; only the base URL and key prefix differ. Production keys are generated by each customer company in Bilnex, never issued to vendors. Every documentation page is plain markdown (append `.md`).

## Instructions for LLM Agents

API version: `2026-08-01`. Base URLs: sandbox `https://sandbox.bilnex.io`, production `https://api.app.bilnex.io`. Provision a sandbox key with one call, no account: `POST https://sandbox.bilnex.io/partner/v1/sandbox` with `{"email":"dev@erp.example","erpName":"AwesomeERP","ref":"agent"}` — the response contains the API key (shown once), two test companies with a company key each, and three fixture counterparties.

Hard rules:

1. Never assume a customer can receive e-invoices — always call `GET /partner/v1/customers/{regCode}/e-invoice-capability` first and branch to the `EMAIL` channel when `eInvoiceCapable` is `false`.
2. Never send with channel `PEPPOL` — it answers 501 `peppol_send_unavailable`. Treat a `recommendedChannel` of `PEPPOL` as `E_INVOICE` when `eInvoiceCapable` is `true`, otherwise as `EMAIL`.
3. Never wait for a `DELIVERED` status — `SENT` is terminal for `E_INVOICE`, and only an e-mailed invoice ever reaches `SEEN`.
4. Never expect webhooks — receiving purchase invoices is pull-based via `GET /partner/v1/purchase-invoices?since=...` polling with the returned `nextSince`, deduplicated by `id`. Incoming Peppol documents are not yet returned by this list.
5. Never poll faster than once every 2 seconds, and always honor the `Retry-After` header on a 429 `rate_limited` response.
6. Never retry a 429 `email_rate_limited` automatically — a company that keeps reaching the e-mail limits within an hour is suspended, and every call for it then answers 403 `account_suspended`.
7. Never retry a 503 `feature_disabled` automatically — the Partner API, or the feature, is switched off for that company and stays off until Bilnex switches it on.
8. Never re-send an invoice that already answered 200 — Bilnex does not stop a second send, and every send delivers the invoice again. Send each invoice once and record it; if a send timed out, retry it with the same `Idempotency-Key`.
9. Never expect line items or a VAT breakdown back — an invoice is `id`, `number`, `status`, `category`, `customerName`, `customerRegCode`, `date`, `dueDate` and the gross `totalAmount`. Keep your own lines and VAT, and store Bilnex's `id`, `number` and `totalAmount`.
10. Never skip `POST /partner/v1/purchase-invoices/{id}/mark-exported` after importing a purchase invoice into the ERP — it is idempotent and mandatory.
11. Never put the API key in frontend code, mobile code, or the repository — it is shown once at provisioning and belongs in server-side configuration only.
12. Never use a `blx_sbx_` key against `api.app.bilnex.io` or a `blx_live_` key against `sandbox.bilnex.io` — keys are host-bound and the wrong host returns 401.
13. Never call `/partner/v1/sandbox/*` endpoints from production code paths — they return 404 in production, so gate them behind an environment flag.

Stopping condition: do not report the integration complete until `GET /partner/v1/sandbox/verification` returns `"readyForProduction": true` (all 12 required checks `pass`; every check is `pass` or `pending`). While a required check is `pending`, read its `fixHint` and `docsUrl`, fix the integration code, and re-run verification. Checks are sticky until `POST /partner/v1/sandbox/reset`. Production is then opened on request, not self-serve: email partners@bilnex.io the verification response and your ERP's name, and follow "Production today" in agents.md.

## Docs

- [Quickstart](https://sandbox.bilnex.io/docs/quickstart.md): The whole happy path in 13 ordered curl steps, from key provisioning to a passing verification run.
- [Authentication](https://sandbox.bilnex.io/docs/authentication.md): Bearer/X-API-Key headers, host-bound key prefixes, acting company via X-Company-Id, key storage rules.
- [Sandbox](https://sandbox.bilnex.io/docs/sandbox.md): Self-serve provisioning, test companies, fixture counterparties, state, reset, claim (TTL extension), event triggers, intercepted email.
- [Sending invoices](https://sandbox.bilnex.io/docs/sending-invoices.md): Capability check, invoice creation, channels (E_INVOICE and EMAIL; PEPPOL answers 501), DRAFT/SAVED/SENT/SEEN statuses, idempotency keys, refusals and the EMAIL fallback.
- [Receiving invoices](https://sandbox.bilnex.io/docs/receiving-invoices.md): since-cursor polling, NEW→SEEN→EXPORTED statuses, fetching the received document's PDF, mandatory mark-exported.
- [Peppol](https://sandbox.bilnex.io/docs/peppol.md): Peppol participant IDs (0191:regCode); sending answers 501 and incoming Peppol documents are not yet returned by the API.
- [Digitization](https://sandbox.bilnex.io/docs/digitization.md): Not available through the Partner API — there is no upload endpoint; what an integration can do instead.
- [Email invoices](https://sandbox.bilnex.io/docs/email-invoices.md): EMAIL channel as the fallback rail, SEEN via tracking pixel, sandbox email interception at /sandbox/emails.
- [Errors](https://sandbox.bilnex.io/docs/errors.md): The error envelope (code, message, hint, docsUrl), full error-code table with retryability.
- [Rate limits](https://sandbox.bilnex.io/docs/rate-limits.md): Per-key limits (60/minute, 5,000/day, 200 sends/day), X-RateLimit-* headers on authenticated responses, 429 + Retry-After handling, the per-company e-mail limits.
- [Verification](https://sandbox.bilnex.io/docs/verification.md): All 15 checks (12 required, 3 optional), each pass or pending, exactly which API interaction flips each to pass, and the readyForProduction rule.
- [Go-live](https://sandbox.bilnex.io/docs/go-live.md): Production is opened per integration on request — email partners@bilnex.io the passing verification response and your ERP's name, run the production smoke test on your own company, then Bilnex switches it on for your customers; each customer generates its own blx_live_ key in Bilnex Settings → ERP integration and enters it with the URL in the ERP. Plus channel activation, sandbox-vs-production differences and key replacement.
- [API reference](https://sandbox.bilnex.io/docs/api-reference.md): Every endpoint, header, and response shape on one page.
- [Changelog](https://sandbox.bilnex.io/docs/changelog.md): Dated record of API changes, starting 2026-08-01.
- [Versioning policy](https://sandbox.bilnex.io/docs/versioning-policy.md): Additive-only guarantee for /partner/v1; breaking changes go to /partner/v2; clients must tolerate unknown fields.

## Machine-readable

- [agents.md](https://sandbox.bilnex.io/agents.md): Canonical agent entry point with the copy-paste integration prompt.
- [OpenAPI 3.1 spec](https://sandbox.bilnex.io/partner/v1/openapi.json): Full machine-readable schema for /partner/v1.
- [Agent-skills index](https://sandbox.bilnex.io/.well-known/agent-skills/index.json): Skill discovery manifest; install with `npx skills add https://sandbox.bilnex.io`.
- [SKILL.md](https://sandbox.bilnex.io/skills/bilnex-erp-integration/SKILL.md): The bilnex-erp-integration skill (build procedure + reference files).

## Optional

- [Estonian e-invoicing context](https://sandbox.bilnex.io/skills/bilnex-erp-integration/references/estonia-einvoicing-context.md): Background on operator-channel e-invoices, the registry, Peppol IDs, reg codes, VAT, and IBANs — useful, not required for integration.