DPS por Web Service - Nota Nacional

A partir da necessidade de atender a Reforma Tributária e as adequações da Nota Nacional, o e-Nota passa a contemplar API para receber automaticamente as Declarações de Prestação de Serviço (DPS) enviadas por Web Service, pelos sistemas próprios dos prestadores de serviços.

Nesta página, você encontra todas as informações necessárias para configurar o recebimento das DPS no padrão adotado pela Betha Sistemas, incluindo layout, schema XML, documentação de integração e URLs de comunicação.

Importante: A integração via Web Service para recebimento das DPS estará ativa e operacional a partir do dia 20/11.

Layout da Betha Sistemas

O layout adotado pela Betha Sistemas para o recebimento das DPS segue o padrão oficial definido pela Receita Federal, contendo todas as implementações e atualizações previstas até a Nota Técnica nº 004 – Versão 1.1

📄 Baixar Layout | Layout oficial da Betha Sistemas para recepção das DPS.

📄 Baixar Layout | Layout oficial da Betha Sistemas para recepção do cancelamento e substituição das DPS.

Documentação Técnica - Web Service DPS (Declaração de Prestação de Serviço)

⚠️ Atenção: Esta documentação está em construção. Recomenda-se verificar periodicamente a tabela de alterações.

Este documento auxilia desenvolvedores na integração com o Web Service SOAP para recepção e validação de DPS (Declaração de Prestação de Serviço). Todos os dados são considerados dados de teste.

Versão Atual: Sistema recepciona e valida DPS. Processamento completo com geração de NFS-e será implementado em versão futura.

Versionamento

Versão	Data	Autor	Alteração
1.0.0	17/11/2025	Douglas Felipe da Silva	Versão inicial
1.1.0	18/11/2025	Lucas Coelho	Correções críticas e melhorias

Ambientes

Ambientes	URL Base	tpAmb	WSDL
Homologação	`http://nota-eletronica-release.test.betha.cloud/dps`	2	`/ws/dps.wsdl`
Produção	`http://nota-eletronica.betha.cloud/dps`	1	`/ws/dps.wsdl`

Fluxo de Processamento

⚠️ IMPORTANTE: Processamento Assíncrono

O processamento da DPS é ASSÍNCRONO:

1. RecepcionarDps → Retorna protocolo imediatamente
   Status: "Aguardando validação do ambiente nacional"

2. Sistema valida e armazena a DPS
   - Valida estrutura XML
   - Valida assinatura digital
   - Valida campos obrigatórios
   - Armazena no XML

3. ConsultarDps → Verifica status da recepção
   Status: "Aguardando validação do ambiente nacional"

Fluxo de Recepção da DPS

graph LR
    A[Assinar DPS] --> B[RecepcionarDps]
    B --> C{Validação}
    C -->|Sucesso| D[Recebe Protocolo]
    C -->|Erro| E[Mensagem Erro]
    D --> F[ConsultarDps]
    F --> G[Status: Aguardando]

Fluxo de Cancelamento

graph LR
    A[Ter NFS-e] --> B[RecepcionarEventoCancelamento]
    B --> C{Validação}
    C -->|Sucesso| D[Recebe Protocolo]
    C -->|Erro| E[Mensagem Erro]

Endpoints

1. RecepcionarDps

Recebe XML da DPS assinado digitalmente para processamento.

Endpoint: POST /ws

Request:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:dps="http://www.betha.com.br/e-nota-dps">
   <soapenv:Body>
      <dps:RecepcionarDpsEnvio>
         <dps:DPS versao="1.0">
            <dps:infDPS id="DPS123456">
               <dps:tpAmb>2</dps:tpAmb>
               <dps:dhEmi>2024-01-15T10:00:00</dps:dhEmi>
               <dps:verAplic>1.0</dps:verAplic>
               <dps:serie>00001</dps:serie>
               <dps:nDPS>123456</dps:nDPS>
               <dps:dCompet>2024-01-15</dps:dCompet>
               <dps:tpEmit>1</dps:tpEmit>
               <dps:cLocEmi>4205407</dps:cLocEmi>
               <dps:prest>
                  <dps:CNPJ>11222333000181</dps:CNPJ>
                  <dps:regTrib>
                     <dps:opSimpNac>1</dps:opSimpNac>
                     <dps:regEspTrib>0</dps:regEspTrib>
                  </dps:regTrib>
               </dps:prest>
               <dps:serv>
                  <dps:locPrest>
                     <dps:cLocPrestacao>4205407</dps:cLocPrestacao>
                  </dps:locPrest>
                  <dps:cServ>
                     <dps:cTribNac>0101010</dps:cTribNac>
                     <dps:xDescServ>Serviço de consultoria</dps:xDescServ>
                     <dps:cNBS>11601010</dps:cNBS>
                  </dps:cServ>
               </dps:serv>
               <dps:valores>
                  <dps:vServPrest>
                     <dps:vServ>1000.00</dps:vServ>
                  </dps:vServPrest>
                  <dps:trib>
                     <dps:tribMun>
                        <dps:tribISSQN>2</dps:tribISSQN>
                        <dps:pAliq>5.00</dps:pAliq>
                     </dps:tribMun>
                     <dps:totTrib>
                        <dps:indTotTrib>0</dps:indTotTrib>
                     </dps:totTrib>
                  </dps:trib>
               </dps:valores>
            </dps:infDPS>
            <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
               <!-- Assinatura digital ICP-Brasil -->
            </ds:Signature>
         </dps:DPS>
      </dps:RecepcionarDpsEnvio>
   </soapenv:Body>
</soapenv:Envelope>

Response (Sucesso):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <dps:RecepcionarDpsResposta xmlns:dps="http://www.betha.com.br/e-nota-dps">
         <dps:protocolo>1abc123def456</dps:protocolo>
         <dps:dhRecebimento>2024-01-15T10:00:01</dps:dhRecebimento>
         <dps:status>Aguardando validação do ambiente nacional</dps:status>
      </dps:RecepcionarDpsResposta>
   </soapenv:Body>
</soapenv:Envelope>

Response (Erro):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <dps:RecepcionarDpsResposta xmlns:dps="http://www.betha.com.br/e-nota-dps">
         <dps:protocolo></dps:protocolo>
         <dps:dhRecebimento>2024-01-15T10:00:01</dps:dhRecebimento>
         <dps:status>Rejeitado</dps:status>
         <dps:listaMensagens>
            <dps:mensagem>
               <dps:codigo>E022</dps:codigo>
               <dps:mensagem>CNPJ do prestador inválido</dps:mensagem>
               <dps:correcao>Verifique o CNPJ informado</dps:correcao>
            </dps:mensagem>
         </dps:listaMensagens>
      </dps:RecepcionarDpsResposta>
   </soapenv:Body>
</soapenv:Envelope>

2. ConsultarDps

Consulta status de processamento pelo protocolo (consulta simples).

Endpoint: POST /ws

Request:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:dps="http://www.betha.com.br/e-nota-dps">
   <soapenv:Body>
      <dps:ConsultarDpsEnvio>
         <dps:protocolo>1abc123def456</dps:protocolo>
      </dps:ConsultarDpsEnvio>
   </soapenv:Body>
</soapenv:Envelope>

Response:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <dps:ConsultarDpsResposta xmlns:dps="http://www.betha.com.br/e-nota-dps">
         <dps:protocolo>1abc123def456</dps:protocolo>
         <dps:dhRecebimento>2024-01-15T10:00:01</dps:dhRecebimento>
         <dps:status>Aguardando validação do ambiente nacional</dps:status>
         <dps:idDps>DPS123456</dps:idDps>
      </dps:ConsultarDpsResposta>
   </soapenv:Body>
</soapenv:Envelope>

3. ConsultarStatusDps

Consulta detalhada do status de Emissão, Cancelamento ou Substituição.

Endpoint: POST /ws

Tipos de Integração

Tipo	Descrição
`EMISSAO`	Status da emissão da DPS
`CANCELAMENTO`	Status do cancelamento
`CANCELAMENTO_POR_SUBSTITUICAO`	Status da substituição

Request - Emissão

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:dps="http://www.betha.com.br/e-nota-dps">
   <soapenv:Body>
      <dps:ConsultarStatusDpsEnvio>
         <dps:codigoIbge>4205407</dps:codigoIbge>
         <dps:cpfCnpjPrestador>11222333000181</dps:cpfCnpjPrestador>
         <dps:protocolo>1abc123def456</dps:protocolo>
         <dps:tipoIntegracao>EMISSAO</dps:tipoIntegracao>
      </dps:ConsultarStatusDpsEnvio>
   </soapenv:Body>
</soapenv:Envelope>

Utilize o código IBGE correspondente ao município onde a consulta será efetuada.

Response - Emissão

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <ns2:ConsultarStatusDpsEmissaoResposta xmlns:ns2="http://www.betha.com.br/e-nota-dps">
         <ns2:statusProcessamento>Aguardando validação do ambiente nacional</ns2:statusProcessamento>
         <ns2:dataHoraRecebimento>2025-11-17T14:30:39.000-03:00</ns2:dataHoraRecebimento>
         <ns2:protocolo>PROTO999</ns2:protocolo>
         <ns2:idDps>DPS004</ns2:idDps>
      </ns2:ConsultarStatusDpsEmissaoResposta>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Nota: Atualmente o sistema apenas recepciona e valida a DPS. O processamento completo com geração de NFS-e será implementado em versão futura.

4. RecepcionarEventoCancelamento

Recebe evento de cancelamento de NFS-e.

Endpoint: POST /ws

Request:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:evt="http://www.betha.com.br/e-nota-evento">
   <soapenv:Body>
      <evt:RecepcionarEventoCancelamentoEnvio>
         <evt:evento versao="1.0">
            <evt:infEvento id="EVT123456">
               <evt:verAplic>1.0</evt:verAplic>
               <evt:ambGer>2</evt:ambGer>
               <evt:nSeqEvento>1</evt:nSeqEvento>
               <evt:dhProc>2024-01-15T10:00:00</evt:dhProc>
               <evt:nDFe>42054071122233300018100000012345601234567890</evt:nDFe>
               <evt:pedRegEvento versao="1.0">
                  <evt:infPedReg id="PED123456">
                     <evt:chNFSe>42054071122233300018100000012345601234567890</evt:chNFSe>
                     <evt:CNPJAutor>11222333000181</evt:CNPJAutor>
                     <evt:dhEvento>2024-01-15T10:00:00</evt:dhEvento>
                     <evt:tpAmb>2</evt:tpAmb>
                     <evt:verAplic>1.0</evt:verAplic>
                     <evt:e105101>
                        <evt:xDesc>Cancelamento de NFSe</evt:xDesc>
                        <evt:cMotivo>1</evt:cMotivo>
                        <evt:xMotivo>Erro na emissão</evt:xMotivo>
                     </evt:e105101>
                  </evt:infPedReg>
                  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                     <!-- Assinatura digital -->
                  </ds:Signature>
               </evt:pedRegEvento>
            </evt:infEvento>
            <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
               <!-- Assinatura digital -->
            </ds:Signature>
         </evt:evento>
      </evt:RecepcionarEventoCancelamentoEnvio>
   </soapenv:Body>
</soapenv:Envelope>

Response:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <evt:RecepcionarEventoCancelamentoResposta xmlns:evt="http://www.betha.com.br/e-nota-evento">
         <evt:protocolo>e9e648b0-ce82-4c28-9a00-997f3b23e35f</evt:protocolo>
         <evt:dhRecebimento>2025-11-18T10:53:22.589-03:00</evt:dhRecebimento>
         <evt:status>Aguardando validação do ambiente nacional</evt:status>
      </evt:RecepcionarEventoCancelamentoResposta>
   </soapenv:Body>
</soapenv:Envelope>

5. RecepcionarEventoSubstituicao

Recebe evento de cancelamento por substituição de NFS-e.

Endpoint: POST /ws

Request:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:evt="http://www.betha.com.br/e-nota-evento">
   <soapenv:Body>
      <evt:RecepcionarEventoSubstituicaoEnvio>
         <evt:evento versao="1.0">
            <evt:infEvento id="EVT123457">
               <evt:verAplic>1.0</evt:verAplic>
               <evt:ambGer>2</evt:ambGer>
               <evt:nSeqEvento>1</evt:nSeqEvento>
               <evt:dhProc>2024-01-15T10:00:00</evt:dhProc>
               <evt:nDFe>42054071122233300018100000012345601234567890</evt:nDFe>
               <evt:pedRegEvento versao="1.0">
                  <evt:infPedReg id="PED123457">
                     <evt:chNFSe>42054071122233300018100000012345601234567890</evt:chNFSe>
                     <evt:CNPJAutor>11222333000181</evt:CNPJAutor>
                     <evt:dhEvento>2024-01-15T10:00:00</evt:dhEvento>
                     <evt:tpAmb>2</evt:tpAmb>
                     <evt:verAplic>1.0</evt:verAplic>
                     <evt:e105102>
                        <evt:xDesc>Substituição de NFSe</evt:xDesc>
                        <evt:cMotivo>1</evt:cMotivo>
                        <evt:xMotivo>Correção de dados</evt:xMotivo>
                        <evt:chSubstituta>42054071122233300018100000012345601234567891</evt:chSubstituta>
                     </evt:e105102>
                  </evt:infPedReg>
                  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                     <!-- Assinatura digital -->
                  </ds:Signature>
               </evt:pedRegEvento>
            </evt:infEvento>
            <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
               <!-- Assinatura digital -->
            </ds:Signature>
         </evt:evento>
      </evt:RecepcionarEventoSubstituicaoEnvio>
   </soapenv:Body>
</soapenv:Envelope>

Response:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <evt:RecepcionarEventoSubstituicaoResposta xmlns:evt="http://www.betha.com.br/e-nota-evento">
         <evt:protocolo>35e5d630-896e-4d22-a563-b57a7793eada</evt:protocolo>
         <evt:dhRecebimento>2025-11-18T10:54:56.294-03:00</evt:dhRecebimento>
         <evt:status>Aguardando validação do ambiente nacional</evt:status>
      </evt:RecepcionarEventoSubstituicaoResposta>
   </soapenv:Body>
</soapenv:Envelope>

Códigos de Erro

Código	Mensagem	Correção	Categoria
E001	XML mal formado	Verifique a estrutura do XML	Estrutura XML
E001A	Protocolo ausente	Informe o protocolo	Estrutura XML
E002	Assinatura digital ausente	Assine digitalmente a DPS	Estrutura XML
E003	Certificado digital inválido	Utilize certificado ICP-Brasil válido	Estrutura XML
E004	Certificado digital expirado	Renove o certificado digital	Estrutura XML
E005	CNPJ/CPF do certificado não corresponde	Utilize certificado do prestador	Estrutura XML
E010	Campo tpAmb é obrigatório	Informe 1=Produção ou 2=Homologação	Campos Obrigatórios
E011	Campo tpAmb inválido	Informe 1=Produção ou 2=Homologação	Campos Obrigatórios
E012	Campo tpEmit é obrigatório	Informe o tipo de emitente	Campos Obrigatórios
E013	Campo tpEmit inválido	Apenas tpEmit=1 (Prestador) aceito	Campos Obrigatórios
E020	Dados do prestador obrigatórios	Informe os dados do prestador	Prestador
E021	CNPJ ou CPF obrigatório	Informe CNPJ ou CPF do prestador	Prestador
E022	CNPJ do prestador inválido	Verifique o CNPJ informado	Prestador
E023	CPF do prestador inválido	Verifique o CPF informado	Prestador
E030	Dados do serviço obrigatórios	Informe os dados do serviço	Serviço
E040	Valor do serviço obrigatório	Informe o valor do serviço	Valores
E041	Valor deve ser maior que zero	Informe um valor válido	Valores
E050	DPS já recepcionada	Esta DPS já foi enviada	Duplicidade
E051	ID da DPS duplicado	O ID já existe para esta entidade	Duplicidade
E052	Número e série duplicados	Esta combinação já foi utilizada	Duplicidade
E060	Data de competência inválida	Data não pode ser futura	Validação
E061	Data de emissão inválida	Data não pode ser futura	Validação
E064	NFS-e não encontrada	A NFS-e informada não existe	Validação
E999	Erro interno	Contate o suporte técnico	Genérico

XSD Schemas

Acessar XSDs

Schema	URL
DPS	`{URL_BASE}/schemas/dps.xsd`
Evento Cancelamento	`{URL_BASE}/schemas/evento-cancelamento.xsd`
Evento Substituição	`{URL_BASE}/schemas/evento-substituicao.xsd`
Consulta Status	`{URL_BASE}/schemas/consulta-status.xsd`

WSDL

{URL_BASE}/ws/dps.wsdl

Limites e Restrições

Tamanho máximo do XML: 5MB
Timeout: 60 segundos
Rate limit: 100 requisições/minuto
DPS por requisição: Apenas 1

Troubleshooting

Problema: Certificado digital inválido

Solução: Verifique se o certificado é ICP-Brasil tipo A1 ou A3 e está dentro da validade.

Problema: CNPJ/CPF não corresponde

Solução: O certificado deve ser do prestador ou da matriz (mesma raiz CNPJ).

Problema: DPS já recepcionada

Solução: Use ConsultarDps para verificar o status da DPS já enviada.

Problema: Status sempre Aguardando validação

Solução: Atualmente o sistema apenas recepciona e valida a DPS. O processamento completo será implementado em versão futura.

Layout da Betha Sistemas​

Documentação Técnica - Web Service DPS (Declaração de Prestação de Serviço)​

Versionamento​

Índice​

Ambientes​

Fluxo de Processamento​

⚠️ IMPORTANTE: Processamento Assíncrono​

Fluxo de Recepção da DPS​

Fluxo de Cancelamento​

Endpoints​

1. RecepcionarDps​

2. ConsultarDps​

3. ConsultarStatusDps​

Tipos de Integração​

Request - Emissão​

Response - Emissão​

4. RecepcionarEventoCancelamento​

5. RecepcionarEventoSubstituicao​

Códigos de Erro​

XSD Schemas​

Acessar XSDs​

WSDL​

Limites e Restrições​

Troubleshooting​

Problema: Certificado digital inválido​

Problema: CNPJ/CPF não corresponde​

Problema: DPS já recepcionada​

Problema: Status sempre Aguardando validação​

Layout da Betha Sistemas

Documentação Técnica - Web Service DPS (Declaração de Prestação de Serviço)

Versionamento

Índice

Ambientes

Fluxo de Processamento

⚠️ IMPORTANTE: Processamento Assíncrono

Fluxo de Recepção da DPS

Fluxo de Cancelamento

Endpoints

1. RecepcionarDps

2. ConsultarDps

3. ConsultarStatusDps

Tipos de Integração

Request - Emissão

Response - Emissão

4. RecepcionarEventoCancelamento

5. RecepcionarEventoSubstituicao

Códigos de Erro

XSD Schemas

Acessar XSDs

WSDL

Limites e Restrições

Troubleshooting

Problema: Certificado digital inválido

Problema: CNPJ/CPF não corresponde

Problema: DPS já recepcionada

Problema: Status sempre Aguardando validação