[PITCH] Consulte notas fiscais através de nossa API 😎
🧭 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:
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