Detalhamento de Valores - Manual do usuário

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.

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.

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.

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.

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.

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.

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

GET /api/v1/transactions/:transaction_id/amount_details

Exemplo de resposta para uma transação simples (sem detalhamentos)

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

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

GET /api/v1/transactions/:transaction_id/amount_details/:id

Exemplo de resposta para visualizar um detalhamento específico

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

POST /api/v1/transactions/:transaction_id/amount_details

Exemplo de corpo da requisição para criar um detalhamento

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

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

PUT /api/v1/transactions/:transaction_id/amount_details/:id

Exemplo de corpo da requisição para marcar como pago

{
  "paid": true,
  "paid_at": "2026-03-26"
}

Exemplo de resposta para editar um detalhamento (200 OK)

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

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)

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

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

DELETE /api/v1/transactions/:transaction_id/amount_details/:id

Exemplo de resposta para excluir um detalhamento (200 OK)

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

{
  "error": "must be greater than 0"
}

​Introdução

​Rotas

​Visualizar todos os detalhamentos

​Visualizar um detalhamento específico

​Criar um detalhamento

​Editar um detalhamento

​Atualizar coleção completa de detalhamentos

​Excluir um detalhamento

​Visualizando todos os detalhamentos

​Visualizando um detalhamento específico

​Criando um detalhamento

​Editando um detalhamento

​Atualizando coleção de detalhamentos

​Excluindo um detalhamento

​Erros

​Erros de validação

​Tabela de erros

Introdução

Rotas

Visualizar todos os detalhamentos

Visualizar um detalhamento específico

Criar um detalhamento

Editar um detalhamento

Atualizar coleção completa de detalhamentos

Excluir um detalhamento

Visualizando todos os detalhamentos

Visualizando um detalhamento específico

Criando um detalhamento

Editando um detalhamento

Atualizando coleção de detalhamentos

Excluindo um detalhamento

Erros

Erros de validação

Tabela de erros