Pagination - Smartbills

Aperçu

Tous les points d’accès de liste de l’API Smartbills retournent des résultats paginés. La pagination vous permet de récupérer efficacement de grands ensembles de données en les divisant en pages plus petites.

Paramètres de requête

Tous les points d’accès de liste acceptent ces paramètres de pagination et de tri :

integer

défaut:"1"

Numéro de page à récupérer (commence à 1)

integer

défaut:"20"

Nombre d’éléments par page. Minimum : 1, Maximum : 100, Défaut : 20

string

défaut:"createdAt"

Champ de tri des résultats (ex. : createdAt, date, amount)

string

défaut:"desc"

Direction du tri : asc (croissant) ou desc (decroissant)

Format de réponse

Les réponses paginéess incluent le tableau de données et un objet de métadonnées de pagination :

{
  "data": [
    {
      "id": 1,
      "merchant": "Bureau en Gros",
      "amount": 45.99
    },
    {
      "id": 2,
      "merchant": "Staples",
      "amount": 32.50
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 5,
    "totalCount": 95,
    "hasNext": true,
    "hasPrevious": false
  }
}

Objet de pagination

object

Métadonnées de pagination

Afficher Propriétés

integer

Numéro de page actuel

integer

Nombre d’éléments par page

integer

Nombre total de pages disponibles

integer

Nombre total d’éléments sur toutes les pages

boolean

Indique s’il y à une page suivante disponible

boolean

Indique s’il y à une page précédente disponible

Exemples de base

Première page

Récupérer la première page de résultats avec tri :

curl --request GET \
  --url 'https://api.smartbills.io/v1/expenses?page=1&pageSize=20&sortBy=date&sortOrder=desc' \
  --header 'Authorization: Bearer VOTRE_CLE_API' \
  --header 'x-tenant-id: 123'

import { SmartbillsClient } from '@smartbills/sdk';

const client = new SmartbillsClient({
  accessToken: 'VOTRE_CLE_API',
  businessId: 123
});

const result = await client.expenses.list({
  page: 1,
  pageSize: 20,
  sortBy: 'date',
  sortOrder: 'desc'
});

console.log(`Page ${result.pagination.page} sur ${result.pagination.totalPages}`);
console.log(`Total d'éléments : ${result.pagination.totalCount}`);

from smartbills import SmartbillsClient

client = SmartbillsClient(access_token="VOTRE_CLE_API", business_id=123)

result = client.expenses.list(
    page=1,
    page_size=20,
    sort_by="date",
    sort_order="desc"
)

print(f"Page {result.pagination.page} sur {result.pagination.total_pages}")
print(f"Total d'éléments : {result.pagination.total_count}")

Page suivante

Naviguer à la page suivante en verifiant hasNext :

curl --request GET \
  --url 'https://api.smartbills.io/v1/expenses?page=2&pageSize=20&sortBy=date&sortOrder=desc' \
  --header 'Authorization: Bearer VOTRE_CLE_API' \
  --header 'x-tenant-id: 123'

if (result.pagination.hasNext) {
  const nextPage = result.pagination.page + 1;
  const nextResult = await client.expenses.list({
    page: nextPage,
    pageSize: 20,
    sortBy: 'date',
    sortOrder: 'desc'
  });
}

if result.pagination.has_next:
    next_page = result.pagination.page + 1
    next_result = client.expenses.list(
        page=next_page,
        page_size=20,
        sort_by="date",
        sort_order="desc"
    )

Parcourir toutes les pages

Iteration simple

Parcourir toutes les pages pour récupérer tous les résultats :

async function getAllExpenses(client) {
  const allExpenses = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const result = await client.expenses.list({
      page: page,
      pageSize: 100
    });

    allExpenses.push(...result.data);
    hasMore = result.pagination.hasNext;
    page++;
  }

  return allExpenses;
}

const client = new SmartbillsClient({
  accessToken: 'VOTRE_CLE_API',
  businessId: 123
});

const expenses = await getAllExpenses(client);
console.log(`${expenses.length} dépenses récupérées`);

def get_all_expenses(client):
    all_expenses = []
    page = 1
    has_more = True

    while has_more:
        result = client.expenses.list(page=page, page_size=100)
        all_expenses.extend(result.data)
        has_more = result.pagination.has_next
        page += 1

    return all_expenses

client = SmartbillsClient(access_token="VOTRE_CLE_API", business_id=123)

expenses = get_all_expenses(client)
print(f"{len(expenses)} dépenses récupérées")

Avec gestion des erreurs et limitation de débit

Pagination prête pour la production avec gestion des erreurs :

async function getAllExpensesSafely(client) {
  const allExpenses = [];
  let page = 1;
  const maxPages = 100; // Limite de sécurité

  while (page <= maxPages) {
    try {
      const result = await client.expenses.list({
        page: page,
        pageSize: 100
      });

      allExpenses.push(...result.data);
      console.log(`Page ${page}/${result.pagination.totalPages} recuperee`);

      if (!result.pagination.hasNext) {
        break;
      }

      page++;
      // Petit delai pour respecter les limites de debit
      await new Promise(resolve => setTimeout(resolve, 100));
    } catch (error) {
      console.error(`Erreur lors de la récupération de la page ${page} :`, error);
      throw error;
    }
  }

  return allExpenses;
}

import time

def get_all_expenses_safely(client):
    all_expenses = []
    page = 1
    max_pages = 100  # Limite de sécurité

    while page <= max_pages:
        try:
            result = client.expenses.list(page=page, page_size=100)
            all_expenses.extend(result.data)
            print(f"Page {page}/{result.pagination.total_pages} recuperee")

            if not result.pagination.has_next:
                break

            page += 1
            time.sleep(0.1)  # Petit delai pour respecter les limites de debit
        except Exception as e:
            print(f"Erreur lors de la récupération de la page {page} : {e}")
            raise

    return all_expenses

Pagination avec filtres

Combinez la pagination avec le filtrage pour affiner vos résultats :

curl --request GET \
  --url 'https://api.smartbills.io/v1/expenses?page=1&pageSize=50&status=pending&sortBy=amount&sortOrder=desc' \
  --header 'Authorization: Bearer VOTRE_CLE_API' \
  --header 'x-tenant-id: 123'

const result = await client.expenses.list({
  page: 1,
  pageSize: 50,
  status: 'pending',
  sortBy: 'amount',
  sortOrder: 'desc'
});

result = client.expenses.list(
    page=1,
    page_size=50,
    status="pending",
    sort_by="amount",
    sort_order="desc"
)

Limites de pagination

Taille maximale de page

Maximum : 100 éléments par page
Défaut : 20 éléments par page
Minimum : 1 élément par page

Demander plus de 100 éléments par page entrainera une erreur de validation 400 Bad Request.

Bonnes pratiques

Utiliser des tailles de page appropriees

Petites pages (20-50) : Mieux pour la pagination UI et une réponse initiale plus rapide
Grandes pages (100) : Mieux pour le traitement en lot et moins d’appels API
Défaut (20) : Bon equilibre pour la plupart des cas d’utilisation

Toujours vérifier hasNext

Vérifiez toujours hasNext avant de récupérer la page suivante. Cela evite les appels API inutiles lorsque vous avez atteint la fin des résultats.

Gérer les limites de débit

Ajoutez de petits délais entre les requêtes lors de la récupération de plusieurs pages pour eviter d’atteindre les limites de débit. Consultez Limites de débit pour plus de détails.

Mettre en cache les résultats

Mettez en cache les résultats paginés pour réduire les appels API redondants, surtout pour les données qui ne changent pas frequemment.

Utiliser des filtres pour réduire les données

Appliquez des filtres pour affiner les résultats avant de paginer, réduisant le nombre total de pages et d’appels API nécessaires.

Dépannage

Résultats vides sur une page valide

Causes possibles : Les données ont été supprimées entre les requêtes, les filtres sont trop restrictifs, ou une condition de concurrence avec des modifications simultanées. Solution : Recommencez depuis le début ou ajustez vos filtres.

Nombre de pages incohérent

Raison : C’est normal. Les données peuvent être ajoutees ou supprimées pendant la pagination. Solution : Utilisez hasNext au lieu de totalPages pour la logique d’iteration.

Performance de pagination lente

Solutions : Utilisez des tailles de page plus grandes (jusqu’a 100), ajoutez des filtres pour réduire le jeu de données total, mettez en cache les résultats, ou utilisez des webhooks pour les mises à jour en temps réel au lieu du polling.

Ressources connexes

Limites de débit

Comprendre la limitation de débit de l’API

Gestion des erreurs

Gérer les erreurs de pagination

Lister les dépenses

Point d’accès de liste des dépenses

Webhooks

Notifications en temps réel

​Aperçu

​Paramètres de requête

Aperçu

Paramètres de requête