generated from coulomb/repo-seed
tegwick
b9aebb42f1
SDK (@binect/js): - BinectClient with domain sub-clients (documents, sendings, accounts, attachments, invoices) - HTTP Basic Auth, native fetch only (no runtime dependencies) - TypeScript types matching Binect API vocabulary - Status predicates and polling helpers in helpers.ts - Structured error handling (BinectApiError, BinectAuthError) Explorer: - Standalone browser-based API explorer (explorer/index.html) - Interactive testing without code Tests: - Unit tests for client, types, errors, helpers, http - E2E tests for upload/delete and send/cancel workflows Also includes: - Architecture Decision Records (ADRs) - Example DIN 5008 letter PDFs for testing - API specification research notes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
116 lines
4.3 KiB
Markdown
116 lines
4.3 KiB
Markdown
# Binect API REST Specification
|
||
|
||
**Source:** https://app.binect.de/binectapi/v1_swagger_api_kernel.json
|
||
**Retrieved:** 2026-01-14
|
||
|
||
## Overview
|
||
The Binect API (v0.9.9) is a letter shipping service that handles document upload, validation, processing, and Deutsche Post delivery. The API uses HTTP Basic Authentication and HTTPS exclusively.
|
||
|
||
## Base Configuration
|
||
- **Base Path:** `/binectapi/v1`
|
||
- **Host:** `app.binect.de`
|
||
- **Scheme:** HTTPS only
|
||
- **Authentication:** HTTP Basic Auth (required for all endpoints)
|
||
- **Contact:** kontakt@binect.de
|
||
|
||
## Core Endpoints
|
||
|
||
### Documents Management
|
||
**Upload & Retrieve:**
|
||
- `POST /documents` – Upload letters/serial letters with base64-encoded content
|
||
- `GET /documents` – List shippable documents (status 2)
|
||
- `GET /documents/errors` – List erroneous documents (status 7)
|
||
- `GET /documents/{documentID}` – Fetch specific document
|
||
- `DELETE /documents/{documentID}` – Remove document
|
||
|
||
**Document Attributes:**
|
||
- `GET /documents/{documentID}/attributes` – Get all attributes
|
||
- `POST /documents/{documentID}/attributes` – Set attributes
|
||
- `GET /documents/{documentID}/attributes/{key}` – Get specific attribute
|
||
- `PUT /documents/{documentID}/attributes/{key}` – Update specific attribute
|
||
- `DELETE /documents/{documentID}/attributes/{key}` – Delete specific attribute
|
||
|
||
**Document Modifications:**
|
||
- `PUT /documents/{documentID}/transformations` – Apply scaling/offset adjustments
|
||
- `DELETE /documents/{documentID}/transformations` – Revert to original
|
||
- `PUT /documents/{documentID}/coverpage` – Add cover page
|
||
- `DELETE /documents/{documentID}/coverpage` – Remove cover page
|
||
- `GET /documents/{documentID}/pdf` – PDF preview
|
||
- `GET /documents/{documentID}/png` – PNG preview
|
||
|
||
**Attachments on Documents:**
|
||
- `GET /documents/{documentID}/attachments` – Get document attachments
|
||
- `POST /documents/{documentID}/attachments` – Add attachment to document
|
||
- `PATCH /documents/{documentID}/attachments` – Update attachments
|
||
- `DELETE /documents/{documentID}/attachments` – Remove attachments
|
||
|
||
### Sendings (Shipments)
|
||
- `POST /sendings` – Announce documents for delivery
|
||
- `GET /sendings` – List all shipments (statuses 3-7)
|
||
- `PUT /sendings` – Cancel unshipped letters
|
||
- `POST /sendings/{documentID}` – Trigger single shipment
|
||
- `GET /sendings/{documentID}` – Get specific sending
|
||
- `PUT /sendings/{documentID}` – Cancel specific sending
|
||
- `DELETE /sendings/{documentID}` – Delete sending
|
||
- `POST /sendings/document` – Upload and immediately send
|
||
- `GET /sendings/status` – Batch status check
|
||
|
||
### Attachments (Standalone)
|
||
- `POST /attachments` – Upload attachment
|
||
- `GET /attachments` – List all attachments
|
||
- `GET /attachments/{attachmentID}` – Get specific attachment
|
||
- `DELETE /attachments/{attachmentID}` – Delete attachment
|
||
- `GET /attachments/{attachmentID}/pdf` – Preview attachment PDF
|
||
- `GET /attachments/{attachmentID}/documents` – Find associated documents
|
||
- `PATCH /attachments/{attachmentID}/documents` – Attach to multiple documents
|
||
|
||
### Account Management
|
||
- `GET /accounts` – Retrieve credit/financial data
|
||
- `GET /accounts/personaldata` – Get user details
|
||
- `PATCH /accounts/personaldata` – Update user details
|
||
- `GET /accounts/options` – Get default print options
|
||
- `PUT /accounts/options` – Update default print options
|
||
- `GET /accounts/coworkers` – List team members
|
||
- `GET /accounts/coworkers/{debitornumber}/journal/{month}` – Coworker transactions
|
||
- `GET /accounts/journal/{month}` – Account transactions
|
||
|
||
### Invoicing
|
||
- `GET /invoices` – List all invoices
|
||
- `GET /invoices/{invoiceNumber}` – Fetch invoice transactions
|
||
- `GET /invoices/{invoiceNumber}/pdf` – Download invoice PDF
|
||
|
||
## Key Data Models
|
||
|
||
### Document Status Codes
|
||
- 1: In preparation
|
||
- 2: Shippable
|
||
- 3: Production queue
|
||
- 4: Printing
|
||
- 5: Sent
|
||
- 6: Canceled
|
||
- 7: Erroneous
|
||
|
||
### Envelope Options
|
||
- DINLANG
|
||
- C4
|
||
|
||
### Franking Types
|
||
- UNSPECIFIED
|
||
- STANDARD_FRANKING
|
||
- DV_FRANKING
|
||
|
||
### Production Countries
|
||
- UNSPECIFIED
|
||
- DE
|
||
- AT
|
||
|
||
### Response Format Options
|
||
- FULL (default): Complete validation results
|
||
- SHORT: Minimal response; validation runs asynchronously
|
||
|
||
## Constraints
|
||
- Maximum file size: 12 MB
|
||
- Pagination supported via `limit` and `offset` parameters
|
||
- Serial letters support token-based or page-count splitting
|
||
- Transformations and cover pages can only be applied to original documents
|