Organizze API

Data Format

The API exclusively supports JSON. Even if you do not explicitly set the Content-Type: application/json; charset=utf-8 header, all responses will be returned in JSON with utf-8 encoding.

Pagination

Transactions (movimentações) and credit card invoices (faturas de cartão de crédito) are paginated by period. Use the start_date and end_date parameters to define the range.

Parameters:

• start_date: Format YYYY-MM-DD (e.g., 2015-09-01)
• end_date: Format YYYY-MM-DD (e.g., 2015-09-30)

Default Behavior:

• If no period is provided, transactions default to the current month.
• If no period is provided, credit card invoices default to the current year.

All requests to the Organizze API require HTTP Basic authentication.

Credentials:

• Username: Your Organizze account email.
• Password: Your access token. You can generate this at https://app.organizze.com.br/configuracoes/api-keys.

Requirements:

• HTTPS Only: The API does not accept plain HTTP requests. The base URL is https://api.organizze.com.br/rest/v2.
• User-Agent Header: You must include a User-Agent header identifying your application and a contact email. Failure to provide this header will result in a 400 Bad Request error.

Example User-Agent headers:

• User-Agent: Esdras (esdras@organizze.com.br)
• User-Agent: Alex (alex@gmail.com)

The API uses standard HTTP status codes to indicate success or failure. Common error scenarios include:

• 401 Unauthorized: Occurs when the email or password is incorrect, or the user is not authenticated.
• 400 Bad Request: Occurs if the User-Agent header is missing.
• 422 Unprocessable Entity: Occurs when attempting to create or update a record with invalid data (e.g., a bank account missing a required name).

Example 422 Error Body:

{
    "id": null,
    "name": null,
    "description": "Minha conta corrente",
    "archived": false,
    "created_at": null,
    "updated_at": null,
    "default": false,
    "errors": {
        "name": [
            "não pode estar em branco"
        ]
    },
    "type": "checking"
}

{
    "error": "Não autorizado"
}

Create a new bank account by providing the name, type, description, and whether it is the default account.

Endpoint: POST /accounts

Request Body Example:

{
    "name": "Itaú CC",
    "type": "checking",
    "description": "Minha conta corrente",
    "default": true
}

When deleting a category, you can specify a replacement_id to ensure existing transactions are moved to a new category instead of being orphaned or moved to the default.

Endpoint: DELETE /categories/{id}

Request Body Example:

{
    "replacement_id": 18
}

Remove a credit card from the account.

Endpoint: DELETE /credit_cards/{id}

DELETE /credit_cards/3

Delete a transaction.

For recurring or installment transactions, use these attributes to define the scope:

• update_future: true: Deletes the transaction and all future occurrences.
• update_all: true: Deletes all occurrences, including previous ones. Warning: This may change the account balance if previous transactions were already marked as paid/received.

```json
{
    "update_future": true
}

DELETE /transactions/101

Manage transaction categories (categories) used for organization.

Deleting a Category: When deleting a category, you can provide a replacement_id in the request body. All transactions associated with the deleted category will be transferred to the replacement category. If no replacement is provided, the system's default category will be used.

Update the details of an existing transfer using its ID.

PUT /transfers/10

{
    "description": "Transferência ajustada",
    "notes": "Ajuste manual",
    "tags": [{"name": "revisado"}]
}

Retrieve detailed information for a specific invoice, including its associated transactions and payments.

Endpoint: GET /credit_cards/{id}/invoices/{invoice_id}

Response includes:

• transactions: A list of transactions that make up the invoice.
• payments: A list of payments applied to this invoice.

GET /credit_cards/3/invoices/186

Retrieve information about a specific user, including their ID, name, email, and role.

Endpoint: GET /users/{id}

GET /users/3