Type Definitions

Complete TypeScript type reference for the @getpeppr/sdk. All types are exported from the package.

InvoiceInput

The main payload for sending invoices. Required fields: number, from, to, lines.

InvoiceInput 
interface InvoiceInput {
  number: string;
  from: Party;
  to: Party;
  lines: InvoiceLine[];

  // Optional
  issueDate?: string;           // ISO 8601 (default: today)
  dueDate?: string;             // ISO 8601
  currency?: string;            // ISO 4217 (default: "EUR")
  note?: string;
  buyerReference?: string;      // BT-10
  orderReference?: string;      // PO number

  // Payment
  paymentTerms?: string;
  paymentMeans?: number;        // 30=credit transfer, 58=SEPA
  paymentIban?: string;
  paymentBic?: string;

  // Extended
  delivery?: Delivery;
  invoicePeriod?: InvoicePeriod;
  attachments?: Attachment[];
  allowances?: AllowanceCharge[];
  charges?: AllowanceCharge[];
}

Party

Represents a seller (from) or buyer (to) in an invoice. The peppolId format is scheme:identifier (e.g. 0208:BE0456789012).

Party 
interface Party {
  name: string;
  peppolId: string;          // e.g. "0208:BE0456789012"
  country: string;           // ISO 3166-1 alpha-2

  // Optional
  vatNumber?: string;
  street?: string;
  city?: string;
  postalCode?: string;
  email?: string;
}

InvoiceLine

A single line item. Totals are calculated automatically from quantity × unitPrice. Line-level allowances and charges can be added.

InvoiceLine 
interface InvoiceLine {
  description: string;
  quantity: number;
  unitPrice: number;
  vatRate: number;            // percentage (e.g. 21)

  // Optional
  unit?: string;              // UN/ECE code or "hour", "day", "kg"...
  vatCategory?: string;       // "S" | "Z" | "E" | "AE" | ...
  itemId?: string;            // seller's item ID
  allowances?: LineAllowanceCharge[];
  charges?: LineAllowanceCharge[];
}

SendResult

Returned by invoices.send() and creditNotes.send(). Check Document Status for the full status lifecycle.

SendResult 
interface SendResult {
  id: string;
  status: DocumentStatus;
  peppolMessageId?: string;   // Peppol AS4 message ID
  ublXml?: string;            // generated UBL (debug)
  warnings?: ValidationWarning[];
  createdAt: string;          // ISO 8601
}

type DocumentStatus =
  | "submitted" | "delivered" | "accepted"
  | "rejected" | "paid" | "failed"
  | "cleared" | "acknowledged" | "unknown";

PeppolConfig

Configuration options for the SDK client. See Authentication for details.

PeppolConfig 
interface PeppolConfig {
  apiKey: string;
  environment?: "sandbox" | "production";
  baseUrl?: string;           // custom endpoint
  timeout?: number;           // ms (default: 30000)
}

Attachment

File attachment for invoices. Supports embedded base64 content or external URL references. See Attachments guide.

Attachment 
interface Attachment {
  id: string;                 // document reference
  description?: string;
  filename?: string;          // e.g. "invoice.pdf"
  mimeType?: string;          // e.g. "application/pdf"
  content?: string;           // base64-encoded
  url?: string;               // external URL alternative
}

AllowanceCharge

Discounts and surcharges at document and line level. See Allowances & Charges guide.

AllowanceCharge 
// Document-level (BG-20 / BG-21)
interface AllowanceCharge {
  reason: string;
  amount: number;
  vatRate: number;
  vatCategory?: string;
}

// Line-level (BG-27 / BG-28)
interface LineAllowanceCharge {
  reason: string;
  amount: number;
}

WebhookEvent

Webhook event payload. See Webhooks for event types and handler examples.

WebhookEvent 
interface WebhookEvent<T = unknown> {
  id: string;
  type: WebhookEventType;
  data: T;
  createdAt: string;
}

type WebhookEventType =
  | "invoice.sent"
  | "invoice.accepted"
  | "invoice.refused"
  | "invoice.error"
  | "invoice.registered"
  | "invoice.paid"
  | "invoice.closed"
  | "invoice.received"
  | "creditnote.sent"
  | "creditnote.received"
  | "test.ping";
Error Handling