Como a API do Guidis DFe funciona

Os ambientes

A homologação (https://api-homologacao.guidisdfe.com.br) não tem valor fiscal, e a produção (https://api.guidisdfe.com.br) tem. São instâncias separadas: a empresa, o certificado, a numeração e os documentos de uma não aparecem na outra.

O plano Teste emite só na homologação, e a homologação não conta franquia.

A chave de API e o token

A chave de API se cria no portal e vale num ambiente só. O seu sistema a troca por um token de acesso, que vence em cerca de 15 minutos, no hostname do mesmo ambiente, e usa o token no cabeçalho Authorization de cada chamada.

Os documentos e os eventos

NF-e, NFC-e, CT-e, CT-e OS, GTVe, MDF-e e NFS-e do padrão nacional usam o mesmo caminho: uma empresa por CNPJ, o certificado dela, e as rotas do documento sob /v1/empresas/{empresaCodigo}.

Os eventos têm rota própria em cada documento: o cancelamento, a carta de correção, a inutilização da NF-e e da NFC-e, o encerramento do MDF-e, o comprovante e o insucesso de entrega do CT-e, e o desacordo do tomador. O PDF sai pelo documento: o DANFE, o DACTE, o DAMDFE e o DANFSe.

A emissão assíncrona e o pedido repetido

O pedido aceito responde 202 antes da SEFAZ, com o documento no corpo. O status passa por aceito, preparando e transmitindo, e termina em autorizado, rejeitado, denegado ou numa falha. O documento cancelado continua autorizado, e o cancelamento aparece num campo próprio.

O pedido idêntico a um aceito antes devolve o documento que já existe, com o mesmo número: repetir depois de um timeout é seguro. A referencia é o identificador do seu sistema, e o documento se busca por ela.

Os erros e a base legal

Toda recusa sai no mesmo envelope, com um codigo_erro estável, que é o que o seu sistema deve ler. A recusa diz quem recusa (norma, quando qualquer emissor teria a mesma recusa, ou produto), cita a norma, o campo, a regra e a rejeição da SEFAZ quando a recusa é de norma, e lista os valores aceitos quando o campo tem domínio fechado.

O webhook

O webhook avisa o desfecho do documento, dos eventos, da inutilização e da guia, num POST assinado com HMAC-SHA256 pelo segredo do destino. A entrega que falha é repetida e pode ser reenviada à mão. O webhook avisa; quem confirma é a consulta, e a conciliação se faz pela listagem por período.

O plano e o consumo

O consumo conta o documento autorizado na produção, com os eventos dele inclusos. A NFC-e vale meio documento, e a GTVe não conta. A rota do plano mostra o plano, os limites e o consumo do mês.

Os guias

• A primeira NF-e na homologação: Da conta grátis à primeira NF-e autorizada na homologação da SEFAZ, sem valor fiscal, com o portal e duas chamadas à API.

A referência completa

Cada rota, com os campos do pedido, a resposta, os erros e o pedido de exemplo. Para testar as chamadas, a documentação da própria API, na homologação.

• Abrir a referência da API
• Testar na homologação