> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Criar uma Conta > Use este endpoint para criar uma Conta no Midaz. Você pode criar quantas contas forem necessárias para estruturar seu ledger, mas cada requisição cria apenas uma conta por vez. **Importante:** Antes de criar uma Conta, certifique-se de que o Ativo correspondente já existe. Use o endpoint [Criar um Ativo](/pt/reference/midaz/create-an-asset) para registrá-lo, se necessário. Se você definiu Tipos de Conta anteriormente, certifique-se de que estão configurados corretamente antes da criação da conta. Recomendamos recriar as contas existentes ou atualizá-las para incluir o tipo correto antes de habilitar o recurso de validação de Tipo de Conta — isso ajuda a prevenir erros de validação e garante conformidade com sua estrutura contábil. **Nota:** o valor `external` do campo `type` é reservado para contas externas gerenciadas pelo sistema e é rejeitado na entrada. ## OpenAPI ````yaml pt/openapi/v3-current/ledger.yaml post /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts openapi: 3.1.0 info: title: API Midaz Ledger description: >- Referência completa da API para serviços do Midaz Ledger incluindo gerenciamento de organizações, operações de ledger, ativos, segmentos, portfolios, contas, tipos de conta, transações, operações, saldos, rotas de operação, rotas de transação e índices de metadata. version: 3.7.8 servers: - url: https://ledger.sandbox.lerian.net security: [] tags: - name: API de Organizações - name: API de Ledgers - name: API de Ativos - name: API de Segmentos - name: API de Portfolios - name: API de Tipos de Conta - name: API de Contas - name: API de Saldos - name: API de Transações - name: API de Operações - name: API de Rotas de Operação - name: API de Rotas de Transação - name: API de Índices de Metadata - name: API de Titulares - name: API de Instrumentos - name: API de Pacotes de Cobrança - name: API de Pacotes - name: API de Cálculo de Cobrança - name: API de Estimativa - name: API de Criptografia - name: API de Proteção - name: API de Taxas de Ativos paths: /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts: post: tags: - API de Contas summary: Criar uma Conta description: > Use este endpoint para criar uma Conta no Midaz. Você pode criar quantas contas forem necessárias para estruturar seu ledger, mas cada requisição cria apenas uma conta por vez. **Importante:** Antes de criar uma Conta, certifique-se de que o Ativo correspondente já existe. Use o endpoint [Criar um Ativo](/pt/reference/midaz/create-an-asset) para registrá-lo, se necessário. Se você definiu Tipos de Conta anteriormente, certifique-se de que estão configurados corretamente antes da criação da conta. Recomendamos recriar as contas existentes ou atualizá-las para incluir o tipo correto antes de habilitar o recurso de validação de Tipo de Conta — isso ajuda a prevenir erros de validação e garante conformidade com sua estrutura contábil. **Nota:** o valor `external` do campo `type` é reservado para contas externas gerenciadas pelo sistema e é rejeitado na entrada. parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LedgerId' - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/XRequestId' - $ref: '#/components/parameters/Authorization' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAccountRequest' example: assetCode: BRL name: Customer BRL Account 1 alias: customer-brl-1 type: deposit status: code: ACTIVE description: Operational retail account for Pix and internal payments metadata: bankCode: '341' branchNumber: '0001' accountNumber: 12345678-9 accountPlan: retail_personal_wallet dailyLimit: 50000 responses: '201': description: >- Indica que a requisição foi bem-sucedida e a resposta contém os dados esperados. content: application/json: schema: $ref: '#/components/schemas/CreateAccountResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0009: $ref: '#/components/examples/Error0009' Error0029: $ref: '#/components/examples/Error0029' Error0047: $ref: '#/components/examples/Error0047' Error0050: $ref: '#/components/examples/Error0050' Error0051: $ref: '#/components/examples/Error0051' Error0053: $ref: '#/components/examples/Error0053' Error0066: $ref: '#/components/examples/Error0066' Error0067: $ref: '#/components/examples/Error0067' Error0094: $ref: '#/components/examples/Error0094' headers: {} '401': description: Não autorizado content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0041: $ref: '#/components/examples/Error0041' Error0042: $ref: '#/components/examples/Error0042' '403': description: Proibido content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0043: $ref: '#/components/examples/Error0043' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0034: $ref: '#/components/examples/Error0034' Error0035: $ref: '#/components/examples/Error0035' Error0036: $ref: '#/components/examples/Error0036' Error0037: $ref: '#/components/examples/Error0037' Error0038: $ref: '#/components/examples/Error0038' Error0109: $ref: '#/components/examples/Error0109' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0020: $ref: '#/components/examples/Error0020' '500': description: Erro Interno do Servidor content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0046: $ref: '#/components/examples/Error0046' components: parameters: OrganizationId: name: organization_id in: path description: O identificador único da Organização associada ao Ledger. required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid LedgerId: name: ledger_id in: path description: O identificador único do Ledger associado. required: true example: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a schema: type: string format: uuid ContentType: name: Content-Type in: header description: O tipo de mídia do recurso. O valor recomendado é `application/json`. required: false example: application/json schema: type: string XRequestId: name: X-Request-Id in: header description: >- Um identificador único utilizado para rastrear e acompanhar cada requisição. required: false example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid Authorization: name: Authorization in: header required: false schema: type: string description: > Token JWT bearer para autenticação. Obrigatório quando `PLUGIN_AUTH_ENABLED=true` (exigido em implantações multi-tenant). Opcional no modo OSS single-tenant padrão. Formato: `Bearer ` schemas: CreateAccountRequest: type: object properties: assetCode: type: string maxLength: 100 description: >- O código que identifica o Ativo utilizado na Conta. **Importante:** Deve ser um Ativo que você já criou usando o endpoint [Criar um Ativo](/pt/reference/midaz/create-an-asset). name: type: string description: O nome da Conta. maxLength: 256 alias: type: string maxLength: 100 pattern: ^[a-zA-Z0-9@:_-]+$ description: >- Um identificador único e amigável para a conta. Usado para referenciar a conta em transações e outras operações. Se não fornecido, o sistema usará o ID da conta como alias. **Nota:** o alias não deve conter o prefixo reservado `@external/`, que é reservado para contas externas gerenciadas pelo sistema. type: type: string maxLength: 256 description: >- Especifica o Tipo de Conta associado à conta. Este campo é **obrigatório**. **Importante:** Quando a validação de Tipo de Conta está habilitada para sua Organização e Ledger, o valor deve corresponder a um `keyValue` existente definido na sua [configuração de Tipos de Conta](/pt/reference/midaz/create-an-account-type). Quando a validação está desabilitada (comportamento padrão), o campo continua sendo obrigatório, mas aceita qualquer string de formato livre sem validação. O valor `external` é reservado e rejeitado na entrada. blocked: type: boolean default: false description: Define se a conta deve começar bloqueada. parentAccountId: type: - string - 'null' description: O identificador único da Conta pai, caso esta seja uma subconta. format: uuid entityId: type: - string - 'null' maxLength: 256 description: O identificador único da Entidade responsável pela Conta. portfolioId: type: - string - 'null' description: O identificador único do Portfolio associado. format: uuid segmentId: type: - string - 'null' description: O identificador único do Segmento utilizado para agrupar a Conta. format: uuid status: $ref: '#/components/schemas/StatusOrganizationRequest' metadata: $ref: '#/components/schemas/Metadata' required: - assetCode - type CreateAccountResponse: type: object properties: id: type: string description: O identificador único da Conta. format: uuid organizationId: type: string format: uuid description: O identificador único da Organização. ledgerId: type: string description: O identificador único do Ledger. format: uuid assetCode: type: string description: O código que identifica o Ativo utilizado na Conta. name: type: string description: O nome da Conta. maxLength: 256 alias: type: string description: >- Um identificador único e amigável para a conta. Usado para referenciar a conta em transações e outras operações. type: type: string description: Especifica o Tipo de Conta associado à conta. blocked: type: boolean default: false description: Define se a conta deve ser bloqueada. parentAccountId: type: - string - 'null' format: uuid description: O identificador único da Conta Pai. entityId: type: - string - 'null' description: O identificador único da Entidade responsável pela Conta. portfolioId: type: - string - 'null' description: O identificador único do Portfolio associado. format: uuid segmentId: type: - string - 'null' description: O identificador único do Segmento utilizado para agrupar a Conta. format: uuid status: $ref: '#/components/schemas/StatusOrganization' metadata: $ref: '#/components/schemas/Metadata' createdAt: type: string format: date-time description: Data e hora de criação (UTC). updatedAt: type: string format: date-time description: Data e hora da última atualização (UTC). deletedAt: type: - string - 'null' format: date-time description: Data e hora da exclusão lógica, se aplicável (UTC). ErrorFormat: type: object description: A mensagem de erro da resposta. required: - code - title - message properties: code: type: string description: Um identificador único e estável para o erro. title: type: string description: Um breve resumo do problema. message: type: string description: Orientação detalhada para resolver o erro. entityType: type: string description: >- O tipo de entidade ao qual o erro se refere (por exemplo, organization, ledger, account, transaction). Opcional. fields: type: object additionalProperties: true description: Informações adicionais sobre os campos que causaram o erro. StatusOrganizationRequest: type: object description: >- Um objeto contendo informações sobre o status. **Importante**: Se não fornecido, o status padrão será 'ACTIVE'. properties: code: type: string maxLength: 100 description: O nome do status. description: type: - string - 'null' maxLength: 256 description: A descrição do status. Metadata: type: object additionalProperties: oneOf: - type: string maxLength: 2000 - type: number - type: boolean description: >- Um objeto contendo pares de chave-valor para adicionar como metadata, onde o campo `name` é a chave e o campo `value` é o valor. Por exemplo, para adicionar um Centro de Custo, use `'costCenter': 'BR_11101997'`. **Restrições:** as chaves devem ter no máximo 100 caracteres; valores de string no máximo 2000 caracteres. Objetos aninhados não são permitidos (os valores devem ser string, número ou booleano), a estrutura não pode exceder uma profundidade máxima de 10, e é permitido um máximo de 100 chaves. StatusOrganization: type: object description: Um objeto contendo informações sobre o status. properties: code: type: string maxLength: 100 description: O nome do status. description: type: - string - 'null' maxLength: 256 description: A descrição do status. examples: Error0009: summary: Missing Fields in Request value: code: '0009' title: Missing Fields in Request message: >- Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request. fields: metadataKey: metadataKey is a required field Error0029: summary: Invalid Parent Account ID value: code: '0029' title: Invalid Parent Account ID message: >- The specified parent account ID does not exist. Please verify the ID is correct and try your request again. Error0047: summary: Bad Request value: code: '0047' title: Bad Request message: >- The server could not understand the request due to malformed syntax. Please check the listed fields and try again. Error0050: value: code: '0050' title: Invalid Metadata message: >- One or more metadata entries are invalid. Please ensure metadata keys and values follow the allowed format. summary: Invalid Metadata Error0051: value: code: '0051' title: Invalid Metadata Key message: >- A metadata key contains unsupported characters or exceeds length limits. Please correct the key and try again. summary: Invalid Metadata Key Error0053: value: code: '0053' title: Unexpected Fields in the Request message: >- The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object. fields: '{{field}}': '{{value}}' summary: Unexpected Fields in the Request Error0066: summary: Invalid Account Type value: code: '0066' title: Invalid Account Type message: >- The provided 'type' is not valid. Accepted types are: deposit, savings, loans, marketplace, cerditCard or external. Please provide a valid type. Error0067: value: code: '0067' title: Invalid Metadata Nesting message: >- The metadata object cannot contain nested values. Please ensure that the value {{value}} is not nested and try again. summary: Invalid Metadata Nesting Error0094: value: code: '0094' title: Invalid Request Body message: >- The request body is invalid or could not be parsed. Please check JSON structure and field types. summary: Invalid Request Body Error0041: summary: Token Missing value: code: '0041' title: Token Missing message: >- A valid token must be provided in the request header. Please include a token and try again. Error0042: summary: Invalid Token value: code: '0042' title: Invalid Token message: >- The provided token is expired, invalid or malformed. Please provide a valid token and try again. Error0043: summary: Insufficient Privileges value: code: '0043' title: Insufficient Privileges message: >- You do not have the necessary permissions to perform this action. Please contact your administrator if you believe this is an error. Error0034: summary: Asset Code Not Found value: code: '0034' title: Asset Code Not Found message: >- The provided asset code does not exist in our records. Please verify the asset code and try again. Error0035: summary: Portfolio ID Not Found value: code: '0035' title: Portfolio ID Not Found message: >- The provided portfolio ID does not exist in our records. Please verify the portfolio ID and try again. Error0036: summary: Segment ID Not Found value: code: '0036' title: Segment ID Not Found message: >- The provided segment ID does not exist in our records. Please verify the segment ID and try again. Error0037: summary: Ledger ID Not Found value: code: '0037' title: Ledger ID Not Found message: >- The provided ledger ID does not exist in our records. Please verify the ledger ID and try again. Error0038: summary: Organization ID Not Found value: code: '0038' title: Organization ID Not Found message: >- The provided organization ID does not exist in our records. Please verify the organization ID and try again. Error0109: value: code: '0109' message: >- The account type you are trying to access does not exist or has been removed. title: Account Type Not Found Error summary: Account Type Not Found Error Error0020: summary: Alias Unavailability Error value: code: '0020' title: Alias Unavailability Error message: >- The alias {{alias}} is already in use. Please choose a different alias and try again. Error0046: summary: Internal Server Error value: code: '0046' title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later or contact support. ````