API docs by Redocly

Reconciliation Partner API (1.0-draft)

Download OpenAPI specification:

API de reconciliação de posições da From Investors para a Smartbrain, parceira exclusiva desta integração. Todas as chamadas são server-to-server com a credencial de parceiro emitida para a Smartbrain. Operações de escrita exigem o header X-End-User-Id (usuário final da Smartbrain), usado para autoria dos runs e rastreio de custo de IA.

Convenções: datas yyyy-MM-dd; camelCase; paginação page/pageSize.

Idempotência. Envie Idempotency-Key (até 64 caracteres, único por requisição) nos POSTs de escrita. Dentro de 24 horas, repetir a mesma chave com o mesmo corpo devolve a resposta original sem executar de novo, com o header Idempotent-Replay: true. A mesma chave com corpo ou caminho diferente devolve 409. Se a primeira chamada ainda estiver em processamento, a segunda também recebe 409: repita em instantes. Resposta de erro não é guardada, então a mesma chave serve para retentar a requisição que falhou.

Não se aplica a POST /auth/token (repetir precisa emitir token novo) nem ao import de planilha, que é multipart e já é substitutivo por escritório, custodiante e período.

A criação de escritório e de carteira é idempotente também por externalId, independentemente do header.

Fora desta versão (documentado para planejamento, ainda não disponível): push programático de posições por carteira (PUT .../custodian-positions e .../consolidator-positions), consulta de consumo (GET /usage) e webhooks (PUT /webhooks). Posições entram por importação de planilha, no endpoint por escritório descrito em Positions.

Auth

Obtém token de acesso (client credentials)

Request Body schema: application/json
required
clientId
required
string
clientSecret
required
string

Responses

Request samples

Content type
application/json
{
  • "clientId": "string",
  • "clientSecret": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "tokenType": "Bearer",
  • "expiresIn": 1800
}

Confirma qual parceiro o token representa

Útil para validar a credencial e o ambiente logo no início da integração, sem efeito colateral. Não exige X-End-User-Id.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "partnerId": 0,
  • "partnerName": "string"
}

Provisioning

Cria um office (tenant do cliente final do parceiro)

Authorizations:
bearerAuth
header Parameters
X-End-User-Id
required
string

Id estável do usuário final no parceiro (autoria + custo de IA)

Idempotency-Key
string <= 64 characters

Torna o POST seguro para retentativa por 24h. Repetição com o mesmo corpo devolve a resposta original e o header Idempotent-Replay: true; corpo diferente na mesma chave devolve 409.

Request Body schema: application/json
required
externalId
required
string

Id da organização no parceiro (único)

name
required
string
taxId
required
string

CNPJ da empresa (14 dígitos, com ou sem máscara). Obrigatório: é a identidade fiscal do escritório, única na base.

aiConfidenceThreshold
number

Confiança mínima p/ auto-confirmar sugestões N:M da IA (0-1, default 0.90)

isSandbox
boolean
Default: false

Escritório de sandbox (dados fictícios, mesma instância). Nesses escritórios a reconciliação pula as etapas de IA, então integrar não gera custo de modelo; o matching determinístico e as regras de grupo seguem funcionando.

aiMonthlyCostCapUsd
number

Teto de custo de IA no mês (USD). Quando omitido, aplicamos um teto padrão conservador (proteção contra consumo muito acima do esperado). Ao atingir o teto, a reconciliação pula só as etapas de IA (não falha).

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "name": "string",
  • "taxId": "string",
  • "aiConfidenceThreshold": 0,
  • "isSandbox": false,
  • "aiMonthlyCostCapUsd": 0
}

Response samples

Content type
application/json
{
  • "officeId": 0,
  • "externalId": "string",
  • "name": "string",
  • "code": "string",
  • "isSandbox": true,
  • "isActive": true,
  • "aiMonthlyCostCapUsd": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Lista offices da credencial

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1
pageSize
integer <= 200
Default: 50

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Cria uma carteira (investidor) no office

Authorizations:
bearerAuth
path Parameters
officeId
required
string
header Parameters
X-End-User-Id
required
string

Id estável do usuário final no parceiro (autoria + custo de IA)

Idempotency-Key
string <= 64 characters

Torna o POST seguro para retentativa por 24h. Repetição com o mesmo corpo devolve a resposta original e o header Idempotent-Replay: true; corpo diferente na mesma chave devolve 409.

Request Body schema: application/json
required
externalId
required
string

Id da carteira no parceiro (único no office)

name
required
string
consolidatorPortfolioCode
string

Código da carteira no consolidador (para pull automático); omitir se usar push

email
string

E-mail de contato da carteira. Se omitido, geramos um placeholder no-reply.

taxId
string

CPF/CNPJ do investidor (opcional)

Array of objects

Contas de custódia (metadado; as posições entram pelo import de planilha)

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "name": "string",
  • "consolidatorPortfolioCode": "string",
  • "email": "string",
  • "taxId": "string",
  • "accounts": [
    ]
}

Response samples

Content type
application/json
{
  • "portfolioId": "string",
  • "officeId": 0,
  • "externalId": "string",
  • "name": "string",
  • "consolidatorPortfolioCode": "string",
  • "accountsCount": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Lista carteiras do office

Authorizations:
bearerAuth
path Parameters
officeId
required
string
query Parameters
page
integer
Default: 1
pageSize
integer <= 200
Default: 50

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Positions

Importa planilha de custódia (fluxo padrão, mesmos modelos de hoje)

Fluxo principal de custódia: o usuário final envia a planilha da instituição, no modelo específico (XP, Genial, BTG) ou no modelo genérico, exatamente como já acontece hoje na plataforma. O backend parseia com o importador correspondente.

É por ESCRITÓRIO, não por carteira: a planilha da instituição cobre todas as contas do escritório. A reconciliação atribui cada linha à carteira certa pelas contas cadastradas no provisionamento.

Substitutivo por (escritório, custodiante, período): cada import troca a carga anterior, então reenviar o mesmo arquivo é seguro e não duplica posições.

O período é mensal (MM-AAAA) porque é assim que as posições de custódia são armazenadas e consultadas pela reconciliação.

Authorizations:
bearerAuth
path Parameters
officeId
required
string
header Parameters
X-End-User-Id
required
string

Id estável do usuário final no parceiro (autoria + custo de IA)

Request Body schema: multipart/form-data
required
file
required
string <binary>

Planilha .xlsx no modelo indicado (até 25 MB)

model
required
string
Enum: "xp" "genial" "btg" "generic"

Modelo da planilha; "generic" = layout genérico da plataforma

period
required
string^(0[1-9]|1[0-2])-\d{4}$

Período de referência no formato MM-AAAA

Responses

Response samples

Content type
application/json
{
  • "accepted": 0,
  • "replaced": 0,
  • "custodian": "string",
  • "period": "07-2026"
}

Reconciliation

Executa a reconciliação da carteira em uma data

Authorizations:
bearerAuth
path Parameters
portfolioId
required
string
header Parameters
X-End-User-Id
required
string

Id estável do usuário final no parceiro (autoria + custo de IA)

Idempotency-Key
string <= 64 characters

Torna o POST seguro para retentativa por 24h. Repetição com o mesmo corpo devolve a resposta original e o header Idempotent-Replay: true; corpo diferente na mesma chave devolve 409.

Request Body schema: application/json
required
date
required
string <date>
mode
string
Default: "sync"
Enum: "sync" "async"

async → 202 + polling/webhook (Fase 3)

Responses

Request samples

Content type
application/json
{
  • "date": "2019-08-24",
  • "mode": "sync"
}

Response samples

Content type
application/json
{
  • "runId": "string",
  • "portfolioId": "string",
  • "date": "2019-08-24",
  • "status": "queued",
  • "matchedCount": 0,
  • "groupMatchCount": 0,
  • "unmatchedConsolidatorCount": 0,
  • "unmatchedCustodianCount": 0,
  • "totalConsolidatorValue": 0,
  • "totalCustodianValue": 0,
  • "totalDifference": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdByEndUserId": "string",
  • "pairs": [
    ],
  • "groupMatches": [
    ],
  • "pendingSuggestions": [
    ],
  • "unmatchedConsolidator": [
    ],
  • "unmatchedCustodian": [
    ]
}

Histórico de runs da carteira

Authorizations:
bearerAuth
path Parameters
portfolioId
required
string
query Parameters
from
string <date>
to
string <date>
page
integer
Default: 1
pageSize
integer <= 200
Default: 50

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Status e resumo de um run

Authorizations:
bearerAuth
path Parameters
runId
required
string

Responses

Response samples

Content type
application/json
{
  • "runId": "string",
  • "portfolioId": "string",
  • "date": "2019-08-24",
  • "status": "queued",
  • "matchedCount": 0,
  • "groupMatchCount": 0,
  • "unmatchedConsolidatorCount": 0,
  • "unmatchedCustodianCount": 0,
  • "totalConsolidatorValue": 0,
  • "totalCustodianValue": 0,
  • "totalDifference": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdByEndUserId": "string"
}

Resumo do run com os grupos N:M

Devolve o resumo e os grupos N:M (que são persistidos).

Atenção: pairs, unmatchedConsolidator e unmatchedCustodian vêm vazios aqui. O detalhe linha a linha não é armazenado, então só está disponível na resposta do POST que executa a reconciliação. Guarde esse payload se precisar exibi-lo depois, ou execute a reconciliação novamente.

Authorizations:
bearerAuth
path Parameters
runId
required
string

Responses

Response samples

Content type
application/json
{
  • "runId": "string",
  • "portfolioId": "string",
  • "date": "2019-08-24",
  • "status": "queued",
  • "matchedCount": 0,
  • "groupMatchCount": 0,
  • "unmatchedConsolidatorCount": 0,
  • "unmatchedCustodianCount": 0,
  • "totalConsolidatorValue": 0,
  • "totalCustodianValue": 0,
  • "totalDifference": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdByEndUserId": "string",
  • "pairs": [
    ],
  • "groupMatches": [
    ],
  • "pendingSuggestions": [
    ],
  • "unmatchedConsolidator": [
    ],
  • "unmatchedCustodian": [
    ]
}

Exporta o resultado em Excel (.xlsx)

Mesmo layout de planilha usado na plataforma, incluindo a seção de grupos N:M.

Como o detalhe linha a linha não é armazenado, o arquivo é remontado recalculando a reconciliação daquela data. O download não cria um run novo no histórico, mas se as posições mudaram desde a execução original os números podem diferir.

Authorizations:
bearerAuth
path Parameters
runId
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Curation

Match manual, grupos N:M, sugestões de IA e regras (Fase 2)

Cria match manual 1:1 (aprende o mapeamento para runs futuros)

Os dois lados são os OBJETOS COMPLETOS devolvidos pela reconciliação (mesma forma de consolidatorPosition/custodianPosition na resposta do run), não apenas um id: o motor aprende o mapeamento a partir dos dados do ativo. Recomenda-se reenviar exatamente o objeto recebido na lista de não-pareados.

Authorizations:
bearerAuth
path Parameters
portfolioId
required
string
header Parameters
X-End-User-Id
required
string

Id estável do usuário final no parceiro (autoria + custo de IA)

Idempotency-Key
string <= 64 characters

Torna o POST seguro para retentativa por 24h. Repetição com o mesmo corpo devolve a resposta original e o header Idempotent-Replay: true; corpo diferente na mesma chave devolve 409.

Request Body schema: application/json
required
required
object (ConsolidatorPositionInput)
required
object (CustodianPositionInput)
justification
string

Responses

Request samples

Content type
application/json
{
  • "consolidatorPosition": {
    },
  • "custodianPosition": {
    },
  • "justification": "string"
}

Response samples

Content type
application/json
{
  • "mappingId": "string",
  • "pair": {
    }
}

Desfaz um match 1:1 e remove o mapeamento aprendido

Authorizations:
bearerAuth
path Parameters
mappingId
required
string
header Parameters
X-End-User-Id
required
string

Id estável do usuário final no parceiro (autoria + custo de IA)

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Cria match de grupo N:M (gera sempre uma regra reutilizável por carteira)

Assim como no match manual 1:1, os dois lados são os objetos completos das posições selecionadas (do resultado da reconciliação), não ids. Diferente da confirmação de sugestão de IA, o match manual de grupo SEMPRE gera uma regra reutilizável, na mesma convenção do 1:1 da plataforma. Não há opção de não salvar como regra.

Authorizations:
bearerAuth
path Parameters
runId
required
string
header Parameters
X-End-User-Id
required
string

Id estável do usuário final no parceiro (autoria + custo de IA)

Idempotency-Key
string <= 64 characters

Torna o POST seguro para retentativa por 24h. Repetição com o mesmo corpo devolve a resposta original e o header Idempotent-Replay: true; corpo diferente na mesma chave devolve 409.

Request Body schema: application/json
required
required
Array of objects (ConsolidatorPositionInput) non-empty
required
Array of objects (CustodianPositionInput) non-empty
description
string

Responses

Request samples

Content type
application/json
{
  • "consolidatorPositions": [
    ],
  • "custodianPositions": [
    ],
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "matchId": "string",
  • "matchType": "Manual",
  • "status": "Confirmed",
  • "ruleId": "string",
  • "consolidatorItems": [
    ],
  • "custodianItems": [
    ],
  • "consolidatorTotalValue": 0,
  • "custodianTotalValue": 0,
  • "consolidatorTotalQuantity": 0,
  • "custodianTotalQuantity": 0,
  • "difference": 0,
  • "aiConfidence": 0,
  • "aiReason": "string"
}

Exclui match de grupo (desativa a regra associada, se houver)

Authorizations:
bearerAuth
path Parameters
runId
required
string
matchId
required
string
header Parameters
X-End-User-Id
required
string

Id estável do usuário final no parceiro (autoria + custo de IA)

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Confirma sugestão de grupo da IA

Authorizations:
bearerAuth
path Parameters
runId
required
string
matchId
required
string
header Parameters
X-End-User-Id
required
string

Id estável do usuário final no parceiro (autoria + custo de IA)

Idempotency-Key
string <= 64 characters

Torna o POST seguro para retentativa por 24h. Repetição com o mesmo corpo devolve a resposta original e o header Idempotent-Replay: true; corpo diferente na mesma chave devolve 409.

Request Body schema: application/json
saveAsRule
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "saveAsRule": true
}

Response samples

Content type
application/json
{
  • "matchId": "string",
  • "matchType": "Manual",
  • "status": "Confirmed",
  • "ruleId": "string",
  • "consolidatorItems": [
    ],
  • "custodianItems": [
    ],
  • "consolidatorTotalValue": 0,
  • "custodianTotalValue": 0,
  • "consolidatorTotalQuantity": 0,
  • "custodianTotalQuantity": 0,
  • "difference": 0,
  • "aiConfidence": 0,
  • "aiReason": "string"
}

Rejeita sugestão de grupo da IA

Authorizations:
bearerAuth
path Parameters
runId
required
string
matchId
required
string
header Parameters
X-End-User-Id
required
string

Id estável do usuário final no parceiro (autoria + custo de IA)

Idempotency-Key
string <= 64 characters

Torna o POST seguro para retentativa por 24h. Repetição com o mesmo corpo devolve a resposta original e o header Idempotent-Replay: true; corpo diferente na mesma chave devolve 409.

Responses

Lista regras de grupo ativas do office

Authorizations:
bearerAuth
path Parameters
officeId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Atualiza regra (descrição/ativação)

Authorizations:
bearerAuth
path Parameters
ruleId
required
string
header Parameters
X-End-User-Id
required
string

Id estável do usuário final no parceiro (autoria + custo de IA)

Request Body schema: application/json
description
string
isActive
boolean

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "isActive": true
}

Desativa a regra

Authorizations:
bearerAuth
path Parameters
ruleId
required
string
header Parameters
X-End-User-Id
required
string

Id estável do usuário final no parceiro (autoria + custo de IA)

Responses

Usage

Webhooks