Skip to content

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, to, lines. The seller identity comes from the API key's legal entity; from carries the seller contact (BG-6) for the document.

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

  // Optional
  date?: string;                // ISO 8601 (default: today)
  dueDate?: string;             // ISO 8601
  currency?: string;            // ISO 4217 (default: "EUR")
  taxCurrency?: string;         // BT-6
  taxCurrencyRate?: number;
  note?: string;
  from?: Party;                 // seller CONTACT only (BG-6) — identity comes from your legal entity
  payeeParty?: Party;           // BG-10
  buyerReference?: string;      // BT-10
  orderReference?: string;      // PO number
  salesOrderReference?: string; // BT-14
  contractReference?: string;   // BT-12
  projectReference?: string;    // BT-11
  invoiceReference?: string;    // required for credit notes
  invoiceReferenceDate?: string; // BT-26, YYYY-MM-DD — required on a French credit note
  isCreditNote?: boolean;

  // Payment
  paymentTerms?: string;
  paymentReference?: string;
  paymentMeans?: number;        // UNCL 4461: 10, 30, 31, 48, 49, 57, 58, 59
  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:0685660237).

A scheme has two legal spellings and both are accepted: the numeric EAS code (9932) and the symbolic form (GB:VAT). They name the same scheme — 9932:123456789 and GB:VAT:123456789 are the same participant, and the SDK always writes the numeric code into the XML for you.

⚠️ The symbolic form contains a colon itself, so a peppolId cannot be split on the first — or the last — colon. If you need the two parts, reach for the parsePeppolId helper rather than splitting the string yourself:

parsePeppolId
import { parsePeppolId } from "@getpeppr/sdk";

// A scheme has two legal spellings, and the symbolic one contains a colon.
// Splitting the string yourself gets this wrong; resolving it does not.
parsePeppolId("GB:VAT:123456789");  // { scheme: "9932", id: "123456789" }
parsePeppolId("9932:123456789");    // { scheme: "9932", id: "123456789" }
parsePeppolId("DE:LWID:04011000");  // { scheme: "0204", id: "04011000" }
parsePeppolId("0208:0685660237");   // { scheme: "0208", id: "0685660237" }

// The scheme comes back in its canonical form: the numeric EAS code for
// every national scheme, which is what BR-CL-25 requires in a document.
// A handful of schemes are canonical as literals — AN, AQ, AS, AU, EM —
// and those are returned unchanged, because that IS their published form.
parsePeppolId("AN:123456789");      // { scheme: "AN", id: "123456789" }

// A scheme this version of the code list does not know comes back
// untouched rather than rejected: being stricter than the network is the
// worse of the two errors, and codes are published after our releases.
Party
interface Party {
  name: string;
  peppolId: string;          // "0208:0685660237" or "GB:VAT:123456789"
  country: string;           // ISO 3166-1 alpha-2

  // Optional
  vatNumber?: string;
  street?: string;
  city?: string;
  postalCode?: string;
  companyId?: string;        // BT-30 / BT-47
  companyIdScheme?: string;  // e.g. "0208"
  contactName?: string;
  phone?: string;
  email?: string;
}

type BuyerParty = Party & {
  street: string;
  city: string;
  postalCode: 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" | ...
  taxExemptReason?: string;   // exemption / reverse-charge reason (zero-rated lines)
  itemId?: string;            // seller's item ID
  standardItemId?: string;    // GTIN/EAN
  standardItemScheme?: string;
  baseQuantity?: number;
  accountingCost?: string;    // BT-133
  allowances?: LineAllowanceCharge[];
  charges?: LineAllowanceCharge[];
}

SendResult

Returned by invoices.send(), including credit notes sent with isCreditNote: true. Check Document Status for the full status lifecycle.

senderCountryNotice (SDK 6.6.0) is present when the legal entity that sent is in a country getpeppr does not serve yet: the send was accepted, and the notice says that this is not proof your country is served. The key is absent otherwise, and its absence proves nothing (a resend rebuilt from our record omits it, and so does a stored country that cannot be read). peppol.identity.get() returns the same SenderCountryNotice, or null, for your own legal entity: that is the standing answer.

SendResult
interface SendResult {
  id: string;                 // unique document ID (the provider document GUID)
  submissionId?: string;      // the getpeppr record of this document (SDK 4.0.0)
  providerDocumentId?: string;// the provider document GUID (SDK 4.0.0)
  status: DocumentStatus;
  rawStatus: string;          // raw pre-coercion gateway status (required, SDK 4.0.0)
  detail?: StatusDetail;      // structured national detail, per axis (SDK 2.2.0)
  peppolMessageId?: string;   // Peppol AS4 message ID — only with ?include=evidence
  clearing?: InvoiceClearing; // France: flow 1 reported to the DGFiP — only with ?include=evidence
  ublXml?: string;            // generated UBL (debug)
  warnings?: ValidationWarning[];
  createdAt?: string;         // ISO 8601, when the gateway measured one
  senderCountryNotice?: SenderCountryNotice; // sender's country not served yet (SDK 6.6.0) — absent otherwise
}

// Returned by identity.get() (null when nothing to say), invoices.validateServer()
// (null, or undefined on an older gateway) and on an accepted send (key absent).
// A notice, never a verdict: nothing is refused on this ground alone.
interface SenderCountryNotice {
  code: string;               // "sender_country_not_served" today; open — pass unknown codes through
  country: string;            // ISO 3166-1 alpha-2 of the sender's legal entity, e.g. "AE"
  message: string;            // a sentence to show a human
  docs: string;               // page that explains the notice
  contact: string;            // the address to write to
}

type DocumentStatus =
  | "submitted" | "delivered" | "accepted"
  | "rejected" | "paid" | "failed"
  | "cleared" | "acknowledged" | "in_process"
  | "under_query" | "conditionally_accepted"
  | "partially_paid" | "no_action" | "unknown";

interface StatusDetail {
  platformFiscal?: StatusDetailEntry;
  delivery?: StatusDetailEntry;
  businessDisposition?: StatusDetailEntry;
  settlement?: StatusDetailEntry;
}

interface StatusDetailEntry {
  axis: "platformFiscal" | "delivery" | "businessDisposition" | "settlement" | "unmapped";
  jurisdiction: string;       // e.g. "FR", or "*" for network-wide
  code: string;               // native code (e.g. "213") — not the label
  label: string;              // human label (e.g. "Rejetée")
  codeSystem: string;         // e.g. "fr-ctc-lifecycle"
  codeVersion: string;
  standardCode?: { system: string; code: string };
  reason?: string;
  warnings?: string[];
  failureCategory?: "transport" | "routing" | "syntax" | "semantic" | "authority";
  payment?: { amount: number; currency: string; date: string };
  paymentSemantics?: "received" | "initiated";
  actor?: "seller" | "buyer";
}

ServerValidationResult

Returned by invoices.validateServer(). The gateway validates the same payload server-side, verifies UBL XML generation under ubl, and keeps xsd as deprecated compatibility metadata. It does not call Storecove: providerSendability: "not_checked" means a later send can still return 422.

ServerValidationResult
interface ServerValidationResult {
  valid: boolean;
  errors: ValidationError[];
  warnings: ValidationWarning[];
  ubl: {
    valid: boolean;
    errors: ServerValidationMessage[];
  };
  /** @deprecated Mirrors ubl.valid; no standalone XSD validator runs. */
  xsd: {
    valid: boolean;
    errors: ServerValidationMessage[];
    note?: string;
  };
  schematron: {
    /** No problem among the rules checked — NOT a statement of Peppol conformance. */
    valid: boolean;
    /** What valid is worth: this pass never covers the whole network rulebook. */
    coverage: { rulesChecked: number; ofNetworkFatalRules: "partial" };
    errors: ServerValidationMessage[];
    warnings: ServerValidationMessage[];
  };
  /** Storecove Standard JSON validation did not run; send may still return 422. */
  providerSendability: "not_checked";
  /** Sender's country not served yet (SDK 6.6.0). null = nothing to say; never changes valid. */
  senderCountryNotice?: SenderCountryNotice | null;
}

interface ServerValidationMessage {
  severity: "error" | "warning";
  message: string;
  location?: string;
  ruleId?: string;
}

PeppolConfig

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

PeppolConfig
interface PeppolConfig {
  apiKey: string;
  environment?: "sandbox" | "production"; // accepted for compatibility — the key decides
  baseUrl?: string;           // custom endpoint
  timeout?: number;           // ms (default: 30000)
}

Attachment

File attachment for invoices, embedded as base64 content. url is read by the local UBL builder only; sending refuses it. 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;           // raw base64, no data URI prefix; 2 MB decoded cap on server validation
  url?: string;               // local UBL builder only — invoices.send() refuses it (422)
}

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.received"
  | "invoice.undeliverable"
  | "invoice.delivery_unconfirmed"   // no evidence yet, not a failure
  | "invoice.partially_paid"
  | "invoice.under_query"
  | "invoice.conditionally_accepted"
  | "invoice.status_changed"   // opt-in: never matched by "*"
  | "legal_entity.registered"
  | "legal_entity.unsupported_scheme"
  | "legal_entity.verification_failed"
  | "legal_entity.awaiting_authz"
  | "legal_entity.awaiting_release"
  | "legal_entity.registration_failed"
  | "legal_entity.send_ready"   // send-only Legal Entities
  | "legal_entity.suspended"
  | "legal_entity.resumed"
  | "peppol_identifier.verified"
  | "peppol_identifier.verification_failed"
  | "inbound.invoice.received"
  | "inbound.creditnote.received"
  | "inbound.document.undeliverable" // also sent to inbound.*.received subscribers
  | "test.ping";

// Also exported as a runtime constant:
// const WEBHOOK_EVENT_TYPES: readonly WebhookEventType[]