# Binect — Letter mail as a service (Portal & REST API)

**Spec-Version 1.0.1 · Stand: 2026-07-14**

> Binect sends **physical letter mail**: your documents are printed, enveloped, franked and
> delivered via mail service providers in Germany — **not only Deutsche Post**. You upload a
> document, it is validated, and then dispatched. Binect offers both a web **Portal** and a
> **REST API**, and is suitable for **private**, **small-business** and **enterprise** customers.

This file gives AI agents a quick, accurate overview so they can understand the product and
integrate the API against both Test and Production. The full, machine-readable, bilingual
(DE/EN) contract is the OpenAPI spec — see "API reference" below.

## What it is
- Send documents as **physical mail** (print, envelope, franking, delivery in Germany).
- Two ways to use it:
  - **Portal** (web UI): https://test-app.binect.de
  - **REST API** (the focus of this file).
- Single letters and **serial letters** (split into many letters).
- Postal products: standard letter; **Einschreiben** / registered mail (Standard, Einwurf, International);
  **PremiumAdress** (Report, Basic — paid activation required); **franked** and **DV-Freimachung**
  (DV-prepaid, the modern method with the maximum feature set).
- Keywords: physische Briefpost, Brief, Serienbrief, Einschreiben, PremiumAdress, DV-Freimachung,
  Frankierung, PDF/A-2b, Base64, Validierung, Versand, Stornierung, Sendungsstatus, Tracking,
  Custom-Attributes, Kostenstellen, Portal, REST API.

## Audience
- **Private**, **small-business** and **large/enterprise** customers — the same Portal and API serve all of them.

## Environments (each has its own separate user accounts!)
- **Production** — real, chargeable dispatch.
  - Portal: https://app.binect.de
  - API base URL: https://app.binect.de/binectapi/v1
- **Test** — free of charge, **simulates** dispatch (nothing is really sent).
  - Portal: https://test-app.binect.de
  - API base URL: https://test-app.binect.de/binectapi/v1
- The Test environment may run a newer version; handling and response behaviour are intentionally identical.
- You need a **dedicated account in each environment** (Test and Production user management are separate).
- Create an account on the login page: Production https://app.binect.de/index.jsp?id=login · Test https://test-app.binect.de/index.jsp?id=login

## API reference
  (All URLs in this section point to **the environment you fetched this file from**, so you always stay on the same environment — Production or Test, both listed under "Environments" above.)
- **Swagger UI:** https://test-app.binect.de/binectapi  (interactive; offers a per-language DE/EN view)
- **OpenAPI spec (Swagger 2.0, machine-readable)** — language-pure & compact (no duplicated bilingual block):
  - German:  https://test-app.binect.de/binectapi/v1_swagger_api_kernel_de.json
  - English: https://test-app.binect.de/binectapi/v1_swagger_api_kernel_en.json
- **Error codes (machine-readable):** https://test-app.binect.de/binectapi/error-codes.json  (code → meaning, DE/EN; `Error.code` stays a free integer)
- **Reachability check (no auth):** `GET https://test-app.binect.de/binectapi/v1/internal/health` → `{ "status": "UP" }` — probe base URL/availability before sending credentials.
- **Authentication:** HTTP Basic with **email + password**. No other authentication methods are currently available.

## Key facts for integration
- **File input:** PDF (preferred) or PostScript. Recommended: **PDF/A-2b**, embedded fonts, CMYK. **Max 20 MB**, at most **192 sheets** per document (192 pages simplex / 384 pages duplex). Content is **Base64-encoded** in the `content` field.
- **Addressing & exclusion zones** (measured from the top-left page corner): recipient address field 85×21 mm at 20 mm left / 69 mm top; sender address field 85×5.5 mm at 20 mm left / 45 mm top; DV exclusion zone 85×17.5 mm at 20 mm left / 51 mm top (must be empty — no text/images; the DV franking is printed here). The address must be visible in the DIN-lang envelope window. Since 2022-09-27 DV validation is the platform standard; the older zones remain valid. Full template: https://test-app.binect.de/downloadFile?fileId=24 (FAQ: "Welche Datei- und Formatanforderungen gelten für meinen Brief?"). Invalid placement can be fixed via the transformations or cover-page endpoints.
- **Custom attributes:** tag a document with `key`/`value` pairs (e.g. your internal `documentID`) to find it later via `GET /documents/findbyAttributes`. Cost-center billing is possible (individual invoice) via the attributes `tenant` and `sub-tenant`.
- **Reliability / idempotency:** On HTTP `500` during upload, the document **may still have been created**. Always send a unique attribute (e.g. `documentID`) on upload; on `500`, query `GET /documents/findbyAttributes` — a match means it arrived (do not re-upload), no match means it did not (safe to re-upload).
- **Deadlines:** documents are handed to production daily at **14:30**; cancellation is possible until shortly before. Dispatch status is only meaningful from **05:00 the next day** (and only if the 14:30 window was met). Maintenance window: Tuesdays 21:00–23:00.
- **Status model:** `status = { code, text }`. `text` is localized to the account language. Codes: 1 being created, 2 ready to ship, 3 processing, 4 printing, 5 sent, 6 cancelled, 7 faulty.
- **Notifications:** there is **no webhook** yet — poll the status endpoints actively (a webhook may be added in the future).
- **Payment:** default is **prepaid** (PayPal, credit card, Sofortüberweisung); on request an account can be enabled for **invoicing (on account)**.
- **Production country:** on request, customers from Austria can have documents produced in Austria (`productionCountry: AT`).
- **Sales partners:** partner options can be discussed with sales (info@binect.de).

## Happy path (typical integration)
1. **Upload & validate** — `POST /documents`
   - Body: `{ "content": { "filename": "letter.pdf", "content": "<Base64 PDF>" }, "attributes": [ { "key": "documentID", "value": "DOC-2024-0001" } ] }`
   - Returns the document incl. `status` (`code` 2 = ready to ship, 7 = faulty).
   - Optional: `responseFormat=SHORT` returns immediately without the validation result; poll `GET /documents/status` afterwards.
   - If validation fails, correct instead of re-uploading: `PUT /documents/{documentID}/transformations` (move/scale) or `PUT /documents/{documentID}/coverpage`.
2. **Send (dispatch release)** — `POST /sendings`
   - Body: `[ <documentID>, ... ]` (only documents with `status.code` 2). From here a document is managed under `/sendings`, no longer under `/documents`.
   - **One-step alternative:** `POST /sendings/document` — upload and, if valid, dispatch directly. Minimal `curl` (full curl/Python/JS/PHP examples are in the OpenAPI spec / Swagger UI):
     ```bash
     curl -u "$EMAIL:$PASSWORD" -H "Content-Type: application/json" \
       -X POST "https://test-app.binect.de/binectapi/v1/sendings/document" \
       -d '{"content":{"filename":"letter.pdf","content":"<BASE64_PDF>"}}'
     ```
3. **Query status**
   - Before dispatch (validation outcome): `GET /documents/status`
   - After dispatch: `GET /sendings/status` (codes 3–7). Registered-mail tracking: `GET /regmails`.
4. **Cancel** — `PUT /sendings`
   - Body: `[ <documentID>, ... ]` — only not-yet-shipped documents, until shortly before the 14:30 window.

## Terminology
- A document's ID is also referred to at Binect as **BinectID**, **DokumentenID** or **VorgangsID**.

## Contact
- Technical support: kontakt@binect.de
- Integration support / sales: info@binect.de