Client libraries
Calco ships an official client for every major backend language. Each one is a thin, dependency-light wrapper over the HTTP API: it handles multipart uploads, JSON data injection, authentication headers, and error mapping so you work with native objects instead of raw requests.
These connectors aren't published to npm, PyPI, Composer, NuGet, RubyGems, or a Go module proxy yet — for now they're do-it-yourself. Each is a small, dependency-light source file (or two) that you copy directly into your project. Because they lean on each language's standard library, vendoring one is a one-step affair.
All clients cover the same surface area:
convert— render a local.xlsx/.docxfile to PDF, HTML, or another format in one call, without storing anything.scaffold— extract the{d.*}placeholder map from a template.- Template management — list, create, update, delete, and version stored templates.
render/download— render a stored template version with JSON data.batchRender— render many records into a single ZIP archive.- By-hash workflow — address any template version by its content hash and render or download straight from it.
Pick your language
The Connector source column lists the file(s) you copy into your project.
| Language | Connector source | Runtime | Dependencies |
|---|---|---|---|
| Node.js / TypeScript | index.ts | Node 18+ | none (native fetch) |
| Python | calco/ package | Python 3.8+ | none (stdlib) |
| PHP | Client.php, CalcoException.php | PHP 8.1+ | none (cURL ext) |
| Go | client.go | Go 1.18+ | none (stdlib) |
| Java | CalcoClient.java | Java 17+ | none (java.net.http) |
| C# / .NET | CalcoClient.cs | .NET 8.0 | none |
| Ruby | calco.rb | Ruby 2.7+ | none (stdlib) |
Authentication
Every client accepts an optional API key, sent as
Authorization: Bearer <key>. Generate one under Account → API Keys
(dc_live_…) and pass it when you construct the client. Calls scoped to a
single organization resolve that org from the key, so you never pass an org id
to a method.
The base URL points at your Calco deployment — http://localhost:8080 in local
development, or your hosted URL in production. The examples below use
placeholders; swap in your own host and key.
A common flow
The typical integration uploads a template once, then renders it many times with different data:
- Upload the
.xlsx/.docxonce withcreateTemplate(or manage it in the web UI) and note itsidor contenthash. - Render per request with
renderTemplate/renderByHash, passing the row's JSON data. - Stream the returned bytes back to your user as a download.
Each language page walks through this end to end, including framework integration (Express/NestJS/Next.js, Django/FastAPI, Laravel/Symfony, Gin/Echo/ Fiber, Spring Boot, ASP.NET Core, Rails) and error handling.