# SKILL.md — Contabeleza API Skill

> **For AI code CLIs.** Copy this file to your project's root or agent's context to bootstrap work on the Contabeleza API.

---

## What this is

You are working with the **Contabeleza API** — a Brazilian financial / fiscal platform for MEIs (Microempreendedores Individuais) and professionals. The full API documentation is served as a browsable site with OpenAPI spec, model reference, and developer guides.

## Environment Variables

Set these to authenticate with the Contabeleza API docs site:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `API_CONTABELEZA_CLIENT_ID` | Yes | — | Cloudflare Access Client ID |
| `API_CONTABELEZA_CLIENT_SECRET` | Yes | — | Cloudflare Access Client Secret |
| `API_CONTABELEZA_URL` | No | `api-docs.contabeleza.com.br` | Base URL for the API docs site |

These are **Cloudflare Access Service Tokens** used to bypass ZeroTrust authentication for programmatic access.

## How to use this skill

1. **Fetch the AI guide** to get the full set of instructions:
   ```
   https://${API_CONTABELEZA_URL:-api-docs.contabeleza.com.br}/ai.md
   ```
   This is the **single source of truth** for an AI agent. It tells you which endpoints to call, what the request/response shapes look like, and what the business context is.

2. **Fetch the compact index** (`/AI_INDEX.md`) before exploring the full spec. At ~270 lines it covers every endpoint, model, and error code — a fraction of the full OpenAPI spec (~1700 lines). Use it to identify which endpoints you need, then fetch their full schemas from `/openapi.json`.

3. **Read the AI guide carefully** before writing any code. It walks you through the docs site, the API conventions (JSON:API, auth, headers), and the gotchas.

4. **Explore the docs site** as needed:
   - `/AI_INDEX.md` — compact index (~270 lines, read this first)
   - `/openapi.json` or `/openapi.yaml` — the full spec
   - `/docs` — interactive Swagger UI
   - `/models` — every JSON:API type
   - `/guides/tech` — developer guides (auth, invoice emission, MEI diagnosis, DAS, etc.)
   - `/guides/geral` — Portuguese guides for business context

5. **Test against the mocks** — every documented path returns an example response. You can hit the deployed site's mock endpoints or run the docs site locally.

## Quick reference

| What | Where |
|---|---|
| AI guide (read this first) | `/ai.md` |
| Compact index (~270 lines, read before spec) | `/AI_INDEX.md` |
| OpenAPI spec | `/openapi.json` |
| Swagger UI | `/docs` |
| Models | `/models` |
| Tech guides (EN) | `/guides/tech` |
| General guides (PT) | `/guides/geral` |
| Internal endpoints ★ | `/guides/tech/internal-endpoints` |
| Endpoint browser | `/` |
| Changelog | `/changelog` |

**Base URL (production):** `https://${API_CONTABELEZA_URL:-api-docs.contabeleza.com.br}`
**Base URL (local dev):** `http://localhost:4321`

## Conventions

- All responses follow **JSON:API v1.1** (`Content-Type: application/vnd.api+json`).
- Auth: `Authorization: Bearer <jwt>` from `POST /sessions`.
- Business context: `ilm-business: <business-id>` header.
- Attribute names are kebab-case. `id` is always a string.
- **Cloudflare Access**: Include `CF-Access-Client-Id` and `CF-Access-Client-Secret` headers when accessing the docs site from external applications.

## Your first step

Read the AI guide now:

```bash
curl -s \
  -H "CF-Access-Client-Id: $API_CONTABELEZA_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $API_CONTABELEZA_CLIENT_SECRET" \
  https://${API_CONTABELEZA_URL:-api-docs.contabeleza.com.br}/ai.md
```

It has the full onboarding path. Don't skip steps.

## Troubleshooting

### Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `403 Forbidden` | Missing or invalid Cloudflare Access headers | Ensure `CF-Access-Client-Id` and `CF-Access-Client-Secret` are set correctly |
| `401 Unauthorized` | Service token expired or revoked | Generate a new Service Token in Cloudflare Zero Trust dashboard |
| `Connection refused` | Wrong `API_CONTABELEZA_URL` | Check the URL, default is `api-docs.contabeleza.com.br` |
| `SSL certificate problem` | Network or proxy issue | Verify network connectivity and SSL certificates |

### Verify Your Setup

```bash
# Test authentication
curl -s -o /dev/null -w "%{http_code}" \
  -H "CF-Access-Client-Id: $API_CONTABELEZA_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $API_CONTABELEZA_CLIENT_SECRET" \
  https://${API_CONTABELEZA_URL:-api-docs.contabeleza.com.br}/ai.md

# Expected output: 200
```