Arquitetura de Processamento e Ambientes

A NFS-e tem a arquitetura de processamento mais particular entre os documentos fiscais da Focus: ela não depende de uma única SEFAZ, e sim de cada prefeitura (padrão municipal) ou do ambiente nacional (padrão DPS). Entender esse modelo híbrido e a separação entre os ambientes é o que evita emitir uma nota real durante um teste — ou enviar pela rota errada.

Modelo de processamento

Modelo Híbrido (pré-validação síncrona + autorização assíncrona): ao enviar, a API valida na hora campos essenciais, formato dos dados e o cadastro do prestador — um erro aqui chega imediatamente na mesma resposta. Passando a pré-validação, a nota é aceita (201 no municipal, 202 no Nacional), entra em fila e é autorizada ou rejeitada pela prefeitura/ambiente nacional em segundo plano.
Aceita para processamento ≠ autorizada: diferente da NFC-e (totalmente síncrona), o retorno de aceite não confirma a autorização. Para saber o desfecho, use a Consulta (GET .../{referencia}) ou configure webhooks — evitando polling manual.
Dois padrões, dois endpoints: o processamento muda conforme o padrão do município. O padrão municipal (/v2/nfse) fala com o webservice de cada prefeitura; o padrão Nacional (/v2/nfsen) fala com o ambiente nacional via DPS (Declaração de Prestação de Serviços). O município define qual se aplica.
Webhooks (recomendado): como a autorização é assíncrona, cadastrar webhooks é a forma indicada de receber a mudança de status sem ficar consultando a API repetidamente.

📘
O endpoint certo vem antes de tudo
/v2/nfse (municipal) e /v2/nfsen (Nacional) são conjuntos de operações independentes. Enviar a nota pelo endpoint errado é causa comum de rejeição. Consulte a lista de municípios integrados para saber qual padrão se aplica ao prestador.

Ambientes

A API oferece dois ambientes. A autenticação ocorre com basic auth, mas com tokens específicos em cada ambiente; além disso, muda a URL base e o efeito fiscal das operações.

Ambiente de Homologação: espelho de testes sem validade jurídica. Use-o para validar regras de schema e integrações antes do go-live. Os cupons emitidos ali não têm validade fiscal nem tributária.
Ambiente de Produção: transmissão oficial, com valor fiscal e jurídico. Use-o somente quando estiver pronto para operar com notas válidas em nome dos seus clientes ou da sua empresa.

Ambiente	URL base
Homologação	`https://homologacao.focusnfe.com.br`
Produção	`https://api.focusnfe.com.br`

As rotas REST documentadas neste portal usam o prefixo /v2. Exemplos: https://api.focusnfe.com.br/v2/nfse (municipal) e https://api.focusnfe.com.br/v2/nfsen (Nacional).

📘
A homologação da NFS-e municipal depende da prefeitura
Ao contrário da NF-e e da NFC-e, nem todo município oferece ambiente de homologação para NFS-e — alguns webservices de prefeitura só têm produção. Antes de planejar os testes do cliente, confirme na lista de municípios atendidos se há homologação disponível para aquele município.

Fonte: documentação de referência da API de NFS-e (/reference/nfse, /reference/nfse-nacional) e página "Ambiente" da Focus NFe (v2.0).