FAQ técnica da API
Atualizado em
Nesta página
- Emissão
- Por que a emissão responde 202 e não a nota pronta?
- Quanto tempo leva para autorizar?
- Posso emitir várias notas numa requisição?
- A nota pode ter vários serviços?
- Duplicidade e falhas
- Meu sistema deu timeout. Posso reenviar?
- E se a Sefin der timeout depois que a nota já saiu?
- Recebi o mesmo webhook duas vezes. É bug?
- Rejeições
- Como sei por que a nota foi rejeitada?
- Uma nota rejeitada consome a cota do plano?
- Posso reenviar uma nota rejeitada?
- Sandbox e ambientes
- Qual a diferença entre sandbox e homologação?
- A URL muda entre teste e produção?
- Dados de teste aparecem no painel?
- Certificado
- Preciso enviar o certificado pela API?
- Posso usar o certificado do meu escritório contábil para emitir pelos clientes?
- O que acontece quando o certificado vence?
- Plano e limites
- A API custa à parte?
- O que acontece se eu passar do rate limit?
- E se a empresa ficar inadimplente?
- Abrangência
- A Emitra emite em qualquer município?
- A Emitra calcula o IBS/CBS?
- Próximos passos
Perguntas que aparecem em quase toda integração.
Emissão#
Por que a emissão responde 202 e não a nota pronta?#
A emissão é assíncrona do nosso lado. O POST /integracao/nfse valida o pedido, reserva o número da DPS, coloca na fila e responde 202 com o id e o status queued. Um worker assina a DPS e envia à Sefin. Acompanhe pelo webhook nfse.authorized / nfse.rejected ou consultando GET /integracao/nfse/{id}. Veja a referência de NFS-e.
Quanto tempo leva para autorizar?#
Normalmente segundos, mas depende da Sefin Nacional, que consulta outros serviços durante a validação. A Emitra não controla esse tempo. Se houver instabilidade, a nota fica em processamento e é tentada de novo automaticamente.
Posso emitir várias notas numa requisição?#
Não. A Sefin Nacional recebe uma DPS por requisição, e a API segue o mesmo modelo: uma nota por POST. Para volume, faça requisições em paralelo dentro do seu rate limit ou use a emissão em lote por planilha no painel.
A nota pode ter vários serviços?#
A DPS do Padrão Nacional tem um código de tributação por nota. Serviços com códigos diferentes precisam de notas separadas.
Duplicidade e falhas#
Meu sistema deu timeout. Posso reenviar?#
Pode, com a mesma Idempotency-Key e o mesmo corpo. A Emitra devolve a resposta da primeira requisição, sem criar outra nota. Se você mudar o corpo e mantiver a chave, recebe 422 IDEMPOTENCY_KEY_REUSED. As chaves valem por 24 horas. Veja Idempotência.
E se a Sefin der timeout depois que a nota já saiu?#
A Emitra nunca gera um número novo nesse caso. Antes de reenviar, ela consulta a Sefin pelo Id da DPS para descobrir se a nota já existe. Se existir, recupera a nota. O status fica em processamento até a confirmação.
Recebi o mesmo webhook duas vezes. É bug?#
Não. A entrega é "pelo menos uma vez". Deduplique pelo id do evento. Veja Retries e boas práticas.
Rejeições#
Como sei por que a nota foi rejeitada?#
O recurso nfse com status rejected traz o objeto rejeicao com o código oficial da Sefin, a mensagem original, um título e uma orientação em português. O mapa dos códigos mais comuns está em Erros.
Uma nota rejeitada consome a cota do plano?#
Não. A cota é contada na autorização.
Posso reenviar uma nota rejeitada?#
Corrija os dados (no cadastro do tomador, do item ou na configuração fiscal) e emita de novo. Rejeição de regra de negócio não é tentada de novo automaticamente, porque o resultado seria o mesmo.
Sandbox e ambientes#
Qual a diferença entre sandbox e homologação?#
O sandbox é da Emitra: chaves emt_test_, respostas simuladas, sem certificado e sem consumir cota. A homologação (produção restrita) é da Sefin: exige certificado real, valida as regras de verdade e gera notas sem valor fiscal. Veja Ambientes e URLs base.
A URL muda entre teste e produção?#
Não. A URL base é a mesma. O ambiente vem da chave que você usa.
Dados de teste aparecem no painel?#
Não, exceto com o filtro "dados de teste". Eles são apagados após 30 dias.
Certificado#
Preciso enviar o certificado pela API?#
Não. O certificado A1 é enviado só pelo painel, por um owner ou admin. A API nunca recebe nem devolve o certificado. Veja Certificado A1.
Posso usar o certificado do meu escritório contábil para emitir pelos clientes?#
Não. A Sefin exige que a DPS seja assinada com o certificado do próprio prestador (erro E0718). Cada empresa precisa do seu A1.
O que acontece quando o certificado vence?#
A emissão para. Você recebe avisos com 30, 15, 7 e 1 dia de antecedência, inclusive pelo webhook certificate.expiring.
Plano e limites#
A API custa à parte?#
Não. A API está inclusa em todos os planos. O plano define o limite de chamadas por minuto, e as notas emitidas pela API contam na mesma cota mensal das emitidas pelo painel. Veja Limites.
O que acontece se eu passar do rate limit?#
Você recebe 429 com o header Retry-After. Espere o tempo indicado e tente de novo. Veja Rate limits.
E se a empresa ficar inadimplente?#
Emissão, cancelamento e substituição respondem 403 TENANT_INADIMPLENTE depois da carência. Consultas, listagens e downloads de XML e PDF continuam funcionando.
Abrangência#
A Emitra emite em qualquer município?#
Só em municípios que usam o Sistema Nacional NFS-e. Municípios com emissor próprio, fora do Sistema Nacional, não são atendidos (a Sefin recusa com E0037). A Emitra não emite NF-e nem NFC-e.
A Emitra calcula o IBS/CBS?#
A Emitra envia a classificação do IBS/CBS cadastrada no serviço. Os valores são calculados e devolvidos pela Sefin.