From 0d9ca311c0a3a02418fa0cb187ac12c3d89a9feb Mon Sep 17 00:00:00 2001 From: Leoni Sandes Date: Mon, 11 May 2026 11:10:29 -0300 Subject: [PATCH 1/2] docs(api): sync fx-account spec with web source MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aligns apis/fx-account/openapi.yml with the live request/response shapes exposed by fx-account's /api channel: - POST /api/accounts: drop AssetRequest.isVirtual (not in source); add CompanyOwnerRequest.isStartup; rewire industry to a shared Industry schema regenerated from IndustryV2 (87 values). - POST/PATCH /api/accounts/{id}/ubos: add phone, email, and isLegalRepresentative to UBORequest, UpdateUBORequest, and UBOResponse. - GET /api/accounts/{id}/ubos: drop spurious pagination/filter params; response is a plain array, not a paginated envelope. - GET /api/accounts/{id}/fundingInstructions: drop pagination/filter params, add asset and rail query filters, response is a plain array. FundingInstructionResponse now uses type as discriminator, exposes both type and rail fields, and includes the missing PIX_BANK_INSTRUCTION variant. - Remove the /api/accounts/{id}/balances endpoint and associated schemas/examples/navigation entry — the route does not exist in fx-account. - Rewrite RequirementResponse as a oneOf with five concrete variants (ACCOUNT_DOCUMENT, UBO_DOCUMENT, IDENTITY_VERIFICATION, ACCOUNT_FIELD, UBO_FIELD) matching the sealed class hierarchy. - AssetResponse.asset renamed to currency to match the wire format. - Extend DocumentType with KYC_FORM, BAAS_ADHESION_FORM, PJ_PARTNER_DOCUMENTS, PJ_PARTNER_FINANCIAL_STATEMENT, and SIGNING_AUTHORITY_PROOF. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../fx-account/balances/get-balance.mdx | 5 - apis/fx-account/openapi.yml | 652 +++++++++++------- docs.json | 7 - 3 files changed, 385 insertions(+), 279 deletions(-) delete mode 100644 api-reference/fx-account/balances/get-balance.mdx diff --git a/api-reference/fx-account/balances/get-balance.mdx b/api-reference/fx-account/balances/get-balance.mdx deleted file mode 100644 index ac09bd2..0000000 --- a/api-reference/fx-account/balances/get-balance.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Get account balance" -description: "Retrieves the multi-currency balance for an account." -openapi: "apis/fx-account/openapi.yml GET /api/accounts/{accountId}/balances" ---- diff --git a/apis/fx-account/openapi.yml b/apis/fx-account/openapi.yml index 911b11c..a8df621 100644 --- a/apis/fx-account/openapi.yml +++ b/apis/fx-account/openapi.yml @@ -17,8 +17,6 @@ tags: description: Upload documents to fulfill account and UBO requirements. - name: Funding instructions description: Retrieve funding instructions for depositing into an account. - - name: Balances - description: Retrieve fiat and crypto balances for an account. components: securitySchemes: bearerAuth: @@ -136,13 +134,8 @@ components: properties: code: $ref: "#/components/schemas/Asset" - isVirtual: - type: boolean - description: Whether this is a virtual (non-custodial) asset. - example: false required: - code - - isVirtual OwnerRequest: description: The legal entity that owns the account. Discriminated by `type`. oneOf: @@ -168,46 +161,19 @@ components: taxId: $ref: "#/components/schemas/TaxIdRequest" industry: - type: string - description: Industry classification. - enum: - - ACCOUNTING - - ADVERTISING__MARKETING - - AEROSPACE__DEFENSE - - AGRICULTURE__FORESTRY - - AMUSEMENT_AND_RECREATION - - AUTOMOTIVE - - CONSTRUCTION__CARPENTRY__LANDSCAPING - - CUSTOMER_SERVICE_AND_SUPPORT - - EDUCATION - - ENERGY - - ENGINEERING - - FINANCIAL_SERVICES - - HEALTHCARE__MEDICAL_SERVICES - - HOTEL__HOSPITALITY - - INFORMATION_TECHNOLOGY - - MANUFACTURING - - MEDIA__ENTERTAINMENT - - MINING_OIL_AND_GAS - - NON_PROFIT__NGO__CHARITY - - PHARMACEUTICALS - - PRINTING__PUBLISHING - - REAL_ESTATE - - RESTAURANT__FOOD_SERVICE - - RETAIL_SALES__RETAIL_TRADE - - SECURITY - - TRANSPORTATION - - TRAVEL - - UTILITIES - - WHOLESALE - - OTHERS - example: "INFORMATION_TECHNOLOGY" + $ref: "#/components/schemas/Industry" incorporateDate: type: string format: date nullable: true description: Company incorporation date in ISO format (yyyy-MM-dd). Optional. example: "2018-05-12" + isStartup: + type: boolean + nullable: true + default: false + description: Whether the company is a startup. Optional. + example: false address: $ref: "#/components/schemas/AddressRequest" required: @@ -300,16 +266,33 @@ components: $ref: "#/components/schemas/TaxIdRequest" address: $ref: "#/components/schemas/AddressRequest" + phone: + type: string + description: Contact phone number with country code. + example: "5511999999999" + email: + type: string + format: email + description: Contact email address. + example: "joao.silva@example.com" ownershipPercentage: type: number format: double nullable: true description: Percentage of ownership. Optional. example: 50.0 + isLegalRepresentative: + type: boolean + nullable: true + default: false + description: Whether this beneficial owner is the legal representative of the account. + example: false required: - name - taxId - address + - phone + - email UpdateUBORequest: type: object description: Request body for updating a beneficial owner. All fields are optional (patch semantics). @@ -322,12 +305,26 @@ components: $ref: "#/components/schemas/TaxIdRequest" address: $ref: "#/components/schemas/AddressRequest" + phone: + type: string + description: Contact phone number with country code. + example: "5511999999999" + email: + type: string + format: email + description: Contact email address. + example: "joao.silva@example.com" ownershipPercentage: type: number format: double nullable: true description: Percentage of ownership. example: 75.0 + isLegalRepresentative: + type: boolean + nullable: true + description: Whether this beneficial owner is the legal representative of the account. + example: false # ── Response schemas ───────────────────────────────────────────── AccountResponse: @@ -413,7 +410,7 @@ components: type: object description: An asset available on the account and the onboarding status of its underlying provider account. properties: - asset: + currency: $ref: "#/components/schemas/Asset" allowsVirtualAccounts: type: boolean @@ -431,7 +428,7 @@ components: example: "ONBOARDING" readOnly: true required: - - asset + - currency - allowsVirtualAccounts - status AmountResponse: @@ -456,47 +453,6 @@ components: - value - asset - decimals - BalanceEntryResponse: - type: object - description: > - A single balance entry for one asset. When `synced` is `false`, the - upstream provider was unreachable and `amount` is omitted; the customer - should retry or fall back to a previously cached value. - properties: - amount: - allOf: - - $ref: "#/components/schemas/AmountResponse" - nullable: true - description: The available balance. Null when `synced` is `false`. - synced: - type: boolean - description: Whether the balance was successfully retrieved from the underlying provider. - example: true - required: - - synced - BalanceResponse: - type: object - description: Multi-currency balance grouped by asset class. - properties: - accountId: - type: string - format: uuid - description: Identifier of the account these balances belong to. - example: "5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c" - fiat: - type: array - description: Fiat balances, one entry per enabled fiat currency. - items: - $ref: "#/components/schemas/BalanceEntryResponse" - crypto: - type: array - description: Crypto balances, one entry per enabled crypto currency. - items: - $ref: "#/components/schemas/BalanceEntryResponse" - required: - - accountId - - fiat - - crypto CustomerResponse: type: object properties: @@ -531,8 +487,7 @@ components: taxId: $ref: "#/components/schemas/TaxIdResponse" industry: - type: string - example: "INFORMATION_TECHNOLOGY" + $ref: "#/components/schemas/Industry" address: $ref: "#/components/schemas/AddressResponse" ubos: @@ -704,24 +659,40 @@ components: - errors - satisfied RequirementResponse: - type: object description: | - A single requirement. The `type` discriminates between two shapes: - - `DOCUMENT`: a specific document of a given `documentType` is required. - - `DOCUMENT_GROUP`: any one document from `options` will satisfy the requirement (e.g., proof of identity can be ID card, passport, or driver's license). + A single requirement. The `type` field discriminates between five + shapes: + + - `ACCOUNT_DOCUMENT`: a specific document is required at the account level. + - `UBO_DOCUMENT`: a specific document is required for a beneficial owner. + - `IDENTITY_VERIFICATION`: any one document from `options` satisfies an identity verification requirement. + - `ACCOUNT_FIELD`: an account-level field was rejected during review. + - `UBO_FIELD`: a UBO field was rejected during review. + oneOf: + - $ref: "#/components/schemas/AccountDocumentRequirement" + - $ref: "#/components/schemas/UboDocumentRequirement" + - $ref: "#/components/schemas/IdentityVerificationRequirement" + - $ref: "#/components/schemas/AccountFieldRejection" + - $ref: "#/components/schemas/UboFieldRejection" + discriminator: + propertyName: type + mapping: + ACCOUNT_DOCUMENT: "#/components/schemas/AccountDocumentRequirement" + UBO_DOCUMENT: "#/components/schemas/UboDocumentRequirement" + IDENTITY_VERIFICATION: "#/components/schemas/IdentityVerificationRequirement" + ACCOUNT_FIELD: "#/components/schemas/AccountFieldRejection" + UBO_FIELD: "#/components/schemas/UboFieldRejection" + AccountDocumentRequirement: + title: Account document + type: object + description: A document required at the account level. properties: type: type: string - description: Requirement type discriminator. enum: - - DOCUMENT - - DOCUMENT_GROUP - example: "DOCUMENT" + - ACCOUNT_DOCUMENT documentType: - allOf: - - $ref: "#/components/schemas/DocumentType" - nullable: true - description: The specific document type required. Set when `type` is `DOCUMENT`. + $ref: "#/components/schemas/DocumentType" documentSubType: allOf: - $ref: "#/components/schemas/DocumentSubType" @@ -729,26 +700,49 @@ components: description: > Sub-classification of the document. Set when the `documentType` requires a specific side (e.g., `FRONT_SIDE` for `ID_CARD`). - group: - allOf: - - $ref: "#/components/schemas/RequirementGroup" - nullable: true - description: Group identifier. Set when `type` is `DOCUMENT_GROUP`. - options: + requiredMetadata: type: array nullable: true - description: Acceptable document types. Set when `type` is `DOCUMENT_GROUP`. + description: Metadata keys that must accompany the document upload (e.g., `country`, `number`). items: - $ref: "#/components/schemas/DocumentType" + type: string + example: ["country"] + metadata: + type: object + nullable: true + additionalProperties: + type: string + description: Metadata captured for an already-fulfilled requirement. + reason: + $ref: "#/components/schemas/Reason" + required: + - type + - documentType + UboDocumentRequirement: + title: UBO document + type: object + description: A document required for a specific beneficial owner. + properties: + type: + type: string + enum: + - UBO_DOCUMENT + documentType: + $ref: "#/components/schemas/DocumentType" + documentSubType: + allOf: + - $ref: "#/components/schemas/DocumentSubType" + nullable: true + description: Sub-classification of the document. uboId: type: string format: uuid - nullable: true - description: UBO identifier when the requirement belongs to a beneficial owner. `null` for account-level requirements. + description: Identifier of the beneficial owner this document belongs to. + example: "a1b2c3d4-e5f6-7890-1234-567890abcdef" requiredMetadata: type: array nullable: true - description: Metadata keys that must accompany the document upload (e.g., `country`, `number`). + description: Metadata keys that must accompany the document upload. items: type: string example: ["country"] @@ -762,6 +756,71 @@ components: $ref: "#/components/schemas/Reason" required: - type + - documentType + - uboId + IdentityVerificationRequirement: + title: Identity verification + type: object + description: > + A grouped requirement satisfied by any one of the document types listed + in `options` (e.g., identity verification can be fulfilled with an + `ID_CARD`, `PASSPORT`, or `DRIVER_LICENSE`). + properties: + type: + type: string + enum: + - IDENTITY_VERIFICATION + options: + type: array + description: Acceptable document types that satisfy this requirement. + items: + $ref: "#/components/schemas/DocumentType" + required: + - type + - options + AccountFieldRejection: + title: Account field rejection + type: object + description: An account-level field was rejected during compliance review. + properties: + type: + type: string + enum: + - ACCOUNT_FIELD + fieldName: + type: string + description: Name of the rejected field. + example: "owner.legalName" + reason: + $ref: "#/components/schemas/Reason" + required: + - type + - fieldName + - reason + UboFieldRejection: + title: UBO field rejection + type: object + description: A UBO field was rejected during compliance review. + properties: + type: + type: string + enum: + - UBO_FIELD + fieldName: + type: string + description: Name of the rejected field. + example: "name" + uboId: + type: string + description: Identifier of the beneficial owner whose field was rejected. + example: "a1b2c3d4-e5f6-7890-1234-567890abcdef" + reason: + $ref: "#/components/schemas/Reason" + required: + - type + - fieldName + - uboId + - reason DocumentType: type: string description: Type of document. @@ -792,6 +851,11 @@ components: - RESIDENCE_PERMIT - SELFIE - UTILITY_BILL + - KYC_FORM + - BAAS_ADHESION_FORM + - PJ_PARTNER_DOCUMENTS + - PJ_PARTNER_FINANCIAL_STATEMENT + - SIGNING_AUTHORITY_PROOF example: "ARTICLES_OF_ASSOCIATION" DocumentSubType: type: string @@ -845,6 +909,97 @@ components: | SGD | 2 | EURC | 6 | | PHP | 2 | BRLT | 6 | example: "BRL" + Industry: + type: string + description: Industry classification for a company-owned account. + enum: + - AGRICULTURE + - AGRICULTURAL_FOOD_SUPPLY + - ENERGY + - ENERGY_OIL_GAS + - RETAIL_GENERAL + - ECOMMERCE_ONLINE_RETAIL + - DISTRIBUTION_WHOLESALE + - MOTOR_VEHICLE_RETAIL_PARTS + - FIRST_HAND_CAR_RETAIL + - SECOND_HAND_CAR_RETAIL + - SPORTS_EQUIPMENT_RETAIL + - TEXTILE_WHOLESALE + - PRECIOUS_METALS_WHOLESALE + - AIRCRAFT_AERONAUTIC_WHOLESALE + - PRE_PRIMARY_PRIMARY_EDUCATION + - SECONDARY_POST_SECONDARY_EDUCATION + - HIGHER_EDUCATION + - PRIVATE_EDUCATION_TRAINING_SERVICES + - ARTS_MEDIA + - VIDEO_TV_PRODUCTION + - TELECOM_MEDIA + - SPORTS_CLUBS_ASSOCIATIONS + - SPORTS_COACHING + - GAMING_EGAMING + - PRODUCTION_CULTURAL_HANDMADE_GOODS + - FASHION_PRODUCTION + - PASSENGER_TRANSPORT + - LEASING_TRANSPORT_EQUIPMENT + - BANKING + - INSURANCE + - LENDING_CREDIT_SERVICES + - INVESTMENT_ASSET_MANAGEMENT + - FINANCIAL_SERVICES_NON_CRYPTO + - PAYMENT_SERVICE_PROVIDERS + - CRYPTO_EXCHANGE_CEX + - WALLET_PROVIDER + - CRYPTO_LIQUIDITY_MARKET_MAKERS + - CRYPTO_MINING + - WEB3_FINANCIAL_SERVICES + - GAMBLING_CASINOS + - ADULT_ENTERTAINMENT + - MEDICAL_CARE_CLINICS + - HEALTHCARE_SERVICES + - MANUFACTURE_MEDICAL_SUPPLIES + - PHARMACEUTICAL_MANUFACTURING + - MEDICAL_PHARMACEUTICAL_SERVICES + - DENTAL_CARE + - VETERINARY_CARE + - AERONAUTICS_AEROSPACE_MANUFACTURING + - AUTOMOTIVE_MANUFACTURING + - CONSTRUCTION_INFRASTRUCTURE + - METAL_MANUFACTURING + - WATER_GAS_PIPELINE_CONSTRUCTION + - INDUSTRIAL_COMPANIES_GENERAL + - PUBLIC_ADMINISTRATION + - LOCAL_GOVERNMENT + - PUBLIC_SERVICES_AUTHORITIES + - NONPROFIT_CHARITY_ORGANIZATIONS + - REAL_ESTATE_AGENCIES + - REAL_ESTATE_DEVELOPERS + - ONLINE_REAL_ESTATE_MARKETPLACES + - INFORMATION_TECHNOLOGY_GENERAL + - COMPUTER_HIGH_TECH_TELECOM + - SOFTWARE_DEVELOPMENT + - IT_INFRASTRUCTURE_FACILITIES_MANAGEMENT + - COMPUTER_ELECTRONICS_REPAIR + - CYBERSECURITY_INFORMATION_SECURITY + - AUDIT_ACCOUNTING_TECHNOLOGY + - TECHNOLOGY_CONSULTING + - ENGINEERING_TECHNICAL_SERVICES + - FREIGHT_LOGISTICS + - TRANSPORTATION + - HOTEL_HOSPITALITY + - RESTAURANTS_CAFES + - TOURISM + - TRAVEL_AGENCIES + - LEGAL_SERVICES + - HUMAN_RESOURCES + - CLEANING_MAINTENANCE_SERVICES + - CULTURAL_GOODS_HANDICRAFTS_TRADE + - FASHION_DESIGN + - PRECIOUS_METALS_STONES + - ENVIRONMENT_SUSTAINABILITY_SERVICES + - ARMAMENT_DEFENSE_INDUSTRY + - UNEMPLOYED_STUDENT_RETIRED + - OTHERS + example: "INFORMATION_TECHNOLOGY_GENERAL" TaxIdType: type: string description: > @@ -1203,11 +1358,21 @@ components: $ref: "#/components/schemas/TaxIdResponse" address: $ref: "#/components/schemas/AddressResponse" + phone: + type: string + example: "5511999999999" + email: + type: string + format: email + example: "joao.silva@example.com" ownershipPercentage: type: number format: double nullable: true example: 50.0 + isLegalRepresentative: + type: boolean + example: false currentState: $ref: "#/components/schemas/UBOState" required: @@ -1215,19 +1380,10 @@ components: - name - taxId - address + - phone + - email + - isLegalRepresentative - currentState - UBOList: - type: object - properties: - data: - type: array - items: - $ref: "#/components/schemas/UBOResponse" - meta: - $ref: "#/components/schemas/PageMetadata" - required: - - data - - meta Rail: type: string description: Payment rail used to fund a deposit. @@ -1244,37 +1400,56 @@ components: - SEPA - ACH FundingInstructionResponse: - description: A funding instruction for depositing into an account. Discriminated by `rail`. + description: A funding instruction for depositing into an account. Discriminated by `type`. oneOf: - $ref: "#/components/schemas/PixKeyFundingInstruction" - $ref: "#/components/schemas/PixStaticQrCodeFundingInstruction" + - $ref: "#/components/schemas/PixBankInstructionFundingInstruction" - $ref: "#/components/schemas/TedFundingInstruction" - $ref: "#/components/schemas/BoletoFundingInstruction" - $ref: "#/components/schemas/CryptoWalletFundingInstruction" discriminator: - propertyName: rail + propertyName: type mapping: PIX_KEY: "#/components/schemas/PixKeyFundingInstruction" PIX_STATIC_QR_CODE: "#/components/schemas/PixStaticQrCodeFundingInstruction" + PIX_BANK_INSTRUCTION: "#/components/schemas/PixBankInstructionFundingInstruction" TED: "#/components/schemas/TedFundingInstruction" BOLETO: "#/components/schemas/BoletoFundingInstruction" - CRYPTO: "#/components/schemas/CryptoWalletFundingInstruction" + CRYPTO_WALLET: "#/components/schemas/CryptoWalletFundingInstruction" FundingInstructionBase: type: object properties: asset: $ref: "#/components/schemas/Asset" + type: + $ref: "#/components/schemas/FundingInstructionType" rail: $ref: "#/components/schemas/Rail" required: - asset + - type - rail + FundingInstructionType: + type: string + description: Funding instruction shape. Each value maps to one variant of `FundingInstructionResponse`. + enum: + - PIX_KEY + - PIX_STATIC_QR_CODE + - PIX_BANK_INSTRUCTION + - TED + - BOLETO + - CRYPTO_WALLET PixKeyFundingInstruction: title: PIX key allOf: - $ref: "#/components/schemas/FundingInstructionBase" - type: object properties: + type: + type: string + enum: + - PIX_KEY rail: type: string enum: @@ -1302,6 +1477,10 @@ components: - $ref: "#/components/schemas/FundingInstructionBase" - type: object properties: + type: + type: string + enum: + - PIX_STATIC_QR_CODE rail: type: string enum: @@ -1312,12 +1491,51 @@ components: example: "00020126580014br.gov.bcb.pix..." required: - qrCode + PixBankInstructionFundingInstruction: + title: PIX bank instruction + allOf: + - $ref: "#/components/schemas/FundingInstructionBase" + - type: object + properties: + type: + type: string + enum: + - PIX_BANK_INSTRUCTION + rail: + type: string + enum: + - PIX_BANK_INSTRUCTION + bankCode: + type: string + description: Bank code (ISPB or COMPE). + example: "001" + branch: + type: string + description: Branch number. + example: "0001" + accountNumber: + type: string + description: Account number. + example: "123456-7" + accountType: + type: string + description: Type of bank account. + example: "CHECKING" + required: + - bankCode + - branch + - accountNumber + - accountType TedFundingInstruction: title: TED allOf: - $ref: "#/components/schemas/FundingInstructionBase" - type: object properties: + type: + type: string + enum: + - TED rail: type: string enum: @@ -1349,6 +1567,10 @@ components: - $ref: "#/components/schemas/FundingInstructionBase" - type: object properties: + type: + type: string + enum: + - BOLETO rail: type: string enum: @@ -1371,6 +1593,10 @@ components: - $ref: "#/components/schemas/FundingInstructionBase" - type: object properties: + type: + type: string + enum: + - CRYPTO_WALLET rail: type: string enum: @@ -1386,18 +1612,6 @@ components: required: - network - walletAddress - FundingInstructionList: - type: object - properties: - data: - type: array - items: - $ref: "#/components/schemas/FundingInstructionResponse" - meta: - $ref: "#/components/schemas/PageMetadata" - required: - - data - - meta UploadDocumentRequest: type: object description: > @@ -1548,44 +1762,6 @@ components: message: "'not-a-uuid' cannot be converted to UUID" field: "path:accountId" params: {} - BalanceNotFound: - summary: No balance is tracked for the requested account - value: - code: "RESOURCE_NOT_FOUND" - message: "Balance with given parameters [Balance.accountId:5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c] not found" - details: - resource: "Balance" - parameters: - Balance.accountId: "5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c" - BalanceMixed: - summary: Account with fiat and crypto assets - value: - accountId: "5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c" - fiat: - - amount: - value: "5000.00" - asset: "BRL" - decimals: 2 - synced: true - crypto: - - amount: - value: "1.500000" - asset: "USDC" - decimals: 6 - synced: true - BalanceUnsyncedSource: - summary: Upstream provider was unreachable for one currency - value: - accountId: "5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c" - fiat: - - amount: - value: "5000.00" - asset: "BRL" - decimals: 2 - synced: true - - amount: null - synced: false - crypto: [] paths: # ── Account endpoints ──────────────────────────────────────────── @@ -1611,15 +1787,15 @@ paths: value: assets: - code: "BRL" - isVirtual: false owner: type: "COMPANY" legalName: "Acme Ltda" taxId: value: "11222333000181" type: "CNPJ" - industry: "INFORMATION_TECHNOLOGY" + industry: "INFORMATION_TECHNOLOGY_GENERAL" incorporateDate: "2018-05-12" + isStartup: false address: addressLine1: "Rua das Flores, 100" addressLine2: "Suite 456" @@ -1632,7 +1808,6 @@ paths: value: assets: - code: "BRL" - isVirtual: false owner: type: "INDIVIDUAL" firstName: "Maria" @@ -1899,44 +2074,50 @@ paths: tags: - Funding instructions summary: List funding instructions - description: Retrieves funding instructions for depositing into an account. Returns all available payment rails (PIX, TED, Boleto, crypto). + description: Retrieves funding instructions for depositing into an account. Returns all available payment rails (PIX, TED, Boleto, crypto). Optionally filter by `asset` and/or `rail`. parameters: - $ref: "#/components/parameters/AccountId" - $ref: "#/components/parameters/TraceVersion" - - $ref: "#/components/parameters/PaginationLimit" - - $ref: "#/components/parameters/PaginationCursor" - - $ref: "#/components/parameters/PaginationDirection" - - $ref: "#/components/parameters/PaginationSortOrder" - - $ref: "#/components/parameters/Filters" + - name: asset + in: query + required: false + description: Filter results by asset code. + schema: + $ref: "#/components/schemas/Asset" + - name: rail + in: query + required: false + description: Filter results by payment rail. + schema: + $ref: "#/components/schemas/Rail" responses: "200": - description: Paginated list of funding instructions. + description: List of funding instructions. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: - $ref: "#/components/schemas/FundingInstructionList" + type: array + items: + $ref: "#/components/schemas/FundingInstructionResponse" examples: mixed: summary: PIX and TED instructions value: - data: - - asset: "BRL" - rail: "PIX_KEY" - keyType: "CNPJ" - key: "12345678000101" - - asset: "BRL" - rail: "TED" - bankCode: "001" - branch: "0001" - accountNumber: "123456-7" - accountType: "CHECKING" - meta: - previousCursor: null - nextCursor: null - total: 2 + - asset: "BRL" + type: "PIX_KEY" + rail: "PIX_KEY" + keyType: "CNPJ" + key: "12345678000101" + - asset: "BRL" + type: "TED" + rail: "TED" + bankCode: "001" + branch: "0001" + accountNumber: "123456-7" + accountType: "CHECKING" "400": description: Invalid account ID format. headers: @@ -1964,66 +2145,6 @@ paths: accountNotFound: $ref: "#/components/examples/AccountNotFound" - # ── Balances ───────────────────────────────────────────────────── - /api/accounts/{accountId}/balances: - get: - operationId: getAccountBalance - tags: - - Balances - summary: Get account balance - description: > - Retrieves the multi-currency balance for the given account, - grouped into `fiat` and `crypto` arrays. - - When an upstream provider is unreachable for a given currency, the - corresponding entry is returned with `synced: false` and `amount: null` - instead of failing the entire request. See - [Errors](/guides/principles/errors) for the standard error envelope. - parameters: - - $ref: "#/components/parameters/AccountId" - - $ref: "#/components/parameters/TraceVersion" - responses: - "200": - description: Account balance. - headers: - X-Request-Id: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/BalanceResponse" - examples: - mixed: - $ref: "#/components/examples/BalanceMixed" - unsyncedSource: - $ref: "#/components/examples/BalanceUnsyncedSource" - "400": - description: Invalid account ID format. - headers: - X-Request-Id: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - invalidUuid: - $ref: "#/components/examples/InvalidAccountIdUuid" - "401": - $ref: "#/components/responses/UnauthorizedError" - "404": - description: No balance found for the given account. - headers: - X-Request-Id: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - balanceNotFound: - $ref: "#/components/examples/BalanceNotFound" - # ── Documents ──────────────────────────────────────────────────── /api/documents: post: @@ -2299,21 +2420,18 @@ paths: parameters: - $ref: "#/components/parameters/AccountId" - $ref: "#/components/parameters/TraceVersion" - - $ref: "#/components/parameters/PaginationLimit" - - $ref: "#/components/parameters/PaginationCursor" - - $ref: "#/components/parameters/PaginationDirection" - - $ref: "#/components/parameters/PaginationSortOrder" - - $ref: "#/components/parameters/Filters" responses: "200": - description: Paginated list of beneficial owners. + description: List of beneficial owners. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: - $ref: "#/components/schemas/UBOList" + type: array + items: + $ref: "#/components/schemas/UBOResponse" "401": $ref: "#/components/responses/UnauthorizedError" "404": diff --git a/docs.json b/docs.json index a5dee3b..ef6d7ab 100644 --- a/docs.json +++ b/docs.json @@ -107,13 +107,6 @@ "api-reference/fx-account/beneficial-owners/remove-ubo" ] }, - { - "group": "Balances", - "icon": "wallet", - "pages": [ - "api-reference/fx-account/balances/get-balance" - ] - }, { "group": "Funding instructions", "icon": "money-bill-transfer", From d568f298bb66b9aae72ffef43eda5bbd7816d784 Mon Sep 17 00:00:00 2001 From: Leoni Sandes Date: Mon, 11 May 2026 11:41:04 -0300 Subject: [PATCH 2/2] fix(openapi): unwrap RequirementResponse description intro line The text-formatting eval flagged a soft-wrapped line inside a `|` literal block, where the newline renders as a visible break in Mintlify. Joining the intro sentence keeps the bullet list intact. Co-Authored-By: Claude Opus 4.7 (1M context) --- apis/fx-account/openapi.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/apis/fx-account/openapi.yml b/apis/fx-account/openapi.yml index 61e2723..b3c4af9 100644 --- a/apis/fx-account/openapi.yml +++ b/apis/fx-account/openapi.yml @@ -660,8 +660,7 @@ components: - satisfied RequirementResponse: description: | - A single requirement. The `type` field discriminates between five - shapes: + A single requirement. The `type` field discriminates between five shapes: - `ACCOUNT_DOCUMENT`: a specific document is required at the account level. - `UBO_DOCUMENT`: a specific document is required for a beneficial owner.