Document engagement tracking, CRM integration, and multi-channel notification system with Pennylane and ProjectFlow integrations.

Overview

Authentication

POST /auth/token

Request Body

{
  "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
  "password": "your_password"
}

Response

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_at": "2025-01-22T15:00:00Z",
    "refresh_token": "refresh_token_here"
  }
}

POST /auth/refresh

Request Body

{
  "refresh_token": "your_refresh_token"
}

Document Engagements

GET /api/v1/document-engagements

Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 20, max: 100)
status	string	Filter: draft, pending, sent, viewed, downloaded, accepted, signed, paid, rejected, expired, cancelled
document_type	string	Filter: pennylane_quote, pennylane_invoice, project_approval, custom
external_source	string	Filter: pennylane, projectflow
contact_id	integer	Filter by contact
organization_id	integer	Filter by organization
date_from	date	Filter by creation date (YYYY-MM-DD)
date_to	date	Filter by creation date (YYYY-MM-DD)
viewed	boolean	Filter by viewed status
search	string	Search in document number, title, external ID
sort	string	Sort: created_at, updated_at, document_type, status, total_amount, due_date
order	string	asc or desc (default: desc)

POST /api/v1/document-engagements

Parameters

Field	Type	Required	Description
document_type	string	Required	pennylane_quote, pennylane_invoice, project_approval, custom
title	string	Required	Document title (min 3 chars)
external_id	string	Optional	External reference ID
external_source	string	Optional	Source system (pennylane, projectflow)
external_url	string	Optional	URL to external document
contact_id	integer	Optional	Link to contact
organization_id	integer	Optional	Link to organization
total_amount	decimal	Optional	Document amount
currency	string	Optional	Currency code (default: EUR)
due_date	date	Optional	Payment/action due date
pdf_url	string	Optional	URL to PDF file
payment_url	string	Optional	Payment link
metadata	object	Optional	Custom JSON metadata
prefill_data	object	Optional	Data to pre-fill forms

GET /api/v1/document-engagements/{id}

Response

{
  "success": true,
  "data": {
    "id": 1,
    "document_type": "pennylane_quote",
    "external_id": "Q-2024-001",
    "external_source": "pennylane",
    "external_url": "https://pennylane.com/quotes/...",
    "title": "Quote #2024-001",
    "description": "Website redesign project",
    "status": "viewed",
    "recipient_email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
    "recipient_name": "John Doe",
    "recipient_company": "Acme Corp",
    "total_amount": 5000.00,
    "currency": "EUR",
    "due_date": "2025-02-15",
    "view_count": 3,
    "first_viewed_at": "2025-01-20T10:30:00Z",
    "downloaded_at": null,
    "accepted_at": null,
    "signed_at": null,
    "paid_at": null,
    "tokens": [
      {
        "id": 1,
        "token": "abc123...",
        "expires_at": "2025-02-20",
        "use_count": 2,
        "allowed_actions": ["view", "download", "sign"]
      }
    ],
    "recent_events": [
      {
        "event_type": "page_viewed",
        "created_at": "2025-01-20T10:30:00Z",
        "device_type": "desktop"
      }
    ]
  }
}

PUT /api/v1/document-engagements/{id}

Updatable fields: status, due_date, title, description, total_amount, currency, metadata, custom_message

DELETE /api/v1/document-engagements/{id}

Soft deletes the document engagement. Can be restored by admin.

GET /api/v1/document-engagements/stats

Returns statistics on statuses, types, conversion rates, and amounts.

Parameters

Parameter	Type	Description
date_from	date	Start date
date_to	date	End date
document_type	string	Filter by type

POST /api/v1/document-engagements/{id}/send

Request Body

{
  "recipient_email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
  "recipient_name": "John Doe",
  "subject": "Your Quote from Our Company",
  "message": "Please review the attached quote...",
  "template": "quote_notification",
  "cc": ["Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser."],
  "generate_token": true,
  "token_options": {
    "allowed_actions": ["view", "download", "sign"],
    "expires_in_days": 30
  }
}

Access Tokens

POST /api/v1/document-engagements/{id}/tokens

Returns token object with public URL and expiration.

Request Body

{
  "allowed_actions": ["view", "download", "sign"],
  "expires_in_days": 30,
  "max_uses": null,
  "recipient_email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
  "prefill_data": {
    "name": "John Doe",
    "company": "Acme Corp"
  },
  "restricted_ips": ["192.168.1.0/24"]
}

GET /api/v1/document-engagements/{id}/tokens

Returns all access tokens created for this document.

DELETE /api/v1/document-engagements/{id}/tokens/{token_id}

Revokes an access token, preventing further access.

Event Tracking

GET /api/v1/document-engagements/{id}/events

Parameters

Parameter	Type	Description
event_type	string	Filter by event type
date_from	date	Start date
date_to	date	End date
page	integer	Page number
per_page	integer	Items per page

Bulk Operations

POST /api/v1/document-engagements/bulk/send

POST /api/v1/document-engagements/bulk/status

POST /api/v1/document-engagements/bulk/export

Returns download URL with 1-hour expiration.

POST /api/v1/document-engagements/bulk/delete

Public Access Endpoints

These endpoints use token-based access. No API key required.

GET /p/{token}

Returns HTML page for viewing the document. Tracks view event.

GET /p/{token}/pdf

Downloads the PDF file. Tracks download event.

POST /p/{token}/accept

POST /p/{token}/sign

POST /p/{token}/register

GET /t/{pixel_id}.gif

Returns 1x1 transparent GIF. Tracks email open event.

Sync Management

POST /api/v1/sync/pennylane

POST /api/v1/sync/projectflow

GET /api/v1/sync/jobs

Parameters

Parameter	Type	Description
source	string	Filter: pennylane, projectflow
status	string	Filter: running, completed, failed
page	integer	Page number
per_page	integer	Items per page

GET /api/v1/sync/jobs/{id}

Returns detailed information including documents_processed, documents_created, documents_updated, and errors.

Analytics & Reporting

GET /api/v1/analytics/overview

Returns by_status, by_type, financial (total/accepted/pending amounts), and engagement (view/download/conversion rates).

Parameters

Parameter	Type	Description
period	string	today, week, month, quarter, year (default: 30d)
compare	boolean	Include comparison with previous period

GET /api/v1/analytics/timeline

Parameters

Parameter	Type	Description
date_from	date	Start date
date_to	date	End date
interval	string	day, week, month
metrics	string	Comma-separated: views, downloads, signatures

GET /api/v1/analytics/events

Returns detailed breakdown of all event types and their counts.

GET /api/v1/analytics/top

Returns top documents by views and conversions.

GET /api/v1/analytics/export

Export analytics data to CSV/Excel format.

Webhooks

GET /api/v1/webhooks

Returns registered webhooks with available events and delivery statistics.

POST /api/v1/webhooks

POST /api/v1/webhooks/{id}/test

Sends a test payload to verify webhook configuration.

GET /api/v1/webhooks/{id}/deliveries

View webhook delivery history with status, response codes, and errors.

POST /webhooks/pennylane

Security: HMAC-SHA256 signature via X-Pennylane-Signature header.

POST /webhooks/projectflow

CRM Endpoints

Multi-Channel Messaging

Error Codes

Code	HTTP	Description
AUTH_INVALID_CREDENTIALS	401	Invalid API key or credentials
AUTH_TOKEN_EXPIRED	401	JWT token expired
AUTH_INSUFFICIENT_PERMISSIONS	403	Not authorized
RESOURCE_NOT_FOUND	404	Resource not found
TOKEN_INVALID	401	Invalid/expired access token
DOCUMENT_ALREADY_SIGNED	400	Document already signed
DOCUMENT_EXPIRED	400	Access expired
VALIDATION_REQUIRED_FIELD	400	Required field missing
RATE_LIMIT_EXCEEDED	429	Too many requests
EXTERNAL_SERVICE_UNAVAILABLE	503	External service down