openapi: 3.0.1 info: title: Introdução description: | Otimize a gestão financeira da sua operação com eficiência e segurança. Organize livros razão, monitore transações e saldos em tempo real, e consolide dados com precisão. Automatize processos com Smart Transactions, garantindo controle total, rastreabilidade e integridade das transações financeiras. Saiba mais sobre o Ledger Kernel Engine [aqui](https://hub.guardia.finance/docs/modules :::warning Ao atualizar um metadata, quando o valor for `null`, caso a propriedade exista, ela será considerada para remoção, conforme a especificação do Json Merge Patch [RFC 7386](https://datatracker.ietf.org/doc/html/rfc7386). ::: operationId: update_asset tags: - Assets parameters: - $ref: "#/components/parameters/AssetIdentifierParam" - $ref: "#/components/parameters/IdempotencyKey" - $ref: "#/components/parameters/Accept" - $ref: "#/components/parameters/AcceptLanguage" - $ref: "#/components/parameters/ContentType" - $ref: "#/components/parameters/CorrelationId" requestBody: required: true content: application/vnd.guardia.v1+json: schema: $ref: "#/components/schemas/AssetUpdateRequest" responses: "200": description: Asset atualizado com sucesso. headers: Cache-Control: $ref: "#/components/headers/Cache-Control" Content-Digest: $ref: "#/components/headers/Content-Digest" Content-Language: $ref: "#/components/headers/Content-Language" Content-Length: $ref: "#/components/headers/Content-Length" Content-Type: $ref: "#/components/headers/Content-Type" Idempotency-Key: $ref: "#/components/headers/Idempotency-Key" Last-Modified: $ref: "#/components/headers/Last-Modified" Strict-Transport-Security: $ref: "#/components/headers/Strict-Transport-Security" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-RateLimit-Limit: $ref: "#/components/headers/X-RateLimit-Limit" X-RateLimit-Remaining: $ref: "#/components/headers/X-RateLimit-Remaining" X-RateLimit-Reset: $ref: "#/components/headers/X-RateLimit-Reset" content: application/vnd.guardia.v1+json: schema: type: object properties: data: $ref: "#/components/schemas/Asset" "400": $ref: "#/components/responses/Error400" "401": $ref: "#/components/responses/Error401" "403": $ref: "#/components/responses/Error403" "404": $ref: "#/components/responses/Error404" "409": $ref: "#/components/responses/Error409" "422": $ref: "#/components/responses/Error422" "429": $ref: "#/components/responses/Error429" "500": $ref: "#/components/responses/Error500" security: [] delete: summary: Descarta um asset específico deprecated: false description: | :::note Se o asset estiver associado a um ledger ativo, isto é, com transações, o descarte será realizado de forma lógica, inativando-o para que não seja mais possível associá-lo a novos ledgers. ::: operationId: delete_asset tags: - Assets parameters: - $ref: "#/components/parameters/AssetIdentifierParam" - $ref: "#/components/parameters/Accept" - $ref: "#/components/parameters/AcceptLanguage" - $ref: "#/components/parameters/ContentType" - $ref: "#/components/parameters/CorrelationId" responses: "204": description: Asset excluído com sucesso headers: Cache-Control: $ref: "#/components/headers/Cache-Control" Content-Digest: $ref: "#/components/headers/Content-Digest" Content-Language: $ref: "#/components/headers/Content-Language" Content-Length: $ref: "#/components/headers/Content-Length" Content-Type: $ref: "#/components/headers/Content-Type" Last-Modified: $ref: "#/components/headers/Last-Modified" Strict-Transport-Security: $ref: "#/components/headers/Strict-Transport-Security" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-RateLimit-Limit: $ref: "#/components/headers/X-RateLimit-Limit" X-RateLimit-Remaining: $ref: "#/components/headers/X-RateLimit-Remaining" X-RateLimit-Reset: $ref: "#/components/headers/X-RateLimit-Reset" "400": $ref: "#/components/responses/Error400" "401": $ref: "#/components/responses/Error401" "403": $ref: "#/components/responses/Error403" "404": $ref: "#/components/responses/Error404" "409": $ref: "#/components/responses/Error409" "422": $ref: "#/components/responses/Error422" "429": $ref: "#/components/responses/Error429" "500": $ref: "#/components/responses/Error500" security: [] x-apidog-folder: Assets x-apidog-status: developing x-apidog-maintainer: Fernando Seguim /v1/ledgers/{ledger_identifier}/books: post: summary: Cria um novo book description: | O Book é uma entidade fundamental que representa uma conta contábil no LKe. Com sua natureza definida como credora ou devedora, ele organiza e registra lançamentos financeiros de maneira estruturada, rastreável e segregada conforme a finalidade contábil ou operacional. Como unidade básica na estrutura do ledger, os Books proporcionam um controle preciso sobre saldos, movimentações e conciliações. Todo Book deve estar vinculado a um Asset, que representa a moeda utilizada (seja fiduciária ou não) nas transações. Além disso, pode ser associado a um Chapter do Ledger para otimizar a gestão e o controle financeiro. operationId: create_ledger_book tags: - Books parameters: - $ref: "#/components/parameters/LedgerIdentifierParam" - $ref: "#/components/parameters/IdempotencyKey" - $ref: "#/components/parameters/Accept" - $ref: "#/components/parameters/AcceptLanguage" - $ref: "#/components/parameters/ContentType" - $ref: "#/components/parameters/CorrelationId" requestBody: required: true content: application/vnd.guardia.v1+json: schema: $ref: "#/components/schemas/BookCreateRequest" responses: "201": description: Book criado com sucesso. headers: Content-Type: $ref: "#/components/headers/Content-Type" Content-Length: $ref: "#/components/headers/Content-Length" Content-Language: $ref: "#/components/headers/Content-Language" Cache-Control: $ref: "#/components/headers/Cache-Control" Idempotency-Key: $ref: "#/components/headers/Idempotency-Key" Content-Digest: $ref: "#/components/headers/Content-Digest" Last-Modified: $ref: "#/components/headers/Last-Modified" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-RateLimit-Limit: $ref: "#/components/headers/X-RateLimit-Limit" X-RateLimit-Remaining: $ref: "#/components/headers/X-RateLimit-Remaining" X-RateLimit-Reset: $ref: "#/components/headers/X-RateLimit-Reset" content: application/vnd.guardia.v1+json: schema: type: object properties: data: $ref: "#/components/schemas/Book" "400": $ref: "#/components/responses/Error400" "401": $ref: "#/components/responses/Error401" "403": $ref: "#/components/responses/Error403" "404": $ref: "#/components/responses/Error404" "409": $ref: "#/components/responses/Error409" "422": $ref: "#/components/responses/Error422" "429": $ref: "#/components/responses/Error429" "500": $ref: "#/components/responses/Error500" security: - BearerAuth: [] get: summary: Lista todos os books do ledger description: Obtém uma lista de books disponíveis no ledger especificado filtrando por metadata, moeda (asset_codes) ou chapters (chapter_ids), além de incluir itens descartados. operationId: list_ledger_books tags: - Books parameters: - $ref: "#/components/parameters/LedgerIdentifierParam" - $ref: "#/components/parameters/ListOfEntityIds" - $ref: "#/components/parameters/ListOfExternalEntityIds" - $ref: "#/components/parameters/ListOfDenominationCodes" - $ref: "#/components/parameters/ListOfChapterIds" - $ref: "#/components/parameters/MetadataFilter" - $ref: "#/components/parameters/IncludeDiscarded" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/PageToken" - $ref: "#/components/parameters/OrderBy" - $ref: "#/components/parameters/Sort" - $ref: "#/components/parameters/Accept" - $ref: "#/components/parameters/AcceptLanguage" - $ref: "#/components/parameters/ContentType" - $ref: "#/components/parameters/CorrelationId" responses: "200": description: Lista de books content: application/vnd.guardia.v1+json: schema: type: object properties: data: $ref: "#/components/schemas/ListOfBooks" pagination: $ref: "#/components/schemas/Pagination" headers: Cache-Control: $ref: "#/components/headers/Cache-Control" Content-Language: $ref: "#/components/headers/Content-Language" Content-Length: $ref: "#/components/headers/Content-Length" Content-Type: $ref: "#/components/headers/Content-Type" Link: $ref: "#/components/headers/Link" Strict-Transport-Security: $ref: "#/components/headers/Strict-Transport-Security" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-RateLimit-Limit: $ref: "#/components/headers/X-RateLimit-Limit" X-RateLimit-Remaining: $ref: "#/components/headers/X-RateLimit-Remaining" X-RateLimit-Reset: $ref: "#/components/headers/X-RateLimit-Reset" "400": $ref: "#/components/responses/Error400" "401": $ref: "#/components/responses/Error401" "403": $ref: "#/components/responses/Error403" "404": $ref: "#/components/responses/Error404" "409": $ref: "#/components/responses/Error409" "422": $ref: "#/components/responses/Error422" "429": $ref: "#/components/responses/Error429" "500": $ref: "#/components/responses/Error500" security: [] x-apidog-folder: Books x-apidog-status: developing x-apidog-maintainer: Fernando Seguim x-run-in-apidog: https://app.apidog.com/web/project/719079/apis/api-14888487-run /v1/ledgers/{ledger_identifier}/books/{book_identifier}: get: summary: Obtém um book específico description: Obtém os detalhes de um book específico usando seu entity_id ou external_entity_id. operationId: get_ledger_book tags: - Books parameters: - $ref: "#/components/parameters/LedgerIdentifierParam" - $ref: "#/components/parameters/BookIdentifierParam" - $ref: "#/components/parameters/Accept" - $ref: "#/components/parameters/AcceptLanguage" - $ref: "#/components/parameters/ContentType" - $ref: "#/components/parameters/CorrelationId" responses: "200": description: Dados do book. content: application/vnd.guardia.v1+json: schema: type: object properties: data: $ref: "#/components/schemas/Book" headers: Cache-Control: $ref: "#/components/headers/Cache-Control" Content-Language: $ref: "#/components/headers/Content-Language" Content-Length: $ref: "#/components/headers/Content-Length" Content-Type: $ref: "#/components/headers/Content-Type" Strict-Transport-Security: $ref: "#/components/headers/Strict-Transport-Security" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-RateLimit-Limit: $ref: "#/components/headers/X-RateLimit-Limit" X-RateLimit-Remaining: $ref: "#/components/headers/X-RateLimit-Remaining" X-RateLimit-Reset: $ref: "#/components/headers/X-RateLimit-Reset" "400": $ref: "#/components/responses/Error400" "401": $ref: "#/components/responses/Error401" "403": $ref: "#/components/responses/Error403" "404": $ref: "#/components/responses/Error404" "409": $ref: "#/components/responses/Error409" "422": $ref: "#/components/responses/Error422" "429": $ref: "#/components/responses/Error429" "500": $ref: "#/components/responses/Error500" security: [] patch: summary: Atualiza um book específico description: | Atualiza os dados como Nome, Natureza, Ativo vinculado e Metadata de um book existente. Se o valor do campo for `null`, o campo não será atualizado.
:::warning Ao atualizar um metadata, quando o valor for `null`, caso a propriedade exista, ela será considerada para remoção, conforme a especificação do Json Merge Patch [RFC 7386](https://datatracker.ietf.org/doc/html/rfc7386). ::: operationId: update_ledger_book tags: - Books parameters: - $ref: "#/components/parameters/LedgerIdentifierParam" - $ref: "#/components/parameters/BookIdentifierParam" - $ref: "#/components/parameters/IdempotencyKey" - $ref: "#/components/parameters/Accept" - $ref: "#/components/parameters/AcceptLanguage" - $ref: "#/components/parameters/ContentType" - $ref: "#/components/parameters/CorrelationId" requestBody: required: true content: application/vnd.guardia.v1+json: schema: $ref: "#/components/schemas/BookUpdateRequest" responses: "200": description: Book atualizado com sucesso. headers: Cache-Control: $ref: "#/components/headers/Cache-Control" Content-Digest: $ref: "#/components/headers/Content-Digest" Content-Language: $ref: "#/components/headers/Content-Language" Content-Length: $ref: "#/components/headers/Content-Length" Content-Type: $ref: "#/components/headers/Content-Type" Idempotency-Key: $ref: "#/components/headers/Idempotency-Key" Last-Modified: $ref: "#/components/headers/Last-Modified" Strict-Transport-Security: $ref: "#/components/headers/Strict-Transport-Security" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-RateLimit-Limit: $ref: "#/components/headers/X-RateLimit-Limit" X-RateLimit-Remaining: $ref: "#/components/headers/X-RateLimit-Remaining" X-RateLimit-Reset: $ref: "#/components/headers/X-RateLimit-Reset" content: application/vnd.guardia.v1+json: schema: type: object properties: data: $ref: "#/components/schemas/Book" "400": $ref: "#/components/responses/Error400" "401": $ref: "#/components/responses/Error401" "403": $ref: "#/components/responses/Error403" "404": $ref: "#/components/responses/Error404" "409": $ref: "#/components/responses/Error409" "422": $ref: "#/components/responses/Error422" "429": $ref: "#/components/responses/Error429" "500": $ref: "#/components/responses/Error500" security: [] delete: summary: Descarta um book específico description: | :::note Se o book possuir transações, o descarte não será permitido. ::: operationId: delete_ledger_book tags: - Books parameters: - $ref: "#/components/parameters/LedgerIdentifierParam" - $ref: "#/components/parameters/BookIdentifierParam" - $ref: "#/components/parameters/Accept" - $ref: "#/components/parameters/AcceptLanguage" - $ref: "#/components/parameters/ContentType" - $ref: "#/components/parameters/CorrelationId" responses: "204": description: Book descartado com sucesso headers: Cache-Control: $ref: "#/components/headers/Cache-Control" Content-Digest: $ref: "#/components/headers/Content-Digest" Content-Language: $ref: "#/components/headers/Content-Language" Content-Length: $ref: "#/components/headers/Content-Length" Content-Type: $ref: "#/components/headers/Content-Type" Last-Modified: $ref: "#/components/headers/Last-Modified" Strict-Transport-Security: $ref: "#/components/headers/Strict-Transport-Security" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-RateLimit-Limit: $ref: "#/components/headers/X-RateLimit-Limit" X-RateLimit-Remaining: $ref: "#/components/headers/X-RateLimit-Remaining" X-RateLimit-Reset: $ref: "#/components/headers/X-RateLimit-Reset" "400": $ref: "#/components/responses/Error400" "401": $ref: "#/components/responses/Error401" "403": $ref: "#/components/responses/Error403" "404": $ref: "#/components/responses/Error404" "409": $ref: "#/components/responses/Error409" "422": $ref: "#/components/responses/Error422" "429": $ref: "#/components/responses/Error429" "500": $ref: "#/components/responses/Error500" security: [] x-apidog-folder: Books x-apidog-status: developing x-apidog-maintainer: Fernando Seguim /v1/ledgers/{ledger_identifier}/books/{book_identifier}/positions: get: summary: Obtém posições de saldo de um book description: | Obtém as positions (posições de saldo) de um book específico com filtros temporais flexíveis. O campo `scope` define o escopo do filtro de referência temporal. - `current`: Retorna a posição de saldo atual do book. **Valor padrão**. - `historical`: Retorna a posição de saldo histórico do book. - `all`: Retorna a posição de saldo atual e histórico do book. Os filtros temporais permitem selecionar o campo de referência temporal e aplicar operadores de comparação: - `filter_by`: Define o campo de referência temporal (created_at, posted_at, reference_at) - `gt`: Maior que a data e hora especificada - `gte`: Maior ou igual à data e hora especificada - `lt`: Menor que a data e hora especificada - `lte`: Menor ou igual à data e hora especificada - `eq`: Igual à data e hora especificada :::note Caso o campo `scope` seja `current`, os filtros temporais não serão aplicados. ::: operationId: list_ledger_book_positions tags: - Positions parameters: - $ref: "#/components/parameters/LedgerIdentifierParam" - $ref: "#/components/parameters/BookIdentifierParam" - $ref: "#/components/parameters/Scope" - $ref: "#/components/parameters/FilterBy" - $ref: "#/components/parameters/GreaterThan" - $ref: "#/components/parameters/GreaterThanOrEqual" - $ref: "#/components/parameters/LessThan" - $ref: "#/components/parameters/LessThanOrEqual" - $ref: "#/components/parameters/Equal" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/PageToken" - $ref: "#/components/parameters/OrderBy" - $ref: "#/components/parameters/Sort" - $ref: "#/components/parameters/Accept" - $ref: "#/components/parameters/AcceptLanguage" - $ref: "#/components/parameters/ContentType" - $ref: "#/components/parameters/CorrelationId" responses: "200": description: Lista de posições de saldo do book content: application/vnd.guardia.v1+json: schema: type: object properties: data: $ref: "#/components/schemas/ListOfPositions" pagination: $ref: "#/components/schemas/Pagination" headers: Cache-Control: $ref: "#/components/headers/Cache-Control" Content-Language: $ref: "#/components/headers/Content-Language" Content-Length: $ref: "#/components/headers/Content-Length" Content-Type: $ref: "#/components/headers/Content-Type" Link: $ref: "#/components/headers/Link" Strict-Transport-Security: $ref: "#/components/headers/Strict-Transport-Security" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-RateLimit-Limit: $ref: "#/components/headers/X-RateLimit-Limit" X-RateLimit-Remaining: $ref: "#/components/headers/X-RateLimit-Remaining" X-RateLimit-Reset: $ref: "#/components/headers/X-RateLimit-Reset" "400": $ref: "#/components/responses/Error400" "401": $ref: "#/components/responses/Error401" "403": $ref: "#/components/responses/Error403" "404": $ref: "#/components/responses/Error404" "409": $ref: "#/components/responses/Error409" "422": $ref: "#/components/responses/Error422" "429": $ref: "#/components/responses/Error429" "500": $ref: "#/components/responses/Error500" security: [] components: parameters: $ref: "#/components/parameters" IdempotencyKey: name: Idempotency-Key in: header description: Chave para garantir idempotência da requisição. required: true schema: type: string format: uuid Accept: name: Accept in: header description: | Tipo de contrato esperado na resposta da API. O valor padrão é `application/vnd.guardia.v1+json` ou a versao mais recente. required: false example: application/vnd.guardia.v1+json schema: type: string AcceptLanguage: name: Accept-Language in: header description: | O idioma em que a API deve retornar as mensagens de erro. Use `en` para inglês americano, `es` para espanhol ou `pt-BR` para português brasileiro. O valor padrão é `en`. required: false example: en schema: type: string ContentType: name: Content-Type in: header description: | Tipo de contrato enviado na requisição para a API. O valor padrão é `application/vnd.guardia.v1+json` ou a versao mais recente. required: false example: application/vnd.guardia.v1+json schema: type: string CorrelationId: name: X-Grd-Correlation-Id in: header description: Identificador de correlação para rastreamento distribuído. required: false schema: type: string format: uuid LedgerIdentifierParam: name: ledger_identifier in: path description: | Identificador único `entity_id` da ledger no formato UUIDv7. Alternativamente pode ser utilizado o `external_entity_id`. required: true schema: $ref: "#/components/schemas/EntityID" AssetIdentifierParam: name: asset_identifier in: path description: | Identificador único `entity_id` do asset no formato UUIDv7. Alternativamente pode ser utilizado o `external_entity_id`. required: true schema: $ref: "#/components/schemas/EntityID" BookIdentifierParam: name: book_identifier in: path description: | Identificador único `entity_id` do book no formato UUIDv7. Alternativamente pode ser utilizado o `external_entity_id`. required: true schema: $ref: "#/components/schemas/EntityID" ChapterIdentifierParam: name: chapter_identifier in: path description: | Identificador único `entity_id` da chapter no formato UUIDv7. Alternativamente pode ser utilizado o `external_entity_id`. required: true schema: $ref: "#/components/schemas/EntityID" PageSize: name: page_size in: query description: Número de itens por página. Máximo de 100 itens. required: false example: 20 schema: type: integer minimum: 1 maximum: 100 default: 20 PageToken: name: page_token in: query description: Token opaco que identifica a página atual. required: false schema: type: string OrderBy: name: order_by in: query description: Campo usado para ordenação dos resultados. Apenas campos temporais são permitidos. required: false schema: type: string enum: - created_at - updated_at - posted_at - reference_at default: created_at Sort: name: sort in: query description: Direção da ordenação. Aceita 'asc' ou 'desc' (case insensitive). required: false schema: type: string enum: - asc - desc default: asc IncludeDiscarded: name: include_discarded in: query description: | Incluir os itens descartados no resultado da busca. O valor padrão é `false`. required: false example: "false" schema: type: string MetadataFilter: name: $metadata.key in: query description: | Se você deseja listar os itens com uma metadata cuja chave seja `foo` e o valor seja `bar`, a consulta seria `$metadata.foo=bar`. required: false example: value schema: type: string ListOfEntityIds: name: entity_ids in: query description: | Uma lista de IDs de entidades no formato UUIDv7 separados por vírgulas. Ex.: `entity_ids={entity_type:entity_id},{entity_type:entity_id},{entity_type:entity_id}`. Espaços em branco entre as vírgulas serão ignorados. required: false example: "{entity_type}:018f74a6e3b270ccbf248a4b012f5f3e,{entity_type}:018f74a6e3b270ccbf248a4b012f5f3f,{entity_type}:018f74a6e3b270ccbf248a4b012f5f40" schema: type: string pattern: ^([0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12},)*[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ ListOfExternalEntityIds: name: external_entity_ids in: query description: | Uma lista de IDs externos de entidades separados por vírgulas. Ex.: `external_entity_ids={ext:external_entity_id},{ext:external_entity_id},{ext:external_entity_id}`. Espaços em branco entre as vírgulas serão ignorados. required: false example: ext:123-456-789-ABCD,ext:456-789-ABCD-EFGH,ext:789-ABCD-EFGH-IJKL schema: type: string ListOfDenominationCodes: name: denomination_codes in: query description: | Uma lista de códigos de denominações separados por vírgulas. Este código pode ser baseado em especificações como ISO 4217, ISO 10962, MIC, ISIN ou um padrão interno da instituição, conforme definido na criação do asset. required: false example: BRL,USD,EUR schema: type: string ListOfDenominationNumbers: name: denomination_numbers in: query description: | Uma lista de números de identificação de denominações separados por vírgulas. Este número pode ser baseado em especificações como ISO 4217, ISO 10962, MIC, ISIN ou um padrão interno da instituição, conforme definido na criação do asset. required: false example: 986,840,978 schema: type: string ListOfLedgerIds: name: entity_ids in: query description: | Uma lista de identificadores `entity_id` de ledgers separados por vírgulas. Ex.: `entity_ids={ledger:entity_id},{ledger:entity_id},{ledger:entity_id}`. Espaços em branco entre as vírgulas serão ignorados. required: false schema: $ref: "#/components/schemas/EntityID" ListOfAssetIds: name: entity_ids in: query description: | Uma lista de identificadores `entity_id` de assets separados por vírgulas. Ex.: `entity_ids={asset:entity_id},{asset:entity_id},{asset:entity_id}`. Espaços em branco entre as vírgulas serão ignorados. required: false schema: $ref: "#/components/schemas/EntityID" ListOfChapterIds: name: entity_ids in: query description: | Uma lista de identificadores `entity_id` de chapters separados por vírgulas. Ex.: `entity_ids={chapter:entity_id},{chapter:entity_id},{chapter:entity_id}`. Espaços em branco entre as vírgulas serão ignorados. required: false schema: $ref: "#/components/schemas/EntityID" Scope: name: scope in: query description: | Define o escopo do filtro de referência temporal. required: false schema: type: string enum: - current - historical - all default: current example: current FilterBy: name: filter_by in: query description: | Define qual será a base do filtro de referência temporal. Deve ser utilizado em conjunto com os operadores de comparação (gt, gte, lt, lte). required: false schema: type: string enum: - created_at - posted_at - reference_at default: created_at example: posted_at GreaterThan: name: gt in: query description: | Filtro de data e hora maior que a data e hora especificada. Utilizado em conjunto com o parâmetro `filter_by`. Formato: Data e hora no formato ISO 8601 / RFC 3339 (UTC). required: false schema: type: string format: date-time example: 2025-01-01T00:00:00Z GreaterThanOrEqual: name: gte in: query description: | Filtro de data e hora maior ou igual à data e hora especificada. Utilizado em conjunto com o parâmetro `filter_by`. Formato: Data e hora no formato ISO 8601 / RFC 3339 (UTC). required: false schema: type: string format: date-time example: 2025-01-01T00:00:00Z LessThan: name: lt in: query description: | Filtro de data e hora menor que a data e hora especificada. Utilizado em conjunto com o parâmetro `filter_by`. Formato: Data e hora no formato ISO 8601 / RFC 3339 (UTC). required: false schema: type: string format: date-time example: 2025-12-31T23:59:59Z LessThanOrEqual: name: lte in: query description: | Filtro de data e hora menor ou igual à data e hora especificada. Utilizado em conjunto com o parâmetro `filter_by`. Formato: Data e hora no formato ISO 8601 / RFC 3339 (UTC). required: false schema: type: string format: date-time example: 2025-12-31T23:59:59Z Equal: name: eq in: query description: | Filtro de data e hora igual à data e hora especificada. Utilizado em conjunto com o parâmetro `filter_by`. Formato: Data e hora no formato ISO 8601 / RFC 3339 (UTC). required: false schema: type: string format: date-time example: 2025-12-31T23:59:59Z headers: $ref: "#/components/headers" X-Grd-Trace-Id: description: Identificador único da requisição gerado pela infraestrutura Guardia. schema: type: string format: uuid example: 018f74a6e3b270ccbf248a4b012f5f3e required: true X-Grd-Correlation-Id: description: Identificador de correlação para rastreamento distribuído. schema: type: string format: uuid example: 018f74a6e3b270ccbf248a4b012f5f3e required: true X-Grd-Debug: description: Habilita informações estendidas de debug no payload da resposta. schema: type: boolean example: true required: false Content-Type: description: Tipo de contrato retornado. schema: type: string example: application/vnd.guardia.v1+json required: true Content-Length: description: Indica o tamanho, em bytes, do corpo da resposta retornado pela API. schema: type: string example: required: true Content-Language: description: O idioma em que a API retorna as mensagens de erro. Use en para inglês americano, es para espanhol ou pt-BR para português brasileiro. schema: type: string example: en required: true Cache-Control: description: Controla o comportamento de cache para respostas HTTP. Deve ser 'no-store' para dados sensíveis. Deve ser 'public' para respostas de sucesso sem dados sensíveis que podem ser compartilhadas, ou 'private' para respostas de sucesso sem dados sensíveis que não podem ser compartilhadas, seguido da diretiva 'max-age' determinando o tempo máximo de cache em segundos. schema: type: string example: public, max-age=900 required: true Link: description: Fornece links de navegação HATEOAS para paginação. schema: type: string example: | ; rel="first", ; rel="previous", ; rel="next", ; rel="last" required: false Content-Digest: description: Hash do payload usado para garantir integridade em requisições idempotentes. schema: type: string example: sha-256= required: true Idempotency-Key: description: Chave para garantir idempotência da requisição. schema: type: string example: 018f74a6e3b270ccbf248a4b012f5f3e required: true Last-Modified: description: Indica a última data de modificação de uma entidade. schema: type: string format: date-time example: Wed, 21 Oct 2015 07:28:00 GMT required: true Retry-After: description: Informa quanto tempo (em segundos) o cliente deve esperar antes de tentar novamente após um erro 429. schema: type: integer minimum: 1 example: 60 required: true X-RateLimit-Limit: description: Cota de requisições por segundos por cliente (org id + tenant id). schema: type: integer example: 30 required: true X-RateLimit-Remaining: description: Cota de requisições restantes no mesmo segundo. schema: type: integer example: 10 required: true X-RateLimit-Reset: description: Tempo restante em segundos para a próxima requisição. schema: type: integer example: 60 required: true Strict-Transport-Security: description: Indica que o navegador deve acessar o site apenas por HTTPS. schema: type: string example: max-age=31536000; includeSubDomains required: true schemas: $ref: "#/components/schemas" UUID: type: string format: uuid description: Identificador único universal no formato UUID. pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ UUIDv7: type: string format: uuid description: Identificador único universal no formato UUIDv7 (RFC 9562). pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ Ledger: type: object properties: entity_id: $ref: "#/components/schemas/EntityID" entity_type: type: string enum: - LEDGER external_entity_id: $ref: "#/components/schemas/ExternalEntityID" version: $ref: "#/components/schemas/Version" name: type: string description: O nome único e personalizado da ledger. Mínimo de 3 caractere e Máximo de 256 caracteres. minLength: 3 maxLength: 128 description: type: string description: Uma descrição personalizada da ledger. Mínimo de 3 caracteres e Máximo de 256 caracteres. minLength: 3 maxLength: 256 created_at: $ref: "#/components/schemas/DateTime" nullable: false updated_at: $ref: "#/components/schemas/DateTime" nullable: false discarded_at: $ref: "#/components/schemas/DateTime" nullable: true metadata: $ref: "#/components/schemas/Metadata" Chapter: type: object properties: entity_id: $ref: "#/components/schemas/EntityID" entity_type: type: string enum: - CHAPTER external_entity_id: $ref: "#/components/schemas/ExternalEntityID" version: $ref: "#/components/schemas/Version" name: type: string description: type: string nullable: true ledger_entity_id: $ref: "#/components/schemas/EntityID" description: | Identificador único da ledger associada ao chapter. created_at: $ref: "#/components/schemas/DateTime" nullable: false updated_at: $ref: "#/components/schemas/DateTime" nullable: false discarded_at: $ref: "#/components/schemas/DateTime" nullable: true metadata: $ref: "#/components/schemas/Metadata" Asset: type: object properties: entity_id: $ref: "#/components/schemas/EntityID" entity_type: type: string enum: - ASSET external_entity_id: $ref: "#/components/schemas/ExternalEntityID" version: $ref: "#/components/schemas/Version" classification: $ref: "#/components/schemas/Classification" denomination: $ref: "#/components/schemas/Denomination" created_at: $ref: "#/components/schemas/DateTime" nullable: false updated_at: $ref: "#/components/schemas/DateTime" nullable: false discarded_at: $ref: "#/components/schemas/DateTime" nullable: true metadata: $ref: "#/components/schemas/Metadata" Classification: type: string enum: - FIAT - NON_FIAT Denomination: type: object properties: code: type: string description: Código de denominação do asset. Pode ser um código ISO 4217, ISO 10962, MIC, ISIN ou um padrão interno da instituição. minLength: 3 maxLength: 12 default: BRL number: type: string description: Número de denominação do asset. Pode ser um número ISO 4217, ISO 10962, MIC, ISIN ou um padrão interno da instituição. minLength: 3 maxLength: 128 default: "968" exponent: type: integer description: Expoente de denominação do asset, que indica o número de casas decimais a ser usado em representações contábeis. Deve estar entre 0 e 18. minimum: 0 maximum: 18 default: 2 BoundAsset: type: object description: Representa a associação entre um ledger e um asset, incluindo informações específicas do vínculo. properties: ledger_entity_id: $ref: "#/components/schemas/EntityID" description: Identificador único do ledger. asset_entity_id: $ref: "#/components/schemas/EntityID" description: Identificador único do asset. version: $ref: "#/components/schemas/Version" denomination: $ref: "#/components/schemas/Denomination" bound_date: $ref: "#/components/schemas/DateTime" description: Data e hora em que o asset foi vinculado ao ledger. Metadata: type: object description: Os metadados a serem adicionados à entidade devem ser fornecidos como pares de chave-valor em um formato de objeto JSON, com chave e valor como strings. O tamanho maximo do objeto deve ser 1MB. additionalProperties: type: string maxProperties: 10 example: foo: bar DateTime: type: string description: Data e hora no formato no formato ISO 8601 / RFC 3339 (UTC). format: date-time pattern: ^(?[0-9]{4})-?(?1[0-2]|0[1-9])-?(?3[01]|0[1-9]|[12][0-9])T(?2[0-3]|[01][0-9]):?(?[0-5][0-9]):?(?[0-5][0-9])(?:\.(?[0-9]{1,9}))?Z$ Error: type: object properties: code: type: string description: "O codigo do erro. Ex.: ERR400_INVALID_PARAMETER." reason: type: string description: "O movito do erro, quando conhecido. Ex.: INVALID_ENTITY_ID_FORMAT." message: type: string description: A mensagem que descreve o erro. required: - code - reason - message Errors: type: array description: Lista de erros retornados pela API. Cada erro contém um código, motivo e mensagem descritiva. items: $ref: "#/components/schemas/Error" example: - code: ERR400_INVALID_PARAMETER reason: INVALID_ENTITY_ID_FORMAT message: O parâmetro 'entity_id' é inválido. Deve ser um UUIDv7 válido. - code: ERR400_INVALID_PARAMETER reason: INVALID_EXTERNAL_ENTITY_ID_LENGTH message: O campo 'external_entity_id' deve ter até 36 caracteres. Version: type: integer minimum: 0 maximum: 128 default: 0 EntityID: type: string description: Identificador único da entidade no formato `{entity_type}:{uuid_v7}`. pattern: ^([a-zA-Z_-]+:[0-9a-f]{8}[0-9a-f]{4}7[0-9a-f]{3}[89ab][0-9a-f]{3}[0-9a-f]{12})$ example: "{entity_type}:018f74a6e3b270ccbf248a4b012f5f3e" ExternalEntityID: type: string description: Identificador externo da entidade para interoperabilidade com outros sistemas. minLength: 1 maxLength: 36 example: ext:123-456-789-ABCD nullable: true EntityIdentifier: type: string description: | Identificador da entidade que aceita tanto `entity_id` quanto `external_entity_id`. - **entity_id**: Formato `{entity_type}:{uuid_v7}` (ex: `ledger:018f74a6-e3b2-70cc-bf24-8a4b012f5f3e`) - **external_entity_id**: Formato `ext:{valor}` (ex: `ext:123-456-789-ABCD`) pattern: ^(([a-zA-Z_-]+:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})|(ext:[a-zA-Z0-9_-]{1,32}))$ example: "{entity_type}:018f74a6e3b270ccbf248a4b012f5f3e" ErrorsResponse: type: object properties: errors: $ref: "#/components/schemas/Errors" description: Lista de erros. reference: type: string description: Link para a documentação. format: uri required: - errors - reference Debug: type: object properties: trace_id: type: string description: Identificador único da requisição. correlation_id: type: string description: Identificador de correlação para rastreamento distribuído. instance: type: string description: Identificador da instância que processou a requisição. timestamp: type: string description: Timestamp UNIX de quando a requisição foi recebida. duration: type: string description: Tempo total de processamento da requisição em milissegundos. memory: type: string description: Memória utilizada para processar a requisição em bytes. query: type: string description: Query string da requisição, se disponível. params: type: string description: Parâmetros de rota utilizados, se houver. external_ip: type: string description: IP externo da requisição do cliente. Pagination: type: object properties: page_size: type: integer description: Número de itens retornados na página atual. total_count: type: integer description: Número total de registros para a consulta original. next_page_token: type: string description: Token para recuperar a próxima página. previous_page_token: type: string description: Token para recuperar a página anterior. first_page_token: type: string description: Token representando a primeira página do conjunto de dados. last_page_token: type: string description: Token para ir para a última página. ListOfLedgers: type: array items: $ref: "#/components/schemas/Ledger" ListOfChapters: type: array items: $ref: "#/components/schemas/Chapter" ListOfAssets: type: array items: $ref: "#/components/schemas/Asset" ListOfBooks: type: array items: $ref: "#/components/schemas/Book" ListOfPositions: type: array items: $ref: "#/components/schemas/Position" ListOfEntityIDs: type: array items: $ref: "#/components/schemas/EntityID" LedgerCreateRequest: type: object properties: external_entity_id: $ref: "#/components/schemas/ExternalEntityID" name: type: string minLength: 3 maxLength: 128 description: type: string minLength: 3 maxLength: 256 metadata: $ref: "#/components/schemas/Metadata" required: - name LedgerUpdateRequest: type: object properties: external_entity_id: $ref: "#/components/schemas/ExternalEntityID" name: type: string minLength: 3 maxLength: 128 description: type: string minLength: 3 maxLength: 256 metadata: $ref: "#/components/schemas/Metadata" ChapterCreateRequest: type: object properties: external_entity_id: $ref: "#/components/schemas/ExternalEntityID" name: type: string description: type: string metadata: $ref: "#/components/schemas/Metadata" required: - name ChapterUpdateRequest: type: object properties: name: type: string description: type: string metadata: $ref: "#/components/schemas/Metadata" AssetCreateRequest: type: object properties: external_entity_id: $ref: "#/components/schemas/ExternalEntityID" name: type: string minLength: 3 maxLength: 128 classification: $ref: "#/components/schemas/Classification" denomination: $ref: "#/components/schemas/Denomination" metadata: $ref: "#/components/schemas/Metadata" required: - name - denomination - classification - metadata AssetUpdateRequest: type: object properties: denomination: $ref: "#/components/schemas/Denomination" classification: $ref: "#/components/schemas/Classification" metadata: $ref: "#/components/schemas/Metadata" Book: type: object properties: entity_id: $ref: "#/components/schemas/EntityID" entity_type: type: string enum: - BOOK external_entity_id: $ref: "#/components/schemas/ExternalEntityID" version: $ref: "#/components/schemas/Version" name: type: string minLength: 3 maxLength: 128 description: Nome único do book dentro do ledger. ledger_entity_id: $ref: "#/components/schemas/EntityID" description: UUIDv7 do ledger ao qual o book pertence. nature: type: string enum: - CREDITOR - DEBITOR description: Natureza do book. created_at: $ref: "#/components/schemas/DateTime" nullable: false updated_at: $ref: "#/components/schemas/DateTime" nullable: false discarded_at: $ref: "#/components/schemas/DateTime" nullable: true metadata: $ref: "#/components/schemas/Metadata" Balance: type: object description: Representa um saldo financeiro em uma position. properties: amount: type: integer description: Valor do saldo em centavos. example: 0 credits: type: integer description: Total de creditos da posicao de saldo. example: 0 debits: type: integer description: Total de debitos da posicao de saldo. example: 0 required: - amount - credits - debits Position: type: object description: | Representa a posição de saldo de um **book** dentro do **ledger**. Inicializada automaticamente com valor zero quando um book é criado. properties: entity_type: type: string enum: - POSITION version: $ref: "#/components/schemas/Version" book_entity_id: $ref: "#/components/schemas/EntityID" description: Identificador único `entity_id` do **book** no formato UUIDv7. asset_entity_id: $ref: "#/components/schemas/EntityID" description: Identificador único `entity_id` do **asset** no formato UUIDv7. reference_at: $ref: "#/components/schemas/DateTime" description: Data e hora de referência da posição de saldo. Quando não informada durante uma transação, será a data de criação da transação. entry_reference: $ref: "#/components/schemas/EntityIdentifier" description: Identificador do último lançamento que atualizou a posição do saldo. É nulo quando a posição do saldo é inicializada. nullable: true posted: $ref: "#/components/schemas/Balance" description: Posição do saldo lançado. confirmable: $ref: "#/components/schemas/Balance" description: Posição do saldo a ser confirmado. provisioned: $ref: "#/components/schemas/Balance" description: Posição do saldo provisionado (lançado e a ser confirmado). available: $ref: "#/components/schemas/Balance" description: Posição do saldo disponível. created_at: $ref: "#/components/schemas/DateTime" updated_at: $ref: "#/components/schemas/DateTime" required: - entity_id - entity_type - reference_at - posted - confirmable - provisioned - available - asset_entity_id - created_at - updated_at BookCreateRequest: type: object properties: external_entity_id: $ref: "#/components/schemas/ExternalEntityID" code: type: string description: | Código único de identificação do book. Pode seguir padrões como IFRS COA, COSIF, GAAP ou uma convenção interna da instituição. Utilizado para estruturar o plano de contas e facilitar classificações contábeis. Quando não informado, será usado o EntityID do book. minLength: 1 maxLength: 128 example: 1.1.2.01.0001 name: type: string description: Nome único do book dentro do ledger. minLength: 3 maxLength: 128 nature: type: string description: Define se o book é um credor ou devedor. enum: - CREDITOR - DEBITOR asset_identifier: $ref: "#/components/schemas/EntityIdentifier" description: Identificador único `entity_id` do **asset** no formato UUIDv7. Alternativamente pode ser utilizado o `external_entity_id`. metadata: $ref: "#/components/schemas/Metadata" required: - code - name - nature - asset_identifier BookUpdateRequest: type: object properties: external_entity_id: $ref: "#/components/schemas/ExternalEntityID" name: type: string minLength: 3 maxLength: 128 nullable: true nature: type: string enum: - CREDITOR - DEBITOR nullable: true asset_identifier: $ref: "#/components/schemas/EntityIdentifier" description: Identificador único `entity_id` do **asset** no formato UUIDv7. Alternativamente pode ser utilizado o `external_entity_id`. nullable: true metadata: $ref: "#/components/schemas/Metadata" nullable: true responses: $ref: "#/components/responses" Error400: description: Requisição inválida. headers: X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" content: application/vnd.guardia.v1+json: schema: $ref: "#/components/schemas/ErrorsResponse" Error401: description: Não autorizado. headers: X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" content: application/vnd.guardia.v1+json: schema: $ref: "#/components/schemas/ErrorsResponse" Error403: description: Acesso proibido. headers: X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" content: application/vnd.guardia.v1+json: schema: $ref: "#/components/schemas/ErrorsResponse" Error404: description: Recurso não encontrado. headers: X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" content: application/vnd.guardia.v1+json: schema: $ref: "#/components/schemas/ErrorsResponse" Error409: description: Conflito. headers: X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" content: application/vnd.guardia.v1+json: schema: $ref: "#/components/schemas/ErrorsResponse" Error422: description: Entidade não processável. headers: X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" content: application/vnd.guardia.v1+json: schema: $ref: "#/components/schemas/ErrorsResponse" Error429: description: Muitas requisições. headers: X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/vnd.guardia.v1+json: schema: $ref: "#/components/schemas/ErrorsResponse" Error500: description: Erro interno do servidor. headers: X-Grd-Trace-Id: $ref: "#/components/headers/X-Grd-Trace-Id" X-Grd-Correlation-Id: $ref: "#/components/headers/X-Grd-Correlation-Id" content: application/vnd.guardia.v1+json: schema: $ref: "#/components/schemas/ErrorsResponse"