A API do Organizze possibilita que aplicações se comuniquem com a sua conta no sistema. Este documento explica como o Organizze funciona, quais são os objetos envolvidos e como esta comunicação pode ser feita. Esta é a primeira versão da API, ainda em versão beta, algumas mudanças e melhorias serão implementadas futuramente.
A autenticação de todas request é via Http Basic com o Username e Password descritos abaixo:
Todas as requisições são criptografadas, o Organizze não aceita requisições feitas com HTTP simples, apenas HTTPS. A URL base da API é https://api.organizze.com.br/rest/v2
Todas as requisições à API do Organizze devem ser acompanhadas do header User-Agent, use este header para informar qual a sua aplicação e qual o seu email para contato. Veja alguns exemplos de como você pode se identificar usando o header User-Agent:
User-Agent: Esdras (esdras@organizze.com.br)
User-Agent: Alex (alex@gmail.com)Se você não informar este header, você receberá 400 Bad Request como resposta.
A API só suporta JSON, nós não vamos dar suporte a outro formato. Mesmo que você não utilize o header Content-Type: application/json; charset=utf-8 a resposta será em JSON e com charset utf-8.
Movimentações e faturas de cartão de crédito são paginadas por período. Para informar qual período utilize os parâmetros &start_date=2015-09-01&end_date=2015-09-30. Se você não informar o período o Organizze vai limitar os registros para o período atual: Mês atual para movimentações e Ano atual para faturas de cartão de crédito.
Abaixo estão listados alguns exemplos de erros que podem acontecer e as suas respectivas respostas:
Autorização negada: O email ou senha estão incorretos ou o usuário não está autenticado, o status HTTP é 401 e o body é:
{
"error": "Não autorizado"
}Uma tentativa de criar ou atualizar um registro inválido. No exemplo abaixo o usuário está tentando criar uma conta bancária sem nome, o status HTTP é 422 e o 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"
}GET /users/3
{
"id": 3,
"name": "Esdras Mayrink",
"email": "falecom@email.com.br",
"role": "admin"
}GET /accounts
[
{
"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"
},
{
"id": 4,
"name": "Caixa Poupança",
"description": "",
"archived": false,
"created_at": "2015-08-20T17:59:06-03:00",
"updated_at": "2015-08-31T18:46:23-03:00",
"default": false,
"type": "savings"
},
{
"id": 5,
"name": "Carteira",
"description": null,
"archived": false,
"created_at": "2015-08-31T18:19:01-03:00",
"updated_at": "2015-08-31T18:19:01-03:00",
"default": false,
"type": "other"
}
]GET /accounts/3
{
"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"
}POST /accounts
{
"name": "Itaú CC",
"type": "checking",
"description": "Minha conta corrente",
"default": true
}{
"id": 18,
"name": "Itaú CC",
"description": "Minha conta corrente",
"archived": false,
"created_at": "2015-09-15T21:04:30-03:00",
"updated_at": "2015-09-15T21:04:30-03:00",
"default": true,
"type": "checking"
}PUT /accounts/18
{
"name": "Itaú Poupança",
}{
"id": 18,
"name": "Itaú Poupança",
"description": "Minha conta corrente",
"archived": false,
"created_at": "2015-09-15T21:04:30-03:00",
"updated_at": "2015-09-15T21:04:30-03:00",
"default": true,
"type": "checking"
}DELETE /accounts/18
{
"id": 18,
"name": "Itaú Poupança",
"description": "Minha conta corrente",
"archived": false,
"created_at": "2015-09-15T21:04:30-03:00",
"updated_at": "2015-09-15T21:04:30-03:00",
"default": true,
"type": "checking"
}Ao chamar a raiz desse endpoint, ira receber todas as metas referentes ao mês atual.
Para retornar todas as metas referentes ao ano, basta escopar na url /budgets/2018
Metas referentes ao mês e ano, basta escopar na url /budgets/2018/08
GET /budgets
[
{
"amount_in_cents": 150000,
"category_id": 17,
"date": "2018-08-01",
"activity_type": 0,
"total": 0,
"predicted_total": 0,
"percentage": "0.0"
},
{
"amount_in_cents": 30000,
"category_id": 13,
"date": "2018-08-01",
"activity_type": 0,
"total": 0,
"predicted_total": 0,
"percentage": "0.0"
}
]GET /categories
[
{
"id": 1,
"name": "Lazer",
"color": "438b83",
"parent_id": null
},
{
"id": 3,
"name": "Saúde",
"color": "ffff00",
"parent_id": null
},
{
"id": 4,
"name": "Salário",
"color": "66ff99",
"parent_id": null
},
{
"id": 5,
"name": "SEO",
"color": "cc0000",
"parent_id": null
}
]GET /categories/1
{
"id": 1,
"name": "Lazer",
"color": "438b83",
"parent_id": null
}POST /categories
{
"name": "SEO"
}{
"id": 6,
"name": "SEO",
"color": "8dd47f",
"parent_id": null
}PUT /categories/6
{
"name": "Marketing",
}{
"id": 6,
"name": "Marketing",
"color": "8dd47f",
"parent_id": null
}Ao excluir uma categoria você pode informar uma categoria para substitui-la, todas as movimentações da categoria excluídas serão transferidas para a categoria substituta. Se a categoria substituta não for informada, a categoria padrão substituirá a categoria excluída.
DELETE /categories/6
{
"replacement_id": 18
}{
"id": 6,
"name": "Marketing",
"color": "8dd47f",
"parent_id": null
}GET /credit_cards
[
{
"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"
},
{
"id": 4,
"name": "Sem limite",
"description": null,
"card_network": null,
"closing_day": 2,
"due_day": 15,
"limit_cents": 0,
"kind": "credit_card",
"archived": false,
"default": false,
"created_at": "2015-09-01T18:06:16-03:00",
"updated_at": "2015-09-01T18:06:16-03:00"
}
]GET /credit_cards/3
{
"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"
}POST /credit_cards
{
"name": "Hipercard",
"card_network": "hipercard",
"due_day": 15,
"closing_day": 2,
"limit_cents": 500000
}{
"id": 6,
"name": "Hipercard",
"description": null,
"card_network": "hipercard",
"closing_day": 2,
"due_day": 15,
"limit_cents": 500000,
"kind": "credit_card",
"archived": false,
"default": false,
"created_at": "2015-09-15T22:02:55-03:00",
"updated_at": "2015-09-15T22:02:55-03:00"
}PUT /categories/6
{
"name": "Visa Exclusive",
"due_day": 17,
"closing_day": 4,
"update_invoices_since": "2015-07-01"
}{
"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"
}DELETE /credit_cards/3
{
"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"
}GET /credit_cards/3/invoices
[
{
"id": 180,
"date": "2015-01-15",
"starting_date": "2014-12-03",
"closing_date": "2015-01-02",
"amount_cents": 0,
"payment_amount_cents": 0,
"balance_cents": 0,
"previous_balance_cents": 0,
"credit_card_id": 3
},
{
"id": 181,
"date": "2015-02-15",
"starting_date": "2015-01-03",
"closing_date": "2015-02-02",
"amount_cents": 0,
"payment_amount_cents": 0,
"balance_cents": 0,
"previous_balance_cents": 0,
"credit_card_id": 3
},
{
"id": 182,
"date": "2015-03-15",
"starting_date": "2015-02-03",
"closing_date": "2015-03-02",
"amount_cents": 0,
"payment_amount_cents": 0,
"balance_cents": 0,
"previous_balance_cents": 0,
"credit_card_id": 3
},
{
"id": 183,
"date": "2015-04-15",
"starting_date": "2015-03-03",
"closing_date": "2015-04-02",
"amount_cents": 0,
"payment_amount_cents": 0,
"balance_cents": 0,
"previous_balance_cents": 0,
"credit_card_id": 3
},
{
"id": 184,
"date": "2015-05-15",
"starting_date": "2015-04-03",
"closing_date": "2015-05-02",
"amount_cents": -25098,
"payment_amount_cents": 0,
"balance_cents": -25098,
"previous_balance_cents": 0,
"credit_card_id": 3
},
{
"id": 185,
"date": "2015-06-15",
"starting_date": "2015-05-03",
"closing_date": "2015-06-02",
"amount_cents": 584900,
"payment_amount_cents": 0,
"balance_cents": 584900,
"previous_balance_cents": 0,
"credit_card_id": 3
},
{
"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
},
{
"id": 187,
"date": "2015-08-17",
"starting_date": "2015-07-05",
"closing_date": "2015-08-04",
"amount_cents": -22098,
"payment_amount_cents": 0,
"balance_cents": 77902,
"previous_balance_cents": 100000,
"credit_card_id": 3
},
{
"id": 188,
"date": "2015-09-17",
"starting_date": "2015-08-05",
"closing_date": "2015-09-04",
"amount_cents": -15000,
"payment_amount_cents": 0,
"balance_cents": -15000,
"previous_balance_cents": 0,
"credit_card_id": 3
},
{
"id": 189,
"date": "2015-10-17",
"starting_date": "2015-09-05",
"closing_date": "2015-10-04",
"amount_cents": -15000,
"payment_amount_cents": 0,
"balance_cents": -15000,
"previous_balance_cents": 0,
"credit_card_id": 3
},
{
"id": 190,
"date": "2015-11-17",
"starting_date": "2015-10-05",
"closing_date": "2015-11-04",
"amount_cents": -30000,
"payment_amount_cents": 0,
"balance_cents": -30000,
"previous_balance_cents": 0,
"credit_card_id": 3
},
{
"id": 191,
"date": "2015-12-17",
"starting_date": "2015-11-05",
"closing_date": "2015-12-04",
"amount_cents": -15000,
"payment_amount_cents": 0,
"balance_cents": -15000,
"previous_balance_cents": 0,
"credit_card_id": 3
}
]GET /credit_cards/3/invoices/186
{
"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,
"transactions": [
{
"id": 19,
"description": "Gasto no cartão",
"date": "2015-06-03",
"paid": true,
"amount_cents": -5000,
"total_installments": 1,
"installment": 1,
"recurring": false,
"account_id": 3,
"account_type": "CreditCard",
"category_id": 21,
"contact_id": null,
"notes": "",
"attachments_count": 0,
"created_at": "2015-08-04T20:13:49-03:00",
"updated_at": "2015-08-04T20:14:04-03:00"
},
{
"id": 12,
"description": "SAQUE LOT",
"date": "2015-06-06",
"paid": true,
"amount_cents": -15000,
"total_installments": 5,
"installment": 1,
"recurring": false,
"account_id": 3,
"account_type": "CreditCard",
"category_id": 21,
"contact_id": null,
"notes": "",
"attachments_count": 0,
"created_at": "2015-07-01T10:52:06-03:00",
"updated_at": "2015-08-04T20:17:17-03:00"
}
],
"payments": [
{
"id": 83,
"description": "Pagamento Julho de 2015",
"date": "2015-09-01",
"paid": true,
"amount_cents": -20000,
"total_installments": 1,
"installment": 1,
"recurring": false,
"account_id": 3,
"account_type": "Account",
"category_id": 21,
"contact_id": null,
"notes": null,
"attachments_count": 0,
"created_at": "2015-09-01T23:42:29-03:00",
"updated_at": "2015-09-01T23:42:29-03:00"
}
]
}GET /credit_cards/3/invoices/186/payments
{
"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"
}A paginação de movimentações é feita com os parâmetros start_date e end_date, conforme descrito na seção de Paginação acima. O periodo processado será sempre mês inteiro. Ou seja, seu start_date é sempre processado como start_date.beginning_of_month e o seu end_date é sempre convertido para end_date.end_of_month.
Esse endpoint permite filtrar por uma conta bancária (account_id).
Para isso, deve enviar o parâmetro account_id com o id da conta bancária que deseja filtrar.
**No endpoint de contas bancárias /accounts, é possível obter o id de todas suas contas bancárias.
GET /transactions
[
{
"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,
"paid_credit_card_id": null,
"paid_credit_card_invoice_id": null,
"oposite_transaction_id": null,
"oposite_account_id": null,
"created_at": "2015-07-01T10:52:06-03:00",
"updated_at": "2015-08-04T20:17:17-03:00"
},
{
"id": 31,
"description": "Lanche",
"date": "2015-09-02",
"paid": false,
"amount_cents": -2098,
"total_installments": 1,
"installment": 1,
"recurring": false,
"account_id": 3,
"account_type": "Account",
"category_id": 18,
"contact_id": null,
"notes": "",
"attachments_count": 0,
"credit_card_id": null,
"credit_card_invoice_id": null,
"paid_credit_card_id": null,
"paid_credit_card_invoice_id": null,
"oposite_transaction_id": 63,
"oposite_account_id": 4,
"created_at": "2015-08-20T18:00:20-03:00",
"updated_at": "2015-09-01T18:14:54-03:00"
},
{
"id": 63,
"description": "Gasolina",
"date": "2015-09-02",
"paid": false,
"amount_cents": 20000,
"total_installments": 1,
"installment": 1,
"recurring": false,
"account_id": 4,
"account_type": "Account",
"category_id": 18,
"contact_id": null,
"notes": "",
"attachments_count": 0,
"credit_card_id": null,
"credit_card_invoice_id": null,
"paid_credit_card_id": null,
"paid_credit_card_invoice_id": null,
"oposite_transaction_id": 31,
"oposite_account_id": 3,
"created_at": "2015-08-20T18:00:20-03:00",
"updated_at": "2015-09-01T18:14:54-03:00"
},
{
"id": 83,
"description": "Pagamento Julho de 2015",
"date": "2015-09-01",
"paid": true,
"amount_cents": -20000,
"total_installments": 1,
"installment": 1,
"recurring": false,
"account_id": 3,
"account_type": "Account",
"category_id": 21,
"contact_id": null,
"notes": null,
"attachments_count": 0,
"credit_card_id": null,
"credit_card_invoice_id": null,
"paid_credit_card_id": 3,
"paid_credit_card_invoice_id": 186,
"oposite_transaction_id": null,
"oposite_account_id": null,
"created_at": "2015-09-01T23:42:29-03:00",
"updated_at": "2015-09-01T23:42:29-03:00"
}
]GET /transactions/15
{
"id": 15,
"description": "SAQUE LOT",
"date": "2015-09-06",
"paid": false,
"amount_cents": -15000,
"total_installments": 1,
"installment": 1,
"recurring": false,
"account_id": 3,
"category_id": 21,
"contact_id": null,
"notes": "",
"attachments_count": 0,
"credit_card_id": 3,
"credit_card_invoice_id": 189,
"paid_credit_card_id": null,
"paid_credit_card_invoice_id": null,
"oposite_transaction_id": null,
"oposite_account_id": null,
"created_at": "2015-07-01T10:52:06-03:00",
"updated_at": "2015-08-04T20:17:17-03:00"
}POST /transactions
{
"description": "Computador",
"notes": "Pagamento via boleto",
"date": "2015-09-16",
"tags": [{"name": "homeoffice"}]
}{
"id": 97,
"description": "Computador",
"date": "2015-09-16",
"paid": false,
"amount_cents": 0,
"total_installments": 1,
"installment": 1,
"recurring": false,
"account_id": 3,
"category_id": 21,
"contact_id": null,
"notes": "Pagamento via boleto",
"attachments_count": 0,
"credit_card_id": null,
"credit_card_invoice_id": null,
"paid_credit_card_id": null,
"paid_credit_card_invoice_id": null,
"oposite_transaction_id": null,
"oposite_account_id": null,
"created_at": "2015-09-04T00:09:34-03:00",
"updated_at": "2015-09-04T00:09:34-03:00",
"tags": [{"name": "homeoffice"}]
}Os valores para periodicity são: ["monthly", "yearly", "weekly", "biweekly", "bimonthly", "trimonthly"]
POST /transactions
{
"description": "Despesa fixa",
"notes": "Pagamento via boleto",
"date": "2015-09-16",
"recurrence_attributes": {"periodicity": "monthly"}
}{
"id": 97,
"description": "Despesa fixa",
"date": "2015-09-16",
"paid": false,
"amount_cents": 0,
"total_installments": 1,
"installment": 1,
"recurring": true,
"account_id": 3,
"category_id": 21,
"contact_id": null,
"notes": "Pagamento via boleto",
"attachments_count": 0,
"credit_card_id": null,
"credit_card_invoice_id": null,
"paid_credit_card_id": null,
"paid_credit_card_invoice_id": null,
"oposite_transaction_id": null,
"oposite_account_id": null,
"created_at": "2015-09-04T00:09:34-03:00",
"updated_at": "2015-09-04T00:09:34-03:00"
}Os valores para periodicity são: ["monthly", "yearly", "weekly", "biweekly", "bimonthly", "trimonthly"]
POST /transactions
{
"description": "Despesa parcelada",
"notes": "Pagamento via boleto",
"date": "2015-09-16",
"installments_attributes": {"periodicity": "monthly", "total": 12}
}{
"id": 97,
"description": "Despesa parcelada",
"date": "2015-09-16",
"paid": false,
"amount_cents": 0,
"total_installments": 12,
"installment": 1,
"recurring": false,
"account_id": 3,
"category_id": 21,
"contact_id": null,
"notes": "Pagamento via boleto",
"attachments_count": 0,
"credit_card_id": null,
"credit_card_invoice_id": null,
"paid_credit_card_id": null,
"paid_credit_card_invoice_id": null,
"oposite_transaction_id": null,
"oposite_account_id": null,
"created_at": "2015-09-04T00:09:34-03:00",
"updated_at": "2015-09-04T00:09:34-03:00"
}No caso de movimentações fixas ou parceladas, para atualizar a movimentação e as próximas ocorrências envie o attributo "update_future": true; Caso queira atualizar todas as ocorrências, inclusive as anteriores, envie o attributo "update_all": true. Observe que este último pode alterar o saldo da conta caso as movimentações anteriores já estejam pagas/recebidas.
PUT /transactions/101
{
"description": "Updated parcelada via API",
"notes": "Pagamento via boleto",
"amount_cents": 20050,
"date": "2015-12-20",
"update_future": true,
"tags": [{"name": "via_api"}]
}{
"id": 101,
"description": "Updated parcelada via API",
"date": "2015-12-20",
"paid": false,
"amount_cents": -20050,
"total_installments": 1,
"installment": 1,
"recurring": true,
"account_id": 3,
"category_id": 21,
"contact_id": null,
"notes": "Pagamento via boleto",
"attachments_count": 0,
"credit_card_id": null,
"credit_card_invoice_id": null,
"paid_credit_card_id": null,
"paid_credit_card_invoice_id": null,
"oposite_transaction_id": null,
"oposite_account_id": null,
"created_at": "2015-09-04T00:09:34-03:00",
"updated_at": "2015-09-04T00:34:54-03:00",
"tags": [{"name": "via_api"}]
}No caso de movimentações fixas ou parceladas, para excluir a movimentação e as próximas ocorrências envie o attributo "update_future": true; Caso queira excluir todas as ocorrências, inclusive as anteriores, envie o attributo "update_all": true. Observe que este último pode alterar o saldo da conta caso as movimentações anteriores já estejam pagas/recebidas.
DELETE /transactions/101
{
"update_future": true
}{
"id": 101,
"description": "Updated parcelada via API",
"date": "2015-12-20",
"paid": false,
"amount_cents": -20050,
"total_installments": 1,
"installment": 1,
"recurring": true,
"account_id": 3,
"category_id": 21,
"contact_id": null,
"notes": "Pagamento via boleto",
"attachments_count": 0,
"credit_card_id": null,
"credit_card_invoice_id": null,
"paid_credit_card_id": null,
"paid_credit_card_invoice_id": null,
"oposite_transaction_id": null,
"oposite_account_id": null,
"created_at": "2015-09-04T00:09:34-03:00",
"updated_at": "2015-09-04T00:34:54-03:00"
}