DC-e obrigatória em 2026 — antecipe-se e emita em lote hoje mesmo. Ver o sistema DC-e
Referência técnica

Documentação da API DC-e

Tudo o que o seu time de desenvolvimento precisa para integrar a emissão de Declaração de Conteúdo Eletrônica: autenticação, endpoints REST, estrutura dos objetos e exemplos de JSON prontos para copiar.

REST + JSON Bearer Token Certificado híbrido
Solicitar credenciais Sobre a API DC-e

Base URL

Todas as requisições partem do mesmo host. Os caminhos descritos nesta documentação são relativos a esta base.

txt
https://portaldce.com.br/api

Autenticação

A API utiliza autenticação via Bearer Token. Todos os endpoints protegidos exigem o cabeçalho de autorização:

http
Authorization: Bearer ACCESS_TOKEN

Gerar access token

POST/oauth/token.php

Headers

http
Content-Type: application/json

Request

json
{
  "client_id": "SEU_CLIENT_ID",
  "client_secret": "SEU_CLIENT_SECRET"
}

Response

json
{
  "success": true,
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "TOKEN",
  "refresh_token": "REFRESH_TOKEN"
}

Refresh token

POST/oauth/refresh.php

Request

json
{
  "refresh_token": "SEU_REFRESH_TOKEN"
}

Response

json
{
  "success": true,
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "NOVO_ACCESS_TOKEN",
  "refresh_token": "NOVO_REFRESH_TOKEN"
}

Expiração do token

CampoTempoObservação
access_token1 horaDeve ser renovado manualmente utilizando o refresh_token
refresh_tokenRenovado automaticamenteUm novo refresh_token é retornado a cada renovação
Importante

O access_token não é renovado automaticamente pelo PortalDCE. A aplicação cliente deve renová-lo manualmente. Sempre que o token expirar, a aplicação deve:

  1. Chamar o endpoint POST /oauth/refresh.php
  2. Enviar o refresh_token
  3. Salvar o novo access_token
  4. Salvar também o novo refresh_token retornado
Recomendação

Renove o token automaticamente alguns minutos antes da expiração para evitar falhas de autenticação em produção.

Headers obrigatórios

Todos os endpoints protegidos

http
Authorization: Bearer ACCESS_TOKEN

Requisições JSON

http
Content-Type: application/json

Métodos HTTP

MétodoUtilização
POSTCriar / transmitir / cancelar
GETConsultar / download
PUTAtualizar
DELETEExcluir

Endpoints disponíveis

MétodoEndpointDescrição
POST /v1/criar.php Criar DC-e
GET /v1/consultar.php?id=ID Consultar DC-e
PUT /v1/atualizar.php?id=ID Atualizar DC-e
DELETE /v1/excluir.php?id=ID Excluir DC-e
POST /v1/transmitir.php?id=ID Transmitir DC-e
POST /v1/cancelar.php?id=ID Cancelar DC-e
GET /v1/download_xml.php?id=ID Download XML autorizado
GET /v1/download_xml_cancelado.php?id=ID Download XML cancelado
GET /v1/dace.php?id=ID Visualizar PDF DACE

Campos raiz: tpEmit e tpEmis

São dois campos diferentes e é fácil confundir pelo nome parecido. Um diz quem está emitindo, o outro diz em qual ambiente a emissão acontece. Os dois são enviados na raiz do JSON.

A diferença em uma linha

tpEmit = tipo de emitente (quem emite: marketplace, a própria empresa ou transportadora).
tpEmis = tipo de emissão (ambiente: produção ou homologação).

tpEmit — Tipo de emitente

Define o cenário da emissão e quais objetos são esperados no corpo da requisição.

ValorEmitenteQuando utilizar
1MarketplaceVenda realizada através de marketplace (Mercado Livre, Shopee, Amazon, Magalu, Americanas). Exige o objeto remetente com o vendedor parceiro.
2Emissor PróprioA própria empresa emissora está emitindo diretamente a DC-e. Não exige remetente.
3TransportadoraOperações de transporte. Exige remetente e destinatario.

tpEmis — Tipo de emissão (ambiente)

Define se o documento vai para o ambiente de produção, com validade fiscal, ou para o ambiente de testes.

ValorAmbienteEfeito
1ProduçãoDocumento com validade fiscal. Use apenas quando a integração já estiver homologada.
2HomologaçãoAmbiente de testes, sem validade fiscal. Use durante o desenvolvimento da integração.
Cuidado ao virar a chave

Todos os exemplos desta documentação usam "tpEmis": 1 (produção). Durante o desenvolvimento, troque para 2 para não gerar documentos fiscais válidos por engano nos seus testes.

Tipo 1 — Marketplace

Utilizado quando a venda foi realizada através de marketplace. Neste cenário o objeto remetente identifica o vendedor parceiro e o destinatario é o cliente final.

JSON completo

json
{
  "tpEmit": 1,
  "tpEmis": 1,
  "siteMarketplace": "mercadolivre.com.br",
  "destinatario": {
    "nome": "CLIENTE MARKETPLACE",
    "cpf_cnpj": "12345678901",
    "cep": "84010000",
    "logradouro": "Rua Marketplace",
    "numero": "500",
    "complemento": "Casa",
    "bairro": "Centro",
    "telefone": "42999999999",
    "email": "cliente.marketplace@teste.com"
  },
  "remetente": {
    "cpf_cnpj": "11222333000144",
    "nome": "LOJA PARCEIRA MARKETPLACE",
    "ie": "1234567890",
    "cep": "84010-120",
    "logradouro": "Rua XV de Novembro",
    "numero": "100",
    "complemento": "Sala 1",
    "bairro": "Centro",
    "telefone": "41999999999",
    "email": "parceiro@teste.com"
  },
  "transporte": {
    "modTrans": 2,
    "CNPJTransp": "55444777000188",
    "xNomeTransp": "TRANSPORTADORA MARKETPLACE"
  },
  "produtos": [
    {
      "descricao": "Notebook Gamer",
      "ncm": "84713012",
      "qtd": 1,
      "valor": 5500.00,
      "informacoes_adicionais": "Produto Marketplace"
    }
  ],
  "informacoes_adicionais": {
    "infAdFisco": "Venda Marketplace",
    "infCpl": "Pedido Marketplace #1000",
    "infAdMarketplace": "Mercado Livre Pedido 1000"
  }
}

Campos

CampoTipoDescrição
tpEmitintegerTipo de emitente — use 1 para marketplace
tpEmisintegerTipo de emissão — 1 produção, 2 homologação
siteMarketplacestringNome ou domínio do marketplace
destinatarioobjectDados do cliente final
remetenteobjectDados do vendedor parceiro
transporteobjectDados do transporte
produtosarrayLista de produtos
informacoes_adicionaisobjectInformações extras

Tipo 2 — Emissor próprio

Utilizado quando a própria empresa emissora está emitindo diretamente a DC-e. Não exige o objeto remetente.

JSON completo

json
{
  "tpEmit": 2,
  "tpEmis": 1,
  "destinatario": {
    "nome": "CLIENTE TESTE API",
    "cpf_cnpj": "12345678901",
    "cep": "84010000",
    "logradouro": "Rua Teste API",
    "numero": "100",
    "complemento": "Sala 1",
    "bairro": "Centro",
    "telefone": "42999999999",
    "email": "cliente@teste.com"
  },
  "transporte": {
    "modTrans": 2,
    "CNPJTransp": "12345678000199",
    "xNomeTransp": "TRANSPORTADORA TESTE"
  },
  "produtos": [
    {
      "descricao": "Produto Teste API",
      "ncm": "61091000",
      "qtd": 2,
      "valor": 150.50,
      "informacoes_adicionais": "Produto enviado via API"
    },
    {
      "descricao": "Segundo Produto",
      "ncm": "84713012",
      "qtd": 1,
      "valor": 999.90
    }
  ],
  "informacoes_adicionais": {
    "infAdFisco": "Teste API",
    "infCpl": "Documento emitido via API"
  }
}

Campos

CampoTipoDescrição
tpEmitintegerTipo de emitente — use 2 para emissor próprio
tpEmisintegerTipo de emissão — 1 produção, 2 homologação
destinatarioobjectDados do cliente
transporteobjectDados do transporte
produtosarrayProdutos do documento
informacoes_adicionaisobjectInformações extras

Tipo 3 — Transportadora

Utilizado para operações de transporte. Exige os objetos remetente e destinatario.

JSON completo

json
{
  "tpEmit": 3,
  "tpEmis": 1,
  "destinatario": {
    "nome": "DESTINATARIO TRANSPORTE",
    "cpf_cnpj": "98765432100",
    "cep": "84010-120",
    "logradouro": "Rua XV de Novembro",
    "numero": "100",
    "complemento": "Sala 1",
    "bairro": "Centro",
    "telefone": "43999999999",
    "email": "destinatario@teste.com"
  },
  "remetente": {
    "cpf_cnpj": "22333444000155",
    "nome": "EMPRESA REMETENTE",
    "ie": "99887766",
    "cep": "84010000",
    "logradouro": "Rua Remetente",
    "numero": "200",
    "complemento": "Barracao",
    "bairro": "Industrial",
    "telefone": "42988888888",
    "email": "remetente@teste.com"
  },
  "transporte": {
    "modTrans": 1
  },
  "produtos": [
    {
      "descricao": "Pecas Automotivas",
      "ncm": "87089990",
      "qtd": 10,
      "valor": 85.90,
      "informacoes_adicionais": "Carga fracionada"
    },
    {
      "descricao": "Filtro de Oleo",
      "ncm": "84212300",
      "qtd": 5,
      "valor": 35.00
    }
  ],
  "informacoes_adicionais": {
    "infAdFisco": "Transporte rodoviario",
    "infCpl": "Entrega prevista em 24h"
  }
}

Campos

CampoTipoDescrição
tpEmitintegerTipo de emitente — use 3 para transportadora
tpEmisintegerTipo de emissão — 1 produção, 2 homologação
remetenteobjectEmpresa remetente
destinatarioobjectDestinatário da carga
transporteobjectDados do transporte
produtosarrayItens transportados

Objeto destinatario

CampoTipoObrigatórioDescrição
nomestringSimNome do cliente
cpf_cnpjstringSimCPF ou CNPJ
cepstringSimCEP
logradourostringSimRua
numerostringSimNúmero
complementostringNãoComplemento
bairrostringSimBairro
telefonestringNãoTelefone
emailstringNãoE-mail

Objeto remetente

CampoTipoObrigatórioDescrição
cpf_cnpjstringSimCPF/CNPJ do remetente
nomestringSimNome do remetente
iestringNãoInscrição estadual
cepstringSimCEP
logradourostringSimRua
numerostringSimNúmero
complementostringNãoComplemento
bairrostringSimBairro
telefonestringNãoTelefone
emailstringNãoE-mail

Objeto transporte

CampoTipoObrigatórioDescrição
modTransintegerSimModalidade de transporte
CNPJTranspstringNãoCNPJ da transportadora
xNomeTranspstringNãoNome da transportadora

Objeto produtos

Array de objetos. Cada item representa um produto do documento.

CampoTipoObrigatórioDescrição
descricaostringSimDescrição do produto
ncmstringSimCódigo NCM
qtddecimalSimQuantidade
valordecimalSimValor unitário
informacoes_adicionaisstringNãoInformação extra do item

Objeto informacoes_adicionais

CampoTipoObrigatórioDescrição
infAdFiscostringNãoInformação fiscal
infCplstringNãoInformação complementar
infAdMarketplacestringNãoInformação de marketplace

Criar DC-e

POST/v1/criar.php

Headers

http
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Response de sucesso

json
{
  "success": true,
  "id": 33098,
  "status": "PENDENTE",
  "mensagem": "DC-e criada com sucesso"
}

Consultar DC-e

GET/v1/consultar.php?id=33098

Response

json
{
  "success": true,
  "data": {
    "dce": {
      "id": "33098",
      "status": "PENDENTE",
      "numero": "37",
      "serie": "1",
      "tpEmit": "1",
      "tpEmis": "1",
      "dhEmi": "2026-05-26 21:58:54"
    }
  }
}

Atualizar DC-e

PUT/v1/atualizar.php?id=33098
O PUT exige o JSON completo atualizado

Não envie apenas os campos alterados. O fluxo correto é:

  1. Consultar a DC-e
  2. Copiar o JSON retornado
  3. Alterar os campos desejados
  4. Enviar novamente no PUT

Exemplo de atualização

json
{
  "tpEmit": 2,
  "tpEmis": 1,
  "destinatario": {
    "nome": "CLIENTE ALTERADO",
    "cpf_cnpj": "12345678901"
  },
  "produtos": [
    {
      "descricao": "Produto Atualizado",
      "ncm": "61091000",
      "qtd": 5,
      "valor": 250.00
    }
  ]
}

Transmitir DC-e

POST/v1/transmitir.php?id=33098

O endpoint suporta dois modos de certificado digital: o certificado salvo no PortalDCE ou um certificado temporário enviado via API em Base64.

Usando o certificado salvo no PortalDCE

Quando o emitente já possui certificado configurado, não é necessário enviar certificado no body:

json
{}

Usando certificado temporário

json
{
  "certificado": {
    "arquivo_base64": "MIIK....",
    "senha": "123456"
  }
}
Observações sobre o certificado
  • O certificado temporário deve ser enviado em Base64
  • Deve estar no formato A1 (.pfx)
  • A senha do certificado é obrigatória
  • O certificado enviado via API é utilizado apenas na requisição atual
  • O certificado não é salvo no PortalDCE
  • Se nenhum certificado for enviado, o sistema utiliza automaticamente o certificado salvo do emitente

Response de sucesso

json
{
  "success": true,
  "status": "autorizado",
  "id": "33098",
  "chave": "41260511496275000184990010000000371205269649",
  "protocolo": "1412600003762188"
}

Cancelar DC-e

POST/v1/cancelar.php?id=33098

Assim como a transmissão, aceita certificado salvo ou temporário.

Usando o certificado salvo

json
{
  "motivo": "Erro na emissao da dce"
}

Usando certificado temporário

json
{
  "motivo": "Erro na emissao da dce",
  "certificado": {
    "arquivo_base64": "MIIK....",
    "senha": "123456"
  }
}

Response de sucesso

json
{
  "status": "cancelado",
  "id": "33098",
  "protocolo": "1412600003762646"
}

XML e DACE

XML autorizado

GET/v1/download_xml.php?id=33098

XML cancelado

GET/v1/download_xml_cancelado.php?id=33098

DACE em PDF

GET/v1/dace.php?id=33098

Status HTTP

CódigoDescrição
200Sucesso
400Requisição inválida
401Não autorizado
404Não encontrado
405Método inválido
500Erro interno

Fluxo recomendado

1
Gerar token

POST /oauth/token.php

2
Criar DC-e

POST /v1/criar.php

3
Consultar

GET /v1/consultar.php?id=33098

4
Atualizar (opcional)

PUT /v1/atualizar.php?id=33098

5
Transmitir

POST /v1/transmitir.php?id=33098

6
Visualizar DACE

GET /v1/dace.php?id=33098

7
Download XML

GET /v1/download_xml.php?id=33098

Postman

CampoTipoDescrição
AuthorizationAuth TypeBearer Token
TokenstringCole o ACCESS_TOKEN
BodyrawSelecione raw e o formato JSON

Observações importantes

  • Todos os endpoints retornam JSON
  • IDs devem ser enviados via query string
  • Utilize sempre UTF-8
  • O token deve ser enviado em todos os endpoints protegidos
  • Salve sempre o novo refresh_token retornado
  • Após a autorização da DC-e o sistema bloqueia alterações
  • tpEmit identifica o emitente: 1 marketplace, 2 emissor próprio, 3 transportadora
  • tpEmis identifica o ambiente: 1 produção, 2 homologação

Pronto para integrar?

Solicite o seu client_id e client_secret e comece a emitir DC-e direto do seu sistema.

Solicitar credenciais

Central DC-e