DC-e
Issue DC-e
Accepts a Declaração de Conteúdo Eletrônica (model 99) and authorizes it asynchronously with SEFAZ.
/openapi/v2/empresas/{empresaId}/dc-etoken, timestamp and sign signature headers, see Authentication.Acceptance returns HTTP 200 with no body. Resubmitting the same id: an identical message fingerprint reuses the original task (idempotent), a different fingerprint returns 10019030, and a previous terminal failure reopens the task with the new message. Results are obtained through the query or the dce.authorized / dce.rejected webhooks (see DC-e). The company must be approved with a usable certificate and emissaoDCe configured. Enum strings are case-insensitive.
Path parameters
empresaId* | string | Issuing company identifier |
* Required field
Request body
id* | string | Request identifier |
ambiente* | string | Environment |
dataEmissao | string | Issue time |
*required for Marketplace companies | object | Sender |
* | object | Recipient |
* | array | Declared items |
* | object | Transport |
| array | XML download authorizations |
informacoesAdicionais | string | Marketplace remark |
informacoesAdicionaisFisco | string | Tax authority remark |
informacoesAdicionaisEmitente | string | Issuer remark |
| array | Marketplace custom entries |
* Required field
Pendente and is numbered and sent to SEFAZ asynchronously. Follow up through the query or the webhook.No response body
The DC-e issuer type set at company registration decides how remetente is filled. Marketplace issues on behalf of a seller; OwnIssuer issues in its own name; Carrier cannot issue yet and returns 10019013.
Marketplace issuing for a seller
The seller goes in remetente with document and address; the CNPJ in the access key remains the Marketplace company.
"remetente": {"tipoPessoa": "F", "nome": "JOAO DA SILVA", "cpfCnpj": "12345678909", "telefone": "41999990000","endereco": { "uf": "PR", "cidade": "4106902", "logradouro": "RUA XV DE NOVEMBRO", "numero": "100", "bairro": "CENTRO", "cep": "80020310" }}
* | object | Sender |
* Required field
Company issuing in its own name
Do not send remetente: the sender and the origin address come from the company registration. If you send remetente.cpfCnpj, it must be the company own CNPJ, otherwise 10019019.
{"id": "DCe-000012334","ambiente": "Homologacao","destinatario": {"tipoPessoa": "F", "nome": "MARIA OLIVEIRA", "cpfCnpj": "11144477735","endereco": { "uf": "SP", "cidade": "3550308", "logradouro": "AVENIDA PAULISTA", "numero": "1000", "bairro": "BELA VISTA", "cep": "01310100" }},"itens": [ { "descricao": "CARTEIRA", "ncm": "42023100", "quantidade": 1, "valorUnitario": 40.00 } ],"transporte": { "modalidade": "PorContaPropria" }}
modalidade is required. cnpjTransportadora only makes sense with PorEmpresaTransportadora.
Post office or own means
"transporte": { "modalidade": "PelosCorreios" }
* | object | Transport |
* Required field
Contracted carrier
"transporte": { "modalidade": "PorEmpresaTransportadora", "cnpjTransportadora": "14422279000106" }
* | object | Transport |
* Required field
The line total is quantity × unit price rounded to 2 decimals; the document total is the sum of the lines. Both are computed by the platform and are not sent in the request. Text fields are sanitized (accents stripped, control characters replaced by spaces, whitespace collapsed) before length validation.
Checks performed at acceptance (no numbering, no SEFAZ call, direct 400): company issuable with a usable certificate and DC-e configured; ambiente matches the company; document lengths and check digits; municipality IBGE code consistent with the UF; 8-digit cep; non-empty itens with valid quantity, unit price and NCM; list size limits; text length.
SEFAZ rejections during issuance are not HTTP errors: they surface as query status Negada and the dce.rejected webhook. The full state machine is in DC-e.
ambienteIssue environment
| Values | Meaning |
|---|---|
| Homologacao | SEFAZ test environment; the document has no legal effect |
| Producao | Official environment |
remetente.tipoPessoaPerson type
Also applies to destinatario.tipoPessoa.
| Values | Meaning |
|---|---|
| F | Individual; 11-digit cpfCnpj |
| J | Company; 14-digit cpfCnpj |
transporte.modalidadeTransport mode
| Values | Meaning |
|---|---|
| PelosCorreios | Sent through the post office |
| PorContaPropria | Carried by the sender own means |
| PorEmpresaTransportadora | Carried by a carrier company; give cnpjTransportadora |
| Code | HTTP | |
|---|---|---|
| 10003000 | 404 | empresaId not found. |
| 10019012 | 400 | Company not configured for DC-e (missing tipoEmitente / model 99 series / Marketplace site). Send emissaoDCe at registration or through an update with id. |
| 10019010 | 400 | ambiente differs from the company's current environment (e.g. Producao sent before operations switched the company to production). Submit for the company's current environment. |
| 10019014 | 400 | Marketplace company without remetente. Add the sender. |
| 10019015 | 400 | remetente.endereco missing. Add the sender address. |
| 10019016 | 400 | Brazilian sender without cpfCnpj. Add the sender document. |
| 10019004 | 400 | Company cannot issue (not approved / certificate not ready). Wait for approval / link the certificate. |
| 10019017 | 400 | Brazilian recipient without cpfCnpj. Add the recipient document. |
| 10019011 | 400 | Municipality IBGE code not found or inconsistent with uf. Check cidade / uf. |
| 10019005 | 400 | Concurrent duplicate request. Retry later. |
| 10019006 | 400 | Too many pending tasks for the CNPJ. Retry later. |
| 10019007 | 400 | Number series unresolved (several enabled series). Ask operations to consolidate the series. |
| 10019013 | 400 | Issuer type Carrier not supported for issuance yet. Use a Marketplace / OwnIssuer company. |
| 10019018 | 400 | Invalid item (NCM length, quantity ≤ 0, negative unit price). Fix per mensagem. |
| 10019019 | 400 | Invalid enum or format (mensagem names the field: tipoPessoa, modalidade, dataEmissao, documents, phone, e-mail, own-issuer remetente differing from the company, ...). Fix per mensagem. |
| 10019020 | 400 | Invalid carrier CNPJ. Fix cnpjTransportadora. |
| 10019021 | 400 | Additional information too long. Shorten the text. |
| 10019022 | 400 | Invalid autorizacaoDownloadXml count or document; includes the issuer's own CNPJ; repeated document. Fix the list. |
| 10019030 | 400 | Same id with a different message. Use a new id or resend the original message. |
| 10019031 | 400 | Production: an active / authorized document already exists for the id. Query the original. |
| 10019048 | 400 | dataEmissao outside the allowed window (more than 5 minutes ahead or more than 30 days back; mensagem carries the current limits). Use the current time or omit dataEmissao. |
| 10001001 | 400 | Request field validation failed (one entry per field). Fix per mensagem. |