Método	URL
	`https://BASE_URL/public/v1/recebiveis/titulos/documentos`

Anexa um documento a um ou mais títulos, identificados pelo id, com um único upload. É a mesma regra de Anexar Lastro Avulso por Chave, mas escolhendo os títulos pelo id em vez da chave do lastro — serve para títulos criados sem lastro.chave (CNAB, XML, tela) e para mirar um título específico entre as parcelas de uma nota.

Cada chamada acrescenta um documento. Um título pode receber, em chamadas separadas, a nota fiscal, o contrato mestre e o termo de utilização — um não substitui o outro. Use tipoDocumento para dizer o que está sendo enviado.

Request Body¶

A requisição deve ser enviada como multipart/form-data.

Campo	Tipo	Obrigatório	Descrição
`arquivo`	Arquivo	Sim	Arquivo a ser anexado. Um único arquivo por chamada.
`idsTitulos`	Lista de números	Sim	Títulos que recebem o documento, todos da mesma operação. Repita o campo para cada título. Até 1.000 por chamada.
`tipoDocumento`	Texto	Não	Tipo do documento, pelo nome (maiúsculas e minúsculas indiferentes). Ver a tabela abaixo.

`tipoDocumento`	Onde o arquivo é gravado
`NFSE`, `NFE`, `CTE`, `DuplicataMercantil`	Documento fiscal: no lastro principal dos títulos, que precisam compartilhar o mesmo lastro principal — e a chamada precisa trazer todos os títulos desse lastro (todas as parcelas da nota). Um novo envio com arquivo diferente substitui o anterior.
`Contrato` (contrato mestre), `TermoUtilizacao`, `CCB`, `NC`, `Nsu`	Documento adicional dos títulos. Cada tipo e cada arquivo diferente viram um documento a mais.
(não informado)	No lastro principal, se todos os títulos compartilham um principal que ainda não tem arquivo; senão, como documento adicional (`Contrato`).

Exemplo de cURL — contrato mestre para três títulos

curl -X POST "https://BASE_URL/public/v1/recebiveis/titulos/documentos" \
  -H "Authorization: Bearer {token}" \
  -H "GrupoEconomico: {grupo}" \
  -F "arquivo=@/caminho/para/contrato-mestre.pdf" \
  -F "idsTitulos=551203" \
  -F "idsTitulos=551204" \
  -F "idsTitulos=551377" \
  -F "tipoDocumento=Contrato"

Response Body — 200 OK

{
  "status": "sucesso",
  "mensagem": "Documento anexado ao lastro.",
  "idLastro": 98231,
  "principal": false,
  "reaproveitado": false,
  "idsTitulos": [551203, 551204, 551377]
}

Response Body — 200 OK (mesmo contrato já enviado para outro título da operação)

{
  "status": "sucesso",
  "mensagem": "Documento já existente vinculado ao título.",
  "idLastro": 98231,
  "principal": false,
  "reaproveitado": true,
  "idsTitulos": [551400]
}

Erros¶

Todos os erros retornam o envelope RetornoPadrao.

HTTP	Quando
`409 Conflict`	O mesmo arquivo (mesmo conteúdo, qualquer nome) já está anexado a algum dos títulos. Nada é gravado.
`404 Not Found`	Algum título não existe. A mensagem lista os ids.
`400 Bad Request`	Nenhum arquivo, nome do arquivo vazio, nenhum título, mais de 1.000 títulos, títulos de operações diferentes, `tipoDocumento` inexistente, documento fiscal para títulos com lastros principais diferentes ou para só parte dos títulos de um lastro principal.

Response Body — 409 Conflict (arquivo já anexado ao título)

{
  "status": "erro",
  "mensagem": "O arquivo 'contrato-mestre.pdf' já está anexado ao(s) título(s) 551203."
}

Response Body — 404 Not Found (título inexistente)

{
  "status": "erro",
  "mensagem": "Título(s) 551999 não encontrado(s)."
}

Response Body — 400 Bad Request (títulos de operações diferentes)

{
  "status": "erro",
  "mensagem": "Os títulos informados pertencem a operações diferentes. Envie o documento separadamente para cada operação."
}

Response Body — 400 Bad Request (nota compartilhada com títulos fora da chamada)

{
  "status": "erro",
  "mensagem": "O documento fiscal é o lastro principal compartilhado com outros títulos (551204, 551205). Inclua todos os títulos da nota na chamada ou envie pela chave do lastro."
}

Response Body — 400 Bad Request (tipoDocumento inexistente)

{
  "status": "erro",
  "mensagem": "Tipo de documento inválido: 999. Valores aceitos: ..."
}

Response Body — 400 Bad Request (acima do limite)

{
  "status": "erro",
  "mensagem": "Informe no máximo 1000 títulos por chamada. Repita a chamada para os demais: o mesmo arquivo é reaproveitado, sem novo upload."
}

Validação da requisição

Um tipoDocumento com nome fora da lista acima — e, na variante base64, o corpo sem nomeArquivo, conteudoBase64 ou idsTitulos, ou com nomeArquivo acima de 255 caracteres — é recusado antes de chegar à regra de anexo: a resposta é 400 Bad Request no formato ProblemDetails, descrito em Primeiros Passos. Um tipoDocumento enviado como número que não corresponde a nenhum tipo é recusado no envelope RetornoPadrao, com a mensagem Tipo de documento inválido e a lista dos valores aceitos, sem upload.

Variante com o arquivo em base64¶

Para integrar sem multipart/form-data, envie o arquivo em base64 no corpo JSON. A regra e as respostas (200, 400, 404 e 409) são as mesmas da rota acima.

Método	URL
	`https://BASE_URL/public/v1/recebiveis/titulos/documentos/base64`

Campo	Tipo	Obrigatório	Descrição
`idsTitulos`	Lista de números	Sim	Títulos que recebem o documento, todos da mesma operação (até 1.000).
`nomeArquivo`	Texto	Sim	Nome do arquivo, com a extensão (até 255 caracteres).
`conteudoBase64`	Texto	Sim	Conteúdo do arquivo codificado em base64.
`tipoDocumento`	Texto	Não	Mesmos valores do campo `tipoDocumento` da rota multipart.

Request Body — base64

{
  "idsTitulos": [551203, 551204],
  "nomeArquivo": "termo-utilizacao.pdf",
  "conteudoBase64": "JVBERi0xLjQKJ...",
  "tipoDocumento": "TermoUtilizacao"
}

Response Body — 400 Bad Request (base64 inválido)

{
  "status": "erro",
  "mensagem": "O conteúdo do arquivo 'termo-utilizacao.pdf' não é um base64 válido."
}

Response Body — 400 Bad Request (base64 vazio)

{
  "status": "erro",
  "mensagem": "O conteúdo do arquivo 'termo-utilizacao.pdf' está vazio."
}

Modelo de dados¶

Retorno¶

Campo	Tipo	Descrição
`status`	Texto	Status do processamento.
`mensagem`	Texto	Mensagem retornada pela API.
`idLastro`	Número	Lastro que recebeu o arquivo (documento fiscal) ou que foi vinculado aos títulos (documento adicional).
`principal`	Booleano	`true` quando o arquivo foi gravado no lastro principal (documento fiscal).
`reaproveitado`	Booleano	`true` quando o mesmo arquivo já existia em outro título da operação e foi apenas vinculado, sem novo upload.
`idsTitulos`	Lista de números	Títulos que passaram a ter o documento (ids repetidos na chamada contam uma vez).

Observações¶

Tudo ou nada: se algum título não existe, é de outra operação ou já tem o arquivo, a chamada inteira é recusada e nada é gravado.
Nota com várias parcelas: o documento fiscal fica no lastro principal, que é o mesmo para todas as parcelas da nota. Por isso a troca do arquivo exige todos os títulos desse lastro na chamada; a recusa lista (até 20) os que faltaram. Para não precisar dos ids, use a rota por chave, que sempre alcança todas as parcelas.
Nome do arquivo: só o nome é usado — um caminho enviado junto é descartado (../pasta/contrato.pdf é gravado como contrato.pdf). Nome que fica vazio é recusado com Informe o nome do arquivo, com a extensão.
Contrato mestre compartilhado: o mesmo arquivo já anexado a outro título da operação não é recusado — o documento existente é vinculado aos novos títulos (reaproveitado: true). Isso também vale para repetir a chamada em blocos de até 1.000 títulos.
Sem interpretação do conteúdo: o arquivo não é parseado nem validado. Os dados da nota (número, série, valor, datas) continuam os informados na criação dos títulos.
Envio à administradora: os documentos adicionais seguem para a administradora apenas nas operações do canal Envio de arquivo configurado; acompanhe em Listar Documentos do Título.