Cadastro de Filiais
Para a habilitação de filiais, existem dois fluxos operacionais que podem ser seguidos:
- Fluxo Completo (Do zero): É o cadastro integral da filial, abrangendo desde dados de endereço e faturamento até informações de representantes legais e avalistas. Neste fluxo, a habilitação segue o processo padrão apresentado anteriormente na documentação, passando por aprovação de documentos e validação de poderes. Este fluxo exige um novo contrato de cessão para a efetiva habilitação do cedente no fundo.
- Fluxo Simplificado (Cadastro Vinculado): Apresentado nesta página, este fluxo trata o cadastro da filial como um vínculo a uma matriz previamente cadastrada. Nele, apenas dados básicos são enviados e uma nova
assignor_registry_keyé criada, porém dados como representantes e avalistas são obrigatoriamente reaproveitados da análise da matriz.
Caso a filial já esteja cadastrada como cedente, também é possível vinculá-la à matriz. Nesse caso, a documentação, representação e avalistas anteriores são descartados, e a mesma passa a herdar os dados da matriz.
Vantagens do Fluxo Facilitado
Existem duas principais vantagens no fluxo de ativação facilitada de filiais:
- Opções de Pagamento: Ao realizar uma operação de cessão com a filial, as contas da matriz também se tornam opções de pagamento.
- Replicação de Configurações: Todas as Configurações de Cessão da matriz são automaticamente replicadas para a filial assim que aprovada, evitando a necessidade da etapa de assinatura de contrato. Para recuperar as novas chaves, recomendamos a utilização do GET de configuração de cessão paginado, tópico 5.3.1.2., com parâmetros como
assignment_contract_key,asset_typeeassignor_document_number, utilizando o contrato formalizado pela matriz como referência.
O fluxo facilitado de filiais exige a presença da seguinte cláusula no contrato mãe formalizado com a matriz para ser utilizado:
CONSIDERANDO que o CEDENTE declara e garante que, caso aplicável, é a matriz e detém plenos poderes para representar juridicamente todas as suas filiais perante a CESSIONÁRIA, inclusive para a prática de todos os atos necessários à formalização e à execução de cessões. O CEDENTE reconhece e assume responsabilidade solidária e ilimitada por todas as obrigações assumidas por suas filiais em decorrência de cessões realizadas junto à CESSIONÁRIA, renunciando, para todos os fins, a qualquer alegação de ausência de poderes ou de autonomia.
Criando uma nova Filial
Por mais que o PLD da matriz já tenha sido realizado, a primeira análise (a de vínculo) de uma filial sempre passa pela etapa de consulta e validação de dados externa, sendo necessário aguardar o hook de aprovação ou reprovação da análise gerada, que é enviada automaticamente.
Request
A assignor_registry_key enviada na requisição deve pertencer à MATRIZ do cedente, e a mesma já deve estar habilitada.
{
"document_number": "32.402.502/0002-16",
"email": "qitechfilial@qitech.com.br",
"phone": {
"international_dial_code": "+55",
"area_code": "11",
"number": "936360269"
},
"address": {
"street": "Rua Maria Carolina dois",
"number": "624",
"neighborhood": "Jardim Paulistano",
"city": "Campinas",
"postal_code": "01445-000",
"uf": "SP",
"country": "BRA"
},
"annual_revenues": 20000,
"accounts": [
{
"account_branch": "0001",
"account_number": "0423223",
"account_digit": "6",
"financial_institution_code": "329",
"account_type": "checking_account",
"default_account": true
}
]
}
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
document_number * | string | Número de documento do cedente (CNPJ). | 14 a 18 |
annual_revenues * | number | Declaração de faturamento anual do cedente, em inteiros. | Mínimo de 1 |
email * | string | Endereço de e-mail do cedente. | 1 a 255 |
phone | object | Objeto referenciando as informações do telefone do cedente. | Ver Definição de Telefone. |
address * | object | Objeto referenciando as informações do endereço do cedente. | Ver Definição de Endereço. |
accounts * | array | Lista de contas de desembolso do cedente. | Ver Definição de Conta. |
*Campos obrigatórios.
Response
{
"assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947",
"status": "pending_registry",
"name": "QI Tech",
"document_number": "32.402.502/0002-16",
"last_analysis": {
"analysis_key": "49bcaaca-6029-4f6f-97a0-d71f7cefb7ae",
"analysis_number": 1,
"status": "sent_to_analysis",
"analysis_related_parties": [
{
"analysis_related_party_key": "65a74b18-0da8-4460-844b-524c9941e615",
"document_number": "802.834.257-41",
"name": "Roberto Carlos",
"documents": []
},
{
"analysis_related_party_key": "f2bc3473-1686-4d15-9a06-b51d25e20cb4",
"document_number": "883.512.866-80",
"name": "Natália Nascimento",
"documents": []
},
{
"analysis_related_party_key": "272cc251-a56d-4b89-82a1-d815a319b9fb",
"passport_number": "C01X00T47",
"name": "Maria Vitoria",
"documents": []
}
],
"documents": [
{
"document_key": "5530af20-f52e-4a2e-b0f3-732e8121f4b3",
"document_type": "social_contract",
"status": "valid",
}
],
"analysis_data": {}
}
}
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
assignor_registry_key | string | Identificador do cadastro. | 36 |
status | string | Status do cadastro. | Ver Enumeradores de status do cadastro. |
name | string | Nome do Cedente. | 1 a 255 |
document_number | string | Documento do Cedente. | 14 a 18 |
last_analysis | object | Objeto de análise. | Ver Definição de Análise. |
Toda informação de representação, avalistas e documentos serão automaticamente replicadas do cadastro da matriz. Entretanto, a conta enviada deve ser de titularidade da filial, caso contrário, futuras transferências falharão.
É importante armazenar a assignor_registry_key, pois ela será utilizada em diversos outros processos, assim como a analysis_key e as analysis_related_party_key.
Erros Tratáveis
| Código | HTTP | Causa | Como resolver |
|---|---|---|---|
| ASR000004 | 404 | Cedente matriz não encontrado para o assignor_registry_key informado. | Garantir que assignor_registry_key na URL corresponda ao cadastro da matriz. |
| ASR000099 | 400 | Cedente pessoa física não pode ter filiais. | Apenas matrizes pessoa jurídica (person_type=legal_person) podem ter filiais. |
| ASR000096 | 400 | Status da matriz não permite ativação de filial. | A matriz deve estar com status=registered para criar uma filial. |
| ASR000097 | 400 | O cadastro referido não é uma matriz. | O assignor_registry_key na URL deve ser de um cadastro com organization_level=headquarters. |
| ASR000098 | 400 | Raiz do CNPJ da filial não corresponde à da matriz. | A raiz (8 primeiros dígitos) do document_number da filial deve ser idêntica à da matriz. |
| ASR000032 | 409 | Esse agente já cadastrou um cedente com esse document_number. | A filial já possui um cadastro vinculado a este agente; utilize o fluxo de vínculo de filial existente. |
| ASR000071 | 404 | Instituição financeira não encontrada para a conta da filial. | Validar o financial_institution_code informado em accounts. |
| ASR000087 | 400 | Informação de conta deve conter apenas números. | Enviar account_branch, account_number e account_digit apenas com dígitos. |
| ASR000081 | 400 | Mais de uma conta padrão foi enviada. | Apenas uma conta deve ter default_account=true. |
Vinculando uma filial já existente à matriz
Caso tanto a filial quanto a matriz já existam em cadastros diferentes, é possível forçar o vínculo entre as duas. Nesse fluxo, todas as informações da filial que não compunham o payload da requisição de criação serão substituídas pelas informações da matriz.
Request
A assignor_registry_key enviada na requisição deve pertencer à MATRIZ do cedente, e a mesma já deve estar habilitada.
{
"branch_assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947",
}
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
branch_assignor_registry_key * | string | Identificador do cadastro. | 36 |
*Campos obrigatórios.
Response
{
"assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947",
"status": "pending_registry",
"name": "QI Tech",
"document_number": "32.402.502/0002-16",
"last_analysis": {
"analysis_key": "49bcaaca-6029-4f6f-97a0-d71f7cefb7ae",
"analysis_number": 1,
"status": "sent_to_analysis",
"analysis_related_parties": [
{
"analysis_related_party_key": "65a74b18-0da8-4460-844b-524c9941e615",
"document_number": "802.834.257-41",
"name": "Roberto Carlos",
"documents": []
},
{
"analysis_related_party_key": "f2bc3473-1686-4d15-9a06-b51d25e20cb4",
"document_number": "883.512.866-80",
"name": "Natália Nascimento",
"documents": []
},
{
"analysis_related_party_key": "272cc251-a56d-4b89-82a1-d815a319b9fb",
"passport_number": "C01X00T47",
"name": "Maria Vitoria",
"documents": []
}
],
"documents": [
{
"document_key": "5530af20-f52e-4a2e-b0f3-732e8121f4b3",
"document_type": "social_contract",
"status": "valid",
}
],
"analysis_data": {}
}
}
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
assignor_registry_key | string | Identificador do cadastro. | 36 |
status | string | Status do cadastro. | Ver Enumeradores de status do cadastro. |
name | string | Nome do Cedente. | 1 a 255 |
document_number | string | Documento do Cedente. | 14 a 18 |
last_analysis | object | Objeto de análise. | Ver Definição de Análise. |
Erros Tratáveis
| Código | HTTP | Causa | Como resolver |
|---|---|---|---|
| ASR000004 | 404 | Cedente matriz ou filial não encontrado. | Garantir que assignor_registry_key na URL pertença à matriz e que branch_assignor_registry_key no body pertença a um cadastro existente do mesmo agente. |
| ASR000099 | 400 | Cedente pessoa física não pode ter filiais. | Apenas matrizes pessoa jurídica podem vincular filiais. |
| ASR000096 | 400 | Status da matriz não permite vínculo de filial. | A matriz deve estar com status=registered. |
| ASR000097 | 400 | O cadastro referido não é uma matriz. | O assignor_registry_key na URL deve ser de um cadastro com organization_level=headquarters. |
| ASR000098 | 400 | Raiz do CNPJ da filial não corresponde à da matriz. | A raiz (8 primeiros dígitos) do document_number da filial deve ser idêntica à da matriz. |
Atualizando dados de uma Filial
Por mais que seja um cadastro vinculado, as informações da filial ainda podem ser atualizadas, porém com algumas restrições:
Informações como email, phone, address e annual_revenues podem ser atualizadas utilizando o mesmo endpoint utilizado para alterar dados da matriz (apresentado abaixo). Entretanto, dados como name, related_parties, guarantors e a documentação em si devem ser atualizados sempre na Matriz. Quando a alteração da matriz é aprovada, todas as filiais vinculadas replicam os dados automaticamente.
Request
{
"email": "qidtvm@qitech.com.br",
"annual_revenues": 1000000,
"address": {
"street": "Rua Maria Carolina",
"number": "624",
"neighborhood": "Jardim Paulistano",
"city": "São Paulo",
"postal_code": "01445-000",
"uf": "SP",
"country": "BRA"
},
"phone": {
"international_dial_code": "+55",
"area_code": "11",
"number": "936360268"
}
}
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
annual_revenues | number | Declaração de faturamento anual do cedente. | - |
email | string | Endereço de e-mail do cedente. | 1 a 255 |
phone | object | Objeto referenciando as informações do telefone do cedente. | Ver Definição de Telefone. |
address | object | Objeto referenciando as informações do endereço do cedente. | Ver Definição de Endereço. |
Caso não deseje alterar um campo, basta não enviá-lo na request.
Response
{
"assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947",
"status": "registred",
"name": "QI Tech",
"document_number": "32.402.502/0002-16",
"last_analysis": {
"analysis_key": "f51a49e1-842c-471f-a0e1-32ee9f12625d",
"analysis_number": 2,
"status": "approved",
"analysis_related_parties": [
{
"analysis_related_party_key": "f361763a-91f5-4688-8e28-cc3f3fbccf9a",
"document_number": "802.834.257-41",
"name": "Roberto Carlos",
"documents": []
},
{
"analysis_related_party_key": "7ea3193b-8e53-40b7-94cf-2d3cc62942e0",
"document_number": "883.512.866-80",
"name": "Natália Nascimento",
"documents": []
},
{
"analysis_related_party_key": "f321f063-5f9a-4964-a24a-52deba128160",
"passport_number": "C01X00T47",
"name": "Maria Vitoria",
"documents": []
}
],
"documents": [
{
"document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017",
"document_type": "social_contract",
"status": "valid",
}
],
"analysis_data": {}
}
}
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
assignor_registry_key | string | Identificador do cadastro. | 36 |
status | string | Status do cadastro. | Ver Enumeradores de status do cadastro. |
name | string | Nome do Cedente. | 1 a 255 |
document_number | string | Documento do Cedente. | 14 a 18 |
last_analysis | object | Objeto de análise. | Ver Definição de Análise. |
Diferente do cadastro de uma matriz, como as alterações não envolvem dados de representação e PLD, a alteração da filial é sempre aprovada AUTOMATICAMENTE.
A manutenção de contas segue exatamente a mesma lógica da manutenção de contas da matriz, segundo a aba 5.2.2.5.