> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneclickdz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Intégration SDK Python

> Guide de configuration rapide pour le SDK Navio Python

## Vue d'ensemble

Le SDK Navio Python fournit une interface claire et idiomatique pour intégrer les paiements Navio dans vos applications Python. Conçu avec les annotations de type Python 3.8+ et les dataclasses pour la meilleure expérience développeur.

<CardGroup cols={2}>
  <Card title="API Pythonique" icon="code" color="#0D9373">
    Interface claire avec annotations de type complètes et dataclasses
  </Card>

  <Card title="Type Safe" icon="shield-check" color="#0D9373">
    Annotations de type complètes avec dataclasses et enums
  </Card>

  <Card title="Validation des entrées" icon="circle-check" color="#0D9373">
    Validation côté client pour un retour d'erreur rapide
  </Card>

  <Card title="Dépendances minimales" icon="box" color="#0D9373">
    Ne requiert que le package `requests`
  </Card>
</CardGroup>

## Prérequis

* Python 3.8 ou supérieur
* pip

## Installation

Installez via pip :

```bash theme={null}
pip install ocpay-python-sdk
```

Ou installez depuis les sources :

```bash theme={null}
git clone https://github.com/oneclickdz/ocpay-python-sdk.git
cd ocpay-python-sdk
pip install -e .
```

## Démarrage rapide

### 1. Initialiser le SDK

```python theme={null}
from ocpay import OCPay

ocpay = OCPay("your-api-access-token")
```

<Warning>
  Stockez votre clé API dans des variables d'environnement, jamais codée en dur dans le code source.
</Warning>

### 2. Créer un lien de paiement

```python theme={null}
from ocpay import OCPay, FeeMode
from ocpay.types import ProductInfo, CreateLinkRequest

ocpay = OCPay("your-api-key")

request = CreateLinkRequest(
    product_info=ProductInfo(
        title="Premium Subscription",
        amount=5000,  # Amount in DZD (500–500,000)
        description="Monthly access to all premium features",
    ),
    fee_mode=FeeMode.NO_FEE,
    success_message="Thank you for your purchase!",
    redirect_url="https://yourstore.com/success?orderId=12345",
)

response = ocpay.create_link(request)

# Share this URL with your customer
print("Payment URL:", response.payment_url)

# Save this reference for tracking
print("Payment Reference:", response.payment_ref)
```

### 3. Vérifier le statut du paiement

```python theme={null}
from ocpay import OCPay

ocpay = OCPay("your-api-key")

status = ocpay.check_payment("OCPL-A1B2C3-D4E5")

if status.is_confirmed():
    print("Payment confirmed!")
    if status.transaction_details:
        print(f"Amount: {status.transaction_details.amount} DZD")
elif status.is_pending():
    print("Payment still pending...")
elif status.is_failed():
    print(f"Payment failed: {status.message}")
```

## Exemple e-commerce complet

<Accordion title="Flux e-commerce complet">
  ```python theme={null}
  from ocpay import (
      OCPay,
      FeeMode,
      ValidationException,
      ApiException,
  )
  from ocpay.types import ProductInfo, CreateLinkRequest

  # Initialize SDK
  ocpay = OCPay("your-api-key")

  # Step 1: Create payment link for your order
  order_id = "ORD-12345"
  response = ocpay.create_link(CreateLinkRequest(
      product_info=ProductInfo(
          title=f"Order #{order_id}",
          amount=8000,
          description=f"Payment for order #{order_id}",
      ),
      fee_mode=FeeMode.NO_FEE,
      success_message=f"Thank you! Your order #{order_id} is being processed.",
      redirect_url=f"https://yourstore.com/orders/{order_id}/success",
  ))

  # Step 2: Save payment reference to your database
  print(f"Payment URL: {response.payment_url}")
  print(f"Payment Ref: {response.payment_ref}")

  # Step 3: Check payment status (in webhook or polling job)
  status = ocpay.check_payment(response.payment_ref)

  if status.is_confirmed():
      print("✅ Payment confirmed - fulfilling order")
  elif status.is_failed():
      print("❌ Payment failed")
  else:
      print("⏳ Payment is pending")
  ```
</Accordion>

## Référence API

### Classe OCPay

Point d'entrée principal du SDK.

#### Constructeur

```python theme={null}
OCPay(access_token: str, options: ClientOptions = None)
```

<ParamField body="access_token" type="string" required>
  Votre token d'accès API OneClickDz.
</ParamField>

<ParamField body="options" type="ClientOptions">
  Configuration optionnelle du client.

  <Expandable title="Propriétés de ClientOptions">
    <ParamField body="timeout" type="int">
      Délai de la requête en secondes. Défaut : `30`.
    </ParamField>

    <ParamField body="base_url" type="string">
      URL de base personnalisée, principalement utilisée pour les tests.
    </ParamField>

    <ParamField body="headers" type="dict">
      En-têtes supplémentaires à inclure dans chaque requête.
    </ParamField>
  </Expandable>
</ParamField>

**Exemple :**

```python theme={null}
from ocpay import OCPay, ClientOptions

ocpay = OCPay("your-api-key", options=ClientOptions(timeout=60))
```

#### `create_link(request)`

Crée un nouveau lien de paiement.

<ParamField body="request" type="CreateLinkRequest" required>
  Requête de création de lien de paiement.

  <Expandable title="Propriétés de CreateLinkRequest">
    <ParamField body="product_info" type="ProductInfo" required>
      Informations sur le produit.

      <Expandable title="Propriétés de ProductInfo">
        <ParamField body="title" type="string" required>
          Nom du produit ou service (1–200 caractères).
        </ParamField>

        <ParamField body="amount" type="int" required>
          Montant en DZD (500–500 000). Doit être un nombre entier.
        </ParamField>

        <ParamField body="description" type="string">
          Description optionnelle du produit (max 1000 caractères).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="fee_mode" type="FeeMode">
      Qui paie les frais de transaction. Défaut : `FeeMode.NO_FEE`.
    </ParamField>

    <ParamField body="success_message" type="string">
      Message optionnel affiché au client après le paiement (max 500 caractères).
    </ParamField>

    <ParamField body="redirect_url" type="string">
      URL optionnelle pour rediriger le client après le paiement.
    </ParamField>
  </Expandable>
</ParamField>

**Retourne :**

<ResponseField name="payment_url" type="string">
  L'URL de la page de paiement à partager avec votre client.
</ResponseField>

<ResponseField name="payment_ref" type="string">
  Code de référence de paiement unique (ex. `OCPL-A1B2C3-D4E5`). Sauvegardez-le pour suivre le statut du paiement.
</ResponseField>

**Lève :** `ValidationException` (400), `UnauthorizedException` (403), `ApiException`

#### `check_payment(payment_ref)`

Vérifie le statut d'un paiement.

<ParamField body="payment_ref" type="string" required>
  Code de référence de paiement retourné par `create_link` (ex. `"OCPL-A1B2C3-D4E5"`).
</ParamField>

**Retourne :**

<ResponseField name="status" type="PaymentStatus">
  Statut actuel du paiement : `PENDING`, `CONFIRMED` ou `FAILED`.
</ResponseField>

<ResponseField name="message" type="string">
  Message de statut lisible par l'humain.
</ResponseField>

<ResponseField name="transaction_details" type="TransactionDetails">
  Détails de la transaction confirmée. Présent uniquement quand `status` est `CONFIRMED`.
</ResponseField>

**Lève :** `NotFoundException` (404), `PaymentExpiredException` (410), `ApiException`

### Enums

#### FeeMode

| Valeur                 | Description                                   |
| ---------------------- | --------------------------------------------- |
| `FeeMode.NO_FEE`       | Le marchand paie tous les frais (défaut)      |
| `FeeMode.SPLIT_FEE`    | Frais partagés 50/50 entre marchand et client |
| `FeeMode.CUSTOMER_FEE` | Le client paie tous les frais                 |

#### PaymentStatus

| Valeur                    | Description                                |
| ------------------------- | ------------------------------------------ |
| `PaymentStatus.PENDING`   | Le paiement est en cours                   |
| `PaymentStatus.CONFIRMED` | Le paiement s'est terminé avec succès      |
| `PaymentStatus.FAILED`    | Le paiement a été refusé, expiré ou annulé |

### Classes d'exception

<AccordionGroup>
  <Accordion title="ValidationException - HTTP 400">
    Levée quand les données de la requête sont invalides (ex. montant hors limites, champs requis manquants).

    **Propriétés :** `message`, `status_code`, `request_id`, `error_data`
  </Accordion>

  <Accordion title="UnauthorizedException - HTTP 403">
    Levée quand l'authentification échoue. Vérifiez que votre clé API est valide et active.

    **Propriétés :** `message`, `status_code`, `request_id`, `error_data`
  </Accordion>

  <Accordion title="NotFoundException - HTTP 404">
    Levée quand la référence de paiement n'existe pas.

    **Propriétés :** `message`, `status_code`, `request_id`, `error_data`
  </Accordion>

  <Accordion title="PaymentExpiredException - HTTP 410">
    Levée quand le lien de paiement a expiré. Les liens expirent 20 minutes après la création.

    **Propriétés :** `message`, `status_code`, `request_id`, `error_data`
  </Accordion>

  <Accordion title="ApiException - divers">
    Exception de base pour toutes les autres erreurs API. Capturez-la comme fallback.

    **Propriétés :** `message`, `status_code`, `request_id`, `error_data`
  </Accordion>
</AccordionGroup>

## Gestion des erreurs

```python theme={null}
from ocpay import (
    OCPay,
    ApiException,
    ValidationException,
    UnauthorizedException,
    NotFoundException,
    PaymentExpiredException,
)

ocpay = OCPay("your-api-key")

try:
    response = ocpay.create_link(request)
except ValidationException as e:
    print(f"Validation error: {e.message}")
    print(f"Request ID: {e.request_id}")
except UnauthorizedException as e:
    print("Authentication failed. Check your API key.")
except NotFoundException as e:
    print(f"Not found: {e.message}")
except PaymentExpiredException as e:
    print(f"Payment expired: {e.message}")
except ApiException as e:
    print(f"API error: {e.message} (status {e.status_code})")
    print(f"Request ID: {e.request_id}")
```

## Intégration avec les frameworks

<Tabs>
  <Tab title="Flask">
    ```python theme={null}
    from flask import Flask, jsonify, request
    from ocpay import OCPay, FeeMode
    from ocpay.types import CreateLinkRequest, ProductInfo

    app = Flask(__name__)
    ocpay = OCPay("your-api-key")

    @app.route("/api/payment", methods=["POST"])
    def create_payment():
        data = request.json
        response = ocpay.create_link(CreateLinkRequest(
            product_info=ProductInfo(
                title=data["title"],
                amount=data["amount"],
            ),
            fee_mode=FeeMode.NO_FEE,
        ))
        return jsonify({
            "payment_url": response.payment_url,
            "payment_ref": response.payment_ref,
        })
    ```
  </Tab>

  <Tab title="Django">
    ```python theme={null}
    from ocpay import OCPay, FeeMode
    from ocpay.types import CreateLinkRequest, ProductInfo

    ocpay = OCPay(settings.OCPAY_API_KEY)

    def create_order_payment(order):
        response = ocpay.create_link(CreateLinkRequest(
            product_info=ProductInfo(
                title=f"Order #{order.id}",
                amount=order.total,
            ),
            fee_mode=FeeMode.NO_FEE,
            redirect_url=f"https://yourstore.com/orders/{order.id}/success",
        ))
        order.payment_ref = response.payment_ref
        order.save()
        return response.payment_url
    ```
  </Tab>

  <Tab title="FastAPI">
    ```python theme={null}
    from fastapi import FastAPI
    from ocpay import OCPay, FeeMode
    from ocpay.types import CreateLinkRequest, ProductInfo

    app = FastAPI()
    ocpay = OCPay("your-api-key")

    @app.post("/api/payment")
    async def create_payment(title: str, amount: int):
        response = ocpay.create_link(CreateLinkRequest(
            product_info=ProductInfo(title=title, amount=amount),
            fee_mode=FeeMode.NO_FEE,
        ))
        return {
            "payment_url": response.payment_url,
            "payment_ref": response.payment_ref,
        }
    ```
  </Tab>
</Tabs>

## Notes importantes

<Warning>
  **Validation du marchand requise** - Complétez la validation du marchand sur [app.oneclickdz.com/profile](https://app.oneclickdz.com/profile) avant d'utiliser l'API.
</Warning>

<Warning>
  **Limites de montant** - Minimum 500 DZD, maximum 500 000 DZD. Doit être un nombre entier (pas de décimales).
</Warning>

<Note>
  **Expiration du lien** - Les liens de paiement expirent 20 minutes après leur création. Après expiration, le statut devient `FAILED`.
</Note>

<Note>
  **Tests en Sandbox** - Utilisez votre clé API sandbox pour les tests. Vérifiez `response.payment_link.is_sandbox` pour confirmer le mode test.
</Note>

<CardGroup cols={3}>
  <Card title="Référence API" icon="square-terminal" href="/fr/api-reference/ocpay/create-link">
    Voir les endpoints API Navio
  </Card>

  <Card title="Support" icon="envelope" href="mailto:support@oneclickdz.com">
    Contacter notre équipe de support
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/oneclickdz/ocpay-python-sdk">
    Voir le code source sur GitHub
  </Card>
</CardGroup>