Layout Retorno AG1¶
Estrutura do Arquivo¶
Arquivo CSV de retorno gerado pelo VeHub após o processamento do lote, com separador ponto e vírgula (;), codificação UTF-8 e quebra de linha CRLF (\r\n).
A primeira linha é o cabeçalho e cada linha seguinte representa um título do lote.
- Nome do arquivo:
RETORNO_VEHUB_{IdLote}_{yyyyMMddHHmmss}.csv— ex.:RETORNO_VEHUB_10254_20260901143012.csv - Cabeçalho: nomes técnicos das colunas, sem acentos e sem alteração de caixa (ex.:
CedenteTipoPessoa) - Linhas: todo o conteúdo é gravado em MAIÚSCULAS e sem acentos
- Datas:
DD/MM/AAAA - Valores monetários: formato pt-BR — ponto (
.) como separador de milhar e vírgula (,) como decimal - Campos sem valor: saem vazios (nada entre os
;), sem aspas e sem texto de preenchimento
Colunas¶
| # | Cabeçalho | Tipo | Descrição | Exemplo |
|---|---|---|---|---|
| 1 | CedenteTipoPessoa | Inteiro | Tipo de pessoa do cedente. Sempre 2 (Pessoa Jurídica) | 2 |
| 2 | CedenteCnpjCpf | Texto | CNPJ/CPF do cedente, com máscara | 45.723.174/0001-10 |
| 3 | CedenteNome | Texto | Razão social do cedente | EMPRESA EXEMPLO LTDA |
| 4 | TituloIdentificadorExterno | Texto | Número de controle do participante (identificador externo do título) | 676500 |
| 5 | TituloNumeroDocumento | Texto | Número do documento do título | 0114800/01 |
| 6 | TituloDataEmissao | Data | Data de emissão do título | 01/02/2026 |
| 7 | TituloDataVencimento | Data | Data de vencimento do título | 01/05/2026 |
| 8 | TituloValorNominal | Decimal | Valor nominal (de face) do título | 120.000,50 |
| 9 | TituloNossoNumero | Texto | Nosso número do título | 00012345678 |
| 10 | TituloBancoCobrador | Inteiro | Código do banco cobrador | 1 |
| 11 | TituloAgenciaCobranca | Inteiro | Código da agência cobradora (sem dígito verificador) | 1234 |
| 12 | TituloEspecie | Texto | Espécie do título | DP |
| 13 | SacadoTipoPessoa | Inteiro | Tipo de pessoa do sacado. 1 = Pessoa Física, 2 = Pessoa Jurídica | 2 |
| 14 | SacadoCpfCnpj | Texto | CNPJ/CPF do sacado, sem máscara (somente dígitos) | 56324545000108 |
| 15 | SacadoNome | Texto | Nome ou razão social do sacado | CLIENTE EXEMPLO LTDA |
| 16 | SacadoCep | Texto | CEP do sacado, como cadastrado | 80010000 |
| 17 | SacadoEndereco | Texto | Endereço do sacado | RUA A, 100 |
| 18 | SacadoBairro | Texto | Coluna reservada — sempre vazia neste retorno | |
| 19 | SacadoCidade | Texto | Cidade do sacado | CURITIBA |
| 20 | SacadoUf | Texto | UF do sacado (sigla de 2 letras) | PR |
| 21 | LastroDataEmissao | Data | Data de emissão do lastro | 01/02/2026 |
| 22 | LastroValorTotal | Decimal | Valor total do lastro | 120.000,50 |
| 23 | LastroPerformado | Texto | Indicador de performance do lastro | BP |
| 24 | NotaFiscalChaveNfe | Texto | Chave de acesso da NF-e (44 dígitos) | 41260245723174000110550020001148001637280530 |
| 25 | NotaServicoNumeroSerie | Inteiro | Número da nota fiscal / duplicata do lastro | 12345 |
| 26 | NotaServicoChaveAcesso | Texto | Código de verificação da NFS-e | 123456000123202404ABCD1234 |
| 27 | NotaServicoCodigoMunicipio | Texto | Código do município — do cedente; na ausência, o do lastro | 4106902 |
| 28 | TituloDataAquisicao | Data | Data de aquisição (cessão) do título | 05/02/2026 |
| 29 | TituloValorAquisicao | Decimal | Valor de aquisição do título no lote | 118.500,00 |
| 30 | TituloValorDesconto | Decimal | Valor de desconto (deságio) aplicado ao título no lote | 1.500,50 |
| 31 | TituloTaxaDesagio | Decimal | Percentual de deságio do lote, com 8 casas decimais — repetido em todas as linhas | 1,50000000 |
| 32 | TituloStatus | Texto | Situação de pagamento do título | ABERTO |
Espécies do Título¶
Códigos emitidos na coluna TituloEspecie:
| Código | Descrição |
|---|---|
DP | Duplicata Mercantil |
UR | Unidade de Recebível |
NFS | Nota Fiscal de Serviço |
ND | Nota de Débito |
CCB | CCB Pré Digital |
NP | Nota Promissória |
Espécies fora dessa lista são gravadas como vazio.
Tipos de Lastro Performado¶
Códigos emitidos na coluna LastroPerformado:
| Código | Descrição |
|---|---|
BP | Bens Performado |
BN | Bens Não Performado |
SP | Serviços Performado |
SN | Serviços Não Performado |
MP | Bens e Serviços Performado |
MN | Bens e Serviços Não Performado |
Lastro sem tipo definido é gravado como vazio.
Status do Título¶
| Valor | Regra |
|---|---|
PAGO | O título possui data de liquidação |
VENCIDO | Sem liquidação e com vencimento anterior à data de geração do arquivo |
ABERTO | Demais casos |
Regras¶
- Geração: o arquivo é produzido quando a operação está configurada com o layout de integração de saída
Águia - Retorno, ou pelo modoRefletir Entradas. - Refletir Entradas: nesse modo o retorno só é gerado se o lote possuir ao menos um título importado pelo layout de entrada
CSV - AG1. Uma vez gerado, o arquivo contém todos os títulos do lote, inclusive os importados por outros layouts. - Lote sem títulos: nenhum arquivo é gerado.
- Documento do cedente: recebe máscara de CNPJ quando tem 14 dígitos; caso contrário, máscara de CPF. O documento do sacado sai sem máscara.
- Acentuação: cabeçalho e linhas são gravados sem acentos (ex.:
OPERACAO,SAO PAULO).
Exemplo¶
CedenteTipoPessoa;CedenteCnpjCpf;CedenteNome;TituloIdentificadorExterno;TituloNumeroDocumento;TituloDataEmissao;TituloDataVencimento;TituloValorNominal;TituloNossoNumero;TituloBancoCobrador;TituloAgenciaCobranca;TituloEspecie;SacadoTipoPessoa;SacadoCpfCnpj;SacadoNome;SacadoCep;SacadoEndereco;SacadoBairro;SacadoCidade;SacadoUf;LastroDataEmissao;LastroValorTotal;LastroPerformado;NotaFiscalChaveNfe;NotaServicoNumeroSerie;NotaServicoChaveAcesso;NotaServicoCodigoMunicipio;TituloDataAquisicao;TituloValorAquisicao;TituloValorDesconto;TituloTaxaDesagio;TituloStatus
2;45.723.174/0001-10;EMPRESA EXEMPLO LTDA;676500;0114800/01;01/02/2026;01/05/2026;120.000,50;00012345678;1;1234;DP;2;56324545000108;CLIENTE EXEMPLO LTDA;80010000;RUA A, 100;;CURITIBA;PR;01/02/2026;120.000,50;BP;41260245723174000110550020001148001637280530;12345;123456000123202404ABCD1234;4106902;05/02/2026;118.500,00;1.500,50;1,50000000;ABERTO