Conceitos: DPS, NFS-e, ambientes, cota e papéis
Atualizado em
Nesta página
Cinco conceitos explicam quase tudo o que acontece na Emitra: a DPS, a NFS-e, os ambientes, a cota e os papéis. Vale ler esta página antes de integrar.
DPS × NFS-e#
A DPS (Declaração de Prestação de Serviço) é o que você declara: quem prestou, para quem, qual serviço, quanto e quando. A Emitra monta a DPS, assina com o certificado A1 da empresa e envia à Sefin Nacional.
A NFS-e é o que a Sefin devolve quando aceita a DPS. Ela tem número próprio (gerado pela Sefin), uma chave de acesso de 50 posições e é assinada pela Sefin. A NFS-e contém a DPS original.
| DPS | NFS-e | |
|---|---|---|
| Quem gera | A Emitra, em nome da sua empresa | A Sefin Nacional |
| Identificador | Id da DPS, 45 posições (DPS + município + CNPJ + série + número) |
Chave de acesso, 50 posições |
| Número | nDPS, sequencial por série, controlado pela Emitra |
nNFSe, sequencial por emitente, controlado pela Sefin |
| Valor fiscal | Nenhum sozinha | É o documento fiscal |
Exemplo com os dados fictícios usados nesta documentação:
Id da DPS: DPS355030821122233300018100900000000000000042
Chave de acesso: 35503082211222333000181000000000004226114829130573Ciclo de vida de uma emissão#
- queued: a DPS foi aceita pela Emitra, o número foi reservado e ela está na fila.
- signed: o XML foi montado, validado contra o XSD e assinado.
- sent: a DPS foi transmitida à Sefin.
- authorized: a Sefin gerou a NFS-e. rejected: a Sefin recusou por regra de negócio. error: falha técnica (rede, indisponibilidade); a Emitra tenta de novo sozinha.
- Depois de autorizada, a nota pode ficar canceled, replaced ou cancel_under_analysis (cancelamento fora do prazo, aguardando o município).
A Sefin responde de forma síncrona, mas a Emitra processa a emissão em fila. Por isso a API responde 202 Accepted e você acompanha o status por consulta ou por webhook.
Ambientes#
| Ambiente | Para que serve | Valor fiscal | Certificado |
|---|---|---|---|
| Sandbox da Emitra | Testar a integração sem falar com a Sefin. Respostas determinísticas por números mágicos | Não | Não precisa |
| Produção restrita (homologação da Sefin) | Testar com a Sefin de verdade, com regras reais | Não | A1 real da empresa |
| Produção | Emitir notas válidas | Sim | A1 real da empresa |
O ambiente da Sefin (produção restrita ou produção) é definido na configuração fiscal da empresa. Na API, uma chave emt_test_ usa o sandbox; uma chave emt_live_ usa o ambiente configurado na empresa. Detalhes em Ambientes e URLs base.
Cota#
Cada plano tem um limite mensal de notas. A cota é consumida na autorização, não no envio: uma DPS rejeitada não conta.
- Notas emitidas pelo painel, por recorrência, por lote, pela API e pelo gatilho do Asaas contam igual.
- Notas do sandbox não contam.
- Ao chegar no limite, a emissão segue a regra do plano: cobra excedente ou bloqueia com o erro
COTA_EXCEDIDA.
Com a assinatura em atraso além da carência, emissão, cancelamento e substituição ficam bloqueados (TENANT_INADIMPLENTE), mas consulta, listagem e download continuam funcionando.
Papéis#
Cada usuário tem um papel por empresa. Um mesmo usuário pode ter papéis diferentes em empresas diferentes.
| Papel | Resumo |
|---|---|
owner |
Titular. Tudo, inclusive assinatura e transferência de titularidade |
admin |
Tudo, exceto gerenciar a assinatura e transferir a titularidade |
emissor |
Emite, cancela, substitui, cadastra clientes e serviços, opera a automação |
contador |
Leitura e exportação. Pode ser contador de várias empresas |
visualizador |
Somente leitura e download |
Só owner e admin criam chaves de API e webhooks. A tabela completa de permissões está em Usuários e papéis.
Escopos de API key#
Uma chave de API não tem papel: tem escopos (nfse:emit, nfse:read, customers:write etc.). Quem cria a chave só pode conceder escopos que ele mesmo tem. Veja Autenticação.