datalogic-sdk 0.1.4

Independent/community Python SDK for the Datalogics shipping API

datalogic-sdk

Independent/community Python SDK for the Datalogics shipping API.

This is not an official Datalogics SDK. It is an independent/community project.

Documentation

• Usage guide: how to use this Python SDK.
• SDK API reference: Python classes, methods, return values, and exceptions.
• OpenAPI contract: raw Datalogics HTTP API contract for POST /rest/w_create_shipping.
• Contributing guide
• Changelog
• Security policy

The OpenAPI file documents the vendor HTTP endpoint, not the Python SDK itself. It is included as a reference for API tooling, contract review, mock servers, or future code generation. The SDK does not load it at runtime.

Installation

From this repository:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install .

This project currently has no third-party runtime dependencies. The requirements.txt file is intentionally empty except for a comment.

If you only want to run from a checkout without installing:

PYTHONPATH=src python -m unittest discover -s tests

Development

Install the SDK and dev tooling inside a virtual environment:

make install

Available commands:

make format
make lint
make typecheck
make test
make check
make integration-test
make package
make release

make package builds the source distribution and wheel into dist/. make release increments the latest vX.Y.Z tag by one patch version, updates pyproject.toml, runs verification, commits the version bump, creates an annotated tag, pushes the branch, and pushes the tag. make check runs lint, typecheck, and tests. make integration-test runs the real API integration script.

CI/CD

GitHub Actions workflows live in .github/workflows/.

• ci.yml runs on pull requests to main and manual dispatch. It installs the package with dev tooling, then runs lint, typecheck, and tests across Python 3.9 through 3.13, and builds the package once on Python 3.13.
• release.yml runs only on tags matching v*. It runs the same checks, builds dist/, uploads the distribution files as a workflow artifact, creates a GitHub Release, and publishes to PyPI through Trusted Publishing.
• PyPI publishing does not use a stored API token. Configure a pending trusted publisher in PyPI with these values:
  • PyPI project name: datalogic-sdk
  • Owner: yair-ros
  • Repository name: datalogic-sdk
  • Workflow name: release.yml
  • Environment name: pypi

To create a GitHub Release and trigger PyPI publishing:

make release

If your virtual environment is not activated, pass the interpreter explicitly:

make release PYTHON=.venv/bin/python

Usage

from datalogic_sdk import DatalogicClient, Order, Origin, ShippingDetails

client = DatalogicClient("YOUR_AUTHENTICATION_TOKEN")

response = client.create_shipping(
    order=Order(
        id=123,
        number="ORD-123",
        shipping=ShippingDetails(
            street="Herzl",
            city="Tel Aviv",
            first_name="Dana",
            last_name="Cohen",
            postcode="6100000",
            house="10",
            apartment="3",
            email="[e-mail]",
            entrance="B",
            floor="4",
            phone="0501234567",
            # Use n_code only when the customer chose a pickup location.
            n_code="PICKUP_LOCATION_ID",
            # Use extra_fields for undocumented keys accepted by Datalogics.
            extra_fields={
                "site_code": "SITE-7",
            },
        ),
        comment="Leave at reception",
        extra_fields={
            "delivery_time": "16:00-20:00",
        },
    ),
    origin=Origin(
        contract="1234",
        company_name="Acme Ltd",
        city="Jerusalem",
        street="Jaffa",
        house="1",
        phone="021234567",
        email="[e-mail]",
    ),
)

print(response.status_code)
print(response.data)

Validation

The SDK validates the request before sending it:

• token is required.
• order.id and order.number are required.
• Required shipping fields: street, city, first_name, last_name, house, phone.
• Optional shipping fields: postcode, apartment, email, company, entrance, floor, n_code.
• order.extra_fields, order.shipping.extra_fields, and origin.extra_fields accept additional JSON-serializable keys for undocumented Datalogics fields.
• origin.contract must be exactly 4 characters.
• Required origin fields: company_name, city, street, house, phone, email.

Field Coverage

The official endpoint doc is narrower than the WooCommerce plugin shipped by Datalogics. The plugin sends the full WooCommerce order object, including standard shipping fields and order meta, to the same w_create_shipping endpoint.

Based on the plugin code, this SDK now explicitly supports the common shipping fields that appear in the Datalogics checkout UI:

• recipient name
• mobile phone
• email
• city
• street
• house
• entrance
• floor
• apartment
• pickup location (n_code)
• notes (order.comment)

For fields that exist in the Datalogics UI but are not clearly documented in the raw API contract, use extra_fields. Examples include custom site codes, delivery-time selections, or other account-specific keys.

Error Handling

from datalogic_sdk import (
    DatalogicAPIError,
    DatalogicClient,
    DatalogicValidationError,
    Order,
    Origin,
    ShippingDetails,
)

client = DatalogicClient("YOUR_AUTHENTICATION_TOKEN")
order = Order(
    id=123,
    number="ORD-123",
    shipping=ShippingDetails(
        street="Herzl",
        city="Tel Aviv",
        first_name="Dana",
        last_name="Cohen",
        house="10",
        phone="0501234567",
    ),
)
origin = Origin(
    contract="1234",
    company_name="Acme Ltd",
    city="Jerusalem",
    street="Jaffa",
    house="1",
    phone="021234567",
    email="[e-mail]",
)

try:
    response = client.create_shipping(order=order, origin=origin)
except DatalogicValidationError as exc:
    print(f"Invalid request: {exc}")
except DatalogicAPIError as exc:
    print(f"API error {exc.status_code}: {exc.response_body}")

Endpoint

By default the client calls:

https://connect.datalogics.co.il/rest/w_create_shipping

You can override the base URL for testing:

from datalogic_sdk import DatalogicClient

client = DatalogicClient("token", base_url="https://example.test")

Real API Test

The repository includes a local integration-test script:

PYTHONPATH=src python scripts/integration_test.py

The test reads local secrets and addresses from:

scripts/integration_test.env

That file is gitignored. The repository only includes:

scripts/integration_test.env.example

To use it:

1. Copy scripts/integration_test.env.example to scripts/integration_test.env.
2. Fill your real token and address data in scripts/integration_test.env.
3. Set DATALOGIC_CONFIRM_REAL_API_CALL=yes in that file.
4. Run make integration-test or PYTHONPATH=src python scripts/integration_test.py.
5. Read the warning in the terminal and type yes to approve the real shipment creation.

This can create a real shipment. Use a sandbox/test token if Datalogics provides one, and do not commit real tokens, customer phones, or real addresses.

The script fails fast if:

• scripts/integration_test.env does not exist
• DATALOGIC_CONFIRM_REAL_API_CALL is not yes
• a required value is missing
• a required value is still one of the example placeholders such as YOUR_TOKEN
• the terminal confirmation is not explicitly approved

License

This project is licensed under the MIT license. See LICENSE.