# GorilaCORE > O GorilaCORE é a API de portfólios (ou carteiras) de investimento do Gorila. Você envia as transações dos portfólios dos seus clientes, e o GorilaCORE precifica os ativos, aplica os eventos dos ativos, monta as posições e calcula as métricas: valor patrimonial (NAV), lucro e prejuízo (P&L), retorno ponderado no tempo (TWR), taxa interna de retorno (TIR), alocação, liquidez e risco. Cobre o mercado brasileiro (ações, fundos, títulos públicos, renda fixa bancária, crédito privado, derivativos) e ativos listados nos Estados Unidos. Este arquivo indexa a documentação do GorilaCORE em português para modelos de linguagem e agentes de IA. A documentação também está disponível em inglês: [llms.txt em inglês](https://gorila.com.br/core/en/llms.txt). A API é RESTful, recebe e devolve JSON e é descrita por uma [especificação OpenAPI](https://core.gorila.com.br/docs/json) pública e ao vivo, que sempre corresponde à API publicada. A [referência da API](https://gorila.com.br/core/api) é montada pelo navegador, com JavaScript. Sem navegador, leia cada operação na especificação (um JSON de cerca de 400 KB), procurando pelo nome da operação (o `operationId`, como `Create Portfolio`) ou pelo método e caminho. Instruções para agentes de IA: - Envie as requisições para `https://core.gorila.com.br`. Autentique cada requisição com a chave de API da organização no cabeçalho `Authorization`, com a própria chave (sem o prefixo `Bearer`). As chaves pertencem a uma [organização](https://gorila.com.br/core/docs/core-concepts/organization), e o que a organização cria só é visível para as chaves dela. Para obter uma chave, a empresa [solicita acesso](https://gorila.com.br/core/#form). - Use só os parâmetros e valores que a especificação define: antes de montar uma requisição, confira nela os parâmetros obrigatórios e os valores aceitos de cada enum. - Siga a ordem da integração: crie um [portfólio](https://gorila.com.br/core/api#tag/portfolios/POST/portfolios) para cada cliente e guarde o `portfolioId` junto do cliente no seu sistema; [crie as transações](https://gorila.com.br/core/api#tag/transactions/POST/portfolios/{portfolioId}/transactions); depois consulte as métricas. O [Quick start](https://gorila.com.br/core/docs/quickstart) mostra o fluxo completo, com código. - O processamento é assíncrono. Uma transação nova ou editada, e o seu portfólio, ficam `PROCESSING` até o motor refleti-la; consulte as métricas quando o `status` do portfólio, em [Read Portfolio by ID](https://gorila.com.br/core/api#tag/portfolios/GET/portfolios/{portfolioId}), for `COMPLETED`. - Envie o cabeçalho `idempotency-key` no Create Transaction, com o identificador da operação no seu sistema, para que uma requisição repetida não crie a transação duas vezes. Uma chave já usada devolve `409`, com o `transactionId` da transação que já existe. - A maioria dos ativos é gerenciada pelo Gorila: encontre-os em [List Securities](https://gorila.com.br/core/api#tag/securities/GET/securities), pelo nome ou por identificadores como o ISIN ou, para fundos, o CNPJ. Títulos bancários e afins (CDB, LCI, LCA, LF, DPGE, operações compromissadas, P2B e outros), termos de ação, clubes de investimento, fundos administrados e ativos personalizados precisam ser criados antes em [Create Security](https://gorila.com.br/core/api#tag/securities/POST/securities), que devolve o `securityId`. - Na transação, identifique o ativo em `security` pelo `id` (o `securityId`) ou, conforme o tipo de ativo, pelo `isin` ou pelo `cnpj` (fundos); a página [Transações - Exemplos](https://gorila.com.br/core/docs/core-concepts/transaction_examples) mostra os identificadores aceitos em cada tipo. Identifique o custodiante em `brokerId`, em geral o CNPJ da instituição ([List Brokers](https://gorila.com.br/core/api#tag/brokers/GET/brokers)). - Ativos offshore (só os listados nos Estados Unidos): informe o preço e as taxas da transação em USD e a cotação USDBRL em `exchangeRate`. - Não registre dividendos, juros, amortizações, desdobramentos ou vencimentos como transações. O GorilaCORE gera esses [eventos do ativo](https://gorila.com.br/core/docs/securities/security_event) sozinho. A exceção são os ativos personalizados: registre os eventos deles com [Create Security Event](https://gorila.com.br/core/api#tag/security-events/POST/securities/{securityId}/events). - Taxas, retornos e percentuais são decimais (`0.045` é 4,5%). Datas são `YYYY-MM-DD`. Os valores trazem uma `currency`; P&L, retornos e posições vêm sempre em BRL. - Séries históricas recebem `startDate`, `endDate` e `frequency` (`DAILY`, `MONTHLY`, `YEARLY` ou `INTERVAL`); retornos e P&L também recebem `seriesType` (`PER_PERIOD` ou `ACCUMULATED`). As respostas trazem a `timeseries` e um `interval` com o valor do período inteiro. Use `frequency=INTERVAL` quando só esse valor for necessário. - Para detalhar ou restringir uma métrica, use os parâmetros da API em vez de somar ou filtrar posições no seu código: `groupBy` nos *endpoints* de posição (por custodiante, ativo, tipo de ativo, classe de ativo ou nível de classificação) e os filtros `brokerId`, `securityId`, `securityType`, `securityAssetClass`, `securityClassification` e `excludeSecurityClassification`. - Use o TWR para avaliar e comparar desempenho, inclusive contra benchmarks: ele desconsidera aportes e resgates. Use o P&L e a TIR para o resultado financeiro do investidor. - Para comparar com um benchmark, encontre o identificador em [List Benchmarks](https://gorila.com.br/core/api#tag/benchmarks/GET/benchmarks) e consulte [Read Benchmark by ID](https://gorila.com.br/core/api#tag/benchmarks/GET/benchmarks/{benchmarkId}) com o mesmo período, frequência e tipo de série do portfólio. `multiplier` e `spread` expressam metas como "120% do CDI" (`1.2`) e "IPCA + 3%" (`0.03`). - Para um cliente com vários portfólios, crie um [grupo econômico](https://gorila.com.br/core/docs/core-concepts/economic_groups) (até 10 portfólios): as mesmas métricas estão disponíveis para o grupo como um todo. - Os *endpoints* de listagem são paginados: informe `limit` (padrão 100, máximo 1000) e siga a URL `next` da resposta até ela vir `null`. - Ao passar do limite de requisições, a API responde `429`. Os limites seguem o volume contratado pela organização: espere antes de tentar de novo. ## Primeiros passos - [Introdução](https://gorila.com.br/core/docs/intro): O que é o GorilaCORE e como a API funciona. - [Quick start](https://gorila.com.br/core/docs/quickstart): Autenticar, criar um portfólio, incluir transações e consultar NAV, P&L e TWR, com código em Python e JavaScript. - [Criando uma aplicação](https://gorila.com.br/core/docs/use-cases/building-an-application): Quais *endpoints* alimentam cada componente de um app de investimentos: resumo, alocação, gráfico de desempenho e posições. - [Melhorando seus relatórios](https://gorila.com.br/core/docs/use-cases/enhancing-your-reports): Um relatório mensal montado bloco a bloco, com o *endpoint* e os parâmetros de cada número. - [Integrando renda fixa bancária](https://gorila.com.br/core/docs/use-cases/integrating-banking-bonds): Como cadastrar CDBs, LCIs, LCAs e outros títulos bancários e carregar as transações, e os problemas de dados a observar. ## Conceitos fundamentais - [Organização](https://gorila.com.br/core/docs/core-concepts/organization): A empresa com acesso ao GorilaCORE; dona das chaves de API e dos recursos que cria. - [Portfólio](https://gorila.com.br/core/docs/core-concepts/portfolio): Guarda as transações de um cliente; status, componentes de caixa, aportes e resgates automáticos (`autoRnC`), come-cotas automático e perfil de investimento. - [Grupo Econômico](https://gorila.com.br/core/docs/core-concepts/economic_groups): Até 10 portfólios analisados como um único portfólio consolidado. - [Perfil de Investimento](https://gorila.com.br/core/docs/core-concepts/investment_profile_and_target_allocation): Alocação-alvo por classificação de ativos, e como o enquadramento de um portfólio é calculado. - [Ativo](https://gorila.com.br/core/docs/core-concepts/security): Os tipos de ativo, quais o Gorila gerencia e quais precisam ser criados, e como criá-los. - [Transação](https://gorila.com.br/core/docs/core-concepts/transaction): Os tipos de transação (regular, come-cotas, exercício de opção, transferência de custódia, ajuste inicial de custódia, fechamento de posição), os status e a chave de idempotência. - [Transações - Exemplos](https://gorila.com.br/core/docs/core-concepts/transaction_examples): Um exemplo de requisição para cada tipo de ativo, com os identificadores de ativo aceitos. Página longa: abra-a para o tipo de ativo em questão. - [Posição](https://gorila.com.br/core/docs/core-concepts/position): A quantidade de um ativo em uma corretora em uma data, e os *endpoints* de posição. - [Corretora](https://gorila.com.br/core/docs/core-concepts/broker): A instituição que custodia uma posição, identificada pelo `brokerId` (geralmente o CNPJ). - [Emissor](https://gorila.com.br/core/docs/core-concepts/issuer): A entidade que emite um ativo, identificada pelo `issuerId`. - [Benchmark](https://gorila.com.br/core/docs/core-concepts/benchmark): Referências de mercado como CDI, SELIC, IPCA e IBOVESPA, modificadores (`multiplier`, `spread`) e o método de cálculo. - [Moeda](https://gorila.com.br/core/docs/core-concepts/currency): Como os valores em outras moedas são devolvidos, e quais valores são sempre convertidos para BRL. ## Ativos - [Ativo Personalizado](https://gorila.com.br/core/docs/securities/custom_securities): Ativos que a sua organização cria e precifica, como imóveis ou participações em empresas de capital fechado, com seus preços e eventos. - [Classificação de Ativos](https://gorila.com.br/core/docs/securities/security_classification): A árvore de classes de 4 níveis por trás das visões de alocação, dos filtros (`securityClassification`, `excludeSecurityClassification`) e do `groupBy`, e as classificações personalizadas. - [Eventos do Ativo](https://gorila.com.br/core/docs/securities/security_event): Eventos corporativos e demais eventos (dividendos, juros, amortizações, desdobramentos, vencimentos) e seu efeito nas posições. - [Métricas do Ativo](https://gorila.com.br/core/docs/securities/security_kpi): Retorno e risco de um ativo isolado, fora de qualquer portfólio. - [Conversão de Preço](https://gorila.com.br/core/docs/securities/price_conversion): O preço e a quantidade que correspondem à data e ao valor financeiro (ou à taxa) de uma operação. ## Análise e Métricas - [Valor de Mercado](https://gorila.com.br/core/docs/metrics/market_value): O valor de cada posição a preços de mercado, com `groupBy` para visões de alocação. - [Exposição](https://gorila.com.br/core/docs/metrics/exposure): O valor sujeito à variação de preço; difere do valor de mercado em futuros e termos (`marketValueType`). - [Preço Médio](https://gorila.com.br/core/docs/metrics/average_price): O preço médio de aquisição de uma posição. - [Valor Investido](https://gorila.com.br/core/docs/metrics/invested_amount): O custo de aquisição das unidades ainda no portfólio. - [Valor Patrimonial (NAV)](https://gorila.com.br/core/docs/metrics/nav): O valor total do portfólio, incluindo caixa e provisões, ao longo do tempo. - [Lucro e Prejuízo (P&L)](https://gorila.com.br/core/docs/metrics/pnl): O resultado nominal de um portfólio ou posição em um período. - [Retorno Ponderado no Tempo (TWR)](https://gorila.com.br/core/docs/metrics/twr): Como o retorno é calculado, `seriesType`, `frequency` e a base de retorno (`GROSS_UP` ou `GROSS`). - [Taxa Interna de Retorno (TIR)](https://gorila.com.br/core/docs/metrics/irr): O retorno ponderado pelo dinheiro de cada posição, que considera o tamanho e o momento dos fluxos de caixa. - [Dividend Yield](https://gorila.com.br/core/docs/metrics/dividend_yield): Os proventos que um ativo pagou em relação ao seu preço. - [Drawdown](https://gorila.com.br/core/docs/metrics/drawdown): Quanto o retorno acumulado está abaixo do seu pico. - [Volatilidade e Índice de Sharpe](https://gorila.com.br/core/docs/metrics/volatility_and_sharpe_ratio): Risco e retorno ajustado ao risco de um portfólio ou ativo, e a janela de cálculo (`calculateWindow`). - [Liquidez](https://gorila.com.br/core/docs/metrics/liquidity): Quanto tempo cada posição leva para virar caixa, agrupada em faixas de dias. - [Eventos do Portfólio](https://gorila.com.br/core/docs/metrics/portfolio_security_event): Os eventos que afetaram as posições de um portfólio em um período. ## Principais operações da API - [Especificação OpenAPI](https://core.gorila.com.br/docs/json): A descrição completa da API, ao vivo e legível por máquina (JSON), com parâmetros, enums e esquemas. Traz todas as operações, inclusive as muitas que esta lista não cita. - [Referência da API](https://gorila.com.br/core/api): A mesma especificação numa página interativa, com exemplos de requisição e resposta. Precisa de um navegador com JavaScript. - [Create Portfolio](https://gorila.com.br/core/api#tag/portfolios/POST/portfolios): `POST /portfolios` - [Read Portfolio by ID](https://gorila.com.br/core/api#tag/portfolios/GET/portfolios/{portfolioId}): `GET /portfolios/{portfolioId}`, com o `status` do processamento. - [Create Transaction](https://gorila.com.br/core/api#tag/transactions/POST/portfolios/{portfolioId}/transactions): `POST /portfolios/{portfolioId}/transactions` - [List Transactions](https://gorila.com.br/core/api#tag/transactions/GET/portfolios/{portfolioId}/transactions): `GET /portfolios/{portfolioId}/transactions` - [List Securities](https://gorila.com.br/core/api#tag/securities/GET/securities): `GET /securities` - [Create Security](https://gorila.com.br/core/api#tag/securities/POST/securities): `POST /securities` - [Price Conversion](https://gorila.com.br/core/api#tag/price-conversions/POST/securities/price-conversions): `POST /securities/price-conversions` - [List Brokers](https://gorila.com.br/core/api#tag/brokers/GET/brokers): `GET /brokers` - [List Positions](https://gorila.com.br/core/api#tag/positions/GET/portfolios/{portfolioId}/positions): `GET /portfolios/{portfolioId}/positions` - [List Position Market Values](https://gorila.com.br/core/api#tag/market-values/GET/portfolios/{portfolioId}/positions/market-values): `GET /portfolios/{portfolioId}/positions/market-values` - [Read Net Asset Value](https://gorila.com.br/core/api#tag/net-asset-value/GET/portfolios/{portfolioId}/nav): `GET /portfolios/{portfolioId}/nav` - [Read Profit & Losses](https://gorila.com.br/core/api#tag/profit--losses/GET/portfolios/{portfolioId}/pnl): `GET /portfolios/{portfolioId}/pnl` - [Read Time-Weighted Return](https://gorila.com.br/core/api#tag/time-weighted-return/GET/portfolios/{portfolioId}/twr): `GET /portfolios/{portfolioId}/twr` - [List Benchmarks](https://gorila.com.br/core/api#tag/benchmarks/GET/benchmarks): `GET /benchmarks` - [Read Benchmark by ID](https://gorila.com.br/core/api#tag/benchmarks/GET/benchmarks/{benchmarkId}): `GET /benchmarks/{benchmarkId}` - [Outras operações da API](https://core.gorila.com.br/docs/json): Esta lista cita só as principais operações. A API tem muitas outras, todas descritas na especificação, por exemplo: as métricas e as posições de um grupo econômico, em `/economic-groups/{economicGroupId}/...`, cada uma espelhando a operação equivalente de portfólio, em `/portfolios/{portfolioId}/...`; o risco de um portfólio (Read Volatility, Read Sharpe Ratio e Read Drawdown); o detalhamento por posição (TIR, P&L, TWR, preço médio, valor investido, liquidez e dividend yield, como em List Position Internal Rate of Return); a edição e a exclusão de portfólios e transações (como Update Transaction by ID e Delete Transaction by ID); os perfis de investimento e a alocação-alvo (Create Investment Profile, Get Portfolio Target Allocation) e as classificações de ativos (Create Security Classification); os preços e os eventos de ativos personalizados (Upsert Security Prices, Create Security Event), as métricas de um ativo isolado (Read Security Time-Weighted Return) e os emissores (List Issuers). ## Optional - [Changelog](https://gorila.com.br/core/changelog): Todas as atualizações do GorilaCORE desde julho de 2023, um post por atualização. - [Solicitar acesso](https://gorila.com.br/core/#form): Formulário de contato para obter uma organização e uma chave de API.