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

{
  "source_pond_id": 1,
  "destination_pond_id": 2,
  "batch_id": 5,
  "quantity": 50000,
  "average_weight": 8.5,
  "transfer_date": "2026-02-15T10:30:00Z",
  "reason": "Repicagem",
  "notes": "Transferência para reduzir densidade"
}

Parâmetros do Body

Campo	Tipo	Obrigatório	Descrição
source_pond_id	integer	✅	ID do tanque de origem
destination_pond_id	integer	✅	ID do tanque de destino
batch_id	integer	✅	ID do lote sendo transferido
quantity	integer	✅	Número de animais transferidos
average_weight	number	❌	Peso médio no momento da transferência (g)
transfer_date	datetime	✅	Data/hora da transferência (ISO 8601 UTC)
reason	string	❌	Motivo da transferência
notes	string	❌	Observações adicionais

Resposta 201 Created

{
  "id": 1,
  "source_pond_id": 1,
  "destination_pond_id": 2,
  "batch_id": 5,
  "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": 1
}

---

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,
      "source_pond_id": 1,
      "destination_pond_id": 2,
      "quantity": 50000,
      "transfer_date": "2026-02-15T10:30:00Z",
      "reason": "Repicagem"
    }
  ],
  "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)

{
  "source_pond_id": 1,
  "destination_pond_id": 2,
  "batch_id": 5,
  "quantity": 100000,
  "reason": "Repicagem - superlotação",
  "notes": "Dividindo lote para manter densidade adequada"
}

2. Transferência de Engorda

{
  "source_pond_id": 3,
  "destination_pond_id": 4,
  "batch_id": 5,
  "quantity": 150000,
  "average_weight": 15.0,
  "reason": "Transferência para engorda",
  "notes": "Movendo para tanque de engorda maior"
}

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