Template de planilha para emissão de DC-e em lote

Emitir várias DC-e de uma vez não exige integração: basta preencher uma planilha e subir o arquivo. Esta página é o contrato desse arquivo — quais abas existem, quais colunas cada uma tem, o que é obrigatório, o que a ausência de uma coluna significa e o que a plataforma faz com cada valor.

Versão do contrato: v1. A versão também aparece na aba Referencia do modelo, e sobe quando uma coluna some, muda de nome ou muda de significado.

Você não precisa começar do modelo

O modelo preenchido é oferecido para download no painel, na importação em lote. Ele existe para poupar trabalho, não para ser obrigatório: qualquer arquivo com estas colunas é aceito, inclusive o que o seu sistema exportar. As colunas são casadas por nome.

Quem integra por API não passa por aqui — a emissão documento a documento está em Emitir uma DC-e.

Por que duas abas, e não uma

Uma DC-e declara de 1 a 999 itens. Repetir os 40 campos do documento em cada linha de item permitiria a mesma DC-e aparecer com destinatários diferentes em linhas distintas, sem critério para eleger a correta — e um lote de 200 documentos com 5 itens viraria 1.000 linhas de 48 colunas.

Por isso o arquivo tem três abas:

Aba	O que é	O que a plataforma faz
DCe	uma linha por documento	lê
Itens	uma linha por item	lê
Referencia	consulta: valores aceitos, limites e obrigatoriedade condicional	ignora, por nome — não é dado

As duas abas de dado são obrigatórias. Arquivo sem a aba Itens é recusado nomeando a aba que falta.

Como as colunas são casadas

Por nome, nunca por posição. O cabeçalho é normalizado antes da comparação — sem acento, sem caixa, sem asterisco e sem separador —, então Descrição *, descricao e DESCRICAO são a mesma coluna.

Isso tem uma consequência que vale conhecer: coluna nova entra no fim, e coluna existente nunca é reordenada. Quem montou o próprio exportador casando por posição continua funcionando.

O asterisco no cabeçalho

* no cabeçalho quer dizer obrigatória sempre.

Coluna sem asterisco não quer dizer opcional

Quer dizer que a obrigatoriedade depende de outra coluna — a modalidade de emissão, a de transporte ou qual documento identifica cada parte. As regras estão em Obrigatoriedade condicional.

Aba DCe

Uma linha por documento. A ordem das colunas é a de preenchimento (identidade → emitente → parte emissora → destinatário → transporte → autorizados → informação adicional), não a do XML: quem preenche lê a planilha da esquerda para a direita uma vez só.

A coluna "Campo na API" é o caminho no corpo da emissão, para quem quiser comparar com a referência da API.

Coluna	Campo na API	Obrigatória	Observação
ID_DCe	— (vínculo local)	sim	Identificador escolhido por você, até 40 caracteres. É o que aparece no relatório de erro. Não vai para a API
Tipo_Emitente	emitterType	sim	Marketplace, Emissao_Propria ou Transportadora
Emitente_CNPJ	issuer.cnpj	condicional	Só dígitos. Único documento aceito em Emissao_Propria
Emitente_CPF	issuer.cpf	condicional	Só dígitos
Emitente_ID_Outros	issuer.idOthers	condicional	Identificação estrangeira, quando não há CNPJ nem CPF
Emitente_Nome	issuer.name	sim
Emitente_Endereco_CEP	issuer.address.postalCode	sim	Só dígitos, oito. O zero à esquerda importa
Emitente_Endereco_Logradouro	issuer.address.street	sim
Emitente_Endereco_Numero	issuer.address.number	sim	Texto: S/N é valor legítimo
Emitente_Endereco_Complemento	issuer.address.complement	não	Vazio é omitido, não enviado como texto vazio
Emitente_Endereco_Bairro	issuer.address.neighborhood	sim
Emitente_Endereco_Cidade_Codigo	issuer.address.cityCode	sim	Código IBGE de sete dígitos
Emitente_Endereco_Cidade_Nome	issuer.address.cityName	sim
Emitente_Endereco_Estado	issuer.address.state	sim	Sigla de duas letras
Parte_Emissora_CNPJ	emitterParty.cnpj	condicional	Em Emissao_Propria, derivado do emitente quando vazio
Parte_Emissora_Nome	emitterParty.name	condicional	Em Emissao_Propria, derivado do emitente quando vazio
Parte_Emissora_Site	emitterParty.site	condicional	Obrigatório em Marketplace
Destinatario_CNPJ	recipient.cnpj	condicional	Só dígitos
Destinatario_CPF	recipient.cpf	condicional	Só dígitos
Destinatario_ID_Outros	recipient.idOthers	condicional	Identificação estrangeira
Destinatario_Nome	recipient.name	sim
Destinatario_Email	recipient.email	não	Quem recebe o aviso de emissão
Destinatario_Endereco_CEP	recipient.address.postalCode	sim	Só dígitos, oito
Destinatario_Endereco_Logradouro	recipient.address.street	sim
Destinatario_Endereco_Numero	recipient.address.number	sim
Destinatario_Endereco_Complemento	recipient.address.complement	não
Destinatario_Endereco_Bairro	recipient.address.neighborhood	sim
Destinatario_Endereco_Cidade_Codigo	recipient.address.cityCode	sim	Código IBGE de sete dígitos
Destinatario_Endereco_Cidade_Nome	recipient.address.cityName	sim
Destinatario_Endereco_Estado	recipient.address.state	sim
Destinatario_Endereco_Pais_Codigo	recipient.address.countryCode	não	Padrão 1058 (Brasil)
Destinatario_Endereco_Pais	recipient.address.country	não	Padrão Brasil
Transporte_Modalidade	transport.mode	sim	Correios, Proprio ou Transportadora
Transporte_Transportadora_CNPJ	transport.carrierCnpj	condicional	Enviado só em Transportadora; nas outras é descartado
Autorizados_CNPJ	authorizedDownloaders[].cnpj	não	Vários separados por ;
Autorizados_CPF	authorizedDownloaders[].cpf	não	Vários separados por ;. Somando as duas colunas, no máximo 10
Info_Adicional_Fisco	additionalInfo.fiscoInfo	não
Info_Adicional_Complementar	additionalInfo.complementary	não
Info_Adicional_Marketplace	additionalInfo.marketplaceInfo	não
Info_Adicional_Correios	additionalInfo.ectInfo	não

Por que o destinatário tem colunas de país e o emitente não

A DC-e admite destinatário no exterior, então o endereço do destinatário aceita qualquer país. O do emitente não: o código de país do emitente é uma enumeração de um único valor (1058) e o nome só aceita Brasil. Informar outro país no emitente faz a SEFAZ rejeitar o documento.

Aba Itens

Uma linha por item. A coluna ID_DCe liga a linha ao documento da aba DCe.

Coluna	Campo na API	Obrigatória	Observação
ID_DCe	— (vínculo local)	sim	Tem que existir na aba DCe. Item órfão é erro
Item_Numero	items[].itemNumber	não	Informativo — veja o aviso abaixo
Descricao	items[].description	sim	1 a 120 caracteres
NCM	items[].ncm	não	Vazio, 2 ou 8 dígitos
Quantidade	items[].quantity	sim	Número. Vírgula ou ponto decimal
Valor_Unitario	items[].unitValue	sim
Valor_Total	items[].totalValue	não	Vazio = quantidade × unitário. Informado é respeitado sem recálculo
Informacoes_Adicionais	items[].additionalInfo	não	Até 500 caracteres

Item_Numero é informativo, e a plataforma o ignora

A numeração enviada é sempre 1..N, pela ordem das linhas na aba. A regra H02-10 da SEFAZ exige numeração consecutiva começando em 1 e rejeita o documento com cStat 927 quando não é — e planilha preenchida à mão chega com numeração que pula e repete. A coluna existe para você se orientar ao preencher; quem decide a ordem é a posição da linha.

Valor_Total informado não é recalculado

Mesmo divergindo de quantidade × valor unitário, o valor que você informar é o que vai para a SEFAZ. Deixar a coluna vazia é o caminho seguro: a conta é feita para você. Na API, o valor total do item é obrigatório — é a planilha que o calcula quando você omite.

Valores aceitos

A planilha fala português e a API fala o enum dela. A tradução é parte do contrato: é o que permite conferir na referência da API o que cada valor faz.

Tipo_Emitente

Na planilha	Na API	O que muda
Marketplace	Marketplace	Exige Parte_Emissora_Site
Emissao_Propria	SelfIssuer	Só aceita Emitente_CNPJ; Parte_Emissora_* é derivada do emitente
Transportadora	Carrier	Aceita CNPJ, CPF ou identificação estrangeira no emitente

Transporte_Modalidade

Na planilha	Na API	O que muda
Correios	Mail	Transporte_Transportadora_CNPJ é descartado
Proprio	OwnCarriage	Transporte_Transportadora_CNPJ é descartado
Transportadora	Carrier	Exige Transporte_Transportadora_CNPJ

Transportadora aparece nas duas listas, e são coisas diferentes

Em Tipo_Emitente, é quem declara o conteúdo. Em Transporte_Modalidade, é quem leva a carga. Uma emissão própria entregue por transportadora usa Emissao_Propria na primeira coluna e Transportadora na segunda.

O que cada modalidade de emissão exige de cadastro na SEFAZ está em Credenciamento.

Regras de vínculo entre as abas

Regra	O que acontece quando quebra
ID_DCe preenchido nas duas abas	linha sem identificador é recusada
ID_DCe único na aba DCe	duas linhas com o mesmo identificador é erro: não há como saber qual documento vale
Todo item aponta para um ID_DCe que existe na aba DCe	item órfão é erro, apontando o identificador
Todo documento tem pelo menos um item	documento sem item é erro: a DC-e exige de 1 a 999
Dados do documento não divergem entre linhas do mesmo ID_DCe	erro, porque nenhum critério de desempate seria defensável

Obrigatoriedade condicional

O quê	Regra
Identificação do emitente	exatamente uma entre Emitente_CNPJ, Emitente_CPF e Emitente_ID_Outros — e só Emitente_CNPJ quando Tipo_Emitente = Emissao_Propria
Identificação do destinatário	exatamente uma entre Destinatario_CNPJ, Destinatario_CPF e Destinatario_ID_Outros
Parte_Emissora_Site	obrigatório quando Tipo_Emitente = Marketplace
Parte_Emissora_CNPJ e Parte_Emissora_Nome	obrigatórios em Marketplace e Transportadora; em Emissao_Propria, derivados do emitente quando vazios
Transporte_Transportadora_CNPJ	obrigatório quando Transporte_Modalidade = Transportadora; descartado nas outras

Se mais de um documento vier preenchido para a mesma parte, a precedência é CNPJ → CPF → identificação estrangeira — a mesma que a API usa ao exibir o documento na consulta.

Limites

O quê	Limite
Itens por DC-e	1 a 999
Descricao do item	1 a 120 caracteres
Informacoes_Adicionais do item	até 500 caracteres
Autorizados a baixar o XML	até 10, somando Autorizados_CNPJ e Autorizados_CPF
ID_DCe	até 40 caracteres, único na aba DCe
NCM	vazio, 2 ou 8 dígitos

Os quatro primeiros são limites do próprio documento fiscal, definidos no leiaute da DC-e: valem igualmente para quem emite pela API. ID_DCe é da planilha, porque a API não tem esse campo.

O que deliberadamente não tem coluna

Ausência	Por quê
Série e número	quem numera é a plataforma. Uma coluna aqui seria promessa que o cliente descobriria como documento duplicado (cStat 451/452)
Ambiente	é da empresa, e é o mesmo valor que escolhe o host da API. O arquivo poder discordar da conta é exatamente o que a validação recusa
Qualquer tributo	a DC-e não tem imposto: sem ICMS, sem IBS/CBS, sem alíquota. É o que a separa da NF-e — veja Conceitos
Tipo de emissão / contingência	só a emissão normal existe; a SEFAZ rejeita contingência offline com cStat 215
País do emitente	o emitente é sempre brasileiro no leiaute: o código de país é enumeração de um valor e o nome fora de Brasil reprova na validação

Zero à esquerda, e por que ele importa

CEP 04403240 lido como número volta 4403240; CNPJ vira notação científica. O arquivo é normalizado na leitura — mas você vê o valor errado na sua tela e conclui que a planilha está quebrada.

Por isso, no modelo, as colunas de documento (CNPJ, CPF, identificação estrangeira), CEP, código de município, NCM e ID_DCe são gravadas com formato de texto: o Excel não as converte ao abrir. Se você montar o arquivo no seu sistema, formate essas colunas como texto antes de exportar.

As linhas de exemplo

O modelo vem preenchido, com dois documentos — o vínculo entre as abas é a única parte do formato que não é óbvia, e dois exemplos o explicam sem documentação:

ID_DCe	Tipo_Emitente	Itens	O que demonstra
EXEMPLO-1	Emissao_Propria	1	o caso simples: CNPJ do emitente, destinatário pessoa física, envio pelos Correios
EXEMPLO-2	Marketplace	2	Parte_Emissora_* com site, transporte por transportadora com CNPJ, autorizados separados por ;

Os documentos dos exemplos são fictícios, com dígito verificador válido.

Apague as linhas de exemplo antes de enviar

Os identificadores começam com EXEMPLO- de propósito: encontrando linhas de exemplo intactas no arquivo enviado, a plataforma avisa antes de emitir. Renomear o prefixo desliga esse aviso — e emitir um exemplo é emitir um documento fiscal de verdade.

A planilha de resultado

Terminado o envio, a exportação devolve o mesmo arquivo — as duas abas e todas as colunas de origem intactas — com mais quatro colunas ao fim da aba DCe:

Coluna	Conteúdo
Resultado	o desfecho da linha
Chave_Acesso	a chave de acesso, quando houver
Protocolo	o protocolo da SEFAZ, quando houver
Motivo	a mensagem da recusa ou o motivo da rejeição, quando houver

Este arquivo volta a ser aceito na importação, e é para isso que ele existe: o ciclo é exportar, corrigir as linhas que falharam no próprio arquivo e subir de novo. As quatro colunas acrescentadas são ignoradas na leitura.

Reenviar uma linha já emitida não gera documento novo: cada linha carrega uma chave de idempotência, e o reenvio devolve o documento que já existe. A proteção vale por 24 horas.

Veja também

• Conceitos da DC-e
• Credenciamento
• Emitir uma DC-e
• Como consultar uma DC-e
• Cancelamento de DC-e