alegra-e-provider 0.0.1__py3-none-any.whl

alegra/client.py

@@ -0,0 +1,141 @@
+import requests
+import httpx
+
+from alegra.config import ApiConfig
+from alegra.models.company import Company
+from alegra.models.dian import DianResource
+from alegra.models.invoice import Invoice, InvoiceResponse, FileResponse
+from alegra.models.payroll import Payroll
+from alegra.models.test_set import TestSet
+from alegra.resources.factory import ResourceFactory
+
+
+class ApiClient:
+    def __init__(self, config: ApiConfig, async_mode=False):
+        self.config = config
+        self.base_url = self.config.get_base_url()
+        self.async_mode = async_mode
+        self._initialize_resources()
+
+    async def _async_request(self, method, endpoint, **kwargs):
+        url = f"{self.base_url}/{endpoint}"
+        async with httpx.AsyncClient(
+            headers={"Authorization": f"Bearer {self.config.api_key}"}, timeout=30.0
+        ) as client:
+            response = await client.request(method, url, **kwargs)
+            return response.json()
+
+    def _sync_request(self, method, endpoint, **kwargs):
+        url = f"{self.base_url}/{endpoint}"
+        with requests.Session() as session:
+            session.headers.update({"Authorization": f"Bearer {self.config.api_key}"})
+            response = session.request(method, url, **kwargs)
+            return response.json()
+
+    def _request(self, method, endpoint, **kwargs):
+        if self.async_mode:
+            return self._async_request(method, endpoint, **kwargs)
+        else:
+            return self._sync_request(method, endpoint, **kwargs)
+
+    def _initialize_resources(self):
+        self.company = ResourceFactory(
+            self,
+            "company",
+            self._request,
+            {
+                "get": {
+                    "model": Company,
+                    "response_model": Company,
+                    "response_key": "company",
+                },
+                "update": {
+                    "model": Company,
+                    "response_model": Company,
+                    "response_key": "company",
+                },
+            },
+        )
+        self.companies = ResourceFactory(
+            self,
+            "companies",
+            self._request,
+            {
+                "create": {
+                    "model": Company,
+                    "response_model": Company,
+                    "response_key": "company",
+                },
+                "get": {
+                    "model": Company,
+                    "response_model": Company,
+                    "response_key": "company",
+                },
+                "update": {
+                    "model": Company,
+                    "response_model": Company,
+                    "response_key": "company",
+                },
+                "list": {
+                    "model": Company,
+                    "response_model": Company,
+                    "response_key": "companies",
+                },
+            },
+        )
+        self.payrolls = ResourceFactory(
+            self,
+            "payrolls",
+            self._request,
+            {
+                "create": {"model": Payroll, "response_key": "payroll"},
+                "get": {"model": Payroll, "response_key": "payroll"},
+                "update": {"model": Payroll, "response_key": "payroll"},
+                "list": {"model": Payroll, "response_key": "payrolls"},
+                "perform__replace": {"model": Payroll, "response_key": "payroll"},
+                "perform__cancel": {"model": Payroll, "response_key": "payroll"},
+            },
+        )
+        self.dian = ResourceFactory(
+            self,
+            "dian",
+            self._request,
+            {"list": {"model": DianResource, "response_key": "dian"}},
+        )
+        self.test_sets = ResourceFactory(
+            self,
+            "test-sets",
+            self._request,
+            {
+                "create": {"model": TestSet, "response_key": "test_set"},
+                "get": {"model": TestSet, "response_key": "test_set"},
+            },
+        )
+        self.invoices = ResourceFactory(
+            self,
+            "invoices",
+            self._request,
+            {
+                "create": {
+                    "model": Invoice,
+                    "response_model": InvoiceResponse,
+                    "response_key": "invoice",
+                },
+                "get": {
+                    "model": Invoice,
+                    "response_model": InvoiceResponse,
+                    "response_key": "invoice",
+                },
+                "perform__file_xml": {
+                    "model": FileResponse,
+                    "endpoint_suffix": "files/XML",
+                    "response_model": FileResponse,
+                    "response_key": "file",
+                },
+                "list": {
+                    "model": InvoiceResponse,
+                    "response_model": InvoiceResponse,
+                    "response_key": "invoices",
+                },
+            },
+        )

alegra/config.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel
+
+
+class ApiConfig(BaseModel):
+    api_key: str
+    environment: str
+
+    def get_base_url(self):
+        if self.environment == 'sandbox':
+            return 'https://sandbox-api.alegra.com/e-provider/col/v1'
+        elif self.environment == 'production':
+            return 'https://api.alegra.com/e-provider/col/v1'
+        else:
+            raise ValueError("Invalid environment. Choose 'sandbox' or 'production'.")

alegra/models/address.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+
+
+class Address(BaseModel):
+    address: str = ""
+    city: str = ""
+    department: str = ""
+    country: str = ""

alegra/models/company.py

@@ -0,0 +1,105 @@
+import re
+from typing import Dict, Optional
+
+from pydantic import BaseModel, EmailStr, field_validator, model_validator
+
+from .address import Address
+
+IDENTIFICATION_TYPES = [
+    "11",
+    "12",
+    "13",
+    "21",
+    "22",
+    "31",
+    "41",
+    "42",
+    "47",
+    "48",
+    "50",
+    "91",
+]
+
+
+class Webhook(BaseModel):
+    url: str = ""
+    headers: Dict[str, str] = {}
+    status: str = ""
+
+
+class Webhooks(BaseModel):
+    general: Dict[str, Webhook] = {}
+    payrolls: Dict[str, Webhook] = {}
+
+
+class Certificate(BaseModel):
+    name: str = ""
+    extension: str = ""
+    content: str = ""
+    password: str = ""
+    issuerName: str = ""
+    startDate: str = ""
+    endDate: str = ""
+    serialNumber: str = ""
+
+
+class GovernmentStatus(BaseModel):
+    payrolls: str = ""
+
+
+class NotificationByEmail(BaseModel):
+    enabled: bool = False
+
+
+class Company(BaseModel):
+    id: Optional[str] = None
+    name: str
+    tradeName: Optional[str] = None
+    identification: str
+    dv: str
+    useAlegraCertificate: bool
+    organizationType: int
+    identificationType: str
+    regimeCode: str = ""
+    email: EmailStr
+    phone: Optional[str] = ""
+    address: Address
+    governmentStatus: Optional[GovernmentStatus] = None
+    certificate: Optional[Certificate] = None
+    webhooks: Optional[Webhooks] = None
+    notificationByEmail: Optional[NotificationByEmail] = None
+
+    @field_validator("dv")
+    def validate_dv(cls, v):
+        if not re.match(r"^([0-9]{1})$", v):
+            raise ValueError("dv must be a single digit")
+        return v
+
+    @field_validator("identificationType")
+    def validate_identificationType(cls, v):
+        if len(v) > 2:
+            raise ValueError("identificationType must have a maximum length of 2")
+        if v not in IDENTIFICATION_TYPES:
+            raise ValueError(
+                f"identificationType must be one of the allowed values: {', '.join(IDENTIFICATION_TYPES)}"
+            )
+        return v
+
+    @field_validator("organizationType")
+    def validate_organizationType(cls, v):
+        if v not in [1, 2]:
+            raise ValueError("organizationType must be 1 or 2")
+        return v
+
+    @model_validator(mode="before")
+    def check_certificate(cls, values):
+        use_alegra_certificate = values.get("useAlegraCertificate")
+        if use_alegra_certificate:
+            return values
+
+        certificate = values.get("certificate")
+        if not use_alegra_certificate and not certificate:
+            raise ValueError(
+                "certificate is required when useAlegraCertificate is False"
+            )
+        return values

alegra/models/customer.py

@@ -0,0 +1,17 @@
+from typing import Optional
+
+from pydantic import BaseModel, EmailStr
+
+from alegra.models.address import Address
+from alegra.models.phone_number import PhoneNumber
+
+
+class Customer(BaseModel):
+    name: str
+    organizationType: int
+    identificationType: str
+    identificationNumber: Optional[str]
+    dv: Optional[str]
+    email: Optional[EmailStr] = ""
+    address: Optional[Address] = None
+    phone: str = ""

alegra/models/dian.py

@@ -0,0 +1,6 @@
+from pydantic import BaseModel
+
+
+class DianResource(BaseModel):
+    id: str
+    name: str

alegra/models/invoice.py

@@ -0,0 +1,108 @@
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+from alegra.models.customer import Customer
+
+
+class Resolution(BaseModel):
+    resolutionNumber: str
+    prefix: str
+    minNumber: int
+    maxNumber: int
+    startDate: str
+    endDate: str
+    technicalKey: str
+
+
+class Taxes(BaseModel):
+    taxCode: str
+    taxAmount: float
+    taxPercentage: str
+    taxableAmount: float
+
+
+class Item(BaseModel):
+    code: str
+    description: str
+    price: float
+    quantity: int
+    unitCode: str
+    note: Optional[str] = ""
+    subtotal: float
+    taxAmount: float
+    total: float
+    discount: float
+    discountAmount: float
+    taxes: List[Taxes] = []
+
+
+class Payment(BaseModel):
+    paymentForm: str
+    paymentMethod: str
+    paymentDueDate: str
+
+
+class DiscountOrCharge(BaseModel):
+    isCharge: bool
+    reason: str
+    percentageAmount: float
+    amount: float
+    baseAmount: float
+
+
+class TotalAmounts(BaseModel):
+    grossTotal: float
+    taxableTotal: float
+    taxTotal: float
+    discountTotal: float
+    chargeTotal: float
+    advanceTotal: float
+    payableTotal: float
+    currencyCode: str
+
+
+class CompanyID(BaseModel):
+    id: str
+
+
+class Invoice(BaseModel):
+    documentType: str
+    resolution: Resolution
+    company: CompanyID
+    customer: Customer
+    number: int
+    note: Optional[str]
+    items: List[Item]
+    payments: List[Payment]
+    discountsAndCharges: List[DiscountOrCharge] = []
+    totalAmounts: TotalAmounts
+
+
+class GovernmentResponse(BaseModel):
+    code: str
+    message: str
+    errorMessages: List[str]
+
+
+class InvoiceResponse(BaseModel):
+    id: str
+    companyIdentification: str
+    customerIdentification: str
+    type: str
+    cufe: str
+    date: datetime
+    prefix: str
+    number: int
+    fullNumber: str
+    status: str
+    legalStatus: str
+    governmentResponse: GovernmentResponse
+    xmlFileName: str
+    zipFileName: str
+    qrCodeContent: str
+
+
+class FileResponse(BaseModel):
+    content: str

alegra/models/payroll.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+
+
+class Payroll(BaseModel):
+    id: str = None
+    prefix: str
+    number: int
+    governmentData: dict

alegra/models/phone_number.py

@@ -0,0 +1,12 @@
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class PhoneNumber(BaseModel):
+    country_code: int
+    national_number: int
+    extension: Optional[str] = None
+    italian_leading_zero: Optional[bool] = None
+    number_of_leading_zeros: Optional[int] = None
+    preferred_domestic_carrier_code: Optional[int] = None

alegra/models/test_set.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+
+
+class TestSet(BaseModel):
+    id: str
+    type: str
+    governmentId: str
+    idCompany: str

alegra/resources/base.py

@@ -0,0 +1,133 @@
+from typing import Callable, Dict
+
+from pydantic import BaseModel
+
+
+class ApiResource:
+    def __init__(
+        self,
+        client,
+        endpoint: str,
+        request_method: Callable,
+        actions_config: Dict[str, Dict[str, str]],
+    ):
+        self.client = client
+        self.endpoint = endpoint
+        self.request_method = request_method
+        self.actions_config = actions_config
+
+    def _is_action_allowed(self, action: str):
+        return action in self.actions_config
+
+    def _parse_response(self, response, action: str):
+        response_key = self.actions_config[action].get("response_key")
+        if response_key:
+            if not response_key in response:
+                if response.get("message"):
+                    raise ValueError(response.get("message"))
+                if response.get("errors"):
+                    raise ValueError(response.get("errors"))
+                raise ValueError(f"Response key '{response_key}' not found in response")
+            response_data = response.get(response_key, response)
+        else:
+            response_data = response
+        model = self.actions_config[action]["response_model"]
+        return model.model_validate(response_data)
+
+    def _prepare_data(self, data: BaseModel):
+        data = data.model_dump()
+        if "customer" in data:
+            customer_data = data["customer"]
+            if customer_data["dv"] is None:
+                del customer_data["dv"]
+        return {k: v for k, v in data.items() if v is not None}
+
+    def get(self, resource_id: str):
+        action = "get"
+        if not self._is_action_allowed(action):
+            raise NotImplementedError(
+                f"The action 'get' is not allowed for {self.endpoint}"
+            )
+        endpoint = f"{self.endpoint}/{resource_id}"
+        response = self.request_method("GET", endpoint)
+        return self._parse_response(response, action)
+
+    def create(self, data: BaseModel):
+        if self.client.async_mode:
+            return self.create_async(data)
+        else:
+            action = "create"
+            if not self._is_action_allowed(action):
+                raise NotImplementedError(
+                    f"The action 'create' is not allowed for {self.endpoint}"
+                )
+            response = self.request_method(
+                "POST", self.endpoint, json=self._prepare_data(data)
+            )
+            return self._parse_response(response, action)
+
+    async def create_async(self, data: BaseModel):
+        action = "create"
+        if not self._is_action_allowed(action):
+            raise NotImplementedError(
+                f"The action 'create' is not allowed for {self.endpoint}"
+            )
+        response = await self.request_method(
+            "POST", self.endpoint, json=self._prepare_data(data)
+        )
+        return self._parse_response(response, action)
+
+    def update(self, resource_id: str, data: BaseModel):
+        action = "update"
+        if not self._is_action_allowed(action):
+            raise NotImplementedError(
+                f"The action 'update' is not allowed for {self.endpoint}"
+            )
+        endpoint = f"{self.endpoint}/{resource_id}"
+        response = self.request_method("PATCH", endpoint, json=self._prepare_data(data))
+        return self._parse_response(response, action)
+
+    def delete(self, resource_id: str):
+        action = "delete"
+        if not self._is_action_allowed(action):
+            raise NotImplementedError(
+                f"The action 'delete' is not allowed for {self.endpoint}"
+            )
+        endpoint = f"{self.endpoint}/{resource_id}"
+        response = self.request_method("DELETE", endpoint)
+        return response.status_code == 204
+
+    def list(self, params=None):
+        action = "list"
+        if not self._is_action_allowed(action):
+            raise NotImplementedError(
+                f"The action 'list' is not allowed for {self.endpoint}"
+            )
+        response = self.request_method("GET", self.endpoint, params=params)
+        return [
+            self.actions_config[action]["model"].model_validate(item)
+            for item in response.get(
+                self.actions_config[action].get("response_key", [])
+            )
+        ]
+
+    def perform_subaction(
+        self, resource_id: str, subaction: str, data: BaseModel = None
+    ):
+        action = f"perform__{subaction}"
+        if not self._is_action_allowed(action):
+            raise NotImplementedError(
+                f"The subaction '{subaction}' is not allowed for {self.endpoint}"
+            )
+        endpoint_suffix = self.actions_config[action].get("endpoint_suffix", subaction)
+        endpoint = f"{self.endpoint}/{resource_id}/{endpoint_suffix}"
+        response = self.request_method(
+            self._request_method_for_subaction(subaction),
+            endpoint,
+            json=self._prepare_data(data) if data else {},
+        )
+        return self._parse_response(response, action)
+
+    @staticmethod
+    def _request_method_for_subaction(subaction: str):
+        return "POST" if subaction in ["replace", "cancel"] else "GET"

alegra/resources/factory.py

@@ -0,0 +1,36 @@
+from typing import Callable, Dict
+
+from pydantic import BaseModel
+
+from .base import ApiResource
+
+
+class ResourceFactory:
+    def __init__(
+        self,
+        client,
+        endpoint: str,
+        request_method: Callable,
+        actions_config: Dict[str, Dict[str, str]],
+    ):
+        self.resource = ApiResource(client, endpoint, request_method, actions_config)
+
+    def get(self, resource_id):
+        return self.resource.get(resource_id)
+
+    def create(self, data):
+        return self.resource.create(data)
+
+    def update(self, resource_id, data):
+        return self.resource.update(resource_id, data)
+
+    def delete(self, resource_id):
+        return self.resource.delete(resource_id)
+
+    def list(self, params=None):
+        return self.resource.list(params)
+
+    def perform_subaction(
+        self, resource_id: str, subaction: str, data: BaseModel = None
+    ):
+        return self.resource.perform_subaction(resource_id, subaction, data)

alegra_e_provider-0.0.1.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.2
+Name: alegra-e-provider
+Version: 0.0.1
+Summary: Alegra E-Provider, Python Wrapper for Alegra Electronic Provider API
+Author: Luis Martinez
+Requires-Python: >=3.6
+Requires-Dist: pydantic[email]==2.8.2
+Requires-Dist: requests==2.32.3
+Requires-Dist: httpx==0.27.2
+Dynamic: author
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

alegra_e_provider-0.0.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+alegra/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+alegra/client.py,sha256=icMG9yK-pT7ipRtwCqll2MRJO9qqaDCRUgF6bCYaKK4,4958
+alegra/config.py,sha256=0X1vmS2rcDcHPz_uP1QP-ui2Vr5JN2ufoWz4uw9c_-I,450
+alegra/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+alegra/models/address.py,sha256=Ze_XAwawYRjz6D1a-T555i5-u5YrVLH_kzMeOJd-nk0,147
+alegra/models/company.py,sha256=kdlLyfQLyGuK3r3rUZp7zFK5XfiH-35dUDQQPhcYBh8,2607
+alegra/models/customer.py,sha256=X9UvI_zageqdgq_mUp97FtFaMAyhqOOxGY9tzDkB7TI,416
+alegra/models/dian.py,sha256=ZJsxY-w05sWpyjW1VjIPdQdlEQ4Tj2OOwADn4qvjwZU,90
+alegra/models/invoice.py,sha256=tZxWdORR8tYRMVuoyAAwJDUh74kp7KO_5HZT431WGtQ,1992
+alegra/models/payroll.py,sha256=OVNz91R4E-R3jEXKelBc748dQXVw91aq5pcM35KfXIY,135
+alegra/models/phone_number.py,sha256=Bw8n62KFBdVUKUCH8Chg3KExEJJYjr8KcPn4GepY4o8,331
+alegra/models/test_set.py,sha256=hzR_8nBmoVljzybK3u6TZUJGlFJw3AM0rAiczLAASew,126
+alegra/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+alegra/resources/base.py,sha256=e3JDEL8Z-2S_mdg4kIC3U_gyUNgmqsTcnBk42HV5V4U,5135
+alegra/resources/factory.py,sha256=9SkaVj8G5sey0exScusCezZNWxipy7ejrkIIuxm2jRA,962
+alegra_e_provider-0.0.1.dist-info/METADATA,sha256=aZdNyriRAzb6kYf_A3RSrU0AxYXwH5Zwsw54JxuU_2Q,364
+alegra_e_provider-0.0.1.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+alegra_e_provider-0.0.1.dist-info/top_level.txt,sha256=NcYktmnWNtk9MEfrDm6zdm260Udm6SmW6gEczIgEefw,7
+alegra_e_provider-0.0.1.dist-info/RECORD,,

alegra_e_provider-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

alegra_e_provider-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+alegra