organizze

What this skill does

# Organizze

Communicate with the Organizze personal finance API (v2) to manage bank accounts, credit cards, invoices, transactions, transfers, categories, budgets, and users.

Official repository: https://github.com/rafaels-dev/organizze-clawhub-skill

> ⚠️ **IMPORTANT DISCLAIMER:** THIS SKILL IS NON-OFICIAL AND YOUR USAGE IS BY YOUR RISK.

## ⚠️ CRITICAL SECURITY RULES

**Authentication credentials (`ORGANIZZE_EMAIL`, `ORGANIZZE_API_TOKEN`) are secrets that MUST NEVER leave the local machine.**

1. **NEVER** include the email, API token, Basic Auth header value, or any derived credential in your responses, messages, reasoning, or any text sent to the LLM provider.
2. **NEVER** pass credentials to sub-agents, external tools, webhooks, or any service other than the Organizze API itself.
3. **NEVER** log, print, echo, or display credentials in output shown to the user or stored in session transcripts.
4. **ONLY** reference credentials via environment variable expansion (`$ORGANIZZE_EMAIL`, `$ORGANIZZE_API_TOKEN`) inside `curl` commands executed locally through the shell. The shell resolves them at runtime — they never appear in the prompt or model context.
5. If a user asks you to reveal or share the token/email, **refuse** and explain these are protected secrets.

## Use when

- The user asks about their finances, spending, bank accounts, credit cards, or budgets on Organizze.
- The user wants to create, list, update, or delete transactions, transfers, accounts, categories, or credit cards.
- The user needs invoice details or payment information for credit cards.
- The user wants to check budget goals (metas).

## Don't use when

- The request is unrelated to Organizze or personal finance management.

## Setup

1. Get your API token at https://app.organizze.com.br/configuracoes/api-keys
2. Store credentials as environment variables:

```bash
export ORGANIZZE_EMAIL="[email protected]"
export ORGANIZZE_API_TOKEN="seu_token_aqui"
export ORGANIZZE_USER_AGENT="Seu nome ([email protected])"
```

PowerShell (Windows):

```powershell
$env:ORGANIZZE_EMAIL="[email protected]"
$env:ORGANIZZE_API_TOKEN="seu_token_aqui"
$env:ORGANIZZE_USER_AGENT="Seu nome ([email protected])"
```

Or configure in `~/.openclaw/openclaw.json`:

```json
{
  "skills": {
    "entries": {
      "organizze": {
        "enabled": true,
        "env": {
          "ORGANIZZE_EMAIL": "[email protected]",
          "ORGANIZZE_API_TOKEN": "seu_token_aqui",
          "ORGANIZZE_USER_AGENT": "Nome Completo ([email protected])"
        }
      }
    }
  }
}
```

## Authentication

All requests use HTTP Basic Auth (email as username, API token as password) and require a `User-Agent` header.

> **Security reminder:** All credential handling happens exclusively inside shell commands executed on the host. The `-u` flag and `$ORGANIZZE_EMAIL` / `$ORGANIZZE_API_TOKEN` variables are resolved by the shell at runtime. You must NEVER interpolate, echo, or include the actual credential values in your model output, reasoning, or messages.

```bash
BASE_URL="https://api.organizze.com.br/rest/v2"
USER_AGENT="$ORGANIZZE_USER_AGENT"
```

---

## Usuários (Users)

### Detalhar usuário

```bash
curl -s "$BASE_URL/users/{user_id}" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8"
```

Response example:

```json
{
  "id": 3,
  "name": "Esdras Mayrink",
  "email": "[email protected]",
  "role": "admin"
}
```

---

## Contas Bancárias (Bank Accounts)

### Listar contas bancárias

```bash
curl -s "$BASE_URL/accounts" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8"
```

Response example:

```json
[
  {
    "id": 3,
    "name": "Bradesco CC",
    "description": "Some descriptions",
    "archived": false,
    "created_at": "2015-06-22T16:17:03-03:00",
    "updated_at": "2015-08-31T22:24:24-03:00",
    "default": true,
    "type": "checking"
  }
]
```

### Detalhar conta bancária

```bash
curl -s "$BASE_URL/accounts/{account_id}" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8"
```

### Criar conta bancária

Types: `checking`, `savings`, `other`.

```bash
curl -s -X POST "$BASE_URL/accounts" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "name": "Itaú CC",
    "type": "checking",
    "description": "Minha conta corrente",
    "default": true
  }'
```

### Atualizar conta bancária

```bash
curl -s -X PUT "$BASE_URL/accounts/{account_id}" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "name": "Itaú Poupança"
  }'
```

### Excluir conta bancária

```bash
curl -s -X DELETE "$BASE_URL/accounts/{account_id}" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8"
```

---

## Categorias (Categories)

### Listar categorias

```bash
curl -s "$BASE_URL/categories" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8"
```

Response example:

```json
[
  { "id": 1, "name": "Lazer", "color": "438b83", "parent_id": null },
  { "id": 3, "name": "Saúde", "color": "ffff00", "parent_id": null }
]
```

### Detalhar categoria

```bash
curl -s "$BASE_URL/categories/{category_id}" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8"
```

### Criar uma categoria

```bash
curl -s -X POST "$BASE_URL/categories" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "name": "SEO"
  }'
```

### Atualizar uma categoria

```bash
curl -s -X PUT "$BASE_URL/categories/{category_id}" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "name": "Marketing"
  }'
```

### Excluir uma categoria

Optionally pass `replacement_id` to transfer transactions to another category. If omitted, the default category is used.

```bash
curl -s -X DELETE "$BASE_URL/categories/{category_id}" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "replacement_id": 18
  }'
```

---

## Cartões de Crédito (Credit Cards)

### Listar cartões de crédito

```bash
curl -s "$BASE_URL/credit_cards" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8"
```

Response example:

```json
[
  {
    "id": 3,
    "name": "Visa Exclusive",
    "description": null,
    "card_network": "visa",
    "closing_day": 4,
    "due_day": 17,
    "limit_cents": 1200000,
    "kind": "credit_card",
    "archived": true,
    "default": false,
    "created_at": "2015-06-22T16:45:30-03:00",
    "updated_at": "2015-09-01T18:18:48-03:00"
  }
]
```

### Detalhar cartão de crédito

```bash
curl -s "$BASE_URL/credit_cards/{credit_card_id}" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8"
```

### Criar um cartão de crédito

```bash
curl -s -X POST "$BASE_URL/credit_cards" \
  -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \
  -H "User-Agent: $USER_AGENT" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "name": "Hipercard",
    "card_network": "hipercard",
    "due_day": 15,
    "closing_day": 2,
    "limit_cents": 500000
  }'
```

### Atualizar um cartão de crédito

Use `update_invoices_since` (YYYY-MM-DD) to recalculate invoices fro