Live verification. Verified live on a test company (2026-11-11) with this release: selling gift certificates (including automatic numbering, required barcodes and expiry), redeeming them with cash change, forfeit and a credit-note change, marking certificates used, activating the change credit note, the recovery commands, and the refusals before any write; every test invoice ended fully settled. Not exercised live: the reference lookup after a failed invoice create, because no create failed.
The invoice and the writes to the papers table are separate requests with no transaction between them. Nothing is retried
and nothing is rolled back: every POST and PUT is sent once. Cancellation is honored until the first write; after that
the remaining steps run to completion, each under its own deadline, so a canceled caller cannot leave an invoice with
unmarked certificates.
When the invoice and all its steps succeed you get a GiftCertificateInvoiceResult. Otherwise you get a
DkPlusGiftCertificateInvoiceException (or the original exception, when nothing was written yet).
| Member | Meaning |
|---|---|
InvoiceOutcome |
NotCreated, Created or Unknown (below) |
InvoiceNumber, InvoiceRecordId |
The invoice, when known |
Posted |
Whether the invoice is posted |
Invoice |
The created invoice, when known |
Completed |
Steps that finished |
Pending |
Steps still to do, each a PendingPaperOperation |
InnerException |
The first failure |
A PendingPaperOperation has a Kind (MarkGiftCertificateUsed, ActivateCreditNote, OrphanedCreditNote,
CreateGiftCertificate), a Reason (NotAttempted, Failed, Conflict, AmountMismatch, LineNotFound), the
PaperRecordId, the Amount, and for a sold certificate the CreateRequest that completes it.
| Where it fails | What you get | What to do |
|---|---|---|
| Validation, a read, the payment modes, the storage, the total, or the number allocation | The original exception; no invoice. When a change credit note was already reserved: InvoiceOutcome = NotCreated with an OrphanedCreditNote step |
Fix the cause and run again. An orphaned credit note is inactive and inert; nothing needs to be done with it |
| DK Plus answers 409: its index already has an invoice with the reference | NotCreated |
If that invoice is this sale, find it with FindByReferenceAsync and complete its steps with its record id |
| Another failure of the invoice request, and the invoice is found by its reference | Created: the remaining steps run as after a success |
See "A step after the invoice exists" |
| Another failure, DK Plus answered with a client error (below 500, not 408) and no matching invoice is found | NotCreated (the best the lookups can tell, not a proof) |
Run again |
| A timeout, a broken connection, 408, a status of 500 or above, or a lookup that fails or finds no single match | Unknown; no paper was touched; every step is NotAttempted |
Check with FindByReferenceAsync before creating again |
| A success without a usable record id or number | The lookup finds it and the steps run; otherwise Created without InvoiceRecordId and every step NotAttempted |
Find the invoice and complete the steps |
| A success that answers an unposted invoice (number 0) although posting was requested | Created, Posted = false, every step NotAttempted |
Post the invoice in dkERP, find it with FindByReferenceAsync, complete the steps with the posted invoice's record id and number. Do not create it again |
| DK Plus created the invoice with another total than the computed one | Created after the certificates are marked used; a change credit note and the sold certificates are Pending with the reason AmountMismatch, and the message says that the invoice total differs |
Do not create the invoice again. Correct the invoice in dkERP, then complete the held steps |
| A step after the invoice exists | Every remaining step is still attempted; then Created with Completed, Pending and the first failure as InnerException |
Do not create the invoice again. Complete each pending step (below) |
Unknown and Created mean the invoice may exist: never create it again without checking.
IReadOnlyList<DkPlusSalesInvoice> found = await dkPlus.Sales.Invoice.FindByReferenceAsync("SALE-1007", cancellationToken);
It lists the posted invoices with exactly that reference (same rule as for creating: at most 12 characters, letters and digits
with -, _ or . between them). It reads dkPlus's invoice index and, when the index has no posted match, DK's posted
invoice heads (which answer with the earliest invoice with the reference only). An empty list means none was found. A
candidate counts as the created invoice only when its reference, customer, date and total match, so check the invoice's
number and record id yourself before you act on it.
CLI: devop-dk sales invoice find --reference SALE-1007 (--json writes the array, [] when there is none).
PowerShell: Get-Invoice -Reference SALE-1007.
All three methods read the paper first and are safe to repeat.
| Pending step | Method | CLI | PowerShell |
|---|---|---|---|
MarkGiftCertificateUsed |
Sales.GiftCertificate.MarkUsedAsync(recordId, invoiceRecordId) |
sales gift-certificate mark-used --record-id <id> --invoice-record-id <id> |
Set-GiftCertificateUsed -RecordId <id> -InvoiceRecordId <id> |
ActivateCreditNote |
Sales.CreditNote.ActivateAsync(recordId, invoiceRecordId, invoiceNumber) |
sales credit-note activate --record-id <id> --invoice-record-id <id> --invoice-number <number> |
Enable-CreditNote -RecordId <id> -InvoiceRecordId <id> -InvoiceNumber <number> |
CreateGiftCertificate |
Sales.GiftCertificate.CreateAsync(request) with the step's CreateRequest |
sales gift-certificate create --number <number> --amount <amount> --source-invoice-record-id <id> --source-invoice-number <number> ... |
New-GiftCertificate -InputObject <CreateRequest> |
MarkUsedAsync: already used on the same invoice is success without a write. Used on another invoice, used without anDkPlusPaperConflictException. dkERP numbers posted and unposted invoicesActivateAsync: already active on the same invoice is success. Linked to another invoice, used, or active without anDkPlusPaperConflictException. Otherwise it verifies the change before it writes and refuses withInvalidOperationException unless the invoice read by its number has the record id and the credit note's customer, the0 is an ArgumentException. DK Plus does not return an invoice's payments, so theCreateAsync: first proves the sale with reads only. It reads the invoice by number and refuses withInvalidOperationException unless the invoice is posted, has the record id, exactly one line names the certificate and wasDkPlusPaperConflictException. It then reads the number: a certificate of the same invoice and amount is returned (andDkPlusPaperConflictException. The step's CreateRequest carries every value this needs.Conflict or AmountMismatch, and a LineNotFound step, need a look at the invoice in dkERP first; noAmountMismatch on a change credit note or a sold certificate means DK created the invoice with another total thanActivateAsync or CreateAsync if the amount is right.A recovery loop in C# (every call is safe to repeat):
try
{
var result = await dkPlus.Sales.Invoice.CreateWithGiftCertificatesAsync(invoice, options, cancellationToken);
}
catch (DkPlusGiftCertificateInvoiceException exception) when (exception.InvoiceOutcome == GiftCertificateInvoiceOutcome.Unknown)
{
var found = await dkPlus.Sales.Invoice.FindByReferenceAsync(invoice.Reference!, cancellationToken);
// Decide from found: do not create the invoice again unless it is certain that it does not exist.
}
catch (DkPlusGiftCertificateInvoiceException exception) when (exception.InvoiceOutcome == GiftCertificateInvoiceOutcome.Created)
{
foreach (var step in exception.Pending)
{
if (step.Kind == PaperOperationKind.CreateGiftCertificate && step.Reason == PaperOperationReason.Failed
&& step.CreateRequest is { } createRequest)
{
await dkPlus.Sales.GiftCertificate.CreateAsync(createRequest, cancellationToken);
continue;
}
if (step.Reason is PaperOperationReason.Conflict or PaperOperationReason.AmountMismatch
|| step.PaperRecordId is not { } paper
|| exception.InvoiceRecordId is not { } invoiceRecordId)
{
// Needs a person: check the invoice and the paper in dkERP.
continue;
}
if (step.Kind == PaperOperationKind.MarkGiftCertificateUsed)
{
await dkPlus.Sales.GiftCertificate.MarkUsedAsync(paper, invoiceRecordId, cancellationToken);
}
else if (step.Kind == PaperOperationKind.ActivateCreditNote && exception.InvoiceNumber is { } invoiceNumber)
{
await dkPlus.Sales.CreditNote.ActivateAsync(paper, invoiceRecordId, invoiceNumber, cancellationToken);
}
}
}
The check that a certificate is unused and the write that marks it used are separate requests, and DK Plus has no
compare-and-set. A redemption that starts after another one marked the certificate is refused before any write. One whose
certificate is marked between its check and its own mark gets a Conflict step, after its invoice already exists. But two
callers whose reads both happen before either write both see the certificate unused: both invoices are created, both writes
succeed, and the later one overwrites the destination invoice. Nothing reports it. Serialize redemptions of one certificate in
your application if that matters.
Gift-certificate and credit-note numbers and barcodes are spendable. The client logs record ids only. Exception messages,
ToString(), the CLI's error and retry lines and PowerShell error targets name record ids, never numbers. DK's error text for
a papers write can echo a number, so the client replaces it with a fixed message (the status, reason phrase and correlation id
are kept). A step carries a number only when the paper has no record id yet: an unconfirmed credit-note reservation and every
pending sold certificate, whose CreateRequest has the number and barcode. These are shown only where you ask for the
partial result (the CLI's --json output, and the exception's members). Do not serialize the exception's members to a log.
1: the invoice exists but a step is pending or its created total differs from the computed one, the outcome is--json, stdout then holds a valid JSON partial result (outcome, invoiceNumber, invoiceRecordId, posted,invoice, completed, pending); stderr holds the error, its cause, and the commands that complete the pending steps.2: a missing or invalid option, before any request.sales invoice create again after exit code 1. When the outcome is unknown, stderr says to rundevop-dk sales invoice find --reference <reference> first.PowerShell reports the same as the error DkPlus.GiftCertificateInvoice, which carries the exception
($error[0].Exception.Pending[i]) and a recommended action that lists the commands that complete the steps.