# ixcpy [](https://pypi.org/project/ixcpy/)
Esta biblioteca não faz parte das bibliotecas oficiais do <a href="https://ixcsoft.com/ixc-provedor" target="_blank">IXC Provedor</a>.\
O desenvolvimento é feito de forma independente e utiliza apenas uma "interface" de conexão com as funcionalidades providas pela API oficial do IXC.\
Você poderá encontrar orientações de como parametrizar as requisições na <a href="https://wikiapiprovedor.ixcsoft.com.br/" target="_blank">WIKI oficial</a>, disponilizada pela própria <a href="https://ixcsoft.com/" target="_blank">IXC Soft</a>.
## Disponível nos repositórios <a href="https://pypi.org/">PyPI</a>
###### Adicione ao seu projeto utilizando o comando <a href="https://pypi.org/project/pip/" target="_blank">pip install</a>.
```bash
pip install ixcpy
```
## Configuração básica
###### Adicione as variáveis de ambiente a um `.env` na raiz do seu projeto:
```dotenv
IXC_ACCESS_TOKEN=conteúdo-do-token-gerado-dentro-do-ixc-provedor
IXC_SERVER_DOMAIN=www.domínio-do-seu-servidor-ixc-provedor.com.br
```
> [!NOTE]\
> Não sabe como gerar um token? Basta consultar <a href="https://wiki.ixcsoft.com.br/pt-br/API/como_gerar_um_token_para_integra%C3%A7%C3%B5es_API" target="_blank">este tutorial</a>.
## Do jeito mais dinâmico 😎
###### Realizando uma consulta através da classe Connection:
```python
from ixcpy import Connection
connection = Connection(table='cliente')
# O operador "%" fará a busca em todos os clientes que possuem "João" no campo "razao".
connection.where(args='razao % "João"')
# Para encontrar um registro pelo nome que seja exatamente igual ao que você busca,
# substitua o operador "%" pelo "=".
connection.where(args='razao = "Nome Completo do João"')
# Para realizar a busca em qualquer outro campo, basta alterar a query,
# como no exemplo abaixo, tendo em vista que o campo deve corresponder
# a uma coluna da tabela que você está buscando, no IXC Provedor.
# Nesse caso, o campo "cnpj_cpf", na tabela "cliente"
connection.where(args='cnpj_cpf = "123.456.789-10"')
```
> Depois de invocar o método `where()` uma ou mais vezes, basta invocar o método `many()` na sua instância de `Connection`\
> Então você irá obter a instância de um objeto do tipo `Response`, de onde poderá acessar a quantidade de registros retornados, através do método `total()`.\
> E uma lista dos objetos, a partir do método `records()`, tudo através da instância de `Response`.
## Do jeito mais simples 🎯
Supondo que você possua o ID de um determinado registro e queira buscá-lo no IXC Provedor, seria contraproducente encadear "chamadas where".
Nesse caso, basta invocar o método `one()` em uma instância de `Connection`, passando o ID como parâmetro, como no exemplo a seguir:
```python
from ixcpy import Connection
connection = Connection(table='cliente')
# Se o IXC encontrar um registro (na tabela "cliente" nesse caso), o método "one" retornará um 'dict'
# onde as chaves serão do tipo 'str' e o valor de cada campo podendo ser 'str', 'int' ou 'bool',
# dependendo do formato retornado pelo IXC Provedor. Se nenhum registro for encontrado,
# o método "one" retornará um 'None'
cliente = connection.one(record_id=12345)
```
## Dica!
Uma opção prática é criar uma classe personalizada que herde de `Connection`, assim será possível encapsular as buscas
detro da subclasse correspondente à tabela que você deseja manipular, como no exemplo a seguir:
```python
from ixcpy import Connection
class Cliente(Connection):
def __init__(self):
super().__init__('cliente')
def lista_por_data_cadastro(self, data_cadastro: str, page: int = 1) -> list:
self.where(args=f'data_cadastro >= {data_cadastro}')
resposta = self.many(page=page)
return resposta.records()
```
## Clone & Setup
```bash
git clone https://github.com/SousaFelipe/ixcpy.git
```
```bash
cd ixcpy
```
```bash
python -m venv .venv
```
```bash
.venv\Scripts\activate
```
```bash
python -m pip install -r requirements.txt
```
## Contribuições
Contribuições são sempre bem-vindas!\
Se você conhece uma maneira melhor de fazer algo, por favor, me avise!
Caso contrário, é sempre melhor fazer um PR na branch main.
At.te,\
<b>Felipe S. Carmo</b>.
Raw data
{
"_id": null,
"home_page": "https://github.com/SousaFelipe/ixcpy",
"name": "ixcpy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "ixc, ixcsoft, api ixc, ixc provedor, ixc python",
"author": "Felipe Sousa",
"author_email": "fscarmo@proton.me",
"download_url": "https://files.pythonhosted.org/packages/16/b3/79e1506c844c6fc4feb6b8e801238429e4ef99718f934c649abcebb4e624/ixcpy-2.0.0.tar.gz",
"platform": null,
"description": "\r\n# ixcpy [](https://pypi.org/project/ixcpy/)\r\n\r\nEsta biblioteca n\u00e3o faz parte das bibliotecas oficiais do <a href=\"https://ixcsoft.com/ixc-provedor\" target=\"_blank\">IXC Provedor</a>.\\\r\nO desenvolvimento \u00e9 feito de forma independente e utiliza apenas uma \"interface\" de conex\u00e3o com as funcionalidades providas pela API oficial do IXC.\\\r\nVoc\u00ea poder\u00e1 encontrar orienta\u00e7\u00f5es de como parametrizar as requisi\u00e7\u00f5es na <a href=\"https://wikiapiprovedor.ixcsoft.com.br/\" target=\"_blank\">WIKI oficial</a>, disponilizada pela pr\u00f3pria <a href=\"https://ixcsoft.com/\" target=\"_blank\">IXC Soft</a>.\r\n\r\n\r\n## Dispon\u00edvel nos reposit\u00f3rios <a href=\"https://pypi.org/\">PyPI</a>\r\n###### Adicione ao seu projeto utilizando o comando <a href=\"https://pypi.org/project/pip/\" target=\"_blank\">pip install</a>.\r\n\r\n```bash\r\npip install ixcpy\r\n```\r\n\r\n\r\n## Configura\u00e7\u00e3o b\u00e1sica\r\n###### Adicione as vari\u00e1veis de ambiente a um `.env` na raiz do seu projeto:\r\n\r\n```dotenv\r\nIXC_ACCESS_TOKEN=conte\u00fado-do-token-gerado-dentro-do-ixc-provedor\r\nIXC_SERVER_DOMAIN=www.dom\u00ednio-do-seu-servidor-ixc-provedor.com.br\r\n```\r\n\r\n> [!NOTE]\\\r\n> N\u00e3o sabe como gerar um token? Basta consultar <a href=\"https://wiki.ixcsoft.com.br/pt-br/API/como_gerar_um_token_para_integra%C3%A7%C3%B5es_API\" target=\"_blank\">este tutorial</a>.\r\n\r\n\r\n## Do jeito mais din\u00e2mico \ud83d\ude0e\r\n###### Realizando uma consulta atrav\u00e9s da classe Connection:\r\n\r\n```python\r\nfrom ixcpy import Connection\r\n\r\nconnection = Connection(table='cliente')\r\n\r\n# O operador \"%\" far\u00e1 a busca em todos os clientes que possuem \"Jo\u00e3o\" no campo \"razao\".\r\nconnection.where(args='razao % \"Jo\u00e3o\"')\r\n\r\n# Para encontrar um registro pelo nome que seja exatamente igual ao que voc\u00ea busca,\r\n# substitua o operador \"%\" pelo \"=\".\r\nconnection.where(args='razao = \"Nome Completo do Jo\u00e3o\"')\r\n\r\n# Para realizar a busca em qualquer outro campo, basta alterar a query,\r\n# como no exemplo abaixo, tendo em vista que o campo deve corresponder\r\n# a uma coluna da tabela que voc\u00ea est\u00e1 buscando, no IXC Provedor.\r\n# Nesse caso, o campo \"cnpj_cpf\", na tabela \"cliente\"\r\nconnection.where(args='cnpj_cpf = \"123.456.789-10\"')\r\n```\r\n\r\n> Depois de invocar o m\u00e9todo `where()` uma ou mais vezes, basta invocar o m\u00e9todo `many()` na sua inst\u00e2ncia de `Connection`\\\r\n> Ent\u00e3o voc\u00ea ir\u00e1 obter a inst\u00e2ncia de um objeto do tipo `Response`, de onde poder\u00e1 acessar a quantidade de registros retornados, atrav\u00e9s do m\u00e9todo `total()`.\\\r\n> E uma lista dos objetos, a partir do m\u00e9todo `records()`, tudo atrav\u00e9s da inst\u00e2ncia de `Response`.\r\n\r\n\r\n## Do jeito mais simples \ud83c\udfaf\r\n\r\nSupondo que voc\u00ea possua o ID de um determinado registro e queira busc\u00e1-lo no IXC Provedor, seria contraproducente encadear \"chamadas where\". \r\nNesse caso, basta invocar o m\u00e9todo `one()` em uma inst\u00e2ncia de `Connection`, passando o ID como par\u00e2metro, como no exemplo a seguir:\r\n\r\n```python\r\nfrom ixcpy import Connection\r\n\r\nconnection = Connection(table='cliente')\r\n\r\n# Se o IXC encontrar um registro (na tabela \"cliente\" nesse caso), o m\u00e9todo \"one\" retornar\u00e1 um 'dict'\r\n# onde as chaves ser\u00e3o do tipo 'str' e o valor de cada campo podendo ser 'str', 'int' ou 'bool',\r\n# dependendo do formato retornado pelo IXC Provedor. Se nenhum registro for encontrado,\r\n# o m\u00e9todo \"one\" retornar\u00e1 um 'None'\r\ncliente = connection.one(record_id=12345)\r\n```\r\n\r\n\r\n## Dica!\r\nUma op\u00e7\u00e3o pr\u00e1tica \u00e9 criar uma classe personalizada que herde de `Connection`, assim ser\u00e1 poss\u00edvel encapsular as buscas\r\ndetro da subclasse correspondente \u00e0 tabela que voc\u00ea deseja manipular, como no exemplo a seguir:\r\n\r\n```python\r\nfrom ixcpy import Connection\r\n\r\nclass Cliente(Connection):\r\n \r\n def __init__(self):\r\n super().__init__('cliente')\r\n \r\n def lista_por_data_cadastro(self, data_cadastro: str, page: int = 1) -> list:\r\n self.where(args=f'data_cadastro >= {data_cadastro}')\r\n resposta = self.many(page=page)\r\n return resposta.records()\r\n\r\n```\r\n\r\n\r\n## Clone & Setup\r\n\r\n```bash\r\ngit clone https://github.com/SousaFelipe/ixcpy.git\r\n```\r\n```bash\r\ncd ixcpy\r\n```\r\n```bash\r\npython -m venv .venv\r\n```\r\n```bash\r\n.venv\\Scripts\\activate\r\n```\r\n```bash\r\npython -m pip install -r requirements.txt\r\n```\r\n\r\n\r\n## Contribui\u00e7\u00f5es\r\n\r\nContribui\u00e7\u00f5es s\u00e3o sempre bem-vindas!\\\r\nSe voc\u00ea conhece uma maneira melhor de fazer algo, por favor, me avise!\r\nCaso contr\u00e1rio, \u00e9 sempre melhor fazer um PR na branch main.\r\n\r\nAt.te,\\\r\n<b>Felipe S. Carmo</b>.\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Wrapper n\u00e3o oficial para conex\u00e3o com a API do sistema IXC Provedor",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/SousaFelipe/ixcpy"
},
"split_keywords": [
"ixc",
" ixcsoft",
" api ixc",
" ixc provedor",
" ixc python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "16b379e1506c844c6fc4feb6b8e801238429e4ef99718f934c649abcebb4e624",
"md5": "087480dea359a3a3432315bbd7392d7e",
"sha256": "9494856640235952fc1ee2f22a08ad951978c347d839cd2cb12c4c48a847869d"
},
"downloads": -1,
"filename": "ixcpy-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "087480dea359a3a3432315bbd7392d7e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6277,
"upload_time": "2025-10-11T16:56:37",
"upload_time_iso_8601": "2025-10-11T16:56:37.037260Z",
"url": "https://files.pythonhosted.org/packages/16/b3/79e1506c844c6fc4feb6b8e801238429e4ef99718f934c649abcebb4e624/ixcpy-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 16:56:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SousaFelipe",
"github_project": "ixcpy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "python-dotenv",
"specs": []
},
{
"name": "certifi",
"specs": [
[
"==",
"2025.8.3"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.4.3"
]
]
},
{
"name": "docopt",
"specs": [
[
"==",
"0.6.2"
]
]
},
{
"name": "et_xmlfile",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.10"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"2.3.3"
]
]
},
{
"name": "openpyxl",
"specs": [
[
"==",
"3.1.5"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.3.2"
]
]
},
{
"name": "pipreqs",
"specs": [
[
"==",
"0.4.13"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.9.0.post0"
]
]
},
{
"name": "pytz",
"specs": [
[
"==",
"2025.2"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.5"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"80.9.0"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.17.0"
]
]
},
{
"name": "tzdata",
"specs": [
[
"==",
"2025.2"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.5.0"
]
]
},
{
"name": "yarg",
"specs": [
[
"==",
"0.1.10"
]
]
}
],
"lcname": "ixcpy"
}
JSON
