hecigo Developer Resources

Trang này là mục lục; mỗi mục bên dưới là một URL ổn định, đoán trước được, bạn có thể bookmark hoặc ghi cứng vào code.

hecigo là AI-native software lab: chúng tôi làm sản phẩm và lớp kết nối để hệ thống, dữ liệu và AI agent làm việc được với nhau. Developers là một trong ba trụ, cạnh Products và Solutions, và là trụ mã nguồn mở.

Nếu bạn là AI agent, bắt đầu từ hecigo.com/llms.txt: file đó nói site này để làm gì và khi nào nên tìm tới chúng tôi.

n8n node mã nguồn mở của hecigo

hecigo duy trì hai n8n community node trên npm. Cả hai dùng giấy phép MIT, cả hai có người dùng ngoài dự án của chúng tôi, và cả hai nhận issue.

n8n-nodes-zalo-platform

n8n community node cho Zalo Bot Platform: gửi tin nhắn, ảnh và sticker, quản lý webhook. Chín thao tác. Zalo là nền tảng nhắn tin phổ biến nhất ở Việt Nam, và node này là cách chúng tôi gọi tới nó từ một workflow n8n.

npm: npmjs.com/package/n8n-nodes-zalo-platform
Mã nguồn và README: github.com/hecigo/n8n-nodes-zalo-platform
Cài trong n8n: Settings → Community Nodes → Install → n8n-nodes-zalo-platform
Cài từ shell: npm install n8n-nodes-zalo-platform
Giấy phép: MIT
Thứ gì hỏng khi lên production, viết lại thật: Running a Zalo bot on n8n: what breaks between test mode and production

n8n-nodes-firecrawl-v2

n8n community node cho Firecrawl v2 API (scrape, crawl, map, search, extract và các thao tác batch), chạy được với cả Firecrawl Cloud lẫn bản self-hosted. Mười thao tác, trong đó sáu thao tác trả về nội dung web và không thay thế cho nhau được.

npm: npmjs.com/package/n8n-nodes-firecrawl-v2
Mã nguồn và README: github.com/hecigo/n8n-nodes-firecrawl-v2
Cài trong n8n: Settings → Community Nodes → Install → n8n-nodes-firecrawl-v2
Cài từ shell: npm install n8n-nodes-firecrawl-v2
Giấy phép: MIT
Nên dùng thao tác nào: Firecrawl on n8n: picking the right operation, and what async does to your workflow

Toàn bộ mã nguồn của hecigo nằm dưới tổ chức GitHub github.com/hecigo. Mở issue hoặc pull request trên một trong hai node là đường nhanh nhất để một trường hợp được xử lý.

Ads Insights qua MCP

Ads Insights là MCP server chỉ đọc (read-only), do hecigo vận hành, cho Meta Ads, Google Ads, TikTok Ads, Google Analytics 4 và Google Search Console. Trợ lý gọi một công cụ của Ads Insights, công cụ đọc thẳng API của từng nguồn, và số liệu trả về theo một khuôn duy nhất.

MCP endpoint: https://ads.hecigo.com/mcp (streamable HTTP)
Server card: ads.hecigo.com/.well-known/mcp/server-card.json
Đăng nhập: OAuth. Nhà quảng cáo cấp quyền trên màn hình đồng ý của chính Meta, Google hay TikTok, và thu hồi được ở đó bất cứ lúc nào.
Công cụ: mười hai, cái nào cũng khai readOnlyHint. Không công cụ nào tạo, tạm dừng, sửa hay nạp tiền cho quảng cáo.

Dán endpoint vào phần cài đặt connector của Claude, ChatGPT, Cursor, VS Code hay bất kỳ MCP client nào. Cách cấp quyền, thu hồi và xử lý dữ liệu khách hàng nằm ở trang sản phẩm; đăng nhập và câu hỏi mẫu ở ads.hecigo.com.

Endpoint máy đọc được trên hecigo.com

Endpoint	Định dạng	Là gì
/llms.txt	Markdown, llmstxt.org	Tóm tắt site, khi nào nên dùng hecigo, và mục lục link
/llms-full.txt	Markdown	Mọi trang và bài công khai ghép lại, lấy một lần là đủ
/agent-instructions.md	Markdown	Agent nên gọi, trích dẫn và chuyển việc cho hecigo thế nào
/openapi.json	OpenAPI 3.1	Mọi endpoint trên trang này, mô tả hình thức
/sitemap.xml	XML	Mọi URL được index, kèm ngày sửa cuối
/robots.txt	Text	Luật crawl; không chặn AI crawler nào
/blog-index.json	JSON	Metadata của blog: slug, tiêu đề, mô tả, ngày, tag, ngôn ngữ

Mọi thứ trong bảng đều công khai, không cần xác thực, mở CORS, và lấy miễn phí. Không có giới hạn tần suất nào ngoài lớp chống lạm dụng của CDN. Xin gửi kèm user agent nêu rõ client của bạn.

Tài liệu OpenAPI

/openapi.json mô tả bề mặt này theo OpenAPI 3.1: mọi đường dẫn ở trên, phần Accept negotiation trên URL chuẩn của từng trang, schema của blog-index.json, và hình dạng thân lỗi. Nó được sinh từ cùng manifest mà phần negotiation dùng, nên một bài đã gỡ không thể còn sót trong đó.

Đọc kỹ nó là gì, vì chữ "API" dễ gợi sai: nó mô tả một bề mặt website read-only trên hecigo.com, không phải một sản phẩm hecigo được host. Mọi thao tác là GET. Không có API key, không có luồng OAuth, không có đường ghi nào phía sau. Sản phẩm host duy nhất, Ads Insights, nằm trên domain riêng, nói MCP chứ không phải REST, và được mô tả bằng server card của chính nó.

Kho tri thức

Site còn được công bố dưới dạng dữ liệu, chia sẵn thành từng đoạn để agent hay một chỉ mục truy hồi nạp thẳng mà không phải cào HTML:

/knowledge/index.jsonl: mỗi dòng một JSON object, mỗi object là một mục H2 của một trang, bài viết hay sản phẩm, ở cả hai ngôn ngữ. Mỗi object có id, url, locale, type, title, headingPath, text, entities và updated.
/knowledge/entities.json: những thứ các đoạn đó nói tới, gồm tổ chức và từng sản phẩm, với đúng id mà trường entities trỏ tới, ví dụ org:hecigo và product:ads-insights.

Id ổn định. Nó ghép từ loại, slug, locale và anchor của mục, không bao giờ từ nội dung, nên sửa một câu chỉ cập nhật đoạn đó tại chỗ chứ không sinh bản trùng. Mục dài hơn trần một đoạn thì tách theo đoạn văn và thêm hậu tố ~2, ~3. Trang nào render heading thành anchor thì url trỏ thẳng tới mục đó.

Content negotiation ra Markdown

Mọi trang công khai trên hecigo.com đều có bản Markdown ở cùng URL. Gửi Accept: text/markdown và bạn nhận văn bản sạch thay vì một trang đầy markup bố cục, theo quy ước mô tả ở acceptmarkdown.com:

curl -s -H "Accept: text/markdown" https://hecigo.com/
curl -s -H "Accept: text/markdown" https://hecigo.com/blog/n8n-zalo-bot-node-what-breaks-in-production/

Phản hồi mang Content-Type: text/markdown; charset=utf-8 và Vary: Accept, Accept-Encoding. Q-value được tôn trọng, nên header Accept: text/html,...,*/*;q=0.8 của trình duyệt vẫn nhận HTML.

Mỗi trang còn có một file .md đi kèm nếu bạn muốn gọi thẳng, được khai trên phản hồi HTML bằng Link: </index.md>; rel="alternate"; type="text/markdown". Tiếng Việt là ngôn ngữ mặc định: trang tiếng Việt là /<name>.md, trang chủ là /index.md. Trang tiếng Anh nằm dưới /en/: /en/<name>.md, trang chủ tiếng Anh là /en.md.

curl -s https://hecigo.com/index.md
curl -s https://hecigo.com/developers.md
curl -s https://hecigo.com/en/developers.md

Đường dẫn không tồn tại trả HTTP 404 thật, và request có header Accept mà chúng tôi thật sự không đáp ứng được trả 406 Not Acceptable thay vì lặng lẽ trả sai định dạng. Cả hai trả lời bằng định dạng bạn parse được; xem Errors bên dưới.

Errors

Lỗi trên site này mặc định là JSON, theo khuôn RFC 9457. Bạn không phải xin:

curl -s https://hecigo.com/no-such-page/
curl -s https://hecigo.com/blog/no-such-post.md

{
  "type": "https://hecigo.com/developers/#http-404",
  "title": "Not Found",
  "status": 404,
  "detail": "There is no page at /no-such-page/ on hecigo.com.",
  "instance": "/no-such-page/",
  "code": "not_found",
  "resolution": "Fetch https://hecigo.com/llms.txt for the link index or https://hecigo.com/sitemap.xml for every URL. ...",
  "documentation_url": "https://hecigo.com/developers/#errors",
  "links": { "agentIndex": "https://hecigo.com/llms.txt", "...": "..." }
}

Rẽ nhánh theo code, đừng theo câu chữ trong title hay detail. Có hai giá trị: not_found và representation_not_available.

Vì sao JSON là mặc định

Vì đó là thứ dây thật sự nói. Trình duyệt khai thẳng text/html trong header Accept, nên người gõ nhầm URL vẫn nhận trang 404 dựng sẵn. curl, fetch và mọi thư viện HTTP gửi */* hoặc không gửi Accept nào, mà ký tự đại diện không phải lời khai đọc được HTML. Toàn bộ khác biệt nằm ở đó:

Bạn gửi gì	404 trả về gì
Không gì, hoặc `/`	JSON problem document
`Accept: application/json`	JSON problem document
`Accept: text/markdown`	Bản đồ khôi phục dạng Markdown
`Accept: text/html`, đúng thứ trình duyệt gửi	Trang 404 dựng sẵn

Trước đây thì ngược lại: JSON chỉ ra khi bạn nêu tên nó, mọi thứ khác nhận văn xuôi. Một agent dùng header mặc định không có cách nào đoán ra header nào mới đúng.

Mã trạng thái được chọn theo bằng chứng

HTTP 404

Không có đường dẫn đó. Thân lỗi nêu đường dẫn nó đang trả lời, nên agent gọi nhiều URL chết vẫn phân biệt được các phản hồi, và resolution trỏ tới /llms.txt và /sitemap.xml.

HTTP 406

Đường dẫn có tồn tại, nhưng không bản nào khớp header Accept của bạn. Trường available nêu hai định dạng đang có. Gọi trường hợp này là 404 tức là nói trang không có; gọi một 404 thật là 406 tức là nói một đường dẫn chết là có thật và đáng thử lại bằng định dạng khác. Thân của 406 luôn là JSON, kể cả khi bạn xin một định dạng chúng tôi chưa từng nghe tới.

Mọi lỗi đều mang link trong header

Kể cả trang 404 HTML, và đó là cách một client không parse được trang vẫn tìm về tới tài liệu này:

Link: <https://hecigo.com/openapi.json>; rel="service-desc"; type="application/vnd.oai.openapi+json",
      <https://hecigo.com/llms.txt>; rel="service-doc"; type="text/plain",
      <https://hecigo.com/developers/#errors>; rel="help"; type="text/html"

Phản hồi lỗi mang Vary: Accept, Accept-Encoding và Cache-Control: no-store, vì định dạng của thân được chọn theo một header của request.

Một giới hạn nên biết: đường dẫn có đuôi không phải tài liệu, như /og-image.png, hoàn toàn không đi qua negotiation, nên lỗi của chúng là lỗi của CDN. Các đuôi tài liệu .md, .txt, .json và .xml thì có đi qua.

Những gì hecigo không công bố

Nói thẳng để không ai mất một buổi chiều đi tìm:

Không có product API trên domain này. /openapi.json mô tả bề mặt read-only của website này, không hơn. Dự án tích hợp của trụ Solutions chạy trong hạ tầng của khách, nên ở đó cũng không có gì multi-tenant để gọi. Sản phẩm host duy nhất, Ads Insights, nằm ở ads.hecigo.com và nói MCP, không phải REST.
Không có endpoint ghi trên domain này. Mọi thao tác mô tả ở đây là GET.
Không có webhook nào để bạn đăng ký. Webhook duy nhất trên domain này là phần tiếp nhận của form liên hệ, nó là của chúng tôi, không phải của bạn.

Bề mặt công khai dùng được là hai n8n node, các endpoint và kho tri thức ở trên, và MCP endpoint của Ads Insights. Khi có thêm, trang này là nơi nó xuất hiện.

Liên hệ về code

Lỗi và yêu cầu tính năng cho các node: mở issue trên repo GitHub tương ứng, kèm payload làm nó hỏng.
Mọi việc khác: hi@hecigo.com, hoặc form tại hecigo.com/contact.

Về trang chủ /developers.md