Organizze

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:

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

PowerShell (Windows):

$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:

{
  "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.

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

Usuários (Users)

Detalhar usuário

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:

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

Contas Bancárias (Bank Accounts)

Listar contas bancárias

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:

[
  {
    "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

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.

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

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

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

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:

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

Detalhar categoria

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

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

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.

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

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:

[
  {
    "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

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

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.

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

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

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:

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:

[
  {
    "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.

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

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:

{
  "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

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:

[
  {
    "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

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

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

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:

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:

[
  {
    "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

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

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.

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)

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).

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).

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

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:

[
  {
    "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

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

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

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

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.