> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arbitragem-crypto.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Operações do journal

> CRUD de operações, fechamento e cancelamento — /v1/journal/operations

Todas as rotas são escopadas pelo `email` do usuário (query string no `GET`/`DELETE`,
corpo JSON nos demais). Uma operação de outro email responde 404.

| Método | Rota | Ação |
| - | - | - |
| `GET` | `/v1/journal/operations?email=&status=&strategy=&asset=&from=&to=&page=&size=` | Lista paginada (`size` 1..100, padrão 20) |
| `POST` | `/v1/journal/operations` | Registra uma operação aberta |
| `GET` | `/v1/journal/operations/{id}?email=` | Detalha uma operação |
| `PUT` | `/v1/journal/operations/{id}` | Edita; operações encerradas aceitam apenas `notes`, `fees` e `funding` |
| `POST` | `/v1/journal/operations/{id}/close` | Fecha e calcula o resultado realizado |
| `POST` | `/v1/journal/operations/{id}/cancel` | Cancela; não entra nos relatórios |
| `DELETE` | `/v1/journal/operations/{id}?email=` | Exclui definitivamente |

`from`/`to` (RFC3339) filtram por `closedAt` quando `status` é `closed` ou
`cancelled`, e por `openedAt` nos demais casos. `source` filtra pela origem.

## Origem e idempotência

`source` indica de onde a operação veio: `manual`, `calculator` ou `desktop`.
Sem valor, vira `calculator` quando há `calculatorId` e `manual` nos demais
casos. O resumo agrupa o resultado por origem em `bySource`.

`externalId` (até 128 caracteres) é o id da operação no cliente, como o id da
execução no app desktop. Com ele a criação é idempotente por usuário: repetir
o `POST` com o mesmo `externalId` devolve a operação existente com **200** em
vez de criar outra (a primeira criação responde 201). Isso permite repetir a
chamada com segurança depois de uma falha de rede ou de retomar uma execução.

`source` e `externalId` só são lidos na criação.

## Estratégias

| `strategy` | Pernas | Resultado bruto |
| - | - | - |
| `spot_spot` | Compra `quantity` em `buyExchange` e vende em `sellExchange` | `(exitSellPrice − entryBuyPrice) × quantity` |
| `spot_future` | Long spot em `buyExchange`, short perpétuo em `sellExchange` | `(exitBuy − entryBuy) × quantity + (entrySell − exitSell) × shortQuantity` |
| `funding` | Igual a `spot_future` (cash and carry) | Igual a `spot_future` |

Em `spot_spot`, `entrySellPrice` é o preço de venda esperado e o fechamento
exige apenas `exitSellPrice`.

## Taxas

`fees` aceita `trading`, `withdrawal` e `funding` em moeda de cotação. Quando
`fees` é nulo o serviço estima as taxas com a taxa taker de cada exchange sobre
todas as pernas e, em `spot_spot`, um saque da `buyExchange`. Sem dado da
exchange são usados `NET_SPREAD_DEFAULT_TAKER_RATE` e
`NET_SPREAD_DEFAULT_WITHDRAWAL_USD`, e a operação fica com `feesEstimated: true`.
O campo `funding` do corpo define o funding (positivo recebido, negativo pago)
mesmo com taxas estimadas.

Resultado líquido = bruto − trading − withdrawal + funding. O percentual usa o
nocional de entrada.

```json theme={null}
POST /v1/journal/operations
{
  "email": "user@example.com",
  "asset": "BTC-USDT",
  "strategy": "spot_future",
  "buyExchange": "Binance",
  "sellExchange": "Binance",
  "quantity": 0.05,
  "shortQuantity": 0.05,
  "entryBuyPrice": 60000,
  "entrySellPrice": 60420,
  "fees": null,
  "calculatorId": "66f0c0ffee"
}
```

Erros: 400 para validação, 404 para operação inexistente ou de outro email,
409 ao fechar ou cancelar uma operação que não está aberta, 429 pelo limitador
geral e 500 em falha do MongoDB.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.