nox-py-sdk 0.1.0
An SDK made with Python to interact with the Checkout API and V2 API in a simple and efficient way.
Requires Python: >=3.6

# Nox SDK

**An SDK made with Python to interact with the Checkout API and V2 API in a simple and efficient way.**

## Installing

```bash
pip install nox-py-sdk
```

## Checkout API

### Setup

To use the SDK, you will need an API token generated by the Nox system.

```py
from nox_py_sdk import CheckoutAPI

token = 'your_api_token'

checkout_api = CheckoutAPI(token)
```

### Using Checkout API methods

#### Listing Checkouts
Gets a list of checkouts based on the given query parameters.

`get_checkouts(query_params: Optional[Dict[str, Any]] = None) -> GetCheckoutsResponse`

Usage Example:
```py
response = checkout_api.get_checkouts({
    'page': 1,
    'created_at_start': '2024-04-08',
    'created_at_end': '2024-05-08'
})
print(response.checkouts)
```

Response:
```json
{
    "checkouts": [
        {
            "id": 1,
            "image": "base64image",
            "image_type": "image/png",
            "description": "Teste",
            "price": "50.00",
            "redirect_url": "https://example.com",
            "is_enabled": true,
            "theme_color": "custom",
            "payment_method": "all",
            "colors": {
                "primary": "#F2F2F2",
                "secondary": "#FFFFFF",
                "text": "#334155",
                "button": "#3F438C",
                "textButton": "#FFFFFF"
            },
            "created_at": "2024-06-13T18:41:20.329Z",
            "url_id": "f25f51c9-0a90-41c9-9571-035813ae0000"
        }
    ],
    "current_page": 1,
    "total_pages": 1
}
```

#### Retrieving Checkout
Retrieves a checkout using its `url_id` identifier.

`get_checkout(url_id: str) -> CheckoutDetail`

Usage Example:
```py
checkout = checkout_api.get_checkout('123')
print(checkout)
```

Response:
```json
{
    "image": "base64image",
    "description": "Produto teste",
    "price": "10.00",
    "redirect_url": "https://example.com",
    "is_enabled": true,
    "payment_method": "all",
    "url_id": "0989d6cc-b02c-493b-b953-dab39dbc1111",
    "colors": {
        "primary": "#F2F2F2",
        "secondary": "#FFFFFF",
        "text": "#334155",
        "button": "#3F438C",
        "textButton": "#FFFFFF"
    },
    "code": "string",
    "txid": "string"
}
```

#### Creating Checkout
Create a new checkout with the provided data.
`create_checkout(data: CreateCheckoutData, file: Optional[IO] = None) -> CreateCheckoutResponse`

Usage Example:
```py
data = {
    'colors': {
        'primary': '#000000',
        'secondary': '#FFFFFF',
        'text': '#333333',
        'button': '#FF0000',
        'textButton': '#FFFFFF'
    },
    'price': 1000,
    'description': 'Produto teste',
    'redirect_url': 'https://example.com',
    'payment_method': 'credit_card',
    'is_enabled': True,
    'theme_color': '#FF00FF'
}

response = checkout_api.create_checkout(data, file)
print(response)
```
Response:
```json
{
    "id": 1,
    "url_id": "87ff1499-dab3-44e6-9538-3cbb05b66666"
}
```

#### Updating Checkout
Updates data from an existing checkout.

`update_checkout(id: int, data: UpdateCheckoutData, file: Optional[IO] = None) -> UpdateCheckoutResponse`

Usage Example:
```py
update_data = {
    'price': 1200,
    'change_image': False
}

response = checkout_api.update_checkout(123, update_data, new_file)
print(response.detail)
```
Response:
```json
{
    "detail": "Checkout updated successfully."
}
```

#### Error Handling
In case of errors, the methods will throw an exception with a detailed message

```py
try:
    checkout = checkout_api.get_checkout('123')
except Exception as e:
    print(e)
```

## V2 API

### Setup

To use the SDK, you will need an API token and a merchant resgistration. To achieve them, you must get in contact with Nox, so we can provide them to you.


```py
from nox_py_sdk import V2API

token = 'your_api_token'

v2_api = V2API(token)
```

### Using V2 API methods

#### Get Account.
Retrieves the account information associated with the API token.
`get_account() -> Account`

Usage Example:
```py
account = v2_api.get_account()
print(account)
```
Response:
```json
{
    "name": "John Doe",
    "balance": 1500.50
}
```

#### Create Payment Method
Creates a new payment using the specified method and details.
`create_payment(data: CreatePaymentData) -> CreatePaymentResponse`

Usage Example:
```py
payment_response = v2_api.create_payment({
    'method': 'PIX',
    'code': '123456',
    'amount': 1000
})
print(payment_response)
```

Response:
```json
{
    "method": "PIX",
    "code": "123456",
    "amount": 1000,
    "qrcode": "https://api.example.com/qrcode",
    "qrcodebase64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "copypaste": "1234567890",
    "txid": "abc123",
    "Status": "WAITING_PAYMENT"
}
```

#### Create Cash-out Payment
Creates a new cash-out payment.
`create_payment_cash_out(data: CreatePaymentData) -> Payment`

Usage Example:
```py
payment_response = v2_api.create_payment({
    'method': 'PIX',
    'code': '123456',
    'amount': 1000,
    'type': 'PIX_KEY',
    'pixkey': 'your-pix-key',
})
print(payment_response)
```

Response:
```json
{
    "Method": "PIXOUT",
    "Status": "SENT",
    "Code": "123456",
    "TxID": "abc123",
    "Amount": 1000,
}
```
#### Retrieve Payment's Info
Fetches the details of a specific payment by its `code` or `tx_id`.
`get_payment(identifier: str) -> Payment`

Usage Example:
```py
payment = v2_api.get_payment('payment-identifier')
print(payment)
```

Response:
```json
{
    "Method": "PIX",
    "Status": "PAID",
    "Code": "123456",
    "TxID": "abc123",
    "Amount": 1000,
    "end2end": "e2e123",
    "receipt": "https://api.example.com/receipt"
}
```

#### Resend Webhook
Resends the webhook for a specific transaction.
`resend_webhook(txid: str) -> None`

Usage Example:
```py
v2_api.resend_webhook('txid')
```

#### Send Transactions Report
Generates and sends a transaction report based on the specified
filters to merchant email associated with the token in csv format.
`send_transactions_report(filters: TransactionsRequestFilters) -> None`

Usage Example:
```py
v2_api.send_transactions_report({
    'begin_date': '2024-01-01',
    'end_date': '2024-01-31',
    'method': 'PIX',
    'status': 'PAID'
})
```

#### Create Credit Card Payment
Creates a new payment using a credit card.
`create_credit_card_payment(data: CreateCreditCardPaymentData) -> CreditCardPaymentResponse`

Usage Example:
```py
credit_card_payment_response = v2_api.create_credit_card_payment({
    'amount': 1000,
    'email': 'user@example.com',
    'code': '123456',
    'name': 'User Name',
    'cpf_cnpj': '12345678900',
    'expired_url': 'https://example.com/expired',
    'return_url': 'https://example.com/return',
    'max_installments_value': 200,
    'soft_descriptor_light': 'COMPANY NAME'
})
print(credit_card_payment_response)
```

Response:
```json
{
    "id": "cc123",
    "due_date": "2024-12-31",
    "currency": "BRL",
    "email": "user@example.com",
    "status": "pending",
    "total_cents": 1000,
    "order_id": "order123",
    "secure_id": "secure123",
    "secure_url": "https://api.example.com/secure",
    "total": "10.00",
    "created_at_iso": "2024-09-01T12:34:56Z"
}
```

#### Retrieve Credit Card Payment
Retrieves details of a specific credit card payment by its identifier.
`get_credit_card_payment(identifier: str) -> CreditCardPayment`

Usage Example:
```py
payment = v2_api.get_credit_card_payment('credit-card-identifier')
print(payment)
```

Response:
```json
{
    "id": 123,
    "status": "PAID",
    "code": "cc123",
    "txid": "tx123",
    "amount": 1000,
    "created_at": "2024-09-01T12:34:56Z",
    "paid_at": "2024-09-01T13:00:00Z",
    "canceled_at": null,
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "customer_document": "123.456.789-00",
    "merchant_id": 456,
    "id_from_bank": "bank123"
}
```

#### Error Handling
In case of errors, the methods will throw an exception with a detailed message

```py
try:
    checkout = v2_api.get_credit_card_payment('identifier')
except Exception as e:
    print(e)
```