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.
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:
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.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.
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.
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.
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.
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.
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.
// 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.
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[]