fiskit 0.1.0__tar.gz

fiskit-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.pyc
+dist/

fiskit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FisKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fiskit-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: fiskit
+Version: 0.1.0
+Summary: Official Python client for the FisKit API: electronic invoices with ARCA (ex AFIP) in a single request.
+Project-URL: Homepage, https://fiskit.com.ar
+Project-URL: Documentation, https://fiskit.com.ar/developers
+License-Expression: MIT
+License-File: LICENSE
+Keywords: afip,arca,argentina,cae,factura electronica,fiskit,invoicing
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# FisKit para Python
+
+Cliente oficial de la API de [FisKit](https://fiskit.com.ar): facturas electrónicas de ARCA (ex AFIP) con un solo pedido. Sin dependencias, para Python 3.10 o superior.
+
+```bash
+pip install fiskit
+```
+
+## Tu primera factura
+
+```python
+from fiskit import Fiskit
+
+fiskit = Fiskit()  # lee FISKIT_API_KEY
+
+invoice = fiskit.invoices.create(
+    {"voucher_type": "invoice_c", "amounts": {"total": 1500}},
+    idempotency_key="venta-8812",  # el id de tu venta: un reintento nunca duplica la factura
+)
+
+print(invoice["number"], invoice["cae"])
+```
+
+Las claves `sk_test_...` emiten en la homologación de ARCA, sin validez fiscal. Las `sk_live_...` emiten facturas reales. Las dos se crean en el panel.
+
+## Qué podés hacer
+
+```python
+fiskit.invoices.retrieve(invoice_id)                  # estado actual
+pdf = fiskit.invoices.pdf(invoice_id)                 # bytes del PDF con el QR de ARCA
+fiskit.invoices.email(invoice_id, "cliente@example.com")
+fiskit.taxpayers.retrieve(30712345671)                # nombre, domicilio y condición frente al IVA
+```
+
+Si ARCA no responde o se corta la conexión, el cliente reintenta solo con la misma `Idempotency-Key`. Si no pasás una, se genera automáticamente.
+
+Los errores llegan como `FiskitError`, con `status`, `type`, `code`, `message`, `param` y `request_id`.
+
+## Webhooks
+
+```python
+from fiskit import verify_webhook
+
+# Flask: usá el cuerpo crudo, antes de parsearlo
+@app.post("/webhooks/fiskit")
+def webhook():
+    event = verify_webhook(request.get_data(), request.headers, os.environ["FISKIT_WEBHOOK_SECRET"])
+    if event["type"] == "invoice.authorized":
+        ...  # event["data"]["object"] es la factura
+    return "", 200
+```
+
+Documentación completa: https://fiskit.com.ar/developers

fiskit-0.1.0/README.md

@@ -0,0 +1,53 @@
+# FisKit para Python
+
+Cliente oficial de la API de [FisKit](https://fiskit.com.ar): facturas electrónicas de ARCA (ex AFIP) con un solo pedido. Sin dependencias, para Python 3.10 o superior.
+
+```bash
+pip install fiskit
+```
+
+## Tu primera factura
+
+```python
+from fiskit import Fiskit
+
+fiskit = Fiskit()  # lee FISKIT_API_KEY
+
+invoice = fiskit.invoices.create(
+    {"voucher_type": "invoice_c", "amounts": {"total": 1500}},
+    idempotency_key="venta-8812",  # el id de tu venta: un reintento nunca duplica la factura
+)
+
+print(invoice["number"], invoice["cae"])
+```
+
+Las claves `sk_test_...` emiten en la homologación de ARCA, sin validez fiscal. Las `sk_live_...` emiten facturas reales. Las dos se crean en el panel.
+
+## Qué podés hacer
+
+```python
+fiskit.invoices.retrieve(invoice_id)                  # estado actual
+pdf = fiskit.invoices.pdf(invoice_id)                 # bytes del PDF con el QR de ARCA
+fiskit.invoices.email(invoice_id, "cliente@example.com")
+fiskit.taxpayers.retrieve(30712345671)                # nombre, domicilio y condición frente al IVA
+```
+
+Si ARCA no responde o se corta la conexión, el cliente reintenta solo con la misma `Idempotency-Key`. Si no pasás una, se genera automáticamente.
+
+Los errores llegan como `FiskitError`, con `status`, `type`, `code`, `message`, `param` y `request_id`.
+
+## Webhooks
+
+```python
+from fiskit import verify_webhook
+
+# Flask: usá el cuerpo crudo, antes de parsearlo
+@app.post("/webhooks/fiskit")
+def webhook():
+    event = verify_webhook(request.get_data(), request.headers, os.environ["FISKIT_WEBHOOK_SECRET"])
+    if event["type"] == "invoice.authorized":
+        ...  # event["data"]["object"] es la factura
+    return "", 200
+```
+
+Documentación completa: https://fiskit.com.ar/developers

fiskit-0.1.0/fiskit/__init__.py

@@ -0,0 +1,179 @@
+"""Official Python client for the FisKit API: electronic invoices with ARCA (ex AFIP).
+
+No dependencies: it uses only the standard library.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Mapping, Optional
+
+__all__ = ["Fiskit", "FiskitError", "verify_webhook"]
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.fiskit.com.ar"
+_RETRYABLE = {408, 409, 429, 500, 502, 503, 504}
+
+
+class FiskitError(Exception):
+    """An error answered by the API, or a network failure (status 0)."""
+
+    def __init__(self, status: int, type: str, code: str, message: str, param: Optional[str] = None,
+                 request_id: Optional[str] = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.type = type
+        self.code = code
+        self.message = message
+        self.param = param
+        self.request_id = request_id
+        self.body = body
+
+
+class Fiskit:
+    """Client of the FisKit API.
+
+    >>> fiskit = Fiskit()  # reads FISKIT_API_KEY
+    >>> invoice = fiskit.invoices.create({"voucher_type": "invoice_c", "amounts": {"total": 1500}},
+    ...                                  idempotency_key="sale-8812")
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: str = DEFAULT_BASE_URL, max_retries: int = 2,
+                 timeout: float = 60.0, opener: Any = None):
+        self.api_key = api_key or os.environ.get("FISKIT_API_KEY")
+        if not self.api_key:
+            raise ValueError("Missing API key: pass it or set FISKIT_API_KEY")
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self._open = opener or urllib.request.urlopen
+        self.invoices = _Invoices(self)
+        self.taxpayers = _Taxpayers(self)
+
+    def request(self, method: str, path: str, body: Any = None, idempotency_key: Optional[str] = None,
+                binary: bool = False) -> Any:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/pdf" if binary else "application/json",
+            "User-Agent": f"fiskit-python/{__version__}",
+        }
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        retry_allowed = method == "GET" or bool(idempotency_key)
+
+        attempt = 0
+        while True:
+            request = urllib.request.Request(self.base_url + path, data=data, headers=headers, method=method)
+            try:
+                with self._open(request, timeout=self.timeout) as response:
+                    content = response.read()
+                    if binary:
+                        return content
+                    return json.loads(content) if content else None
+            except urllib.error.HTTPError as error:
+                if error.code in _RETRYABLE and retry_allowed and attempt < self.max_retries:
+                    _wait(attempt, error.headers.get("Retry-After") if error.headers else None)
+                    attempt += 1
+                    continue
+                raise _api_error(error) from None
+            except (urllib.error.URLError, TimeoutError, ConnectionError) as error:
+                # Without an idempotency key a POST is not repeated: it might have been processed
+                if retry_allowed and attempt < self.max_retries:
+                    _wait(attempt, None)
+                    attempt += 1
+                    continue
+                raise FiskitError(0, "connection_error", "network", str(error)) from None
+
+
+class _Invoices:
+    def __init__(self, client: Fiskit):
+        self._client = client
+
+    def create(self, body: Mapping[str, Any], idempotency_key: Optional[str] = None) -> dict:
+        """Issues an invoice. Without idempotency_key one is generated, so retries never issue twice."""
+        return self._client.request("POST", "/v1/invoices", body=dict(body),
+                                    idempotency_key=idempotency_key or str(uuid.uuid4()))
+
+    def retrieve(self, invoice_id: str) -> dict:
+        return self._client.request("GET", f"/v1/invoices/{urllib.parse.quote(invoice_id)}")
+
+    def pdf(self, invoice_id: str) -> bytes:
+        """The voucher PDF as bytes."""
+        return self._client.request("GET", f"/v1/invoices/{urllib.parse.quote(invoice_id)}/pdf", binary=True)
+
+    def email(self, invoice_id: str, email: Optional[str] = None) -> dict:
+        """Emails the PDF to the customer; without email, to receiver.email of the invoice."""
+        return self._client.request("POST", f"/v1/invoices/{urllib.parse.quote(invoice_id)}/email",
+                                    body={"email": email} if email else {})
+
+
+class _Taxpayers:
+    def __init__(self, client: Fiskit):
+        self._client = client
+
+    def retrieve(self, cuit: int | str) -> dict:
+        """Name, address and VAT condition of a CUIT, from the ARCA registry."""
+        return self._client.request("GET", f"/v1/taxpayers/{urllib.parse.quote(str(cuit))}")
+
+
+def verify_webhook(raw_body: str | bytes, headers: Mapping[str, str], secret: str, *,
+                   tolerance_seconds: int = 300, now: Optional[float] = None) -> dict:
+    """Checks a webhook (Standard Webhooks) and returns the parsed event.
+
+    Raises ValueError if the signature is wrong or too old. Pass the raw body as received.
+    """
+    lowered = {key.lower(): value for key, value in headers.items()}
+    message_id = lowered.get("webhook-id")
+    timestamp = lowered.get("webhook-timestamp")
+    signatures = lowered.get("webhook-signature")
+    if not message_id or not timestamp or not signatures:
+        raise ValueError("Missing webhook headers")
+    current = time.time() if now is None else now
+    if abs(current - int(timestamp)) > tolerance_seconds:
+        raise ValueError("Webhook timestamp out of tolerance")
+    body = raw_body.decode("utf-8") if isinstance(raw_body, bytes) else raw_body
+    key = base64.b64decode(secret.removeprefix("whsec_"))
+    expected = base64.b64encode(
+        hmac.new(key, f"{message_id}.{timestamp}.{body}".encode("utf-8"), hashlib.sha256).digest()).decode()
+    for candidate in signatures.split(" "):
+        if hmac.compare_digest(candidate.removeprefix("v1,"), expected):
+            return json.loads(body)
+    raise ValueError("Invalid webhook signature")
+
+
+def _wait(attempt: int, retry_after: Optional[str]) -> None:
+    try:
+        seconds = float(retry_after) if retry_after else 0
+    except ValueError:
+        seconds = 0
+    time.sleep(min(seconds, 30) if seconds > 0 else 0.5 * 2 ** attempt)
+
+
+def _api_error(error: urllib.error.HTTPError) -> FiskitError:
+    try:
+        payload = json.loads(error.read() or b"null")
+    except ValueError:
+        payload = None
+    details = payload.get("error", {}) if isinstance(payload, dict) else {}
+    return FiskitError(
+        status=error.code,
+        type=details.get("type", "api_error"),
+        code=details.get("code", f"http_{error.code}"),
+        message=details.get("message", f"HTTP {error.code}"),
+        param=details.get("param"),
+        request_id=details.get("request_id") or (error.headers.get("Request-Id") if error.headers else None),
+        body=payload,
+    )

fiskit-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fiskit"
+version = "0.1.0"
+description = "Official Python client for the FisKit API: electronic invoices with ARCA (ex AFIP) in a single request."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["arca", "afip", "factura electronica", "invoicing", "argentina", "cae", "fiskit"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Office/Business :: Financial :: Accounting",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://fiskit.com.ar"
+Documentation = "https://fiskit.com.ar/developers"
+
+[tool.hatch.build.targets.wheel]
+packages = ["fiskit"]

fiskit-0.1.0/tests/test_client.py

@@ -0,0 +1,137 @@
+import base64
+import hashlib
+import hmac
+import io
+import json
+import unittest
+import urllib.error
+from email.message import Message
+
+from fiskit import Fiskit, FiskitError, verify_webhook
+
+INVOICE = {"id": "inv_1", "object": "invoice", "status": "authorized", "number": 42, "cae": "76451234567890"}
+
+
+class _Response(io.BytesIO):
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+def _http_error(status, body, headers=None):
+    message = Message()
+    for key, value in (headers or {}).items():
+        message[key] = value
+    return urllib.error.HTTPError("https://api.test", status, "error", message, io.BytesIO(json.dumps(body).encode()))
+
+
+class FakeOpener:
+    """Answers from a list and records every request."""
+
+    def __init__(self, answers):
+        self.answers = list(answers)
+        self.requests = []
+
+    def __call__(self, request, timeout):
+        self.requests.append(request)
+        answer = self.answers.pop(0)
+        if isinstance(answer, Exception):
+            raise answer
+        return _Response(answer if isinstance(answer, bytes) else json.dumps(answer).encode())
+
+
+class ClientTest(unittest.TestCase):
+
+    def test_creates_an_invoice_with_the_key_the_body_and_an_idempotency_key(self):
+        opener = FakeOpener([INVOICE])
+        client = Fiskit("sk_test_x", base_url="https://api.test", opener=opener)
+
+        invoice = client.invoices.create({"voucher_type": "invoice_c", "amounts": {"total": 1500}},
+                                         idempotency_key="sale-1")
+
+        self.assertEqual(invoice["cae"], "76451234567890")
+        request = opener.requests[0]
+        self.assertEqual(request.full_url, "https://api.test/v1/invoices")
+        self.assertEqual(request.get_method(), "POST")
+        self.assertEqual(request.get_header("Authorization"), "Bearer sk_test_x")
+        self.assertEqual(request.get_header("Idempotency-key"), "sale-1")
+        self.assertEqual(json.loads(request.data), {"voucher_type": "invoice_c", "amounts": {"total": 1500}})
+
+    def test_retries_an_outage_with_the_same_generated_idempotency_key(self):
+        opener = FakeOpener([
+            _http_error(503, {"error": {"code": "authority_unavailable"}}, {"Retry-After": "0"}),
+            urllib.error.URLError("reset"),
+            INVOICE,
+        ])
+        client = Fiskit("sk_test_x", opener=opener)
+
+        client.invoices.create({"voucher_type": "invoice_c", "amounts": {"total": 1}})
+
+        keys = {request.get_header("Idempotency-key") for request in opener.requests}
+        self.assertEqual(len(opener.requests), 3)
+        self.assertEqual(len(keys), 1)
+        self.assertTrue(next(iter(keys)))
+
+    def test_api_errors_become_a_fiskit_error(self):
+        opener = FakeOpener([_http_error(400, {"error": {
+            "type": "invalid_request_error", "code": "parameter_invalid", "message": "Bad total",
+            "param": "amounts.total", "request_id": "req_1"}})])
+        client = Fiskit("sk_test_x", opener=opener)
+
+        with self.assertRaises(FiskitError) as raised:
+            client.invoices.retrieve("inv_1")
+
+        error = raised.exception
+        self.assertEqual((error.status, error.code, error.param, error.request_id),
+                         (400, "parameter_invalid", "amounts.total", "req_1"))
+
+    def test_the_pdf_comes_back_as_bytes_and_the_taxpayer_by_cuit(self):
+        opener = FakeOpener([b"%PDF-1.7", {"object": "taxpayer", "vat_condition": "registered"}])
+        client = Fiskit("sk_test_x", opener=opener)
+
+        self.assertEqual(client.invoices.pdf("inv_1"), b"%PDF-1.7")
+        self.assertEqual(client.taxpayers.retrieve(30712345671)["vat_condition"], "registered")
+        self.assertEqual(opener.requests[0].get_header("Accept"), "application/pdf")
+        self.assertTrue(opener.requests[1].full_url.endswith("/v1/taxpayers/30712345671"))
+
+    def test_a_post_without_idempotency_key_is_never_retried(self):
+        opener = FakeOpener([urllib.error.URLError("reset")])
+        client = Fiskit("sk_test_x", opener=opener)
+
+        with self.assertRaises(FiskitError) as raised:
+            client.invoices.email("inv_1", "a@b.com")
+
+        self.assertEqual(raised.exception.code, "network")
+        self.assertEqual(len(opener.requests), 1)
+
+
+class WebhookTest(unittest.TestCase):
+    # Example from the Standard Webhooks specification
+    SECRET = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
+    HEADERS = {
+        "webhook-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
+        "webhook-timestamp": "1614265330",
+        "webhook-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
+    }
+
+    def test_verifies_the_specification_example(self):
+        event = verify_webhook('{"test": 2432232314}', self.HEADERS, self.SECRET, now=1614265330)
+        self.assertEqual(event, {"test": 2432232314})
+
+    def test_rejects_tampering_and_old_messages(self):
+        with self.assertRaisesRegex(ValueError, "Invalid"):
+            verify_webhook('{"test": 1}', self.HEADERS, self.SECRET, now=1614265330)
+        with self.assertRaisesRegex(ValueError, "tolerance"):
+            verify_webhook('{"test": 2432232314}', self.HEADERS, self.SECRET, now=1614265330 + 3600)
+
+    def test_accepts_its_own_signature(self):
+        key = base64.b64decode(self.SECRET.removeprefix("whsec_"))
+        signature = base64.b64encode(hmac.new(key, b"evt_1.1614265330.{}", hashlib.sha256).digest()).decode()
+        headers = {"Webhook-Id": "evt_1", "Webhook-Timestamp": "1614265330", "Webhook-Signature": f"v1,{signature}"}
+        self.assertEqual(verify_webhook(b"{}", headers, self.SECRET, now=1614265330), {})
+
+
+if __name__ == "__main__":
+    unittest.main()