Fluxo Completo: Cadastro de Pessoa Jurídica (PJ) / Complete Flow: Legal Entity (PJ) Registration¶

📌 Visão Geral / Overview¶

O Fluxo de Cadastro de Pessoa Jurídica é um processo completo que permite a parceiros integrados registrar e habilitar empresas clientes na Plataforma de Parceiros, possibilitando a realização de operações de câmbio e transferências internacionais.

Este fluxo segue rigorosamente as regulamentações do Banco Central do Brasil e adota as melhores práticas de Know Your Business (KYB), garantindo conformidade regulatória e segurança operacional.

The Legal Entity Registration Flow is a complete process that allows integrated partners to register and enable corporate clients on the Partner Platform, enabling foreign exchange operations and international transfers.

This flow strictly follows the regulations of the Central Bank of Brazil and adopts the best Know Your Business (KYB) practices, ensuring regulatory compliance and operational security.

🔐 Autenticação / Authentication¶

Todos os endpoints desta API exigem os seguintes headers obrigatórios para garantir a segurança e a correta identificação da requisição:

All endpoints in this API require the following mandatory headers to ensure security and the correct identification of the request:

Header / Header	Descrição / Description	Exemplo de Valor / Value Example
`Authorization`	Token JWT válido com a role `ADMIN_PARTNER` Valid JWT token with the `ADMIN_PARTNER` role	`Bearer {seu_jwt_token}`
`Role`	Permissão do usuário autenticado Authenticated user permission	`ADMIN_PARTNER`
`x-api-key`	Chave de acesso individual do parceiro (formato GUID) Individual partner access key (GUID format)	`62c45798-3500-47c9-8d0f-4b22effbc70e`
`Accept-Language`	Idioma esperado na resposta da API Expected language in the API response	`pt-br`, `en-us` ou / or `es-es`

📝 Descrição dos Headers / Headers Description¶

Authorization: Token JWT assinado, contendo as credenciais do parceiro com permissão de administrador.
- Authorization: Signed JWT token, containing the partner's credentials with administrator permission.
Role: Define o papel do usuário na autenticação. Para este fluxo, deve ser sempre ADMIN_PARTNER.
- Role: Defines the user's role in authentication. For this flow, it must always be ADMIN_PARTNER.
x-api-key: Identificador único no formato GUID, fornecido previamente ao parceiro durante o processo de integração.
- x-api-key: Unique identifier in GUID format, previously provided to the partner during the integration process.
Accept-Language: Define o idioma das mensagens de retorno da API, facilitando a internacionalização.
- Accept-Language: Defines the language of the API return messages, facilitating internationalization.

🚦 Rate Limiting / Rate Limiting¶

As APIs Públicas possuem um sistema de limitação de taxa de requisições para garantir a estabilidade, segurança e disponibilidade do serviço para todos os usuários.

The Public APIs have a request rate limiting system to ensure stability, security, and service availability for all users.

[!NOTE] 💡 IMPORTANTE / IMPORTANT

Os limites são aplicados por endereço IP, ou seja, cada IP possui seus próprios contadores de requisições de forma independente.

Limits are applied per IP address, meaning each IP has its own request counters independently.

📊 Limites Aplicados / Applied Limits¶

A tabela abaixo descreve os limites de requisições permitidos por período:

The table below describes the allowed request limits per period:

Período / Period	Limite de Requisições / Request Limit	Descrição / Description
1 segundo / 1 second	3	Proteção contra picos de tráfego Protection against traffic spikes
1 minuto / 1 minute	30	Uso normal da API Normal API usage
15 minutos / 15 minutes	100	Operações em lote Batch operations
1 hora / 1 hour	300	Limite máximo por hora Maximum hourly limit

📥 Headers de Resposta / Response Headers¶

A API retorna os seguintes cabeçalhos HTTP para informar sobre o status da taxa de requisições:

The API returns the following HTTP headers to inform about the request rate status:

Header / Header	Descrição / Description
`X-RateLimit-Status`	JSON array contendo o status de todas as regras de limite aplicadas. JSON array containing the status of all applied limit rules.
`X-RateLimit-Limit`	Limite da regra mais restritiva no momento (mantido para compatibilidade). Limit of the most restrictive rule currently (kept for compatibility).
`X-RateLimit-Remaining`	Número de requisições restantes da regra mais restritiva. Number of remaining requests from the most restrictive rule.
`Retry-After`	Tempo (em segundos) que o cliente deve aguardar antes de tentar novamente (enviado apenas em respostas com status `429 Too Many Requests`). Time (in seconds) the client must wait before trying again (sent only in responses with status `429 Too Many Requests`).

💻 Exemplo do Header `X-RateLimit-Status` / Header Example `X-RateLimit-Status`¶

JSON

[
  { "period": "1s",  "remaining": 2,   "limit": 3 },
  { "period": "1m",  "remaining": 29,  "limit": 30 },
  { "period": "15m", "remaining": 99,  "limit": 100 },
  { "period": "1h",  "remaining": 299, "limit": 300 }
]

❌ Resposta de Erro por Excesso de Requisições / Error Response for Too Many Requests¶

JSON¶

{
  "success": false,
  "errors": ["Rate limit exceeded. Retry after X seconds."]
}