Método	URL
	`https://BASE_URL/public/v1/recebiveis/lotes/{idOperacao}/lastros/avulsos/chave/{chave}`

Anexa um documento aos títulos cujo lastro já existe e foi identificado pela chave livre que você informou em lastro.chave ao criar os títulos (ver Adicionar Títulos).

Resolve o caso em que os documentos do lastro só ficam prontos depois da cessão — a nota fiscal, o contrato assinado, o termo de utilização, o canhoto digitalizado. Você cria os títulos informando uma chave da sua própria origem e, quando cada arquivo existir, envia-o com a mesma chave, sem precisar conhecer o identificador interno do lastro na plataforma.

Cada chamada acrescenta um documento. Uma mesma chave 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.

Títulos sem chave ou um título específico

Esta rota envia o documento para todos os títulos da chave. Para escolher os títulos pelo id — títulos criados sem lastro.chave (CNAB, XML, tela) ou uma única parcela da nota —, use Anexar Documento a Títulos. Para consultar, baixar ou desvincular o que foi enviado, veja a seção Documentos do Título.

Diferença para Anexar Lastros Avulsos

Em /lastros/avulsos/nfe você envia XML de NF-e, o conteúdo é interpretado pela plataforma e o vínculo com o título acontece de forma assíncrona, casando pela chave de acesso da nota.

Aqui o lastro já existe e o arquivo é apenas anexado, de forma síncrona: o conteúdo não é interpretado. Por isso aceita qualquer documento, inclusive os que não possuem chave de acesso fiscal — contrato, termo, nota promissória, imagem de canhoto.

Path Params¶

Campo	Tipo	Descrição
`idOperacao`	Número	Identificador da operação, fornecido pela VeHub. A busca pelo lastro é limitada a esta operação.
`chave`	Texto	Chave livre do lastro — exatamente a mesma enviada em `lastro.chave` na criação dos títulos.

Query Params¶

Campo	Tipo	Obrigatório	Descrição
`tipoDocumento`	Texto	Não	Tipo do documento enviado, 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 do título. Um novo envio com arquivo diferente substitui o anterior.
`Contrato` (contrato mestre), `TermoUtilizacao`, `CCB`, `NC`, `Nsu`	Documento adicional do título. Cada tipo e cada arquivo diferente viram um documento a mais.
(não informado)	No lastro principal, se ele ainda não tiver arquivo; senão, como documento adicional.

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.

Exemplo de cURL — nota, contrato mestre e termo pela mesma chave

curl -X POST "https://BASE_URL/public/v1/recebiveis/lotes/23/lastros/avulsos/chave/NF-4231?tipoDocumento=NFSE"   -H "Authorization: Bearer {token}"   -H "GrupoEconomico: {grupo}"   -F "arquivo=@/caminho/para/nota-4231.pdf"

curl -X POST "https://BASE_URL/public/v1/recebiveis/lotes/23/lastros/avulsos/chave/NF-4231?tipoDocumento=Contrato"   -H "Authorization: Bearer {token}"   -H "GrupoEconomico: {grupo}"   -F "arquivo=@/caminho/para/contrato-mestre.pdf"

curl -X POST "https://BASE_URL/public/v1/recebiveis/lotes/23/lastros/avulsos/chave/NF-4231?tipoDocumento=TermoUtilizacao"   -H "Authorization: Bearer {token}"   -H "GrupoEconomico: {grupo}"   -F "arquivo=@/caminho/para/termo-utilizacao.pdf"

Response Body — 200 OK

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

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

Erros¶

O mesmo arquivo reenviado para o mesmo título retorna HTTP 409 Conflict. Os demais erros retornam HTTP 400 Bad Request. Todos com o envelope RetornoPadrao.

Validação da requisição

Um tipoDocumento com nome fora da lista acima — e, na variante base64, o corpo sem nomeArquivo ou conteudoBase64, 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.

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, 551204."
}

Response Body — 400 Bad Request (chave não encontrada)

{
  "status": "erro",
  "mensagem": "Nenhum lastro encontrado para a chave informada"
}

Response Body — 400 Bad Request (nenhum arquivo enviado)

{
  "status": "erro",
  "mensagem": "Nenhum lastro foi enviado"
}

Response Body — 400 Bad Request (operação inexistente)

{
  "status": "erro",
  "mensagem": "Não foi possível identificar a operação 23."
}

Response Body — 400 Bad Request (documento fiscal para títulos de lastros diferentes)

{
  "status": "erro",
  "mensagem": "Documento fiscal só pode ser anexado de uma vez a títulos que compartilham o mesmo lastro principal."
}

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 e 409) são as mesmas da rota acima.

Método	URL
	`https://BASE_URL/public/v1/recebiveis/lotes/{idOperacao}/lastros/avulsos/chave/{chave}/base64`

Campo	Tipo	Obrigatório	Descrição
`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 parâmetro `tipoDocumento` da rota multipart (`NFSE`, `Contrato`, `TermoUtilizacao`...).

Request Body — base64

{
  "nomeArquivo": "contrato-mestre.pdf",
  "conteudoBase64": "JVBERi0xLjQKJ...",
  "tipoDocumento": "Contrato"
}

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

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

Response Body — 400 Bad Request (base64 vazio)

{
  "status": "erro",
  "mensagem": "O conteúdo do arquivo 'contrato-mestre.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). Só no sucesso.
`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 envio.
`idsTitulos`	Lista de números	Títulos que passaram a ter o documento.

Observações¶

A chave precisa existir antes: o endpoint não cria lastro. Se nenhum título daquela operação tiver lastro com a chave informada, a resposta é 400 com Nenhum lastro encontrado para a chave informada — e nada é gravado. Crie os títulos com lastro.chave primeiro.
Todos os títulos da chave recebem o documento: as parcelas de uma mesma nota compartilham o lastro e a chave, e todas passam a ter o documento enviado.
Use uma chave única por nota: recomendamos enviar em lastro.chave o mesmo sequencial usado em numeroControleParticipante. Chaves repetidas em criações diferentes geram lastros diferentes, e o documento vai para os títulos de todos eles.
Escopo por operação: a busca considera apenas títulos da operação da rota, dentro do grupo econômico autenticado. Uma chave que existe em outra operação não é encontrada aqui.
Sem interpretação do conteúdo: o arquivo não é parseado nem validado. Nada é extraído dele — número, série, valor e datas do lastro permanecem como foram informados na criação dos títulos.
Mesmo arquivo, mesmo título: reenviar um arquivo idêntico (mesmo conteúdo, qualquer nome) para um título que já o tem retorna 409 e nada é gravado. Se só parte dos títulos da chave já tiver o arquivo, a chamada inteira é recusada.
Contrato mestre compartilhado: o mesmo arquivo enviado para a chave de outro título da operação não é recusado — o documento que já existe é vinculado ao novo título (reaproveitado: true).
Documento fiscal substitui: um novo envio com tipoDocumento fiscal e conteúdo diferente substitui o arquivo do lastro principal. Documentos adicionais nunca substituem uns aos outros.
Espaços são aparados: a chave na URL é comparada sem os espaços em volta, do mesmo modo que na criação dos títulos.
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 400 e Informe o nome do arquivo, com a extensão.