Skip to main content

Alegra API Client

This project provides an API client for the Alegra platform using the pydantic and requests libraries. The modular structure allows for flexible and extensible resource management.

Installation

  1. Clone the repository.
  2. Install the required dependencies:
    pip install -r requirements.txt
    

Configuration

Create a configuration object to handle API key and environment settings.

from config import ApiConfig

config = ApiConfig(api_key='your_api_key', environment='sandbox')

Usage

Initialize the API client with the configuration:

from client import ApiClient

client = ApiClient(config)

Company Operations

Create a Company

from models.company import Company, NotificationByEmail

company_data = Company(
    useAlegraCertificate=True,
    notificationByEmail=NotificationByEmail(enabled=True)
)
new_company = client.companies.create(company_data)
print(new_company.id, new_company.name)

Get a Company

company = client.companies.get("company_id")
print(company.id, company.name)

Update a Company

updated_data = Company(name="Updated Company Name")
updated_company = client.companies.update("company_id", updated_data)
print(updated_company.name)

List Companies

companies = client.companies.list()
for company in companies:
    print(company.id, company.name)

Payroll Operations

Create a Payroll

from models.payroll import Payroll

payroll_data = Payroll(
    prefix="NE",
    number=1,
    governmentData={"key": "value"}
)
new_payroll = client.payrolls.create(payroll_data)
print(new_payroll.id, new_payroll.prefix)

Get a Payroll

payroll = client.payrolls.get("payroll_id")
print(payroll.id, payroll.prefix)

Update a Payroll

updated_data = Payroll(prefix="NE", number=2)
updated_payroll = client.payrolls.update("payroll_id", updated_data)
print(updated_payroll.number)

List Payrolls

payrolls = client.payrolls.list()
for payroll in payrolls:
    print(payroll.id, payroll.prefix)

Replace a Payroll

replacement_data = Payroll(prefix="NE", number=2, governmentData={"key": "new_value"})
replaced_payroll = client.payrolls.perform_subaction("payroll_id", "replace", replacement_data)
print(replaced_payroll.id, replaced_payroll.number)

Cancel a Payroll

cancel_response = client.payrolls.perform_subaction("payroll_id", "cancel")
print(cancel_response)

DIAN Operations

List DIAN Resources

dian_resources = client.dian.list()
for resource in dian_resources:
    print(resource.id, resource.name)

Test Set Operations

Create a Test Set

from models.test_set import TestSet

test_set_data = TestSet(
    type="test",
    governmentId="gov123",
    idCompany="company_id"
)
new_test_set = client.test_sets.create(test_set_data)
print(new_test_set.id)

Get a Test Set

test_set = client.test_sets.get("test_set_id")
print(test_set.id, test_set.type)

Error Handling

Every error the client raises intentionally is an AlegraApiError:

  • AlegraConfigurationError: invalid ApiConfig (bad environment, blank api_key)
  • AlegraHttpError: an HTTP error response, or a network/transport failure. Carries .status_code (None for network errors), .url, and .response
  • AlegraResponseParseError: a "successful" response didn't have the expected shape
from alegra import AlegraApiError, AlegraHttpError

try:
    new_company = client.companies.create(company_data)
except AlegraHttpError as e:
    print(f"Request to {e.url} failed with status {e.status_code}")
except AlegraApiError as e:
    print(f"An error occurred: {e}")

Working with Pydantic Models

This library uses Pydantic V2 for data validation. When working with models, use the Pydantic V2 API:

Serializing Models to JSON

from alegra.models.company import Company

company = Company(...)

# ✅ Correct - Use model_dump_json() (Pydantic V2)
json_string = company.model_dump_json()

# ❌ Deprecated - Avoid using json() (will be removed in Pydantic V3)
json_string = company.json()  # Generates deprecation warning

Serializing Models to Dictionary

# ✅ Correct - Use model_dump() (Pydantic V2)
data_dict = company.model_dump()

# ❌ Deprecated - Avoid using dict() (will be removed in Pydantic V3)
data_dict = company.dict()  # Generates deprecation warning

For more information, see the Pydantic V2 Migration Guide.

License

This project is licensed under the MIT License.

Metadata

Release files for alegra-e-provider 0.0.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for alegra-e-provider 0.0.8
File Size Uploaded Provenance Actions
alegra_e_provider-0.0.8.tar.gz 35.1 kB With provenance Details for alegra_e_provider-0.0.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for alegra-e-provider 0.0.8
File Interpreter ABI Platform Actions
alegra_e_provider-0.0.8-py3-none-any.whl Python 3 none any Details for alegra_e_provider-0.0.8-py3-none-any.whl

Total release size: 49.5 kB

Release files / alegra_e_provider-0.0.8.tar.gz

Download URL alegra_e_provider-0.0.8.tar.gz
Size 35.1 kB
Tags Source
SHA-256 checksum
How to use checksums
b31aaba26ae8f7004fcd9452f535377a6ff31ce3610bd49d50766feeddb5272f
BLAKE2b-256 checksum
How to use checksums
ff64b7b5074008c93f7d0eaf197400fea9184f52e6b533147b04749110d1c01f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / alegra_e_provider-0.0.8-py3-none-any.whl

Download URL alegra_e_provider-0.0.8-py3-none-any.whl
Size 14.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
740f222a1c0783bcbbefa67fae0ce4c0b83e294f3d1a646f69c85096005c0455
BLAKE2b-256 checksum
How to use checksums
a4020c4088f2f7aa39cb22265b5ad9c117aedcd2b2f739386619e1edee65a3ce
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for alegra-e-provider 0.0.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for alegra_e_provider-0.0.8.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page