Pular para o conteúdo
Docs

Exportação contábil por layout

Atualizado em

Nesta página

A exportação gera um arquivo com as notas de um período no formato que o sistema contábil importa. O formato é descrito por um layout declarativo: um JSON que diz o tipo de arquivo, a codificação e quais campos vão em cada linha.

Quem pode usar#

Ação Permissão Papéis
Exportar e baixar ZIPs export:run owner, admin, emissor, contador
Criar e editar layouts da empresa export:layouts owner, admin

Exportar pelo painel#

  1. Abra a tela de exportação e escolha o layout.
  2. Escolha a competência (ou um período), se quer incluir notas canceladas e o que vai no pacote: o arquivo do layout, um ZIP com os XMLs e um ZIP com os PDFs.
  3. Confirme. A exportação roda em segundo plano.
  4. Quando terminar, o link de download fica disponível por 24 horas. O arquivo é apagado depois de 7 dias.

Se você assina o evento export.completed, recebe um webhook quando o arquivo fica pronto.

Layouts de sistema#

A plataforma mantém layouts prontos, que você pode usar direto ou duplicar e editar:

Layout O que gera
generico_csv CSV com uma linha por NFS-e, com os campos fiscais da nota. Opção de uma linha por item.
generico_xlsx O mesmo conteúdo em planilha XLSX.
Layouts de exemplo em TXT Modelos de arquivo de importação para sistemas contábeis específicos, marcados como a validar.

Status possíveis de um layout:

validation_status Significado
a_validar Criado a partir de documentação pública ou do cliente, sem teste de importação confirmado.
validado Importação testada, com responsável, data e evidência registrados.
obsoleto Substituído por uma versão mais nova.

Layouts da empresa#

Para ajustar um formato, duplique um layout de sistema e edite a cópia. O editor visual gera o JSON e mostra uma prévia com as 5 primeiras notas do período, antes de você salvar.

Formato do layout#

Layout de exemplo (TXT de largura fixa)
{
  "format": "txt_fixed",
  "encoding": "iso-8859-1",
  "line_ending": "crlf",
  "delimiter": ";",
  "quote": "\"",
  "header": false,
  "decimal_separator": ",",
  "date_format": "dd/MM/yyyy",
  "record_types": [
    {
      "code": "H",
      "when": "header_once",
      "fields": [
        { "name": "tipo", "source": "literal:H", "width": 1 },
        { "name": "cnpj_prestador", "source": "company.document", "transform": "digits_only", "width": 14 },
        { "name": "competencia", "source": "agg.period_start", "format": "date:MM/yyyy", "width": 7 }
      ]
    },
    {
      "code": "N",
      "when": "per_nfse",
      "fields": [
        { "name": "tipo", "source": "literal:N", "width": 1 },
        { "name": "numero", "source": "nfse.number", "width": 15, "pad": "left", "pad_char": "0" },
        { "name": "emissao", "source": "nfse.issued_at", "format": "date:dd/MM/yyyy", "width": 10 },
        { "name": "valor", "source": "nfse.total_amount", "format": "decimal:2", "width": 15, "pad": "left", "pad_char": "0" },
        { "name": "situacao", "source": "nfse.status", "map": { "authorized": "N", "canceled": "C" }, "width": 1 },
        { "name": "cnpj_tomador", "source": "customer.document", "transform": "digits_only", "width": 14 },
        { "name": "nome_tomador", "source": "customer.name", "transform": "upper", "width": 60, "pad": "right", "pad_char": " " }
      ]
    },
    {
      "code": "I",
      "when": "per_item",
      "fields": [
        { "name": "tipo", "source": "literal:I", "width": 1 },
        { "name": "codigo_servico", "source": "item.national_service_code", "width": 6 },
        { "name": "descricao", "source": "item.description", "transform": "truncate:80", "width": 80, "pad": "right", "pad_char": " " }
      ]
    },
    {
      "code": "T",
      "when": "trailer_once",
      "fields": [
        { "name": "tipo", "source": "literal:T", "width": 1 },
        { "name": "qtd", "source": "agg.count", "width": 6, "pad": "left", "pad_char": "0" }
      ]
    }
  ]
}

Opções de topo#

Chave Valores Observação
format csv, xlsx, txt_delimited, txt_fixed Em txt_fixed, cada campo precisa de width.
encoding utf-8, iso-8859-1, cp1252 Muitos sistemas contábeis antigos esperam iso-8859-1.
line_ending crlf, lf
delimiter / quote caractere Para csv e txt_delimited.
header true / false Linha de cabeçalho com os nomes dos campos (CSV/XLSX).
decimal_separator , ou .
date_format padrão de data Padrão para campos de data sem format próprio.

Tipos de registro (when)#

Valor Quando a linha é gerada
header_once Uma vez, no início do arquivo.
per_nfse Uma vez por nota.
per_item Uma vez por item da nota.
trailer_once Uma vez, no fim do arquivo.

Origens de dados (source)#

source aceita apenas caminhos de um catálogo fechado. Não existe expressão livre nem execução de código.

Prefixo Dados
nfse.* Dados da nota autorizada: número, chave de acesso, emissão, valores, status.
dps.* Dados da DPS: série, número, competência.
customer.* Tomador: documento, nome, endereço.
item.* Item: descrição, códigos de serviço, valores.
company.* Empresa prestadora.
agg.* Agregados do arquivo: contagem, somas, período.

Transformações#

Também vêm de uma lista fechada:

Transformação Efeito
digits_only Remove tudo que não é dígito (CNPJ, CPF, CEP).
upper Converte para maiúsculas.
truncate Corta no tamanho informado.
map Troca valores, por exemplo authorized → N.
default Valor padrão quando o campo vier vazio.
decimal:N Número com N casas decimais.
date:<formato> Data no formato informado.

Próximos passos#

Esta página foi útil?