REST API de Declaração de Conteúdo Eletrônica

Guia Rápido

Todas as solicitações na API devem ser realizadas em ambiente criptografado HTTPS através da URL https://api.webmania.com.br. O prefixo /2/ indica que atualmente estamos utilizando a versão 2.0 da API.

Módulos & Exemplos

Realize a emissão com apenas um clique na sua Loja Virtual através dos módulos da Webmania® ou realize a integração para os diversos tipos de linguagens de programação.

• Ferramentas
  • 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 pode ser obtido no painel da Webmania® e deve ser incluído em todas as requisições.

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, garantindo clareza e facilidade de interpretação.

A tabela abaixo apresenta os códigos de status HTTP que a API pode retornar com suas respectivas descrições. Esses códigos indicam o resultado da operação solicitada e ajudam a entender se a requisição foi bem-sucedida ou se ocorreu alguma falha.

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

{
  "error": "Parâmetro inválido: cnpj. O valor ABCD não é um CNPJ válido."
}

Notificações

Para que a sua plataforma se mantenha sempre atualizada, a Webmania disponibiliza as notificações automáticas para todos os status do DC-e.

Cada DC-e possui um identificador único chamado de UUID. Este identificador deve ser utilizado para recepcionar e identificar o DC-e para atualizar as informações no seu banco de dados.

No momento em que for realizada a emissão do DC-e, caso tenha informado o parâmetro url_notificacao, será enviado o retorno no formato POST para a URL especificada, contendo no corpo os parâmetros ID, uuid, chave, serie, numero, status, motivo, modelo, xml, xml_cancelamento, dace e log.

A requisição via POST é realizada no formato application/json:

-X POST \
-header "Content-type: application/json" \

Segue exemplo do retorno via POST:

{
  "ID": "PED-123",
  "uuid": "00000000-0000-0000-0000-000000000000",
  "chave": "00000000000000000000000000000000000000000000",
  "serie": 1,
  "numero": 123,
  "status": "aprovado",
  "motivo": "Autorizado o uso do DC-e",
  "modelo": "dce",
  "xml": "https://api.webmania.com.br/xmldce/[chave]",
  "dace": "https://api.webmania.com.br/dace/[chave]",
  "log": { ... }
}

Emissão de DC-e

A Declaração de Conteúdo Eletrônica (DC-e) é um documento digital que substitui a antiga declaração de conteúdo em papel. Ela é utilizada para documentar o transporte de bens e mercadorias quando não há exigência de documento fiscal (NF-e, NFC-e, etc.).

A DC-e pode ser emitida por pessoas físicas ou jurídicas não contribuintes do ICMS. Após a autorização pela SEFAZ, é gerado o DACE (Declaração Auxiliar de Conteúdo Eletrônica), que deve acompanhar a mercadoria durante o transporte.

Para emitir, envie uma requisição POST para /2/dce/emissao com os dados no formato JSON:

curl -X POST \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "ID": "PED-123",
  "ambiente": 2,
  "url_notificacao": "https://suaaplicacao.com.br/webhook/dce",
  "emitente": {
    "cnpj": "12345678000195",
    "razao_social": "EMPRESA EMISSORA LTDA",
    "logradouro": "Rua A",
    "numero": "100",
    "bairro": "Centro",
    "codigo_municipio": "4106902",
    "municipio": "Curitiba",
    "uf": "PR",
    "cep": "80000000"
  },
  "cliente": {
    "cnpj": "12345678000195",
    "razao_social": "CLIENTE LTDA",
    "logradouro": "Rua B",
    "numero": "200",
    "bairro": "Centro",
    "codigo_municipio": "3550308",
    "municipio": "São Paulo",
    "uf": "SP",
    "cep": "01001000"
  },
  "itens": [
    {
      "descricao": "Frete",
      "ncm": "99000000",
      "quantidade": 1,
      "valor_unitario": 100.00
    }
  ],
  "transporte": {
    "modalidade": "0"
  },
  "informacoes_adicionais": "Observações gerais"
}' \
https://api.webmania.com.br/2/dce/emissao

A resposta será no formato JSON. Consulte a seção de Notificações para a descrição completa de cada campo.

{
  "ID": "PED-123",
  "uuid": "00000000-0000-0000-0000-000000000000",
  "chave": "00000000000000000000000000000000000000000000",
  "serie": 1,
  "numero": 123,
  "status": "aprovado",
  "motivo": "Autorizado o uso do DC-e",
  "modelo": "dce",
  "xml": "https://api.webmania.com.br/xmldce/[chave]",
  "dace": "https://api.webmania.com.br/dace/[chave]",
  "log": { ... }
}

Emissão de DC-e
Informações Gerais

Os parâmetros abaixo compõem o corpo principal da requisição de emissão. Clique no nome dos campos destacados para ver os detalhes de cada seção.

Emissão de DC-e
Emitente

O emitente é a pessoa física ou jurídica que está remetendo o bem ou mercadoria ao destinatário. Envie os dados no objeto emitente.

Para identificação, informe apenas uma das opções: cnpj, cpf ou identificacao_alternativa. De acordo com o tipo de identificação, o campo de nome também muda:

• CNPJ: informe razao_social
• CPF ou Identificação alternativa: informe nome_completo

Autopreenchimento por CEP: os campos logradouro, bairro, codigo_municipio, municipio e uf são preenchidos automaticamente quando o cep informado for válido e localizável.

Exemplo de emitente pessoa jurídica:

{
  "emitente": {
    "cnpj": "00000000000000",
    "razao_social": "Empresa Logistica Ltda",
    "logradouro": "Avenida Paulista",
    "numero": "1000",
    "bairro": "Bela Vista",
    "codigo_municipio": "3550308",
    "municipio": "Sao Paulo",
    "uf": "SP",
    "cep": "01310100",
    "telefone": "1130000000"
  }
}

Emissão de DC-e
Cliente

O cliente é o destinatário do bem ou mercadoria. Envie os dados no objeto cliente.

A regra de identificação é a mesma do emitente: informe apenas uma das opções (cnpj, cpf ou identificacao_alternativa), com o respectivo campo de nome.

Autopreenchimento por CEP: os campos logradouro, bairro, codigo_municipio, municipio e uf são preenchidos automaticamente quando o cep informado for válido e localizável.

Exemplo de cliente pessoa jurídica:

{
  "cliente": {
    "cnpj": "00000000000000",
    "razao_social": "Empresa Comercial Ltda",
    "email": "fiscal@empresacomercial.com.br",
    "logradouro": "Rua da Bahia",
    "numero": "550",
    "bairro": "Centro",
    "codigo_municipio": "3106200",
    "municipio": "Belo Horizonte",
    "uf": "MG",
    "cep": "30160011",
    "telefone": "3130000000"
  }
}

Emissão de DC-e
Itens

Os itens representam os bens ou mercadorias transportados. Envie os dados em um array no parâmetro itens, com no mínimo 1 e no máximo 999 itens.

Limites de valor: o valor total de cada item (quantidade × valor unitário) não pode exceder R$ 100.000,00. A soma de todos os itens da DC-e não pode exceder R$ 200.000,00.

Exemplo com dois itens:

{
  "itens": [
    {
      "descricao": "Cafe torrado e moido 500g",
      "ncm": "09012100",
      "quantidade": 120,
      "valor_unitario": 18.9,
      "informacoes_adicionais": "Lote 202603A"
    },
    {
      "descricao": "Filtro de papel tamanho 103 com 30 unidades",
      "ncm": "48232099",
      "quantidade": 80,
      "valor_unitario": 6.5
    }
  ]
}

Emissão de DC-e
Transporte

Informe como a mercadoria será transportada no objeto transporte.

Exemplo de transporte por empresa transportadora:

{
  "transporte": {
    "modalidade": "2",
    "cnpj_transportadora": "19131243000197"
  }
}

Emissão de DC-e
Informações Adicionais

Todos os campos desta seção são opcionais e permitem incluir observações complementares no documento. A DC-e oferece dois níveis de informações adicionais:

• Gerais (informacoes_adicionais e observacoes): visíveis para o destinatário e o fisco.
• Do emitente (informacoes_adicionais_emitente e observacoes_emitente): de interesse do emissor.

Emissão de DC-e > Informações Adicionais
Observações

Cada item dos arrays observacoes e observacoes_emitente deve conter os campos campo e texto:

Exemplo utilizando todos os campos de informações adicionais:

{
  "informacoes_adicionais": "Entrega agendada para o periodo da manha.",
  "observacoes": [
    {
      "campo": "PEDIDO",
      "texto": "Pedido interno 78954"
    },
    {
      "campo": "CONTATO",
      "texto": "Recebimento com Joao"
    }
  ],
  "informacoes_adicionais_emitente": "Documento emitido para controle logistico.",
  "observacoes_emitente": [
    {
      "campo": "ORDEM",
      "texto": "Ordem de coleta 45678"
    }
  ]
}

Funções
Download XML e PDF da Nota Fiscal

Na Webmania, a segurança da informação é nossa prioridade máxima. Por esse motivo, aplicamos restrições de acesso aos arquivos XML e PDF para garantir a segurança dos documentos fiscais.

O documento fiscal é criptografado com senha, e só pode ser visualizado após a confirmação do CPF/CNPJ do tomador da nota fiscal ou conforme formas de autenticação através do IP emissor, Credenciais de acesso, Token ou Conectado no painel Webmania®.

Segue abaixo as condições de acesso disponibilizados, após as restrições serem aplicadas:

Funções > Download XML e PDF da Nota Fiscal
Credenciais de acesso

Ao enviar as credenciais de acesso da empresa na HEADER da requisição, podem ser acessados todos os documentos fiscais emitidos pela empresa. Segue abaixo exemplo de como visualizar o PDF, utilizando as credenciais de acesso:

curl -X GET \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
https://api.webmania.com.br/dace/00000000000000000000000000000000000000000000

A resposta do corpo da mensagem será no formato application/pdf ou text/xml, contendo no corpo da requisição o arquivo.

Funções > Download XML e PDF da Nota Fiscal
Token

Para disponibilizar o link do PDF e XML com segurança e eliminar a exigência da senha, é necessário a geração do token de forma criptografada utilizando a camada de segurança AES-256-CBC. Após gerar o token, deve ser enviado na URL do arquivo. Segue abaixo exemplo:

https://api.webmania.com.br/dace/00000000000000000000000000000000000000000000?token=[TOKEN]

Pare gerar o token criptografado, verifique o passo a passo disponibilizado no Github da Webmania juntamente com as funções nas linguagens em PHP, Python, Java, C# e Ruby: https://github.com/webmaniabr/DFeToken.

Infraestrutura

O 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 algumas das 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 API da Webmania a requisição será redirecionada para o servidor mais próximo da sua localidade. As requisições dos endpoints são gerenciados 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

API da Webmania® é protegida por um firewall que identifica de forma automática os acessos indevidos, suspeitos, credenciais incorretas e a localização da requisição, onde também pode limitar solicitações por segundo e o total de requisições para evitar o mal uso da API e a sobrecarga dos servidores. O uso indevido da API pode gerar mensagens de erro 503 ou 403 no retorno do cabeçalho da requisição. Segue abaixo especificações para uma correta integração:

• Localização do servidor: O firewall bloqueia por padrão o IP de servidores suspeitos 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.
• Limite de requisições:
  - GET: 4.500 requisições a cada 5 minutos (15/reqs/s).
  - POST/PUT/DELETE: 10.000 requisições a cada 5 minutos (30/reqs/s).
  Precisa de um volume maior de requisições? Por favor, entre em contato para liberação.
• 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 Danfe e XML.