> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abacatepay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar subconta

> Cadastra um vendedor como subconta da sua loja, identificado pelo CPF ou CNPJ. Idempotente pelo `taxId`: se a subconta já existe, a API devolve a existente, com o saldo atual.


Cadastra um vendedor como subconta da sua loja.

> [card]
>
> Requer a permissão `SUB_ACCOUNT:CREATE`.

**Formato aceito pela API:**

```json theme={null}
{
  "name": "João da Silva",
  "taxId": "111.444.777-35",
  "externalId": "vendedor-42",
  "metadata": {
    "loja": "centro"
  }
}
```

| Campo | Tipo | Descrição |
| - | - | - |
| `name` | `string` | Nome do titular, até 100 caracteres. Obrigatório |
| `taxId` | `string` | CPF ou CNPJ do titular, com ou sem máscara. Obrigatório |
| `externalId` | `string` | ID no seu sistema, até 100 caracteres. Opcional |
| `metadata` | `object` | Campos livres; todos os valores precisam ser texto. Opcional |

> [!NOTE]
>
> A criação é idempotente pelo CPF/CNPJ: se já existe uma subconta com o mesmo `taxId`, a API devolve essa subconta, com o saldo atual, e ignora os outros campos.

**Erros comuns:**

| `error` | Motivo |
| - | - |
| `CPF ou CNPJ inválido` | O `taxId` não é um CPF nem um CNPJ válido |
| `A subconta não pode ter o CPF ou CNPJ da própria loja` | O `taxId` é o documento da sua loja. O seu saldo já é o da loja; subconta é para vendedores |
| `externalId já usado por outra subconta` | Outra subconta da loja já tem esse `externalId` |
| `Função não habilitada` | As subcontas não estão habilitadas na sua conta |


## OpenAPI

````yaml POST /sub-accounts/create
openapi: 3.1.0
info:
  title: API AbacatePay
  description: API para gerenciamento de cobranças e pagamentos usando o AbacatePay.
  version: 1.0.0
servers:
  - url: https://api.abacatepay.com/v2
    description: Único servidor para os ambientes de produção e sandbox.
security: []
paths:
  /sub-accounts/create:
    post:
      summary: Criar subconta
      description: >
        Cadastra um vendedor como subconta da sua loja, identificado pelo CPF ou
        CNPJ. Idempotente pelo `taxId`: se a subconta já existe, a API devolve a
        existente, com o saldo atual.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - taxId
              additionalProperties: false
              example:
                name: João da Silva
                taxId: 111.444.777-35
                externalId: vendedor-42
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Nome do titular.
                  example: João da Silva
                taxId:
                  type: string
                  minLength: 11
                  maxLength: 18
                  description: CPF ou CNPJ do titular, com ou sem máscara.
                  example: 111.444.777-35
                externalId:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: >-
                    Identificador da subconta no seu sistema. Não pode se
                    repetir entre as subcontas da loja.
                  example: vendedor-42
                metadata:
                  type: object
                  description: Campos livres; todos os valores precisam ser texto.
                  additionalProperties:
                    type: string
                  example:
                    loja: centro
      responses:
        '200':
          description: Subconta criada, ou a existente com o mesmo `taxId`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SubAccount'
                  error:
                    type: string
                    nullable: true
                    example: null
                  success:
                    $ref: '#/components/schemas/Success'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Token de autenticação inválido ou ausente.
      security:
        - bearerAuth: []
components:
  schemas:
    SubAccount:
      type: object
      description: Subconta de um vendedor, com o saldo atual.
      properties:
        id:
          type: string
          description: ID único da subconta.
          example: sacc_9f8Kq2LmX4vTzR7pWn3bYc1H
        name:
          type: string
          description: Nome do titular.
          example: João da Silva
        taxId:
          type: string
          description: CPF ou CNPJ do titular, só dígitos.
          example: '11144477735'
        externalId:
          type: string
          nullable: true
          description: Identificador no seu sistema.
          example: vendedor-42
        balance:
          type: object
          description: Saldo da subconta em centavos.
          properties:
            available:
              type: integer
              description: Disponível para saque.
              example: 7000
            blocked:
              type: integer
              description: Retido.
              example: 0
        devMode:
          type: boolean
          description: Indica se a subconta foi criada em ambiente de testes.
          example: false
        metadata:
          type: object
          additionalProperties:
            type: string
          example:
            loja: centro
        createdAt:
          type: string
          format: date-time
          example: '2026-10-26T14:22:10.381Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-10-26T14:22:10.381Z'
    Success:
      type: boolean
      description: Se a requisição obteve sucesso ou não.
      example: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Todas as requisições devem incluir sua chave de API no header
        Authorization usando o formato `Bearer <abacatepay-api-key>`. Sem esse
        header a requisição será rejeitada.


        Saiba mais sobre como criar e usar chaves de API na [documentação de
        autenticação](/pages/authentication).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.