dougs-api

Client TypeScript non-officiel pour l'API interne de Dougs, reverse-engineered depuis les requêtes XHR/Fetch du SPA Angular.

Non affilié à Dougs. Usage à vos risques. L'API interne peut changer sans préavis.

API officielle en cours : Dougs travaille sur une API publique — liste d'attente beta disponible sur dougs.fr/api. Ce repo est un palliatif le temps que ça arrive.

Auth

Deux options :

Option 1 — Login programmatique

import { DougsClient } from './client';

const dougs = await DougsClient.login('[email protected]', 'motdepasse');

⚠️ Limitations connues du login programmatique :

• 2FA activée → throw immédiat (enabledAuthFactors non vide)
• Compte SSO / Google → pas de mot de passe Dougs, donc ça échoue
• Dougs peut ajouter du rate-limiting ou captcha à tout moment
• Si ça ne marche pas → utiliser l'option 2

Option 2 — Cookie de session (toujours fiable)

1. Ouvre app.dougs.fr dans Chrome, connecte-toi
2. F12 → Application → Cookies → app.dougs.fr → copie la valeur de auth_session

const dougs = new DougsClient('valeur_auth_session_ici');
// ou avec le préfixe complet :
const dougs = new DougsClient('auth_session=valeur_ici');

Endpoints découverts

Méthode	URL	Description
POST	/auth/api/login	Login email/password → { status, accessToken, refreshToken }
GET	/users/me	Utilisateur connecté + ses sociétés
GET	/companies/:id	Détails de la société
GET	/companies/:id/operations	Écritures comptables
GET	/companies/:id/vendor-invoices	Factures d'achat
GET	/companies/:id/vendor-invoices/:id	Détail facture d'achat
GET	/companies/:id/declarations	Déclarations fiscales (TVA, IS…)
GET	/companies/:id/partners	Clients / fournisseurs / associés
GET	/companies/:id/investments	Immobilisations
GET	/companies/:id/accounts	Comptes bancaires
GET	/companies/:id/categories	Plan comptable (2349 catégories)
GET	/companies/:id/salesChannels	Canaux de vente
GET	/companies/:id/accounting-searches	Recherches sauvegardées
GET	/companies/:id/customer-todo	Tâches "À faire" (TVA, DSN, bulletins…)
GET	/companies/:id/connections	Synchronisations bancaires (CIC, Stripe, PayPal…)
GET	/companies/:id/operations/future-dispatch	Ventilations à venir (e-commerce mensuel)
GET	/companies/:id/accounting/negative-associate-accounts	Comptes associés en négatif
GET	/companies/:id/treasury-accounts	Comptes de trésorerie
GET	/companies/:id/customer-deliveries	Livrables (bulletins paie, DSN, clôture…)
GET	/companies/:id/state	État global de la société (comptabilité, social, facturation…)
POST	/companies/:id/fields	Champs custom société
POST	/companies/:id/partners/:id/fields	Champs custom partenaire
POST	/pusher/auth	Auth Pusher WebSocket (temps réel)

Exemples

import { DougsClient } from './client';

// Login (sans 2FA)
const dougs = await DougsClient.login('[email protected]', 'password');

// ou avec cookie manuel
// const dougs = new DougsClient(process.env.DOUGS_SESSION!);

const me = await dougs.getMe();
const companyId = me.preferredCompanyId;

// Opérations non validées
const pending = await dougs.getOperations(companyId, { validated: false });

// Toutes les opérations validées (auto-pagination)
const all = await dougs.getAllOperations(companyId, { validated: true });

// Factures d'achat non payées
const unpaid = await dougs.getVendorInvoices(companyId, { status: 'not_paid' });

// Toutes les factures d'achat (auto-pagination)
const allInvoices = await dougs.getAllVendorInvoices(companyId);

// Déclarations TVA / IS
const decls = await dougs.getDeclarations(companyId);

// Comptes bancaires
const accounts = await dougs.getAccounts(companyId);

// Tâches "À faire" (DSN, TVA, bulletins, documents à signer…)
const todos = await dougs.getCustomerTodo(companyId);
const overdue = todos.filter(t => t.task.overdue);
const declarations = todos.filter(t => t.code === 'customer:declarationNotification');

// Partenaires (clients + fournisseurs)
const partners = await dougs.getPartners(companyId);

Params getOperations

Param	Type	Défaut	Description
limit	number	40	Résultats par page
offset	number	0	Décalage
validated	boolean	false	Écritures validées
needsAttention	boolean	false	Écritures nécessitant une action

MCP Server (Claude / Cursor / Windsurf)

Un serveur MCP est disponible dans mcp/ — il expose toutes les API Dougs comme outils utilisables directement dans Claude Desktop, Cursor, Windsurf, etc.

Installation

cd mcp
npm install
npm run build

Configuration Claude Desktop

Fichier de config :

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows : %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dougs": {
      "command": "node",
      "args": ["/chemin/absolu/vers/dougs-api/mcp/build/index.js"],
      "env": {
        "DOUGS_COOKIE": "auth_session=ta_valeur_ici",
        "DOUGS_COMPANY_ID": "174027"
      }
    }
  }
}

Redémarre Claude Desktop — les outils Dougs apparaissent automatiquement.

Outils disponibles

Outil	Description
dougs_me	Utilisateur connecté + ses sociétés
dougs_company	Détails d'une société
dougs_operations	Écritures comptables (filtres : validé, dates, auto-pagination)
dougs_vendor_invoices	Factures d'achat (filtre : statut paiement)
dougs_declarations	Déclarations fiscales (TVA, IS…)
dougs_partners	Clients / fournisseurs / associés
dougs_accounts	Comptes bancaires
dougs_treasury_accounts	Comptes de trésorerie avec soldes
dougs_investments	Immobilisations
dougs_connections	Synchronisations bancaires
dougs_customer_todo	Tâches « À faire »
dougs_customer_deliveries	Livrables (bulletins paie, DSN, clôture…)
dougs_company_state	État global de la société
dougs_categories	Plan comptable (~2300 catégories)
dougs_sales_channels	Canaux de vente

Exemples de prompts dans Claude

"Quelles sont mes factures non payées sur Dougs ?"

"Montre-moi les tâches en retard sur Dougs"

"Quel est le solde de mes comptes de trésorerie ?"

"Liste toutes les opérations comptables non validées de ce mois"

CLI Go

Un CLI standalone est disponible dans cli/.

Installation

cd cli
go build -o dougs .
# ou directement :
go install github.com/netvolo/dougs-cli@latest

Auth

# Login email/password (échoue si 2FA activée)
dougs login --email [email protected] --password motdepasse

# Ou coller le cookie depuis le navigateur
dougs login --cookie "valeur_auth_session_ici" --company 174027

La session est sauvegardée dans ~/.dougs/config.json. Vous pouvez aussi utiliser :

• --cookie (flag global) ou la variable d'environnement DOUGS_COOKIE
• -c / --company ou la variable DOUGS_COMPANY

Commandes disponibles

Commande	Description
dougs login	Authentification (email/password ou cookie)
dougs me	Utilisateur connecté + ses sociétés
dougs company	Détails de la société
dougs operations	Écritures comptables
dougs invoices	Factures d'achat
dougs accounts	Comptes bancaires
dougs treasury	Comptes de trésorerie
dougs declarations	Déclarations fiscales (TVA, IS…)
dougs partners	Clients / fournisseurs / associés
dougs investments	Immobilisations
dougs connections	Synchronisations bancaires
dougs todo	Tâches « À faire »
dougs deliveries	Livrables (bulletins paie, DSN, clôture…)
dougs state	État global de la société

Exemples

# Toutes les écritures non validées
dougs operations

# Écritures validées avec auto-pagination
dougs operations --validated --all

# Factures non payées en JSON brut
dougs invoices --status not_paid --json

# Tâches en retard
dougs todo --json | jq '[.[] | select(.task.overdue == true)]'

# Société spécifique sans config
dougs accounts --company 174027 --cookie "auth_session=..."

Notes

• Le companyId est visible dans l'URL : app.dougs.fr/app/c/**174027**/...
• Le cookie auth_session expire → relance DougsClient.login() ou re-copie le cookie
• En cas de 401/403, la session a expiré