> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uvvipay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar subconta
> Cria uma nova subconta vinculada ao merchant autenticado. Aceita upload de documentos via multipart/form-data (arquivos binários; base64 não é aceito). Os documentos obrigatórios variam conforme o documentType — consulte a descrição de cada campo.
Ao cadastrar o submerchant, a chave PIX é criada automaticamente com o
documento do cadastro (CPF ou CNPJ).
## Formato do envio
A requisição deve ser `multipart/form-data`: os campos de texto vão como form
fields e cada documento vai como **file part** (arquivo binário — PDF ou
imagem).
Strings base64 **não são aceitas** nos campos de arquivo. Enviar o conteúdo
do documento como texto retorna erro 400.
## Documentos obrigatórios
Os arquivos exigidos dependem do `documentType` da subconta:
| Campo | CNPJ | CPF |
| -------------------- | --------------------------------- | --------------------------------- |
| `cartaoCnpj` | Obrigatório | Não se aplica |
| `contratoSocial` | Obrigatório | Não se aplica |
| `selfieComDocumento` | Obrigatório | Obrigatório |
| `documentoFrente` | Obrigatório¹ | Obrigatório¹ |
| `documentoVerso` | Obrigatório¹ | Obrigatório¹ |
| `cnhCompleta` | Opcional — substitui frente/verso | Opcional — substitui frente/verso |
¹ Dispensados quando `cnhCompleta` (frente e verso em um único arquivo) é
enviada. Para `documentType: cnpj`, os documentos de identidade são do
**representante legal**.
Se algum documento obrigatório faltar, a resposta 400 lista os campos ausentes
em `missingDocuments`.
## Exemplo
```bash theme={null}
curl -X POST https://api.uvvipay.com.br/v1/submerchants \
-H "CLIENT-ID: seu-client-id" \
-H "CLIENT-SECRET: seu-client-secret" \
-H "x-idempotency-key: 4f7b2c1e-0000-0000-0000-000000000000" \
-F "documentType=cnpj" \
-F "documentNumber=12345678000190" \
-F "email=parceiro@exemplo.com.br" \
-F "phone=11999999999" \
-F "addressStreetNumber=100" \
-F 'bankAccount={"bankingDataType":"bank_account","bankName":"Nubank","bankCode":"260","bankAgency":"0001","bankAccount":"1234567","bankAccountDv":"8","bankAccountType":"conta_corrente"}' \
-F "cartaoCnpj=@cartao-cnpj.pdf" \
-F "contratoSocial=@contrato-social.pdf" \
-F "selfieComDocumento=@selfie.jpg" \
-F "cnhCompleta=@cnh.jpg" # dispensa documentoFrente e documentoVerso
```
Em Node.js, use `FormData` com `Blob`/stream do arquivo — nunca
`JSON.stringify` com o conteúdo em base64.
## OpenAPI
````yaml POST /v1/submerchants
openapi: 3.0.0
info:
title: UvviPay Public API
description: >-
Endpoints públicos da plataforma UvviPay para integração de subcontas
(submerchants).
version: 1.0.0
contact: {}
servers:
- url: https://api.uvvipay.com.br
description: Produção
- url: https://api-staging.uvvipay.com.br
description: Staging
security:
- client-id: []
client-secret: []
tags: []
paths:
/v1/submerchants:
post:
tags:
- Submerchants
summary: Criar subconta
description: >-
Cria uma nova subconta vinculada ao merchant autenticado. Aceita upload
de documentos via multipart/form-data (arquivos binários; base64 não é
aceito). Os documentos obrigatórios variam conforme o documentType —
consulte a descrição de cada campo.
operationId: apiCreate
parameters:
- name: client-secret
in: header
description: Secret da credencial do merchant
required: true
schema:
type: string
- name: client-id
in: header
description: ID público da credencial do merchant
required: true
schema:
type: string
- name: x-idempotency-key
in: header
description: UUID gerado pelo cliente para garantir idempotência
required: true
schema:
type: string
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/ApiCreateSubMerchantDto'
responses:
'201':
description: Subconta criada com sucesso
content:
application/json:
schema:
$ref: '#/components/schemas/ApiCreateSubMerchantResponseDto'
'400':
description: Dados inválidos
'401':
description: Credenciais inválidas ou ausentes
'409':
description: Idempotency key já utilizada com payload diferente
'429':
description: Limite de requisições excedido
components:
schemas:
ApiCreateSubMerchantDto:
type: object
properties:
legalName:
type: string
description: Nome legal (obrigatório quando documentType = cpf)
example: João da Silva
maxLength: 255
email:
type: string
format: email
description: Email de contato da subconta
example: contato@exemplo.com.br
maxLength: 255
url:
type: string
description: URL do site da subconta
example: https://exemplo.com.br
maxLength: 255
phone:
type: string
description: Telefone de contato
example: '11999999999'
maxLength: 20
documentType:
type: string
description: Tipo do documento
enum:
- cpf
- cnpj
example: cnpj
documentNumber:
type: string
description: Número do documento (apenas dígitos, 11 para CPF ou 14 para CNPJ)
example: '12345678000199'
maxLength: 20
legalType:
type: string
description: Tipo jurídico
example: LTDA
maxLength: 255
addressZipCode:
type: string
description: CEP (obrigatório quando documentType = cpf)
example: '01310100'
maxLength: 10
addressStreet:
type: string
description: Logradouro do endereço
example: Avenida Paulista
maxLength: 255
addressStreetNumber:
type: string
description: Número do endereço
example: '1000'
maxLength: 20
addressComplement:
type: string
description: Complemento do endereço
example: Conjunto 101
maxLength: 255
addressNeighborhood:
type: string
description: Bairro do endereço
example: Bela Vista
maxLength: 100
addressCity:
type: string
description: Cidade do endereço
example: São Paulo
maxLength: 100
addressState:
type: string
description: UF do endereço (2 caracteres)
example: SP
maxLength: 2
addressCountry:
type: string
description: País do endereço (ISO Alpha-2)
example: BR
default: BR
maxLength: 2
contratoSocial:
type: string
format: binary
description: >-
Contrato social (PDF/imagem). Obrigatório para documentType cnpj;
não se aplica a cpf. Enviar como arquivo binário via
multipart/form-data — base64 não é aceito
cartaoCnpj:
type: string
format: binary
description: >-
Cartão CNPJ (PDF/imagem). Obrigatório para documentType cnpj; não se
aplica a cpf. Enviar como arquivo binário via multipart/form-data —
base64 não é aceito
documentoFrente:
type: string
format: binary
description: >-
Foto da frente do documento de identidade (do representante legal
quando cnpj). Obrigatória, exceto se cnhCompleta for enviada.
Arquivo binário via multipart/form-data — base64 não é aceito
documentoVerso:
type: string
format: binary
description: >-
Foto do verso do documento de identidade (do representante legal
quando cnpj). Obrigatória, exceto se cnhCompleta for enviada.
Arquivo binário via multipart/form-data — base64 não é aceito
selfieComDocumento:
type: string
format: binary
description: >-
Selfie segurando o documento. Sempre obrigatória. Arquivo binário
via multipart/form-data — base64 não é aceito
cnhCompleta:
type: string
format: binary
description: >-
CNH completa, frente e verso em um único arquivo. Opcional — quando
enviada, dispensa documentoFrente e documentoVerso. Arquivo binário
via multipart/form-data — base64 não é aceito
bankAccount:
description: >-
Dados bancários da subconta. Pode ser enviado como JSON string em
multipart/form-data. A chave PIX é criada automaticamente com o
documento do cadastro (CPF ou CNPJ).
allOf:
- $ref: '#/components/schemas/CreateSubMerchantBankAccountDto'
required:
- email
- phone
- documentType
- documentNumber
- addressStreetNumber
- bankAccount
ApiCreateSubMerchantResponseDto:
type: object
properties:
message:
type: string
example: Subconta criada com sucesso
id:
type: string
description: ID (UUID) da subconta criada
format: uuid
example: 5b9f3d6a-3a2c-4d6f-9b9e-0a1b2c3d4e5f
required:
- message
- id
CreateSubMerchantBankAccountDto:
type: object
properties:
bankingDataType:
type: string
description: Tipo dos dados bancários
enum:
- bank_account
- chave_pix
example: bank_account
bankName:
type: string
description: Nome do banco
example: Banco do Brasil
maxLength: 100
bankAgency:
type: string
description: Agência bancária
example: '1234'
maxLength: 20
bankAccount:
type: string
description: Conta bancária
example: '56789'
maxLength: 30
bankAccountDv:
type: string
description: Dígito verificador
example: '0'
maxLength: 5
bankAccountType:
type: string
description: Tipo da conta bancária
enum:
- conta_corrente
- conta_poupanca
example: conta_corrente
ispb:
type: string
description: ISPB do banco
example: '00000000'
maxLength: 8
bankCode:
type: string
description: Código compe do banco
example: '001'
maxLength: 8
required:
- bankingDataType
- bankName
- bankAgency
- bankAccount
- bankAccountDv
- bankAccountType
- bankCode
securitySchemes:
client-id:
type: apiKey
in: header
name: client-id
client-secret:
type: apiKey
in: header
name: client-secret
````