{"id":26047908,"url":"https://github.com/bonifaciocalindoro/holded-python","last_synced_at":"2025-08-25T18:44:54.994Z","repository":{"id":280989651,"uuid":"943861451","full_name":"BonifacioCalindoro/holded-python","owner":"BonifacioCalindoro","description":"A comprehensive Python wrapper for the Holded API, providing both synchronous and asynchronous clients with complete coverage of all API endpoints. Features type hints, Pydantic models for request/response validation, robust error handling, and detailed documentation. ","archived":false,"fork":false,"pushed_at":"2025-05-21T08:30:41.000Z","size":106,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-24T01:36:06.382Z","etag":null,"topics":["accounting","api","client","holded","invoices","python","wrapper"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/holded-python/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BonifacioCalindoro.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-06T11:41:07.000Z","updated_at":"2025-05-21T08:30:45.000Z","dependencies_parsed_at":"2025-03-06T11:46:51.697Z","dependency_job_id":"861f6f8c-059e-4b9f-b63e-2f1a192d6857","html_url":"https://github.com/BonifacioCalindoro/holded-python","commit_stats":null,"previous_names":["bonifaciocalindoro/holded-python"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/BonifacioCalindoro/holded-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BonifacioCalindoro%2Fholded-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BonifacioCalindoro%2Fholded-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BonifacioCalindoro%2Fholded-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BonifacioCalindoro%2Fholded-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BonifacioCalindoro","download_url":"https://codeload.github.com/BonifacioCalindoro/holded-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BonifacioCalindoro%2Fholded-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272116668,"owners_count":24876266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-25T02:00:12.092Z","response_time":1107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accounting","api","client","holded","invoices","python","wrapper"],"created_at":"2025-03-07T23:14:59.099Z","updated_at":"2025-08-25T18:44:54.951Z","avatar_url":"https://github.com/BonifacioCalindoro.png","language":"Python","funding_links":["https://buymeacoffee.com/bonifaciocalindoro)!","https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee\u0026emoji=","https://buymeacoffee.com/bonifaciocalindoro"],"categories":[],"sub_categories":[],"readme":"# Holded API Python Wrapper\n\nA comprehensive Python wrapper for the Holded API, providing a clean, type-safe interface for interacting with Holded's services.\n\n**DISCLAIMER: This is an unofficial library for the Holded API. It is not affiliated with, officially maintained, or endorsed by Holded. The author(s) of this library are not responsible for any misuse or damage caused by using this code. Use at your own risk.**\n\n## Features\n\n- **Complete API Coverage**: Supports all Holded API endpoints across Invoice, CRM, Projects, Team, and Accounting services\n- **Type Safety**: Comprehensive Pydantic models for request and response validation\n- **Synchronous and Asynchronous**: Choose between synchronous and asynchronous clients based on your needs\n- **Pagination Handling**: Automatic pagination for list endpoints\n- **Error Handling**: Robust error handling with detailed exception hierarchy\n- **Rate Limiting**: Built-in rate limit handling with exponential backoff\n\n## Installation\n\n```bash\npip install holded-python\n```\n\n## Quick Start\n\n```python\nimport os\nfrom holded import HoldedClient\n\n# Initialize the client with your API key\napi_key = os.environ.get(\"HOLDED_API_KEY\")\nclient = HoldedClient(api_key=api_key)\n\n# List contacts\ncontacts = client.contacts.list(limit=10)\nfor contact in contacts.items:\n    print(f\"Contact: {contact.name} ({contact.id})\")\n\n# Create a new contact\nnew_contact = client.contacts.create(\n    name=\"Acme Inc.\",\n    email=\"info@acme.com\",\n    type=\"client\"\n)\nprint(f\"Created contact with ID: {new_contact.id}\")\n\n# Create an invoice\ninvoice = client.documents.create(\n    contact_id=new_contact.id,\n    type=\"invoice\",\n    date=\"2023-01-01\",\n    items=[\n        {\n            \"name\": \"Product A\",\n            \"units\": 2,\n            \"price\": 100\n        }\n    ]\n)\nprint(f\"Created invoice with ID: {invoice.id}\")\n```\n\n## Asynchronous Usage\n\n```python\nimport asyncio\nimport os\nfrom holded import AsyncHoldedClient\n\nasync def main():\n    api_key = os.environ.get(\"HOLDED_API_KEY\")\n    client = AsyncHoldedClient(api_key=api_key)\n    \n    # List contacts\n    contacts = await client.contacts.list(limit=10)\n    for contact in contacts.items:\n        print(f\"Contact: {contact.name} ({contact.id})\")\n    \n    # Don't forget to close the client\n    await client.close()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n## Enhanced Data Models\n\nThe wrapper includes comprehensive data models for all Holded API resources:\n\n### Base Models\n\n- `BaseModel`: Foundation for all models with Pydantic configuration\n- `BaseResponse`: Common response structure\n- `PaginationParams`: Parameters for paginated endpoints\n- `DateRangeParams`: Parameters for date filtering\n- `SortParams`: Parameters for sorting results\n- `ErrorResponse`: Structure for API errors\n\n### Resource-Specific Models\n\n- **Contacts**: Contact management with address, bank account, and tax information\n- **Documents**: Invoices, estimates, orders, and other document types\n- **Products**: Product catalog with variants, categories, and stock management\n- **CRM**: Leads, funnels, tasks, and notes\n- **Treasury**: Accounts, transactions, and categories\n- **Projects**: Project management, tasks, and time tracking\n- **Accounting**: Journal entries, accounts, and financial reports\n- **Team**: Employee management and permissions\n\n## Documentation\n\nFor more detailed documentation, see:\n\n- [Getting Started](docs/getting_started.md)\n- [API Reference](docs/api_reference/index.md)\n- [Examples](docs/examples.md)\n- [Advanced Usage](docs/advanced_usage.md)\n- [Error Handling](docs/error_handling.md)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details. \n\n## Funding\n\n## ☕ Sponsor Me\n\nIf you like this project, consider [buying me OpenAI credits](https://buymeacoffee.com/bonifaciocalindoro)!\n\n[![Buy Me a Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee\u0026emoji=☕\u0026slug=bonifaciocalindoro\u0026button_colour=FFDD00\u0026font_colour=000000\u0026font_family=Comic\u0026outline_colour=000000\u0026coffee_colour=ffffff)](https://buymeacoffee.com/bonifaciocalindoro)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonifaciocalindoro%2Fholded-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbonifaciocalindoro%2Fholded-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonifaciocalindoro%2Fholded-python/lists"}