REST API Gerencial B2B

Guia Rápido

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

Todas as respostas são no formato objeto JSON.

Uma requisição bem-sucedida é indicada através do status HTTP. O status 2xx indica sucesso, enquanto os status 4xx indicam falhas. Quando uma requisição falha, o corpo da resposta [body] continua no formato JSON, mas sempre contém o campo error. Por exemplo, caso sua autenticação não seja bem-sucedida, será retornada a seguinte mensagem:

{
  "error": "Access Token e Access Token Secret não conferem."
}

Autenticação

A credencial de acesso está disponível na aba Credenciais no menu Configurações em cada empresa cadastrada. Visualize a sua credencial, clique aqui.

Para as requisições, o corpo da requisição [body] deve ser enviado no formato JSON com o header Content-Type definido para application/json.

A autenticação é realizada através do cabeçalho HTTP (HTTP headers). É necessário o envio do X-Consumer-Key e X-Consumer-Secret da sua aplicação, juntamente com o X-Access-Token e X-Access-Token-Secret do seu usuário.

Mantenha as credenciais de acesso em segurança. Nunca publique as credenciais de acesso no código fonte do site, aplicativo ou software onde o usuário possa ter fácil acesso.

Para aplicativos móveis iOS e Android, recomendamos que o processo de emissão seja realizado no servidor (back-end). O código fonte do aplicativo deve possuir somente a solicitação de emissão, enquanto o processo deve ser realizado em seu servidor.

Criar novas empresas

Para cadastrar novas empresas, envie a requisição com o método POST para a URL /1/b2b/empresas/ contendo apenas o parâmetro quantidade com o número de empresas que deseja abrir.

Segue abaixo exemplo da abertura de novas empresas:

curl -X POST \
-H "X-Consumer-Key: SEU_CONSUMER_KEY_REVENDEDOR" \
-H "X-Consumer-Secret: SEU_CONSUMER_SECRET_REVENDEDOR" \
-H "X-Access-Token: SEU_ACCESS_TOKEN_REVENDEDOR" \
-H "X-Access-Token-Secret: SEU_ACCESS_TOKEN_SECRET_REVENDEDOR" \
-H "Content-Type: application/json" \
-d '{
    "quantidade": 3
}' \
https://webmania.com.br/api/1/b2b/empresas/

A resposta do corpo da mensagem será no formato objeto JSON, contendo os campos id, consumer_key, consumer_secret, access_token, access_token_secret e bearer_access_token:

[
  {
    "id": "1234",
    "consumer_key": "SEU_CONSUMER_KEY",
    "consumer_secret": "SEU_CONSUMER_SECRET",
    "access_token": "SEU_ACCESS_TOKEN",
    "access_token_secret": "SEU_ACCESS_TOKEN_SECRET",
    "bearer_access_token": "SEU_BEARER_ACCESS_SECRET",
  },{
    "id": "1235",
    "consumer_key": "SEU_CONSUMER_KEY",
    "consumer_secret": "SEU_CONSUMER_SECRET",
    "access_token": "SEU_ACCESS_TOKEN",
    "access_token_secret": "SEU_ACCESS_TOKEN_SECRET",
    "bearer_access_token": "SEU_BEARER_ACCESS_SECRET"
  },
  {
    "id": "1236",
    "consumer_key": "SEU_CONSUMER_KEY",
    "consumer_secret": "SEU_CONSUMER_SECRET",
    "access_token": "SEU_ACCESS_TOKEN", 
    "access_token_secret": "SEU_ACCESS_TOKEN_SECRET",
    "bearer_access_token": "SEU_BEARER_ACCESS_SECRET"
  }
]

Com as credenciais de acesso, as informações das empresas podem ser alteradas através do endpoint /1/nfe/empresa/. Visualizar documentação.

Listar empresas

Para listar as empresas cadastradas, envie uma requisição utilizando o método GET para a URL /1/b2b/empresas/. A resposta do corpo da mensagem será uma array no formato JSON, contendo os seguintes campos:

Segue abaixo exemplo para listar as empresas:

curl -X GET \
-H "X-Consumer-Key: SEU_CONSUMER_KEY_REVENDEDOR" \
-H "X-Consumer-Secret: SEU_CONSUMER_SECRET_REVENDEDOR" \
-H "X-Access-Token: SEU_ACCESS_TOKEN_REVENDEDOR" \
-H "X-Access-Token-Secret: SEU_ACCESS_TOKEN_SECRET_REVENDEDOR" \
-H "Content-Type: application/json" \
https://webmania.com.br/api/1/b2b/empresas/

A resposta do corpo da mensagem será um array no formato JSON:

[
  {
    "id": "1234",
    "razao_social": "Nome da empresa LTDA",
    "cnpj": "00000000000000",
    "ie": "0000000000",
    "unidade_empresa": "matriz",
    "tipo_tributacao": "simples_nacional",
    "credenciais": {
        "consumer_key": "SEU_CONSUMER_KEY",
        "consumer_secret": "SEU_CONSUMER_SECRET",
        "access_token": "SEU_ACCESS_TOKEN",
        "access_token_secret": "SEU_ACCESS_TOKEN_SECRET",
        "bearer_access_token": "SEU_BEARER_ACCESS_SECRET"
    },
  },
  {
    "id": "1235",
    "nome_completo": "Nome da empresa LTDA",
    "cpf": "00000000000",
    "ie": "0000000000",
    "unidade_empresa": "matriz",
    "tipo_tributacao": "simples_nacional",
    "credenciais": {
        "consumer_key": "SEU_CONSUMER_KEY",
        "consumer_secret": "SEU_CONSUMER_SECRET",
        "access_token": "SEU_ACCESS_TOKEN",
        "access_token_secret": "SEU_ACCESS_TOKEN_SECRET",
        "bearer_access_token": "SEU_BEARER_ACCESS_SECRET"
    },
   },
  ...
]

Consultar Requisições

Para consultar o uso das requisições da API, envie uma requisição no método GET para a URL /1/b2b/requests/. É possível informar os parâmetros mes e ano para consulta em um período específico. Caso esses parâmetros não sejam informados, será utilizado o mês e ano atuais.

Segue abaixo exemplo para consultar requisições:

curl -X GET \
-H "X-Consumer-Key: SEU_CONSUMER_KEY_REVENDEDOR" \
-H "X-Consumer-Secret: SEU_CONSUMER_SECRET_REVENDEDOR" \
-H "X-Access-Token: SEU_ACCESS_TOKEN_REVENDEDOR" \
-H "X-Access-Token-Secret: SEU_ACCESS_TOKEN_SECRET_REVENDEDOR" \
-H "Content-Type: application/json" \
https://webmania.com.br/api/1/b2b/requests/?mes=01&ano=2022

A resposta do corpo da mensagem será no formato objeto JSON:

{
    "total_notas_processadas": 12000,
    "empresas": [
        {
          "cnpj": "00000000000000",
          "razao_social": "Empresa 1",
          "ie": "0000000000",
          "notas_processadas": 7000,
        },
        {
          "cpf": "00000000000",
          "nome_completo": "Empresa 2",
          "ie": "0000000000",
          "notas_processadas": 5000,
        },
        ...
    ]
}

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.
  - Exceção de segurança (SEFAZ/prefeitura): os endpoints de eventos dos documentos fiscais, como cancelamento, carta de correção, manifestação e etc, são limitados a 1 requisição por segundo, em qualquer método HTTP.
  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 Danfe e XML.