Criar ou Atualizar Calculadora

📖 Descrição

Endpoint que cria ou atualiza (upsert) os dados de entrada de uma posição de arbitragem spot-futuro na Calculadora. Se já existir uma entrada para o par email + ticker, ela é sobrescrita com os novos valores. Os dados de entrada são o ponto de referência para o cálculo do PNL em tempo real.

Este endpoint é o primeiro passo — registrar a posição de entrada. Depois de salvo, use GET /v1/calculators/stream para monitorar o PNL em tempo real.

🛠️ Requisição

Método

POST

URL

/v1/calculators

Request Body

Campo	Tipo	Obrigatório	Descrição
`email`	string	Sim	Email do usuário
`ticker`	string	Sim	Par de trading (ex: `BTC-USDT`)
`entrySpotValue`	float	Sim	Preço de entrada no mercado Spot
`entryShortValue`	float	Sim	Preço de entrada no mercado Futuro (short)
`entrySpotQty`	float	Sim	Quantidade comprada no Spot
`entryFuturesQty`	float	Sim	Quantidade vendida nos Futuros

Exemplo de Requisição

curl -X POST http://localhost:8080/v1/calculators \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "ticker": "BTC-USDT",
    "entrySpotValue": 83000.00,
    "entryShortValue": 83150.00,
    "entrySpotQty": 0.1,
    "entryFuturesQty": 0.1
  }'

📤 Resposta

Exemplo de Resposta (200 OK)

{
  "id": "507f1f77bcf86cd799439011",
  "email": "user@example.com",
  "ticker": "BTC-USDT",
  "entrySpotValue": 83000.00,
  "entryShortValue": 83150.00,
  "entrySpotQty": 0.1,
  "entryFuturesQty": 0.1,
  "entrySpotTotalValue": 8300.00,
  "entryFuturesTotalValue": 8315.00,
  "entrySpread": 150.00,
  "entrySpreadPercentage": 0.18,
  "timestamp": 1743595200000
}

Campos da Resposta

Campo	Tipo	Descrição
`id`	string	ID da entrada no MongoDB
`email`	string	Email do usuário
`ticker`	string	Par de trading
`entrySpotValue`	float	Preço spot de entrada
`entryShortValue`	float	Preço futuro de entrada
`entrySpotQty`	float	Quantidade spot
`entryFuturesQty`	float	Quantidade futuro
`entrySpotTotalValue`	float	`entrySpotValue × entrySpotQty`
`entryFuturesTotalValue`	float	`entryShortValue × entryFuturesQty`
`entrySpread`	float	`entryShortValue − entrySpotValue`
`entrySpreadPercentage`	float	`(entrySpread / entrySpotValue) × 100`
`timestamp`	int64	Timestamp de criação (milissegundos Unix)

📝 Códigos de Resposta

200 OK: Posição criada ou atualizada com sucesso. Retorna o objeto completo com spread calculado.

400 Bad Request:

Invalid request body: JSON malformado
email is required: Campo email ausente
ticker is required: Campo ticker ausente

500 Internal Server Error: Failed to create or update calculator — Erro ao persistir no MongoDB.

🔁 Comportamento de Upsert

O endpoint verifica se já existe uma entrada para email + ticker:

Não existe → cria um novo documento
Já existe → atualiza todos os campos de valor/quantidade

Isso garante que cada usuário tenha apenas uma posição por par de trading, facilitando o rastreamento via stream.

🔍 Fluxo Completo da Calculadora

POST /v1/calculators          → Registra dados de entrada (este endpoint)
GET  /v1/calculators/stream   → Monitora PNL em tempo real (SSE)
POST /v1/calculators/process  → Consulta pontual de PNL (alternativa ao stream)

API Documentation

Endpoint Examples

Criar ou Atualizar Calculadora

📖 Descrição

🛠️ Requisição

Método

URL

Request Body

Exemplo de Requisição

📤 Resposta

Exemplo de Resposta (200 OK)

Campos da Resposta

📝 Códigos de Resposta

🔁 Comportamento de Upsert

🔍 Fluxo Completo da Calculadora

​📖 Descrição

​🛠️ Requisição

​Método

​URL

​Request Body

​Exemplo de Requisição

​📤 Resposta

​Exemplo de Resposta (200 OK)

​Campos da Resposta

​📝 Códigos de Resposta

​🔁 Comportamento de Upsert

​🔍 Fluxo Completo da Calculadora

📖 Descrição

🛠️ Requisição

Método

URL

Request Body

Exemplo de Requisição

📤 Resposta

Exemplo de Resposta (200 OK)

Campos da Resposta

📝 Códigos de Resposta

🔁 Comportamento de Upsert

🔍 Fluxo Completo da Calculadora