REST API de DUA-ES

Guia Rápido

Todas as requisições na API devem ser realizadas em ambiente criptografado HTTPS através da URL https://api.webmania.com.br/. O prefixo /2/dua deve ser adicionado na URL em todas as requisições.

Principais funcionalidades:

• Dois modos de emissão — por valor direto ou a partir de notas fiscais já emitidas na Webmania®
• Seleção por período ou por chaves/UUIDs de até 100 notas por requisição
• Cálculo automático do valor a partir do ICMS-ST e do DIFAL declarados nas notas
• Prévia da seleção sem emitir e sem consumir cota do plano
• Emissão de Dívida Ativa a partir do número da CDA
• Consulta de área, serviço, município e valor antes da emissão
• PDF do DUA-e em base64 e consulta de DUA-e pago
• Notificação por webhook no desfecho de cada emissão

A tabela abaixo lista todos os endpoints disponíveis na API:

Sempre envie o corpo da requisição no formato JSON, e o cabeçalho Content-Type deve estar definido como application/json.

A resposta da API estará sempre no formato JSON, o padrão da estrutura da resposta está disponível nesta seção da documentação.

Notificações

O webhook é o canal principal de notificação de resultado da API DUA-ES. Toda emissão (normal ou de Dívida Ativa) deve informar a URL de callback no parâmetro url_notificacao.

O que é o UUID?

O UUID (Universally Unique Identifier) é um identificador único de 36 caracteres, no formato 8-4-4-4-12, que a Webmania® atribui a cada emissão de DUA-e. Ele é gerado assim que a requisição é aceita pela API — antes de qualquer transmissão à SEFAZ/ES.

Uma vez gerado, o UUID é definitivo: não muda em retentativas nem em reenvio. O protocolo devolvido pela SEFAZ/ES também tem formato UUID, mas não é o mesmo identificador: ele é gerado pelo órgão, só existe após o processamento e não deve ser usado como chave no seu banco. Guarde sempre o uuid devolvido pela emissão.

Quando o DUA-e atingir um status terminal — aprovado ou rejeitado — a Webmania® envia uma requisição POST para a url_notificacao com o resultado completo.

Exemplo do payload enviado pelo webhook:

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "modelo": "dua",
  "status": "aprovado",
  "ambiente": 1,
  "identificador": "0000000000"
}

O identificador é o número do DUA-e emitido (numero_guia) — sempre o numero_guia, inclusive na emissão de Dívida Ativa (o numero_cda é apenas a chave de entrada dessa modalidade). É o mesmo valor exposto em provider_identifier no endpoint de status. Exceção: se a emissão por CDA é rejeitada antes da aceitação pela SEFAZ/ES — nenhum DUA-e emitido, sem provider_identifier — o identificador cai para o numero_cda enviado. Quando status é rejeitado, o payload inclui motivos_rejeicao (lista de {codigo, mensagem}) com o motivo da rejeição.

A notificação é enviada no método POST, com o cabeçalho Content-Type: application/json — os campos do payload:

Em emissões por notas, o payload inclui ainda origem (periodo ou chaves), o detalhe notas e o índice notas_ignoradas das notas não liquidadas — veja Emissão por Notas.

Exemplo de notificação — DUA-e rejeitado:

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "modelo": "dua",
  "status": "rejeitado",
  "ambiente": 1,
  "motivos_rejeicao": [
    { "codigo": "705", "mensagem": "A Área não pertence ao Órgão" }
  ]
}

O webhook não dispara para processando nem para erro_comunicacao. O status erro_comunicacao indica que o resultado junto à SEFAZ/ES ficou incerto: a API não reenvia a emissão automaticamente, e a resolução é manual — consulte GET /2/dua/status/{uuid}, que retorna uma mensagem orientando a conferência com a SEFAZ/ES. Só reemita após confirmar que o DUA-e não foi gerado, para evitar documento fiscal em duplicidade.

Se a comunicação com a SEFAZ/ES falhar e a API esgotar as tentativas sem obter o número do DUA, a guia será marcada como rejeitada e o webhook será chamado com a mensagem explicando que houve instabilidade nos servidores da SEFAZ/ES. Nessa situação, o integrador pode tentar emitir novamente.

Para casos em que o webhook não puder ser recebido, acompanhe GET /2/dua/status/{uuid} como fallback de consulta manual.

Resumo dos status possíveis:

Dois modos de emissão

O endpoint POST /2/dua/emissao aceita dois modos de origem, mutuamente exclusivos:

Emissão a partir de notas fiscais. Informe uma janela de emissão em periodo (data_inicio e data_fim) ou uma lista de até 100 identificadores em documentos[]. A API localiza as notas e apura o valor do DUA-e a partir do ICMS-ST e do DIFAL declarados.

Atenção: os sete campos de serviço/órgão — cnpj_orgao, codigo_area, codigo_servico, documento_contribuinte, data_referencia, codigo_municipio e informacoes_complementares — permanecem obrigatórios em todos os modos, inclusive por notas. Eles identificam o órgão e a receita da SEFAZ/ES e não são deriváveis da NF-e. Como o DUA-e é produção-only e não tem cancelamento, essa validação é feita antes de qualquer seleção ou reserva de notas: uma requisição incompleta é recusada sem gerar nada.

📌 O documentos[] aceita a chave de acesso ou o UUID da nota. O UUID é o mesmo identificador que a REST API de NF-e da Webmania® devolve na emissão e que você já tem gravado no seu banco. Você pode misturar chaves de 44 dígitos e UUIDs no mesmo array:

"documentos": [
  "35260800000000000000550010000012341123456789",
  "8f14e45f-ceea-4d3e-a2e0-123456789012"
]

💡 A prévia é gratuita. POST /2/dua/notas/preview executa a mesma seleção da emissão e devolve o valor que seria apurado, sem emitir, sem ocupar lote e sem consumir cota do plano. Como não há homologação para o DUA-e, a prévia é a única forma segura de validar a integração antes de gerar um documento pagável — use-a.

Módulos & Exemplos

Teste a REST API de DUA-ES sem escrever uma linha de código e acelere a sua integração com as ferramentas oficiais da Webmania®.

• Ferramentas
  • Coleção Postman (Testes instantâneos)
  • Vídeo: Testar REST API sem linha de código

Autenticação

Para acessar os recursos da API, é necessário autenticar as requisições por meio do cabeçalho HTTP (HTTP headers). A autenticação deve ser feita utilizando o cabeçalho Authorization, no seguinte formato:

Authorization: Bearer {Access-Token}

O Access-Token da API 2.0 é encontrado no painel Webmania® e deve ser incluído em todas as requisições.

Autenticação mútua (mTLS) com a SEFAZ/ES. A Webmania® utiliza internamente um certificado digital A1 do tipo e-CNPJ A1 para a comunicação SOAP com a SEFAZ/ES. O integrador não precisa enviar certificado nas requisições à API Webmania®; o certificado do transmissor é resolvido e aplicado automaticamente pelo gateway.

Mantenha suas credenciais em segurança. Nunca publique o Access Token no código-fonte do site, aplicativo ou sistema onde ele possa ser facilmente acessado por terceiros.

Para aplicativos móveis (iOS e Android), recomendamos que a consulta à API seja realizada no servidor (back-end). O código-fonte do aplicativo deve apenas enviar a requisição enquanto o processamento da consulta deve ocorrer no seu servidor.

Formato de resposta

Todas as respostas da API seguem um padrão e estão no formato JSON. Os campos usam snake_case por extenso, no mesmo vocabulário das APIs GNRE e DARE-ICMS SP.

A tabela abaixo apresenta os códigos de status HTTP que a API pode retornar com suas respectivas descrições.

Legenda: ✅ a operação foi concluída · ❌ a operação não foi concluída e nada foi criado.

O código 429 (Too Many Requests) não aparece nesta tabela: ele é específico do controle de volume e está descrito em Limite de requisições.

Limite diário do modo por notas: as emissões de DUA-e a partir de notas fiscais somam um limite diário de 1.000 emissões por empresa. Ao atingir o teto, novas emissões por notas retornam 429 com a mensagem "Limite diário de 1000 emissões por notas atingido. Novas emissões por notas serão liberadas no próximo dia." O limite é renovado à meia-noite (horário de Brasília) e a emissão com valor direto não consome esse limite.

Exemplo de resposta para uma requisição com erro de validação:

{
  "error": "O campo documento_contribuinte é obrigatório."
}

Órgãos Credenciados

Todo DUA-e é emitido para um órgão credenciado na SEFAZ/ES. O CNPJ do órgão é o ponto de partida da integração: é ele que você informa em cnpj_orgao na emissão e em cnpj nas consultas de área/serviço e de valor.

A tabela abaixo lista os órgãos credenciados. Não há endpoint que retorne essa lista — copie o CNPJ do órgão responsável pelo serviço que você precisa quitar.

Serviços DUA-e

Os serviços a seguir espelham os 10 endpoints REST da API Webmania®. Todos utilizam JSON sobre HTTPS com autenticação Bearer na API Webmania®. A comunicação com a SEFAZ/ES (SOAP/XML com autenticação mútua mTLS) é um canal interno da Webmania® — transparente para a sua integração: você não envia certificado nem monta envelope XML.

Serviços
Emissão de DUA-e

Emite um DUA-e junto à SEFAZ/ES. A API retorna imediatamente e processa o DUA-e em background. O resultado final é notificado pelo webhook informado em url_notificacao, com acompanhamento por GET /2/dua/status/{uuid} — Saiba mais.

Parâmetros da requisição:

A coluna Tam. indica o tamanho: 14 = exatamente 14 caracteres; 1 a 6 e 4 a 5 = entre 1 e 6 / entre 4 e 5 algarismos; 1-100 = limite de itens da lista; 12,2 = até 12 algarismos com 2 casas decimais; 256 e 500 = até esse número de caracteres; - = tamanho fixo não publicado:

Como o valor é definido

Exemplo de requisição: emissão direta de um DUA-e com vencimento e pagamento no mesmo dia

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/dua/emissao

{
  "ambiente": 1,
  "url_notificacao": "https://seudominio.com.br/webhook/dua",
  "cnpj_orgao": "27080571000130",
  "codigo_area": 5,
  "codigo_servico": 3867,
  "documento_contribuinte": "12345678000195",
  "data_referencia": "2027-06",
  "data_vencimento": "2027-06-30",
  "data_pagamento": "2027-06-30",
  "codigo_municipio": 57053,
  "informacoes_complementares": "DUA EXEMPLO",
  "valor": 1.00,
  "quantidade": 1,
  "referencia_interna": "NFe XYZ",
  "gerar_pix": true
}

Exemplo de resposta: resposta imediata da emissão — o processamento é assíncrono e o desfecho final chega pelo webhook

{
  "status": "processando",
  "message": "Emissão em processamento. Consulte novamente em alguns instantes.",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Quando a SEFAZ/ES recusa a emissão, o resultado terminal chega com status: "rejeitado" e a causa da recusa nos dois canais de acompanhamento — o webhook de url_notificacao (Notificações) e o GET /2/dua/status/{uuid} (Consulta de Status):

Corpo enviado pelo webhook: notificação de rejeição com o código e o motivo da recusa

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "modelo": "dua",
  "status": "rejeitado",
  "ambiente": 1,
  "motivos_rejeicao": [
    { "codigo": "705", "mensagem": "A Área não pertence ao Órgão" }
  ]
}

Resposta do GET /2/dua/status/{uuid}: o mesmo desfecho rejeitado, com o código do último erro apontado pela SEFAZ/ES

{
  "status": "rejeitado",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider_identifier": null,
  "motivos_rejeicao": [
    { "codigo": "705", "mensagem": "A Área não pertence ao Órgão" }
  ],
  "last_error_code": "705"
}

Em motivos_rejeicao, o codigo é o codigo_retorno da SEFAZ/ES e a mensagem é o descricao_retorno correspondente. Exceção: se a API esgotar as tentativas de comunicação com a SEFAZ/ES sem obter o número do DUA, codigo é SEFAZ_UNSTABLE_TIMEOUT (não um codigo_retorno). A lista completa está em Códigos de Retorno.

Os campos da tabela abaixo compõem o response retornado quando o DUA-e é aprovado (disponível na resposta armazenada e em GET /2/dua/status/{uuid}) — não na resposta imediata acima.

Serviços
Emissão por Notas (período ou chaves)

O POST /2/dua/emissao — o mesmo endpoint da emissão por valor direto — também aceita a origem por notas. Além do valor direto, o DUA-e pode ser emitido a partir de notas fiscais já emitidas, informando uma janela de emissão (periodo) ou uma lista de identificadores (documentos). Os dois modos são mutuamente exclusivos entre si e não podem ser combinados com o valor direto (valor). O valor é calculado pela API a partir das notas selecionadas, e o emitente é preenchido pelo servidor.

Os sete campos de serviço/órgão permanecem obrigatórios em todos os modos de emissão, inclusive por notas:

Eles identificam o órgão/receita da SEFAZ-ES e o contribuinte do serviço e não são deriváveis da NF-e; por isso a recusa acontece antes de qualquer seleção ou reserva de notas — o DUA-e é produção-only e não tem cancelamento, então a validação é feita primeiro.

Exemplo de requisição por chaves: emissão do DUA-e calculando o valor a partir das chaves de acesso informadas

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/dua/emissao

{
  "ambiente": 1,
  "url_notificacao": "https://seudominio.com.br/webhook/dua",
  "cnpj_orgao": "27080571000130",
  "codigo_area": 5,
  "codigo_servico": 3867,
  "documento_contribuinte": "12345678000195",
  "data_referencia": "2027-06",
  "data_vencimento": "2027-06-30",
  "data_pagamento": "2027-06-30",
  "codigo_municipio": 57053,
  "informacoes_complementares": "DUA EXEMPLO POR NOTAS",
  "documentos": [
    "35260700000000000000550010000012341123456789",
    "8f14e45f-ceea-4d3e-a2e0-123456789012"
  ]
}

A resposta é a mesma da emissão por valor direto, com o resultado final notificado pelo webhook informado em url_notificacao.

Serviços
Prévia de Seleção por Notas

POST /2/dua/notas/preview antecipa, sem emitir nada, a seleção de notas que POST /2/dua/emissao faria para a mesma origem (periodo ou documentos). Como a SEFAZ-ES não disponibiliza homologação para DUA-e, a seleção é sempre feita sobre o ambiente 1 (produção), independentemente do valor informado. Na origem por período, o limite é de 100 notas por requisição (limite_por_requisicao): um período acima desse limite responde 422 pedindo uma janela menor, sem emitir nada.

Limite diário por notas. A emissão por notas está sujeita ao limite diário de 1.000 emissões por notas: ao atingi-lo, a API responde 429 sem emitir nada. A emissão por valor direto não consome esse contador, e a prévia acima também não.

Parâmetros da requisição:

Campos da resposta:

Exemplo de requisição: prévia de seleção por período — mostra as notas que seriam usadas, sem emitir nada

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/dua/notas/preview

{
  "ambiente": 1,
  "periodo": {
    "data_inicio": "2026-07-01",
    "data_fim": "2026-07-31"
  }
}

Exemplo de resposta: notas selecionadas, ignoradas e totais calculados para o período informado

{
  "tipo": "dua",
  "selecionadas": [
    {
      "fiscal_document_uuid": "8f14e45f-ceea-4d3e-a2e0-123456789012",
      "document_key": "35260700000000000000550010000012341123456789",
      "valor_icms_st": "0.00",
      "valor_difal": "85.40",
      "uf_destino": "ES",
      "guia_indicado": "dua"
    }
  ],
  "ignoradas": [],
  "totais": { "icms_st": "0.00", "difal": "85.40", "total": "85.40" },
  "total_encontradas": 1,
  "total_omitidas": 0,
  "limite_por_requisicao": 100
}

Serviços
Emissão de DUA-e de Dívida Ativa

Emite um DUA-e de Dívida Ativa (CDA) a partir do número da Certidão da Dívida Ativa. A API retorna imediatamente e processa o DUA-e em background. O resultado final é notificado pelo webhook informado em url_notificacao, com acompanhamento por GET /2/dua/status/{uuid} — Saiba mais.

O que é a Certidão da Dívida Ativa? A Certidão da Dívida Ativa (CDA) é o documento oficial emitido pelo Estado do Espírito Santo que formaliza a inscrição de um débito em dívida ativa — o registro definitivo do crédito após a fase administrativa de cobrança, e o que habilita a cobrança judicial (execução fiscal) do débito. O número da certidão (numero_cda) identifica o débito inscrito e é a chave desta emissão.

Quando usar a emissão por CDA? Utilize POST /2/dua/emissao-cda quando o contribuinte já possui a CDA: o DUA-e é gerado diretamente a partir do numero_cda, sem consulta de área/serviço e sem seleção de notas, porque o débito já está formalizado na certidão. Débitos sem CDA devem ser emitidos por POST /2/dua/emissao — Saiba mais.

Parâmetros da requisição:

Exemplo de requisição: emissão de um DUA-e de dívida ativa a partir do número da CDA

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/dua/emissao-cda

{
  "ambiente": 1,
  "url_notificacao": "https://seudominio.com.br/webhook/dua",
  "documento_contribuinte": "12345678000195",
  "numero_cda": "99992099"
}

Exemplo de resposta: resposta imediata — o processamento é assíncrono e o desfecho final chega pelo webhook

{
  "status": "processando",
  "message": "Emissão em processamento. Consulte novamente em alguns instantes.",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Os campos da tabela abaixo compõem o response retornado quando o DUA-e CDA é aprovado (disponível na resposta armazenada e em GET /2/dua/status/{uuid}) — não na resposta imediata acima.

Serviços
Consulta de DUA-e

Consulta as informações de um DUA-e já emitido. O retorno contém dados do órgão, área, serviço, receita, contribuinte, datas, valores e situação de pagamento.

Parâmetros da requisição:

Exemplo de requisição: consulta de um DUA-e pelo número do documento e pelo identificador do cliente

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/dua/consulta

{
  "ambiente": 1,
  "numero_guia": "0000000000",
  "cnpj": "00000000000000"
}

Os campos retornados na resposta estão descritos a seguir:

Exemplo de resposta: dados completos do DUA-e consultado — envelope, órgão, área, serviço, receita, contribuinte, datas, valores e pagamento

{
  "ambiente": 1,
  "data_retorno": "2026-07-14T18:30:29",
  "protocolo": "00000000-aaaa-0000-aaaa-000000000000",
  "tempo_processamento": 186,
  "codigo_retorno": 104,
  "descricao_retorno": "Consulta Dua realizada com sucesso",
  "guia": {
    "numero_guia": "0000000000",
    "data_emissao": "2026-07-14T15:18:16",
    "linha_digitavel": "85870000000601120007202730811...",
    "qrcode_payload": "00020126920014br.gov.bcb.pix2570p...",
    "data_referencia": "2026-01",
    "data_vencimento": "2026-02-15",
    "data_pagamento": "2026-07-14",
    "valor_multa": 0.05,
    "valor_juros": 0.07,
    "valor_atualizacao": 0.00,
    "valor_credito": 0.00,
    "valor_total": 1.12,
    "orgao": {
      "cnpj": "27080571000130",
      "nome": "Secretaria de Estado da Fazenda",
      "sigla": "SEFAZ",
      "codigo": 1
    },
    "area": {
      "nome": "Receita de ICMS",
      "codigo": 1902
    },
    "servico": {
      "nome": "ICMS - Diferencial de Alíquota ...",
      "codigo": 3867
    },
    "receita": {
      "codigo": 3867,
      "valor": 1.00
    },
    "contribuinte": {
      "cnpj": "00000000000000",
      "razao_social": "Empresa Exemplo LTDA"
    },
    "pagamento": {
      "codigo": 1,
      "data_autenticacao": "2026-07-14",
      "agencia": "0675",
      "autenticacao": "0675PIX-00000000000000",
      "forma": 1,
      "tipo_captura": 9,
      "banco": "021"
    }
  }
}

Serviços
Obtenção de PDF do DUA-e

Obtém a representação gráfica (PDF) de um DUA-e emitido, retornada em base64.

Parâmetros da requisição:

Exemplo de requisição: obtenção do PDF de um DUA-e pelo número do documento

curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
"https://api.webmania.com.br/2/dua/pdf/0000000000?ambiente=1&cnpj=00000000000000"

Os campos retornados na resposta estão descritos a seguir:

Exemplo de resposta: o PDF do DUA-e devolvido em base64

{
  "ambiente": 1,
  "data_retorno": "2026-07-14T18:49:09",
  "protocolo": "00000000-aaaa-0000-aaaa-000000000000",
  "tempo_processamento": 613,
  "codigo_retorno": 106,
  "descricao_retorno": "PDF do Dua obtido com sucesso",
  "pdf_base64": "JVBERi0xLjQKMSAwIG9iago8PAovVGl0bGUgKP7/AEQAV..."
}

Serviços
Consulta de Área e Serviço

Consulta as áreas e serviços disponíveis de determinado órgão credenciado na SEFAZ/ES. Úteis para descobrir o codigo_area e codigo_servico antes da emissão.

Parâmetros da requisição:

Exemplo de requisição: as áreas e serviços do órgão credenciado

curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
"https://api.webmania.com.br/2/dua/area-servico?ambiente=1&cnpj=28161362000183"

Os campos presentes na resposta:

Exemplo de resposta: áreas, serviços e receitas do órgão consultado

{
  "status": "aprovado",
  "ambiente": 1,
  "data_retorno": "2026-07-14T19:06:08",
  "protocolo": "00000000-aaaa-0000-aaaa-000000000000",
  "tempo_processamento": 121,
  "codigo_retorno": 101,
  "descricao_retorno": "Consulta Area e Servico realizada com sucesso",
  "orgao": {
    "cnpj": "28161362000183",
    "nome": "Departamento de Imprensa Oficial",
    "sigla": "DIO",
    "area": [
      {
        "cod": 269,
        "desc": "Outras Receitas",
        "servico": [
          { "cod": 19442, "desc": "Outras receitas", "codigo_receita": 2411 }
        ]
      },
      {
        "cod": 278,
        "desc": "Venda de Jornais",
        "servico": [
          { "cod": 21849, "desc": "Jornal Atrasado", "codigo_receita": 4553 },
          { "cod": 21850, "desc": "Jornal do Dia", "codigo_receita": 4553 }
        ]
      }
    ]
  }
}

Serviços
Consulta de Município

Consulta a lista de municípios utilizados pelo serviço DUA-e da SEFAZ/ES.

Parâmetros da requisição:

Exemplo de requisição: a lista de municípios atendidos pelo serviço DUA-e

curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
"https://api.webmania.com.br/2/dua/municipio?ambiente=1"

Os campos presentes na resposta:

Exemplo de resposta: municípios retornados pela SEFAZ/ES

{
  "status": "aprovado",
  "ambiente": 1,
  "data_retorno": "2026-07-14T19:20:14",
  "protocolo": "00000000-aaaa-0000-aaaa-000000000000",
  "tempo_processamento": 102,
  "codigo_retorno": 103,
  "descricao_retorno": "Consulta Municipio realizada com sucesso",
  "municipio": [
    { "cod": 56014, "desc": "AFONSO CLAUDIO" },
    { "cod": 57177, "desc": "AGUA DOCE DO NORTE" },
    { "cod": 57053, "desc": "VITORIA" }
  ]
}

Serviços
Consulta do Valor do Serviço

Consulta o valor de determinado serviço de um órgão, área e código de serviço. Úteis para calcular o valor antes da emissão.

Parâmetros da requisição:

Exemplo de requisição: o valor de um serviço de um órgão credenciado

curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
"https://api.webmania.com.br/2/dua/valor-servico?ambiente=1&cnpj=27080571000130&codigo_area=297&codigo_servico=11092&quantidade=1"

Os campos presentes na resposta:

Exemplo de resposta: valor do serviço consultado

{
  "status": "aprovado",
  "ambiente": 1,
  "data_retorno": "2026-07-14T19:33:42",
  "protocolo": "00000000-aaaa-0000-aaaa-000000000000",
  "tempo_processamento": 154,
  "codigo_retorno": 102,
  "descricao_retorno": "Consulta Valor do Servico realizada com sucesso",
  "orgao": {
    "cnpj": "27080571000130",
    "nome": "Secretaria de Estado da Fazenda",
    "sigla": "SEFAZ",
    "area": {
      "cod": 297,
      "desc": "Requerimentos",
      "servico": {
        "cod": 11092,
        "desc": "Isencao de IPVA Para Deficiente",
        "codigo_receita": 2097,
        "valor": 73.03
      }
    }
  }
}

Serviços
Consulta de DUA-e Pago

Consulta os DUA-e pagos de um contribuinte em um período. O retorno pode ser descompactado (array pagamentos) ou compactado em base64 (pagamentos_base64) conforme o indicador compactar.

Parâmetros da requisição:

Exemplo de requisição: consulta os DUA-e pagos do contribuinte no período informado

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
https://api.webmania.com.br/2/dua/pagos

{
  "ambiente": 1,
  "compactar": 0,
  "cnpj": "00000000000000",
  "periodo": {
    "data_inicio": "2026-07-01",
    "data_fim": "2026-07-14"
  }
}

A resposta descompactada (compactar=0) devolve o envelope padrão — status, ambiente, data_retorno, protocolo, tempo_processamento, compactar, codigo_retorno e descricao_retorno — e o array pagamentos com um item por pagamento localizado. Campos de cada item de pagamentos[] (e do formato compactado pagamentos_base64):

Exemplo de resposta: um pagamento localizado no período consultado

{
  "status": "aprovado",
  "ambiente": 1,
  "data_retorno": "2026-07-14T18:30:10",
  "protocolo": "00000000-aaaa-0000-aaaa-000000000000",
  "tempo_processamento": 130,
  "compactar": 0,
  "codigo_retorno": 108,
  "descricao_retorno": "Pagamentos localizados",
  "pagamentos": [
    {
      "numero_guia": "0000000000",
      "tp_pess": 2,
      "documento_contribuinte": "00000000000000",
      "nome_orgao": "Secretaria de Estado da Fazenda",
      "nome_area": "Receita de ICMS",
      "nome_servico": "ICMS - Diferencial de Aliquotas",
      "codigo_receita": 3867,
      "nome_municipio": "VITORIA",
      "valor_receita": 1.00,
      "valor_multa": 0.05,
      "valor_juros": 0.07,
      "valor_atualizacao": 0.00,
      "banco": "021",
      "agencia": "0675",
      "data_autenticacao": "2026-07-14",
      "forma_recebimento": "9",
      "informacoes_complementares": "DUA EXEMPLO"
    }
  ]
}

Serviços
Consulta de Status

Consulta o status de uma emissão DUA-ES pelo uuid retornado na emissão. Endpoint: GET /2/dua/status/{uuid}. Prefira a notificação por webhook — ela chega assim que o desfecho existe.

A resposta base é:

{
  "status": "processando",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider_identifier": null
}

Os campos variam conforme o status:

Além dos campos por status, a resposta inclui campos adicionais ligados à origem da emissão, quando presentes:

Exemplo — status erro_comunicacao (resultado incerto; não dispara webhook):

{
  "status": "erro_comunicacao",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider_identifier": null,
  "message": "Status incerto. A guia pode ter sido emitida antes da falha de comunicação. Consulte a SEFAZ manualmente. Não reenvie a emissão antes dessa confirmação, para evitar um documento fiscal em duplicidade."
}

Códigos de Retorno

Além destes códigos, toda falha é retornada no envelope de erro JSON {"error": "..."} (com motivos_rejeicao quando a SEFAZ/ES devolve motivo) — a tabela abaixo detalha os códigos que aparecem no DUA.

A tabela a seguir apresenta os códigos de retorno (codigo_retorno) do Web Service DUA-e da SEFAZ/ES, agrupados por tipo de serviço. Em caso de rejeição, o campo descricao_retorno contém a descrição correspondente.

Mensagens de Sucesso

Sobre o código 107. A SEFAZ/ES não define o codigo_retorno 107 no catálogo oficial do Web Service — o Anexo II do Manual de Integração passa de 106 diretamente para 108. Nenhum serviço documentado do DUA-e o devolve; se ele aparecer em uma resposta, entre em contato com o suporte informando o protocolo da operação.

Mensagens de Erro Genéricas

Mensagens de Erro – Consulta de Área e Serviço

Mensagens de Erro – Consulta do Valor do Serviço

Sobre 406 e 407 — e, na emissão, 706 e 710. As quatro mensagens significam o mesmo para a sua integração: o serviço (codigo_servico) não foi encontrado para a área e o órgão informados. As qualificações "(item)" e "(serviço)" são distinções internas da SEFAZ/ES, sem definição publicada no manual — a correção é idêntica nos códigos: confirme cnpj_orgao/cnpj, codigo_area e codigo_servico exatamente como retornados pela consulta de Área e Serviço.

O que é uma taxa? O Web Service distingue os serviços do tipo taxa — valor tabelado e fixo, publicado pela SEFAZ/ES no portal do DUA-e — dos demais serviços, cujo valor é calculado a partir da quantidade (quantidade). O código 409 informa que o serviço consultado não é uma taxa: confira a combinação cnpj/codigo_area/codigo_servico retornada pela consulta de Área e Serviço.

Mensagens de Erro – Consulta de DUA

Mensagens de Erro – Emissão de DUA

Mensagens de Erro – Obter PDF

Erro inesperado — 999

Política de repetição para o 999. Em operações de leitura (consultas), aguarde alguns instantes e repita a requisição. Em emissões, o desfecho chega pela notificação: entre em contato com o suporte antes de reenviar — como o DUA-e não tem cancelamento, é preciso confirmar que a SEFAZ/ES não gerou nada antes de uma nova emissão.

Infraestrutura

Os servidores da Webmania® estão localizados na Amazon AWS, líder global em cloud computing, na região us-east-1 (Leste dos EUA) com ponto de presença em sa-east-1 (São Paulo). Manter a sua estrutura perto de uma dessas duas localidades, garante um menor tempo de resposta nas requisições na API.

Utilizamos uma infraestrutura na Amazon AWS anycast de alta disponibilidade, o que significa que ao se comunicar com a API da Webmania® a requisição será redirecionada para o servidor mais próximo da sua localidade. As requisições dos endpoints são gerenciadas através de IPs estáticos, caso necessite autorize no firewall a comunicação com os IPs abaixo.

• 13.248.145.90
• 76.223.17.240

• 34.196.69.38
• 44.219.142.86

Limite de requisições

A API da Webmania® aplica limites de solicitação por método HTTP para evitar o mal uso da API e a sobrecarga dos servidores. Quando o limite é excedido, a requisição retorna erro 429 (Too Many Requests). Segue abaixo as especificações para uma correta integração:

• Taxas por requisição:
  - GET: 15 requisições por segundo.
  - POST: sem limite de requisições.
  - PUT/DELETE: 5 requisições por segundo.
  Precisa de um volume maior de requisições? Por favor, entre em contato para liberação.
• Localização do servidor: O firewall bloqueia por padrão o IP de servidores em regiões com alto índice de ataques ou de baixa reputação. Caso a sua comunicação via GET no endpoint https://webmania.com.br/api/ ou https://api.webmania.com.br retorne 403 Erro Forbidden por engano, por favor, entre em contato para liberarmos o IP do seu servidor.
• Credenciais de acesso: Os endpoints exigem as credenciais de acesso válida e correta na HEADER da requisição, o envio incorreto é atribuído como uso indevido da API.
• URL de notificação: Realize a integração para obter todos os retornos da API via URL de notificação, dessa forma todos os processos podem ser realizados ao receber o retorno, como atualizar o banco de dados e o download do PDF da guia.