REST API Gerencial B2B

Guia Rápido

Todas as solicitações na API devem ser realizadas em ambiente criptografado HTTPS através da URL https://webmaniabr.com/api/. O prefixo /1/ indica que atualmente nós 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 indica falhas. Quando uma requisição ocorre falha, o corpo da resposta [body] continua no formato JSON, mas sempre contém o campo error. Por exemplo, caso a sua autenticação não seja bem sucedida irá retornar 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 solicitaçõ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 mobile iOS e Android recomendamos que o processo de emissão seja realizado no servidor (back-end). No 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://webmaniabr.com/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:

[
  {
    "id": "1234",
    "consumer_key": "SEU_CONSUMER_KEY",
    "consumer_secret": "SEU_CONSUMER_SECRET",
    "access_token": "SEU_ACCESS_TOKEN",
    "access_token_secret": "SEU_ACCESS_TOKEN_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",
  },
  {
    "id": "1236",
    "consumer_key": "SEU_CONSUMER_KEY",
    "consumer_secret": "SEU_CONSUMER_SECRET",
    "access_token": "SEU_ACCESS_TOKEN",
    "access_token_secret": "SEU_ACCESS_TOKEN_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://webmaniabr.com/api/1/b2b/empresas/

A resposta do corpo da mensagem será uma 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"
    },
  },
  {
    "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"
    },
   },
  ...
]

Consultar Requisições

Para consultar o uso das requisições da API, envie a 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 atual.

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://webmaniabr.com/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

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 IP's estáticos, caso necessite autorize no firewall a comunicação com os seguintes IP's:

• 13.248.145.90
• 76.223.17.240

Limite de requisições

A API de Nota Fiscal da Webmania® não possui limite de requisições, porém existem regras automáticas realizadas pelo Firewall para evitar o mal uso da API e a sobrecarga nos servidores. O uso incorreto da API pode gerar o erro 503 ou 403 no retorno do cabeçalho da requisição. Segue abaixo as especificações para uma correta integração:

• Localização do servidor: O firewall bloqueia por padrão o IP de servidores em regiões com alto índice de ataques, como na Europa e na Ásia oriental. Caso a sua comunicação via GET no endpoint https://webmaniabr.com/api/ retorne 403 Erro Forbidden 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.
• Requisições GET: O método GET deve ser utilizado de forma sistemática, o recomendado é até 2 solicitações por segundo. Um alto índice de requisições via GET é atribuído como uso indevido da API.