# 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