exportflow 1.0.0__py3-none-any.whl

exportflow-1.0.0.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.5
+Name: exportflow
+Version: 1.0.0
+Summary: The official Python SDK for the ExportFlow document processing and verification API
+Project-URL: Documentation, https://exportflow.app/developers
+Project-URL: Changelog, https://exportflow.app/developers/changelog
+Author: MeerTech Ltd
+License: Proprietary
+Keywords: documents,erp,exportflow,ocr,trade,verification
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Description-Content-Type: text/markdown
+
+# ExportFlow Python SDK
+
+The official Python client for the ExportFlow API: upload trade documents from
+your own software, have them classified and read, confirm what they say, and
+verify them against each other.
+
+```bash
+pip install exportflow
+```
+
+Python 3.9 or later. The only dependency is `httpx`.
+
+## Quick start
+
+```python
+from exportflow import ExportFlow
+
+client = ExportFlow(api_key="exfk_test_...")   # or set EXPORTFLOW_API_KEY
+
+# 1. Upload. The document is scanned, stored and queued for processing.
+document = client.documents.upload(file="bill_of_lading.pdf")
+
+# 2. Wait for processing (or use a webhook; see below).
+document = client.documents.wait(document.id)
+print(document.status, document.document_type)        # processed bill_of_lading
+
+# 3. Read what was extracted.
+extraction = client.documents.extraction(document.id)
+print(extraction.as_dict())                           # {"bl_number": "MEDU7741203", ...}
+
+# 4. Confirm what the documents say, then verify the shipment.
+client.records.confirm(document.shipment_id, {"port_of_discharge": "NHAVA SHEVA"})
+verification = client.verifications.create(document.shipment_id)
+verification = client.verifications.wait(verification.id)
+for finding in verification.findings:
+    print(finding.severity, finding.message)
+```
+
+A key that begins `exfk_test_` works in the **sandbox**: the same pipeline,
+separate data, never charged. A key that begins `exfk_live_` is **production**.
+Create both in the developer console.
+
+## How ExportFlow models documents
+
+A **shipment** is a set of documents that travel together: a bill of lading, a
+commercial invoice, a packing list, certificates. Documents are uploaded to a
+shipment, each is **processed** (classified, then its fields extracted), and
+the shipment is **verified** by checking the documents against each other and
+against the published rule set.
+
+`client.documents.upload(file=...)` with no `shipment_id` creates a shipment
+for the document. To group several documents, create the shipment first:
+
+```python
+shipment = client.shipments.create(reference="PO-7741", origin_country="NG",
+                                   destination_country="IN")
+for path in ("bl.pdf", "invoice.pdf", "packing_list.pdf"):
+    client.documents.upload(file=path, shipment_id=shipment.id)
+```
+
+### Why you confirm before you verify
+
+Verification refuses to start (`ConflictError`, code `not_confirmed`) until the
+shipment's record has been confirmed. This is deliberate. If a field was
+misread, every finding computed from it would be wrong, in both directions.
+Show your user what was read (`client.records.get(shipment_id)`), let them
+confirm or correct it, and send that with `client.records.confirm(...)`.
+Confirm what the document *says*, not what it should say: verification is what
+finds the error.
+
+## Webhooks
+
+Polling works; webhooks are better. Register an endpoint once:
+
+```python
+endpoint = client.webhook_endpoints.create(
+    "https://erp.example.com/hooks/exportflow",
+    event_types=["document.processing.completed", "verification.completed"],
+)
+print(endpoint.signing_secret)   # whsec_...  store this
+```
+
+Verify every delivery before trusting it:
+
+```python
+from exportflow import webhooks, SignatureVerificationError
+
+def handle(request):
+    try:
+        event = webhooks.construct_event(
+            payload=request.body,                               # raw bytes
+            signature=request.headers["ExportFlow-Signature"],
+            secret=WEBHOOK_SECRET,
+        )
+    except SignatureVerificationError:
+        return 400
+    if already_handled(event.id):          # deliveries are at-least-once
+        return 200
+    if event.type == "document.processing.completed":
+        document_id = event.data["document"]["id"]
+        ...
+    return 200
+```
+
+Answer with any `2xx` within 10 seconds. Anything else is retried with
+increasing delays for about two and a half hours. An event carries identifiers
+and statuses, never document content: fetch the resource to read it.
+
+| Event | When |
+|---|---|
+| `document.uploaded` | A document was accepted, scanned and stored |
+| `document.processing.started` | Classification began |
+| `document.processing.completed` | The document was classified and read |
+| `document.processing.failed` | Processing stopped; `GET` the document for why |
+| `verification.completed` | A verification finished; fetch it for the findings |
+| `verification.failed` | A verification could not run |
+| `billing.invoice.generated` | An invoice was issued to your organisation |
+
+## Errors
+
+Every error is an `exportflow.ExportFlowError`. One returned by the API is an
+`APIError` with a stable `code`, the HTTP `status_code` and a `request_id` to
+quote to support. Branch on the type or the code, never on the message.
+
+```python
+import exportflow
+
+try:
+    client.verifications.create(shipment_id)
+except exportflow.ConflictError as error:
+    if error.code == "not_confirmed":
+        ...                                   # ask the user to confirm the record
+except exportflow.QuotaExceededError:
+    ...                                       # the month's allowance is used up
+except exportflow.RateLimitError as error:
+    time.sleep(error.retry_after or 5)
+except exportflow.APIConnectionError:
+    ...                                       # safe to retry later
+```
+
+| Exception | HTTP | Meaning |
+|---|---|---|
+| `AuthenticationError` | 401 | Key missing, wrong, revoked or expired |
+| `PermissionDeniedError` | 403 | Missing scope, suspended account, network not allowed |
+| `NotFoundError` | 404 | No such resource in this organisation and environment |
+| `ConflictError` | 409 | Not possible in the current state (e.g. `not_confirmed`) |
+| `InvalidRequestError` | 400, 422 | The request is wrong; do not retry |
+| `RateLimitError` | 429 | Slow down; see `retry_after` |
+| `QuotaExceededError` | 429 | Allowance or spending limit reached for the period |
+| `SDKVersionUnsupportedError` | 426 | Upgrade this SDK |
+| `ServerError` | 5xx | ExportFlow's fault; retried automatically |
+| `APIConnectionError`, `APITimeoutError` | none | The API could not be reached |
+
+## Retries and idempotency
+
+The client retries connection failures, timeouts, `429 rate_limited` and `5xx`
+up to `max_retries` times (default 2), with backoff, honouring `Retry-After`.
+
+Every request that changes something carries an `Idempotency-Key`, and a retry
+sends the *same* key and the *same* body, so the work is done once however many
+times it is sent. To make your own retries safe across process restarts, pass
+your own key:
+
+```python
+client.documents.upload(file="bl.pdf", shipment_id=sid, idempotency_key=f"upload-{erp_document_id}")
+```
+
+Uploading the same file to the same shipment twice returns the first document
+(`duplicate=True`) and is not charged again.
+
+## Usage and charges
+
+```python
+usage = client.usage.get()            # this month; or client.usage.get("2026-10")
+for meter in usage.meters:
+    print(meter.name, meter.succeeded, "of", meter.quota or "unlimited")
+print(usage.estimated_charge, usage.currency)
+```
+
+Requests are not charged. Usage is recorded when work completes: a document
+accepted, a document processed, a verification completed. Sandbox usage is
+measured and never charged. Charges are estimates until an invoice is issued.
+
+## Configuration
+
+```python
+ExportFlow(
+    api_key=None,          # default: EXPORTFLOW_API_KEY
+    base_url=None,         # default: EXPORTFLOW_BASE_URL or https://api.exportflow.app
+    timeout=60.0,          # seconds per response
+    max_retries=2,
+    http_client=None,      # your own httpx.Client: proxies, TLS, tests
+)
+```
+
+The client is safe to share between threads. Use it as a context manager, or
+call `close()`, to release its connections.
+
+## Versioning
+
+This SDK follows semantic versioning and speaks version 1 of the API. Within
+version 1 the API only adds; nothing is removed or changed in meaning, so this
+SDK keeps working as the API grows, and unknown fields are available on every
+model's `.raw`. If the server ever reports a different major version the
+client raises `IncompatibleAPIVersionError` rather than misread a response.
+See `CHANGELOG.md`.

exportflow-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+exportflow/__init__.py,sha256=_j4jIjZpnLzTqkRSaQtK8WcPQNwA1pQaqiyIUyn65Uk,2009
+exportflow/_client.py,sha256=tHm4BedY4hvowBdfNMyWFscRYbkyKFh07x6s0wL_XUE,23490
+exportflow/_errors.py,sha256=GMeaOE3dkKZWZw0bBLV-q0bj6FjdB6zpVG1s30MJ3SA,4139
+exportflow/_models.py,sha256=cN0a-dSgaz2iMFPiEVLnxqbJq85y_D-YGS2I63ZOzTM,9432
+exportflow/_version.py,sha256=2PZkUmAuO6RtbMAGbuvx-dbkFjjEE4gFF_JrZB8wruY,384
+exportflow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+exportflow/webhooks.py,sha256=zEfp_fdqrruHaTW-ZcNQS3n9d__DECEEiE-CJDuTgfo,3028
+exportflow-1.0.0.dist-info/METADATA,sha256=Yh5NmGtOaOwFKwJnJpssG_ATvt0BHzDQo_eBAZ_bbME,8766
+exportflow-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+exportflow-1.0.0.dist-info/RECORD,,

exportflow-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any