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

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

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. 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 o arquivo 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 o documento (PDF do contrato, XML, imagem) usando a mesma chave — sem precisar descobrir o identificador interno do lastro.

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