### Install Prometeo Python Package

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/index.md

Install the Prometeo Python package using pip. This is the first step to using the API client.

```bash
pip install prometeo
```

--------------------------------

### Install Prometeo with Local Files

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Installs the prometeo package using local files instead of the production source code, useful for development or testing specific versions.

```bash
pip install prometeo --no-index --find-links file:///srv/pkg/mypackage
```

--------------------------------

### Call Banking API Synchronously

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/index.md

Example of calling the `get_providers` method from the banking service in a synchronous context.

```python
result = client.banking.get_providers()
```

--------------------------------

### Call Banking API Asynchronously

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/index.md

Example of calling the `get_providers` method from the banking service in an asynchronous context.

```python
result = await client.banking.get_providers()
```

--------------------------------

### Synchronous and Asynchronous Banking Operations

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Demonstrates both synchronous and asynchronous methods for interacting with banking services. Requires API key and environment setup. Asynchronous operations leverage asyncio for concurrent requests.

```python
import asyncio
from prometeo import Client

client = Client('<YOUR_API_KEY>', environment='sandbox')

# Synchronous usage
providers = client.banking.get_providers()

# Asynchronous usage
async def get_banking_data():
    session = client.banking.new_session()
    await session.login(provider='test', username='12345', password='gfdsa')

    # Run multiple requests concurrently
    accounts, cards = await asyncio.gather(
        session.get_accounts(),
        session.get_credit_cards()
    )

    print(f"Found {len(accounts)} accounts and {len(cards)} credit cards")

    await session.logout()

# Run the async function
asyncio.run(get_banking_data())
```

--------------------------------

### Get Acknowledgements

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Retrieves acknowledgements from the SAT system, requiring a SIAT scope login. It allows filtering by various criteria and includes an example of downloading the acknowledgement file.

```python
session_siat = client.sat.login(
    rfc='ABCD1234EFGH',
    password='password',
    scope=LoginScope.SIAT
)
acks = session_siat.get_acknowledgements(
    year=2024,
    month_start=1,
    month_end=3,
    motive=Motive.ALL,
    document_type=DocumentType.ALL,
    status=Status.ALL,
    send_type=SendType.ALL
)
for ack in acks:
    print(f"ID: {ack.id}")
    print(f"Period: {ack.period}")
    print(f"Status: {ack.status}")
    print(f"File Name: {ack.file_name}")
    # Download acknowledgement
    download = ack.get_download()
    content = download.get_file().read()
```

--------------------------------

### Get Numeration

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/dian.md

Retrieve numeration details within a specified date range. This requires the numeration type and the start and end dates for the query.

```python
from datetime import datetime
from prometeo.dian import NumerationType

session.get_numeration(
    NumerationType.Authorization,
    datetime(2019, 1, 1),
    datetime(2019, 5, 1)
)
```

--------------------------------

### Get Balances

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/dian.md

Retrieve the financial balances associated with the company. This function call fetches the balance information for the authenticated company.

```python
session.get_balances()
```

--------------------------------

### Get DIAN Rent Declaration

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Retrieve the rent declaration for a specific year from the DIAN API.

```python
session.get_rent_declaration(2018)
```

--------------------------------

### Get FX Quote

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Obtains a foreign exchange quote for converting one currency to another. Requires source and target currencies, and the amount.

```python
# Get FX quote
fx_quote = FXQuoteData(
    source_currency="USD",
    target_currency="MXN",
    amount="1000.00"
)
quote = client.crossborder.create_fx_quote(fx_quote)
print(f"Quote ID: {quote.id}")
print(f"Exchange Rate: {quote.rate}")
print(f"Target Amount: {quote.target_amount}")
```

--------------------------------

### Session Management API

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/sat.md

Provides methods to manage SAT API sessions, including getting a session key and restoring a session.

```APIDOC
## Session Management API

### Description
APIs for managing SAT API sessions, including serializing and restoring sessions.

### Method
GET/POST

### Endpoint
/api/sat/session

### Parameters
#### Request Body (for restoring session)
- **session_key** (string) - Required - The key representing the serialized session.

### Request Example (Get Session Key)
```python
session_key = session.get_session_key()
```

### Request Example (Restore Session)
```python
restored_session = client.sat.get_session(session_key)
```

### Response
#### Success Response (200) - Get Session Key
- **session_key** (string) - The serialized session key.

#### Success Response (200) - Restore Session
- **session** (object) - The restored session object.

#### Response Example (Restore Session)
```json
{
  "session": "<restored_session_object_representation>"
}
```
```

--------------------------------

### Retrieve Payment Intent by ID using Prometeo Python Client

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/payment.md

Use this method to get details of a specific payment intent. You need the payment ID. Initialize the client with your API key and set the environment to 'production'.

```python
from prometeo import Client

# Initialize the Prometeo client with your API key and set the environment to 'production'
client = Client('<YOUR_API_KEY>', environment='production')

# Specify the payment ID for the desired payment intent
payment_id = "<PAYMENT_ID>"
data = client.payment.get_transaction_data(payment_id)
```

--------------------------------

### Get Rent Declaration

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/dian.md

Retrieve the rent declaration for a specific year. This function requires the year for which the declaration is requested.

```python
session.get_rent_declaration(2019)
```

--------------------------------

### Bulk Download CFDI Bills

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Initiates a bulk download for emitted CFDI bills within a date range and status. Iterates through download requests to get file content.

```python
from prometeo.sat import BillStatus

download_requests = session.download_emitted_bills(
    date_start=datetime(2020, 1, 1),
    date_end=datetime(2020, 2, 1),
    status=BillStatus.ANY,
)

for request in download_requests:
    download = request.get_download()
    content = download.get_file().read()
```

--------------------------------

### Get Specific Cross-Border Intent

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Fetches the details of a specific cross-border intent using its ID.

```python
# Get specific intent
intent = client.crossborder.get_intent('intent-id-here')
```

--------------------------------

### Get DIAN Numeration

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Retrieve numeration data from the DIAN API for a given type and date range.

```python
from datetime import datetime
from prometeo.dian import NumerationType

session.get_numeration(NumerationType.Authorization, datetime(2019, 1, 1), datetime(2019, 5, 1))
```

--------------------------------

### Get VAT Declaration

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/dian.md

Retrieve the VAT declaration for a specific year and period. This requires specifying the year, periodicity, and the specific quarterly period.

```python
from prometeo.dian import Periodicity, QuartlerlyPeriod

session.get_vat_declaration(2019, Periodicity.QUARTERLY, QuartlerlyPeriod.JANUARY_APRIL)
```

--------------------------------

### Get Retentions

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/dian.md

Retrieve retention information for a specific year and month. This function requires the year and the monthly period for which the retentions are requested.

```python
from prometeo.dian import MonthlyPeriod

session.get_retentions(2019, MonthlyPeriod.NOVEMBER)
```

--------------------------------

### Get Company Information

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/dian.md

Retrieve company information, specifically Form 001. This function call fetches the basic details of the company associated with the current session.

```python
session.get_company_info()
```

--------------------------------

### Get Payment Intent Details

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Retrieves the transaction data for a given payment intent ID, including its status, amount, currency, and creation timestamp.

```python
# Get payment intent details
intent_data = client.payment.get_transaction_data(payment_intent.intent_id)
print(f"Status: {intent_data.status}")
print(f"Amount: {intent_data.amount}")
print(f"Currency: {intent_data.currency}")
print(f"Created At: {intent_data.created_at}")
```

--------------------------------

### Get Acknowledgements API

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/sat.md

Retrieves acknowledgements based on specified criteria including date range, motive, document type, status, and send type.

```APIDOC
## GET /api/sat/acknowledgements

### Description
Retrieves acknowledgements from the SAT API based on a variety of filtering criteria.

### Method
GET

### Endpoint
/api/sat/acknowledgements

### Parameters
#### Query Parameters
- **year** (integer) - Required - The year for filtering acknowledgements.
- **month_start** (integer) - Required - The starting month for the range.
- **month_end** (integer) - Required - The ending month for the range.
- **motive** (Motive) - Required - The motive for filtering (e.g., ALL).
- **document_type** (DocumentType) - Required - The document type for filtering (e.g., ALL).
- **status** (Status) - Required - The status for filtering (e.g., ALL).
- **send_type** (SendType) - Required - The send type for filtering (e.g., ALL).

### Request Example
```python
acks = session.get_acknowledgement(
    year=2020,
    month_start=1,
    month_end=2,
    motive=Motive.ALL,
    document_type=DocumentType.ALL,
    status=Status.ALL,
    send_type=SendType.ALL,
)
```

### Response
#### Success Response (200)
- **acks** (array) - A list of acknowledgement objects.

#### Response Example
```json
[
  {
    "ack_details": "<ack_object_representation>"
  }
]
```
```

--------------------------------

### Initialize Prometeo Client

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Configure the client with an API key and environment. Optional parameters include raw response toggles and proxy settings.

```python
from prometeo import Client

# Initialize client for sandbox environment (testing)
client = Client('<YOUR_API_KEY>', environment='sandbox')

# Initialize client for production environment
client = Client('<YOUR_API_KEY>', environment='production')

# Initialize with optional parameters
client = Client(
    '<YOUR_API_KEY>',
    environment='production',
    raw_responses=False,  # Set True to get raw API responses
    proxy='http://proxy.example.com:8080'  # Optional proxy configuration
)

# Access different API services
banking_client = client.banking
account_validation_client = client.account_validation
curp_client = client.curp
dian_client = client.dian
sat_client = client.sat
payment_client = client.payment
crossborder_client = client.crossborder
```

--------------------------------

### Instantiate Prometeo Client

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/index.md

Instantiate the Prometeo client with your API key. Use 'sandbox' for the sandbox environment and 'production' for the production environment.

```python
from prometeo import Client

client = Client('<YOUR_API_KEY>', environment='sandbox')
```

--------------------------------

### Generate HTML Documentation

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Builds HTML documentation files for the project from the /docs folder using make.

```bash
make html
```

--------------------------------

### Initialize Prometeo Client

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/dian.md

Initialize the Prometeo client with your API key and environment. This is the first step before interacting with any DIAN API endpoints.

```python
from prometeo import Client
from prometeo.dian import DocumentType

client = Client('<YOUR_API_KEY>', environment='sandbox')
```

--------------------------------

### Select Client Profile

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/banking.md

Handle sessions where multiple client profiles are available by selecting one after login.

```python
if session.get_status() == 'select_client':
    clients = session.get_clients()
    session.select_client(clients[0])
    assert session.status == 'logged_in'
```

--------------------------------

### List Payouts and Transactions

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Use this to list payouts and retrieve account and transaction details. Ensure the client is initialized.

```python
payouts = client.crossborder.list_payouts()
for p in payouts:
    print(f"Payout: {p.id} - {p.amount} {p.currency}")

accounts = client.crossborder.get_accounts()
for account in accounts:
    print(f"Account: {account.id} - {account.currency}")
    transactions = client.crossborder.get_account_transactions(account.id)
    for tx in transactions:
        print(f"  Transaction: {tx.id} - {tx.amount}")
```

--------------------------------

### Run All Tests with Tox

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Execute all tests in the project for both Python 2 and 3 using the tox testing library.

```bash
tox
```

--------------------------------

### Create Payment Intent with Prometeo Python Client

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/payment.md

Use this method to create a new payment intent. Ensure you have your API key and widget ID. The environment should be set to 'production'.

```python
from prometeo import Client

# Initialize the Prometeo client with your API key and set the environment to 'production'
client = Client('<YOUR_API_KEY>', environment='production')

# Specify the necessary parameters for creating a payment intent
widget_id = '<YOUR_WIDGET_ID>'
data = client.payment.create_intent(
    widget_id=widget_id,
    currency="USD",
    amount="1.00",
    external_id=None,
    concept="PROM123452 REF454243",
    bank_codes=["test"],
)

# Print the generated payment intent ID
print("Intent ID:", data.intent_id)
```

--------------------------------

### Retrieve Banking Providers

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Fetch supported financial institutions and inspect their specific authentication requirements. Provider lists should be cached.

```python
from prometeo import Client

client = Client('<YOUR_API_KEY>', environment='sandbox')

# Get list of all available banking providers
providers = client.banking.get_providers()
for provider in providers:
    print(f"Code: {provider.code}")
    print(f"Name: {provider.name}")
    print(f"Country: {provider.country}")
    print("---")

# Get detailed information about a specific provider
session = client.banking.new_session()
provider_detail = session.get_provider_detail('test')
print(f"Provider: {provider_detail.name}")
print(f"Country: {provider_detail.country}")
print(f"Logo: {provider_detail.logo}")
print(f"Available methods: {provider_detail.methods}")
print("Auth fields required:")
for field in provider_detail.auth_fields:
    print(f"  - {field.name}: {field.label_en} (type: {field.type})")
```

--------------------------------

### Log in to a Banking Provider

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/banking.md

Authenticate with a provider using credentials. Extra authentication fields can be passed as keyword arguments.

```python
session.login(
    provider='test',
    username='12345',
    password='gfdsa',
)
```

```python
session.login(
    provider='test',
    username='12345otp',
    password='asdfg',
    otp=8888
)
```

--------------------------------

### Authenticate with SAT API

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/sat.md

Initializes a session using RFC, password, and a specific LoginScope.

```python
from prometeo.sat import LoginScope

session = client.sat.login(
    rfc='ABCD1234EFGH',
    password='password',
    scope=LoginScope.CFDI,
)
```

--------------------------------

### Create Payment Intent

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Creates a payment intent for processing payments via Prometeo's widgets. Requires a widget ID, currency, amount, and an external reference.

```python
from prometeo import Client

client = Client('<YOUR_API_KEY>', environment='production')

# Create a payment intent
payment_intent = client.payment.create_intent(
    widget_id='<YOUR_WIDGET_ID>',
    currency='USD',
    amount='100.00',
    external_id='ORDER-12345',  # Your internal reference
    concept='Payment for Order #12345',
    bank_codes=['test', 'bancolombia']  # Optional: limit banks shown
)
print(f"Intent ID: {payment_intent.intent_id}")
print(f"Widget URL: {payment_intent.widget_url}")  # Redirect user here
```

--------------------------------

### List Available Banks

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Retrieve and print the names and countries of all available banking providers.

```python
providers = client.banking.get_providers()
for provider in providers:
    print(provider.name, provider.country)
```

--------------------------------

### List Available Banks

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/banking.md

Retrieve a list of supported banking providers.

```python
providers = session.get_providers()
```

--------------------------------

### Handle Interaction Required

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/banking.md

Manage sessions requiring additional authentication steps like security questions or OTPs.

```python
session.login(provider='test', username='user', password='pass')
if session.get_status() == 'interaction_required':
    # necessary context, like the security question to answer.
    print(session.get_interactive_context())
    session.finish_login(
        provider='test',
        username='user',
        password='pass',
        answer='1234',
    )
```

--------------------------------

### Create Cross-Border Pay-In Intent

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Creates a pay-in intent for international payments. Requires amount, currency, an external ID, and a description.

```python
from prometeo import Client
from prometeo.crossborder.models import (
    IntentDataRequest, FXQuoteData, CustomerInput,
    PayoutTransferInput, WithdrawalAccountInput
)

client = Client('<YOUR_API_KEY>', environment='sandbox')

# Create a pay-in intent
intent_request = IntentDataRequest(
    amount="1000.00",
    currency="USD",
    external_id="PAY-123",
    description="International payment"
)
intent = client.crossborder.create_intent(intent_request)
print(f"Intent ID: {intent.id}")
print(f"Status: {intent.status}")
```

--------------------------------

### Download Emitted Bills

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/sat.md

Initiates a download request and polls until the file is ready for retrieval.

```python
import time
from prometeo.sat import BillStatus

download_requests = session.download_emitted_bills(
    date_start=datetime(2020, 1, 1),
    date_end=datetime(2020, 2, 1),
    status=BillStatus.ANY,
)
for request in download_requests:
    while not request.is_ready():
        time.sleep(5)
    download = request.get_download()
    content = download.get_file().read()
```

--------------------------------

### Serialize and Restore Sessions

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/sat.md

Use session keys to persist or transfer authentication state between processes.

```python
session_key = session.get_session_key()

# save session_key somewhere...

restored_session = client.sat.get_session(session_key)
```

--------------------------------

### Manage Banking Sessions

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Handle authentication flows including OTP, security questions, and client selection. Sessions can be serialized for persistence.

```python
from prometeo import Client
from prometeo.exceptions import WrongCredentialsError

client = Client('<YOUR_API_KEY>', environment='sandbox')

# Create a new banking session
session = client.banking.new_session()

# Basic login (sandbox test account)
session.login(
    provider='test',
    username='12345',
    password='gfdsa'
)

# Login with OTP/2FA (sandbox test account with token)
session.login(
    provider='test',
    username='12345otp',
    password='asdfg',
    otp=8888  # One-time password from token device
)

# Handle interactive login (security questions, OTP)
session.login(provider='test', username='user', password='pass')
if session.get_status() == 'interaction_required':
    context = session.get_interactive_context()  # e.g., security question
    print(f"Please answer: {context}")
    session.finish_login(
        provider='test',
        username='user',
        password='pass',
        answer='1234'  # User's answer to security question
    )

# Handle client selection (some banks have multiple profiles)
if session.get_status() == 'select_client':
    clients = session.get_clients()
    for c in clients:
        print(f"Client ID: {c.id}, Name: {c.name}")
    session.select_client(clients[0])

# Serialize session for later use (e.g., task queues)
session_key = session.get_session_key()
# Later, restore the session
restored_session = client.banking.get_session(session_key)

# Logout when done
session.logout()
```

--------------------------------

### Log in as a Company

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/dian.md

Log in to the DIAN API as a company by providing your company's NIT, your document type and number, and your password. Ensure the document type and number correspond to the company's registration.

```python
session = client.dian.login(
    nit='098765',
    document_type=DocumentType.CEDULA_CIUDADANIA,
    document='12345',
    password='test_password',
)
```

--------------------------------

### Validate a bank account in Python

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/account_validation.md

Use the validate method to verify account details. Ensure the client is initialized with the correct API key and sandbox environment.

```python
from prometeo import Client

# Initialize the Prometeo client with your API key and set the environment to 'sandbox'
client = Client('<YOUR_API_KEY>', environment='sandbox')

data = client.account_validation.validate(
    account_number="1001",
    country_code="BR",
    document_number="58.547.642/0001-95",
    branch_code="00001",
    bank_code="999",
    account_type="CHECKING",
)

print(data.beneficiary_name)
# "JOÃO DAS NEVES"
print(data.account_type)
# "CHECKING"
print(data.account_type)
```

```python
from prometeo import Client
from prometeo.account_validation import exceptions

# Initialize the Prometeo client with your API key and set the environment to 'sandbox'
client = Client('<YOUR_API_KEY>', environment='sandbox')

try:
    data = client.account_validation.validate(
        account_number="1002",
        country_code="BR",
        document_number="58.547.642/0001-95",
        branch_code="00001",
        bank_code="999",
        account_type="CHECKING",
    )
except exceptions.InvalidAccountError as e:
    print(e.message)
```

--------------------------------

### Download Acknowledgements

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/sat.md

Retrieves and downloads acknowledgements based on date, motive, document type, and status filters.

```python
from prometeo.sat import Motive, DocumentType, Status, SendType

acks = session.get_acknowledgement(
    year=2020,
    month_start=1,
    month_end=2,
    motive=Motive.ALL,
    document_type=DocumentType.ALL,
    status=Status.ALL,
    send_type=SendType.ALL,
)
for ack in acks:
    download = ack.download().get_file()
```

--------------------------------

### Authenticate with Mexican SAT API

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Initialize a session with the SAT service using specific scopes like CFDI or SIAT.

```python
import time
from datetime import datetime
from prometeo import Client
from prometeo.sat import (
    LoginScope, BillStatus, Motive,
    DocumentType, Status, SendType
)

client = Client('<YOUR_API_KEY>', environment='sandbox')

# Login to SAT (CFDI scope for bills)
session = client.sat.login(
    rfc='ABCD1234EFGH',
    password='password',
    scope=LoginScope.CFDI  # Use LoginScope.SIAT for acknowledgements
)
```

--------------------------------

### List Bank Movements

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Retrieve and print account details and movements from the sandboxed bank. Requires a logged-in session.

```python
from datetime import datetime

session = client.banking.new_session()
session = session.login(provider='test', username='12345', password='gfdsa')
accounts = session.get_accounts()
account = accounts[0]
print(account.number, ' - ', account.name)
movements = account.get_movements(datetime(2019, 2, 1), datetime(2019, 2, 2))
for movement in movements:
    print(movement.detail, movement.debit, movement.credit)
```

--------------------------------

### User Authentication API

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/sat.md

Logs in to the SAT API and returns a session object. Requires RFC, password, and a login scope.

```APIDOC
## POST /api/sat/login

### Description
Authenticates a user with the SAT API using RFC, password, and a specified scope.

### Method
POST

### Endpoint
/api/sat/login

### Parameters
#### Request Body
- **rfc** (string) - Required - The RFC of the user.
- **password** (string) - Required - The password for authentication.
- **scope** (LoginScope) - Required - The scope of the login (e.g., CFDI).

### Request Example
```json
{
  "rfc": "ABCD1234EFGH",
  "password": "password",
  "scope": "CFDI"
}
```

### Response
#### Success Response (200)
- **session** (object) - An object representing the authenticated session.

#### Response Example
```json
{
  "session": "<session_object_representation>"
}
```
```

--------------------------------

### Bulk Download Emitted Bills

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Initiates a bulk download for emitted bills within a date range. It then polls for download readiness and saves the zip file.

```python
download_requests = session.download_emitted_bills(
    date_start=datetime(2024, 1, 1),
    date_end=datetime(2024, 1, 31),
    status=BillStatus.ANY
)
for request in download_requests:
    # Wait for download to be ready
    while not request.is_ready():
        time.sleep(5)
    # Get the download
    download = request.get_download()
    content = download.get_file().read()
    with open(f"bills_{request.request_id}.zip", "wb") as f:
        f.write(content)
```

--------------------------------

### List Accounts and Movements

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/banking.md

Retrieve account lists and their associated transaction movements within a date range.

```python
from datetime import datetime

accounts = session.get_accounts()
for account in accounts:
    movements = account.get_movements(
        datetime(2019, 2, 1), datetime(2019, 15, 1)
    )
```

--------------------------------

### Restore a Session

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/banking.md

Serialize and restore a session using a session key for persistence or task queues.

```python
session_key = session.get_session_key()

# save session_key somewhere...

restored_session = client.banking.get_session(session_key)
```

--------------------------------

### Create Cross-Border Payout

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Initiates a cross-border payout to a customer. Requires the customer ID, amount, currency, FX quote ID, and a description.

```python
# Create a payout
payout_data = PayoutTransferInput(
    customer_id=customer.id,
    amount="500.00",
    currency="MXN",
    quote_id=quote.id,
    description="Payout to customer"
)
payout = client.crossborder.create_payout(payout_data)
print(f"Payout ID: {payout.id}")
print(f"Status: {payout.status}")
```

--------------------------------

### Run Python 3 Tests with Tox

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Restrict test execution to only Python 3 environments using tox.

```bash
tox -e py3
```

--------------------------------

### DIAN Login as Company

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Log in to the DIAN API as a company using NIT, document type, document number, and password.

```python
from prometeo.dian import DocumentType

session = client.dian.login(
    nit='098765',
    document_type=DocumentType.CEDULA_CIUDADANIA,
    document='12345',
    password='test_password',
)
```

--------------------------------

### Create Cross-Border Customer

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Creates a new customer profile for cross-border transactions. Requires customer's email, name, tax ID, and country.

```python
# Create a customer
customer_data = CustomerInput(
    email="customer@example.com",
    first_name="John",
    last_name="Doe",
    tax_id="123456789",
    country="MX"
)
customer = client.crossborder.create_customer(customer_data)
print(f"Customer ID: {customer.id}")
```

--------------------------------

### List Emitted and Received Bills

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/sat.md

Retrieve bills by date range for emitted items or by year and month for received items.

```python
from prometeo.sat import BillStatus

emitted_bills = session.get_emitted_bills(
    date_start=datetime(2020, 1, 1),
    date_end=datetime(2020, 2, 1),
    status=BillStatus.ANY,
)
```

```python
received_bills = session.get_received_bills(
    year=2020,
    month=1,
    status=BillStatus.ANY,
)
```

--------------------------------

### Check CURP Existence

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/curp.md

Use this method to verify if a CURP is registered in the system. It requires a valid CURP string. Handle `CurpError` for non-existent CURPs.

```python
from prometeo import Client
from prometeo.curp import exceptions

client = Client('<YOUR_API_KEY>', environment='sandbox')
try:
    result = client.curp.query('ABCD12345EFGH')
except exceptions.CurpError as e:
    print("CURP does not exist:", e.message)
```

--------------------------------

### Execute Bank Transfers

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Perform a two-step bank transfer process: preprocessing to validate details and confirming with an authorization method.

```python
from prometeo import Client

client = Client('<YOUR_API_KEY>', environment='sandbox')
session = client.banking.new_session()
session.login(provider='test', username='12345', password='gfdsa')

# List available transfer destination institutions
institutions = session.list_transfer_institutions()
for inst in institutions:
    print(f"ID: {inst.id}, Name: {inst.name}")

# Step 1: Preprocess transfer (validate and get authorization requirements)
preprocess = session.preprocess_transfer(
    origin_account='002206345988',
    destination_institution='0',
    destination_account='001002363321',
    currency='UYU',
    amount='100.50',
    concept='Payment for services',
    destination_owner_name='John Doe',
    branch='62'
)
print(f"Approved: {preprocess.approved")
print(f"Request ID: {preprocess.request_id}")
print(f"Authorization devices: {preprocess.authorization_devices}")
print(f"Message: {preprocess.message}")

# Step 2: Confirm transfer with authorization
if preprocess.approved:
    confirmation = session.confirm_transfer(
        request_id=preprocess.request_id,
        authorization_type='cardCode',  # Options: 'cardCode', 'pin', 'otp', 'otp-api'
        authorization_data='1, 2, 3'  # Coordinates or PIN values
    )
    print(f"Success: {confirmation.success}")
    print(f"Message: {confirmation.message}")
```

--------------------------------

### Access Accounts and Movements

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Retrieve account data and transaction history after establishing an authenticated session.

```python
from datetime import datetime
from prometeo import Client

client = Client('<YOUR_API_KEY>', environment='sandbox')
session = client.banking.new_session()
session.login(provider='test', username='12345', password='gfdsa')
```

--------------------------------

### List Credit Cards and Movements

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/banking.md

Retrieve credit card lists and their movements, specifying the currency for the transaction history.

```python
from datetime import datetime

cards = session.get_credit_cards()
for card in cards:
    movements = card.get_movements(
        'USD', datetime(2019, 2, 1), datetime(2019, 15, 1)
    )
```

--------------------------------

### List All Cross-Border Intents

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Retrieves a list of all cross-border intents associated with the account.

```python
# List all intents
intents = client.crossborder.list_intents()
for intent in intents:
    print(f"Intent: {intent.id} - {intent.status}")
```

--------------------------------

### Log in as a Person

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/dian.md

Log in to the DIAN API as an individual by providing your document type and number, and your password. This method omits the company NIT.

```python
session = client.dian.login(
    document_type=DocumentType.CEDULA_CIUDADANIA,
    document='12345',
    password='test_password',
)
```

--------------------------------

### Download Emitted Bills API

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/sat.md

Initiates the download of emitted bills within a specified date range and status, returning download requests.

```APIDOC
## POST /api/sat/bills/emitted/download

### Description
Initiates the download process for emitted bills within a specified date range and status. Returns a list of download requests.

### Method
POST

### Endpoint
/api/sat/bills/emitted/download

### Parameters
#### Request Body
- **date_start** (datetime) - Required - The start date for the range.
- **date_end** (datetime) - Required - The end date for the range.
- **status** (BillStatus) - Required - The status of the bills to download (e.g., ANY).

### Request Example
```python
download_requests = session.download_emitted_bills(
    date_start=datetime(2020, 1, 1),
    date_end=datetime(2020, 2, 1),
    status=BillStatus.ANY,
)
```

### Response
#### Success Response (200)
- **download_requests** (array) - A list of objects representing the download requests.

#### Response Example
```json
[
  {
    "request_id": "<request_id>",
    "status": "pending"
  }
]
```
```

--------------------------------

### Preprocess a Transfer

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/banking.md

Validate transfer details before final confirmation.

```python
preprocess = session.preprocess_transfer(
  origin_account='002206345988',
  destination_institution='0',
  destination_account='001002363321',
  currency='UYU',
  amount='1.3',
  concept='transfer description',
  destination_owner_name='John Doe',
  branch='62',
)

print(preprocess)
```

--------------------------------

### Retrieve Bank Accounts and Movements

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Fetch all accounts associated with a session and retrieve transaction movements for a specific account within a date range.

```python
# Get all accounts
accounts = session.get_accounts()
for account in accounts:
    print(f"Account ID: {account.id}")
    print(f"Name: {account.name}")
    print(f"Number: {account.number}")
    print(f"Branch: {account.branch}")
    print(f"Currency: {account.currency}")
    print(f"Balance: {account.balance}")
    print("---")

# Get movements for a specific account
account = accounts[0]
movements = account.get_movements(
    date_start=datetime(2024, 1, 1),
    date_end=datetime(2024, 1, 31)
)
for movement in movements:
    print(f"Date: {movement.date}")
    print(f"Reference: {movement.reference}")
    print(f"Detail: {movement.detail}")
    print(f"Debit: {movement.debit}")
    print(f"Credit: {movement.credit}")
    print(f"Extra Data: {movement.extra_data}")
    print("---")
```

--------------------------------

### Logout

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Logs out the current session.

```python
session.logout()
```

--------------------------------

### Find CURP by Personal Information

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/curp.md

This method allows searching for a CURP using personal details such as state, birthdate, name, surnames, and gender. Ensure all required personal information is accurate. Handle `CurpError` if the CURP cannot be found.

```python
from datetime import datetime
from prometeo.curp import exceptions, Gender, State

curp = 'ABCD12345EFGH'
state = State.SINALOA
birthdate = datetime(1988, 3, 4)
name = 'JOHN'
first_surname = 'DOE'
last_surname = 'PONCE'
gender = Gender.MALE
try:
    result = client.curp.reverse_query(
        state, birthdate, name, first_surname, last_surname, gender
    )
except exceptions.CurpError as e:
    print("CURP does not exist:", e.message)
```

--------------------------------

### Restore Session

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/dian.md

Restore a previously saved session using its session key. This is useful for maintaining session state across different processes or over time.

```python
session_key = session.get_session_key()

# save session_key somewhere...

restored_session = client.dian.get_session(session_key)
```

--------------------------------

### Manage Credit Cards and Movements

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Retrieve credit card details and transaction history, including currency-specific movements.

```python
from datetime import datetime
from prometeo import Client

client = Client('<YOUR_API_KEY>', environment='sandbox')
session = client.banking.new_session()
session.login(provider='test', username='12345', password='gfdsa')

# Get all credit cards
cards = session.get_credit_cards()
for card in cards:
    print(f"Card ID: {card.id}")
    print(f"Name: {card.name}")
    print(f"Number: {card.number}")
    print(f"Close Date: {card.close_data}")
    print(f"Due Date: {card.due_date}")
    print(f"Balance (Local): {card.balance_local}")
    print(f"Balance (USD): {card.balance_dollar}")
    print("---")

# Get credit card movements (specify currency)
card = cards[0]
movements = card.get_movements(
    currency_code='USD',
    date_start=datetime(2024, 1, 1),
    date_end=datetime(2024, 1, 31)
)
for movement in movements:
    print(f"Date: {movement.date}")
    print(f"Detail: {movement.detail}")
    print(f"Debit: {movement.debit}")
    print(f"Credit: {movement.credit}")
    print("---")
```

--------------------------------

### List Transfer Institutions

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/banking.md

Retrieve a list of institutions available for transfers.

```python
institutions_list = session.list_transfer_institutions()
for intitution in institutions_list:
  print(intitution)
```

--------------------------------

### List Credit Card Movements

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Retrieve and print credit card details and movements. Requires a logged-in session.

```python
cards = session.get_credit_cards()
card = cards[0]
print(card.number, ' - ', card.name)
movements = card.get_movements('USD', datetime(2019, 2, 1), datetime(2019, 2, 2))
for movement in movements:
    print(movement.detail, movement.debit, movement.credit)
```

--------------------------------

### DIAN Login as Person

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Log in to the DIAN API as a person using document type, document number, and password. Omit the NIT for person login.

```python
from prometeo.dian import DocumentType

session = client.dian.login(
    document_type=DocumentType.CEDULA_CIUDADANIA,
    document='12345',
    password='test_password',
)
```

--------------------------------

### Download PDF Content

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/dian.md

Download the content of a form in PDF format. The content is retrieved using the `pdf.get_content()` method and can be written to a file.

```python
info = session.get_company_info()
pdf_content = info.pdf.get_content()
# write the contents to a file:
with open("company-info.pdf", "wb") as f:
    f.write(pdf_content)
```

--------------------------------

### List Emitted and Received CFDI Bills

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Use this to retrieve lists of emitted or received bills within a specified date range or month. Requires importing BillStatus.

```python
from prometeo.sat import BillStatus

emitted_bills = session.get_emitted_bills(
    date_start=datetime(2020, 1, 1),
    date_end=datetime(2020, 2, 1),
    status=BillStatus.ANY,
)

received_bills = session.get_received_bills(
    year=2020,
    month=1,
    status=BillStatus.ANY,
)
```

--------------------------------

### List Emitted Bills

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Retrieves a list of emitted bills within a specified date range and status. Iterates through the results to print bill details.

```python
emitted_bills = session.get_emitted_bills(
    date_start=datetime(2024, 1, 1),
    date_end=datetime(2024, 1, 31),
    status=BillStatus.ANY  # Options: ANY, VALID, CANCELLED
)
for bill in emitted_bills:
    print(f"Bill ID: {bill.id}")
    print(f"Emitter RFC: {bill.emitter_rfc}")
    print(f"Emitter: {bill.emitter_reason}")
    print(f"Receiver RFC: {bill.receiver_rfc}")
    print(f"Receiver: {bill.receiver_reason}")
    print(f"Emitted Date: {bill.emitted_date}")
    print(f"Certification Date: {bill.certification_date}")
    print(f"Total Value: {bill.total_value}")
    print(f"Status: {bill.status}")
    print("---")
```

--------------------------------

### Validate Bank Accounts

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Verify bank account information across different countries using specific formats like CLABE or CCI.

```python
from prometeo import Client
from prometeo.account_validation import exceptions

client = Client('<YOUR_API_KEY>', environment='sandbox')

# Validate a Brazilian account (local format)
try:
    result = client.account_validation.validate(
        account_number="1001",
        country_code="BR",
        document_number="58.547.642/0001-95",
        branch_code="00001",
        bank_code="999",
        account_type="CHECKING"
    )
    print(f"Beneficiary Name: {result.beneficiary_name}")
    print(f"Account Type: {result.account_type}")
    print(f"Bank Name: {result.bank_name}")
except exceptions.InvalidAccountError as e:
    print(f"Invalid account: {e.message}")
except exceptions.PendingValidationError as e:
    print(f"Validation pending: {e.message}")

# Validate a Mexican account (CLABE format)
result = client.account_validation.validate(
    account_number="999000000000000001",
    country_code="MX"
)

# Validate a Peruvian account (CCI format)
result = client.account_validation.validate(
    account_number="99900000000000000030",
    country_code="PE"
)

# Validate a Uruguayan account
result = client.account_validation.validate(
    account_number="0000",
    country_code="UY",
    bank_code="999"
)
```

--------------------------------

### List Received Bills

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Fetches received bills for a specific month and year, filtering by status.

```python
received_bills = session.get_received_bills(
    year=2024,
    month=1,
    status=BillStatus.VALID
)
```

--------------------------------

### Access Colombian DIAN Tax Information

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Authenticate as a company or individual to retrieve tax declarations, balances, and company information. Sessions can be restored using a session key.

```python
from datetime import datetime
from prometeo import Client
from prometeo.dian import (
    DocumentType, Periodicity, QuarterlyPeriod,
    MonthlyPeriod, NumerationType
)

client = Client('<YOUR_API_KEY>', environment='sandbox')

# Login as a company (with NIT)
session = client.dian.login(
    nit='098765',
    document_type=DocumentType.CEDULA_CIUDADANIA,
    document='12345',
    password='test_password'
)

# Login as a person (without NIT)
session = client.dian.login(
    document_type=DocumentType.CEDULA_CIUDADANIA,
    document='12345',
    password='test_password'
)

# Get company information (Form 001)
info = session.get_company_info()
print(f"Company Name: {info.name}")
print(f"Reason: {info.reason}")
print(f"Constitution Date: {info.constitution_date}")
print(f"Location: {info.location}")
print("Representatives:")
for rep in info.representation:
    print(f"  - {rep.name.first} {rep.name.last}")
# Download PDF
pdf_content = info.pdf.get_content()
with open("company-info.pdf", "wb") as f:
    f.write(pdf_content)

# Get balances
balances = session.get_balances()
for balance in balances:
    print(f"Year: {balance.year}, Amount: {balance.amount}")

# Get rent declaration (Form 110/210)
rent = session.get_rent_declaration(2023)
print(f"Year: {rent.year}")
print(f"Form Number: {rent.form_number}")
print(f"NIT: {rent.nit}")
for field in rent.fields:
    print(f"  {field.code}: {field.value}")

# Get VAT declaration (Form 300)
vat = session.get_vat_declaration(
    year=2023,
    periodicity=Periodicity.QUARTERLY,
    period=QuarterlyPeriod.JANUARY_APRIL
)
print(f"VAT Declaration Year: {vat.year}, Period: {vat.period}")

# Get bill numeration (Form 1876)
numerations = session.get_numeration(
    type=NumerationType.Authorization,
    date_start=datetime(2023, 1, 1),
    date_end=datetime(2023, 12, 31)
)
for num in numerations:
    print(f"NIT: {num.nit}, Reason: {num.reason}")
    for r in num.ranges:
        print(f"  Range: {r.from_number} to {r.to_number}")

# Get retentions (Form 350)
retentions = session.get_retentions(
    year=2023,
    period=MonthlyPeriod.NOVEMBER
)
print(f"Retentions Year: {retentions.year}, Period: {retentions.period}")

# Restore session for later use
session_key = session.get_session_key()
restored_session = client.dian.get_session(session_key)
```

--------------------------------

### Add Withdrawal Account to Customer

Source: https://context7.com/prometeoapi/prometeo-python/llms.txt

Adds a withdrawal account to an existing customer profile. Requires the customer's ID and the account details.

```python
# Add withdrawal account to customer
account_data = WithdrawalAccountInput(
    account_number="123456789012",
    bank_code="014",
    account_type="CHECKING"
)
client.crossborder.add_withdrawal_account(customer.id, account_data)
```

--------------------------------

### Validate Account in MX

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Validate an account number for Mexico using the Account Validation API.

```python
result = client.account_validation.validate(
    account_number="999000000000000014",
    country_code="MX"
)
```

--------------------------------

### Check CURP Existence

Source: https://github.com/prometeoapi/prometeo-python/blob/master/README.md

Check if a CURP exists using the CURP API. Catches and prints a CurpError if the CURP does not exist.

```python
from prometeo.curp import exceptions

curp = 'ABCD12345EFGH'
try:
    result = client.curp.query(curp)
except exceptions.CurpError as e:
    print("CURP does not exist:", e.message)
```

--------------------------------

### Confirm a Transfer

Source: https://github.com/prometeoapi/prometeo-python/blob/master/docs/guides/banking.md

Finalize a transfer using the request ID and required authorization data.

```python
confirmation = session.confirm_transfer(
  request_id='0b7d6b32d1be4c11bde21e7ddc08cc36',
  authorization_type='cardCode',
  authorization_data='1, 2, 3',
)

print(confirmation)
```