Executable SDK examples

Source-linked snippets

These examples are extracted at build time from the SDK source files between stable snippet markers. The documentation does not maintain a second hand-edited copy of SDK code.

Issuance guard

The first-invoice example validates before issue and requires an explicit caller confirmation setting and idempotency key. Do not run it against Production.

First invoice

C#

        var draft = await client.Invoices.CreateDraftAsync(
            new CreateInvoiceDraftRequest
            {
                CustomerId = Required("EMISSARY_CUSTOMER_ID"),
                SeriesId = Required("EMISSARY_SERIES_ID"),
                Currency = "EUR",
                IssueDate = DateOnly.FromDateTime(DateTime.UtcNow),
                Lines =
                [
                    new InvoiceLineRequest
                    {
                        Description = "Software development service",
                        Quantity = 1,
                        Unit = "service",
                        UnitPrice = 100m,
                        DiscountType = "None",
                        DiscountValue = 0,
                        TaxRateId = Required("EMISSARY_TAX_RATE_ID")
                    }
                ]
            },
            idempotencyKey: Required("EMISSARY_DRAFT_IDEMPOTENCY_KEY"));

        var validation = await client.Invoices.ValidateAsync(draft.Id);
        Console.WriteLine($"Draft {draft.Id}: valid={validation.IsValid}");
        foreach (var error in validation.Errors)
        {
            Console.WriteLine($"Validation: {error}");
        }

        if (!validation.IsValid || !string.Equals(Environment.GetEnvironmentVariable("EMISSARY_CONFIRM_ISSUE"), "true", StringComparison.OrdinalIgnoreCase))
        {
            Console.WriteLine("No invoice was issued. Set EMISSARY_CONFIRM_ISSUE=true to explicitly authorize the example issue call.");
            return;
        }

        var issued = await client.Invoices.IssueAsync(
            draft.Id,
            new IssueInvoiceRequest { ExpectedVersion = draft.Version },
            idempotencyKey: Required("EMISSARY_ISSUE_IDEMPOTENCY_KEY"));
        Console.WriteLine($"Issued {issued.InvoiceNumber ?? issued.Id}; fiscal status: {issued.FiscalSubmissionStatus ?? issued.FiscalStatus ?? "not reported"}.");
        //

TypeScript

const client = createClient();
const customer = await client.customers.create({
  type: "Business",
  legalName: requiredEnv("EMISSARY_CUSTOMER_LEGAL_NAME"),
  countryCode: requiredEnv("EMISSARY_CUSTOMER_COUNTRY"),
  defaultCurrency: "EUR",
  preferredLocale: "en",
  billingAddress: { line1: requiredEnv("EMISSARY_CUSTOMER_ADDRESS"), city: requiredEnv("EMISSARY_CUSTOMER_CITY"), countryCode: requiredEnv("EMISSARY_CUSTOMER_COUNTRY") },
}, { idempotencyKey: requiredEnv("EMISSARY_CUSTOMER_IDEMPOTENCY_KEY") });
if (!customer.id) throw new Error("The API did not return the customer ID.");

const draft = await client.invoices.createDraft({
  customerId: customer.id,
  seriesId: requiredEnv("EMISSARY_SERIES_ID"),
  currency: "EUR",
  lines: [{ description: "Development service", quantity: 1, unitPrice: 100, taxRateId: requiredEnv("EMISSARY_TAX_RATE_ID") }],
}, { idempotencyKey: requiredEnv("EMISSARY_DRAFT_IDEMPOTENCY_KEY") });
if (!draft.id) throw new Error("The API did not return the draft ID.");
const validation = await client.invoices.validate(draft.id);
if (!validation.isValid) throw new Error(`Draft is invalid: ${(validation.errors ?? []).join("; ")}`);

if (process.env.EMISSARY_CONFIRM_ISSUE === "true") {
  await client.invoices.issue(draft.id, { expectedVersion: draft.version }, requiredEnv("EMISSARY_ISSUE_IDEMPOTENCY_KEY"));
  console.log(`Issued invoice ${draft.id}.`);
} else {
  console.log(`Validated draft ${draft.id}. Set EMISSARY_CONFIRM_ISSUE=true to explicitly issue it.`);
}
//

Python

from __future__ import annotations

import os
from datetime import date

from emissary import (
    CreateInvoiceDraftRequest,
    EmissaryClient,
    InvoiceLineRequest,
    IssueInvoiceRequest,
)


def required(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise SystemExit(f"Set {name} before running this example.")
    return value


with EmissaryClient(
    api_key=required("EMISSARY_API_KEY"),
    environment_id=required("EMISSARY_ENVIRONMENT_ID"),
    base_url=required("EMISSARY_BASE_URL"),
) as client:
    draft = client.invoices.create_draft(
        CreateInvoiceDraftRequest(
            customer_id=required("EMISSARY_CUSTOMER_ID"),
            series_id=required("EMISSARY_SERIES_ID"),
            currency=os.environ.get("EMISSARY_CURRENCY", "EUR"),
            issue_date=date.today().isoformat(),
            lines=[
                InvoiceLineRequest(
                    description="Integration service",
                    quantity=1,
                    unit_price=float(required("EMISSARY_UNIT_PRICE")),
                    tax_rate_id=required("EMISSARY_TAX_RATE_ID"),
                )
            ],
        ),
        idempotency_key=os.environ.get("EMISSARY_DRAFT_IDEMPOTENCY_KEY"),
    )
    if not draft.id:
        raise RuntimeError("The API did not return the draft ID.")
    validation = client.invoices.validate(draft.id)
    if not validation.is_valid:
        raise RuntimeError(f"Draft is not valid: {validation.errors}")

    confirmation = input(f"Issue invoice {draft.id}? Type ISSUE to confirm: ")
    if confirmation != "ISSUE":
        print(f"Draft {draft.id} remains unissued.")
    else:
        result = client.invoices.issue(
            draft.id,
            IssueInvoiceRequest(expected_version=draft.version),
            idempotency_key=required("EMISSARY_ISSUE_IDEMPOTENCY_KEY"),
        )
        print(f"Issued invoice {result.invoice_number or result.id} ({result.status}).")
#

Fiscal status

C#

        var status = await client.Invoices.GetFiscalStatusAsync(Required("EMISSARY_INVOICE_ID"));
        Console.WriteLine($"Invoice {status.InvoiceId}: commercial={status.CommercialStatus}, fiscal={status.FiscalStatus}");
        if (status.LatestOperation is { } operation)
        {
            Console.WriteLine($"Operation {operation.Id}: {operation.Status}; code={operation.LatestErrorCode ?? "none"}");
        }
        //

TypeScript

const client = createClient();
const status = await client.invoices.getFiscalStatus(requiredEnv("EMISSARY_INVOICE_ID"));
console.log(status.fiscalStatus, status.latestOperation?.status ?? "No fiscal operation");
if (status.latestOperation?.id) {
  const operation = await client.fiscalOperations.get(status.latestOperation.id);
  console.log(operation.providerCode, operation.latestErrorCode, operation.latestErrorExcerpt);
}
//

Python

from __future__ import annotations

import os

from emissary import EmissaryClient


def required(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise SystemExit(f"Set {name} before running this example.")
    return value


with EmissaryClient(
    api_key=required("EMISSARY_API_KEY"),
    environment_id=required("EMISSARY_ENVIRONMENT_ID"),
    base_url=required("EMISSARY_BASE_URL"),
) as client:
    status = client.invoices.get_fiscal_status(required("EMISSARY_INVOICE_ID"))
    operation = status.latest_operation
    print(f"Invoice: {status.invoice_id}; fiscal status: {status.fiscal_status}")
    if operation:
        print(f"Operation: {operation.id}; status: {operation.status}; provider:")
        print(operation.provider_code)
#

Download a document

C#

        var invoiceId = Required("EMISSARY_INVOICE_ID");
        var documentId = Required("EMISSARY_DOCUMENT_ID");
        await using var download = await client.Documents.DownloadAsync(invoiceId, documentId);
        var destination = download.FileName ?? $"{documentId}.bin";
        await using var file = File.Create(destination);
        await download.Content.CopyToAsync(file);
        Console.WriteLine($"Saved {destination} ({download.ContentType ?? "unknown content type"}).");
        //

TypeScript

const client = createClient();
const invoiceId = requiredEnv("EMISSARY_INVOICE_ID");
const documentId = requiredEnv("EMISSARY_DOCUMENT_ID");
const metadata = await client.documents.getMetadata(invoiceId, documentId);
const download = await client.documents.download(invoiceId, documentId);
const reader = download.body.getReader();
try {
  for (;;) {
    const { done, value } = await reader.read();
    if (done) break;
    process.stdout.write(value);
  }
} finally {
  reader.releaseLock();
}
console.error(`Downloaded ${metadata.fileName ?? download.fileName ?? "document"} (${download.contentType ?? "unknown type"}).`);
//

Python

from __future__ import annotations

import os
from pathlib import Path

from emissary import EmissaryClient


def required(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise SystemExit(f"Set {name} before running this example.")
    return value


destination = Path(required("EMISSARY_OUTPUT_PATH")).expanduser()
with EmissaryClient(
    api_key=required("EMISSARY_API_KEY"),
    environment_id=required("EMISSARY_ENVIRONMENT_ID"),
    base_url=required("EMISSARY_BASE_URL"),
) as client:
    with client.documents.download(
        required("EMISSARY_INVOICE_ID"), required("EMISSARY_DOCUMENT_ID")
    ) as document:
        with destination.open("wb") as output:
            for chunk in document.iter_bytes():
                output.write(chunk)
    print(f"Downloaded {destination}.")
#

Webhook verification

C#

        var secret = Required("EMISSARY_WEBHOOK_SECRET");
        var timestamp = Required("WEBHOOK-TIMESTAMP");
        var signature = Required("WEBHOOK-SIGNATURE");
        using var body = new MemoryStream();
        await Console.OpenStandardInput().CopyToAsync(body);

        var verified = EmissaryWebhookVerifier.Verify(body.ToArray(), timestamp, signature, secret);
        Console.WriteLine(verified ? "Webhook signature verified." : "Webhook signature is invalid or outside the timestamp tolerance.");
        //

TypeScript

const chunks: Buffer[] = [];
for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
const rawBody = Buffer.concat(chunks);
const valid = verifyWebhookSignature(rawBody, {
  timestamp: requiredEnv("WEBHOOK-TIMESTAMP"),
  signature: requiredEnv("WEBHOOK-SIGNATURE"),
}, requiredEnv("EMISSARY_WEBHOOK_SECRET"));
if (!valid) throw new Error("Webhook signature is invalid or expired.");
const event = parseWebhookEvent<{ id: string; type: string }>(rawBody);
console.log(event.id, event.type);
//

Python

from __future__ import annotations

import os
import sys

from emissary import parse_webhook_event, verify_webhook_signature

secret = os.environ.get("EMISSARY_WEBHOOK_SECRET", "")
timestamp = os.environ.get("EMISSARY_WEBHOOK_TIMESTAMP")
signature = os.environ.get("EMISSARY_WEBHOOK_SIGNATURE")
raw_body = sys.stdin.buffer.read()
if not verify_webhook_signature(raw_body, timestamp=timestamp, signature=signature, secret=secret):
    raise SystemExit("Webhook signature verification failed.")
event = parse_webhook_event(raw_body)
print(f"Verified event: {event.get('id', '<unknown>')}")
#