# 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
18 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 assinantes (/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes)
- 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.

:::

Quem faz o quê:

| Ação | Gestora | Consultoria | Cedente |
|------|---------|-------------|---------|
| Listar apontamentos da análise | Sim | Sim | Não (use o webhook e a consulta por chave) |
| Consultar apontamento e documento | Sim | Sim | Sim |
| Responder | `PUT .../annotation/{annotation_key}` | `PUT .../annotation/{annotation_key}` | `PUT .../annotation/{annotation_key}/response` |

---

## Consulta Paginada de Apontamentos

Recupera a lista de apontamentos de uma análise, permitindo ao agente identificar o que precisa ser respondido.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura |
| Consultoria | `consultant-api` | Ler Cedentes |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

O cedente não tem esta listagem: ele recebe o [webhook de apontamento](/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise#webhooks-de-apontamento), que traz a `annotation_key`, e consulta o apontamento por chave.

### Request

ENDPOINT /assignor_registry/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

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000026` | O agente autenticado não está habilitado no cadastro de cedentes. |
| 400 | — | `limit` acima de `50` ou `page` negativo. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## Consulta de Apontamento por Chave

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura |
| Consultoria | `consultant-api` | Ler Cedentes |
| Cedente     | `assignor-api`   | Leitura |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### Request

ENDPOINT /assignor_registry/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

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | `assignor_registry_key` não encontrado ou o agente não tem acesso a esse cedente. |
| 404 | `ASR000033` | `analysis_key` não encontrado. |
| 404 | `ASR000043` | `annotation_key` não pertence à análise indicada. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## Resposta ao Apontamento

Envia a resposta a um apontamento `open`. Opcionalmente, é possível anexar um documento em PDF (até 20 MB) que comprove ou complemente a resposta. Respondido, o apontamento passa para `closed` e o webhook de apontamento é disparado.

A gestora e a consultoria respondem pelo `PUT` no próprio apontamento; o cedente responde pelo `PUT` em `/response`. O corpo e a resposta são os mesmos.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Escrita |
| Consultoria | `consultant-api` | Cadastrar Cedente |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### Request (gestora e consultoria)

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY
MÉTODO PUT

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Cedente     | `assignor-api`   | Escrita |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### Request (cedente)

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY/response
MÉTODO PUT

### Request Body

```json title='Request Body'
{
    "response": "Segue autos do processo.",
    "document_b64": "JVBERi0xLjQK..."
}
```

### Objeto de Resposta

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `response` * | string | Texto de resposta ao apontamento. | 1 - 3000 |
| `document_b64` | string | Arquivo PDF codificado em Base64. Até 20 MB. | - |

\*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

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | `assignor_registry_key` não encontrado ou o agente não tem acesso a esse cedente. |
| 404 | `ASR000033` | `analysis_key` não encontrado. |
| 404 | `ASR000043` | `annotation_key` não pertence à análise indicada. |
| 400 | `ASR000045` | O apontamento não está `open`. |
| 400 | `ASR000044` | O apontamento já foi respondido. Cada apontamento aceita uma única resposta. |
| 400 | `ASR000005` | `document_b64` não é Base64 válido. |
| 400 | `ASR000060` | O conteúdo de `document_b64` não é um PDF. |
| 400 | `ASR000059` | O PDF passa de 20 MB. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## Consulta de Documento do Apontamento

Recupera uma URL temporária para download do documento anexado a um apontamento. A `DOCUMENT_KEY` é o `attached_document_key` do apontamento.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura |
| Consultoria | `consultant-api` | Ler Cedentes |
| Cedente     | `assignor-api`   | Leitura |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### Request

ENDPOINT /assignor_registry/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://URL_TEMPORARIA_DO_DOCUMENTO"
}
```

:::info

A `document_url` retornada é uma URL pré-assinada com validade de 24 horas.

:::

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | `assignor_registry_key` não encontrado ou o agente não tem acesso a esse cedente. |
| 404 | `ASR000033` | `analysis_key` não encontrado. |
| 404 | `ASR000043` | `annotation_key` não pertence à análise indicada. |
| 404 | `ASR000006` | `DOCUMENT_KEY` não é o documento anexado ao apontamento. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## 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 |
| ---------- | --------- |
| **open** | Aberto e aguardando resposta do agente. |
| **closed** | Respondido e encerrado. A QI DTVM pode reabri-lo (volta a `open`). |

### 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 importância, 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.

:::caution 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 realizadas. 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

Se houver uma análise em andamento quando a atualização cadastral for enviada, ela é cancelada automaticamente (`analysis_status: canceled`, com `reproval_details` indicando a atualização cadastral) e uma nova análise é gerada.

:::

---

## Atualização de Cadastro de Cedente Pessoa Jurídica

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Escrita |
| Consultoria | `consultant-api` | Cadastrar Cedente |
| Cedente     | `assignor-api`   | Escrita |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY
MÉTODO PUT

```json title='Request Body'
{
  "email": "financeiro@cedente-exemplo.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": "123.456.789-09",
      "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": "969.698.790-03",
      "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": "222.333.444-05",
      "person_type": "natural_person",
      "email": "email@avalista.com"
    },
    {
      "name": "Avalista PJ",
      "document_number": "22.333.444/0001-81",
      "person_type": "legal_person",
      "email": "email@avalista.com",
      "guarantor_representatives": [
        {
          "name": "Assinante do Avalista",
          "document_number": "111.444.777-35",
          "email": "emailrepresentante@avalista.com"
        }
      ]
    }
  ]
}
```

---

### Definição do Cedente

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` | string | Nome/razão social do cedente. | 1 a 255 |
| `annual_revenues` | integer | 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 |
| `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](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-telefone)**. |
| `address`  | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-endereco)**. |
| `related_parties`  | array | Lista de partes relacionadas da empresa.| Ver  **[Definição de Parte Relacionada](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-parte-relacionada)**. |
| `minimum_required_signers` | integer | Quantidade mínima de representantes que precisam assinar pelo cedente. | Mínimo de 1 |
| `guarantors` | array | Lista de avalistas do cedente.| Ver  **[Definição de Avalista](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-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": "registered",
  "name": "Cedente Exemplo LTDA",
  "document_number": "55.666.777/0001-81",
  "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": "969.698.790-03",
        "name": "Roberto Carlos",
        "documents": []
      },
      {
        "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
        "document_number": "123.456.789-09",
        "name": "Natália Nascimento",
        "documents": []
      },
      {
        "analysis_related_party_key": "8a3e2f61-0c4b-4d7e-9f15-2b6c7d8e9a01",
        "passport_number": "C01X00T47",
        "name": "Maria Vitoria",
        "documents": []
      }
    ],
    "documents": [
      {
        "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017",
        "document_type": "social_contract",
        "status": "valid"
      }
    ]
  }
}
```

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | Identificador do cadastro. | 36 |
| `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](/documentation/iaas/homologacao_cedente/cadastro/envio_de_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](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-analise)**. |

:::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

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` existe (ou, para gestora e consultoria, se o cadastro pertence à sua integração). |
| 400 | `ASR000100` | Campo enviado não pode ser atualizado em uma filial: `name`, `related_parties` e `guarantors` são sempre os da matriz. Para alterá-los, atualize o cadastro da matriz. |
| 400 | `ASR000128` | Uma filial vinculada a esta matriz está com análise em andamento. Aguarde a conclusão da análise da filial e reenvie a atualização da matriz. |
| 400 | `ASR000056` | 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. |
| 400 | `ASR000054` | 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. |
| 400 | `ASR000057` | Cedente pessoa jurídica deve ter pelo menos 1 representante assinante. Garantir que ao menos uma parte relacionada tenha `is_representative=true`. |
| 400 | `ASR000011` | Número de documento de parte relacionada duplicado. Cada `document_number` em `related_parties` deve ser único. |
| 400 | `ASR000041` | Email obrigatório para representante. Para partes relacionadas com `is_representative=true`, informar `email`. |
| 400 | `ASR000058` | Pessoa estrangeira sem CPF não pode ser assinante. Estrangeiros sem `document_number` (CPF) não podem ter `is_representative=true`. |
| 400 | `ASR000078` | Número de documento de avalista duplicado. Cada avalista em `guarantors` deve ter `document_number` único. |
| 400 | `ASR000079` | Avalista pessoa física não aceita representante. Para `person_type=natural_person`, só é aceito o cônjuge: `related_party_type: spouse`. |
| 400 | `ASR000080` | Documento de representante de avalista duplicado. Cada representante em `guarantor_representatives` deve ter `document_number` único. |
| 400 | `ASR000091` | Avalista pessoa jurídica deve ter pelo menos um representante. Para `person_type=legal_person`, enviar pelo menos um item em `guarantor_representatives`. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

# 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`), um **avalista** (`guarantor`) ou o **cônjuge** de um avalista pessoa física (`spouse`).

A definição customizada permite, por exemplo, exigir múltiplos assinantes, ou restringir quem pode assinar determinado produto.

:::

:::caution 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.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Escrita |
| Consultoria | `consultant-api` | Cadastrar Cedente |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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": "123.456.789-09",
              "is_required_signer": true
            },
            {
              "document_number": "969.698.790-03",
              "is_required_signer": false
            }
          ],
          "expiration": "2026-12-31"
        }
      ]
    },
    {
      "product": "commercial_paper",
      "signer_groups": [
        {
          "minimum_required_signers": 1,
          "signers": [
            {
              "document_number": "123.456.789-09",
              "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` igual a `valid` são utilizados nas assinaturas.

:::

:::caution 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.

:::

:::caution Atenção

Caso o `custom` signer group enviado seja **menos restritivo** que o validado pela Administradora, a análise será **negada**.

:::

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto. |
| 404 | `ASR000033` | Análise não encontrada para o `analysis_key` informado. Verificar se o `analysis_key` está correto. |
| 400 | `ASR000066` | Status da análise não permite definição de grupos customizados. A análise deve estar em `pending_documents` para receber grupos customizados. |
| 404 | `ASR000109` | Tipo de produto inválido. Usar um valor válido para `product` (ver enum [Product Type](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes#product-type)). |
| 400 | `ASR000118` | Signatário inválido. O `document_number` enviado em `signers` deve corresponder a um representante já cadastrado para o cedente, com `is_representative=true`. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## Definição de Conjunto Customizado para Parte Relacionada

Permite definir conjuntos customizados para um **avalista** ou para o **cônjuge** de um avalista pessoa física, utilizando a `analysis_related_party_key` retornada na criação da análise.

:::info Informação

Este endpoint customiza os assinantes de um **avalista** ou do **cônjuge** de um avalista pessoa física, identificado pela `analysis_related_party_key`. Para os representantes do próprio cedente, use o endpoint de conjunto customizado do cedente acima. Para outras partes relacionadas, a chamada não cria conjunto.

:::

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Escrita |
| Consultoria | `consultant-api` | Cadastrar Cedente |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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": "111.444.777-35",
              "is_required_signer": true
            }
          ],
          "expiration": "2026-12-31"
        }
      ]
    }
  ]
}
```

### Response

STATUS 204

Sem conteúdo no corpo de resposta.

:::caution 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.

:::

:::caution Atenção

Caso o `custom` signer group enviado seja **menos restritivo** que o validado pela Administradora, a análise será **negada**.

:::

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto. |
| 404 | `ASR000033` | Análise não encontrada para o `analysis_key` informado. Verificar se o `analysis_key` está correto. |
| 404 | `ASR000035` | 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 cônjuge de avalista da análise. |
| 400 | `ASR000066` | Status da análise não permite definição de grupos customizados. A análise deve estar em `pending_documents` para receber grupos customizados. |
| 404 | `ASR000109` | Tipo de produto inválido. Usar um valor válido para `product` (ver enum [Product Type](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes#product-type)). |
| 400 | `ASR000118` | 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). |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## Consulta de Conjuntos de Assinantes

Para consultar os conjuntos vigentes (padrão e customizados) e obter a `signer_group_set_key`, use a [Consulta de Assinantes](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes). Os enumeradores de `owner_type`, `product_type`, `signer_group_set_type` e `status` estão documentados nessa página.

---

## Definições

### 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](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes#product-type)**. |
| `signer_groups` * | array | Lista de grupos de assinantes (mínimo 1). | Ver **[Definição de Grupo de Assinantes](#definicao-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](#definicao-de-assinante-signer)**. |
| `expiration` | string | Data de expiração do grupo no formato `YYYY-MM-DD`. Aceito no envio; na consulta, grupos expirados não aparecem. | 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.

:::

---

# 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á também montada 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.

---

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Escrita |
| Consultoria | `consultant-api` | Cadastrar Cedente |
| Cedente     | `assignor-api`   | Escrita |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

## 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 202

O corpo é a análise completa, no formato da [Consulta de Análise](/documentation/iaas/homologacao_cedente/consulta/consulta_de_analise). Trecho:

```json title='Response Body'
{
  "analysis_key": "2b1fa466-4d36-48e9-b6e3-776a1b700b9f",
  "analysis_number": 1,
  "assignor_registry_key": "d0a93900-457d-496a-8326-480ecaf946c3",
  "assignor_registry_status": "pending_registry",
  "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.

:::

:::caution Não deixe a análise parada

Uma análise que fica **1 mês sem movimentação** e ainda não foi concluída é **cancelada automaticamente** (`canceled`). O caso mais comum é a análise parada em `pending_documents`. Depois de cancelada, ela não pode mais ser disparada: a tentativa é recusada com `ASR000034`. Nesse caso, gere uma nova análise por meio da [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro).

:::

## Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto (ou, para gestora e consultoria, se o cadastro pertence à sua integração). |
| 404 | `ASR000033` | Análise não encontrada para o `analysis_key` informado. Verificar se o `analysis_key` está correto. |
| 400 | `ASR000040` | A análise não pertence ao cedente informado. Garantir que `analysis_key` e `assignor_registry_key` correspondam à mesma análise. |
| 400 | `ASR000034` | 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). Se estiver `canceled`, ela foi cancelada por inatividade e é preciso gerar uma nova análise. |
| 400 | `ASR000038` | Status enviado é inválido. O campo `analysis_status` deve ser exatamente `sent_to_analysis`. |
| 400 | `ASR000009` | 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). |
| 400 | `ASR000015` | 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. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

# 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 Sandbox

Em sandbox, o resultado da análise depende do primeiro dígito do documento do **cedente** (`document_number`): começando com 1, reprovação automática; começando com 8, a análise vai para validação manual (`pending_internal_validation`); os demais são aprovados automaticamente.

:::

---
## Cadastro de Cedente

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Escrita |
| Consultoria | `consultant-api` | Cadastrar Cedente |
| Cedente     | `assignor-api`   | Escrita |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### Request

ENDPOINT /assignor_registry/assignor_registry
MÉTODO POST

```json title='Request Body'
{
  "name": "Cedente Exemplo LTDA",
  "document_number": "55.666.777/0001-81",
  "person_type": "legal_person",
  "email": "financeiro@cedente-exemplo.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": "123.456.789-09",
      "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": "969.698.790-03",
      "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": "222.333.444-05",
      "person_type": "natural_person",
      "email": "email@avalista.com"
    },
    {
      "name": "Avalista PJ",
      "document_number": "22.333.444/0001-81",
      "person_type": "legal_person",
      "email": "email@avalista.com",
      "guarantor_representatives": [
        {
          "name": "Assinante do Avalista",
          "document_number": "111.444.777-35",
          "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 | CPF ou CNPJ do cedente, formatado (`000.000.000-00` ou `00.000.000/0000-00`). | 14 a 18 |
| `annual_revenues` * | number | Declaração de faturamento anual do cedente, em inteiros. | Mínimo de 1 |
| `person_type` * | string | `natural_person` (física) ou `legal_person` (jurídica). | - |
| `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](#definicao-de-telefone)**. |
| `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definicao-de-endereco)**. |
| `related_parties` ** | array | Lista de partes relacionadas da empresa.| Ver  **[Definição de Parte Relacionada](#definicao-de-parte-relacionada)**. |
| `accounts` | array | Lista de contas de desembolso do cedente. Sem conta, não é possível propor um contrato de cessão.| Ver  **[Definição de Conta](#definicao-de-conta)**. |
| `guarantors` | array | Lista de avalistas do cedente.| Ver  **[Definição de Avalista](#definicao-de-avalista)**. |
| `minimum_required_signers` | integer | Quantidade mínima de representantes que precisam assinar pelo cedente. | Mínimo de 1 |

\*Campos obrigatórios.

\*\*Obrigatório para pessoa jurídica, com ao menos um representante assinante (`is_representative: true`).

### Response

STATUS 201

```json title='Response Body'
{
  "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907",
  "status": "pending_registry",
  "name": "Cedente Exemplo LTDA",
  "document_number": "55.666.777/0001-81",
  "related_parties": [
    {
      "related_party_key": "0b6f6a52-6c1e-4f4e-9d2a-1f3c5e7a9b10",
      "name": "Natália Nascimento",
      "document_number": "123.456.789-09",
      "direct_beneficiary": true,
      "is_representative": true,
      "related_party_type": "attorney"
    },
    {
      "related_party_key": "3e9d1c7b-2a4f-4b8e-8c6d-5f7a9b1c3d20",
      "name": "Maria Vitoria",
      "document_number": null,
      "direct_beneficiary": true,
      "is_representative": false,
      "related_party_type": "president",
      "passport_number": "C01X00T47"
    },
    {
      "related_party_key": "7a2c4e6f-8b0d-4f1a-9c3e-5d7f9a1b3c30",
      "name": "Roberto Carlos",
      "document_number": "969.698.790-03",
      "direct_beneficiary": false,
      "is_representative": false,
      "related_party_type": "director"
    }
  ],
  "last_analysis": {
    "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691",
    "analysis_number": 1,
    "status": "pending_documents",
    "analysis_datetime": "2026-01-15T14:32:10Z",
    "analysis_related_parties": [
      {
        "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59",
        "name": "Roberto Carlos",
        "document_number": "969.698.790-03",
        "analysis_roles": [{ "related_party_type": "director" }],
        "documents": []
      },
      {
        "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
        "name": "Natália Nascimento",
        "document_number": "123.456.789-09",
        "analysis_roles": [{ "related_party_type": "attorney" }],
        "documents": []
      },
      {
        "analysis_related_party_key": "8a3e2f61-0c4b-4d7e-9f15-2b6c7d8e9a01",
        "name": "Maria Vitoria",
        "document_number": null,
        "analysis_roles": [{ "related_party_type": "president" }],
        "documents": [],
        "passport_number": "C01X00T47"
      },
      {
        "analysis_related_party_key": "1f4b6d8a-3c5e-4a7b-9d1f-2e4a6c8b0d40",
        "name": "Avalista PF",
        "document_number": "222.333.444-05",
        "analysis_roles": [{ "related_party_type": "guarantor" }],
        "documents": []
      },
      {
        "analysis_related_party_key": "9c1e3a5b-7d9f-4b2c-8e4a-6f8b0c2d4e50",
        "name": "Avalista PJ",
        "document_number": "22.333.444/0001-81",
        "analysis_roles": [{ "related_party_type": "guarantor" }],
        "documents": []
      },
      {
        "analysis_related_party_key": "4d6f8b0c-2e4a-4c6d-8f0b-1a3c5e7d9f60",
        "name": "Assinante do Avalista",
        "document_number": "111.444.777-35",
        "analysis_roles": [{ "related_party_type": "guarantor_representative" }],
        "documents": []
      }
    ],
    "documents": [],
    "annotations": [],
    "last_updated": "2026-01-15T14:32:10Z",
    "analysis_origin_type": "assignor_registry",
    "reproval_reason": null,
    "reproval_details": null
  }
}
```

| 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 |
| `related_parties` | array | Partes relacionadas do cedente, com `related_party_key`, `name`, `document_number`, `direct_beneficiary`, `is_representative`, `related_party_type` e, para estrangeiros, `passport_number`. | - |
| `last_analysis`  | object | Objeto de análise. | Ver **[Definição de Análise](#definicao-de-analise)**. |

:::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.
:::

---

## 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](#definicao-de-endereco)**. |
| `email` **** | string | Endereço de e-mail do representante. | 1 a 255 |
| `phone` | object | Objeto referenciando as informações do telefone do representante. Recomendado para representantes assinantes. |  Ver **[Definição de Telefone](#definicao-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.

\*\*\*\*Campo exigido 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](#definicao-de-partes-relacionadas-de-analise)**. |
| `documents` * | array | Documentos da análise. | Ver **[Definição de Documentos de análise](#definicao-de-documentos)**. |
| `analysis_datetime` * | string | Data e hora de criação da análise (ISO 8601, UTC). | - |
| `annotations` * | array | Apontamentos da análise. | - |
| `last_updated` * | string | Data e hora da última alteração da análise (ISO 8601, UTC). | - |
| `analysis_origin_type` * | string | Origem da análise. Para cadastros enviados pela API, `assignor_registry`. | - |
| `analysis_data` | object | Request body que originou a análise. Só vem na [consulta da análise](/documentation/iaas/homologacao_cedente/consulta/consulta_de_analise); não vem no retorno do cadastro. | - |
| `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 |
| `passport_number` | string | Passaporte, só para estrangeiros que o informaram. | - |
| `analysis_roles` * | array | Papéis da pessoa na análise, cada um com `related_party_type` (por exemplo, `director`, `guarantor` ou `guarantor_representative`). | - |
| `documents` * | array | Documentos da análise da parte relacionada. | Ver **[Definição de Documentos de análise](#definicao-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. Só dígitos. | 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. | - |
| `description` | string | Descrição livre da conta. | Até 255 |

\*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.

:::caution 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](#definicao-de-telefone)**. |
| `address` | object | Objeto referenciando as informações do endereço do avalista. | Ver **[Definição de Endereço](#definicao-de-endereco)**. |
| `guarantor_representatives` | array | Representantes do avalista PJ ou cônjuge do avalista PF. | Ver  **[Definição de Representante do Avalista](#definicao-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.

:::caution Atenção
Tanto o avalista quanto os representantes também serão adicionados à análise 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](#definicao-de-endereco)**. |
| `phone` | object | Objeto referenciando as informações do telefone do representante do avalista. |  Ver **[Definição de Telefone](#definicao-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. |
| `related_party_type` | string | `guarantor_representative` (padrão) para representante de avalista PJ; `spouse` para o cônjuge de avalista PF (outorga uxória). | - |

---

## Enumeradores

### Assignor Registry Status

| Enumerador                 | Descrição       |
| -------------------------- | ----------------- |
| **created** | Criado (transitório) |
| **pending_registry** | Pendente Registro |
| **pending_manual_approval** | Pendente aprovação manual da QI DTVM |
| **registered**       | Registrado        |
| **rejected** | Rejeitado |
| **blocked** | Bloqueado |

---

### Analysis Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **created** | Criada (transitório) |
| **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    |
| **in_risk_analysis** | Em Análise de Risco |
| **approved**           | Aprovado              |
| **reproved**           | Reprovado             |
| **canceled**           | Cancelado             |

---

### Related Party Type

| Enumerador              | Descrição   |
| ----------------------- | ------------- |
| **president**     | Presidente    |
| **partner**       | Sócio        |
| **administrator** | Administrador |
| **director**      | Diretor       |
| **manager**       | Gestor        |
| **attorney**      | Procurador    |
| **spouse**        | Cônjuge       |
| **legal_representative** | Representante legal |

---

### Document Status

| Enumerador              | Descrição   |
| ----------------------- | ------------- |
| **created**     | Criado    |
| **valid**       | Válido        |
| **invalid** | Inválido |
| **canceled** | Cancelado |
| **accepted** | Aceito, porém não validado |
| **inconclusive** | Validação inconclusiva |

---

### 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.           |
| **national_registry_of_foreigners** | Registro Nacional de Estrangeiros. |
| **cin_digital**                 | Carteira de Identidade Nacional (Digital).           |
| **social_contract**          | Contrato/Estatuto Social.   |
| **cnpj_card**          | Cartão CNPJ.   |
| **commercial_board_certificate** | Certidão Simplificada 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      |
| **saving_account** | Conta Poupança |
| **escrow_account** | Conta Vinculada (escrow) |

---

### 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 |
| **risk_analysis_reproval** | Reprovação na análise de risco |

---

### 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         |

## Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 409 | `ASR000032` | 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). |
| 400 | `ASR000054` | Cedente pessoa jurídica deve ter pelo menos 1 parte relacionada. Incluir ao menos uma parte relacionada em `related_parties`. |
| 400 | `ASR000056` | Pessoa física não pode ser participante do Sistema Financeiro Nacional. Para `person_type=natural_person`, enviar `is_in_national_financial_system=false`. |
| 400 | `ASR000057` | Cedente pessoa jurídica deve ter pelo menos 1 representante assinante. Garantir que ao menos uma parte relacionada possua `is_representative=true`. |
| 400 | `ASR000011` | Número de documento de parte relacionada duplicado. Cada `document_number` em `related_parties` deve ser único. |
| 400 | `ASR000041` | Parte relacionada com `is_representative=true` sem `email`. Informe o e-mail do representante. |
| 400 | `ASR000058` | Pessoa estrangeira sem CPF não pode ser assinante. Estrangeiros sem `document_number` (CPF) não podem ter `is_representative=true`. |
| 404 | `ASR000071` | Instituição financeira não encontrada. Validar o `financial_institution_code` (código bancário) informado para a conta. |
| 400 | `ASR000087` | Informação de conta deve conter apenas números. Enviar `account_branch`, `account_number` e `account_digit` apenas com dígitos. |
| 400 | `ASR000081` | Mais de uma conta padrão foi enviada. Apenas uma conta deve ter `default_account=true`. |
| 400 | `ASR000078` | Número de documento de avalista duplicado. Cada avalista em `guarantors` deve ter `document_number` único. |
| 400 | `ASR000079` | Avalista pessoa física não aceita representante. Para `person_type=natural_person`, só é aceito o cônjuge: `related_party_type: spouse`. |
| 400 | `ASR000080` | Documento de representante de avalista duplicado. Cada representante em `guarantor_representatives` deve ter `document_number` único. |
| 400 | `ASR000091` | Avalista pessoa jurídica deve ter pelo menos um representante. Para `person_type=legal_person`, enviar pelo menos um item em `guarantor_representatives`. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

# 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á operar 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 só são aceitos enquanto a análise estiver em `pending_documents`. Pela gestora e pela consultoria, o envio é restrito ao agente dono do cadastro (quem o criou); para outro agente, a API responde `ASR000004`.

## Enviou o documento errado?

Reenvie o documento correto com o mesmo `document_type`, enquanto a análise ainda estiver em `pending_documents`. O documento anterior daquele tipo (`valid` ou `accepted`) passa automaticamente para `canceled` e o novo o substitui. Não existe chamada de cancelamento.

A exceção é `additional_document`: documentos adicionais se acumulam e não são substituídos. Se um documento adicional foi enviado por engano, fale com o time de integração em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) antes de disparar a análise.

Depois do [Envio para Análise](/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise), a análise não aceita mais documentos (`ASR000039`). Para corrigir, gere uma nova análise pela [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro).

---

## Documentos do Cedente

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Escrita |
| Consultoria | `consultant-api` | Cadastrar Cedente |
| Cedente     | `assignor-api`   | Escrita |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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": "JVBERi0xLjQK...",
    "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 | Arquivo 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",
    "status": "valid",
    "observation": "CONTRATO SOCIAL ATUALIZADO",
    "reference_date": null
}
```

:::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

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado (ou, para gestora e consultoria, o cadastro não pertence à sua integração). Verificar se o `assignor_registry_key` está correto. |
| 404 | `ASR000033` | Análise não encontrada para o `analysis_key` informado. Verificar se o `analysis_key` está correto. |
| 400 | `ASR000039` | 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 — ou se a análise tiver sido cancelada por inatividade (`canceled`) — gere uma nova análise via [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). |
| 400 | `ASR000005` | Formato de arquivo inválido. Enviar `document_b64` como string em base64 válida. |
| 400 | `ASR000060` | O arquivo enviado não é um PDF válido. O conteúdo decodificado de `document_b64` deve ser um PDF. |
| 400 | `ASR000059` | Tamanho do arquivo excede o limite. Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). |
| 400 | `ASR000061` | 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-padrao-do-cedenteavalista)). |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

## Documentos das partes relacionadas

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Escrita |
| Consultoria | `consultant-api` | Ler Cedentes |
| Cedente     | `assignor-api`   | Escrita |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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": "JVBERi0xLjQK...",
    "observation":"CNH Válida"
}
```

### Response

STATUS 201

```json title='Response Body'
{
    "document_key": "afe8532a-4b0b-4e63-8d16-5084b2681752",
    "status": "valid",
    "document_type": "cnh",
    "observation": "CNH Válida"
}
```

:::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 — veja [Enviou o documento errado?](#enviou-o-documento-errado).

:::

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado (ou, para gestora e consultoria, o cadastro não pertence à sua integração). Verificar se o `assignor_registry_key` está correto. |
| 404 | `ASR000033` | Análise não encontrada para o `analysis_key` informado. Verificar se o `analysis_key` está correto. |
| 404 | `ASR000035` | 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. |
| 400 | `ASR000039` | O status atual da análise não aceita novos documentos. Documentos só podem ser anexados quando a análise estiver em `pending_documents`; depois disso, gere uma nova análise via [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). |
| 400 | `ASR000005` | Formato de arquivo inválido. Enviar `document_b64` como string em base64 válida. |
| 400 | `ASR000060` | O arquivo enviado não é um PDF válido. O conteúdo decodificado de `document_b64` deve ser um PDF. |
| 400 | `ASR000059` | Tamanho do arquivo excede o limite. Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). |
| 400 | `ASR000062` | 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-padrao-das-partes-relacionadasrepresentantes)). |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

### 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 | Certidã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.

:::caution 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 retorna de forma síncrona 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.           |
| **national_registry_of_foreigners** | Registro Nacional de Estrangeiros. |
| **cin_digital**                 | Carteira de Identidade Nacional (Digital).           |
| **social_contract**          | Contrato/Estatuto Social.   |
| **cnpj_card**          | Cartão CNPJ.   |
| **commercial_board_certificate** | Certidão Simplificada 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 (substituído por um novo envio do mesmo tipo) |
| **accepted** | Aceito, porém não validado |
| **inconclusive** | Validação inconclusiva |

---

# 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 [listagem de configurações de cessão](/documentation/iaas/negociacao_recebiveis/listagem), com parâmetros como `assignment_contract_key`, `asset_type` e `assignor_document_number`, utilizando o contrato formalizado pela matriz como referência.

:::caution 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 webhook de aprovação ou reprovação da análise gerada, que é enviada automaticamente.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Escrita |
| Consultoria | `consultant-api` | Cadastrar Cedente |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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": "55.666.777/0002-62",
    "email": "filial@cedente-exemplo.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](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-telefone)**. |
| `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-endereco)**. |
| `accounts` * | array | Lista de contas de desembolso do cedente.| Ver  **[Definição de Conta](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-conta)**. |

*Campos obrigatórios.

### Response

STATUS 201

```json title='Response Body'
{
  "assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947",
  "status": "pending_registry",
  "name": "Cedente Exemplo LTDA",
  "document_number": "55.666.777/0002-62",
  "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": "969.698.790-03",
        "name": "Roberto Carlos",
        "documents": []
      },
      {
        "analysis_related_party_key": "f2bc3473-1686-4d15-9a06-b51d25e20cb4",
        "document_number": "123.456.789-09",
        "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"
      }
    ]
  }
}
```

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | Identificador do cadastro. | 36 |
| `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](/documentation/iaas/homologacao_cedente/cadastro/envio_de_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](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-analise)**. |

:::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

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | Cedente matriz não encontrado para o `assignor_registry_key` informado. Garantir que `assignor_registry_key` na URL corresponda ao cadastro da matriz. |
| 400 | `ASR000099` | Cedente pessoa física não pode ter filiais. Apenas matrizes pessoa jurídica (`person_type=legal_person`) podem ter filiais. |
| 400 | `ASR000096` | Status da matriz não permite ativação de filial. A matriz deve estar com `status=registered` para criar uma filial. |
| 400 | `ASR000097` | O cadastro referido não é uma matriz. O `assignor_registry_key` na URL deve ser de um cadastro com `organization_level=headquarters`. |
| 400 | `ASR000098` | 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. |
| 409 | `ASR000032` | 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-ja-existente-a-matriz). |
| 404 | `ASR000071` | Instituição financeira não encontrada para a conta da filial. Validar o `financial_institution_code` informado em `accounts`. |
| 400 | `ASR000087` | Informação de conta deve conter apenas números. Enviar `account_branch`, `account_number` e `account_digit` apenas com dígitos. |
| 400 | `ASR000081` | Mais de uma conta padrão foi enviada. Apenas uma conta deve ter `default_account=true`. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## 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.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Escrita |
| Consultoria | `consultant-api` | Cadastrar Cedente |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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": "Cedente Exemplo LTDA",
  "document_number": "55.666.777/0002-62",
  "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": "969.698.790-03",
        "name": "Roberto Carlos",
        "documents": []
      },
      {
        "analysis_related_party_key": "f2bc3473-1686-4d15-9a06-b51d25e20cb4",
        "document_number": "123.456.789-09",
        "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"
      }
    ]
  }
}
```

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | Identificador do cadastro. | 36 |
| `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](/documentation/iaas/homologacao_cedente/cadastro/envio_de_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](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-analise)**. |

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | 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. |
| 400 | `ASR000099` | Cedente pessoa física não pode ter filiais. Apenas matrizes pessoa jurídica podem vincular filiais. |
| 400 | `ASR000096` | Status da matriz não permite vínculo de filial. A matriz deve estar com `status=registered`. |
| 400 | `ASR000097` | O cadastro referido não é uma matriz. O `assignor_registry_key` na URL deve ser de um cadastro com `organization_level=headquarters`. |
| 400 | `ASR000098` | 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. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## 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.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Escrita |
| Consultoria | `consultant-api` | Cadastrar Cedente |
| Cedente     | `assignor-api`   | Escrita |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY
MÉTODO PUT

```json title='Request Body'
{
  "email": "financeiro@cedente-exemplo.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](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-telefone)**. |
| `address`  | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-endereco)**. |

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": "registered",
  "name": "Cedente Exemplo LTDA",
  "document_number": "55.666.777/0002-62",
  "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": "969.698.790-03",
        "name": "Roberto Carlos",
        "documents": []
      },
      {
        "analysis_related_party_key": "7ea3193b-8e53-40b7-94cf-2d3cc62942e0",
        "document_number": "123.456.789-09",
        "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"
      }
    ]
  }
}
```

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | Identificador do cadastro. | 36 |
| `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](/documentation/iaas/homologacao_cedente/cadastro/envio_de_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](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-analise)**. |

:::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 a mesma lógica da matriz: veja [Contas do cedente](/documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas).

:::

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | 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. |
| 400 | `ASR000100` | Campo enviado não pode ser atualizado em uma filial: `name`, `related_parties` e `guarantors` são sempre os da matriz. Para alterá-los, atualize o cadastro da matriz (ver [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro)). |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

# Contas do cedente

URL: /documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas

As contas de desembolso podem ser enviadas já no [cadastro do cedente](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro) (`accounts`) ou adicionadas depois por esta página. O cedente precisa ter ao menos uma conta para que um [contrato de cessão](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato) seja proposto. 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.

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, obrigatoriamente 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.

:::caution 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.

:::

:::info A gestora não mantém contas por API

As rotas de conta não estão disponíveis em `manager-api`. A manutenção das contas do cedente é feita pela consultoria (`consultant-api`) ou pelo próprio cedente (`assignor-api`). Uma gestora que precise incluir ou desativar uma conta deve enviá-la já no cadastro inicial do cedente (`accounts`), pedir à consultoria ou ao cedente, ou falar com o time de integração em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br).

:::

---

## Adição de conta alternativa

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Consultoria | `consultant-api` | Cadastrar Cedente |
| Cedente     | `assignor-api`   | Escrita |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto. |
| 409 | `ASR000072` | 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. |
| 400 | `ASR000087` | Informação de conta deve conter apenas números. Enviar `account_branch`, `account_number`, `account_digit` e `financial_institution_code` apenas com dígitos. |
| 404 | `ASR000071` | Instituição financeira não encontrada. Validar o `financial_institution_code` (código bancário) informado. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

## 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.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Consultoria | `consultant-api` | Cadastrar Cedente |
| Cedente     | `assignor-api`   | Escrita |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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 | Só aceita `true`: torna esta a conta padrão de desembolso. | - |

Envie ao menos um dos dois campos.

### 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 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. Não é possível desativar uma conta padrão, ou definir como padrão uma conta inativa.

:::

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto. |
| 404 | `ASR000073` | Conta não encontrada para o `account_key` informado. Verificar se o `account_key` pertence ao cedente. |
| 400 | `ASR000074` | 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. |
| 400 | `ASR000075` | Nenhuma informação foi enviada para atualização. Informar `status` ou `default_account` no corpo da requisição. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

## Enumeradores

### Account Status

| Enumerador                 | Descrição       |
| -------------------------- | ----------------- |
| **active** | Conta ativa e disponível como opção de desembolso. |
| **inactive** | Conta inativa e indisponível para desembolso. |

---

# Webhooks

URL: /documentation/iaas/homologacao_cedente/cadastro/webhooks_analise

---

Os webhooks do cadastro são enviados a todos os agentes com acesso ao cadastro do cedente (gestora, consultoria e cedente) que tenham webhook configurado. Cadastros originados por carga da Fromtis (`fromtis_load`) não disparam webhook. Assinatura, reenvio e configuração: veja [Autenticação de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks).

## Webhooks de Análise

`webhook_type`: `assignor_registry.analysis_status_change`

### Derivaçã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:23Z"
}
```

### 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:23Z"
}
```

### Aprovado

STATUS approved

```json title='Webhook Body'
{
    "data":{
        "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
        "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
        "analysis_status": "approved",
        "reproval_reason": null,
        "reproval_details": null
    },
    "webhook_type":"assignor_registry.analysis_status_change",
    "webhook_datetime":"2025-01-22T20:30:23Z"
}
```

### Reprovado

STATUS reproved

```json title='Webhook Body'
{
    "data":{
        "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
        "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
        "analysis_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:23Z"
}
```

### Cancelado

STATUS canceled

Disparado quando uma análise é cancelada. O caso mais comum é o **cancelamento automático por inatividade**: uma análise que fica **1 mês sem movimentação** — tipicamente parada em `pending_documents`, sem documentos anexados ou sem o disparo da análise — é cancelada pela QI Tech.

O status é **terminal**. Para retomar o cadastro, gere uma nova análise por meio da [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro).

```json title='Webhook Body'
{
    "data":{
        "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
        "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
        "analysis_status": "canceled",
        "reproval_reason": null,
        "reproval_details": null
    },
    "webhook_type":"assignor_registry.analysis_status_change",
    "webhook_datetime":"2025-01-22T20:30:23Z"
}
```

## Webhooks de Apontamento

`webhook_type`: `assignor_registry.annotation_status_change`

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

`webhook_type`: `assignor_registry.assignor_registry_status_change`. Enviado uma única vez, quando o cedente é efetivado (`registered`).

### 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:23Z"
}
```

---

# Consulta de análise

URL: /documentation/iaas/homologacao_cedente/consulta/consulta_de_analise

---

O campo `status` da análise segue os **[Enumeradores de status de análise](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#analysis-status)**.

:::info Status `canceled`

Uma análise que fica **1 mês sem movimentação** — tipicamente parada em `pending_documents`, sem documentos anexados ou sem o disparo da análise — é **cancelada automaticamente** e passa a `canceled`. O status é terminal: a análise não aceita mais documentos nem disparo. Para retomar o cadastro, gere uma nova análise por meio da [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro).

:::

## Consulta de Análise Por Chave

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura |
| Consultoria | `consultant-api` | Ler Cedentes |
| Cedente     | `assignor-api`   | Leitura |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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": "969.698.790-03",
      "name": "Roberto Carlos",
      "documents": [
        {
          "document_key": "72bad379-dbe6-40ca-97f2-1181257889ba",
          "document_type": "cnh",
          "status": "valid"
        }
      ]
    },
    {
      "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
      "document_number": "123.456.789-09",
      "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": "Cedente Exemplo LTDA",
    "document_number": "33.344.455/0001-83",
    "person_type": "legal_person",
    "email": "financeiro@cedente-exemplo.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": "123.456.789-09",
        "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": "969.698.790-03",
        "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

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto (ou, para gestora e consultoria, se o cadastro pertence à sua integração). |
| 404 | `ASR000033` | Análise não encontrada para o `analysis_key` informado. Verificar se o `analysis_key` está correto. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## Consulta Paginada de Análises

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura |
| Consultoria | `consultant-api` | Ler Cedentes |
| Cedente     | `assignor-api`   | Leitura |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analyses
MÉTODO GET

### Query params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `limit` | integer | Itens por página. Padrão `10`, máximo `50`. Acima do máximo, a API devolve 400 | - |
| `page` | integer | Página, começando em `0`. Use `is_last_page` da resposta para saber quando parar | - |

### 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": "969.698.790-03",
            "name": "Roberto Carlos",
            "documents": [
              {
                "document_key": "72bad379-dbe6-40ca-97f2-1181257889ba",
                "document_type": "cnh",
                "status": "valid"
              }
            ]
          },
          {
            "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
            "document_number": "123.456.789-09",
            "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

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto (ou, para gestora e consultoria, se o cadastro pertence à sua integração). |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

# Consulta de assinantes

URL: /documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes

Consulta **paginada** dos conjuntos de assinantes (`signer_group_sets`) vinculados ao cedente e às suas partes relacionadas. Retorna tanto os conjuntos padrão (`main`), gerados pela análise da Administradora, quanto os conjuntos customizados (`custom`) definidos pelo cliente.

:::info Informação

Cada conjunto está vinculado a um proprietário (`owner`), que pode ser o **cedente** (`assignor_registry`), um **avalista** (`guarantor`) ou o **cônjuge** de um avalista pessoa física (`spouse`), e a um tipo de produto.

Para criar conjuntos customizados, consulte [Definição de Assinantes](/documentation/iaas/homologacao_cedente/cadastro/definicao_de_assinantes).

:::

---

## Consulta Paginada de Conjuntos de Assinantes

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura |
| Consultoria | `consultant-api` | Ler Cedentes |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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, avalista ou cônjuge). Ver **[Owner Type](#owner-type)**. |
| `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)**. |
| `status` | string | Filtra pelo status do conjunto. Ver **[Signer Group Set Status](#signer-group-set-status)**. |

:::tip Dica

Para listar apenas os conjuntos que estão efetivamente sendo utilizados nas assinaturas, filtre por `status=valid`. Conjuntos em `in_analysis` ainda dependem da aprovação do cadastro e não são enviados para assinatura.

:::

### 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": "valid",
      "signer_groups": [
        {
          "minimum_required_signers": 2,
          "signers": [
            {
              "document_number": "123.456.789-09",
              "is_required_signer": true
            },
            {
              "document_number": "969.698.790-03",
              "is_required_signer": false
            }
          ]
        }
      ]
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

#### Campos de Paginação

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `data` | array | Lista de conjuntos de assinantes da página atual. Ver **[Definição de Conjunto de Assinantes](#definicao-de-conjunto-de-assinantes-signer-group-set)**. |
| `limit` | integer | Quantidade de itens por página utilizada na consulta. |
| `page` | integer | Página retornada, iniciando em 0. |
| `is_last_page` | boolean | Indica se esta é a última página do resultado. |

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 400 | `ASR000121` | `owner_document_number` enviado sem `owner_type`. Ao filtrar por `owner_document_number`, sempre informar também `owner_type`. |
| 400 | `ASR000120` | 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)). |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## 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, conforme o `owner_type`. Ver **[Owner Type](#owner-type)**. | 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](#definicao-de-grupo-de-assinantes-signer-group)**. |

---

### 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. | Ver **[Definição de Assinante](#definicao-de-assinante-signer)**. |

A consulta não devolve `expiration`, e grupos já expirados não aparecem.

---

### 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. | - |

---

## Enumeradores

### Owner Type

| Enumerador | Descrição |
|------------|-----------|
| **assignor_registry** | Conjunto do cedente. `owner_key` = `assignor_registry_key`. |
| **guarantor** | Conjunto de um avalista. `owner_key` = chave do avalista (`guarantor_key`). |
| **spouse** | Conjunto do cônjuge de um avalista pessoa física. `owner_key` = chave do cônjuge (`representative_key` em `guarantor_representatives`). |

---

### 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. Não é utilizado nas assinaturas. |
| **valid** | Conjunto vigente e utilizado nas assinaturas. |
| **invalid** | Conjunto substituído por um envio mais recente, ou descartado. Não é utilizado nas assinaturas. |

---

# Consulta de cedente

URL: /documentation/iaas/homologacao_cedente/consulta/consulta_de_cedente

---

## Consulta de Cedente Por Chave

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura |
| Consultoria | `consultant-api` | Ler Cedentes |
| Cedente     | `assignor-api`   | Leitura |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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": "registered",
  "name": "Cedente Exemplo LTDA",
  "document_number": "33.344.455/0001-83",
  "person_type": "legal_person",
  "email": "financeiro@cedente-exemplo.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": "123.456.789-09",
      "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": "969.698.790-03",
      "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"
      }
    }
  ],
  "accounts": [
    {
      "account_key": "3c53a94a-2b81-4837-b7eb-8e025e69d81c",
      "account_branch": "0001",
      "account_number": "7912584",
      "account_digit": "1",
      "account_type": "checking_account",
      "status": "active",
      "financial_institution_code": "329",
      "financial_institution_ispb": "32402502",
      "default_account": true,
      "owner": { "document_number": "33.344.455/0001-83" },
      "description": null
    }
  ],
  "guarantors": [],
  "last_analysis": {
    "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691",
    "analysis_number": 1,
    "status": "pending_documents",
    "analysis_datetime": "2026-01-15T14:32:10Z",
    "analysis_related_parties": [
      {
        "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59",
        "name": "Roberto Carlos",
        "document_number": "969.698.790-03",
        "analysis_roles": [{ "related_party_type": "director" }],
        "documents": []
      },
      {
        "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
        "name": "Natália Nascimento",
        "document_number": "123.456.789-09",
        "analysis_roles": [{ "related_party_type": "attorney" }],
        "documents": []
      }
    ],
    "documents": [],
    "annotations": [],
    "last_updated": "2026-01-15T14:32:10Z",
    "analysis_origin_type": "assignor_registry",
    "reproval_reason": null,
    "reproval_details": null
  }
}
```

### 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` | string | Status do cadastro. | Ver [Assignor Registry Status](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#assignor-registry-status) |
| `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](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-telefone)**. |
| `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-endereco)**. |
| `related_parties` * | array | Lista de partes relacionadas da empresa.| Ver  **[Definição de Parte Relacionada](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-parte-relacionada)**. |
| `accounts` * | array | Lista de contas de desembolso do cedente.| Ver  **[Definição de Conta](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-conta)**. |
| `guarantors` * | array | Lista de avalistas do cedente.| Ver  **[Definição de Avalista](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-avalista)**. |
| `last_analysis` | object | Última análise do cadastro. | Ver **[Definição de Análise](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-analise)**. |
| `signer_groups` | array | Grupos de assinantes vigentes do cedente. | Ver **[Definição de Grupo de Assinantes](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes#definicao-de-grupo-de-assinantes-signer-group)**. |
| `organization_level` | string | `headquarters` (matriz), `branch` (filial) ou `not_applicable`. Só vem quando definido. | - |
| `headquarters_bond` | boolean | `true` quando o cadastro é uma filial vinculada a uma matriz. | - |

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ASR000004` | Cedente não encontrado para o `assignor_registry_key` informado. Verificar se o `assignor_registry_key` está correto (ou, para gestora e consultoria, se o cadastro pertence à sua integração). |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## Consulta Paginada de Cedentes

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura |
| Consultoria | `consultant-api` | Ler Cedentes |
| Cedente     | `assignor-api`   | Leitura |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### Request

ENDPOINT /assignor_registry/assignor_registries
MÉTODO GET

### Query 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 | Itens por página. Padrão `25` (`10` na `assignor-api`), máximo `50`. Acima do máximo, a API devolve 400 | - |
| `page` | integer | Página, começando em `0`. Use `is_last_page` da resposta para saber quando parar | - |

### Response

STATUS 200

```json title='Response Body'
{
  "data": [
    {
      "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907",
      "status": "registered",
      "name": "Cedente Exemplo LTDA",
      "document_number": "33.344.455/0001-83",
      "person_type": "legal_person",
      "email": "financeiro@cedente-exemplo.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": "123.456.789-09",
          "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": "969.698.790-03",
          "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"
          }
        }
      ],
      "accounts": [
        {
          "account_key": "3c53a94a-2b81-4837-b7eb-8e025e69d81c",
          "account_branch": "0001",
          "account_number": "7912584",
          "account_digit": "1",
          "account_type": "checking_account",
          "status": "active",
          "financial_institution_code": "329",
          "financial_institution_ispb": "32402502",
          "default_account": true,
          "owner": { "document_number": "33.344.455/0001-83" },
          "description": null
        }
      ],
      "guarantors": [],
      "last_analysis": {
        "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691",
        "analysis_number": 1,
        "status": "pending_documents",
        "analysis_datetime": "2026-01-15T14:32:10Z",
        "analysis_related_parties": [
          {
            "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59",
            "name": "Roberto Carlos",
            "document_number": "969.698.790-03",
            "analysis_roles": [{ "related_party_type": "director" }],
            "documents": []
          },
          {
            "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
            "name": "Natália Nascimento",
            "document_number": "123.456.789-09",
            "analysis_roles": [{ "related_party_type": "attorney" }],
            "documents": []
          }
        ],
        "documents": [],
        "annotations": [],
        "last_updated": "2026-01-15T14:32:10Z",
        "analysis_origin_type": "assignor_registry",
        "reproval_reason": null,
        "reproval_details": null
      }
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 400 | — | `limit` acima de `50` ou `page` negativo. |
| 404 | `ASR000026` | O agente autenticado não está habilitado no cadastro de cedentes. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## 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 (`owner_key`, `owner_type`, `owner_document_number`, `product_type` e `status`), paginação, formato de resposta e enumeradores —, consulte [Consulta de Assinantes](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes).

---

---

# Consultar documentos

URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/consulta_de_documentos

---

Retorna um documento anexo do contrato de cessão (o contrato ou a declaração da gestora) com a URL para download da versão mais recente.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura |
| Consultoria | `consultant-api` | Ler contratos de cessão |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

## 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 title='Response Body'
{
  "document_key": "8f1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "document_type": "assignment_contract",
  "status": "signed",
  "generation_method": "internal",
  "signature_validation_method": "internal",
  "document_template_key": "2a7c9e1b-3d5f-4b8a-9c0e-6f1a2b3c4d5e",
  "required_parties": ["manager", "assignor"],
  "upload_document_analyses": [],
  "download_url": "url para download do documento"
}
```

:::info Observação

O campo `download_url` traz a URL assinada para download do documento em sua versão mais atual: se o documento já estiver assinado, é a versão assinada. A URL expira e não deve ser guardada para consulta posterior.

:::

### 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 **[Attached Document Status](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato#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. | -- |
| `generation_method` | string | Como o documento é gerado: `internal` (pela plataforma) ou `external` (enviado por upload). | -- |
| `signature_validation_method` | string | Como a assinatura é validada (por exemplo, `internal` ou `external`). | -- |
| `upload_document_analyses` | array | Análises dos documentos enviados por upload. Vazio quando não há upload. | -- |
| `download_url` | string | URL de download do PDF. | -- |

## Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ACT000023` | `assignment_contract_key` não encontrado. |
| 404 | `ACT000087` | `document_key` não encontrado ou não pertence ao contrato indicado. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

# 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 seja enviado para assinatura. Só a gestora aprova ou recusa: a consultoria acessa a mesma rota, mas apenas para [cancelar](#cancelamento-de-contrato).

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura e escrita |
| Consultoria | `consultant-api` | Criar contratos de cessão |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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: `approved` ou `denied`. | -- |
| `denial_reason` | string | Descritivo com o motivo da recusa. Volta no webhook do status `denied`. | Até 500 |

*Campos obrigatórios

### Response

STATUS 202

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ACT000023` | `assignment_contract_key` não encontrado. |
| 400 | `ACT000025` | Aprovação ou recusa enviada por quem não é a gestora. |
| 400 | `ACT000077` | O status atual não permite a decisão. `approved` exige `pending_manager_approval`; `denied` aceita `pending_manager_approval` ou `pending_document`. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## 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. Todos os contratos do lote precisam estar em `pending_signature_submission`.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Escrita |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### Request

ENDPOINT /assignment_contract/signature_batch
MÉTODO POST

```json title='Request Body'
{
    "assignment_contract_keys": [
        "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "41d6ff41-1dac-4df7-9e50-d15210ec57f3"
    ]
}
```

#### 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

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ACT000023` | Uma das chaves de `assignment_contract_keys` não foi encontrada. |
| 400 | `ACT000088` | Um dos contratos não está em `pending_signature_submission`. |
| 404 | `ACT000089` | Os contratos do lote não têm as mesmas partes relacionadas (gestor, cedente, avalistas). Agrupe só contratos com as mesmas partes. |
| 400 | `ACT000165` | Todos os contratos do lote são de templates que proíbem assinatura isolada. Inclua ao menos um contrato que a permita. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## 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.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura e escrita |
| Consultoria | `consultant-api` | Criar contratos de cessão |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ACT000023` | `assignment_contract_key` não encontrado. |
| 400 | `ACT000077` | O contrato está `signed` ou `denied` e não pode ser cancelado. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

# 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 DTVM, 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 e os **produtos** do contrato.

Os produtos identificam, por exemplo, uma configuração de cessão de um tipo de ativo, de recompra, e assim por diante. Eles vêm do template: não é preciso enviá-los no pedido. 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.

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. As contas de desembolso são definidas no cadastro do cedente; quando o template exige uma conta específica para o contrato, ela é indicada em `disbursement_account_key`.

Todo o fluxo de assinatura do contrato é realizado pela nossa certificadora, CertifiQI. O acompanhamento das assinaturas e a ativação dos produtos acontecem de forma automática — veja [Ativação dos produtos](#ativacao-dos-produtos).

:::info Disponível em

| Perfil      | Host             | Permissão exigida                                                       |
| ----------- | ---------------- | ----------------------------------------------------------------------- |
| Gestora     | `manager-api`    | Escrita                                                                 |
| Consultoria | `consultant-api` | Criar contratos de cessão |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

## Request

ENDPOINT /assignment_contract/assignment_contract
MÉTODO POST

```json title='Request Body'
{
    "fund_class_key": "813ce253-bae5-4448-8d15-04c48d9991b7",
    "assignor_document_number": "55.666.777/0001-81",
    "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": "969.698.790-03"
        }
    ]
}
```

### 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 DTVM. | Chave uuid |
| `assignment_contract_template_key` * | string | Chave única de identificação do Template de Contrato. Também fornecida pelo time da QI DTVM. | Chave uuid |
| `assignor_document_number` ** | string | Número do documento do cedente. | CPF ou CNPJ, até 18 |
| `assignor_registry_key` ** | string | Chave do cadastro do cedente, alternativa ao `assignor_document_number`. | Chave uuid |
| `credit_limit` | number | Valor do limite de crédito do contrato. | 1 a 1.000.000.000 |
| `disbursement_account_key` | string | Conta de desembolso do contrato. Obrigatória quando a política de conta de desembolso do template é `locked_on_assignment_contract`, e recusada nas demais. Deve ser uma conta `active` do cedente. | Chave uuid |
| `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato. | Até 50 |
| `case_number` | string | Número de caso. Único por fundo; se omitido, é gerado automaticamente. | Até 17 |
| `observation` | string | Observação. Campo livre para quaisquer anotações. | Até 1000 |
| `delay` | object | Multa (`fine`) e juros (`interest`) por atraso. Só é aceito quando o template permite customizar esses valores. | -- |
| `guarantors` | array | Avalistas da operação. | Ver **[Definição de Avalista](#definicao-de-avalista)**. |

\*Campos obrigatórios

\*\*Envie exatamente um dos dois: `assignor_document_number` ou `assignor_registry_key`.

:::caution 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

O corpo da resposta é o contrato completo, no mesmo formato da [Consulta de Contrato](/documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato). Trecho:

```json title='Response Body'
{
    "assignment_contract_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_document",
    "external_id": "Contrato 550",
    "case_number": "17375775230001234",
    "disbursement_account_key": null,
    "products": [
        {
            "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
            "assignment_configuration_key": null,
            "fund_class_configuration_key": "0b6f3a8e-2f7d-4c11-9a52-6a1d1c0e9f10",
            "product_type": "assignment_term",
            "asset_type": "ccb",
            "has_coobligation": true,
            "status": "pending_contract_signature"
        }
    ]
}
```

:::info

É de extrema importância salvar a `assignment_contract_key`: ela identifica o contrato nas consultas e nos webhooks, e as configurações de cessão geradas pelo contrato (inclusive as originadas pelo fluxo de [Filiais](/documentation/iaas/homologacao_cedente/cadastro/filiais)) ficam vinculadas a ele. Para recuperar os produtos e as configurações geradas, use a [Consulta de Contrato](/documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato).

:::

## Ativação dos produtos

Não existe chamada de ativação: os produtos são ativados automaticamente quando o contrato é assinado.

1. Todos os documentos assinados → o contrato passa para `signed` e é enviado o webhook `assignment_contract.assignment_contract_status_change` com `assignment_contract_new_status: contract_signed`.
2. Cada produto passa de `pending_contract_signature` para `pending_create_assignment_configuration` enquanto a esteira de cessão é configurada. Isso pode levar alguns minutos.
3. Configurada a esteira, o produto passa para `active` e é enviado o webhook `assignment_contract.product_status_change`, que traz a `assignment_configuration_key` — a chave usada para ceder ativos entre o fundo e o cedente.

Os payloads estão em [Webhooks do Contrato](/documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato). Se preferir não depender do webhook, consulte o contrato e leia `products[].status` e `products[].assignment_configuration_key`.

### Definição de Avalista

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` | string | Nome do avalista. | Até 255 |
| `document_number` | string | CPF ou CNPJ, formatado. | 14 a 18 |

:::caution Aviso

Como já indicado, o avalista deve ser previamente cadastrado, junto com o cedente em específico.

:::

## Enumeradores

### Assignment Contract Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **created**  | Contrato criado (estado inicial e transitório) |
| **pending_document**  | Pendente geração dos documentos |
| **pending_manager_approval**           | Pendente aprovação do gestor |
| **pending_assignor_registry_release**           | Pendente liberação do cadastro de cedente vinculado (Em fase de cadastro ou atualização) |
| **pending_signature_submission**           | Pendente envio manual para assinatura |
| **sending_to_signature**   | Em envio para assinatura |
| **pending_signature** | Disponível para assinatura das partes |
| **waiting_escrow_data** | Aguardando dados da conta escrow (só em templates com conta escrow) |
| **pending_escrow_activation** | Aguardando ativação da conta escrow (só em templates com conta escrow) |
| **signed** | Assinado |
| **suspended** | Suspenso; os produtos ficam `inactive` até a reativação |
| **denied**           | Reprovado na análise do gestor |
| **canceled**           | Cancelado |

### Product Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **pending_contract_signature** | Aguardando a assinatura do contrato |
| **pending_create_assignment_configuration** | Contrato assinado; esteira de cessão em configuração |
| **active** | Ativo; `assignment_configuration_key` disponível |
| **inactive** | Inativo (contrato cancelado ou suspenso) |

### Attached Document Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **pending_generate**  | Pendente geração do documento |
| **approved** | Documento gerado |
| **pending_upload** | Aguardando o upload do documento |
| **uploaded** | Documento enviado |
| **pending_validation** | Documento enviado, em validação |
| **pending_signed_upload** | Aguardando o upload do documento assinado |
| **signed**           | Documento assinado |
| **reproved** | Documento invalidado (contrato cancelado ou recusado) |

## Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ACT000001` | `fund_class_key` não encontrado ou não pertence à gestora autenticada. |
| 404 | `ACT000016` | `assignment_contract_template_key` não encontrado para o fundo. |
| 400 | `ACT000126` | O template está inativo. Use um template ativo. |
| 404 | `ACT000065` | O cedente do `assignor_document_number` não está cadastrado para o agente proponente. |
| 404 | `ACT000134` | `assignor_registry_key` não encontrado, ou o agente não é dono do cadastro. |
| 400 | `ACT000142` | O cedente tem só cadastro de análise básica e não pode receber contrato. |
| 400 | `ACT000096` | O cedente não tem conta cadastrada. Cadastre uma em [Manutenção de Contas](/documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas). |
| 400 | `ACT000155` | O template exige `disbursement_account_key` e ele não foi enviado. |
| 400 | `ACT000156` | `disbursement_account_key` enviado, mas o template não aceita conta por contrato. |
| 400 | `ACT000154` | `disbursement_account_key` não é uma conta `active` do cedente. |
| 400 | `ACT000081` | Um item de `guarantors` não está cadastrado como avalista do cedente. |
| 400 | `ACT000102` | `delay` enviado, mas o template não permite customizar multa e juros. |
| 409 | `ACT000095` | `case_number` já usado neste fundo. Use outro ou omita o campo. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

# Recuperação do contrato

URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato

---

## Recuperação do Contrato

Retorna um contrato de cessão, com seus documentos e produtos. É a forma de consultar o status de cada produto e a `assignment_configuration_key` gerada após a assinatura.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura |
| Consultoria | `consultant-api` | Ler contratos de cessão |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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": "22.233.344/0001-83",
        "manager": {
          "manager_key": "UUID",
          "document_number": "33.344.455/0001-83",
          "manager_name": "SAMPLE MANAGER NAME"
        }
      },
      "assignor": {
        "assignor_key": "UUID",
        "document_number": "55.666.777/0001-81",
        "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": 1000000.0,
      "external_id": "ID EXTERNO",
      "case_number": "NÚMERO DO PROCESSO",
      "denial_reason": null,
      "observation": "OBSERVAÇÃO",
      "disbursement_account_key": null,
      "creation_datetime": "YYYY-MM-DDTHH:MM:SSZ",
      "products": [
        {
          "product_key": "UUID",
          "assignment_configuration_key": null,
          "fund_class_configuration_key": "UUID",
          "product_type": "assignment_term",
          "asset_type": "ccb",
          "status": "pending_contract_signature",
          "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 Documento Anexo](#definicao-de-documento-anexo)**. |
| `products` * | array | Lista de produtos sob o contrato. | Ver **[Definição de Produto](#definicao-de-produto)**. |
| `proposal_agent` * | string | Tipo do agente proponente do contrato. | -- |
| `status` * | string | Status do contrato. | Ver **[Enumeradores de status do contrato de cessão](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato#assignment-contract-status)**. |
| `credit_limit` | number | Limite de crédito enviado. | -- |
| `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato | Até 50 |
| `case_number` | string | Número de caso. Único por fundo | -- |
| `denial_reason` | string | Detalhes da recusa do gestor. | Até 500 |
| `observation` | string | Observações enviadas. | Até 1000 |
| `disbursement_account_key` | string | Conta de desembolso fixada no contrato, quando o template exige uma. | 36 |
| `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](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato#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. Necessária na esteira de compra de ativos. `null` até o produto ficar `active`. | 36 |
| `fund_class_configuration_key` * | string | Configuração do fundo que originou o produto. | 36 |
| `product_type` * | string | Tipo do produto (por exemplo, `assignment_term`, `assignment_repurchase`). | -- |
| `asset_type` * | string | Tipo do ativo. | -- |
| `has_coobligation` * | boolean | Se há coobrigação do cedente. | -- |
| `status` * | string | Status do produto. Ver **[Product Status](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato#product-status)**. | -- |

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 404 | `ACT000023` | `assignment_contract_key` não encontrado. |
| 403 | `ACT000024` | O contrato existe, mas o agente autenticado não é parte dele. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

## Listagem de Contratos de Cessão

Lista os contratos de cessão visíveis para o agente autenticado, com paginação.

:::info Disponível em

| Perfil      | Host             | Permissão exigida |
| ----------- | ---------------- | ----------------- |
| Gestora     | `manager-api`    | Leitura |
| Consultoria | `consultant-api` | Ler contratos de cessão |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

### 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 do contrato. Aceita vários, separados por vírgula                  |
| `proposal_agent_type`       | Quem propôs o contrato: `manager` ou `consultant`                         |
| `case_number`               | Número do caso                                                            |
| `start_date`                | Data de início (`YYYY-MM-DD`)                                             |
| `end_date`                  | Data de fim (`YYYY-MM-DD`)                                                |
| `page`                      | Página, começando em `0`. Padrão `0`                                      |
| `limit`                     | Itens por página. Padrão `20`, máximo `100`                               |

Use `is_last_page` da resposta para saber quando parar de paginar.

### Response

STATUS 200

```json title='Response Body'
{
  "data": [
    {
      "assignment_contract_key": "UUID",
      "fund_class": {
        "fund_class_key": "UUID",
        "name": "SAMPLE FUND NAME",
        "document_number": "22.233.344/0001-83",
        "manager": {
          "manager_key": "UUID",
          "document_number": "33.344.455/0001-83",
          "manager_name": "SAMPLE MANAGER NAME"
        }
      },
      "assignor": {
        "assignor_key": "UUID",
        "document_number": "55.666.777/0001-81",
        "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": 1000000.0,
      "external_id": "ID EXTERNO",
      "case_number": "NÚMERO DO PROCESSO",
      "denial_reason": null,
      "observation": "OBSERVAÇÃO",
      "disbursement_account_key": null,
      "creation_datetime": "YYYY-MM-DDTHH:MM:SSZ",
      "products": [
        {
          "product_key": "UUID",
          "assignment_configuration_key": null,
          "fund_class_configuration_key": "UUID",
          "product_type": "assignment_term",
          "asset_type": "ccb",
          "status": "pending_contract_signature",
          "has_coobligation": true
        }
      ],
      "signature_batch_key": "UUID"
    }
  ],
  "limit": 20,
  "page": 0,
  "is_last_page": true
}
```

### Erros

| Status | Código | Quando acontece |
|--------|--------|-----------------|
| 400 | — | `limit` acima de `100` ou `page` negativo. |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

## Enumeradores

Os status do contrato, dos produtos e dos documentos estão em [Criação do Contrato › Enumeradores](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato#enumeradores).

---

# Webhooks do contrato

URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato

---

O contrato de cessão envia dois tipos de webhook: um a cada mudança de status do contrato e um quando um produto do contrato é ativado. Os dois são enviados para a gestora, para o cedente e, se houver, para a consultoria do contrato — para cada um que tenha webhook configurado. Assinatura, reenvio e configuração: veja [Autenticação de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks).

## Mudança de status do contrato

`webhook_type`: `assignment_contract.assignment_contract_status_change`

```json title='Webhook Body'
{
    "data": {
        "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "status": "denied",
        "external_id": "Contrato número 550",
        "denial_reason": "Documentação do cedente insuficiente"
    },
    "webhook_type": "assignment_contract.assignment_contract_status_change",
    "webhook_datetime": "2025-01-22T20:30:23Z"
}
```

| Campo | Descrição |
|-------|-----------|
| `data.assignment_contract_key` | Chave do contrato. |
| `data.status` | Novo status do contrato. Ver [Enumeradores](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato#assignment-contract-status). |
| `data.external_id` | `external_id` enviado no pedido do contrato, ou `null`. |
| `data.denial_reason` | Motivo da recusa informado pela gestora. `null` fora do status `denied`. |
| `data.assignment_contract_new_status` | Só presente quando `status` é `signed`, com o valor `contract_signed`. |

Exemplo do contrato assinado:

```json title='Webhook Body'
{
    "data": {
        "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "status": "signed",
        "external_id": "Contrato número 550",
        "denial_reason": null,
        "assignment_contract_new_status": "contract_signed"
    },
    "webhook_type": "assignment_contract.assignment_contract_status_change",
    "webhook_datetime": "2025-01-22T20:30:23Z"
}
```

Status que disparam o webhook:

| Status | Quando |
|--------|--------|
| `pending_manager_approval` | Contrato proposto pela consultoria aguarda a decisão da gestora. |
| `pending_assignor_registry_release` | O cadastro do cedente ainda está em análise. |
| `pending_signature_submission` | O template exige envio manual para assinatura. |
| `sending_to_signature` | O contrato está sendo enviado à CertifiQI. |
| `pending_signature` | Disponível para assinatura das partes. |
| `waiting_escrow_data` / `pending_escrow_activation` | Etapas de conta escrow (só em templates com conta escrow). |
| `signed` | Todos os documentos foram assinados. Os produtos começam a ser ativados. |
| `suspended` | Contrato suspenso; os produtos ficam `inactive`. Volta a `signed` na reativação. |
| `denied` | A gestora recusou o contrato. |
| `canceled` | O contrato foi cancelado. |

## Produto ativado

`webhook_type`: `assignment_contract.product_status_change`

Enviado quando a esteira de cessão de um produto termina de ser configurada, depois da assinatura do contrato. É aqui que chega a `assignment_configuration_key`, usada para ceder ativos entre o fundo e o cedente. Contratos com mais de um produto geram um webhook por produto.

```json title='Webhook Body'
{
    "data": {
        "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "assignment_configuration_key": "372f0449-4043-4523-9f0f-dff70c65b9c9",
        "status": "active",
        "product_new_status": "active"
    },
    "webhook_type": "assignment_contract.product_status_change",
    "webhook_datetime": "2025-01-22T20:30:23Z"
}
```

| Campo | Descrição |
|-------|-----------|
| `data.product_key` | Chave do produto. Para saber a qual contrato ele pertence, consulte o contrato em [Consulta de Contrato](/documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato). |
| `data.assignment_configuration_key` | Chave da configuração de cessão criada para o produto. |
| `data.status` / `data.product_new_status` | Sempre `active` neste webhook. |

---

# 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 seções, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que sejam feitas as devidas liberações, tanto em sandbox quanto em 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 ANBIMA.

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.

:::caution Análises paradas por 1 mês são canceladas automaticamente
Uma Análise que fica **1 mês sem movimentação** é cancelada automaticamente, passando para o status `canceled`. Na prática, o caso mais comum é a análise que permanece em `pending_documents` — aquelas em que a documentação nunca foi anexada, ou em que o [Disparo da Análise](/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise) nunca foi comandado.

O cancelamento é **terminal**: a análise cancelada não volta atrás e não aceita novos documentos nem disparo. Para retomar o cadastro, gere uma nova análise por meio da [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro).

A mudança dispara o webhook `assignor_registry.analysis_status_change` com `analysis_status: canceled` — veja [Webhooks de Análise](/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise).
:::

## 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](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato), a partir de um template, que irá disparar internamente a criação do contrato e envio para assinatura. Os produtos do contrato (por exemplo, cessão de um tipo de ativo ou recompra) são definidos pelo template. Uma vez com o contrato assinado, cada produto é ativado automaticamente — não há chamada de ativação. Ao final, enviamos o webhook `assignment_contract.product_status_change` com a chave da Configuração de Cessão gerada (`assignment_configuration_key`), identificador que será utilizado posteriormente no processo de compra e venda de ativos. Veja [Webhooks do Contrato](/documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato).