# QI Tech — Investment-as-a-Service › Homologação de Cedente Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 17 página(s). Índice: - Apontamentos de Compliance (/documentation/iaas/homologacao_cedente/cadastro/apontamentos) - Atualização de Cadastro (/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro) - Definição de Assinantes (/documentation/iaas/homologacao_cedente/cadastro/definicao_de_assinantes) - Envio para Análise (/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise) - Envio de Cadastro (/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro) - Envio de Documentos (/documentation/iaas/homologacao_cedente/cadastro/envio_de_documentos) - Cadastro de Filiais (/documentation/iaas/homologacao_cedente/cadastro/filiais) - Contas do cedente (/documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas) - Webhooks (/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise) - Consulta de Análise (/documentation/iaas/homologacao_cedente/consulta/consulta_de_analise) - Consulta de Cedente (/documentation/iaas/homologacao_cedente/consulta/consulta_de_cedente) - Consultar Documentos (/documentation/iaas/homologacao_cedente/contrato_de_cessao/consulta_de_documentos) - Manipulação de contrato (/documentation/iaas/homologacao_cedente/contrato_de_cessao/manutencao_do_contrato) - Contrato de Cessão (/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato) - Recuperação do Contrato (/documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato) - Webhooks do Contrato (/documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato) - Introdução (/documentation/iaas/homologacao_cedente/inicio) --- # Apontamentos de Compliance URL: /documentation/iaas/homologacao_cedente/cadastro/apontamentos Durante o processo de análise cadastral do Cedente, as equipes de Compliance, Risco ou de validação interna podem registrar **apontamentos** (também chamados de *annotations*). Um apontamento é uma solicitação ou questionamento direcionado ao agente responsável pelo cadastro, que precisa ser respondido para que a análise prossiga. Sempre que um apontamento é criado, ele nasce no status `open` e, caso configurado, é disparado um [Webhook de Apontamento](/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise#webhooks-de-apontamento) notificando a abertura. Também é enviado um e-mail aos destinatários configurados para o agente. Após o agente responder ao apontamento, ele passa para o status `closed` e um novo webhook é disparado. :::info Apontamentos só existem enquanto a análise estiver em um dos status `in_manual_analysis`, `pending_internal_validation` ou `in_risk_analysis`. Cada apontamento aceita apenas **uma** resposta. ::: --- ## Consulta Paginada de Apontamentos Recupera a lista de apontamentos de uma análise, permitindo ao agente identificar o que precisa ser respondido. ### Request ENDPOINT /assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotations MÉTODO GET ### Query params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `limit` | integer | Limite de objetos por página (padrão 10, máximo 50). | - | | `page` | integer | Página desejada (inicia em 0). | - | ### Response STATUS 200 ```json title='Response Body' { "data": [ { "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "status": "open", "origin_type": "compliance", "annotation_datetime": "2025-01-22T20:30:23Z", "message": "Anexar detalhes do processo XXXXXXXXXXX." } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000026 | 404 | Agente não encontrado para a `AGENT-KEY` informada. | Verificar se a chave do agente autenticado está correta. | --- ## Consulta de Apontamento por Chave ### Request ENDPOINT /assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY MÉTODO GET ### Response STATUS 200 ```json title='Response Body' { "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "status": "closed", "origin_type": "compliance", "annotation_datetime": "2025-01-22T20:30:23Z", "message": "Anexar detalhes do processo XXXXXXXXXXX.", "response": "Segue autos do processo.", "response_datetime": "2025-01-23T14:05:11Z", "attached_document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a" } ``` :::info Os campos `response`, `response_datetime` e `attached_document_key` só são retornados quando o apontamento já foi respondido e/ou possui um documento anexado. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000026 | 404 | Agente não encontrado para a `AGENT-KEY` informada. | Verificar se a chave do agente autenticado está correta. | | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000043 | 404 | Apontamento não encontrado para o `annotation_key` informado. | Verificar se o `annotation_key` pertence à análise indicada. | --- ## Resposta ao Apontamento Envia a resposta do agente a um apontamento. Opcionalmente, é possível anexar um documento em PDF que comprove ou complemente a resposta. ### Request ENDPOINT /assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY MÉTODO PUT ```json title='Request Body' { "response": "Segue autos do processo.", "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg==" } ``` ### Objeto de Resposta | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `response` * | string | Texto de resposta ao apontamento. | 1 - 3000 | | `document_b64` | string | Binário do arquivo em PDF, codificado em Base64. | - | *Campos obrigatórios. ### Response STATUS 202 ```json title='Response Body' { "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "status": "closed", "origin_type": "compliance", "annotation_datetime": "2025-01-22T20:30:23Z", "message": "Anexar detalhes do processo XXXXXXXXXXX.", "response": "Segue autos do processo.", "response_datetime": "2025-01-23T14:05:11Z", "attached_document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a" } ``` ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000026 | 404 | Agente não encontrado para a `AGENT-KEY` informada. | Verificar se a chave do agente autenticado está correta. | | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000043 | 404 | Apontamento não encontrado para o `annotation_key` informado. | Verificar se o `annotation_key` pertence à análise indicada. | | ASR000045 | 400 | O apontamento não está mais em status `open` e não aceita mais respostas. | Só é possível responder apontamentos com status `open`. | | ASR000044 | 400 | O apontamento já foi respondido. | Cada apontamento aceita apenas uma resposta. | | ASR000005 | 400 | Formato de arquivo inválido. | Enviar `document_b64` como string em base64 válida. | | ASR000060 | 400 | O arquivo enviado não é um PDF válido. | O conteúdo decodificado de `document_b64` deve ser um PDF. | | ASR000059 | 400 | Tamanho do arquivo excede o limite. | Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). | --- ## Consulta de Documento do Apontamento Recupera uma URL temporária para download do documento anexado a um apontamento. ### Request ENDPOINT /assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY/document/DOCUMENT_KEY MÉTODO GET ### Response STATUS 200 ```json title='Response Body' { "document_url": "https://assignor-bucket.s3.amazonaws.com/8e515a17-8b4d-49a3-aed6-47c9574e426a?..." } ``` :::info A `document_url` retornada é uma URL pré-assinada com validade de 24 horas. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000026 | 404 | Agente não encontrado para a `AGENT-KEY` informada. | Verificar se a chave do agente autenticado está correta. | | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000043 | 404 | Apontamento não encontrado para o `annotation_key` informado. | Verificar se o `annotation_key` pertence à análise indicada. | | ASR000006 | 404 | Documento não encontrado para o `document_key` informado. | Verificar se o `document_key` corresponde ao documento anexado ao apontamento. | --- ## Objeto de Apontamento | Campo | Tipo | Descrição | |-------|------|-----------| | `annotation_key` | string | Identificador único do apontamento. | | `analysis_key` | string | Chave da análise à qual o apontamento pertence. | | `assignor_registry_key` | string | Chave do cedente. | | `status` | string | Status atual do apontamento. Ver **[Annotation Status](#annotation-status)**. | | `origin_type` | string | Origem do apontamento. Ver **[Annotation Origin Type](#annotation-origin-type)**. | | `annotation_datetime` | string | Data e hora de criação do apontamento (ISO 8601). | | `message` | string | Mensagem do apontamento registrada pela equipe da QI DTVM. | | `response` | string | Resposta enviada pelo agente (presente após a resposta). | | `response_datetime` | string | Data e hora da resposta (presente após a resposta). | | `attached_document_key` | string | Chave do documento anexado à resposta (quando houver). | ### Annotation Status | Enumerador | Descrição | | ---------- | --------- | | **created** | Apontamento criado, ainda não disponibilizado. | | **open** | Aberto e aguardando resposta do agente. | | **closed** | Respondido e encerrado. | ### Annotation Origin Type | Enumerador | Descrição | | ---------- | --------- | | **compliance** | Apontamento originado pela equipe de Compliance (análise manual). | | **risk_analysis** | Apontamento originado pela equipe de Risco. | | **internal** | Apontamento originado na validação interna. | --- # Atualização de Cadastro URL: /documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro É de responsabilidade do gestor manter os dados dos cedentes atualizados, de acordo com a situação atual da companhia. Este comprometimento é de extrema importancia, tanto para manter as análises de PLD atualizadas quanto para atualizar os grupos de assinantes, que mudam constantemente e expiram, sendo necessária uma nova análise. Além disso, a cada 2 anos, automaticamente é gerada uma nova análise para garantir a atualização periódica dos mesmos. :::warning Aviso É de responsabilidade do gestor manter os dados do cedente atualizados e refletindo a realidade da companhia. ::: Ao atualizar um cadastro, independente de qual campo for alterado, uma nova análise será gerada, a qual exigirá novos documentos de acordo com as alterações relalizadas. As análises seguem um sequencial, e podem falhar inúmeras vezes até serem finalmente aprovadas pelo compliance. As alterações só serão aplicadas após a análise ser concluída com sucesso. Caso as partes relacionadas sejam alteradas, haverá uma etapa de validação dos grupos de assinantes do cedente. Vale ressaltar que caso uma parte relacionada ou um avalista NÃO for enviado, o mesmo será considerado EXCLUÍDO. :::info Caso uma análise esteja em andamento, e uma atualização cadastral seja enviada, a última análise em aberto será automaticamente fechada, sendo recusada, com motivo "assignor_update". ::: --- ## Atualização de Cadastro de Cedente Pessoa Jurídica ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY MÉTODO PUT ```json title='Request Body' { "email": "qidtvm@qitech.com.br", "annual_revenues": 1000000, "is_in_national_financial_system": true, "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" }, "related_parties": [ { "name": "Natália Nascimento", "document_number": "883.512.866-80", "related_party_type": "attorney", "nationality": "BRA", "direct_beneficiary": true, "is_representative": true, "email": "natalia.nascimento@yopmail.com", "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" } }, { "name": "Maria Vitoria", "related_party_type": "president", "nationality": "DEU", "passport_number": "C01X00T47", "direct_beneficiary": true, "is_representative": false }, { "name": "Roberto Carlos", "document_number": "802.834.257-41", "related_party_type": "director", "nationality": "BRA", "direct_beneficiary": false, "company_country": "NZL", "company_registry_number": "4984037284610", "is_representative": true, "email": "roberto.carlos@yopmail.com", "phone": { "international_dial_code": "+64", "area_code": "11", "number": "936360268" } } ], "guarantors": [ { "name": "Avalista PF", "document_number": "172.775.419-01", "person_type": "natural_person", "email": "email@avalista.com" }, { "name": "Avalista PJ", "document_number": "65.679.662/0001-85", "person_type": "legal_person", "email": "email@avalista.com", "guarantor_representatives": [ { "name": "Assinante do Avalista", "document_number": "244.412.084-13", "email": "emailrepresentante@avalista.com" } ] }, ] } ``` --- ### Definição do Cedente | 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 | | `is_in_national_financial_system` | boolean | Indicador se o cedente é integrante do SFN. | - | | `phone` | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `related_parties` | array | Lista de partes relacionadas da empresa.| Ver **[Definição de Parte Relacionada](#definição-de-parte-relacionada)**. | | `guarantors` | array | Lista de avalistas do cedente.| Ver **[Definição de Avalista](#definição-de-avalista)**. | Caso não deseje alterar um campo, basta não enviá-lo na request. Para listas, como é o caso de `related_parties` e `guarantors`, caso uma lista vazia seja enviada, ou uma parte previamente indicada na lista, e não indicada na nova, será tratado como exclusão. ### Response STATUS 200 ```json title='Response Body' { "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "registred", "name": "QI Tech", "document_number": "32.402.502/0001-35", "last_analysis": { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 2, "status": "pending_documents", "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "document_number": "802.834.257-41", "name": "Roberto Carlos", "documents": [] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "883.512.866-80", "name": "Natália Nascimento", "documents": [] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "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](#assignor-registry-status)**. | | `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](#definição-de-análise)**. | :::info É importante armazenar a `analysis_key` e as `analysis_related_party_key` que serão utilizadas para envio de documentos do cedente e das partes relacionadas. ::: --- :::caution Atenção! Ao atualizar o cadastro de um cedente, uma nova análise cadastral é gerada, resultando em uma nova `analysis_key` e novas `analysis_related_party_key`. O cadastro só será efetivamente atualizado após a aprovação desta nova análise. ::: :::caution Importante! Não é possível atualizar dados essenciais do cedente como **Número do Documento**, **Tipo de Pessoa**. Os dados cadastrais passíveis de alteração incluem: - Nome/Razão Social; - Email; - Endereço; - Telefone; - Faturamento; - Participante do SFN; - Partes Relacionadas (inclusão e alteração de vigentes); - Avalistas (inclusão e alteração de vigentes); ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` existe e pertence ao agente autenticado. | | ASR000100 | 400 | Campo enviado não pode ser atualizado em uma filial. | Para filiais, somente `email`, `phone`, `address` e `annual_revenues` podem ser atualizados. Para alterar `name`, `is_in_national_financial_system`, `related_parties` ou `guarantors`, atualizar o cadastro da matriz. | | ASR000056 | 400 | Pessoa física não pode ser participante do Sistema Financeiro Nacional. | Para cedentes pessoa física, enviar `is_in_national_financial_system=false` ou omitir o campo. | | ASR000054 | 400 | Cedente pessoa jurídica deve ter pelo menos 1 parte relacionada. | Garantir que `related_parties` (após a atualização) tenha ao menos um item para cedentes pessoa jurídica. | | ASR000057 | 400 | Cedente pessoa jurídica deve ter pelo menos 1 representante assinante. | Garantir que ao menos uma parte relacionada tenha `is_representative=true`. | | ASR000011 | 400 | Número de documento de parte relacionada duplicado. | Cada `document_number` em `related_parties` deve ser único. | | ASR000041 | 400 | Email obrigatório para representante. | Para partes relacionadas com `is_representative=true`, informar `email`. | | ASR000058 | 400 | Pessoa estrangeira sem CPF não pode ser assinante. | Estrangeiros sem `document_number` (CPF) não podem ter `is_representative=true`. | | ASR000078 | 400 | Número de documento de avalista duplicado. | Cada avalista em `guarantors` deve ter `document_number` único. | | ASR000079 | 400 | Avalista pessoa física não pode receber representantes. | Não enviar `guarantor_representatives` para avalistas com `person_type=natural_person`. | | ASR000080 | 400 | Documento de representante de avalista duplicado. | Cada representante em `guarantor_representatives` deve ter `document_number` único. | | ASR000091 | 400 | Avalista pessoa jurídica deve ter pelo menos um representante. | Para `person_type=legal_person`, enviar pelo menos um item em `guarantor_representatives`. | --- ## Definições ### Definição de Endereço | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `street` * | string | Nome da rua. | 1 a 255 | | `number` * | string | Número do endereço. | 1 a 4 | | `neighborhood` * | string | Bairro. | 1 a 255 | | `city` * | string | Cidade. | 1 a 255 | | `uf` * | string | Sigla do estado. | 2 | | `complement` | string | Complemento do endereço. | 1 a 255 | | `postal_code` * | string | Código postal. | 9 (formato: XXXXX-XXX) | | `country` * | string | País (sigla). | 3 | *Campos obrigatórios. --- ### Definição de Telefone | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `international_dial_code` * | string | Código internacional de discagem. | 1 a 3 | | `area_code` * | string | Código de área. | 2 | | `number` * | string | Número de telefone. | 8 a 9 | *Campos obrigatórios. --- ### Definição de Parte Relacionada | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome da parte relacionada. | 1 a 255 | | `document_number` ** | string | Número de documento do beneficiário (CPF). | 14 a 18 | | `passport_number` ** | string | Número de documento do beneficiário estrangeiro. | 8 a 9 | | `related_party_type` * | string | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** | | `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 | | `direct_beneficiary` * | boolean | Beneficiário diretamente ou indiretamente ligado ao cedente. | 1 a 255 | | `is_representative` * | boolean | Indicador se a parte relacionada é representante assinante do cedente. | 1 a 255 | | `company_registry_number` *** | string | Caso não seja diretamente ligado ao cedente, à qual companhia o mesmo está ligado. | 1 a 255 | | `company_country` *** | string | País onde a companhia-elo entre o beneficiário e o cedente está registrada. | 3, de acordo com a ISO 3166-1 alpha-3 | | `address` | object | Objeto referenciando as informações do endereço do representante. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `email` **** | string | Endereço de e-mail do representante. | 1 a 255 | | `phone` | object | Objeto referenciando as informações do telefone do representante. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `marital_status` | string | Estado civil da parte relacionada. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão da parte relacionada. | 1 a 255. | *Campos obrigatórios. **document_number obrigatório para brasileiros, e passport_number para estrangeiros. ***Campos obrigatórios caso a parte relacionada não seja beneficiário diretamente ligada ao cedente. ****Campos exigidos apenas para representantes assinantes. --- ### Definição de Análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_key` * | string | Identificador da análise. | 36 | | `analysis_number` * | integer | Número sequencial da análise. | - | | `status` * | string | Status da análise. | Ver **[Enumeradores de status de análise](#analysis-status)**. | | `analysis_related_parties` * | array | Partes Relacionadas da análise. | Ver **[Definição de Partes Relacionadas de Análise](#definição-de-partes-relacionadas-de-análise)**. | | `documents` * | array | Documentos da anáise. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | | `analysis_data` * | object | Payload da request que originou a análise. | - | | `analysis_datetime` * | string | Objeto date time da criação da análise. | - | | `reproval_reason` | string | Enumerador com o motivo de rejeição da análise. | Ver **[Enumeradores de motivo de reprovação](#analysis-reproval-reason)**. | | `reproval_details` | string | Campo livre com detalhes da rejeição da análise. | - | *Campos obrigatórios. --- ### Definição de Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do Avalista. | 3 - 255 | | `document_number` * | string | Número de documento do avalista. | 14 a 18 | | `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - | | `email` * | string | Endereço de e-mail do avalista. | 1 a 255 | | `nationality` | string | País de origem do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 | | `phone` | object | Objeto referenciando as informações do telefone do avalista. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` | object | Objeto referenciando as informações do endereço do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `guarantor_representatives` | array | Assinantes do Avalista - Apenas para avalista pessoa jurídica. | Ver **[Definição de Representante do Avalista](#definição-de-representante-do-avalista)**. | | `marital_status` | string | Estado civil do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão do avalista. | 1 a 255. | *Campos obrigatórios. Os representantes do avalista devem ser enviados apenas para o avalista pessoa jurídica. :::warning Atenção Tanto o avalista quanto os representantes também serão adicionados à anáise gerada, sendo necessário enviar os documentos padrão de acordo com o tipo de pessoa do mesmo. Também passarão pelo processo de compliance, podendo gerar apontamentos. ::: --- ### Definição de Representante do Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do Representante. | 3 - 255 | | `document_number` * | string | Número de documento do representante do avalista - obrigatóriamente pessoa física. | 14 | | `email` * | string | Endereço de e-mail do representante do avalista. | 1 a 255 | | `nationality` | string | País de origem do representante do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 | | `address` | object | Objeto referenciando as informações do endereço do representante do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `phone` | object | Objeto referenciando as informações do telefone do representante do avalista. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `marital_status` | string | Estado civil do representante do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão do representante do avalista. | 1 a 255. | --- ### Definição de Documentos | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` * | string | Identificador do documento. | 36 | | `document_type` * | string | Tipo do documento. | Ver **[Enumeradores de tipo de documento](#document-type)**. | | `status` | string | Status do documento. | Ver **[Enumeradores de status de documento](#document-status)**. | | `observation` | string | Observações enviadas. | - | *Campos obrigatórios. --- ### Definição de Partes Relacionadas de análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_representative_key` * | string | Identificador do representante. | 36 | | `document_number` * | string | Número de documento do representante. | 14 a 18 | | `name` | string | Nome do beneficiário. | 1 a 255 | | `documents` * | enumerador | Documentos da anáise do representante. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | *Campos obrigatórios. --- # Enumeradores ### Assignor Registry Status | Enumerador | Descrição | | -------------------------- | ----------------- | | **pending_registry** | Pendente Registro | | **registered** | Registrado | --- ### Analysis Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_documents** | Pendente Documentos | | **sent_to_analysis** | Enviado para Análise | | **pending_internal_validation** | Em Validação de documentos | | **in_manual_analysis** | Em Análise Manual de Compliance | | **approved** | Aprovado | | **reproved** | Reprovado | --- ### Related Party Type | Enumerador | Descrição | | ----------------------- | ------------- | | **president** | Presidente | | **partner** | Sócio | | **administrator** | Administrador | | **director** | Diretor | | **manager** | Gestor | | **attorney** | Procurador | --- ### Document Status | Enumerador | Descrição | | ----------------------- | ------------- | | **created** | Criado | | **valid** | Válido | | **invalid** | Inválido | | **canceled** | Cancelado | | **accepted** | Aceito, porém não validado | --- ### Document Type | Enumerador | Descrição | | ---------------------------- | -------------------------- | | **cnh** | CNH. | | **rg_back** | RG parte traseira. | | **rg_front** | RG parte frontal. | | **passport** | Passaporte - exclusivo para estrangeiros. | | **national_migration_registry** | Registro Nacional de Migração. | | **cin_digital** | Carteira de Identidade Nacional (Digital). | | **passport** | Passaporte - exclusivo para estrangeiros. | | **social_contract** | Contrato/Estatuto Social. | | **cnpj_card** | Cartão CNPJ. | | **commercial_board_certificate** | Certidão Simplidicada da Junta Comercial. | | **board_election_record** | Ata de Eleição da Diretoria Vigente. | | **power_of_attorney** | Procuração - obrigatório caso o representante seja um procurador. | | **marital_power_of_attorney** | Procuração Uxória - disponível apenas para cônjuges. | | **compliance_statement** | Parecer de Compliance. | | **financial_statement** | Demonstração Financeira. | | **credit_report** | Ata/Parecer de Crédito. | | **manager_statement** | Parecer/Ficha do Gestor. | | **visit_report** | Relatório de Visita. | | **proof_of_residence** | Comprovante de Residência. | | **credit_agency_consulation** | Consulta aos órgãos de Proteção de Crédito. | | **annual_revenues_declaration** | Declaração de Faturamento. | | **financial_institutions_declaration** | Declaração de Relacionamento Bancário. | | **additional_document** | Documento adicional - livre. | --- ### Analysis Reproval Reason | Enum | Description | |--------------|---------------| | **assignor_update** | Análise cancelada devido à atualização cadastral posterior | | **insuficient_documents** | Documentação mínima para comprovação de poderes não enviada | | **compliance_reproval** | Reprovação de vínculo por análise do time de compliance | | **unidentified_related_parties** | Parte relacionada enviada, porém vinculo não comprovado | | **invalid_documents** | Documentação inválida/expirada | | **missing_related_parties** | Parte relacionada obrigatória não enviada | --- ### Marital Status | Enum | Description | |--------------|---------------| | **single** | Solteiro(a) | | **married** | Casado(a) | | **widower** | Viúvo(a) | | **divorced** | Divorciado(a) | | **separated** | Separado(a) | | **stable_union** | Em União Estável | --- ### Property System | Enum | Descrição | | --------------------------------- | -------------------------------------- | | **total_communion_of_goods** | Comunhão Total de Bens | | **partial_communion_of_goods** | Comunhão Parcial de Bens | | **total_separation_of_goods** | Separação Total de Bens | | **final_participation_of_acquisitions** | Participação Final nos Aquestos | | **compulsory_separation_of_goods** | Separação Obrigatória de Bens | --- # Definição de Assinantes URL: /documentation/iaas/homologacao_cedente/cadastro/definicao_de_assinantes Após o envio do cadastro do cedente, é possível, **opcionalmente**, definir conjuntos customizados de assinantes para a operação. Esses conjuntos determinam quais partes relacionadas (do cedente ou de avalistas) devem assinar cada tipo de documento, com possibilidade de regras por tipo de produto. Caso nenhum conjunto customizado seja enviado, o sistema utiliza os conjuntos padrão definidos pela administradora. :::info Informação Os conjuntos de assinantes (`signer_group_sets`) representam grupos de assinantes vinculados a um proprietário (`owner`), que pode ser o **cedente** (`assignor_registry`) ou uma **parte relacionada de análise** (`analysis_related_party`, de avalistas). A definição customizada permite, por exemplo, exigir múltiplos assinantes, ou restringir quem pode assinar determinado produto. ::: :::warning Atenção A definição de conjuntos customizados deve ocorrer antes da etapa de [Envio para Análise](/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise). Após o envio para análise, os conjuntos vigentes serão utilizados nas assinaturas dos contratos de cessão. ::: --- ## Definição de Conjunto Customizado para o Cedente Permite ao cliente substituir o conjunto padrão de assinantes do cedente por um ou mais conjuntos customizados, organizados por produto. Os assinantes informados devem corresponder a partes relacionadas previamente cadastradas como representantes do cedente. ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/custom_signer_groups MÉTODO POST ```json title='Request Body' { "signer_group_sets": [ { "product": "assignment_contract", "signer_groups": [ { "minimum_required_signers": 2, "signers": [ { "document_number": "883.512.866-80", "is_required_signer": true }, { "document_number": "802.834.257-41", "is_required_signer": false } ], "expiration": "2026-12-31" } ] }, { "product": "commercial_paper", "signer_groups": [ { "minimum_required_signers": 1, "signers": [ { "document_number": "883.512.866-80", "is_required_signer": true } ], "expiration": "2026-12-31" } ] } ] } ``` ### Response STATUS 204 Sem conteúdo no corpo de resposta. :::info Informação A criação de um conjunto customizado para o cedente substitui o conjunto `main` (padrão) vigente para o produto informado. Apenas os conjuntos com `status` ativo são utilizados nas assinaturas. ::: :::warning Atenção Ao enviar, o grupo de assinantes nasce no status `in_analysis`. Signer groups sets neste status não são enviados para assinatura. Com a aprovação do cadastro, o grupo passa para o status `valid`, e só então, será utilizado para assinaturas acima do `main` signer group. ::: :::warning Atenção Caso o `custom` signer group enviado seja **menos restritivo** que o validado pela Administradora, a análise será **negada**. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000066 | 400 | Status da análise não permite definição de grupos customizados. | A análise deve estar em `pending_documents` para receber grupos customizados. | | ASR000109 | 404 | Tipo de produto inválido. | Usar um valor válido para `product` (ver enum [Product Type](#product-type)). | | ASR000118 | 400 | Signatário inválido. | O `document_number` enviado em `signers` deve corresponder a um representante já cadastrado para o cedente, com `is_representative=true`. | --- ## Definição de Conjunto Customizado para Parte Relacionada Permite definir conjuntos customizados para uma parte relacionada específica do cedente — como avalistas (`guarantors`) — utilizando a `analysis_related_party_key` retornada na criação da análise. :::info Informação Lembre-se de que avalistas são representados como `analysis_related_party`. Logo, este endpoint é o ponto único para customizar assinantes de qualquer parte vinculada à análise (representantes do cedente, avalistas e representantes de avalistas). ::: ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/related_party/ANALYSIS_RELATED_PARTY_KEY/custom_signer_groups MÉTODO POST ```json title='Request Body' { "signer_group_sets": [ { "product": "assignment_contract", "signer_groups": [ { "minimum_required_signers": 1, "signers": [ { "document_number": "244.412.084-13", "is_required_signer": true } ], "expiration": "2026-12-31" } ] } ] } ``` ### Response STATUS 204 Sem conteúdo no corpo de resposta. :::warning Atenção Ao enviar, o grupo de assinantes nasce no status `in_analysis`. Signer groups sets neste status não são enviados para assinatura. Com a aprovação do cadastro, o grupo passa para o status `valid`, e só então, será utilizado para assinaturas acima do `main` signer group. ::: :::warning Atenção Caso o `custom` signer group enviado seja **menos restritivo** que o validado pela Administradora, a análise será **negada**. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000035 | 404 | Parte relacionada da análise não encontrada para o `analysis_related_party_key` informado. | Verificar se o `analysis_related_party_key` corresponde a um avalista ou representante de avalista da análise. | | ASR000066 | 400 | Status da análise não permite definição de grupos customizados. | A análise deve estar em `pending_documents` para receber grupos customizados. | | ASR000109 | 404 | Tipo de produto inválido. | Usar um valor válido para `product` (ver enum [Product Type](#product-type)). | | ASR000118 | 400 | Signatário inválido. | O `document_number` enviado em `signers` deve corresponder a um representante já cadastrado para a parte relacionada (avalista ou representante de avalista). | --- ## Consulta de Conjuntos de Assinantes Esse endpoint permite ao cliente consultar os conjuntos de assinantes existentes para o cedente e suas partes relacionadas, incluindo os conjuntos padrão gerados automaticamente. É útil para identificar `signer_group_set_key` e estrutura atual antes de criar uma versão customizada. ### Request ENDPOINT /assignor_registry/signer_group_sets MÉTODO GET #### Query Parameters | Campo | Tipo | Descrição | |-------|------|-----------| | `limit` | integer | Quantidade de itens por página (0 a 50). Padrão: 10. | | `page` | integer | Página a ser consultada, iniciando em 0. Padrão: 0. | | `owner_key` | string | Filtra pelo identificador do proprietário (cedente ou parte relacionada). | | `owner_type` | string | Tipo do proprietário. Ver **[Owner Type](#owner-type)**. | | `owner_document_number` | string | Documento do proprietário. Exige `owner_type` para ser utilizado. | | `product_type` | string | Filtra por tipo de produto. Ver **[Product Type](#product-type)**. | ### Response STATUS 200 ```json title='Response Body' { "data": [ { "signer_group_set_key": "f2c1e4a8-91d2-4f10-8a3b-7e5c9b2d4a6e", "owner_key": "c4295375-4077-4092-a258-5bcdf8875907", "owner_type": "assignor_registry", "product_type": "assignment_contract", "signer_group_set_type": "custom", "status": "active", "signer_groups": [ { "minimum_required_signers": 2, "signers": [ { "document_number": "883.512.866-80", "is_required_signer": true }, { "document_number": "802.834.257-41", "is_required_signer": false } ], "expiration": null } ] } ], "limit": 10, "page": 0, "is_last_page": true } ``` ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000121 | 400 | `owner_document_number` enviado sem `owner_type`. | Ao filtrar por `owner_document_number`, sempre informar também `owner_type`. | | ASR000120 | 400 | Valor de `status` inválido no filtro. | Usar um valor válido para o filtro `status` (ver enum [Signer Group Set Status](#signer-group-set-status)). | --- ## Definições ### Definição de Conjunto de Assinantes (Signer Group Set) | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `signer_group_set_key` | string | Identificador único do conjunto. | 36 | | `owner_key` | string | Identificador do proprietário. Pode ser `assignor_registry_key` ou `analysis_related_party_key`. | 36 | | `owner_type` | string | Tipo do proprietário. | Ver **[Owner Type](#owner-type)**. | | `product_type` | string | Tipo de produto ao qual o conjunto está associado. | Ver **[Product Type](#product-type)**. | | `signer_group_set_type` | string | Tipo do conjunto (`main` ou `custom`). | Ver **[Signer Group Set Type](#signer-group-set-type)**. | | `status` | string | Status do conjunto. | Ver **[Signer Group Set Status](#signer-group-set-status)**. | | `signer_groups` | array | Lista de grupos de assinantes que compõem o conjunto. | Ver **[Definição de Grupo de Assinantes](#definição-de-grupo-de-assinantes-signer-group)**. | --- ### Definição de Item de Envio (Signer Group Set Item) Estrutura utilizada no corpo das requisições de criação de conjuntos customizados. | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `product` * | string | Tipo de produto ao qual o conjunto será associado. | Ver **[Product Type](#product-type)**. | | `signer_groups` * | array | Lista de grupos de assinantes (mínimo 1). | Ver **[Definição de Grupo de Assinantes](#definição-de-grupo-de-assinantes-signer-group)**. | *Campos obrigatórios. --- ### Definição de Grupo de Assinantes (Signer Group) | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `minimum_required_signers` * | number | Quantidade mínima de assinantes do grupo necessários para validar a assinatura. | Mínimo 1 | | `signers` * | array | Lista de assinantes do grupo (mínimo 1). | Ver **[Definição de Assinante](#definição-de-assinante-signer)**. | | `expiration` | string | Data de expiração do grupo no formato `YYYY-MM-DD`. | 10 | *Campos obrigatórios. --- ### Definição de Assinante (Signer) | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_number` * | string | CPF do assinante no formato `XXX.XXX.XXX-XX`. | 14 | | `is_required_signer` * | boolean | Indica se o assinante é obrigatório no grupo. | - | *Campos obrigatórios. :::info Informação Os `document_number` enviados devem corresponder a partes relacionadas (representantes do cedente, ou representantes do avalista em questão) presentes no cadastro do cedente. Documentos que não estiverem associados ao cedente serão rejeitados. ::: --- # Enumeradores ### Owner Type | Enumerador | Descrição | |------------|-----------| | **assignor_registry** | Conjunto vinculado ao cedente. | | **analysis_related_party** | Conjunto vinculado a uma parte relacionada da análise (avalistas). | --- ### Product Type | Enumerador | Descrição | |------------|-----------| | **assignment_contract** | Contrato de cessão (utilizado por padrão). | | **commercial_paper** | Nota Comercial (Cadastro único com a plataforma de escrituração). | --- ### Signer Group Set Type | Enumerador | Descrição | |------------|-----------| | **main** | Conjunto padrão, gerado da análise da Administradora. | | **custom** | Conjunto customizado, criado pelo cliente sobrepondo o conjunto `main`. | --- ### Signer Group Set Status | Enumerador | Descrição | |------------|-----------| | **in_analysis** | Conjunto enviado e atrelado à análise em aberto. | | **active** | Conjunto vigente e utilizado nas assinaturas. | | **inactive** | Conjunto substituído por uma versão mais recente ou desativado. | --- # Envio para Análise URL: /documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise Após todos os documentos estarem devidamente anexados, deve ser disparada a análise, a qual enviará todos os dados para nosso sistema de anti-fraude, para análise de compliance. Caso recusada, deverá ser feita uma nova análise, caso aprovada, haverá uma etapa posterior de validação interna de representantes, onde será tambem monstada a estrutura de assinantes do cedente, para finalmente começar a operação com o mesmo, disponibilizando a criação de contratos mãe entre o cedente e o fundo. --- ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY MÉTODO PUT ```json title='Request Body' { "analysis_status":"sent_to_analysis" } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_status` * | string | Novo status da análise a ser enviado (deve ser igual a **sent_to_analysis**). | 1 a 50 | *Campo obrigatório. ### Response STATUS 200 ```json title='Response Body' { "analysis_key": "2b1fa466-4d36-48e9-b6e3-776a1b700b9f", "analysis_number": 1, "assignor_registry_key": "d0a93900-457d-496a-8326-480ecaf946c3", "status": "sent_to_analysis" } ``` :::caution Atenção! Uma análise deve ser efetivamente enviada somente após anexar todos os documentos pertinentes. Uma vez enviada a análise, não será mais possível anexar novos documentos. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000040 | 400 | A análise não pertence ao cedente informado. | Garantir que `analysis_key` e `assignor_registry_key` correspondam à mesma análise. | | ASR000034 | 400 | A análise não pode receber este status. | A análise só pode ser enviada quando estiver no status `pending_documents`. Verifique o status atual em [Consulta de Análise](/documentation/iaas/homologacao_cedente/consulta/consulta_de_analise). | | ASR000038 | 400 | Status enviado é inválido. | O campo `analysis_status` deve ser exatamente `sent_to_analysis`. | | ASR000009 | 400 | A análise não possui todos os documentos obrigatórios do cedente. | Anexar os documentos exigidos para o tipo de pessoa do cedente antes de disparar a análise. Ver [Envio de Documentos](/documentation/iaas/homologacao_cedente/cadastro/envio_de_documentos). | | ASR000015 | 400 | Uma parte relacionada da análise não possui todos os documentos obrigatórios. | Anexar os documentos exigidos da parte relacionada indicada pela `analysis_related_party_key` no erro antes de disparar a análise. | --- # Envio de Cadastro URL: /documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro Na primeira etapa de cadastro do cedente, são informados os dados do mesmo, conforme definidos abaixo. Vale relembrar que, apenas enviar os dados, não cria um cedente operacional, o mesmo só será ativado após a conclusão bem sucedida das análises dos documentos do mesmo. Obrigatoriamente para pessoas jurídicas, e opcionalmente em pessoas físicas, é possível cadastrar partes relacionadas, que representam os beneficiários finais ligados ao cedente. :::info Informação Um beneficiário final é definido como o indivíduo, ou grupo de indivíduos, com relevância significativa na empresa ou conglomerado, com poder decisório ou participação significativa na grade societária. Para fins de cadastro, devem ser levados em conta quaisquer associados com participação superior a 15% na companhia, ou no conglomerado do qual fazem parte, ou, caso não haja participação tão relevante, os três maiores em ordem decrescente. ::: Caso o beneficiário relevante seja uma outra empresa, deve-se atribuir os seus beneficiários finais, indicados como beneficiários indiretos. Além disso, são considerados partes relacionadas quaisquer procuradores, gestores, e diretores envolvidos na operação, que serão os representantes assinantes do cedente na mesma. Os representantes assinantes são partes relacionadas responsáveis por acompanhar e assinar os documentos direcionados ao cedente pelo nosso sistema, sendo necessária comprovação do vínculo, no caso de empresas, por meio do quadro societário, ou de diretores, ou com uma procuração. Não é possível cadastrar uma parte relacionada que não seja um procurador para um cedente pessoa física. Além disso, é necessário indicar se a parte relacionada considerada beneficiário final tem vínculo direto ou indireto com o cedente. :::info Informação No ambiente de Homologação, temos a seguinte regra para aprovações: CPF/CNPJ com início 1: Reprovação automática; CPF/CNPJ com início 8: Pendente Validação Manual; O restante é aprovado automaticamente. ::: --- ## Cadastro de Cedente ### Request ENDPOINT /assignor_registry/assignor_registry MÉTODO POST ```json title='Request Body' { "name": "QI Tech", "document_number": "32.402.502/0001-35", "person_type": "legal_person", "email": "qitech@qitech.com.br", "annual_revenues": 1000000, "is_in_national_financial_system": true, "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" }, "related_parties": [ { "name": "Natália Nascimento", "document_number": "883.512.866-80", "related_party_type": "attorney", "nationality": "BRA", "address": { "street": "Rua Maria Carolina", "number": "624", "neighborhood": "Jardim Paulistano", "city": "São Paulo", "postal_code": "01445-000", "uf": "SP", "country": "BRA" }, "direct_beneficiary": true, "is_representative": true, "email": "natalia.nascimento@yopmail.com", "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" } }, { "name": "Maria Vitoria", "related_party_type": "president", "nationality": "DEU", "passport_number": "C01X00T47", "direct_beneficiary": true, "is_representative": false }, { "name": "Roberto Carlos", "document_number": "802.834.257-41", "related_party_type": "director", "nationality": "BRA", "direct_beneficiary": false, "company_country": "NZL", "company_registry_number": "4984037284610", "is_representative": false, "email": "roberto.carlos@yopmail.com", "phone": { "international_dial_code": "+64", "area_code": "11", "number": "936360268" } } ], "accounts": [ { "account_branch": "0001", "account_number": "7912584", "account_digit": "1", "financial_institution_code": "329", "account_type": "checking_account", "default_account": true }, { "account_branch": "0001", "account_number": "8758931", "account_digit": "5", "financial_institution_code": "329", "account_type": "escrow_account", "default_account": false } ], "guarantors": [ { "name": "Avalista PF", "address": { "street": "Rua Maria Carolina", "number": "624", "neighborhood": "Jardim Paulistano", "city": "São Paulo", "postal_code": "01445-000", "uf": "SP", "country": "BRA" }, "document_number": "172.775.419-01", "person_type": "natural_person", "email": "email@avalista.com" }, { "name": "Avalista PJ", "document_number": "65.679.662/0001-85", "person_type": "legal_person", "email": "email@avalista.com", "guarantor_representatives": [ { "name": "Assinante do Avalista", "document_number": "244.412.084-13", "email": "emailrepresentante@avalista.com", "address": { "street": "Rua Maria Carolina", "number": "624", "neighborhood": "Jardim Paulistano", "city": "São Paulo", "postal_code": "01445-000", "uf": "SP", "country": "BRA" } } ] }, ] } ``` --- ### Definição do Cedente | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do cedente. | 1 a 255 | | `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 | | `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - | | `email` * | string | Endereço de e-mail do cedente. | 1 a 255 | | `is_in_national_financial_system` * | boolean | Indicador se o cedente é integrante do SFN. | - | | `phone` | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `related_parties` * | array | Lista de partes relacionadas da empresa.| Ver **[Definição de Parte Relacionada](#definição-de-parte-relacionada)**. | | `accounts` * | array | Lista de contas de desembolso do cedente.| Ver **[Definição de Conta](#definição-de-conta)**. | | `guarantors` * | array | Lista de avalistas do cedente.| Ver **[Definição de Avalista](#definição-de-avalista)**. | *Campos obrigatórios. ### Response STATUS 201 ```json title='Response Body' { "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_registry", "name": "QI Tech", "document_number": "32.402.502/0001-35", "last_analysis": { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "status": "pending_documents", "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "document_number": "802.834.257-41", "name": "Roberto Carlos", "documents": [] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "883.512.866-80", "name": "Natália Nascimento", "documents": [] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "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](#assignor-registry-status)**. | | `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](#definição-de-análise)**. | :::info É 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` que serão utilizadas para envio de documentos do cedente e das partes relacionadas. ::: :::info Na estrutura de análise, um avalista, ou um representante de um avalista, também é representado por um `analysis_related_party`. Importante notar que o mesmo é único por `document_number`, logo, caso a mesma pessoa seja avalista e parte relacionada do cedente, por exemplo, gerará apenas um `analysis_related_party`, com uma `analysis_related_party_key`, que servirá tanto para a parte relacionada, quanto para o avalista. ::: :::info Os representantes de pessoa física se limitam apenas ao procurador que pode assinar por tal. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000032 | 409 | Esse agente já cadastrou esse cedente. | O `document_number` já possui um cadastro; utilize o fluxo de [atualização de cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). | | ASR000054 | 400 | Cedente pessoa jurídica deve ter pelo menos 1 parte relacionada. | Incluir ao menos uma parte relacionada em `related_parties`. | | ASR000056 | 400 | Pessoa física não pode ser participante do Sistema Financeiro Nacional. | Para `person_type=natural_person`, enviar `is_in_national_financial_system=false`. | | ASR000057 | 400 | Cedente pessoa jurídica deve ter pelo menos 1 representante assinante. | Garantir que ao menos uma parte relacionada possua `is_representative=true`. | | ASR000011 | 400 | Número de documento de parte relacionada duplicado. | Cada `document_number` em `related_parties` deve ser único. | | ASR000041 | 400 | Email obrigatório para representante. | Para partes relacionadas com `is_representative=true`, informar `email`. | | ASR000058 | 400 | Pessoa estrangeira sem CPF não pode ser assinante. | Estrangeiros sem `document_number` (CPF) não podem ter `is_representative=true`. | | ASR000071 | 404 | Instituição financeira não encontrada. | Validar o `financial_institution_code` (código bancário) informado para a conta. | | 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`. | | ASR000078 | 400 | Número de documento de avalista duplicado. | Cada avalista em `guarantors` deve ter `document_number` único. | | ASR000079 | 400 | Avalista pessoa física não pode receber representantes. | Para avalistas com `person_type=natural_person`, o `guarantor_representatives` deve ser do tipo `spouse` | | ASR000080 | 400 | Documento de representante de avalista duplicado. | Cada representante em `guarantor_representatives` deve ter `document_number` único. | | ASR000091 | 400 | Avalista pessoa jurídica deve ter pelo menos um representante. | Para `person_type=legal_person`, enviar pelo menos um item em `guarantor_representatives`. | --- ## Definições ### Definição de Endereço | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `street` * | string | Nome da rua. | 1 a 255 | | `number` * | string | Número do endereço. | 1 a 4 | | `neighborhood` * | string | Bairro. | 1 a 255 | | `city` * | string | Cidade. | 1 a 255 | | `uf` * | string | Sigla do estado. | 2 | | `complement` | string | Complemento do endereço. | 1 a 255 | | `postal_code` * | string | Código postal. | 9 (formato: XXXXX-XXX) | | `country` * | string | País (sigla). | 3, de acordo com a ISO 3166-1 alpha-3 | *Campos obrigatórios. --- ### Definição de Telefone | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `international_dial_code` * | string | Código internacional de discagem. | 1 a 3 | | `area_code` * | string | Código de área. | 2 | | `number` * | string | Número de telefone. | 8 a 9 | *Campos obrigatórios. --- ### Definição de Parte Relacionada | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome da parte relacionada. | 1 a 255 | | `document_number` ** | string | Número de documento do beneficiário (CPF). | 14 a 18 | | `passport_number` ** | string | Número de documento do beneficiário estrangeiro. | 8 a 9 | | `related_party_type` * | string | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** | | `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 | | `direct_beneficiary` * | boolean | Beneficiário diretamente ou indiretamente ligado ao cedente. | 1 a 255 | | `is_representative` * | boolean | Indicador se a parte relacionada é representante assinante do cedente. | 1 a 255 | | `company_registry_number` *** | string | Caso não seja diretamente ligado ao cedente, à qual companhia o mesmo está ligado. | 1 a 255 | | `company_country` *** | string | País onde a companhia-elo entre o beneficiário e o cedente está registrada. | 3, de acordo com a ISO 3166-1 alpha-3 | | `address` | object | Objeto referenciando as informações do endereço do representante. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `email` **** | string | Endereço de e-mail do representante. | 1 a 255 | | `phone` | object | Objeto referenciando as informações do telefone do representante. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `marital_status` | string | Estado civil da parte relacionada. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão da parte relacionada. | 1 a 255. | *Campos obrigatórios. **document_number obrigatório para brasileiros, para estrangeiros, caso tenha CPF, é possível utilizar o document_number, caso contrário, pelo menos o passport_number deve ser enviado. ***Campos obrigatórios caso a parte relacionada não seja beneficiário diretamente ligada ao cedente. Caso contrário, não devem ser enviados. ****Campos exigidos apenas para representantes assinantes. :::info Campos não obrigatorios, como `marital_status` e `address`, podem ser enviados caso deseje uma qualificação mais completa no contrato mãe de cessão, nas etapas futuras. ::: --- ### Definição de Análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_key` * | string | Identificador da análise. | 36 | | `analysis_number` * | integer | Número sequencial da análise. | - | | `status` * | string | Status da análise. | Ver **[Enumeradores de status de análise](#analysis-status)**. | | `analysis_related_parties` * | array | Partes Relacionadas da análise. | Ver **[Definição de Partes Relacionadas de Análise](#definição-de-partes-relacionadas-de-análise)**. | | `documents` * | array | Documentos da anáise. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | | `analysis_data` * | object | Payload da request que originou a análise. | - | | `analysis_datetime` * | string | Objeto date time da criação da análise. | - | | `reproval_reason` | string | Enumerador com o motivo de rejeição da análise. | Ver **[Enumeradores de motivo de reprovação](#analysis-reproval-reason)**. | | `reproval_details` | string | Campo livre com detalhes da rejeição da análise. | - | *Campos obrigatórios. --- ### Definição de Partes Relacionadas de análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_related_party_key` * | string | Identificador da parte relacionada. | 36 | | `document_number` * | string | Número de documento da parte relacionada. | 14 a 18 | | `name` * | string | Nome da parte relacionada. | 1 a 255 | | `documents` * | array | Documentos da anáise da parte relacionada. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | *Campos obrigatórios. --- ### Definição de Documentos | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` * | string | Identificador do documento. | 36 | | `document_type` * | string | Tipo do documento. | Ver **[Enumeradores de tipo de documento](#document-type)**. | | `status` | string | Status do documento. | Ver **[Enumeradores de status de documento](#document-status)**. | | `observation` | string | Observações enviadas. | - | *Campos obrigatórios. --- ### Definição de Conta | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `account_branch` * | string | Agência da conta do cedente. | 4 | | `account_number` * | string | Número da conta do cedente. | 3 - 20 | | `account_digit` * | string | Dígito da conta do cedente. | 1 | | `financial_institution_code` * | string | Código do banco da conta do cedente. | 3 | | `account_type` * | string | Tipo de conta. | Ver **[Enumeradores de tipo de conta](#account-type)**. | | `default_account` * | boolean | Conta padrão de desembolso. | - | *Campos obrigatórios. Apenas uma conta do cedente pode ser a conta padrão, que será a conta para qual o dinheiro das cessões será enviado caso nenhuma conta alternativa seja indicada. Caso sejam enviadas mais de uma conta padrão, um erro será retornado. :::warning Atenção Muito cuidado ao preencher os dados da conta. Caso a conta seja inválida, o pagamento da cessão não ocorrerá, e toda a operação será cancelada. ::: --- ### Definição de Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do Avalista. | 3 - 255 | | `document_number` * | string | Número de documento do avalista. | 14 a 18 | | `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - | | `email` * | string | Endereço de e-mail do avalista. | 1 a 255 | | `nationality` | string | País de origem do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 | | `phone` | object | Objeto referenciando as informações do telefone do avalista. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` | object | Objeto referenciando as informações do endereço do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `guarantor_representatives` | array | Assinantes do Avalista - Apenas para avalista pessoa jurídica. | Ver **[Definição de Representante do Avalista](#definição-de-representante-do-avalista)**. | | `marital_status` | string | Estado civil do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão do avalista. | 1 a 255. | *Campos obrigatórios. O campo `guarantor_representatives` pode ser utilizado para indicar tanto representantes de um avalista pessoa jurídica, quanto, no caso de avalista pessoa física, onde se encontrar necessário, o cônjuge para realização da Outorga Uxória. :::warning Atenção Tanto o avalista quanto os representantes também serão adicionados à anáise gerada, sendo necessário enviar os documentos padrão de acordo com o tipo de pessoa do mesmo. Os mesmos também passam pelo processo de compliance, podendo gerar apontamentos. ::: --- ### Definição de Representante do Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do Representante. | 3 - 255 | | `document_number` * | string | Número de documento do representante do avalista - obrigatóriamente pessoa física. | 14 | | `email` * | string | Endereço de e-mail do representante do avalista. | 1 a 255 | | `nationality` | string | País de origem do representante do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 | | `address` | object | Objeto referenciando as informações do endereço do representante do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `phone` | object | Objeto referenciando as informações do telefone do representante do avalista. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `marital_status` | string | Estado civil do representante do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão do representante do avalista. | 1 a 255. | --- # Enumeradores ### Assignor Registry Status | Enumerador | Descrição | | -------------------------- | ----------------- | | **pending_registry** | Pendente Registro | | **registered** | Registrado | --- ### Analysis Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_documents** | Pendente Documentos | | **sent_to_analysis** | Enviado para Análise | | **pending_internal_validation** | Em Validação de documentos | | **in_manual_analysis** | Em Análise Manual de Compliance | | **approved** | Aprovado | | **reproved** | Reprovado | --- ### Related Party Type | Enumerador | Descrição | | ----------------------- | ------------- | | **president** | Presidente | | **partner** | Sócio | | **administrator** | Administrador | | **director** | Diretor | | **manager** | Gestor | | **attorney** | Procurador | --- ### Document Status | Enumerador | Descrição | | ----------------------- | ------------- | | **created** | Criado | | **valid** | Válido | | **invalid** | Inválido | | **canceled** | Cancelado | | **accepted** | Aceito, porém não validado | --- ### Document Type | Enumerador | Descrição | | ---------------------------- | -------------------------- | | **cnh** | CNH. | | **rg_back** | RG parte traseira. | | **rg_front** | RG parte frontal. | | **passport** | Passaporte - exclusivo para estrangeiros. | | **national_migration_registry** | Registro Nacional de Migração. | | **cin_digital** | Carteira de Identidade Nacional (Digital). | | **passport** | Passaporte - exclusivo para estrangeiros. | | **social_contract** | Contrato/Estatuto Social. | | **cnpj_card** | Cartão CNPJ. | | **commercial_board_certificate** | Certidão Simplidicada da Junta Comercial. | | **board_election_record** | Ata de Eleição da Diretoria Vigente. | | **power_of_attorney** | Procuração - obrigatório caso o representante seja um procurador. | | **marital_power_of_attorney** | Procuração Uxória - disponível apenas para cônjuges. | | **compliance_statement** | Parecer de Compliance. | | **financial_statement** | Demonstração Financeira. | | **credit_report** | Ata/Parecer de Crédito. | | **manager_statement** | Parecer/Ficha do Gestor. | | **visit_report** | Relatório de Visita. | | **proof_of_residence** | Comprovante de Residência. | | **credit_agency_consulation** | Consulta aos órgãos de Proteção de Crédito. | | **annual_revenues_declaration** | Declaração de Faturamento. | | **financial_institutions_declaration** | Declaração de Relacionamento Bancário. | | **additional_document** | Documento adicional - livre. | --- ### Account Type | Enumerador | Descrição | |----------------------|---------------------| | **checking_account** | Conta Corrente | --- ### Analysis Reproval Reason | Enum | Description | |--------------|---------------| | **assignor_update** | Análise cancelada devido à atualização cadastral posterior | | **insuficient_documents** | Documentação mínima para comprovação de poderes não enviada | | **compliance_reproval** | Reprovação de vínculo por análise do time de compliance | | **unidentified_related_parties** | Parte relacionada enviada, porém vinculo não comprovado | | **invalid_documents** | Documentação inválida/expirada | | **missing_related_parties** | Parte relacionada obrigatória não enviada | --- ### Marital Status | Enum | Description | |--------------|---------------| | **single** | Solteiro(a) | | **married** | Casado(a) | | **widower** | Viúvo(a) | | **divorced** | Divorciado(a) | | **separated** | Separado(a) | | **stable_union** | Em União Estável | --- ### Property System | Enum | Descrição | | --------------------------------- | -------------------------------------- | | **total_communion_of_goods** | Comunhão Total de Bens | | **partial_communion_of_goods** | Comunhão Parcial de Bens | | **total_separation_of_goods** | Separação Total de Bens | | **final_participation_of_acquisitions** | Participação Final nos Aquestos | | **compulsory_separation_of_goods** | Separação Obrigatória de Bens | --- # Envio de Documentos URL: /documentation/iaas/homologacao_cedente/cadastro/envio_de_documentos Após o envio do cadastro do cedente, devem ser enviados os documentos relacionados ao mesmo. Para isso, é utilizada a estrutura de análise de documentos, onde, tanto na criação quanto na alteração, uma análise é gerada e os devidos documentos devem ser enviados. Cabe à gestora averiguar a operação do cedente que irá opear com os fundos geridos, e, futuramente, na etapa de criação de contrato mãe, será necessário assinar uma declaração da gestora, atestando que a mesma cumpriu toda a análise requerida pelo manual de Regras e Procedimentos de Administração e Gestão de Recursos de Terceiros, a qual encarrega à gestora tanto a análise quanto a atualização do cadastro do cedente. :::info Caso se trate de uma atualização, os documentos da última análise aprovada são automaticamente reaproveitados, podendo ser substituídos por novos. ::: --- ## Documentos do Cedente ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/document MÉTODO POST ```json title='Request Body' { "document_type":"social_contract", "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg==", "observation":"CONTRATO SOCIAL ATUALIZADO", } ``` ## Objeto de Documento | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_type` * | string | Tipo do documento. | Ver **[Tipos de Documento ](#document-type)**. | | `document_b64` * | string | Deve ser o binário do arquivo em PDF, codificado em Base64. | - | | `observation` | string | Campo livre para descrever arquivos enviados. | 1 - 255 | *Campos obrigatórios. ### Response STATUS 201 ```json title='Response Body' { "document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a", "document_type": "social_contract", "analysis_key": "63db95c2-9985-405a-a521-6904f9e96cc6", "status": "valid" } ``` :::info Em caso de atualização cadastral, o envio de documentos específicos do cedente na análise será necessário somente quando houver alguma atualização nas informações que sejam **específicas do cedente**. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000039 | 400 | O status atual da análise não aceita novos documentos. | Documentos só podem ser anexados quando a análise estiver em `pending_documents`. Para reenviar após análise iniciada, gere uma nova análise via [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). | | ASR000005 | 400 | Formato de arquivo inválido. | Enviar `document_b64` como string em base64 válida. | | ASR000060 | 400 | O arquivo enviado não é um PDF válido. | O conteúdo decodificado de `document_b64` deve ser um PDF. | | ASR000059 | 400 | Tamanho do arquivo excede o limite. | Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). | | ASR000061 | 400 | Tipo de documento inválido para o cedente. | Usar um `document_type` compatível com o tipo de pessoa do cedente (ver tabela [Documentos padrão do cedente/avalista](#documentos-padrão-do-cedenteavalista)). | ## Documentos das partes relacionadas ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/related_party/ANALYSIS_RELATED_PARTY_KEY/document MÉTODO POST ```json title='Request Body' { "document_type":"cnh", "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg==", "observation":"CNH Válida", } ``` ### Response STATUS 201 ```json title='Response Body' { "document_key": "afe8532a-4b0b-4e63-8d16-5084b2681752", "document_type": "cnh", "analysis_related_party_key": "fd1fb513-5ffc-4060-bca1-17deed680011", "status": "valid" } ``` :::info Em caso de atualização cadastral, o envio de documentos das partes relacionadas na análise será necessário somente quando houver alguma inclusão ou atualização de partes relacionadas do cedente. ::: :::caution Atenção! Caso um documento seja enviado com o tipo errado, ou com má qualidade ele pode retornar com o status **accepted**, indicando que a qualidade do mesmo está duvidosa, ou até **invalid**, assim sendo necessário reenviá-lo corretamente. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000035 | 404 | Parte relacionada da análise não encontrada para o `analysis_related_party_key` informado. | Verificar se o `analysis_related_party_key` retornado na criação da análise está correto. | | ASR000039 | 400 | O status atual da análise não aceita novos documentos. | Documentos só podem ser anexados quando a análise estiver em `pending_documents`. | | ASR000005 | 400 | Formato de arquivo inválido. | Enviar `document_b64` como string em base64 válida. | | ASR000060 | 400 | O arquivo enviado não é um PDF válido. | O conteúdo decodificado de `document_b64` deve ser um PDF. | | ASR000059 | 400 | Tamanho do arquivo excede o limite. | Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). | | ASR000062 | 400 | Tipo de documento inválido para a parte relacionada. | Usar um `document_type` compatível com o tipo de pessoa da parte relacionada (ver tabela [Documentos padrão das partes relacionadas/representantes](#documentos-padrão-das-partes-relacionadasrepresentantes)). | ## Cancelamento do envio de documento Com exceção do tipo additional_document, apenas um documento com status "valid" é permitido na análise. Caso, por algum motivo, deseje substituir um documento já válido, deve-se cancelá-lo. ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/related_party/ANALYSIS_RELATED_PARTY_KEY/document/DOCUMENT_KEY MÉTODO PUT OU ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/document/DOCUMENT_KEY MÉTODO PUT ```json title='Request Body' { "status":"canceled" } ``` ### Response STATUS 200 ```json title='Response Body' { "document_key": "afe8532a-4b0b-4e63-8d16-5084b2681752", "document_type": "cnh", "analysis_related_party_key": "fd1fb513-5ffc-4060-bca1-17deed680011", "status": "canceled" } ``` ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | | ASR000006 | 404 | Documento da análise não encontrado para o `document_key` informado. | Verificar se o `document_key` pertence à análise indicada. | | ASR000036 | 404 | Documento da parte relacionada da análise não encontrado para o `document_key` informado. | Verificar se o `document_key` pertence à parte relacionada indicada (rota com `related_party`). | | ASR000076 | 400 | Status enviado não permitido para esse fluxo. | O único valor aceito para `status` neste endpoint é `canceled`. | --- ### Documentos padrão do cedente/avalista | Tipo de Pessoa | *document_type* | Descrição | Obrigatoriedade | |----------------|-------------------|------------|--------------| | Pessoa Física | cnh | CNH (Carteira Nacional de Habilitação) | * | | Pessoa Física | cin_digital | Carteira de Identidade Nacional (Digital) | * | | Pessoa Física | rg_back | RG (Carteira de Identidade) - Verso | * | | Pessoa Física | rg_front | RG (Carteira de Identidade) - Frente | * | | Pessoa Jurídica | social_contract | Contrato Social | Sempre | | Pessoa Jurídica | commercial_board_certificate | Ceridão Simplificada da Junta Comercial | Opcional, entretanto obrigatório para contratos sociais com data superior a 3 anos | | Pessoa Jurídica | board_election_record | Eleição da diretoria - se aplicável | Necessário para comprovação de vínculo | *Para quaisquer pessoas físicas, é necessário apenas um dentre RG frente e verso, CNH e Carteira de Identidade Nacional. ### Documentos padrão das partes relacionadas/representantes | Tipo de Pessoa | *document_type* | Descrição | Obrigatoriedade | |----------------|-------------------|------------|--------------| | Pessoa Física | cnh | CNH (Carteira Nacional de Habilitação) | * | | Pessoa Física | cin_digital | Carteira de Identidade Nacional (Digital) | * | | Pessoa Física | rg_back | RG (Carteira de Identidade) - Verso | * | | Pessoa Física | rg_front | RG (Carteira de Identidade) - Frente | * | | Pessoa Física | power_of_attorney | Procuração PF ou PJ - Obrigatório caso representante seja um procurador | Necessário para comprovação de vínculo | *Para quaisquer pessoas físicas, é necessário apenas um dentre RG frente e verso, CNH e Carteira de Identidade Nacional. :::warning Atenção Alguns tipos de documentos passam por uma ferramenta de OCR para extração e verificação dos dados. Deve-se sempre atentar ao retorno do envio de documento, que síncronamente retorna a validação - valid/accepted/invalid do OCR. ::: ## Tipos de Documento ### Document Type | Enumerador | Descrição | | ---------------------------- | -------------------------- | | **cnh** | CNH. | | **rg_back** | RG parte traseira. | | **rg_front** | RG parte frontal. | | **passport** | Passaporte - exclusivo para estrangeiros. | | **national_migration_registry** | Registro Nacional de Migração. | | **cin_digital** | Carteira de Identidade Nacional (Digital). | | **passport** | Passaporte - exclusivo para estrangeiros. | | **social_contract** | Contrato/Estatuto Social. | | **cnpj_card** | Cartão CNPJ. | | **commercial_board_certificate** | Certidão Simplidicada da Junta Comercial. | | **board_election_record** | Ata de Eleição da Diretoria Vigente. | | **power_of_attorney** | Procuração - obrigatório caso o representante seja um procurador. | | **marital_power_of_attorney** | Procuração Uxória - disponível apenas para cônjuges. | | **compliance_statement** | Parecer de Compliance. | | **financial_statement** | Demonstração Financeira. | | **credit_report** | Ata/Parecer de Crédito. | | **manager_statement** | Parecer/Ficha do Gestor. | | **visit_report** | Relatório de Visita. | | **proof_of_residence** | Comprovante de Residência. | | **credit_agency_consulation** | Consulta aos órgãos de Proteção de Crédito. | | **annual_revenues_declaration** | Declaração de Faturamento. | | **financial_institutions_declaration** | Declaração de Relacionamento Bancário. | | **additional_document** | Documento adicional - livre. | ### Document Status | Enumerador | Descrição | | ----------------------- | ------------- | | **created** | Criado | | **valid** | Válido | | **invalid** | Inválido | | **canceled** | Cancelado | | **accepted** | Aceito, porém não validado | --- # Cadastro de Filiais URL: /documentation/iaas/homologacao_cedente/cadastro/filiais Para a habilitação de filiais, existem dois fluxos operacionais que podem ser seguidos: 1. **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. 2. **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. :::info 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_type` e `assignor_document_number`, utilizando o contrato formalizado pela matriz como referência. :::warning Atenção 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 ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/branch MÉTODO POST :::info A `assignor_registry_key` enviada na requisição deve pertencer à MATRIZ do cedente, e a mesma já deve estar habilitada. ::: ```json title='Request Body' { "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](#definição-de-telefone)**. | | `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `accounts` * | array | Lista de contas de desembolso do cedente.| Ver **[Definição de Conta](#definição-de-conta)**. | *Campos obrigatórios. ### Response STATUS 201 ```json title='Response Body' { "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](#assignor-registry-status)**. | | `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](#definição-de-análise)**. | :::info 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. ::: :::info É 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](#vinculando-uma-filial-já-existente-à-matriz). | | 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 ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/branch MÉTODO PUT :::info A `assignor_registry_key` enviada na requisição deve pertencer à MATRIZ do cedente, e a mesma já deve estar habilitada. ::: ```json title='Request Body' { "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 STATUS 200 ```json title='Response Body' { "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](#assignor-registry-status)**. | | `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](#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 ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY MÉTODO PUT ```json title='Request Body' { "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](#definição-de-telefone)**. | | `address` | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. | Caso não deseje alterar um campo, basta não enviá-lo na request. ### Response STATUS 200 ```json title='Response Body' { "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](#assignor-registry-status)**. | | `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](#definição-de-análise)**. | :::info 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. ::: :::info 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. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente filial não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` na URL corresponde a um cadastro de filial. | | ASR000100 | 400 | Campo enviado não pode ser atualizado em uma filial. | Em filiais, somente `email`, `phone`, `address` e `annual_revenues` podem ser atualizados. Para alterar `name`, `is_in_national_financial_system`, `related_parties` ou `guarantors`, atualizar o cadastro da matriz (ver [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro)). | --- ## Definições ### Definição de Endereço | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `street` * | string | Nome da rua. | 1 a 255 | | `number` * | string | Número do endereço. | 1 a 4 | | `neighborhood` * | string | Bairro. | 1 a 255 | | `city` * | string | Cidade. | 1 a 255 | | `uf` * | string | Sigla do estado. | 2 | | `complement` | string | Complemento do endereço. | 1 a 255 | | `postal_code` * | string | Código postal. | 9 (formato: XXXXX-XXX) | | `country` * | string | País (sigla). | 3, de acordo com a ISO 3166-1 alpha-3 | *Campos obrigatórios. --- ### Definição de Telefone | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `international_dial_code` * | string | Código internacional de discagem. | 1 a 3 | | `area_code` * | string | Código de área. | 2 | | `number` * | string | Número de telefone. | 8 a 9 | *Campos obrigatórios. --- ### Definição de Parte Relacionada | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome da parte relacionada. | 1 a 255 | | `document_number` ** | string | Número de documento do beneficiário (CPF). | 14 a 18 | | `passport_number` ** | string | Número de documento do beneficiário estrangeiro. | 8 a 9 | | `related_party_type` * | string | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** | | `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 | | `direct_beneficiary` * | boolean | Beneficiário diretamente ou indiretamente ligado ao cedente. | 1 a 255 | | `is_representative` * | boolean | Indicador se a parte relacionada é representante assinante do cedente. | 1 a 255 | | `company_registry_number` *** | string | Caso não seja diretamente ligado ao cedente, à qual companhia o mesmo está ligado. | 1 a 255 | | `company_country` *** | string | País onde a companhia-elo entre o beneficiário e o cedente está registrada. | 3, de acordo com a ISO 3166-1 alpha-3 | | `address` | object | Objeto referenciando as informações do endereço do representante. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `email` **** | string | Endereço de e-mail do representante. | 1 a 255 | | `phone` | object | Objeto referenciando as informações do telefone do representante. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `marital_status` | string | Estado civil da parte relacionada. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão da parte relacionada. | 1 a 255. | *Campos obrigatórios. **document_number obrigatório para brasileiros, para estrangeiros, caso tenha CPF, é possível utilizar o document_number, caso contrário, pelo menos o passport_number deve ser enviado. ***Campos obrigatórios caso a parte relacionada não seja beneficiário diretamente ligada ao cedente. Caso contrário, não devem ser enviados. ****Campos exigidos apenas para representantes assinantes. :::info Campos não obrigatorios, como `marital_status` e `address`, podem ser enviados caso deseje uma qualificação mais completa no contrato mãe de cessão, nas etapas futuras. ::: --- ### Definição de Análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_key` * | string | Identificador da análise. | 36 | | `analysis_number` * | integer | Número sequencial da análise. | - | | `status` * | string | Status da análise. | Ver **[Enumeradores de status de análise](#analysis-status)**. | | `analysis_related_parties` * | array | Partes Relacionadas da análise. | Ver **[Definição de Partes Relacionadas de Análise](#definição-de-partes-relacionadas-de-análise)**. | | `documents` * | array | Documentos da anáise. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | | `analysis_data` * | object | Payload da request que originou a análise. | - | | `analysis_datetime` * | string | Objeto date time da criação da análise. | - | | `reproval_reason` | string | Enumerador com o motivo de rejeição da análise. | Ver **[Enumeradores de motivo de reprovação](#analysis-reproval-reason)**. | | `reproval_details` | string | Campo livre com detalhes da rejeição da análise. | - | *Campos obrigatórios. --- ### Definição de Partes Relacionadas de análise | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `analysis_related_party_key` * | string | Identificador da parte relacionada. | 36 | | `document_number` * | string | Número de documento da parte relacionada. | 14 a 18 | | `name` * | string | Nome da parte relacionada. | 1 a 255 | | `documents` * | array | Documentos da anáise da parte relacionada. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. | *Campos obrigatórios. --- ### Definição de Documentos | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` * | string | Identificador do documento. | 36 | | `document_type` * | string | Tipo do documento. | Ver **[Enumeradores de tipo de documento](#document-type)**. | | `status` | string | Status do documento. | Ver **[Enumeradores de status de documento](#document-status)**. | | `observation` | string | Observações enviadas. | - | *Campos obrigatórios. --- ### Definição de Conta | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `account_branch` * | string | Agência da conta do cedente. | 4 | | `account_number` * | string | Número da conta do cedente. | 3 - 20 | | `account_digit` * | string | Dígito da conta do cedente. | 1 | | `financial_institution_code` * | string | Código do banco da conta do cedente. | 3 | | `account_type` * | string | Tipo de conta. | Ver **[Enumeradores de tipo de conta](#account-type)**. | | `default_account` * | boolean | Conta padrão de desembolso. | - | *Campos obrigatórios. Apenas uma conta do cedente pode ser a conta padrão, que será a conta para qual o dinheiro das cessões será enviado caso nenhuma conta alternativa seja indicada. Caso sejam enviadas mais de uma conta padrão, um erro será retornado. :::warning Atenção Muito cuidado ao preencher os dados da conta. Caso a conta seja inválida, o pagamento da cessão não ocorrerá, e toda a operação será cancelada. ::: --- ### Definição de Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do Avalista. | 3 - 255 | | `document_number` * | string | Número de documento do avalista. | 14 a 18 | | `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - | | `email` * | string | Endereço de e-mail do avalista. | 1 a 255 | | `nationality` | string | País de origem do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 | | `phone` | object | Objeto referenciando as informações do telefone do avalista. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` | object | Objeto referenciando as informações do endereço do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `guarantor_representatives` | array | Assinantes do Avalista - Apenas para avalista pessoa jurídica. | Ver **[Definição de Representante do Avalista](#definição-de-representante-do-avalista)**. | | `marital_status` | string | Estado civil do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão do avalista. | 1 a 255. | *Campos obrigatórios. O campo `guarantor_representatives` pode ser utilizado para indicar tanto representantes de um avalista pessoa jurídica, quanto, no caso de avalista pessoa física, onde se encontrar necessário, o cônjuge para realização da Outorga Uxória. :::warning Atenção Tanto o avalista quanto os representantes também serão adicionados à anáise gerada, sendo necessário enviar os documentos padrão de acordo com o tipo de pessoa do mesmo. Os mesmos também passam pelo processo de compliance, podendo gerar apontamentos. ::: --- ### Definição de Representante do Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do Representante. | 3 - 255 | | `document_number` * | string | Número de documento do representante do avalista - obrigatóriamente pessoa física. | 14 | | `email` * | string | Endereço de e-mail do representante do avalista. | 1 a 255 | | `nationality` | string | País de origem do representante do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 | | `address` | object | Objeto referenciando as informações do endereço do representante do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `phone` | object | Objeto referenciando as informações do telefone do representante do avalista. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `marital_status` | string | Estado civil do representante do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. | | `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. | | `profession` | string | Profissão do representante do avalista. | 1 a 255. | --- # Enumeradores ### Assignor Registry Status | Enumerador | Descrição | | -------------------------- | ----------------- | | **pending_registry** | Pendente Registro | | **registered** | Registrado | --- ### Analysis Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_documents** | Pendente Documentos | | **sent_to_analysis** | Enviado para Análise | | **pending_internal_validation** | Em Validação de documentos | | **in_manual_analysis** | Em Análise Manual de Compliance | | **approved** | Aprovado | | **reproved** | Reprovado | --- ### Related Party Type | Enumerador | Descrição | | ----------------------- | ------------- | | **president** | Presidente | | **partner** | Sócio | | **administrator** | Administrador | | **director** | Diretor | | **manager** | Gestor | | **attorney** | Procurador | --- ### Document Status | Enumerador | Descrição | | ----------------------- | ------------- | | **created** | Criado | | **valid** | Válido | | **invalid** | Inválido | | **canceled** | Cancelado | | **accepted** | Aceito, porém não validado | --- ### Document Type | Enumerador | Descrição | | ---------------------------- | -------------------------- | | **cnh** | CNH. | | **rg_back** | RG parte traseira. | | **rg_front** | RG parte frontal. | | **passport** | Passaporte - exclusivo para estrangeiros. | | **national_migration_registry** | Registro Nacional de Migração. | | **cin_digital** | Carteira de Identidade Nacional (Digital). | | **passport** | Passaporte - exclusivo para estrangeiros. | | **social_contract** | Contrato/Estatuto Social. | | **cnpj_card** | Cartão CNPJ. | | **commercial_board_certificate** | Certidão Simplidicada da Junta Comercial. | | **board_election_record** | Ata de Eleição da Diretoria Vigente. | | **power_of_attorney** | Procuração - obrigatório caso o representante seja um procurador. | | **marital_power_of_attorney** | Procuração Uxória - disponível apenas para cônjuges. | | **compliance_statement** | Parecer de Compliance. | | **financial_statement** | Demonstração Financeira. | | **credit_report** | Ata/Parecer de Crédito. | | **manager_statement** | Parecer/Ficha do Gestor. | | **visit_report** | Relatório de Visita. | | **proof_of_residence** | Comprovante de Residência. | | **credit_agency_consulation** | Consulta aos órgãos de Proteção de Crédito. | | **annual_revenues_declaration** | Declaração de Faturamento. | | **financial_institutions_declaration** | Declaração de Relacionamento Bancário. | | **additional_document** | Documento adicional - livre. | --- ### Account Type | Enumerador | Descrição | |----------------------|---------------------| | **checking_account** | Conta Corrente | --- ### Analysis Reproval Reason | Enum | Description | |--------------|---------------| | **assignor_update** | Análise cancelada devido à atualização cadastral posterior | | **insuficient_documents** | Documentação mínima para comprovação de poderes não enviada | | **compliance_reproval** | Reprovação de vínculo por análise do time de compliance | | **unidentified_related_parties** | Parte relacionada enviada, porém vinculo não comprovado | | **invalid_documents** | Documentação inválida/expirada | | **missing_related_parties** | Parte relacionada obrigatória não enviada | --- ### Marital Status | Enum | Description | |--------------|---------------| | **single** | Solteiro(a) | | **married** | Casado(a) | | **widower** | Viúvo(a) | | **divorced** | Divorciado(a) | | **separated** | Separado(a) | | **stable_union** | Em União Estável | --- ### Property System | Enum | Descrição | | --------------------------------- | -------------------------------------- | | **total_communion_of_goods** | Comunhão Total de Bens | | **partial_communion_of_goods** | Comunhão Parcial de Bens | | **total_separation_of_goods** | Separação Total de Bens | | **final_participation_of_acquisitions** | Participação Final nos Aquestos | | **compulsory_separation_of_goods** | Separação Obrigatória de Bens | --- # Contas do cedente URL: /documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas No ato do cadastro do cedente, é obrigatório providenciar ao menos uma conta de desembolso de cessão para o cedente. Na etapa de aprovação da cessão pela gestora, é possível indicar qualquer uma das contas cadastradas para o cedente para ocorrer o desembolso da mesma. Vale ressaltar que, caso o proponente da operação entre cedente-fundo seja um consultor, a manutenção das contas será de responsabilidade da consultoria ao invś da gestora. Diferente de dados cadastrais, como representantes, endereços, e outros dados, não será criada uma nova análise ao realizar uma alteração nas contas do cedente, sendo assim, a alteração passa a valer de imediato. Para uma conta de desembolso, obrigatóriamente o titular da conta deve ser o cedente, inclusive a titularidade da conta, e o número de documento do dono da conta já é assumido ser o do cedente. :::warning Atenção Muito cuidado ao preencher os dados da conta. Caso a conta seja inválida, o pagamento da cessão não ocorrerá, e toda a operação será cancelada. ::: --- ## Adição de conta alternativa ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/account MÉTODO POST ```json title='Request Body' { "account_number": "8473124", "account_digit": "8", "account_branch": "0001", "account_type": "checking_account", "financial_institution_code": "329", "default_account": false } ``` ## Objeto de Conta | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `account_number` * | string | Número da conta. | 3-20 | | `account_digit` * | string | Dígito da conta. | 1 | | `account_branch` * | string | Agência da conta. | 4 | | `account_type` * | string | Tipo da conta. | - | | `financial_institution_code` * | string | Código do banco da conta. | 3 | | `default_account` * | boolean | Conta padrão de desembolso. | - | *Campos obrigatórios. ### Response STATUS 201 ```json title='Response Body' { "account_key": "3c53a94a-2b81-4837-b7eb-8e025e69d81c", "account_branch": "0001", "account_number": "8473124", "account_digit": "8", "account_type": "checking_account", "status": "active", "financial_institution_code": "329", "financial_institution_ispb": "32402502", "default_account": false, } ``` :::info Caso a conta nova seja enviada com "default_account" true, a antiga conta padrão de desembolso será tornada uma conta não padrão, e a partir de então, a nova conta postada será a padrão de desembolso. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000072 | 409 | Já existe uma conta ativa com a mesma combinação de banco, agência, conta e dígito. | Não enviar contas duplicadas — verificar as contas já cadastradas para o cedente. | | ASR000087 | 400 | Informação de conta deve conter apenas números. | Enviar `account_branch`, `account_number`, `account_digit` e `financial_institution_code` apenas com dígitos. | | ASR000071 | 404 | Instituição financeira não encontrada. | Validar o `financial_institution_code` (código bancário) informado. | ## Atualização de conta Não é possível alterar os dados de uma conta. Caso deseje, é necessário desativar a conta errada, e criar uma nova conta com os dados válidos. Para alterar a conta padrão de desembolso, basta indicar qual será a nova conta, que a antiga será alterada automaticamente. Não é possível definir uma conta como não padrão de desembolso, deve-se sempre indicar a nova. ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/account/ACCOUNT_KEY MÉTODO PUT ```json title='Request Body' { "status": "active", "default_account": true, } ``` ## Objeto de Conta | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `status` | string | Novo status da conta. | Ver **[Enumeradores de status de conta](#account-status)**. | | `default_account` | boolean | Conta padrão de desembolso. | - | *Campos obrigatórios (nenhum). ### Response STATUS 200 ```json title='Response Body' { "account_key": "3c53a94a-2b81-4837-b7eb-8e025e69d81c", "account_branch": "0001", "account_number": "8473124", "account_digit": "8", "account_type": "checking_account", "status": "active", "financial_institution_code": "329", "financial_institution_ispb": "32402502", "default_account": true, } ``` :::info Caso a atualização enviada com "default_account" true, a antiga conta padrão de desembolso será tornada uma conta não padrão, e a partir de então, a nova conta postada será a padrão de desembolso. Não é possível desativar uma conta padrão, ou definir como padrão uma conta inativa. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. | | ASR000073 | 404 | Conta não encontrada para o `account_key` informado. | Verificar se o `account_key` pertence ao cedente. | | ASR000074 | 400 | Não é possível desativar/desmarcar uma conta padrão. | Indicar primeiro outra conta como padrão (`default_account=true` em outra conta) antes de inativar a atual. | | ASR000075 | 400 | Nenhuma informação foi enviada para atualização. | Informar `status` ou `default_account` no corpo da requisição. | # Enumeradores ### Account Status | Enumerador | Descrição | | -------------------------- | ----------------- | | **active** | Conta ativa e disponível como opção de desembolso. | | **inactive** | Conta inativa e indisponível para desembolo. | --- # Webhooks URL: /documentation/iaas/homologacao_cedente/cadastro/webhooks_analise --- ## Webhooks de Análise --- #### Drivação para Compliance STATUS in_manual_analysis ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "analysis_status": "in_manual_analysis", "reproval_reason": null, "reproval_details": null, }, "webhook_type":"assignor_registry.analysis_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Em análise de Documentos STATUS pending_internal_validation ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "analysis_status": "pending_internal_validation", "reproval_reason": null, "reproval_details": null, }, "webhook_type":"assignor_registry.analysis_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Aprovado STATUS approved ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "approved", "reproval_reason": null, "reproval_details": null, }, "webhook_type":"assignor_registry.analysis_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Reprovado STATUS reproved ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "reproved", "reproval_reason": "insuficient_documents", "reproval_details": "Anexar procuração do sócio XXX.XXX.XXX-XX.", }, "webhook_type":"assignor_registry.analysis_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` ## Webhooks de Apontamento --- Disparados sempre que um [Apontamento de Compliance](/documentation/iaas/homologacao_cedente/cadastro/apontamentos) tem seu status alterado. São enviados quando o apontamento é aberto (`open`) e quando é respondido (`closed`). :::info Apontamentos originados por carga da Fromtis (`fromtis_load`) não disparam webhook. ::: #### Apontamento aberto STATUS open ```json title='Webhook Body' { "data":{ "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "annotation_status": "open", "message": "Anexar procuração do sócio XXX.XXX.XXX-XX.", }, "webhook_type":"assignor_registry.annotation_status_change", "webhook_datetime":"2025-01-22T20:30:23Z" } ``` #### Apontamento respondido STATUS closed ```json title='Webhook Body' { "data":{ "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f", "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "annotation_status": "closed", "message": "Anexar procuração do sócio XXX.XXX.XXX-XX.", }, "webhook_type":"assignor_registry.annotation_status_change", "webhook_datetime":"2025-01-22T20:30:23Z" } ``` ## Webhooks de Cadastro --- #### Cedente ativado STATUS registered ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "status": "registered", }, "webhook_type":"assignor_registry.assignor_registry_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Cedente expirado STATUS expired ```json title='Webhook Body' { "data":{ "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4", "status": "expired", }, "webhook_type":"assignor_registry.assignor_registry_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` --- # Consulta de Análise URL: /documentation/iaas/homologacao_cedente/consulta/consulta_de_analise --- ## Consulta de Análise Por Chave ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY MÉTODO GET ### Response STATUS 200 ```json title='Response Body' { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_documents", "documents": [ { "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017", "document_type": "social_contract", "status": "valid", } ], "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "document_number": "802.834.257-41", "name": "Natália Nascimento", "documents": [ { "document_key": "72bad379-dbe6-40ca-97f2-1181257889ba", "document_type": "cnh", "status": "valid", } ] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "883.512.866-80", "name": "Natália Nascimento", "documents": [ { "document_key": "8b9fe448-7ad7-4410-b8f7-5c920b07b9a7", "document_type": "cnh", "status": "valid", } ] } ], "analysis_data": { "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_registry", "name": "QI CTVM", "document_number": "67.987.787/0001-06", "person_type": "legal_person", "email": "qidtvm@qitech.com.br", "phone": { "number": "936360268", "area_code": "11" }, "address": { "uf": "SP", "city": "São Paulo", "number": "215", "street": "Gilberto Sabino", "country": "BRA", "postal_code": "05425-020", "neighborhood": "Pinheiros" }, "related_parties": [ { "name": "Natália Nascimento", "document_number": "883.512.866-80", "related_party_type": "attorney", "nationality": "BRA", "direct_beneficiary": true, "is_representative": true, "email": "natalia.nascimento@yopmail.com", "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" } }, { "name": "Maria Vitoria", "related_party_type": "president", "nationality": "DEU", "passport_number": "C01X00T47", "direct_beneficiary": true, "is_representative": false }, { "name": "Roberto Carlos", "document_number": "802.834.257-41", "related_party_type": "director", "nationality": "BRA", "direct_beneficiary": false, "company_country": "NZL", "company_registry_number": "4984037284610", "is_representative": true, "email": "roberto.carlos@yopmail.com", "phone": { "international_dial_code": "+64", "area_code": "11", "number": "936360268" } } ] } } ``` ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | | ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. | --- ## Consulta Paginada de Análises ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analyses MÉTODO GET ### Path params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `limit` | integer | Limite de objetos | - | | `page` | integer | Página desejada | - | ### Response STATUS 200 ```json title='Response Body' { "data": [ { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_documents", "documents": [ { "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017", "document_type": "social_contract", "status": "valid", } ], "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "document_number": "802.834.257-41", "name": "Natália Nascimento", "documents": [ { "document_key": "72bad379-dbe6-40ca-97f2-1181257889ba", "document_type": "cnh", "status": "valid", } ] }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "883.512.866-80", "name": "Natália Nascimento", "documents": [ { "document_key": "8b9fe448-7ad7-4410-b8f7-5c920b07b9a7", "document_type": "cnh", "status": "valid", } ] } ], } ], "limit": 10, "page": 0, "is_last_page": true, } ``` ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | --- # Consulta de Cedente URL: /documentation/iaas/homologacao_cedente/consulta/consulta_de_cedente --- ## Consulta de Cedente Por Chave ### Request ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY MÉTODO GET --- ### Response STATUS 200 ```json title='Response Body' { "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "registred", "name": "QI CTVM", "document_number": "67.987.787/0001-06", "person_type": "legal_person", "email": "qidtvm@qitech.com.br", "annual_revenues": 1000000, "is_in_national_financial_system": true, "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" }, "related_parties": [ { "name": "Natália Nascimento", "document_number": "883.512.866-80", "related_party_type": "attorney", "nationality": "BRA", "direct_beneficiary": true, "is_representative": true, "email": "natalia.nascimento@yopmail.com", "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" } }, { "name": "Maria Vitoria", "related_party_type": "president", "nationality": "DEU", "passport_number": "C01X00T47", "direct_beneficiary": true, "is_representative": false }, { "name": "Roberto Carlos", "document_number": "802.834.257-41", "related_party_type": "director", "nationality": "BRA", "direct_beneficiary": false, "company_country": "NZL", "company_registry_number": "4984037284610", "is_representative": true, "email": "roberto.carlos@yopmail.com", "phone": { "international_dial_code": "+64", "area_code": "11", "number": "936360268" } } ], "last_analysis": { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_documents", "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "document_number": "802.834.257-41", "name": "Natália Nascimento", }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "883.512.866-80", "name": "Natália Nascimento", } ], "documents": [], "analysis_data": {} } } ``` ### Objeto Cedente | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignor_registry_key` | string | Identificador do cadastro. | 36 | | `name` * | string | Nome do cedente. | 1 a 255 | | `document_number` * | string | Número de documento do cedente (CNPJ). | 14 a 18 | | `status` | enumerador | Status do cadastro. | 14 a 18 | | `annual_revenues` * | number | Declaração de faturamento anual do cedente, em inteiros. | Mínimo de 1 | | `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - | | `email` * | string | Endereço de e-mail do cedente. | 1 a 255 | | `is_in_national_financial_system` * | boolean | Indicador se o cedente é integrante do SFN. | - | | `phone` | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](#definição-de-telefone)**. | | `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. | | `related_parties` * | array | Lista de partes relacionadas da empresa.| Ver **[Definição de Parte Relacionada](#definição-de-parte-relacionada)**. | | `accounts` * | array | Lista de contas de desembolso do cedente.| Ver **[Definição de Conta](#definição-de-conta)**. | | `guarantors` * | array | Lista de avalistas do cedente.| Ver **[Definição de Avalista](#definição-de-avalista)**. | ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. | --- ## Consulta Paginada de Cedentes ### Request ENDPOINT /assignor_registry/assignor_registries MÉTODO GET ### Path params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `name` | string | Nome do cedente | 1-255 | | `document_number` | string | Número de documento do cedente | 1-18 | | `assignor_registry_status` | string | Status do cedente | 1-255 | | `analysis_status` | string | Status da análise mais recente | 1-255 | | `limit` | integer | Limite de objetos | - | | `page` | integer | Página desejada | - | ### Response STATUS 200 ```json title='Response Body' { "data": [ { "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "registred", "name": "QI CTVM", "document_number": "67.987.787/0001-06", "person_type": "legal_person", "email": "qidtvm@qitech.com.br", "annual_revenues": 1000000, "is_in_national_financial_system": true, "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" }, "related_parties": [ { "name": "Natália Nascimento", "document_number": "883.512.866-80", "related_party_type": "attorney", "nationality": "BRA", "direct_beneficiary": true, "is_representative": true, "email": "natalia.nascimento@yopmail.com", "phone": { "international_dial_code": "+55", "area_code": "11", "number": "936360268" } }, { "name": "Maria Vitoria", "related_party_type": "president", "nationality": "DEU", "passport_number": "C01X00T47", "direct_beneficiary": true, "is_representative": false }, { "name": "Roberto Carlos", "document_number": "802.834.257-41", "related_party_type": "director", "nationality": "BRA", "direct_beneficiary": false, "company_country": "NZL", "company_registry_number": "49.846.582/0001-10", "is_representative": true, "email": "roberto.carlos@yopmail.com", "phone": { "international_dial_code": "+64", "area_code": "11", "number": "936360268" } } ], "last_analysis": { "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691", "analysis_number": 1, "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907", "status": "pending_documents", "analysis_related_parties": [ { "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59", "document_number": "802.834.257-41", "name": "Natália Nascimento", }, { "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721", "document_number": "883.512.866-80", "name": "Natália Nascimento", } ], "documents": [], "analysis_data": {} } } ], "limit": 10, "page": 0, "is_last_page": true, } ``` --- ## Consulta de Conjuntos de Assinantes A consulta dos assinantes vinculados ao cedente e suas partes relacionadas é feita através do endpoint paginado de conjuntos de assinantes (`signer_group_sets`), que retorna tanto os conjuntos padrão (`main`) gerados pela análise quanto os conjuntos customizados (`custom`) definidos pelo cliente. Para a especificação completa do endpoint — incluindo filtros disponíveis, formato de resposta e enumeradores —, consulte [Consulta de Conjuntos de Assinantes](/documentation/iaas/homologacao_cedente/cadastro/definicao_de_assinantes#consulta-de-conjuntos-de-assinantes) na seção de Definição de Assinantes. --- --- # Consultar Documentos URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/consulta_de_documentos --- ### Request ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY/attached_document/DOCUMENT_KEY MÉTODO GET ### Path Params | Parâmetro | Descrição | |------------------------------|------------------------------------| | `assignment_contract_key` | Chave da contrato de cessão | | `document_key` | Chave do documento | ### Response STATUS 200 ```json { "document_key":"UUID", "document_type":"manager_declaration | assignment_contract", "status":"signed | pending_signature", "document_template_key":"UUID", "required_parties":[ "manager | consultant | attestant" ], "download_url":"url para download do documento" } ``` :::info Observação O campo de download url trás a URL assinada para download do documento em sua versão mais atual, ou seja caso o documento esteja assinado ele vai trazer nesta mesma URL. A mesma expira, e não deve ser utilizada para consulta atemporal. ::: ### Definição de Documento Anexo | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` * | string | Chave única de identificação do documento. | 36 | | `document_type` * | string | Tipo do documento. | -- | | `status` * | string | Status do documento. | Ver **[Enumeradores de status do documento](#attached-document-status)**. | | `document_template_key` | string | Chave única de identificação do template que gerou o documento. | 36 | | `required_parties` | array | Lista de partes que assinam o documento em questão. | -- | | `download_url` | string | URL de download do PDF. | -- | ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ACT000023 | 404 | Contrato de cessão não encontrado para o `assignment_contract_key` informado. | Verificar se o `assignment_contract_key` está correto. | | ACT000087 | 404 | Documento anexo não encontrado para o `document_key` informado. | Verificar se o `document_key` pertence ao contrato indicado. | # Enumeradores ### Attached Document Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_generate** | Pendente geração do documento | | **approved** | Documento gerado | | **signed** | Documento assinado | --- # Manipulação de contrato URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/manutencao_do_contrato --- Dependendo do fluxo, pode ser necessário realizar algumas chamadas para concluir o fluxo de um contrato. --- # Aprovação do Gestor --- Caso o contrato seja proposto por uma consultoria, após a geração dos documentos, será necessária a aprovação do gestor, antes que o mesmo sja enviado para assinatura. ### Request ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY MÉTODO PUT ```json title='Request Body' { "status": "denied", "denial_reason": "Documentação do cedente insuficiente", } ``` #### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `status` * | string | Decisão do Gestor. denied ou approved | -- | | `denial_reason` | string | Descritivo com o motivo da recusa. | 1 a 500 | *Campos obrigatórios ### Response STATUS 202 ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ACT000023 | 404 | Contrato de cessão não encontrado para o `assignment_contract_key` informado. | Verificar se o `assignment_contract_key` está correto. | | ACT000025 | 400 | Apenas gestores podem realizar a aprovação ou recusa. | A aprovação/recusa deve ser feita por um agente com `AGENT-TYPE=manager`. | | ACT000077 | 400 | Status atual do contrato não permite aprovação ou recusa. | Para `approved`: o contrato deve estar em `pending_manager_approval`. Para `denied`: o contrato deve estar em `pending_manager_approval` ou `pending_document`. | --- # Envio para Assinatura Manual --- Caso o template configure envio manual para assinatura, é possível agrupar vários contratos, desde que os mesmos tenham o mesmo gestor, cedente e avalistas, para um mesmo lote de assinaturas. ### Request ENDPOINT /assignment_contract/signature_batch MÉTODO POST ```json title='Request Body' { "assignment_contract_keys": ["assignment_contract_key", "assignment_contract_key"], } ``` #### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `assignment_contract_keys` * | array | Lista de contratos para serem enviados no mesmo lote | -- | *Campos obrigatórios ### Response STATUS 202 ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ACT000023 | 404 | Contrato de cessão não encontrado para uma das chaves informadas. | Verificar todos os `assignment_contract_keys` enviados no array. | | ACT000088 | 400 | Status de um contrato não é válido para envio manual. | Todos os contratos do lote devem estar com `status=pending_signature_submission`. | | ACT000089 | 404 | Contratos do lote possuem partes relacionadas (gestor, cedente, avalistas) diferentes. | Apenas contratos com as mesmas partes relacionadas podem ser agrupados em um mesmo lote de assinaturas. | --- # Cancelamento de Contrato --- Em qualquer etapa, menos no caso de um contrato já assinado, é possível cancelar o mesmo. Caso esteja em assinatura, o evento de assinaturas também é cancelado ### Request ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY MÉTODO PUT ```json title='Request Body' { "status": "canceled" } ``` #### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `status` * | string | canceled | -- | *Campos obrigatórios ### Response STATUS 202 ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ACT000023 | 404 | Contrato de cessão não encontrado para o `assignment_contract_key` informado. | Verificar se o `assignment_contract_key` está correto. | | ACT000077 | 400 | Status atual do contrato não permite cancelamento. | Contratos com status `signed` ou `denied` não podem ser cancelados. | --- # Contrato de Cessão URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato --- Esse processo gera um contrato de cessão entre o Fundo de Investimento e o Cedente e o envia para a assinatura. Para gerar um contrato, é necessário possuir em mãos o fund_class_key do fundo, providenciado pelo time da QI CTVM, assim como um assignment_contract_template_key, também providenciado pelo time, que define os parâmetros do contrato, como coobrigação, documentos obrigatórios de cessão, cláusulas, etc. Na estrutura do contrato, existem os produtos, que identificam, por exemplo, uma configuração de cessão de um tipo de ativo, de recompra, e assim por diante. Serão enviados para assinatura dois documentos: o contrato propriamente dito, com todas as partes relacionadas envolvidas, como cedente, gestora, avalistas, etc.; e a declaração da gestora, a qual deve ser assinada apenas por esta, atestando que foram cumpridas todas as normas e exigências previstas pela CVM, Anbima e Banco Central quanto à operação do cedente, abrangendo desde a análise de risco até o PLD, entre outras que podem ser consultadas nos respectivos portais. O fluxo do contrato é variável: é possível configurar o envio dos documentos para assinatura assim que gerados, ou para aguardar um envio manual dos mesmos. Além disso, caso o mesmo seja proposto por um consultor, será necessária a aprovação do gestor, antes que o mesmo seja enviado para assinatura. Por último, caso o cadastro de cedente ainda não tenha sido liberado, ou o mesmo esteja em processo de atualização, será necessário aguardar a conclusão da última análise antes de enviar para assinatura. Caso a análise seja recusada, o contrato também é cancelado. Após a assinatura de ambos os documentos pelas partes requeridas, os produtos ficam pendentes de ativação, podendo levar alguns minutos para configurar a esteira de cessão, e finalmente, será possível usar a chave da configuração `assignment_configuration_key` de cessão do respectivo produto para realizar a cessão entre o fundo e o cedente. Opcionalmente, é possível definir avalistas da operação entre o cedente e o fundo, desde que o template de contrato permita tal. Os avalistas devem ser previamente cadastrados junto com o cedente, e apenas indicados no contrato pelo número do documento. Vale ressaltar que as contas de desembolso são definidas no cadastro do cedente. Todo o fluxo de assinatura do contrato é realizado pela nossa certificadora, CertifiQI, para maior comodidade e facilidade. O acompanhamento das assinaturas e posterior ativação do cedente se dá de forma automática graças a esse recurso. ### Request ENDPOINT /assignment_contract/assignment_contract MÉTODO POST ```json title='Request Body' { "fund_class_key": "813ce253-bae5-4448-8d15-04c48d9991b7", "assignor_document_number": "18.458.041/0001-91", "assignment_contract_template_key": "2555f90a-4c6a-4d65-8bda-5d16f827840c", "credit_limit": 1000000, "external_id": "Contrato 550", "observation": "Contrato referente ao vínculo com coobrigação do cedente", "guarantors": [ { "name": "Avalista da operação", "document_number": "81.914.413/0001-83" } ] } ``` #### Body Params | Campo | Tipo | Descrição | Caracteres | |-|-|-|-| | `fund_class_key` * | string | Chave única de identificação do Fundo. Gerada na criação do Fundo e fornecida pelo time da QI CTVM. | Chave uuid | | `assignment_contract_template_key` * | string | Chave única de identificação do Template de Contrato. Também fornecida pelo time da QI CTVM. | Chave uuid | | `assignor_document_number` * | string | Número do documento do cedente. | CPF ou CNPJ | | `credit_limit` | number | Valor do limite de crédito do contrato. | - | | `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato. | 1 a 255 | | `observation` | string | Observação. Campo livre para quaisquer anotações. | 1 a 500 | | `guarantors` | array | Avalistas da operação. | Ver **[Definição de Avalista](#definição-de-avalista)**. | *Campos obrigatórios :::warning Aviso É muito importante que os avalistas sejam indicados tanto no cadastro do cedente, quanto nessa etapa. Caso seja indicado somente no cadastro, e não no contrato, o avalista não irá assinar o documento. Caso seja indicado apenas no contrato, e não no cadastro, um erro será retornado. ::: --- ### Response STATUS 201 ```json title='Response Body' { "assignment_contract_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "pending_document", "products": [ { "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "assignment_configuration_key": "372f0449-4043-4523-9f0f-dff70c65b9c9", "product_type": "assignment_term", "asset_type": "ccb", "status": "pending_contract", "required_documents": [ "ccb" ] } ] } ``` :::info É de extrema importância salvar a `assignment_contract_key`, pois a mesma é utilizada para caracterizar as configurações de cessão geradas pelo contrato futuramente, principalmente as originadas pelo fluxo de filiais do tópico 5.2.2.6.. É possível recuperar as configurações geradas seguindo o GET do tópico 5.3.1.2. ::: ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ACT000001 | 404 | Classe de Fundo não encontrada para o `fund_class_key` informado. | Verificar se o `fund_class_key` está correto e pertence ao gestor autenticado. | | ACT000016 | 404 | Template de contrato não encontrado para o `assignment_contract_template_key` informado. | Verificar se o `assignment_contract_template_key` está correto e vinculado ao `fund_class_key`. | | ACT000123 | 400 | Template está inativo e não pode ser usado para criar contratos. | Utilizar um template ativo. | | ACT000065 | 404 | Cedente não cadastrado para o agente proponente. | Verificar se o `assignor_document_number` corresponde a um cedente cadastrado. | | ACT000096 | 400 | Cedente não possui conta cadastrada. | Cadastrar pelo menos uma conta de desembolso para o cedente antes de propor um contrato (ver [Manutenção de Contas](/documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas)). | | ACT000081 | 400 | Avalista não está cadastrado junto ao cedente. | Cada item em `guarantors` deve corresponder a um avalista previamente cadastrado para o cedente, com status `registered` ou `pending_registry`. | | ACT000095 | 409 | Número de caso (`case_number`) duplicado para este fundo. | Utilizar um `case_number` único dentro do mesmo `fund_class_key`, ou omitir o campo para gerar um automaticamente. | ### Definição de Contrato de Cessão | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignment_contract_key` * | string | Chave única de identificação do contrato. | 36 | | `fund_class` * | object | Objeto fundo | -- | | `assignor` * | object | Objeto cedente. | -- | | `consultant` | object | Objeto consultor. Somente quando o consultor for parte do contrato. | -- | | `assignment_contract_template` * | object | Objeto template de contrato. | -- | | `attached_documents` * | array | Lista de documentos anexos. | Ver **[Definição de documentos anexos](#definição-de-documento-anexo)**. | | `products` * | array | Lista de produtos sob o contrato. | Ver **[Definição de documentos anexos](#definição-de-documento-anexo)**. | | `proposal_agent` * | string | Tipo do agente proponente do contrato. | -- | | `status` * | string | Status do contrato. | Ver **[Enumeradores de status do contrato de cessão](#assignmnt-contract-status)**. | | `credit_limit` | number | Limite de crédito enviado. | -- | | `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato | 1 a 255 | | `case_number` | string | Número de caso. Único por fundo | -- | | `denial_reason` | string | Detalhes da recusa do gestor. | 1 a 255 | | `observation` | string | Observações enviadas. | 1 a 500 | | `creation_datetime` | string | Datetime da criação do contrato. | -- | ### Definição de Documento Anexo | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` * | string | Chave única de identificação do documento. | 36 | | `document_type` * | string | Tipo do documento. | -- | | `status` * | string | Status do documento. | Ver **[Enumeradores de status do documento](#attached-document-status)**. | | `document_template_key` | string | Chave única de identificação do template que gerou o documento | 36 | | `required_parties` | array | Lista de partes que assinam o documento em questão | -- | ### Definição de Produto | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `product_key` * | string | Chave única de identificação do produto. | 36 | | `assignment_configuration_key` * | string | Chave única de identificação da Configuração de Cessão. | 36 | | `asset_type` * | string | Tipo do ativo. | -- | | `status` * | string | Status do produto. | -- | ### Definição de Avalista | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `name` * | string | Nome do avalista. | 1 a 255 | | `document_number` * | string | CPF ou CNPJ. | 14 a 18 | *Campos obrigatórios :::warning Aviso Como já indicado, o avalista deve ser previamente cadastrado, junto com o cedente em específico. ::: # Enumeradores ### Assignment Contract Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_document** | Pendente geração dos documentos | | **sending_to_signature** | Em envio para assinatura | | **pending_signature** | Disponível para assinatura das partes | | **signed** | Assinado | | **pending_manager_approval** | Pendente aprovação do gestor | | **denied** | Reprovado na análise do gestor | | **pending_signature_submission** | Pendente envio manual para assinatura | | **pending_assignor_registry_release** | Pendente liberação do cadastro de cedente vinculado (Em fase de cadastro ou atualização) | | **canceled** | Cancelado | ### Attached Document Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_generate** | Pendente geração do documento | | **approved** | Documento gerado | | **signed** | Documento assinado | --- # Recuperação do Contrato URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato --- ## Recuperação do Contrato ### Request ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY MÉTODO GET ### Response STATUS 200 ```json title='Response Body' { "assignment_contract_key": "UUID", "fund_class": { "fund_class_key": "UUID", "name": "SAMPLE FUND NAME", "document_number": "00.000.000/0000-00", "manager": { "manager_key": "UUID", "document_number": "00.000.000/0000-00", "manager_name": "SAMPLE MANAGER NAME" } }, "assignor": { "assignor_key": "UUID", "document_number": "00.000.000/0000-00", "name": "SAMPLE ASSIGNOR NAME" }, "assignment_contract_template": { "assignment_contract_template_key": "UUID", "document_template_key": "UUID", "name": "NOME DO TEMPLATE", "borrower_agreement": null }, "attached_documents": [ { "document_key": "UUID", "document_type": "assignment_contract", "status": "pending_generate", "document_template_key": "UUID", "required_parties": ["manager", "assignor", "consultant"] } ], "proposal_agent": "consultant", "status": "pending_document", "credit_limit": 0.00, "external_id": "ID EXTERNO", "case_number": "NÚMERO DO PROCESSO", "denial_reason": "MOTIVO DA NEGATIVA", "creation_datetime": "YYYY-MM-DDTHH:MM:SSZ", "products": [ { "product_key": "UUID", "assignment_configuration_key": "UUID", "asset_type": "ccb | duplicata_mercantil | duplicata_servico", "status": "pending_signature | active | canceled", "has_coobligation": true, } ], "signature_batch_key": "UUID" } ``` ### Definição de Contrato de Cessão | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `assignment_contract_key` * | string | Chave única de identificação do contrato. | 36 | | `fund_class` * | object | Objeto fundo | -- | | `assignor` * | object | Objeto cedente. | -- | | `consultant` | object | Objeto consultor. Somente quando o consultor for parte do contrato. | -- | | `assignment_contract_template` * | object | Objeto template de contrato. | -- | | `attached_documents` * | array | Lista de documentos anexos. | Ver **[Definição de documentos anexos](#definição-de-documento-anexo)**. | | `products` * | array | Lista de produtos sob o contrato. | Ver **[Definição de documentos anexos](#definição-de-documento-anexo)**. | | `proposal_agent` * | string | Tipo do agente proponente do contrato. | -- | | `status` * | string | Status do contrato. | Ver **[Enumeradores de status do contrato de cessão](#assignmnt-contract-status)**. | | `credit_limit` | number | Limite de crédito enviado. | -- | | `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato | 1 a 255 | | `case_number` | string | Número de caso. Único por fundo | -- | | `denial_reason` | string | Detalhes da recusa do gestor. | 1 a 255 | | `observation` | string | Observações enviadas. | 1 a 500 | | `signature_batch_key` | string | Identificador do lote de assinaturas. | 36 | | `creation_datetime` | string | Datetime da criação do contrato. | -- | ### Definição de Documento Anexo | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `document_key` * | string | Chave única de identificação do documento. | 36 | | `document_type` * | string | Tipo do documento. | -- | | `status` * | string | Status do documento. | Ver **[Enumeradores de status do documento](#attached-document-status)**. | | `document_template_key` | string | Chave única de identificação do template que gerou o documento | 36 | | `required_parties` | array | Lista de partes que assinam o documento em questão | -- | ### Definição de Produto | Campo | Tipo | Descrição | Caracteres | |-------|------|-----------|------------| | `product_key` * | string | Chave única de identificação do produto. | 36 | | `assignment_configuration_key` * | string | Chave de identificação da configuração de cessão. Necssária na esteira de compra de ativos. | 36 | | `asset_type` * | string | Tipo do ativo. | -- | | `status` * | string | Status do produto. | -- | ### Erros Tratáveis | Código | HTTP | Causa | Como resolver | |--------|------|-------|---------------| | ACT000023 | 404 | Contrato de cessão não encontrado para o `assignment_contract_key` informado. | Verificar se o `assignment_contract_key` está correto. | --- # Listagem de Contratos de Cessão --- ### Request ENDPOINT /assignment_contract/assignment_contracts MÉTODO GET ### Query Params | Parâmetro | Descrição | |-----------------------------|---------------------------------------------------------------------------| | `assignor_document_number` | Documento do cedente | | `fund_class_document_number`| Documento do fundo | | `fund_class_key` | Identificador único do fundo (UUID) | | `status` | Status da cessão | | `case_number` | Número do caso | | `start_date` | Data de início | | `end_date` | Data de fim | ### Response STATUS 200 ```json title='Response Body' { "data": [ { "assignment_contract_key": "UUID", "fund_class": { "fund_class_key": "UUID", "name": "SAMPLE FUND NAME", "document_number": "00.000.000/0000-00", "manager": { "manager_key": "UUID", "document_number": "00.000.000/0000-00", "manager_name": "SAMPLE MANAGER NAME" } }, "assignor": { "assignor_key": "UUID", "document_number": "00.000.000/0000-00", "name": "SAMPLE ASSIGNOR NAME" }, "assignment_contract_template": { "assignment_contract_template_key": "UUID", "document_template_key": "UUID", "name": "NOME DO TEMPLATE", "borrower_agreement": null }, "attached_documents": [ { "document_key": "UUID", "document_type": "assignment_contract", "status": "pending_generate", "document_template_key": "UUID", "required_parties": ["manager", "assignor", "consultant"] } ], "proposal_agent": "consultant", "status": "pending_document", "credit_limit": 0.00, "external_id": "ID EXTERNO", "case_number": "NÚMERO DO PROCESSO", "denial_reason": "MOTIVO DA NEGATIVA", "creation_datetime": "YYYY-MM-DDTHH:MM:SSZ", "products": [ { "product_key": "UUID", "assignment_configuration_key": "UUID", "asset_type": "ccb | duplicata_mercantil | duplicata_servico", "status": "pending_signature | active | canceled", "has_coobligation": true, } ], "signature_batch_key": "UUID" } ], "limit": 10, "page": 0, "is_last_page": true } ``` # Enumeradores ### Assignment Contract Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_document** | Pendente geração dos documentos | | **sending_to_signature** | Em envio para assinatura | | **pending_signature** | Disponível para assinatura das partes | | **signed** | Assinado | | **pending_manager_approval** | Pendente aprovação do gestor | | **denied** | Reprovado na análise do gestor | | **pending_signature_submission** | Pendente envio manual para assinatura | | **pending_assignor_registry_release** | Pendente liberação do cadastro de cedente vinculado (Em proceso de cadastro ou atualização) | | **canceled** | Cancelado | ### Attached Document Status | Enumerador | Descrição | | ----------------------- | --------------------- | | **pending_generate** | Pendente geração do documento | | **approved** | Documento gerado | | **signed** | Documento assinado | --- # Webhooks do Contrato URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato --- #### Pendente Aprovação do Gestor STATUS pending manager approval ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "pending_manager_approval" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Pendente Envio para Assinatura STATUS pending signature submission ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "pending_signature_submission" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Pendente Liberação do Cadastro do Cedente STATUS pending assignor registry release ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "pending_assignor_registry_release" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Recusado pelo Gestor STATUS denied ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "denied" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Contrato Enviado para Assinatura STATUS pending signature ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "pending_signature" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Assinado STATUS signed ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "signed" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Contrato Cancelado STATUS canceled ```json title='Webhook Body' { "data":{ "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "external_id": "Contrato número 550", "status": "canceled" }, "webhook_type":"assignment_contract.assignment_contract_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` # Webhooks do Produto --- #### Produto Ativado STATUS active ```json title='Webhook Body' { "data":{ "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "assignment_configuration_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "active" }, "webhook_type":"assignment_contract.product_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` #### Produto Em Ativação STATUS pending_create_assignment_configuration ```json title='Webhook Body' { "data":{ "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "assignment_configuration_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "pending_create_assignment_configuration" }, "webhook_type":"assignment_contract.product_status_change", "webhook_datetime":"2025-01-22T20:30:23.459Z" } ``` --- # Introdução URL: /documentation/iaas/homologacao_cedente/inicio A parte de cadastro de Cedente é essencial para o início da operação de qualquer fundo que compre direitos creditórios. Nessa seção iremos explicar todo o fluxo, desde o envio das primeiras informações, até a abertura da Esteira de Cessão para envio de Ativos. Para ter acesso aos serviços discutidos nas próximas sessões, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox) quanto em ambiente de produção. É importante mencionar que para a efetiva liberação de um Cedente, deve-se consumir dois diferentes sistemas: 1. O cadastro do Cedente em nossa base, realizado uma única vez; 2. Formalização de um Contrato de Cessão, entre o Cedente e o Fundo; Para ambos os sistemas, tanto o gestor quanto o consultor podem atuar como agentes, propondo cadastros e contratos entre os cedentes e os fundos de acordo com o desenvolver da operação. ### Cadastro do Cedente Nessa etapa, deve-se enviar todas as informações tanto do Cedente quanto dos seus representantes e beneficiários finais. Uma vez feito o envio, o Cedente nasce Pendente Registro, é gerada uma primeira análise e deve-se enviar a documentação necessária, validando o cadastro. Por fim, após anexar todos os documentos necessários deve-se comandar o disparo da Análise, ou seja, o envio da Análise para validação, a qual passará por um processo de anti-fraude e PLD. Alguns documentos são necessários para a análise realizada, no caso de uma pessoa jurídica, o contrato social, com a última atualização disponível, certidão simplificada da Junta Comercial, e a ata de eleição da diretoria vigente. Além disso, devem ser enviados os documentos dos beneficiários finais da empresa, para fins de combate à lavagem de dinheiro, corrupção e financiamento ao terrorismo. Para cedentes pessoa física, apenas o documento de identificação é suficiente para a análise. Em ambos os casos, é necessário um termo de responsabilidade do agente de cadastro, afirmando que realizou todo o levante de documentos, como comprovantes de faturamento, compliance, entre outros, propostos pela norma da CVM e da AMBIMA. Assim que esta primeira Análise for aprovada, o cadastro passará por uma etapa de validação interna, onde uma equipe validará as informações recebidas e dará seguimento ao mesmo, após a validação dos assinantes. Assim que efetivado, o cedente estará disponível para as próximas operações. Nesse momento, caso configurado, enviamos um Webhook notificando que a Análise foi aprovada, mas também é possível acompanhar os cedentes cadastrados pelo portal do gestor. ### Atualização de Cedente Em caso de necessidade de atualização cadastral, deve-se enviar novamente todas as informações do Cedente com as modificações desejadas. Após envio, é gerada uma nova Análise em que é necessário anexar a documentação necessária para garantirmos a validade da atualização. Por fim, após anexar todos os documentos necessários deve-se comandar o disparo da Análise, ou seja, o envio da nova Análise para validação. Vale ressaltar que os documentos que devem ser enviados, são apenas os das entidades que foram alteradas, seja a adição de um novo representante, ou alteração de algum dado cadastral da companhia. Assim que esta nova Análise for aprovada, os novos dados cadastrais do Cedente são efetivamente alterados. Nesse momento, caso configurado, enviamos um Webhook notificando que a Análise foi aprovada. Note que, uma atualização cadastral de um Cedente não gera impedimento em realizar novas operações com ele. ### Formalização de Contrato de Cessão Para formalizar a relação entre o Cedente e o Fundo, é necessário a assinatura de um Contrato de Cessão, que rege essa venda de ativos. Nós disponibilizamos uma API que viabiliza esse processo de maneira automática. O processo envolve o pedido de formalização, a partir de um template, que irá disparar internamente a criação do contrato e envio para assinatura. Uma vez com o contrato assinado, os produtos definidos pelo template ficam disponíveis para ativação. Assim o cliente escolhe qual produto quer ativar, e indica a conta de desembolso. Será retornada, através da ativação do Produto, a chave da Configuração de Cessão gerada, identificador que será utilizado posteriormente no processo de compra e venda de ativos.