---
title: 2.2. Adicionar Títulos
url: https://docs.vehub.com.br/API/Integra%C3%A7%C3%A3o%20FIDC/2.%20Cess%C3%A3o%20de%20Direitos%20Credit%C3%B3rios/2.2.%20Adicionar%20T%C3%ADtulos/
---
| Método | URL |
|--------|-----|
| ![POST](https://img.shields.io/badge/POST-green) | `https://BASE_URL/public/v1/recebiveis/lotes/{idLote}/titulos` |

Adiciona um ou mais títulos a um lote de cessão existente.

## Path Params

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `idLote` | Número | Identificador do lote. |

```` json title="Request Body"
{
  "titulos": [
    {
      "numeroControleParticipante": "0001",
      "numeroDocumento": "12345",
      "nossoNumero": "00012345",
      "codigoOriginador": "ORIGINADOR-123",
      "dataEmissao": "2024-11-28",
      "dataVencimento": "2024-12-28",
      "valorNominal": 1000.5,
      "valorAquisicao": 900.78,
      "bancoCobranca": 123,
      "agenciaDepositaria": 4567,
      "especie": "DM",
      "jurosMoraDiaAtraso": 0.5,
      "valorAbatimento": 20,
      "valorDesconto": 15.5,
      "tags": ["CC01", "RATING_A"],
      "sacado": {
        "tipoPessoa": 2,
        "cpfCnpj": "12345678000199",
        "nome": "Sacado I",
        "cep": "12345678",
        "endereco": "Rua dos Sacados, 1000",
        "cidade": "Blumenau",
        "uf": "SC",
        "email": "financeiro@sacado.com.br",
        "telefone": "47999990000",
        "numero": 1000,
        "bairro": "Centro",
        "complemento": "Sala 1"
      },
      "lastro": {
        "numeroNotaFiscal": 123456789,
        "numeroSerieNotaFiscal": 1,
        "chaveNfe": "12345678901234567890123456789012345678901234",
        "chaveAcessoNfe": "",
        "inscricaoMunicipal": "",
        "codigoMunicipioIBGE": "4202404",
        "dataEmissao": "2024-11-28",
        "valorTotal": 1000.5,
        "tipoLastroPerformado": "BP",
        "quantidadeParcelas": 1,
        "chave": "CONTRATO-4231"
      }
    }
  ]
}
````

```` json title="Response Body — 200 OK"
{
  "status": "sucesso",
  "mensagem": "1 título(s) inserido(s) com sucesso.",
  "titulos": null
}
````

# Modelo de dados

## Requisição

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `titulos` | Lista de [Título](#titulo) | Lista de títulos a serem adicionados ao lote. |

### Título

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `numeroControleParticipante` | Texto | Número de controle do participante. |
| `numeroDocumento` | Texto | Número do documento. |
| `nossoNumero` | Texto | Nosso número do boleto. Campo opcional. |
| `codigoOriginador` | Texto | Código do originador do título. Campo opcional. |
| `dataEmissao` | Data | Data de emissão do título. |
| `dataVencimento` | Data | Data de vencimento do título. |
| `valorNominal` | Decimal | Valor original do título. |
| `valorAquisicao` | Decimal | Valor de aquisição do título. |
| `bancoCobranca` | Número | Código do banco responsável pela cobrança. Campo opcional. |
| `agenciaDepositaria` | Número | Agência depositária do banco de cobrança. Campo opcional. |
| `especie` | Texto ou Número | Espécie do título. Ver [Espécies de Título](#especies-de-titulo). |
| `jurosMoraDiaAtraso` | Decimal | Juros aplicados por dia de atraso. |
| `valorAbatimento` | Decimal | Valor de abatimento do título. |
| `valorDesconto` | Decimal | Valor de desconto concedido no título. Campo opcional; quando omitido, o título é gravado sem desconto. Não pode ser negativo nem superior ao `valorNominal`. |
| `tags` | Lista de texto | Tags associadas ao título. |
| `sacado` | [Sacado](#sacado) | Dados do pagador. |
| `lastro` | [Lastro](#lastro) | Dados do lastro do título. Obrigatório, exceto para as espécies `CCB` e `UR`. |

### Espécies de Título

Informe a **sigla** ou o **código numérico** correspondente à espécie do título no campo `especie`. Ambas as formas são aceitas.

| Sigla  | Código numérico | Espécie |
|--------|-----------------|---------|
| `DM`   | `2`  | Duplicata Mercantil |
| `UR`   | `3`  | Unidade de Recebível |
| `NFSE` | `4`  | Nota Fiscal de Serviço |
| `ND`   | `5`  | Nota de Débito |
| `CCB`  | `6`  | CCB Pré Digital |
| `NP`   | `8`  | Nota Promissória |
| `NC`   | `9`  | Nota Comercial |
| `CT`   | `10` | Contrato |
| `NF`   | `11` | Nota Fiscal |
| `CPR`  | `12` | Cédula de Produto Rural |
| `CTE`  | `13` | CT-e |
| `CD`   | `14` | Confissão de Dívida |
| `AD`   | `15` | Assunção de Dívida |
| `FCC`  | `16` | Fatura de Cartão de Crédito |
| `BAP`  | `17` | Bloqueio Agenda Pagamento Cartão |

> **Espécies de cartão**: `FCC` e `BAP` cobrem os recebíveis de cartão que chegam pelo arquivo de estoque diário — respectivamente a fatura de cartão de crédito e o bloqueio de agenda de pagamento com baixa automática. Como qualquer espécie fora de `CCB` e `UR`, ambas exigem o objeto `lastro`.

### Sacado

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `tipoPessoa` | Número | `1` = Pessoa Física, `2` = Pessoa Jurídica. |
| `cpfCnpj` | Texto | Documento do sacado, somente números. |
| `nome` | Texto | Nome do sacado. |
| `cep` | Texto | CEP do endereço. |
| `endereco` | Texto | Endereço do sacado. |
| `cidade` | Texto | Cidade do sacado. |
| `uf` | Texto | Unidade federativa do sacado. |
| `email` | Texto | E-mail do sacado. Campo opcional. |
| `telefone` | Texto | Telefone do sacado. Campo opcional. |
| `numero` | Número | Número do endereço. Campo opcional. |
| `bairro` | Texto | Bairro. Campo opcional. |
| `complemento` | Texto | Complemento do endereço. Campo opcional. |

### Lastro

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `numeroNotaFiscal` | Número | Número da nota fiscal. Campo opcional. |
| `numeroSerieNotaFiscal` | Número | Número de série da nota fiscal. Campo opcional. |
| `chaveNfe` | Texto | Chave da nota fiscal eletrônica. |
| `chaveAcessoNfe` | Texto | Chave de acesso da NF-e. Campo opcional. |
| `inscricaoMunicipal` | Texto | Inscrição municipal. Campo opcional. |
| `codigoMunicipioIBGE` | Texto | Código do município segundo o IBGE. Campo opcional. |
| `dataEmissao` | Data | Data de emissão da nota fiscal. |
| `valorTotal` | Decimal | Valor total da nota fiscal. |
| `tipoLastroPerformado` | Texto ou Número | Tipo do lastro performado. Aceita o código em **string** ou **numérico**: `SN` ou `0` (Serviços não performado), `SP` ou `1` (Serviços performado), `BN` ou `2` (Bens não performado), `BP` ou `3` (Bens performado), `MN` ou `4` (Bens e serviços não performado), `MP` ou `5` (Bens e serviços performado). |
| `quantidadeParcelas` | Número | Quantidade de parcelas vinculadas ao lastro. Campo opcional. |
| `chave` | Texto | Chave livre de identificação do lastro, definida por você (máximo de 100 caracteres). Campo opcional. Serve para **agrupar títulos no mesmo lastro** e para anexar o arquivo depois, em [Anexar Lastro Avulso por Chave](../9.%20Lastros%20Avulsos/9.3.%20Anexar%20Lastro%20Avulso%20por%20Chave.md). Ver [Agrupando títulos pelo mesmo lastro](#agrupando-titulos-pelo-mesmo-lastro). |


### Agrupando títulos pelo mesmo lastro

Um lastro pode respaldar **vários títulos** — o caso comum é uma nota fiscal parcelada, em que cada parcela vira um título. Para que os títulos apontem para um único lastro em vez de criarem uma cópia cada um, informe a **mesma chave** no campo `lastro.chave` de todos eles, na mesma requisição.

O agrupamento segue esta ordem:

1. Se `lastro.chaveNfe` estiver preenchida, ela é a chave de agrupamento — `lastro.chave` não é usada para agrupar (mas continua sendo gravada).
2. Sem `chaveNfe`, o agrupamento usa `lastro.chave`. É o caminho para lastros que **não possuem chave de acesso fiscal**: contrato, nota promissória, recebível de cartão.
3. Sem nenhuma das duas, cada título recebe o tratamento padrão e não há agrupamento por chave.

Espaços em volta da chave são removidos, e chave em branco é tratada como não informada — `" CONTRATO-4231 "` e `"CONTRATO-4231"` agrupam juntos.

```` json title="Dois títulos, um único lastro"
{
  "titulos": [
    {
      "numeroDocumento": "1001-1",
      "valorNominal": 500.0,
      "lastro": { "tipoLastroPerformado": "BP", "chave": "CONTRATO-4231" }
    },
    {
      "numeroDocumento": "1001-2",
      "valorNominal": 500.0,
      "lastro": { "tipoLastroPerformado": "BP", "chave": "CONTRATO-4231" }
    }
  ]
}
````

!!! tip "Anexando o arquivo depois"
    A chave também identifica o lastro no endpoint [Anexar Lastro Avulso por Chave](../9.%20Lastros%20Avulsos/9.3.%20Anexar%20Lastro%20Avulso%20por%20Chave.md). O fluxo típico é criar os títulos informando `lastro.chave` e, em seguida, enviar o documento (PDF do contrato, XML, imagem) usando a mesma chave — sem precisar descobrir o identificador interno do lastro.

!!! warning "A chave é sua, e o escopo dela é a operação"
    A `chave` é livre e definida por você; a plataforma não valida formato nem exige unicidade. Reaproveitar a mesma chave para lastros diferentes dentro da mesma operação faz títulos distintos compartilharem um lastro que não é o deles. Use um identificador estável da sua origem — número do contrato, id do pedido no ERP.

## Retorno

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `status` | Texto | Status do processamento. |
| `mensagem` | Texto | Mensagem retornada pela API. |
| `titulos` | Lista de [Título inválido](#titulo-invalido) | Lista preenchida quando houver inconsistências por título. |

### Título inválido

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `regra` | Texto | Regra de validação que rejeitou o título. |
| `quantidadeOcorrencia` | Número | Quantidade de ocorrências da regra. |
| `numeroDocumento` | Texto | Número do documento rejeitado. |
| `dataEmissao` | Data | Data de emissão informada. |
| `dataVencimento` | Data | Data de vencimento informada. |
| `valorNominal` | Decimal | Valor nominal informado. |
| `especie` | Número | Código da espécie do título. |
| `documentoSacado` | Texto | Documento do sacado informado. |