FFINAUTON B2B · Docs
App modelo

Referência da API

Clientes

Cadastro do cliente na FINAUTON, visão consolidada e controle pelo backoffice. O cliente é identificado pelo SEU id (externalUserId) — nunca pelo e-mail.
POST/v1/usersGET/v1/usersGET/v1/users/:externalUserIdGET/v1/users/:externalUserId/statusGET/v1/users/:externalUserId/commercialPOST/v1/users/:externalUserId/suspendPOST/v1/users/:externalUserId/reactivate
POST/v1/users

Criar cliente

Rotina do servidorIdempotency-Key obrigatórioVer no app modelo: Criar conta ↗

Cria o cliente (ou devolve o existente com created:false). Chame no cadastro do usuário no seu app. O e-mail não vai para a FINAUTON.

Se a FINAUTON recusar, desfaça o cadastro local ou marque para nova tentativa (com a mesma Idempotency-Key).

Corpo (JSON)

  • externalUserIdstring (1–120)obrigatório

    id do cliente no SEU sistema

  • tenantIdstringcondicional

    obrigatório se você tem tenants

Erros comuns

  • 400TENANT_REQUIREDfaltou tenantId
  • 409TENANT_MISMATCHo id já existe em outro tenant
  • 400IDEMPOTENCY_KEY_REQUIREDfaltou o cabeçalho
Requisição
curl -X POST "$FIN_API/v1/users" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "Idempotency-Key: create-user-cli-1001-$(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "externalUserId": "cli-1001",
    "tenantId": "TENANT_A"
  }'
Resposta201
{
  "externalUserId": "cli-1001",
  "tenantId": "TENANT_A",
  "status": "ACTIVE",
  "created": true,
  "requestId": "req_muyn3wh8_9qgkdh2s"
}
GET/v1/users

Listar clientes

Backoffice do parceiroVer no app modelo: Clientes ↗

Lista seus clientes, do mais novo para o mais antigo.

Query string

  • tenantIdstringopcional

    filtra por tenant

  • statusACTIVE | SUSPENDEDopcional

    filtra por status

  • limit1–500opcional

    padrão 100

Requisição
curl -X GET "$FIN_API/v1/users?status=ACTIVE&limit=50" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"
Resposta200
{
  "users": [
    {
      "externalUserId": "cli-1001",
      "tenantId": "TENANT_A",
      "status": "ACTIVE",
      "createdAt": "2026-10-07T21:38:31.726Z",
      "updatedAt": "2026-10-07T21:38:31.726Z"
    }
  ],
  "requestId": "req_muyn0vxt_0pdrd3he"
}
GET/v1/users/:externalUserId

Consultar cliente

Rotina do servidor

Vínculo do cliente e as automações registradas.

Parâmetros de caminho

  • externalUserIdstring (1–120)obrigatório

    id do cliente no SEU sistema

Erros comuns

  • 404NOT_FOUNDnão existe ou não é seu
Requisição
curl -X GET "$FIN_API/v1/users/cli-1001" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"
Resposta200
{
  "externalUserId": "cli-1001",
  "tenantId": "TENANT_A",
  "status": "ACTIVE",
  "automations": [
    {
      "providerId": "BINANCE",
      "strategyId": "FUTURES_MAIN_V1",
      "strategyVersion": "1.0.0",
      "enabled": false,
      "risk": {
        "leverage": 3,
        "maxMarginPerTradeUsd": 10,
        "maxConcurrentTrades": 1,
        "maxDailyLossUsd": 10
      },
      "conditions": {},
      "runtime": "DISABLED"
    }
  ],
  "requestId": "req_muyn0vyp_et3iv74l"
}
GET/v1/users/:externalUserId/status

Status consolidado

Tela do clienteVer no app modelo: Minha conta ↗

A chamada principal da tela inicial do cliente: por corretora, conexão, setup e situação comercial; automações; posições abertas. Use para o checklist "primeiros passos": estratégia → corretora CONNECTED → setup enabled → automação ligada.

Cliente novo aparece com setup.mode "PAPER" e enabled false (padrão interno, nunca opera) até gravar o setup REAL.

Parâmetros de caminho

  • externalUserIdstring (1–120)obrigatório

    id do cliente no SEU sistema

Requisição
curl -X GET "$FIN_API/v1/users/cli-1001/status" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"
Resposta200
{
  "externalUserId": "cli-1001",
  "tenantId": "TENANT_A",
  "requestId": "req_muyn0vzl_c4pkli1i",
  "status": "ACTIVE",
  "access": {
    "active": true
  },
  "strategies": [
    "FUTURES_MAIN_V1"
  ],
  "providers": [
    {
      "providerId": "BINANCE",
      "connection": "NOT_CONNECTED",
      "setup": {
        "mode": "PAPER",
        "enabled": false
      },
      "commercial": {
        "allowed": true,
        "state": "ACTIVE",
        "reasonCode": "B2B_CONTRACT_ACTIVE",
        "graceUntil": null,
        "source": "B2B_CONTRACT"
      }
    }
  ],
  "automations": [
    {
      "providerId": "BINANCE",
      "strategyId": "FUTURES_MAIN_V1",
      "enabled": false
    }
  ],
  "openPositions": 0
}
GET/v1/users/:externalUserId/commercial

Situação comercial

Rotina do servidor

Por corretora: se pode abrir novas entradas pelo lado comercial (allowed), o estado (ACTIVE, GRACE, SUSPENDED, REVOKED, BLACKLISTED, NO_ENTITLEMENT, ACCOUNT_INACTIVE), o motivo e o fim da carência.

Parâmetros de caminho

  • externalUserIdstring (1–120)obrigatório

    id do cliente no SEU sistema

Requisição
curl -X GET "$FIN_API/v1/users/cli-1001/commercial" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET"
Resposta200
{
  "externalUserId": "cli-1001",
  "tenantId": "TENANT_A",
  "requestId": "req_muyn0w1o_qm9wu8pm",
  "clientStatus": "ACTIVE",
  "providers": [
    {
      "providerId": "BINANCE",
      "allowed": true,
      "state": "ACTIVE",
      "reasonCode": "B2B_CONTRACT_ACTIVE",
      "graceUntil": null,
      "source": "B2B_CONTRACT"
    }
  ]
}
POST/v1/users/:externalUserId/suspend

Suspender cliente

Backoffice do parceiroVer no app modelo: Clientes ↗

Bloqueia novas entradas e escritas do cliente. Leitura e manutenção das posições abertas (stop, alvo, fechamento) continuam.

Parâmetros de caminho

  • externalUserIdstring (1–120)obrigatório

    id do cliente no SEU sistema

Corpo (JSON)

  • reasonstring (3–500)obrigatório

    motivo

Requisição
curl -X POST "$FIN_API/v1/users/cli-1001/suspend" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "content-type: application/json" \
  -d '{
    "reason": "Pedido do cliente"
  }'
Resposta200
{
  "externalUserId": "cli-1001",
  "tenantId": "TENANT_A",
  "status": "SUSPENDED",
  "createdAt": "2026-10-07T21:49:03.493Z",
  "updatedAt": "2026-10-07T21:49:04.600Z",
  "requestId": "req_muyn3xdg_8sc7kyur"
}
POST/v1/users/:externalUserId/reactivate

Reativar cliente

Backoffice do parceiroVer no app modelo: Clientes ↗

Reativa o cliente. Não significa "pode operar": todas as outras regras (setup, conexão, cobrança) continuam valendo.

Parâmetros de caminho

  • externalUserIdstring (1–120)obrigatório

    id do cliente no SEU sistema

Corpo (JSON)

  • reasonstring (3–500)obrigatório

    motivo

Requisição
curl -X POST "$FIN_API/v1/users/cli-1001/reactivate" \
  -u "$FIN_CLIENT_ID:$FIN_CLIENT_SECRET" \
  -H "content-type: application/json" \
  -d '{
    "reason": "Regularizado"
  }'
Resposta200
{
  "externalUserId": "cli-1001",
  "tenantId": "TENANT_A",
  "status": "ACTIVE",
  "createdAt": "2026-10-07T21:49:03.493Z",
  "updatedAt": "2026-10-07T21:49:04.674Z",
  "requestId": "req_muyn3xfm_5kzkqsl0"
}