InvoiceSalesOrder

The InvoiceSalesOrder-CUWO is responsible for invoicing a sales order outside of the enfore platform.

The CUWO receives the sales order as well as context information and is expected to return a confirmation that the order has been or will be externally invoiced. When it has already been invoiced, the CUWO should also immediately return the invoice number and invoicing data so it can be directly persisted when storing the order. When the external system creates the invoice only later (e.g., as a combined settlement when the customer checks out of the hotel), that invoice number cannot be provided as CUWO-result but must then be later set via backend API.

If the sales order cannot be invoiced via the external system, the CUWO shall return as "canceled" with reason UNABLE_TO_INVOICE after informing the user about the reason for this.

When the CUWO returns as "canceled", it is assumed that the user actively decided to cancel and/or was informed about the cancelation and thus no message must be shown by the enfore runtime. The CUWO will simply be closed and the user will be back in the payment UI.

When the CUWO returns as "failed", the enfore runtime will display the failure to the customer and return the user to the payment UI.

Workflow parameters

The InvoiceSalesOrder-CUWO will receive an InvoiceSalesOrderWorkflowParameters structure as input.

The structure is defined as:

/**
 * The parameter/input structure for an "invoice sales order" workflow.
 */
class InvoiceSalesOrderWorkflowParameters extends WorkflowParameters {
    readonly "@type" : string = "n4.cuwo.workflows.externalinvoicing.invoicesalesorder.InvoiceSalesOrderWorkflowParameters";

    /**
     * Information about the order to be invoiced.
     *
     * Includes the orer number, items of the order, information
     * about the customer etc.
     *
     * Note that pricing information is provided via the separate
     * "pricingData" structure.
     */
    public orderData : SalesOrderData;

    /**
     * Information about the pricing calculation for the order and
     * its items.
     *
     * Consists of information about the order itself as well as
     * item- and subitem-level information.
     */
    public pricingData : SalesOrderPricingData;

    /**
     * Holds a reference to and configuration of the external
     * invoicing method that the CUWO belongs to. 
     */
    public invoicingMethodConfiguration : InvoicingMethodConfiguration;
}

Success result

On success, the InvoiceSalesOrder-CUWO is expected to pass an InvoiceSalesOrderWorkflowResult structure to terminateSuccess.

The structure is defined as:

/**
 * The result/output structure for a successful "invoice sales order" workflow.
 */
class InvoiceSalesOrderWorkflowResult extends WorkflowResult {
    readonly "@type" : string = "n4.cuwo.workflows.externalinvoicing.invoicesalesorder.InvoiceSalesOrderWorkflowResult";

    /**
     * A human-readable reference identifying the order/invoice in the external invoicing system.
     *
     * This is an "external identifier" for the enfore platform, so it has no semantic meaning
     * but will only be stored, shown in the sales history UI of the enforePOS client and passed
     * to subsequent CUWOs such as ViewExternalInvoice.
     *
     * The reason for requiring this reference is that with this, there is a way for the
     * merchant/customer to look up the order/invoice in the external system or call the
     * external systems support hotline and be able to provide some kind if reference.
     */
    public externalReference : string;

    /**
     * An optional note that will be stored as part of the "externally
     * invoiced" information at the order.
     *
     * This will be shown in the "Sales History UI".
     */
    public note? : string;

    /**
     * The number of the externally created invoice.
     *
     * When not available yet, this can be left empty. The invoice
     * number must then be set later via backend APIs.
     */
    public invoiceNumber? : string;

    /**
     * The date of the externally created invoice.
     *
     * When not available yet, this can be left empty. The invoice
     * date must then be set later via backend APIs.
     */
    public invoiceDate? : Date;
}

Failure result

On failure, the InvoiceSalesOrder-CUWO is expected to pass an InvoiceSalesOrderWorkflowFailure structure to terminateFailure.

The structure is defined as:

/**
 * The result/output structure for a failed "invoice sales order" workflow.
 */
class InvoiceSalesOrderWorkflowFailure extends WorkflowFailure {
    readonly "@type" : string = "n4.cuwo.workflows.externalinvoicing.invoicesalesorder.InvoiceSalesOrderWorkflowFailure";

    /**
     * The reason for the failure.
     */
    public failureReason : InvoiceSalesOrderWorkflowFailureReason;

    /**
     * A failure message that can be shown to in the UI.
     * When not provided, a generic message will be shown instead.
     */
    public failureMessage? : string;
}

Cancelation result

On cancelation, the InvoiceSalesOrder-CUWO is expected to pass an InvoiceSalesOrderWorkflowCancelation structure to terminateCanceled.

The structure is defined as:

/**
 * The result/output structure for a canceled "invoice sales order" workflow.
 */
class InvoiceSalesOrderWorkflowCancelation extends WorkflowCancelation {
    readonly "@type" : string = "n4.cuwo.workflows.externalinvoicing.invoicesalesorder.InvoiceSalesOrderWorkflowCancelation";

    /**
     * The reason for the cancelation.
     */
    public cancelationReason : InvoiceSalesOrderWorkflowCancelationReason;
}