🧭 Obtendo informações de uma Nota Fiscal Eletrônica

Minha ideia

Esse serviço é parte de uma API que estou criando, e o objetivo dela é ser um gateway de informações sobre o Brasil que ainda não são muito bem providas pelos sistemas do governo.

Tecnologias e libs usadas

• NextJS;
• MySQL;
• MongoDB;
• puppeteer (para web scrapping com navegador automatizado);
• cheerio.js (para web scrapping usando clients http e query selectors);

Serviços usados

• MySQL as a service através do Planet Scale;
• MongoDB as a service através do MongoDB Atlas;
• Hospedagem no Railway;
• Login com Google OAuth através do Google Cloud;
• Campanhas de anúncios através do Google ADs;
• Relatórios de SEO com Google Search;
• Resolução de DNS e proteção através da Cloudflare;
• Resolução de Captchas:
  • AntiCaptha;
  • 2Captcha;

Abordagem

Focar em simplicidade técnica e baixo custo operacional.

Quais foram/são minhas maiores dificuldades na criação desse serviço?

• Criação da base de dados (com web scrapping e alguns scripts rodando no meu notebook por vários meses kkkk) para os endpoints de ceps;
• Contornar bloqueios de acesso que os sites tem;

Exemplo de uso

Você deve usar a API de NFe's no seguinte padrão:

GET https://brasilaberto.com/api/v1/nfe/{code}

Supondo que você queira buscar uma nota cujo código é 12345123451234512345123451234512345123451234 (esse é um código fictício):

Exemplo com dados da nota ainda processando:

Esse tipo de retorno acontece quando é a primeira vez que você está consultando esse código em nossa API ou os dados da nota ainda não estão
dispoíveis nos portais do governo. Para acompanhar o processamento da nota e saber se seu status foi alterado, basta fazer outras consultas
a esse endpoint (você não será cobrado a mais por isso, a cobrança da consulta só será feita quando ela passar para um status conclusivo).

// GET https://brasilaberto.com/api/v1/nfe/12345123451234512345123451234512345123451234
{
  "meta": {
    "currentPage": 1,
    "itemsPerPage": 1,
    "totalOfItems": 1,
    "totalOfPages": 1
  },
  "result": {
    "status": "PROCESSING"
  }
}

Exemplo com dados da nota já processados:

Esse tipo de retorno acontece quando nosso sistema já processou a nota e conseguiu obter os dados dos portais do governo.

// GET https://brasilaberto.com/api/v1/nfe/123451234512345123451234512345123451234512345 
// OBS.: Alguns dados foram omitidos por questões de privacidade.
{
  "meta": {
    "currentPage": 1,
    "itemsPerPage": 1,
    "totalOfItems": 1,
    "totalOfPages": 1
  },
  "result": {
    "nfe": {
      "model": "55",
      "serie": "1",
      "number": "88307",
      "emission": "2022-02-22T11:34:00.000Z",
      "amount": "832,50"
    },
    "issuer": {
      "cnpj": "99.999.999/9999-99",
      "name": "XPTO COMERCIO",
      "fantasyName": "XPTO",
      "stateRegistration": "127042692118",
      "address": {
        "street": "Avenida XPTO",
        "city": "Cidade do emitente",
        "uf": "UR",
        "zipCode": "99999-999",
        "district": "Bairro do emitente",
        "country": "País do emitente"
      }
    },
    "recipient": {
      "cpf": "999.999.999-99",
      "name": "JOHN DOE",
      "address": {
        "street": "Rua do destinatário",
        "city": "Cidade do destinatário",
        "uf": "UF",
        "zipCode": "99999-999",
        "district": "Bairro do destinatário",
        "country": "País do destinatário"
      }
    },
    "products": [
      {
        "description": "PRODUTO XPTO",
        "code": "834849",
        "ncmCode": "94013090",
        "quantity": "1,0000",
        "unit": "CX",
        "value": "832,50",
        "ean": {
          "taxableCode": "SEM GTIN",
          "commercialCode": "SEM GTIN"
        },
        "pis": {
          "cst": "01 - Operação Tributável (base de cálculo = valor da operação alíquota normal (cumulativo/não cumulativo))",
          "calculationBasis": "832,50",
          "aliquot": "0,6500",
          "value": "5,41"
        },
        "cofins": {
          "cst": "01 - Operação Tributável (base de cálculo = valor da operação alíquota normal (cumulativo/não cumulativo))",
          "calculationBasis": "832,50",
          "aliquot": "3,0000",
          "value": "24,98"
        },
        "icms": {
          "normal": {
            "merchandiseOrigin": "0 - Nacional",
            "icmsTributation": "00 - Tributada integralmente",
            "calculationBasis": "832,50",
            "aliquot": "7,0000",
            "value": "58,28",
            "bcModality": "0 - Margem Valor Agregado(%)"
          },
          "destinationUf": {
            "bcIcms": "832,50",
            "bcFcp": "832,50",
            "fcpIcms": "",
            "fcpPercentage": "",
            "internalAliquot": "17,0000",
            "interstateAliquot": "7,0000",
            "provisionalPercentageOfSharing": "100,0000",
            "interstateICMSValue": "0,00"
          },
          "interstateValueUFSender": "0,00"
        },
        "taxesOverIndustrializedProducts": {
          "framingClass": "",
          "framingCode": "301",
          "producerCnpj": "",
          "cst": "52-Saída isenta",
          "ipi": "",
          "calculationBasis": "",
          "aliquot": "",
          "totalQuantityForStandardUnit": "",
          "valuePerUnit": ""
        }
      }
    ],
    "transport": {
      "modality": "0 - Contratação do Frete por Conta do Remetente",
      "transporter": {
        "cnpj": "99.999.999/9999-99",
        "name": "Nome do transportador",
        "address": {
          "street": "Rua XPTO",
          "city": "São Paulo",
          "uf": "SP"
        }
      },
      "volumes": [
        {
          "quantity": "1",
          "kind": "Tipo do volume do transporte",
          "brand": "MARCA",
          "grossWeight": "13,500"
        },
      ]
    },
    "billing": {
      "invoice": {
        "number": "88307",
        "originalValue": "832,50",
        "discountValue": "0,00",
        "netValue": "832,50"
      },
      "duplicates": [
        {
          "number": "001",
          "expiration": "2022-02-25T03:00:00.000Z",
          "value": "832,50"
        }
      ],
      "paymentMethods": {
        "paymentMethod": "0 - Pagamento à Vista",
        "value": "832,50"
      }
    },
    "code": "123451234512345123451234512345123451234512345",
    "status": "CONCLUDED"
  }
}

Status de retorno

200 Sucesso
500 Erro na nossa API