⚡ AmoDocsEngine

Shared-hosting friendly amoCRM document generation engine for DOCX orders, acts, and custom templates.

🇬🇧 English docs · 🇷🇺 Документация · 🔌 API · 🛡️ Security · 🤝 Contributing · 📜 Code of Conduct

---

✨ What It Does

AmoDocsEngine connects a small browser UI to amoCRM and generates .docx documents from Word templates. It keeps the deployment simple enough for shared hosting while still separating OAuth, security, field mapping, quote calculation, template rendering, cache, notes, and logging into focused PHP services.

Area	What is included
🔐 Security	Server-issued generate_token for browser flow, optional HMAC mode for trusted server clients
🧾 Documents	PhpWord template rendering for orders, acts, and config-driven custom templates
📊 Totals	Backend-only quote calculation through POST /api/quote.php
🔗 amoCRM	OAuth token refresh, lead/contact loading, document note replacement
🗂️ Runtime	Prefill cache, generated documents, JSON logs, token storage

🚀 Quick Start

composer install
Copy-Item config/config.example.php config/config.php
.\vendor\bin\phpunit

Then fill config/config.php, run the amoCRM OAuth flow through oauth.php?code=..., and open:

public/ui.html?lead_id=<amoCRM_LEAD_ID>

🧭 Docs Map

Topic	English	Русский
Start and deploy	Getting started	Запуск
Configuration	Configuration	Конфигурация
API contracts	API	API
Word templates	Templates	Шаблоны
Logs and migration	Operations	Эксплуатация
Development	Development	Разработка

🏗️ Request Flow

sequenceDiagram
    participant UI as Browser UI
    participant Prefill as GET /api/prefill.php
    participant Quote as POST /api/quote.php
    participant Generate as POST /api/generate.php
    participant Amo as amoCRM API
    participant Docx as DOCX storage

    UI->>Prefill: lead_id
    Prefill-->>UI: cached form + generate_token
    UI->>Quote: products + discount
    Quote-->>UI: rows + totals + total_words
    UI->>Generate: lead_id + template + products + generate_token
    Generate->>Amo: fetch lead/contact
    Generate->>Docx: render PhpWord template
    Generate->>Amo: replace document note
    Generate-->>UI: generated document URL

Loading

Reusable diagram sources:

• Architecture overview
• Workflow overview

🧱 Module Boundaries

flowchart LR
    API["api/<br/>HTTP entrypoints"]
    Amo["src/AmoCrm/<br/>client, notes, fields"]
    Docs["src/Documents/<br/>quotes, registry, generation"]
    Security["src/Security/<br/>tokens, authentication"]
    Storage["src/Storage/<br/>prefill cache"]
    Support["src/Support/<br/>formatting, logging"]

    API --> Amo
    API --> Docs
    API --> Security
    API --> Storage
    API --> Support

Loading

🧩 Main Endpoints

Endpoint	Purpose
GET /api/prefill.php?lead_id=	Restore cached form data and issue generate_token
POST /api/quote.php	Calculate rows, totals, and amount in words
POST /api/generate.php	Validate request, fetch amoCRM data, generate DOCX, update note

🧪 Verification

composer install
.\vendor\bin\phpunit

Current suite covers URL routing, quote calculations, amoCRM client behavior, field ID mapping, template registry, security token validation, cache, notes, and logging.

🏷️ Repository Setup Tips

• Description: amoCRM document generation engine with OAuth, DOCX templates, secure browser flow, quote preview, and shared-hosting deployment.
• Topics: php, amocrm, docx, phpword, crm, document-generation.
• Social preview: upload docs/assets/github-social-preview.png in GitHub repository settings.
• Community: keep Security, Contributing, Code of Conduct, and GitHub issue templates visible.

---

Made for pragmatic CRM document automation: small surface, clear modules, practical docs.