Endpoints de Transferência de Lotes

Visão Geral

A API de Transferência de Lotes gerencia a movimentação de populações de camarão entre tanques. Isso é essencial para operações de repicagem, remanejamento ou divisão de lotes.

Ajustes Automáticos

Ao criar uma transferência, as populações de origem e destino são automaticamente ajustadas, e os custos são acumulados adequadamente.

---

POST /transfers/

Cria um novo registro de transferência entre tanques.

Requisição

POST /api/v1/transfers/
Authorization: Bearer {token}
Content-Type: application/json

{
  "batch_id": "batch-uuid",
  "from_pond_id": "pond-uuid-1",
  "to_pond_id": "pond-uuid-2"
}

Parâmetros do Body

Campo	Tipo	Obrigatório	Descrição
batch_id	UUID	✅	ID do lote sendo transferido
from_pond_id	UUID	✅	ID do viveiro de origem
to_pond_id	UUID	✅	ID do viveiro de destino
transfer_date	date	❌	Data da transferência (padrão: dia atual)
population_count	integer	❌	População no momento (calculado se omitido)
avg_weight	number	❌	Peso médio (calculado se omitido)

Resposta 201 Created

{
  "id": "transfer-uuid",
  "batch_id": "batch-uuid",
  "farm_id": "farm-uuid",
  "from_pond_id": "pond-uuid-1",
  "to_pond_id": "pond-uuid-2",
  "population_count": 50000,
  "avg_weight": 8.5,
  "biomass_kg": 425.0,
  "transfer_date": "2026-02-15T10:30:00Z",
  "performed_by": "Joao Silva",
  "accumulated_feed_kg": 340.0,
  "accumulated_feed_cost": 5100.0,
  "accumulated_operational_cost": 1200.0,
  "days_in_previous_pond": 45,
  "created_at": "2026-02-15T10:35:00Z"
}

Nota

O backend calcula automaticamente transfer_date, population_count, avg_weight e biomass_kg quando esses campos opcionais nao sao enviados.

---

GET /transfers/{id}

Obtém detalhes de uma transferência específica.

Parâmetros de Path

Parâmetro	Tipo	Descrição
id	integer	ID da transferência

Requisição

GET /api/v1/transfers/1
Authorization: Bearer {token}

Resposta 200 OK

{
  "id": 1,
  "source_pond": {
    "id": 1,
    "name": "Tanque A1"
  },
  "destination_pond": {
    "id": 2,
    "name": "Tanque A2"
  },
  "batch": {
    "id": 5,
    "name": "Lote 2026-A"
  },
  "quantity": 50000,
  "average_weight": 8.5,
  "biomass_transferred": 425.0,
  "transfer_date": "2026-02-15T10:30:00Z",
  "reason": "Repicagem",
  "notes": "Transferência para reduzir densidade",
  "created_at": "2026-02-15T10:35:00Z",
  "created_by": {
    "id": 1,
    "name": "João Silva"
  }
}

---

PUT /transfers/{id}

Atualiza um registro de transferência existente.

Cuidado

Atualizar uma transferência irá recalcular automaticamente as populações dos tanques de origem e destino.

Parâmetros de Path

Parâmetro	Tipo	Descrição
id	integer	ID da transferência

Requisição

PUT /api/v1/transfers/1
Authorization: Bearer {token}
Content-Type: application/json

{
  "quantity": 48000,
  "notes": "Atualizado: mortalidade de 2000 durante transferência"
}

Resposta 200 OK

{
  "id": 1,
  "quantity": 48000,
  "notes": "Atualizado: mortalidade de 2000 durante transferência",
  "updated_at": "2026-02-15T11:00:00Z"
}

---

DELETE /transfers/{id}

Exclui um registro de transferência.

Cuidado

Excluir uma transferência irá reverter os ajustes de população nos tanques de origem e destino.

Parâmetros de Path

Parâmetro	Tipo	Descrição
id	integer	ID da transferência

Requisição

DELETE /api/v1/transfers/1
Authorization: Bearer {token}

Resposta 204 No Content

---

GET /transfers/batch/{batch_id}

Lista todas as transferências de um lote específico.

Parâmetros de Path

Parâmetro	Tipo	Descrição
batch_id	integer	ID do lote

Parâmetros de Query

Parâmetro	Tipo	Descrição
skip	integer	Registros a pular (paginação)
limit	integer	Máximo de registros (padrão: 100)

Requisição

GET /api/v1/transfers/batch/5?skip=0&limit=50
Authorization: Bearer {token}

Resposta 200 OK

{
  "items": [
    {
      "id": 1,
      "from_pond_id": "pond-uuid-1",
      "to_pond_id": "pond-uuid-2",
      "population_count": 50000,
      "avg_weight": 8.5,
      "biomass_kg": 425.0,
      "transfer_date": "2026-02-15T10:30:00Z",
      "performed_by": "Joao Silva"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 50
}

---

GET /transfers/batch/{batch_id}/history

Obtém o histórico completo de movimentação de um lote.

Parâmetros de Path

Parâmetro	Tipo	Descrição
batch_id	integer	ID do lote

Requisição

GET /api/v1/transfers/batch/5/history
Authorization: Bearer {token}

Resposta 200 OK

{
  "batch_id": 5,
  "batch_name": "Lote 2026-A",
  "total_transfers": 3,
  "total_quantity_moved": 150000,
  "history": [
    {
      "id": 1,
      "date": "2026-02-15T10:30:00Z",
      "from": "Tanque A1",
      "to": "Tanque A2",
      "quantity": 50000,
      "average_weight": 8.5,
      "reason": "Repicagem"
    },
    {
      "id": 2,
      "date": "2026-03-01T08:00:00Z",
      "from": "Tanque A2",
      "to": "Tanque A3",
      "quantity": 50000,
      "average_weight": 12.0,
      "reason": "Remanejamento"
    }
  ],
  "current_locations": [
    {
      "pond_id": 2,
      "pond_name": "Tanque A2",
      "quantity": 45000
    },
    {
      "pond_id": 3,
      "pond_name": "Tanque A3",
      "quantity": 48000
    }
  ]
}

---

Cenários Comuns

1. Repicagem (Dividindo Superlotação)

{
  "batch_id": "batch-uuid",
  "from_pond_id": "pond-uuid-1",
  "to_pond_id": "pond-uuid-2"
}

2. Transferência de Engorda

{
  "batch_id": "batch-uuid",
  "from_pond_id": "pond-uuid-3",
  "to_pond_id": "pond-uuid-4",
  "avg_weight": 15.0
}

3. Consolidação de Lotes

Dica

Para consolidar múltiplos tanques em um, crie transferências separadas de cada tanque de origem para o destino.

---

Tratamento de Erros

Código	Descrição
400	Dados de transferência inválidos
404	Transferência, lote ou tanque não encontrado
409	Conflito - quantidade excede população disponível
422	Erro de validação