> ## Documentation Index
> Fetch the complete documentation index at: https://docs.procfy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Detalhamento de Valores
## Introdução
Na API do Procfy o detalhamento de valores permite dividir o valor total de uma transação em itens individuais (filhos). Quando o primeiro detalhamento é adicionado a uma transação **simples**, ela é automaticamente convertida para uma transação **detalhada**. Os totais da transação pai (valor, valor pago, status de pagamento) são recalculados automaticamente a partir dos filhos.
Atributos com o valor `null` serão retornados na resposta.
| Atributo | Tipo | Descrição |
| :----------------- | :------ | :---------------------------------- |
| id | integer | Identificador único do detalhamento |
| name | string | Nome do detalhamento |
| description | string | Descrição do detalhamento |
| due\_date | date | Data de vencimento |
| competency\_date | date | Data de competência |
| category\_id | integer | Identificador da categoria |
| contact\_id | integer | Identificador do contato |
| cost\_center\_id | integer | Identificador do centro de custo |
| paid | boolean | Indica se o detalhamento foi pago |
| paid\_at | date | Data de pagamento |
| amount | decimal | Valor do detalhamento |
| amount\_cents | integer | Valor do detalhamento em centavos |
| category\_name | string | Nome da categoria |
| contact\_name | string | Nome do contato |
| cost\_center\_name | string | Nome do centro de custo |
| created\_at | string | Data de criação |
| updated\_at | string | Data de atualização |
Ao excluir o último detalhamento de uma transação **detalhada**, ela é automaticamente revertida para **simples**.
***
## **Rotas**
| Método | Endpoint | Descrição |
| :---------- | :----------------------------------------------------------------------- | :------------------------------------------ |
| GET | /api/v1/transactions/:transaction\_id/amount\_details | Visualizar todos os detalhamentos |
| GET | /api/v1/transactions/:transaction\_id/amount\_details/:id | Visualizar um detalhamento específico |
| POST | /api/v1/transactions/:transaction\_id/amount\_details | Criar um detalhamento |
| PUT / PATCH | /api/v1/transactions/:transaction\_id/amount\_details/:id | Editar um detalhamento |
| PUT | /api/v1/transactions/:transaction\_id/amount\_details/update\_collection | Atualizar coleção completa de detalhamentos |
| DELETE | /api/v1/transactions/:transaction\_id/amount\_details/:id | Excluir um detalhamento |
#### **Visualizar todos os detalhamentos**
Para visualizar todos os detalhamentos de uma transação, faça uma requisição `GET` para o endpoint correspondente.
```text theme={null}
GET /api/v1/transactions/:transaction_id/amount_details
```
#### **Visualizar um detalhamento específico**
Para visualizar um detalhamento específico, faça uma requisição `GET` informando o `id` do detalhamento.
```text theme={null}
GET /api/v1/transactions/:transaction_id/amount_details/:id
```
#### **Criar um detalhamento**
Para criar um detalhamento, faça uma requisição `POST` com os atributos desejados no corpo da requisição.
```text theme={null}
POST /api/v1/transactions/:transaction_id/amount_details
```
#### **Editar um detalhamento**
Para editar um detalhamento, faça uma requisição `PUT` ou `PATCH` informando o `id` do detalhamento.
```text theme={null}
PUT /api/v1/transactions/:transaction_id/amount_details/:id
```
#### **Atualizar coleção completa de detalhamentos**
Para substituir a coleção inteira de detalhamentos em uma única requisição, utilize o endpoint `update_collection`.
```text theme={null}
PUT /api/v1/transactions/:transaction_id/amount_details/update_collection
```
#### **Excluir um detalhamento**
Para excluir um detalhamento, faça uma requisição `DELETE` informando o `id` do detalhamento.
```text theme={null}
DELETE /api/v1/transactions/:transaction_id/amount_details/:id
```
***
## **Visualizando todos os detalhamentos**
Para visualizar todos os detalhamentos de uma transação, faça uma requisição `GET` para o endpoint correspondente.
A resposta inclui um resumo dos totais da transação e o array `items` com os detalhamentos.
> Exemplo de requisição para visualizar todos os detalhamentos de uma transação
```text theme={null}
GET /api/v1/transactions/:transaction_id/amount_details
```
> Exemplo de resposta para uma transação simples (sem detalhamentos)
```json theme={null}
{
"transaction_id": 123,
"transaction_kind": "simple",
"children_count": 0,
"total_amount": 1000.0,
"total_amount_cents": 100000,
"allocated_amount": 0.0,
"allocated_amount_cents": 0,
"paid_amount": 0.0,
"paid_amount_cents": 0,
"remaining_amount": 1000.0,
"remaining_amount_cents": 100000,
"all_children_paid": false,
"items": [],
"can_add_details": true,
"message": "This transaction is simple and can be converted to detailed by adding items."
}
```
> Exemplo de resposta para uma transação detalhada (com detalhamentos)
```json theme={null}
{
"transaction_id": 123,
"transaction_kind": "detailed",
"children_count": 2,
"total_amount": 1000.0,
"total_amount_cents": 100000,
"allocated_amount": 1000.0,
"allocated_amount_cents": 100000,
"paid_amount": 500.0,
"paid_amount_cents": 50000,
"remaining_amount": 0.0,
"remaining_amount_cents": 0,
"all_children_paid": false,
"items": [
{
"id": 456,
"name": "Primeira parcela",
"description": "Pagamento de janeiro",
"due_date": "2026-01-15",
"competency_date": "2026-01-01",
"category_id": 10,
"contact_id": 20,
"cost_center_id": 30,
"paid": true,
"paid_at": "2026-01-15",
"created_at": "2026-01-01T10:00:00.000Z",
"updated_at": "2026-01-15T14:30:00.000Z",
"amount": 500.0,
"amount_cents": 50000,
"category_name": "Serviços",
"contact_name": "Empresa ABC",
"cost_center_name": "Operações"
},
{
"id": 789,
"name": "Segunda parcela",
"description": "Pagamento de fevereiro",
"due_date": "2026-02-15",
"competency_date": "2026-02-01",
"category_id": 10,
"contact_id": 20,
"cost_center_id": 30,
"paid": false,
"paid_at": null,
"created_at": "2026-01-01T10:00:00.000Z",
"updated_at": "2026-01-01T10:00:00.000Z",
"amount": 500.0,
"amount_cents": 50000,
"category_name": "Serviços",
"contact_name": "Empresa ABC",
"cost_center_name": "Operações"
}
]
}
```
***
## **Visualizando um detalhamento específico**
Para visualizar um detalhamento específico, faça uma requisição `GET` informando o `id` do detalhamento.
> Exemplo de requisição para visualizar um detalhamento específico
```text theme={null}
GET /api/v1/transactions/:transaction_id/amount_details/:id
```
> Exemplo de resposta para visualizar um detalhamento específico
```json theme={null}
{
"id": 456,
"name": "Primeira parcela",
"description": "Pagamento de janeiro",
"due_date": "2026-01-15",
"competency_date": "2026-01-01",
"category_id": 10,
"contact_id": 20,
"cost_center_id": 30,
"paid": true,
"paid_at": "2026-01-15",
"created_at": "2026-01-01T10:00:00.000Z",
"updated_at": "2026-01-15T14:30:00.000Z",
"amount": 500.0,
"amount_cents": 50000,
"category_name": "Serviços",
"contact_name": "Empresa ABC",
"cost_center_name": "Operações"
}
```
***
## **Criando um detalhamento**
Para criar um detalhamento, faça uma requisição `POST` para o endpoint correspondente.
A API retorna o objeto criado. Se a transação for **simples**, ela é automaticamente convertida para **detalhada**.
Os atributos opcionais não informados são herdados da transação pai (`due_date`, `competency_date`, `category_id`, `contact_id`, `cost_center_id`).
Os atributos são:
| Atributo | Tipo | Obrigatório | Descrição |
| :--------------- | :------ | :---------- | :-------------------------------------------------- |
| amount | decimal | **sim** | Valor do detalhamento (deve ser maior que 0) |
| description | string | não | Descrição do detalhamento |
| name | string | não | Nome (usa `description` se não informado) |
| due\_date | date | não | Data de vencimento (herda da transação pai) |
| competency\_date | date | não | Data de competência (herda da transação pai) |
| category\_id | integer | não | Identificador da categoria (herda da transação pai) |
| contact\_id | integer | não | Identificador do contato (herda da transação pai) |
| cost\_center\_id | integer | não | Identificador do centro de custo |
| paid | boolean | não | Se o detalhamento foi pago (padrão: `false`) |
| paid\_at | date | não | Data de pagamento |
> Exemplo de requisição para criar um detalhamento
```text theme={null}
POST /api/v1/transactions/:transaction_id/amount_details
```
> Exemplo de corpo da requisição para criar um detalhamento
```json theme={null}
{
"amount": 500.0,
"description": "Primeira parcela",
"name": "Parcela 1",
"due_date": "2026-01-15",
"category_id": 10,
"contact_id": 20,
"paid": true,
"paid_at": "2026-01-15"
}
```
> Exemplo de resposta para criar um detalhamento (`201 Created`)
```json theme={null}
{
"message": "Amount detail created successfully.",
"id": 456,
"name": "Parcela 1",
"description": "Primeira parcela",
"due_date": "2026-01-15",
"competency_date": null,
"category_id": 10,
"contact_id": 20,
"cost_center_id": null,
"paid": true,
"paid_at": "2026-01-15",
"amount": 500.0,
"amount_cents": 50000,
"category_name": "Serviços",
"contact_name": "Empresa ABC",
"cost_center_name": null,
"created_at": "2026-01-10T10:00:00.000Z",
"updated_at": "2026-01-10T10:00:00.000Z"
}
```
***
## **Editando um detalhamento**
Para editar um detalhamento, faça uma requisição `PUT` ou `PATCH` informando o `id` do detalhamento.
Apenas os atributos informados no corpo da requisição serão atualizados. Os demais permanecem inalterados.
Após a edição, os totais da transação pai são recalculados automaticamente.
> Exemplo de requisição para editar um detalhamento
```text theme={null}
PUT /api/v1/transactions/:transaction_id/amount_details/:id
```
> Exemplo de corpo da requisição para marcar como pago
```json theme={null}
{
"paid": true,
"paid_at": "2026-03-26"
}
```
> Exemplo de resposta para editar um detalhamento (`200 OK`)
```json theme={null}
{
"message": "Amount detail updated successfully.",
"id": 456,
"name": "Primeira parcela",
"description": "Pagamento de janeiro",
"due_date": "2026-01-15",
"competency_date": "2026-01-01",
"category_id": 10,
"contact_id": 20,
"cost_center_id": 30,
"paid": true,
"paid_at": "2026-03-26",
"amount": 500.0,
"amount_cents": 50000,
"category_name": "Serviços",
"contact_name": "Empresa ABC",
"cost_center_name": "Operações",
"created_at": "2026-01-01T10:00:00.000Z",
"updated_at": "2026-03-26T09:00:00.000Z"
}
```
***
## **Atualizando coleção de detalhamentos**
Para substituir a coleção inteira de detalhamentos em uma única requisição, utilize o endpoint `update_collection`.
Detalhamentos **não incluídos** no array `items` serão excluídos. Itens com `id` informado são atualizados; itens sem `id` são criados.
Os atributos do array `items` são:
| Atributo | Tipo | Obrigatório | Descrição |
| :--------------- | :------ | :---------- | :----------------------------------------------- |
| id | integer | não | ID do detalhamento existente (omitir para criar) |
| amount | decimal | **sim** | Valor do detalhamento (deve ser maior que 0) |
| description | string | não | Descrição do detalhamento |
| name | string | não | Nome do detalhamento |
| due\_date | date | não | Data de vencimento |
| competency\_date | date | não | Data de competência |
| category\_id | integer | não | Identificador da categoria |
| contact\_id | integer | não | Identificador do contato |
| cost\_center\_id | integer | não | Identificador do centro de custo |
| paid | boolean | não | Status de pagamento |
| paid\_at | date | não | Data de pagamento |
> Exemplo de requisição para atualizar a coleção de detalhamentos
```text theme={null}
PUT /api/v1/transactions/:transaction_id/amount_details/update_collection
```
> Exemplo de corpo da requisição (mantém um existente, cria um novo, remove os demais)
```json theme={null}
{
"items": [
{
"id": 456,
"amount": 600.0,
"description": "Primeira parcela atualizada"
},
{
"amount": 400.0,
"description": "Nova segunda parcela",
"due_date": "2026-02-15"
}
]
}
```
> Exemplo de resposta para atualizar a coleção (`200 OK`)
```json theme={null}
{
"message": "Amount details collection updated successfully.",
"transaction_id": 123,
"transaction_kind": "detailed",
"children_count": 2,
"total_amount": 1000.0,
"total_amount_cents": 100000,
"allocated_amount": 1000.0,
"allocated_amount_cents": 100000,
"paid_amount": 0.0,
"paid_amount_cents": 0,
"remaining_amount": 0.0,
"remaining_amount_cents": 0,
"all_children_paid": false,
"items": [
{
"id": 456,
"amount": 600.0,
"amount_cents": 60000,
"description": "Primeira parcela atualizada",
"paid": false,
"paid_at": null
},
{
"id": 790,
"amount": 400.0,
"amount_cents": 40000,
"description": "Nova segunda parcela",
"due_date": "2026-02-15",
"paid": false,
"paid_at": null
}
]
}
```
***
## **Excluindo um detalhamento**
Para excluir um detalhamento, faça uma requisição `DELETE` informando o `id` do detalhamento.
Se o detalhamento excluído for o último filho da transação, ela é automaticamente revertida para **simples**.
> Exemplo de requisição para excluir um detalhamento
```text theme={null}
DELETE /api/v1/transactions/:transaction_id/amount_details/:id
```
> Exemplo de resposta para excluir um detalhamento (`200 OK`)
```json theme={null}
{
"message": "Amount detail deleted successfully."
}
```
***
## **Erros**
Erros que podem ocorrer durante as operações de detalhamento de valores.
#### **Erros de validação**
Os erros de validação são retornados quando os atributos obrigatórios não são informados ou quando os valores informados não passam nas regras de validação (ex: `amount` igual a zero ou negativo).
#### **Tabela de erros**
| Status | Descrição |
| :----- | :----------------------------------------------------------------------------- |
| 400 | Token de autenticação ausente ou inválido |
| 403 | Token sem permissão suficiente ou acesso negado à conta |
| 404 | Transação ou detalhamento não encontrado (ou pertence a outra conta) |
| 422 | Erro de validação (ex: `amount` não informado, `amount` menor ou igual a zero) |
> Exemplo de resposta para erro de validação (`422 Unprocessable Entity`)
```json theme={null}
{
"error": "must be greater than 0"
}
```