binect-js/research/binect-api-specification.md

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