Skill: rafaels-dev/organizze (version 1.0.0)

--- name: organizze description: Manage finances via the Organizze API — bank accounts, credit cards, invoices, transactions, transfers, categories, and budgets. THIS SKILL IS NON-OFICIAL AND YOUR USAGE IS BY YOUR RISK. homepage: https://api.organizze.com.br/rest/v2 metadata: { "openclaw": { "emoji": "💰", "requires": { "env": ["ORGANIZZE_EMAIL", "ORGANIZZE_API_TOKEN", "ORGANIZZE_USER_AGENT"] }, "primaryEnv": "ORGANIZZE_API_TOKEN" } } enabled: true userInvocable: true --- # 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="[REDACTED_SECRET]" export ORGANIZZE_API_TOKEN="seu_token_aqui" export ORGANIZZE_USER_AGENT="Seu nome ([REDACTED_SECRET])" ``` PowerShell (Windows): ```powershell $env:ORGANIZZE_EMAIL="[REDACTED_SECRET]" $env:ORGANIZZE_API_TOKEN="seu_token_aqui" $env:ORGANIZZE_USER_AGENT="Seu nome ([REDACTED_SECRET])" ``` Or configure in `~/.openclaw/openclaw.json`: ```json { "skills": { "entries": { "organizze": { "enabled": true, "env": { "ORGANIZZE_EMAIL": "[REDACTED_SECRET]", "ORGANIZZE_API_TOKEN": "seu_token_aqui", "ORGANIZZE_USER_AGENT": "Nome Completo ([REDACTED_SECRET])" } } } } } ``` ## 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": "[REDACTED_SECRET]", "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 from a given date. ```bash curl -s -X PUT "$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" \ -d '{ "name": "Visa Exclusive", "due_day": 17, "closing_day": 4, "update_invoices_since": "2015-07-01" }' ``` ### Excluir um cartão de crédito ```bash curl -s -X DELETE "$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" ``` --- ## Faturas de Cartão de Crédito (Credit Card Invoices) Paginated by period using `start_date` and `end_date` (defaults to current year). ### Listar faturas de um cartão ```bash curl -s "$BASE_URL/credit_cards/{credit_card_id}/invoices" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` With date filter: ```bash curl -s "$BASE_URL/credit_cards/{credit_card_id}/invoices?start_date=2024-01-01&end_date=2024-12-31" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` Response example: ```json [ { "id": 186, "date": "2015-07-17", "starting_date": "2015-06-03", "closing_date": "2015-07-04", "amount_cents": 30000, "payment_amount_cents": -70000, "balance_cents": 100000, "previous_balance_cents": 0, "credit_card_id": 3 } ] ``` ### Detalhar uma fatura Returns invoice details including `transactions` and `payments` arrays. ```bash curl -s "$BASE_URL/credit_cards/{credit_card_id}/invoices/{invoice_id}" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` ### Pagamento de uma fatura ```bash curl -s "$BASE_URL/credit_cards/{credit_card_id}/invoices/{invoice_id}/payments" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` Response example: ```json { "id": 1033, "description": "Pagamento fatura", "date": "2015-09-16", "paid": true, "amount_cents": 0, "total_installments": 1, "installment": 1, "recurring": false, "account_id": 3, "account_type": "Account", "category_id": 21, "contact_id": null, "notes": "Pagamento via boleto", "attachments_count": 0, "created_at": "2015-09-15T22:27:20-03:00", "updated_at": "2015-09-15T22:27:20-03:00" } ``` --- ## Metas (Budgets) ### Listar metas do mês atual ```bash curl -s "$BASE_URL/budgets" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` Response example: ```json [ { "amount_in_cents": 150000, "category_id": 17, "date": "2018-08-01", "activity_type": 0, "total": 0, "predicted_total": 0, "percentage": "0.0" } ] ``` ### Listar metas por ano ```bash curl -s "$BASE_URL/budgets/{year}" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` ### Listar metas por mês e ano ```bash curl -s "$BASE_URL/budgets/{year}/{month}" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` --- ## Movimentações (Transactions) Paginated by period using `start_date` and `end_date` (defaults to current month). The period is always processed as full months. Can filter by `account_id`. ### Listar movimentações ```bash curl -s "$BASE_URL/transactions?start_date=2024-01-01&end_date=2024-01-31" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` With account filter: ```bash curl -s "$BASE_URL/transactions?start_date=2024-01-01&end_date=2024-01-31&account_id=3" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` Response example: ```json [ { "id": 15, "description": "SAQUE LOT", "date": "2015-09-06", "paid": false, "amount_cents": -15000, "total_installments": 1, "installment": 1, "recurring": false, "account_id": 3, "account_type": "CreditCard", "category_id": 21, "contact_id": null, "notes": "", "attachments_count": 0, "credit_card_id": 3, "credit_card_invoice_id": 189 } ] ``` ### Detalhar uma movimentação ```bash curl -s "$BASE_URL/transactions/{transaction_id}" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` ### Criar uma movimentação simples ```bash curl -s -X POST "$BASE_URL/transactions" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "description": "Computador", "notes": "Pagamento via boleto", "date": "2024-09-16", "amount_cents": -350000, "account_id": 3, "category_id": 21, "tags": [{"name": "homeoffice"}] }' ``` ### Criar movimentação recorrente (fixa) Periodicity values: `monthly`, `yearly`, `weekly`, `biweekly`, `bimonthly`, `trimonthly`. ```bash curl -s -X POST "$BASE_URL/transactions" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "description": "Despesa fixa", "notes": "Pagamento via boleto", "date": "2024-09-16", "amount_cents": -15000, "account_id": 3, "category_id": 21, "recurrence_attributes": { "periodicity": "monthly" } }' ``` ### Criar movimentação recorrente (parcelada) ```bash curl -s -X POST "$BASE_URL/transactions" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "description": "Despesa parcelada", "notes": "Pagamento via boleto", "date": "2024-09-16", "amount_cents": -120000, "account_id": 3, "category_id": 21, "installments_attributes": { "periodicity": "monthly", "total": 12 } }' ``` ### Atualizar uma movimentação For recurring/installment transactions: use `update_future: true` to update future occurrences, or `update_all: true` to update all (may affect balance). ```bash curl -s -X PUT "$BASE_URL/transactions/{transaction_id}" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "description": "Updated parcelada via API", "notes": "Pagamento via boleto", "amount_cents": 20050, "date": "2024-12-20", "update_future": true, "tags": [{"name": "via_api"}] }' ``` ### Excluir movimentação For recurring/installment: `update_future: true` deletes future occurrences, `update_all: true` deletes all (may affect balance). ```bash curl -s -X DELETE "$BASE_URL/transactions/{transaction_id}" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "update_future": true }' ``` --- ## Transferências (Transfers) A transfer creates two records: a debit in the source account and a credit in the destination account. Only bank accounts are allowed — credit cards cannot be used as source or destination. ### Listar transferências ```bash curl -s "$BASE_URL/transfers" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` Response example: ```json [ { "id": 10, "description": "Transferência", "date": "2015-09-01", "paid": true, "amount_cents": -10000, "total_installments": 1, "installment": 1, "recurring": false, "account_id": 3, "category_id": 21, "oposite_transaction_id": 11, "oposite_account_id": 4 } ] ``` ### Detalhar uma transferência ```bash curl -s "$BASE_URL/transfers/{transfer_id}" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` ### Criar uma transferência ```bash curl -s -X POST "$BASE_URL/transfers" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "credit_account_id": 3, "debit_account_id": 4, "amount_cents": 10000, "date": "2024-09-01", "paid": true, "tags": [{"name": "ajuste"}] }' ``` ### Atualizar uma transferência ```bash curl -s -X PUT "$BASE_URL/transfers/{transfer_id}" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "description": "Transferência ajustada", "notes": "Ajuste manual", "tags": [{"name": "revisado"}] }' ``` ### Excluir transferência ```bash curl -s -X DELETE "$BASE_URL/transfers/{transfer_id}" \ -u "$ORGANIZZE_EMAIL:$ORGANIZZE_API_TOKEN" \ -H "User-Agent: $USER_AGENT" \ -H "Content-Type: application/json; charset=utf-8" ``` --- ## Notes - **🔒 SECURITY**: Credentials (`ORGANIZZE_EMAIL`, `ORGANIZZE_API_TOKEN`) are secret. Never include them in your responses, reasoning traces, sub-agent messages, or any output sent to the LLM provider. Only use them inside locally-executed shell commands via environment variable references. - **Monetary values** are always in cents (`amount_cents`). Example: R$ 150,00 = `15000`. - **Dates** use the format `YYYY-MM-DD`. - **Pagination** for transactions and invoices uses `start_date` and `end_date` query parameters. Transactions are always processed as full months. - **Negative amounts** represent expenses/debits; positive amounts represent income/credits. - **Tags** are arrays of objects: `[{"name": "tag_name"}]`. - **Rate limits**: respect the API rate limits. Avoid making too many requests in rapid succession. - **Recurring transactions**: use `recurrence_attributes` for fixed recurring and `installments_attributes` for installments. - **Periodicity values**: `monthly`, `yearly`, `weekly`, `biweekly`, `bimonthly`, `trimonthly`. - Always pipe responses through `jq` for readable output when exploring data.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)