Executando verificação de segurança...
27

Pitch: Brasil Aberto, uma api muito delicinha 🧭

O que é o projeto?

Estou aqui para falar um pouco do Brasil Aberto, minha nova api. Esse é um projeto que eu comecei por sentir falta de um serviço simples que pudesse me dizer os bairros de cada cidade, e surgiu esse projeto que já conta com consulta de CEP, busca de cidades por estado, busca de bairros por cidade e busca de ruas por bairro, além de rastreio de encomendas, busca de CNPJ e envio de e-mails. Em breve espero, disponibilizar mais serviços.

Detalhes da API

🧭 Obtendo a lista de cidades de um estado

Exemplo de uso

Você deve usar a API de ceps no seguinte padrão:

GET https://brasilaberto.com/api/v1/cities/{stateShortname}

Supondo que você queira buscar as cidades do Rio de Janeiro:

// Esse exemplo mostra somente parte dos resultados
// GET https://brasilaberto.com/api/v1/cities/RJ
{
  "meta": {
    "currentPage": 1,
    "itemsPerPage": 92,
    "totalOfItems": 92,
    "totalOfPages": 1
  },
  "result": [
    {
      "id": 646,
      "ibgeId": null,
      "name": "Rio de Janeiro"
    },
    {
      "id": 647,
      "ibgeId": null,
      "name": "Itaguaí"
    },
    {
      "id": 648,
      "ibgeId": null,
      "name": "Mangaratiba"
    },
    {
      "id": 649,
      "ibgeId": null,
      "name": "Seropédica"
    },
    ...
  ]
}

🏦 Consultando os dados de um CNPJ

Exemplo de uso

Você deve usar a API de consulta de CNPJs no seguinte padrão:

GET https://brasilaberto.com/api/v1/cnpj/{cnpj}

Retorno

// GET https://brasilaberto.com/api/v1/cnpj/18236120000158

{
  "meta": {
    "currentPage": 1,
    "itemsPerPage": 1,
    "totalOfItems": 1,
    "totalOfPages": 1
  },
  "result": {
    "baseCnpj": 18236120,
    "corporateName": "NU PAGAMENTOS S.A. - INSTITUICAO DE PAGAMENTO",
    "legalCode": "2054",
    "legalType": "Sociedade Anônima Fechada",
    "socialCapital": 368732164400,
    "companySizeCode": "05",
    "fantasyName": "",
    "situationCode": "02",
    "activityStart": "2013-06-04T00:00:00",
    "fiscalCnae": "6613400",
    "fiscalCnaeText": "Administração de cartões de crédito",
    "secondaryCnaes": [
      "6209100",
      "7490104",
      "8299799"
    ],
    "addressType": "RUA",
    "address": "CAPOTE VALENTE",
    "number": "39",
    "complement": "",
    "district": "PINHEIROS",
    "zipCode": "05409000",
    "uf": "SP",
    "cityCode": 7107,
    "code": "SAO PAULO"
  }
}

🧭 Obtendo a lista de bairros de uma cidade

Exemplo de uso

Você deve usar a API de ceps no seguinte padrão:

GET https://brasilaberto.com/api/v1/districts/{cityId}

Supondo que você queira buscar os bairros de Nova Iguaçu:

// Esse exemplo mostra somente parte dos resultados
// GET https://brasilaberto.com/api/v1/districts/669
{
  "meta": {
    "currentPage": 1,
    "itemsPerPage": 1910,
    "totalOfItems": 1910,
    "totalOfPages": 1
  },
  "result": [
    {
      "id": 1,
      "name": "Sé"
    },
    {
      "id": 2,
      "name": "Centro"
    },
    {
      "id": 3,
      "name": "Brás"
    },
    {
      "id": 4,
      "name": "República"
    },
    ...
  ]
}

Realizando envio de Emails por API

Exemplo de uso

Você deve usar a API de Email no seguinte padrão:

POST https://brasilaberto.com/api/v1/email/send

Esse é um exemplo supondo que você queira enviar uma mensagem para o destinatário [email protected]
e [email protected]. Os valores permitidos para o atributo destiny são string e array de strings.

Payload

// POST https://brasilaberto.com/api/v1/email/send
{
	"name": "John Doe",
	"sender": "[email protected]",
	"destiny": [
		"[email protected]",
		"[email protected]"
	],
	"message": "Teste2",
  "subject": "Formulário de contato"
}

Retorno

{
  "meta": {
    "currentPage": 1,
      "itemsPerPage": 1,
      "totalOfItems": 1,
      "totalOfPages": 1
  },
  "result": {
    "from": "[email protected]",
    "to": [
      "[email protected]",
    "[email protected]"
    ],
    "messageId": "<[email protected]>"
  }
}

🚀 Consultando os dados de rastreio de uma encomenda

Exemplo de uso

Você deve usar a API de consulta de encomendas no seguinte padrão:

GET https://brasilaberto.com/api/v1/postal-orders/{code}

Retorno

// GET https://brasilaberto.com/api/v1/postal-orders/LB*********HK

{
  "meta": {
    "currentPage": 1,
    "itemsPerPage": 1,
    "totalOfItems": 1,
    "totalOfPages": 1
  },
  "result": [
    {
      "objectCode": "LB*********HK",
      "events": [
        {
          "code": "RO",
          "description": "Objeto em trânsito - por favor aguarde",
          "creation": "2022-01-24T08:57:58",
          "type": "01",
          "unit": {
            "city": "CURITIBA",
            "state": "PR"
          }
        },
        {
          "code": "PAR",
          "description": "Fiscalização aduaneira finalizada",
          "creation": "2022-01-24T08:55:58",
          "type": "10",
          "unit": {
            "city": "CURITIBA",
            "state": "PR"
          }
        }
      ],
      "modality": "V",
      "postalType": {
        "category": "PRIME EXPRÈS",
        "description": "OBJETO INTERNACIONAL PRIME",
        "initials": "LB"
      }
    }
  ]
}

🧭 Obtendo a lista de estados do Brasil

Exemplo de uso

Você deve usar a API de ceps no seguinte padrão. Ela retorna um array contendo as informações
de cada estado.

 GET https://brasilaberto.com/api/states
// Esse exemplo mostra somente parte dos resultados
// GET https://brasilaberto.com/api/states
{
  "meta": {
    "currentPage": 1,
    "itemsPerPage": 27,
    "totalOfItems": 27,
    "totalOfPages": 1
  },
  "result": [
    {
      "name": "Acre",
      "shortName": "AC"
    },
    {
      "name": "Alagoas",
      "shortName": "AL"
    },
    {
      "name": "Amapá",
      "shortName": "AP"
    },
    ...
  ]
}

🧭 Obtendo a lista de ruas de um bairro

Exemplo de uso

Você deve usar a API de ceps no seguinte padrão:

GET https://brasilaberto.com/api/v1/streets/{districtId}

Supondo que você queira buscar pelas ruas do bairro Jardim Palmares:

// Esse exemplo mostra somente parte dos resultados
// GET https://brasilaberto.com/api/streets/549
{
  "meta": {
    "currentPage": 1,
    "itemsPerPage": 95,
    "totalOfItems": 95,
    "totalOfPages": 1
  },
  "result": [
    {
      "id": 1,
      "name": "Praça da Sé"
    },
    {
      "id": 2,
      "name": "Rua Filipe de Oliveira"
    },
    {
      "id": 3,
      "name": "Praça da Sé 108"
    },
    {
      "id": 4,
      "name": "Praça da Sé 371"
    },
    ...
  ]
}

🧭 Obtendo informações de um CEP

Exemplo de uso

Você deve usar a API de ceps no seguinte padrão:

GET https://brasilaberto.com/api/v1/zipcode/{zipcode}

Supondo que você queira buscar o CEP 26277-645:

// GET https://brasilaberto.com/api/v1/zipcode/26277645
{
  "meta": {
    "currentPage": 1,
    "itemsPerPage": 1,
    "totalOfItems": 1,
    "totalOfPages": 1
  },
  "result": {
    "street": "Rua Cajurana",
    "complement": "",
    "district": "Jardim Palmares",
    "districtId": 22687,
    "city": "Nova Iguaçu",
    "cityId": 669,
    "ibgeId": 3303500,
    "state": "Rio de Janeiro",
    "stateShortname": "RJ",
    "zipcode": "26277645"
  }
}
4
3

Primeiramente, muito obrigado!!! Os endpoints de consulta de CEP, CNPJ e rastreio de encomentas não tem limite de uso. Os outros endpoints tem um limite mensal, que será indicado ao criar sua conta. É possivel assinar o plano preemium para ter acesso ilimitado a todos os endpoints, pagando de acordo com o uso e podendo cancelar a qualquer momento. Mas com o plano gratuito, você já pode gerar seu token de acesso e começar a usar. Você pode encontrar mais informações na documentação e no swagger.

brasil-aberto

3

Que projeto sensacional meu caro, meus sinceros parabéns e obrigado por fazer aqui o Pitch com tantos detalhes 😍 🤝

Duas perguntas:

  1. Qual stack você utilizou no projeto para camada de aplicação e persistência?
  2. Qual serviço de email você está utilizando para o endpoint de email?
2
3

Projeto show de bola, parabéns!

Aproveito para deixar aqui uma dúvida para todos vocês que estão trabalhando em APIs para serviços brasileiros (Brasil Aberto e Brasil API): Vocês estão cacheando essas informações para devolver ao consumidor, ou toda vez que alguém busca uma informação o sistema precisa perguntar para um core externo (Como a API do Correios por exemplo)?
E se estão, com quanto tempo estão invalidando essas informações?
Acho importante manter dados recentes quando se trata de dados de endereço e até mesmo de rastreio ou valores de postagem no Correios por exemplo, e dependendo do caso acho que seria legal até mesmo trazer a data da última vez que o sistema atualizou aquela informação, mesmo que não tiver alterado nada, mas só pra informar para o consumidor que aquele dado está atualizado.
Acho que vocês me entederam hahaha!

2

É um ponto interessante, não há cache em todos os endpoints. O cache fica por até 30 dias, mas costuma ser menos, pois são revalidados em background. Há uma área de contato também, para o caso de vc encontrar um CEP incorreto. Em breve haverá mais informações sobre cacheamento das rotas na documentação.

1