> ## 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.
# Onboarding PJ
> Inicia o onboarding assíncrono de subconta pessoa jurídica via multipart/form-data. Retorna 202 com registration_id e status.
`POST /v2/submerchants/onboarding/pj`
Inicia o onboarding de uma subconta **PJ**. A requisição é `multipart/form-data`
e retorna `202 Accepted` com o `registration_id` e o status inicial.
Inicia o onboarding assíncrono de subconta pessoa jurídica. Retorna `202` com
`registration_id`. Exige headers `client-id` + `client-secret` e
`x-idempotency-key` (UUID v4).
## Arquivos (multipart)
Envie **uma** das opções de documento de identidade do representante, a selfie,
e os documentos da empresa:
| Campo | Obrigatório | Descrição |
| ----------------- | ----------- | ---------------------------------------------------------- |
| `documentoFrente` | Condicional | Frente do RG/CIN do representante |
| `documentoVerso` | Condicional | Verso do RG/CIN do representante |
| `cnhCompleta` | Condicional | CNH completa do representante (alternativa a frente+verso) |
| `selfie` | Sim | Selfie do representante (rosto) |
| `contratoSocial` | Sim | Contrato social |
| `cartaoCnpj` | Sim | Cartão CNPJ |
Regras:
* Envie `documentoFrente` **e** `documentoVerso`, **ou** `cnhCompleta`.
* O campo da selfie é `selfie` (não use mais `selfieComDocumento`).
Envie `documentoFrente` e `documentoVerso` do representante, ou envie
`cnhCompleta`. Envie também `selfie`, `contratoSocial` e `cartaoCnpj`. O
campo da selfie é `selfie`. Não use `selfieComDocumento`. Depois do `202`,
consulte o status com o `registration_id`. Veja o guia [Subcontas](/subcontas).
## OpenAPI
````yaml POST /v2/submerchants/onboarding/pj
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:
/v2/submerchants/onboarding/pj:
post:
tags:
- Submerchants
summary: Onboarding PJ (API)
description: >-
Inicia o onboarding assíncrono de subconta pessoa jurídica via
multipart/form-data. Retorna 202 com registration_id e status.
operationId: apiOnboardingSubmerchantPj
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 v4 gerado pelo cliente. Usado como externalId da subconta.
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/ApiOnboardingSubmerchantPjDto'
responses:
'202':
description: Onboarding iniciado
content:
application/json:
schema:
$ref: '#/components/schemas/ApiOnboardingSubmerchantResponseDto'
'400':
description: Dados ou documentos inválidos
'401':
description: Credenciais inválidas ou ausentes
'403':
description: Recurso não habilitado para este merchant
'409':
description: Idempotency key já utilizada com payload diferente
'429':
description: Limite de requisições excedido
components:
schemas:
ApiOnboardingSubmerchantPjDto:
type: object
properties:
cnpj:
type: string
description: CNPJ da empresa (14 dígitos)
example: '12345678000199'
representativeCpf:
type: string
description: CPF do representante (11 dígitos)
example: '12345678901'
representativeName:
type: string
description: Nome completo do representante
example: Maria Souza
maxLength: 255
birthDate:
type: string
format: date
description: Data de nascimento do representante (YYYY-MM-DD)
example: '1985-05-20'
email:
type: string
format: email
description: Email de contato (opcional)
example: contato@empresa.com
maxLength: 255
phone:
type: string
description: Telefone no formato E.164
example: '+5511888888888'
bankAccount:
description: Dados bancários. Em multipart, envie como JSON string.
allOf:
- $ref: '#/components/schemas/ApiOnboardingSubmerchantBankAccountDto'
documentoFrente:
type: string
format: binary
description: >-
Frente do RG/CIN do representante. Obrigatório com documentoVerso,
se não enviar cnhCompleta.
documentoVerso:
type: string
format: binary
description: >-
Verso do RG/CIN do representante. Obrigatório com documentoFrente,
se não enviar cnhCompleta.
cnhCompleta:
type: string
format: binary
description: >-
CNH completa do representante. Alternativa a documentoFrente +
documentoVerso.
selfie:
type: string
format: binary
description: Selfie do representante (rosto). Não use selfieComDocumento.
contratoSocial:
type: string
format: binary
description: Contrato social (PDF ou imagem)
cartaoCnpj:
type: string
format: binary
description: Cartão CNPJ (PDF ou imagem)
required:
- cnpj
- representativeCpf
- representativeName
- birthDate
- phone
- bankAccount
- selfie
- contratoSocial
- cartaoCnpj
anyOf:
- required:
- documentoFrente
- documentoVerso
- required:
- cnhCompleta
ApiOnboardingSubmerchantResponseDto:
type: object
properties:
registration_id:
type: string
format: uuid
description: ID do registro de onboarding
example: 2f1c8b9a-4d3e-4f6a-9b1c-0a1b2c3d4e5f
status:
type: string
description: Status do onboarding após o submit ou reenvio
example: submitted
required:
- registration_id
- status
ApiOnboardingSubmerchantBankAccountDto:
type: object
properties:
bankAccountType:
type: string
description: Tipo da conta bancária
enum:
- conta_corrente
- conta_poupanca
example: conta_corrente
bankName:
type: string
description: Nome do banco
example: Banco do Brasil
maxLength: 100
bankCode:
type: string
description: Código compe do banco (3 dígitos)
example: '001'
maxLength: 3
bankAgency:
type: string
description: Agência bancária
example: '1234'
maxLength: 20
bankAccount:
type: string
description: Número da conta
example: '56789'
maxLength: 30
bankAccountDv:
type: string
description: Dígito verificador da conta
example: '0'
maxLength: 5
ispb:
type: string
description: ISPB do banco (8 dígitos)
example: '00000000'
maxLength: 8
required:
- bankAccountType
- bankName
- bankCode
- bankAgency
- bankAccount
- bankAccountDv
- ispb
securitySchemes:
client-id:
type: apiKey
in: header
name: client-id
client-secret:
type: apiKey
in: header
name: client-secret
````