Método	URL
	`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.

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": "12345678000195",
        "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"
      }
    }
  ]
}

Response Body — 200 OK

{
  "status": "sucesso",
  "mensagem": "1 título(s) incluído(s) com sucesso.",
  "titulosIncluidos": [
    {
      "id": 2001,
      "situacao": "",
      "numeroControleParticipante": "0001",
      "numeroDocumento": "12345",
      "dataEmissao": "2024-11-28",
      "dataVencimento": "2024-12-28",
      "valorNominal": 1000.5,
      "valorAquisicao": 975.12,
      "bancoCobranca": 123,
      "agenciaCobranca": 4567,
      "especie": "Duplicata",
      "jurosMoraDiaAtraso": 0.5,
      "valorAbatimento": 20,
      "valorDesconto": 15.5,
      "tags": ["CC01", "RATING_A"],
      "sacado": {
        "tipoPessoa": 2,
        "cpfCnpj": "12345678000195",
        "nome": "Sacado I",
        "cep": "12345678",
        "endereco": "Rua dos Sacados, 1000",
        "cidade": "Blumenau",
        "uf": "Santa Catarina (SC)",
        "email": "financeiro@sacado.com.br",
        "telefone": "47999990000",
        "numero": 1000,
        "bairro": "Centro",
        "complemento": "Sala 1"
      },
      "lastro": {
        "numeroNotaFiscal": 123456789,
        "numeroSerieNotaFiscal": 1,
        "chaveNfe": "12345678901234567890123456789012345678901234",
        "chaveCte": null,
        "chaveAcessoNfe": "",
        "inscricaoMunicipal": "",
        "codigoMunicipioIBGE": "",
        "dataEmissao": "2024-11-28",
        "valorTotal": 1000.5,
        "tipoLastroPerformado": "Bens performado",
        "quantidadeParcelas": 1,
        "chave": "CONTRATO-4231"
      }
    }
  ],
  "titulosNaoIncluidos": []
}

Modelo de dados¶

Requisição¶

Campo	Tipo	Descrição
`titulos`	Lista de Título	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.
`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	Dados do pagador.
`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
`DS`	`18`	Duplicata de Serviç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 de 44 dígitos da NF-e (modelo 55) ou do CT-e (modelo 57 ou 67). Quando a chave pertence a um CT-e válido, o sistema a reconhece automaticamente e vincula o título a um lastro de CT-e já existente (por exemplo, criado pelo upload do XML), evitando duplicidade.
`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. Ver Agrupando títulos 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:

Se lastro.chaveNfe estiver preenchida, ela é a chave de agrupamento — lastro.chave não é usada para agrupar (mas continua sendo gravada).
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.
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.

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" }
    }
  ]
}

Anexando os arquivos depois

A chave também identifica o lastro no endpoint Anexar Lastro Avulso por Chave. O fluxo típico é criar os títulos informando lastro.chave e, em seguida, enviar os documentos usando a mesma chave — um por chamada, como a nota fiscal, o contrato mestre e o termo de utilização — sem precisar descobrir o identificador interno do lastro. Sem chave, envie pelo id dos títulos em Anexar Documento a Títulos.

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 traz dois efeitos: na mesma requisição, títulos distintos passam a compartilhar um lastro que não é o deles; em requisições diferentes, cada uma cria o seu lastro, mas o documento enviado depois pela chave vai para os títulos de todos eles. Use um identificador único por nota, estável na sua origem — recomendamos o mesmo sequencial de numeroControleParticipante.

Retorno¶

A resposta 200 OK traz os títulos efetivamente incluídos no lote em titulosIncluidos. Títulos recusados na validação ou removidos por inelegibilidade aparecem em titulosNaoIncluidos, com o motivo — a inclusão pode ser parcial: o 200 pode trazer as duas listas preenchidas.

Campo	Tipo	Descrição
`status`	Texto	`"sucesso"` no `200 OK`; `"erro"` no `400 Bad Request`.
`mensagem`	Texto	Resumo do resultado. Ver Mensagens de sucesso.
`titulosIncluidos`	Lista de Título incluído	Títulos incluídos no lote. Vazia nos erros `400`.
`titulosNaoIncluidos`	Lista de Título não incluído	Títulos não incluídos, com o motivo. Pode vir preenchida no `200` (inclusão parcial) e no `400`.

Mensagens de sucesso¶

Situação	`mensagem`
Todos os títulos incluídos	`{n} título(s) incluído(s) com sucesso.`
Parte dos títulos não incluída	`{n} título(s) incluído(s) e {m} título(s) não incluído(s).`

Response Body — 200 OK (inclusão parcial)

{
  "status": "sucesso",
  "mensagem": "1 título(s) incluído(s) e 1 título(s) não incluído(s).",
  "titulosIncluidos": [
    { "id": 2001, "numeroControleParticipante": "0001", "numeroDocumento": "12345" }
  ],
  "titulosNaoIncluidos": [
    {
      "numeroControleParticipante": "",
      "numeroDocumento": "12346",
      "dataEmissao": "2024-11-28",
      "dataVencimento": "2024-10-28",
      "valorNominal": 500.0,
      "especie": "Duplicata",
      "documentoSacado": "12345678000195",
      "motivo": "Título vencido. Operação não permite importação de títulos com data de vencimento anterior à data atual."
    }
  ]
}

Exemplo resumido

No exemplo acima, os itens de titulosIncluidos foram abreviados; na resposta real, cada item traz todos os campos de Título incluído.

Título incluído¶

Campo	Tipo	Descrição
`id`	Número	Identificador do título.
`situacao`	Texto	Não utilizado neste endpoint: vem vazio.
`numeroControleParticipante`	Texto	Número de controle do participante.
`numeroDocumento`	Texto	Número do documento.
`dataEmissao`	Data	Data de emissão do título.
`dataVencimento`	Data	Data de vencimento do título.
`valorNominal`	Decimal	Valor nominal do título.
`valorAquisicao`	Decimal	Valor de aquisição do título no lote, já calculado.
`bancoCobranca`	Número	Código do banco de cobrança.
`agenciaCobranca`	Número	Agência de cobrança.
`especie`	Texto	Descrição da espécie do título (ex.: `Duplicata`, `UR`, `CCB Pré Digital`).
`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.
`tags`	Lista de texto	Tags associadas ao título.
`sacado`	Objeto	Dados do pagador. Mesmos campos do Sacado da requisição; no retorno, `uf` é devolvido por extenso (ex.: `Santa Catarina (SC)`).
`lastro`	Objeto	Dados do lastro, quando houver. Mesmos campos do Lastro da requisição, mais `chaveCte` (chave do CT-e, quando o lastro é um CT-e); no retorno, `tipoLastroPerformado` é devolvido por extenso (ex.: `Bens performado`) e `chaveAcessoNfe`, `inscricaoMunicipal` e `codigoMunicipioIBGE` vêm vazios.

Título não incluído¶

Campo	Tipo	Descrição
`numeroControleParticipante`	Texto	Número de controle do participante. Vem vazio quando o título foi recusado nas validações da requisição; vem preenchido quando o título foi removido do lote por inelegibilidade no cálculo do deságio.
`numeroDocumento`	Texto	Número do documento.
`dataEmissao`	Data	Data de emissão.
`dataVencimento`	Data	Data de vencimento.
`valorNominal`	Decimal	Valor nominal.
`especie`	Texto	Descrição da espécie do título (ex.: `Duplicata`), e não a sigla enviada.
`documentoSacado`	Texto	Documento do sacado, quando disponível. Pode vir nulo.
`motivo`	Texto	Motivo da recusa.

Respostas de erro¶

Os erros retornam 400 Bad Request no mesmo formato do retorno, com status "erro" e titulosIncluidos vazia. Nenhum título é gravado.

Situação	`mensagem`	`titulosNaoIncluidos`
Lote não encontrado.	`Lote não encontrado.`	Vazia.
Lote fora do status Em Digitação.	`Para adicionar títulos é necessário que o lote esteja 'Em digitação'.`	Vazia.
Operação valida lastro e algum título veio sem `lastro` (exceto CCB Pré Digital e UR).	`Erro ao inserir títulos no lote.`	Títulos sem lastro, com `motivo` `As informações de lastro são obrigatórias.`
Operação exige a chave da nota fiscal na entrada e algum lastro veio sem ela.	`Existem lastros sem chave da nota fiscal`	Vazia.
Operação exige o arquivo do lastro para compor o lote e algum título não tem o arquivo. Ver Validação de arquivo de lastro.	`Erro ao inserir títulos no lote.`	Títulos sem arquivo, com `motivo` `O arquivo do lastro é obrigatório para compor o lote.`
Nenhum título passou nas regras de elegibilidade da operação.	`Nenhum título foi elegível para as regras desta operação.`	Títulos removidos, com o motivo de cada um.

Validação de arquivo de lastro¶

Quando a operação tem o parâmetro "Exige arquivo de lastro para compor lote" habilitado, todo título incluído em um lote de cessão precisa ter, no momento da inclusão, um lastro com o arquivo (XML ou PDF) já gravado na plataforma. Se qualquer título não tiver o arquivo, nenhum título da requisição é incluído e a resposta é 400 Bad Request.

Como os títulos são criados por esta própria requisição, o arquivo precisa ter sido enviado antes:

Envie o XML da nota por Anexar Lastros Avulsos (ou por Anexar Lastros, com o lote já criado).
Acompanhe a importação em Consultar Importação de Lastros Avulsos até que ela termine: o processamento do XML é assíncrono.
Adicione os títulos informando em lastro.chaveNfe a mesma chave de acesso do XML enviado. O título é vinculado ao lastro já existente, que tem o arquivo.

Response Body — 400 Bad Request (arquivo de lastro ausente)

{
  "status": "erro",
  "mensagem": "Erro ao inserir títulos no lote.",
  "titulosIncluidos": [],
  "titulosNaoIncluidos": [
    {
      "numeroControleParticipante": "",
      "numeroDocumento": "12345",
      "dataEmissao": "2024-11-28",
      "dataVencimento": "2024-12-28",
      "valorNominal": 1000.50,
      "especie": "Duplicata",
      "documentoSacado": null,
      "motivo": "O arquivo do lastro é obrigatório para compor o lote."
    }
  ]
}

Espécies sujeitas à exigência

A exigência vale para as espécies configuradas na operação junto com o parâmetro. Em operações que habilitaram o parâmetro antes de existir essa lista de espécies, valem todas as espécies, exceto CCB Pré Digital e Unidade de Recebível. A validação só se aplica a lotes de cessão.