Amocrm Api Library Laravel Package

Technical Evaluation

Architecture fit

• Official vendor SDK (amoCRM's own amocrm-api-php), MIT-licensed, distributed as a Composer package. This is the "blessed path" rather than a community wrapper — the strongest argument for adoption.
• Composed of three layers we care about: an OAuth2 client (built on league/oauth2-client), an HTTP abstraction (AmoCRM\HttpClient interface with a bundled Guzzle adapter), and a domain layer (models, collections, filters, query builders, custom-field entities, webhook/chat API helpers). That separation is what makes it viable inside Laravel — the HTTP layer is swappable, so we can route calls through Laravel's HTTP client for logging, retries, and tracing without forking.
• It is not Laravel-aware. No service provider, no config publishing, no facade, no queue integration, no Eloquent persistence. All of that is ours to build. Budget for a thin adapter package (app/AmoCRM or an internal acme/laravel-amocrm) of roughly 400–800 LOC, not for "just composer require and go."
• Stateful by design: token storage is delegated to a TokenInterface implementation, and refresh-token rotation is a first-class concern. In a Laravel app this means the integration has a persistence requirement from day one — plan an amocrm_tokens table with encrypted casts, not a .env variable.

Integration feasibility

• High. Composer-native, PSR-friendly, no exotic extensions. A mid-level Laravel developer can have a read-only authenticated call working in a day against a sandbox account.
• The realistic blockers are all account-side and process-side, not code-side: obtaining integration credentials in the client's amoCRM account (requires admin), agreeing which pipelines/entity types are in scope, and mapping custom fields (custom_fields_values are keyed by field ID, not code — IDs differ per account, so field mapping must be configuration, never hardcoded).
• Rate limits, not the library, will shape the design. amoCRM enforces roughly 7 requests/second per integration with a burst allowance and returns 429 with Retry-After. Every write path needs to go through a queued, rate-limited job. This is an architectural constraint to state up front, not a tuning detail.

Technical risk

• Refresh-token concurrency (highest severity). Refresh tokens are single-use and rotate on each refresh. Two queue workers refreshing simultaneously will invalidate each other and hard-fail the integration until an admin re-authorizes. Mitigation: serialize refresh behind a cache lock / dedicated token-refresh job; treat this as a P0 design requirement.
• Low ecosystem validation. 185 stars and effectively zero downstream dependents means we are near the leading edge of bug discovery on this library. It is official, which buys responsiveness, but it does not buy a crowd-sourced answer to "why does this filter return 204 instead of 200." Assume we own first-line debugging.
• Documentation and issue tracker are primarily Russian. Not a functional problem, but a staffing and ramp-up constraint — call it out if the team or the client's support org is English-only.
• Minor-version churn. v3 has shipped incremental breaking-ish changes in model/filter signatures. Pin to ~3.x with a committed lockfile, and treat library upgrades as scheduled work with an integration-test gate.
• Silent partial failures. Batch endpoints and entity creation can return per-item errors inside a 200/202 envelope. Our adapter must surface per-entity results rather than trusting the HTTP status, or we will "successfully" lose records.
• Release date signal. The 2026-07-01 timestamp indicates an actively maintained line, which is reassuring, but it also means recent releases are lightly field-tested. Do not adopt a brand-new minor inside a client delivery window.

Key questions

1. Which amoCRM entities and pipelines are in scope (leads, contacts, companies, tasks, notes, chats)? Scope drives 80% of the mapping effort.
2. Is this a one-way export, a one-way import, or bidirectional sync? Bidirectional requires a conflict/ownership rule and loop-prevention — price accordingly.
3. Do we need the Chat API / webhook surface (incoming messages, bot events), or only CRM entities? The Chat API has different reliability characteristics.
4. Who owns the amoCRM integration credentials, and what is the re-authorization runbook when tokens break? Name a human.
5. What is the acceptable staleness window? This determines polling vs. webhooks vs. queue depth.
6. Are we the system of record for any field we write? If both systems claim ownership of a field, we need an explicit precedence rule before the first line of sync code.

Integration Approach

Stack fit

• Laravel 10/11 + PHP 8.2+ is a clean fit; the library's constraints are unremarkable. One HTTP client and one OAuth2 dependency added to the tree.
• Recommended shape: an internal acme/laravel-amocrm package with a service provider that binds AmoCRM\AmoCRM\Client\AmoCRMApiClient (or its factory) as a singleton, publishes config/amocrm.php (subdomain, client id/secret, redirect URI, base domain for the RU/COM/KZ zones), and registers the token store.
• Implement TokenInterface against an Eloquent model with encrypted casts and an observer that records rotations. Wrap refreshAccessToken() in Cache::lock().
• Swap the Guzzle adapter for a PSR-18 client backed by Laravel's Http facade (Http::withToken(...)->asJson() via a small adapter class) so every call lands in our logs and tracing. Keep Guzzle as the fallback if the adapter proves fiddly.

Migration path

• There is nothing to migrate from unless a legacy integration exists. If one does (raw cURL scripts, Zapier, an old dotmailer-era wrapper), the migration is: run both in parallel read-only, diff outputs for 1–2 weeks, then cut writes over.
• Greenfield: no data migration, but a backfill plan. Initial entity pull should be windowed (e.g., last 90 days, or by pipeline stage) and idempotent, with checkpointed cursors so a failure resumes rather than restarts.

Compatibility

• Multi-account? The client is single-account per instance. If the client has multiple amoCRM subdomains, we need a per-account client factory keyed by account, plus per-account token rows. Decide this early — retrofitting multi-tenancy into a singleton-bound SDK is the most common refactor cost here.
• PHP 8.1 vs 8.2 vs 8.3: verify against your CI matrix before committing; the OAuth2 dependency chain is the usual culprit.
• Laravel Octane: the singleton client holds no per-request state, so it is safe, but confirm the token cache is not process-local.

Sequencing (suggested delivery slices)

1. Credentials + adapter package + token persistence with lock-safe refresh. Exit criteria: a 200 from /account in staging.
2. Read-only sync for the primary entity, queued and rate-limited, with idempotent upsert into our DB.
3. Field-mapping configuration layer (account field IDs → our columns), seeded via a one-off introspection job.
4. Write-back for the agreed subset, with per-item result handling and a dead-letter path.
5. Webhooks + queue workers for near-real-time triggers; retry/backoff policy hardened.
6. Observability, runbooks, and handover.

Slice 1–2 is the realistic "prove it" phase; slices 3–4 are where scope creeps. Do not start at 4.

Operational Impact

Maintenance

• Low-but-nonzero ongoing code maintenance; the real cost is account-side change. Client admins add custom fields, rename pipelines, and delete stages without telling anyone. Field-ID mappings will drift and sync will start silently dropping values. Build a mapping-integrity check into a scheduled command and alert on unmapped required fields.
• Own the vendor relationship: subscribe to releases, read the changelog before every minor bump, keep a locked version and an upgrade ticket per quarter.
• Budget roughly 0.1–0.2 FTE steady state for a single-account, moderate-scope integration; more if bidirectional.

Support

• Two distinct support surfaces with different owners: (a) our code and mapping layer — us; (b) amoCRM API behavior, rate-limit policy, and auth changes — the client's amoCRM account manager, not us. Establish that boundary in writing before launch, or we will absorb vendor incidents indefinitely.
• Because the library's community is small, internal documentation is the support asset. Write the runbook: how to re-authorize, how to replay a dead-lettered job, how to re-run a backfill window.

Scaling

• Throughput is bound almost entirely by the ~7 req/s integration limit, not by our infrastructure. Model capacity in entities/minute, not requests/second, and set client expectations accordingly: a 50k-record backfill is roughly 2+ hours of pure API time before retries.
• Horizontal scaling of workers does not help and actively hurts (token contention, 429 storms). Scale by adding queue depth and smarter batching, not by adding pods. One dedicated low-concurrency queue for amoCRM is the right pattern.
• Cache aggressively on read paths; entity reads that are only used for display should not hit the API per page view.

Failure modes (ranked by blast radius)

1. Token rotation race → integration dead. Requires manual admin re-authorization. Mitigate with a lock; alert on consecutive 401s.
2. Sustained 429s → queue backup → stale data. Detect via queue-age SLO, not error count; 429s are often swallowed by retry logic until the backlog is hours deep.
3. Field-ID drift → silent data loss. Worst kind: no error, just empty columns. Needs a proactive mapping audit.
4. Partial batch failures read as success. Mitigate with per-item result parsing and a dead-letter table.
5. Webhook delivery gaps. amoCRM webhooks are at-least-once and not guaranteed; the design must tolerate missed events, which means a periodic reconciliation sweep as a backstop. Do not build on webhooks alone.
6. Vendor-side breaking change in a minor release. Contained by version pinning plus an integration-test suite that runs against a sandbox account nightly.

Ramp-up

• A competent Laravel developer reaches productive velocity in ~1 week: the domain model is straightforward and the SDK's query builder is idiomatic enough. The learning curve is in amoCRM's concepts (pipelines, statuses, custom field types, the difference between leads and contacts responsibilities), which no library teaches.
• The Russian-language docs and issue tracker add a real but modest tax — plan for one team member to become the designated owner and translate the recurring gotchas into internal notes.
• Estimate: 2–3 weeks for a read-only single-entity sync by one developer; 6–10 weeks for a bidirectional multi-entity integration with webhooks, properly hardened. The library saves maybe 2–3 weeks of OAuth2 and model boilerplate — meaningful, but it does not change the order of magnitude, and it does not touch the parts (mapping, rate limiting, idempotency, reconciliation) where these projects actually fail.