A primeira NF-e na homologação

Este guia leva o seu sistema da conta grátis à primeira NF-e autorizada na homologação, onde o documento não tem valor fiscal. A conta nasce no plano Teste, que emite só na homologação, sem cartão. O detalhe de cada rota, com os campos e os erros, está na referência da API.

Antes de começar

• O CNPJ da empresa que vai emitir e o certificado A1 dela, o arquivo .pfx e a senha. A homologação usa o mesmo certificado da produção.
• Um sistema que faça chamadas HTTP com JSON. Os exemplos abaixo usam o curl.

1. Crie a conta e confirme o e-mail

Crie a conta no portal e abra o link que chega no seu e-mail. Na tela inicial do portal, o passo a passo do ambiente mostra o que falta, e cada passo se marca sozinho quando é feito.

2. Cadastre a empresa e o certificado

No topo do portal, deixe o ambiente em Homologação, e em Empresas cadastre a empresa emitente pelo CNPJ. Na página dela, envie o certificado A1 (o arquivo e a senha), que passa a ser o ativo. O arquivo e a senha ficam cifrados, com a chave fora do banco.

A homologação e a produção são separadas: a empresa, o certificado, a numeração e os documentos de uma não aparecem na outra.

3. Crie a chave de API

Em Chaves de API, crie a chave da homologação e guarde-a: ela aparece uma vez só. A chave vale num ambiente só, e o seu sistema a troca por um token de acesso, que vence em cerca de 15 minutos:

curl -X POST https://api-homologacao.guidisdfe.com.br/api/integracao/token \
  -H "Authorization: Bearer <chave de API>"

Use o access_token da resposta no cabeçalho Authorization: Bearer das chamadas seguintes, e troque de novo antes de vencer.

4. Envie a NF-e

O pedido é o JSON da nota, com o ambiente igual a homologacao e a data_emissao no instante atual, com o fuso. A referência da API traz um pedido de exemplo com dados fictícios; troque a data antes de enviar.

curl -X POST https://api-homologacao.guidisdfe.com.br/v1/empresas/<empresaCodigo>/nfe \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d @pedido.json

O pedido aceito responde 202, com o documento no corpo e o endereço dele no Location. A transmissão à SEFAZ acontece depois. Se a resposta não chegar, repita o mesmo pedido: o pedido idêntico a um aceito antes devolve o documento que já existe, com o mesmo número.

O pedido fora da norma é recusado antes da SEFAZ, com o código do erro, a regra e a rejeição que ela daria, e os valores aceitos quando o campo tem domínio fechado.

5. Acompanhe e baixe

Consulte o documento pelo endereço do Location até o status final (autorizado, rejeitado, denegado ou uma falha), ou configure o webhook, que avisa o desfecho num POST assinado. Com a nota autorizada, baixe o XML em /xml e o DANFE em /danfe. O documento também aparece no portal, em Documentos, com o XML e o PDF.

Depois da homologação

A emissão na produção começa num plano pago, com uma chave de produção e o hostname https://api.guidisdfe.com.br. A empresa e o certificado se cadastram de novo na produção, que é outra instância.