Emitir Nota Fiscal pela API — do zero, sem complicação
Um guia simples, com fotos das telas, para quem vai usar a Plataforma de APIs da DotCompany para emitir NF-e direto do seu sistema. Você configura uma vez no painel e depois emite quantas notas quiser, pagando só pelo que usar.
O que você precisa saber primeiro
Onde fica o painel
erp.dotcompany.com.br/api-devComo você pagaCréditos pré-pagos (sem mensalidade)
Custo de cada NF-e8 créditos
Comece sempre porHomologação (teste, sem valor fiscal)
O caminho é simples: 1) cadastra o certificado da sua empresa → 2) completa o perfil fiscal → 3) gera a sua chave → 4) compra créditos → 5) emite as notas pela API. As 4 primeiras telas são uma vez só.
★Comece por aqui — 6 ideias que se repetem o tempo todo›
São 6 ideias que aparecem em quase todas as telas. Entendendo elas agora, todo o resto fica fácil. Leia com calma — leva 3 minutos.
🧩
API é o seu sistema “conversando” com o nosso. Em vez de abrir uma tela e digitar a nota à mão, o seu programa manda os dados da nota para a DotCompany e nós emitimos na SEFAZ por você. Tudo automático.
📄
Certificado A1 é a “identidade digital” da empresa. É um arquivo
.pfx com senha que prova que a nota foi você quem emitiu. Você compra ele na sua contadora/certificadora. Sem ele, a SEFAZ não aceita a nota.🔑
Chave de API é a sua senha de acesso à plataforma. Toda chamada que o seu sistema faz leva essa chave junto, para nós sabermos que é você. Existe a de teste (
dc_test_) e a de verdade (dc_live_).🧪
Homologação = ensaio. Produção = pra valer. Em homologação você emite notas de teste, que não têm valor fiscal — serve para conferir tudo sem risco. Quando estiver certo, vira para produção.
🪙
Créditos são fichas pré-pagas. Você compra um pacote e cada coisa que faz “gasta” fichas: emitir uma NF-e custa 8 créditos, baixar o PDF custa 1, consultar é de graça. Você só paga de verdade quando a nota é autorizada — se a SEFAZ recusar, o crédito volta.
🛡️
“Chave de idempotência” evita nota duplicada. É um codigozinho que você inventa para cada pedido. Se mandar a mesma nota duas vezes por engano (a internet caiu, você reenviou), o sistema devolve a mesma nota em vez de emitir e cobrar de novo.
📌 O que é o painel
/api-dev? É a parte visual da plataforma, onde você configura tudo clicando (sem programar): cadastra o certificado, completa o perfil, cria a chave e compra créditos. A emissão em si é feita pelo seu sistema, pela API. Este tutorial mostra as 5 telas do painel + como emitir a nota no fim.As telas do painel — configuração (uma vez só)
1O Painel — sua visão geral (saldo, uso e atalhos)›
É a primeira tela que você vê ao entrar em /api-dev. Aqui você acompanha quanto de crédito ainda tem, quanto já usou, e tem os atalhos para começar. Pense nela como o “painel do carro” da sua conta de API.
- O quadro de boas-vindas com os 3 primeiros passos pra quem está começando.
- O atalho “Crie e teste sua chave” — o ponto de partida.
- Os filtros e cartões de uso: veja o consumo por período, CNPJ, ambiente ou chave.
🔊 Ouvir esta seção
O que tem nesta tela
- No topo, o Consumo da API: quanto você gastou no período (pode trocar entre Hoje, 7 dias, 30 dias e 90 dias).
- O saldo disponível em destaque: quantos créditos ainda restam e o valor em reais.
- Um quadro de boas-vindas com 3 passos para quem está começando: criar a chave, fazer a 1ª chamada e comprar créditos.
- Embaixo, cartões com os números de uso (notas emitidas, consultas, etc.) e filtros para olhar por CNPJ, ambiente ou chave.
💡 Primeira vez aqui? Não precisa entender tudo de cara. Siga os 3 passos do quadro de boas-vindas, nesta ordem: 1) crie a chave, 2) cadastre o certificado e o perfil, 3) compre créditos. As próximas seções deste tutorial seguem exatamente esse caminho.
2Cadastrar a empresa emissora (subir o certificado A1)›
Aqui você envia o certificado digital A1 (arquivo .pfx) + a senha da empresa que vai emitir as notas. É o que prova para a SEFAZ que a nota é sua. Você faz isso uma vez por CNPJ.
- Arraste ou clique para enviar o arquivo .pfx do certificado.
- Digite a senha do certificado e, se quiser, um apelido.
- Escolha o ambiente: Homologação (teste) ou Produção (pra valer).
🔊 Ouvir esta seção
Passo a passo
- Clique para escolher o arquivo .pfx do seu computador (ou arraste para dentro do quadro pontilhado).
- Digite a senha do certificado — a mesma que a sua contadora/certificadora te passou quando você comprou o A1.
- (Opcional) Dê um apelido para reconhecer fácil, ex.: “Loja Matriz”.
- Escolha o ambiente: Homologação para testar (recomendado no começo) ou Produção para valer.
- Salve. O sistema lê sozinho o CNPJ, a razão social e a validade direto de dentro do certificado — você não precisa digitar nada disso.
Mais abaixo na tela aparece a lista de emissores cadastrados, com a opção de trocar o certificado (quando ele vencer) ou abrir os dados do perfil (próxima seção).
⚠️ O certificado A1 vence (geralmente em 1 ano). Quando faltar pouco para vencer, compre o novo com a sua certificadora e use o botão “Trocar certificado” aqui mesmo. Sem certificado válido, a emissão para.
📌 Não tem o .pfx em mãos? O certificado A1 é comprado em certificadoras (Serasa, Soluti, Certisign, etc.), normalmente pela sua contabilidade. É o mesmo arquivo que você já usa para emitir notas em outros lugares.
3Completar o perfil fiscal da emissora›
Cada empresa precisa de alguns dados fiscais antes de emitir. Sem isso, a nota é recusada com uma mensagem dizendo o que falta. É um formulário rápido, e o sistema já preenche boa parte para você.
- “Buscar dados por CNPJ”: preenche endereço e dados pela Receita automaticamente.
- A Inscrição Estadual e o endereço completo da empresa.
- O regime tributário (Simples, Lucro Presumido/Real) — confira com a contabilidade.
🔊 Ouvir esta seção
O que preencher
- Inscrição Estadual (IE) — o registro da empresa na Secretaria da Fazenda do seu estado. Se for isenta, há uma opção marcando “Isento”.
- Endereço completo — logradouro, número, bairro, cidade, UF e CEP.
- Regime tributário — Simples Nacional, Lucro Presumido, Lucro Real ou MEI (escolha o da sua empresa).
- Série da NF-e — normalmente “1” (na dúvida, deixe 1).
💡 Atalho que economiza tempo: clique em “Buscar dados por CNPJ” no alto da tela. O sistema busca o endereço e os dados na Receita e preenche os campos para você — depois é só conferir e salvar.
⚠️ Confira com calma o regime tributário. Ele muda o cálculo dos impostos da nota. Se tiver dúvida, pergunte à sua contabilidade — esse é o campo que mais gera erro quando preenchido errado.
4Gerar a sua chave de API›
A chave é o que o seu sistema usa para entrar na plataforma e emitir. É como uma senha: você cria aqui, copia e guarda em lugar seguro. Cada chamada do seu sistema leva essa chave junto.
- O botão “Nova chave” para criar a sua chave de acesso.
- A chave criada, com o ambiente (Sandbox/Produção), as permissões e os botões Rotacionar/Revogar.
🔊 Ouvir esta seção
Passo a passo
- Clique em “Nova chave” (botão no canto superior direito).
- Escolha o ambiente: Sandbox (testes — gera uma chave
dc_test_…) ou Produção (geradc_live_…). - Marque as permissões. Para emitir NF-e, marque nfe:emit. As permissões de cadastro e consulta já vêm marcadas e são gratuitas.
- Confirme. Pronto: a chave aparece na lista, com os botões de Rotacionar (trocar o segredo) e Revogar (desligar) quando precisar.
⚠️ O segredo da chave aparece UMA única vez. Copie e guarde com segurança na hora (igual a uma senha). Se você perder, não dá para ver de novo — aí é só gerar uma chave nova. A chave tem o formato
dc_live_123.xxxxxxxx (produção) ou dc_test_123.xxxxxxxx (teste).📌 O prefixo precisa bater com o ambiente: chave
dc_test_ só funciona em teste e dc_live_ só em produção. Se misturar, dá o erro ENVIRONMENT_MISMATCH — é só usar a chave certa para o ambiente.5Comprar créditos (PIX ou Boleto)›
Créditos são as “fichas” pré-pagas que você gasta ao emitir. Aqui você escolhe um pacote e paga por PIX ou Boleto. Assim que o pagamento é confirmado, os créditos entram na sua conta automaticamente.
- Cada cartão é um pacote de créditos — quanto maior, melhor o preço por crédito.
- Pague por PIX (na hora) ou Boleto; os créditos entram sozinhos ao confirmar.
🔊 Ouvir esta seção
Como comprar
- Escolha o pacote que faz sentido para o seu volume (quanto maior o pacote, melhor o preço por crédito).
- Clique em PIX (cai na hora) ou Boleto (compensa em 1–2 dias úteis).
- Pague. Os créditos entram sozinhos quando o pagamento é confirmado — você acompanha o saldo no Painel (seção 1).
💡 Quanto custa cada coisa: emitir uma NF-e = 8 créditos; baixar o DANFE (PDF) = 1; cancelar uma nota = 2; consultar saldo e uso = grátis. E lembre: nota recusada pela SEFAZ não gasta crédito — o valor reservado volta para você.
Pondo para funcionar
6Emitir uma NF-e pela API (o coração de tudo)›
Com certificado, perfil, chave e créditos prontos, agora o seu sistema emite as notas sozinho. Esta parte é feita pelo seu programa (ou pela sua equipe de tecnologia) — abaixo está, em linguagem simples, o que acontece. Se você não programa, é só passar esta seção para quem cuida do seu sistema.
Comece sempre por homologação
Cadastre a emissora em Homologação e use uma chave dc_test_. Emita algumas notas de teste (elas não têm valor fiscal) e confira se está tudo certo. Quando estiver, vire para Produção com uma chave dc_live_ e emita de verdade.
Como o seu sistema emite uma nota
O seu sistema faz uma chamada para POST /api/v1/nfe levando a chave no cabeçalho e, no corpo, os dados da nota: o destinatário (nome, CPF/CNPJ, endereço) e os itens (descrição, NCM, CFOP, quantidade e valor). Custo: 8 créditos por nota autorizada.
📌 O que volta para você: se a SEFAZ autorizar, a resposta traz
autorizada: true, o número da nota, a chave de acesso e o protocolo. O crédito só é cobrado quando a nota é autorizada — se for recusada, o valor é estornado.💡 Sempre mande uma “chave de idempotência” (um código seu para cada pedido, ex.: o número do pedido de venda). Se a mesma nota for enviada duas vezes por engano, o sistema devolve a mesma nota em vez de duplicar e cobrar de novo.
Depois de emitir — o que mais dá para fazer pela API
| O que faz | Como | Custo |
|---|---|---|
| Emitir NF-e | POST /api/v1/nfe | 8 créditos |
| Baixar o DANFE (PDF) | POST /fiscal/nfe/danfe | 1 crédito |
| Cancelar uma nota | POST /fiscal/nfe/cancelar | 2 créditos |
| Ver status do serviço da SEFAZ | POST /fiscal/nfe/status | 1 crédito |
| Consultar saldo e uso | GET /api/v1/usage | grátis |
⚠️ Para cancelar, a justificativa precisa ter entre 15 e 255 caracteres (é uma exigência da SEFAZ). Ex.: “Cancelamento por erro no pedido do cliente”.
📌 Documentação completa para a sua equipe: os exemplos prontos de cada chamada (com o corpo da nota completo) estão no guia técnico que acompanha a sua conta. O painel também tem um “guia rápido” na tela de Chaves.
7Glossário — as palavras difíceis em português claro›
Sem decoreba. Sempre que bater uma dúvida com um termo, volte aqui.
- API — o jeito do seu sistema “falar” com o nosso automaticamente, sem ninguém digitar nota à mão.
- Certificado A1 (.pfx) — arquivo com senha que é a identidade digital da empresa; prova que a nota é sua.
- Chave de API — a senha de acesso do seu sistema à plataforma (
dc_test_= teste,dc_live_= produção). - Homologação / Sandbox — ambiente de ensaio; as notas não valem fiscalmente, serve para testar sem risco.
- Produção — ambiente real; as notas valem de verdade.
- Créditos — fichas pré-pagas; cada ação gasta uma quantidade (emitir NF-e = 8).
- NF-e — Nota Fiscal Eletrônica de produto (modelo 55).
- DANFE — o PDF da nota, aquele papel/arquivo que você manda para o cliente.
- NCM — o código que classifica o produto (define os impostos).
- CFOP — o código que diz o tipo da operação (venda, devolução, etc.).
- Chave de idempotência — código seu por pedido; impede emitir/cobrar a mesma nota duas vezes.
- SEFAZ — a Secretaria da Fazenda, o órgão do governo que autoriza a nota.