# PES2B NFSe Emissor Service — API 0.2.0 URL base: https://emissor.service.pes2b.com Documentação: https://developer.emissor.service.pes2b.com/ — Swagger: https://developer.emissor.service.pes2b.com/docs/ — Contrato: https://developer.emissor.service.pes2b.com/openapi.json. A API permanece em emissor.service.pes2b.com. ## Autenticação Enviar X-API-Key em todas as rotas /api/. A chave é vinculada ao cliente, tenant, escopos e empresas autorizadas. Nunca enviar a senha ou o arquivo do certificado no corpo da emissão. A instalação atual só permite Jorgepla em produção restrita. O domínio não define o ambiente: conferir GET /api/v1/ambiente. ## Duas formas de informar a DPS As rotas POST /api/v1/nfse/validar e POST /api/v1/nfse/emitir aceitam o formato simplificado da versão 0.1 e o formato completo da versão 0.2. Não misturar os dois formatos em uma requisição. Formato completo: empresa_codigo + leiaute + dados_dps. Usar nomes, capitalização e hierarquia do XSD oficial, incluindo IBSCBS. Valores decimais, códigos, datas, percentuais e quantidades são strings. Elementos repetidos são arrays, inclusive com um único item. Não enviar null em campos opcionais: omitir o campo. Leiautes: - restrita_20261020: homologação NT009. finNFSe diretamente em dados_dps; CST e cClassTrib diretamente em IBSCBS.valores.trib. Grupo gIBSCBS para crédito presumido, tributação regular e diferimento. - producao_20260209: leiaute de produção. finNFSe dentro de IBSCBS; CST e cClassTrib dentro de IBSCBS.valores.trib.gIBSCBS. A instalação atual rejeita esse perfil por divergência de ambiente. O servidor controla Id, tpAmb, verAplic e tpEmit=1. Esses campos não são aceitos na entrada. O CNPJ em dados_dps.prest.CNPJ deve ser o CNPJ da empresa autorizada. Emissão como tomador ou intermediário não é suportada. Série permitida: 1 a 49999; nDPS positivo com até 15 dígitos. Tamanho máximo do corpo: 256.000 bytes. Campos desconhecidos são rejeitados. ## Reforma tributária Todos os elementos de entrada da DPS nos dois XSD empacotados são mapeados e serializados na ordem oficial. Isso inclui destinatário nacional/exterior, imóveis, bens móveis no perfil restrito, referências, operações governamentais, crédito presumido, tributação regular, diferimento e ajustes/reembolsos nos grupos próprios de cada perfil. O catálogo /rtc-campos.json lista cada caminho, tipo, descrição e ocorrência. A marcação 0..1 significa opcional no XSD; as regras fiscais podem exigir o campo em determinada operação. Escolhas entre CNPJ/CPF/NIF e outros grupos são exclusivas. Alíquotas efetivas, bases e totais calculados pela SEFIN na NFS-e são campos de saída. Não os inventar nem enviar no lugar de campos da DPS. O serviço recebe as informações declaradas, valida e transmite; não escolhe CST, classificação, créditos ou enquadramento tributário. A validação XSD não substitui as regras fiscais da SEFIN. ## Operações | Método | Caminho | Escopo | | --- | --- | --- | | GET | /api/v1/ambiente | consultar | | POST | /api/v1/nfse/validar | emitir | | POST | /api/v1/nfse/emitir | emitir | | POST | /api/v1/nfse/cancelar | cancelar | | GET | /api/v1/solicitacoes/{id} | consultar | | POST | /api/v1/solicitacoes/{id}/reconciliar | consultar | | GET | /api/v1/solicitacoes/{id}/xml | consultar | | GET | /api/v1/solicitacoes/{id}/danfse | consultar | | GET | /api/v1/solicitacoes/{id}/eventos | consultar | /validar não abre o certificado e não transmite dados ao Fisco. /emitir gera, valida, assina e envia com mTLS. /cancelar usa evento 101101 e confirma titularidade da nota. As consultas exigem autorização da empresa e do tenant. DANFSe retorna PDF; XML retorna o documento fiscal integral, incluindo os campos calculados de IBS/CBS; eventos preservam o retorno do provedor. ## Idempotência e resultados Enviar Idempotency-Key estável (8 a 200 caracteres: letras, números, ponto, sublinhado, dois-pontos ou hífen) em emissão e cancelamento. A mesma operação com a mesma chave e corpo reutiliza o resultado. Corpo alterado com a mesma chave ou reutilização da mesma identificação fiscal em outra solicitação gera conflito. Não mudar número, data, chave ou formato simplificado/completo ao repetir uma solicitação existente. AUTORIZADA indica autorização fiscal. REJEITADA indica rejeição conhecida. PENDENTE ou RESULTADO_DESCONHECIDO exige consulta e reconciliação, sem criar outra DPS ou retry automático. HTTP 200 da API pode conter REJEITADA; HTTP 202 indica pendência. O httpStatus interno é o código recebido do provedor. Sempre avaliar status. Erros HTTP comuns: 400 dados inválidos/XSD, 401 chave ausente ou inválida, 403 escopo/empresa/CNPJ sem autorização, 409 conflito ou ambiente divergente, 413 tamanho excedido, 429 limite de 60 requisições por minuto, 503 dependências indisponíveis. Envelope de erro: sucesso=false, status, mensagem e requestId, sem segredos. ## Integração n8n Usar credencial Header Auth com X-API-Key e domínio emissor.service.pes2b.com. Conferir ambiente e validar antes do envio. Desativar retry no nó de emissão. Guardar a solicitação_id retornada e a Idempotency-Key. Não fixar dados reais ou credenciais em exports públicos. Exemplos disponíveis nos downloads são fictícios e servem para validação local, não são um enquadramento fiscal pronto para uso. ## Disponibilidade e fontes GET /health verifica o processo; GET /ready verifica dependências. A expansão RTC foi validada localmente nos XSD dos dois perfis; não significa homologação fiscal de todas as combinações. O teste anterior da Jorgepla autorizou uma DPS em homologação; produção real permanece bloqueada. Fontes oficiais conferidas em 10/11/2026: - https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/producao-restrita - https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual/documentacao-atual - Pacotes e hashes preservados em schemas/ORIGEM.md. Compatibilidade futura: novos leiautes e regras publicados após essa data precisam de revisão e testes antes de uso.