Criar subconta
POST
/api/subaccounts
Autenticação
subaccounts:write e da flag whiteLabelEnabled. Sem a flag → 404 (a rota é invisível, idêntica a rota inexistente).Criar subconta
subaccounts:writeLEGAL_PERSON ou pessoa física) sob o master autenticado. A subconta é headless: nasce sem senha e sem login próprio — ela é operada 100% pela API key do master. Já nasce com kycStatus = PRE_APPROVED, Balance zerado e herda o roteamento de adquirente e as taxas-base do master.Idempotência (CRÍTICO)
correlationId no escopo do master. Reenviar o mesmo correlationId:{ subaccount, idempotent: true } (reusa, não duplica).correlationId foi excluída (soft delete) → 409 SUBACCOUNT_DELETED (o correlationId fica queimado; use outro).Body
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | sim | 2–100 chars. Razão social ou nome do seller. |
email | string | sim | E-mail válido, único globalmente na plataforma. |
taxId | string | sim | CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita formatado (pontos/traços) — é limpo para dígitos. Dígito verificador é validado. Imutável após a criação. |
phone | string | não | 10–11 dígitos (DDD + número), apenas números. |
correlationId | string | sim | 1–100 chars, apenas [a-zA-Z0-9_-]. Seu identificador da subconta. Chave de idempotência e de deduplicação. |
Resposta
201 Created (nova) ou 200 OK (idempotente) com { subaccount: { id, name, email, kycStatus, createdAt } }. Em idempotência o envelope inclui idempotent: true.Erros
| HTTP | code | Quando |
|---|---|---|
| 400 | — | Body inválido (Zod): nome curto, e-mail inválido, CPF/CNPJ com dígito errado, correlationId fora do padrão. |
| 401 | — | API key ausente/inválida. |
| 403 | — | Escopo subaccounts:write ausente. |
| 404 | — | Sem a flag whiteLabelEnabled (rota invisível). |
| 409 | SUBACCOUNT_DELETED | correlationId já foi usado por uma subconta excluída. |
| 409 | SUBACCOUNT_CONFLICT | Já existe conta na plataforma com o mesmo email ou taxId. |
| 422 | SUBACCOUNT_LIMIT | Teto de subcontas do master atingido. |
| 422 | — | Master é conta nominal (Woovi) — não habilitada para operar subcontas. |
Exemplo cURL
429 ao exceder). Além do teto global de 600/min por credencial.Requisição
Parâmetros Header
Parâmetros Bodyapplication/json
Respostas
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/api/subaccounts' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Loja do João LTDA",
"email": "financeiro@lojadojoao.com.br",
"taxId": "12345678000199",
"phone": "11999998888",
"correlationId": "seller-001"
}'Response Response Example
201 - Criada (201)
{
"subaccount": {
"id": "{{subaccount_id}}",
"name": "Loja do João LTDA",
"email": "financeiro@lojadojoao.com.br",
"kycStatus": "PRE_APPROVED",
"createdAt": "2026-06-12T14:30:00.000Z"
}
}Modificado em 2026-07-02 06:57:27