====== COBI.shipping ======

COBI.shipping is a REST-API service that acts as a connector between **Barcode Shipping** and **SAP Business One**.
Its primary purpose is to exchange delivery and shipping data: \\
  - It retrieves open delivery notes from SAP Business One and
  - reports back shipping information (including tracking numbers, weights, and item details) after the shipment has been processed.

===== Features =====

**Delivery note retrieval:**
COBI.shipping provides Barcode Shipping with open (or optionally closed) delivery notes from SAP Business One. Only delivery notes with allowed shipping methods and unassigned items (not yet packed) are included.

**Shipping confirmation:**
After a shipment has been processed in Barcode Shipping, COBI.shipping sends shipping details back into SAP Business One, including tracking numbers, shipping weight, and item-package assignments.

**Automatic delivery note creation:**
If no delivery note exists for an order, COBI.shipping can automatically generate one based on the corresponding Sales Order, ensuring correct serial number or bin location assignment.

**Status updates:**
The service updates delivery notes with shipping statuses (“In progress” for partial shipments or “Completed” when fully shipped) and can optionally trigger automatic invoice creation.

**Integration with Coresuite Print:**
After invoice creation, COBI.shipping can trigger automatic printing through the COBI.wms Printservice, using predefined layouts and print definitions.

**Shop/Partner feedback:**
Once a shipment is completed, COBI.shipping can send status updates (including tracking numbers, delivery note references, and customer codes) back to connected shops or partners.

===== Implementation details =====

  - Delivered as a Windows service (installation via included batch files). \\
  - Requires Barcode Shipping software and Java 11. \\
  - API endpoints are provided under /api/v1/ with authentication through an API key. \\
  - Configuration is stored in SAP Business One (@CMP_CONFIG) and must be reloaded by restarting the service after changes. \\
  - Supports customizable UDF mappings for address fields, tracking numbers, and commodity codes. \\
  - Optional automatic invoice creation and Coresuite Print integration. \\  
  - Reads address and shipping information directly from SAP table DLN12.

===== Required UDFs in SAP Business One =====

For COBI.shipping to function properly, several **User-Defined Fields (UDFs)** must be created in SAP Business One.  \\
These fields store address information, shipping metadata, and customs information that are required by the integration.

Under //Delivery Notes -> Lines (DLN12)//:

^ Title                         ^ Data type     ^ Size  ^ Description                                      ^
| cobi-shipping_firstNameField  | Alphanumeric  | 50    | First name of the recipient                      |
| cobi-shipping_lastNameField   | Alphanumeric  | 50    | Last name of the recipient                       |
| cobi-shipping_companyField    | Alphanumeric  | 100   | Company name of the recipient                    |
| cobi-shipping_phoneField      | Alphanumeric  | 30    | Phone number of the recipient                    |
| cobi-shipping_emailField      | Alphanumeric  | 100   | Email address of the recipient                   |

Under //Delivery Notes -> Header//:

^ Title                                ^ Data type     ^ Size  ^ Description                                        ^
| cobi-shipping_trackingInHeaderField  | Alphanumeric  | 100   | Field to store tracking number(s) in delivery note |
| cobi-shipping_alarmGroupId           | Numeric       | 11    | Alarm group for invoice errors                     |

Under //Items (OITM)//:

^ Title                                ^ Data type     ^ Size  ^ Description                                  ^
| cobi-shipping_oitmCommodityCodeField | Alphanumeric  | 20    | Customs tariff code for export/import handling |


===== Installation =====

**1. Install Barcode Shipping**

  * Download and install Barcode Shipping from the internal archive (N:\Entwicklung\Barcode Shipping\Downloads.7z).
  * During setup, choose **Shop → Eigenentwicklung** and **Shipper → Einfacher Versender**, then enable additional functions as needed.
  * Install **Java 11** (required by Barcode Shipping). \\
  * Instructions: https://www.barcodeshipping.de/java-installation
  * Log in to Barcode Shipping with COMP.net credentials.

**2. Install COBI.shipping service**

  * Extract the cobi-shipping ZIP archive (recommended path: C:\cobi-shipping).
  * Configure the connection values in the file cobi-shipping-service.exe.config (SAP database settings).
  * Run the provided batch files:

  * InstallService.bat → installs the Windows service.
  * DeleteService.bat → removes the Windows service.

**3. Configure Barcode Shipping**

  * Open Barcode Shipping → File → Settings.
  * General:

  * Default shipper: *Einfacher Versender*
  * Disable *Check order status*
  * Enable *Mouse Mode*
  * Default shop: *Connector*
  * Connector: \\
  * API URL: http://IPvomCOBIShippingServer:Port/api/v1/
  * (example: http://127.0.0.1:62005/api/v1/)
  *   API Version: V2

===== Optional toggles (Boolean, 0/1) =====

The following toggles are configured in @CMP_CONFIG and must be set to 0 (disabled) or 1 (enabled).

^ Key ^ Meaning ^
| cobi-shipping_companyFromCardName | Use CardName as company name on the delivery address. |
| cobi-shipping_firstLastNameFromContacts | Take first/last name from the linked Contact Person. |
| cobi-shipping_firstNameLastNameFromCardName | Derive first/last name from CardName. |
| cobi-shipping_companyFirstNameLastNameFromAddress3 | Pull company / first / last name from Address3 field. |
| cobi-shipping_addressFromAddress2 | Use Address2 as the street address. |
| cobi-shipping_companyAddressFromAddress2 | Take name/company from Address2. |
| cobi-shipping_privateAddressFromAddress2 | Treat Address2 as a private address. |
| cobi-shipping_createInvoiceAfterFullyPacked | Auto-create Invoice when the delivery is fully packed. |
| cobi-shipping_invoiceDateEqDeliveryNoteDate | Set Invoice Date = Delivery Note Date for auto-created invoices. |
| cobi-shipping_displayClosedDeliveryNotes | Also show closed Delivery Notes to Barcode Shipping. |

===== Coresuite Print configuration =====

For environments with automatic invoice creation, COBI.shipping can trigger Coresuite Print. \\
The following configuration values must be set:

^ Key ^ Type / Example ^ Purpose ^
| cobi-shipping_printService | URL (e.g. http://127.0.0.1:62005) | URL of the COBI.wms Printservice endpoint |
| cobi-shipping_printDefinition | Text / ID (e.g. DeliveryNoteLayout) | Print Definition ID to be used for output |
| cobi-shipping_layoutId | Text / ID (e.g. 1001) | Layout ID for the document |
| cobi-shipping_printMode | Text (Print or Email) | Determines whether the invoice is printed or sent by email |