Documentação Técnica

1. Visão Geral da Arquitetura

O AXIO é uma plataforma server-side proxy. O browser nunca chama a API RFN diretamente — todas as requisições passam pelo serverless function /api/data, que autentica, encaminha e devolve os dados.

Browser (axio.metadax.com.br)
  │
  │  POST /api/data  { cnpj: "..." }
  │  Header: X-Metadax-Key: {systemId}
  ▼
Vercel Serverless — api/data.js
  │
  ├─► GET metadax.com.br/_functions/systemsStatus?systemId={key}
  │     Valida: systemId === env.METADAX_API_KEY
  │             title    === env.METADAX_APP_URL
  │             license  === "true"
  │
  └─► GET axio.metadax.com.br/api/data?cnpj={cnpj}
        Retorna: { cadastro, localizacao, rating, apiStatus, _meta }
        ▼
      Resposta enriquecida com _coords e _auth
        ▼
Browser ← JSON final

2. Autenticação via systemsStatus

Fluxo de validação

O proxy valida a identidade da aplicação cliente em três etapas:

1. Correspondência de chave: O valor do header X-Metadax-Key deve ser idêntico ao process.env.METADAX_API_KEY (systemId UUID).
2. Consulta systemsStatus: O servidor faz um GET em https://metadax.com.br/_functions/systemsStatus?systemId={key} e verifica se systems[0].license === "true".
3. Validação de URL: O campo systems[0].title (ex: axio.metadax.com.br) deve bater com process.env.METADAX_APP_URL e/ou o Origin da requisição.

Configuração de ambiente

Degraded mode

Se o endpoint systemsStatus estiver temporariamente indisponível, o proxy loga o aviso e prossegue com a validação relaxada (apenas chave vs. env var), evitando interrupção do serviço. O campo _auth.degraded: true na resposta indica quando isso aconteceu.

3. Endpoint POST /api/data

POST https://axio.metadax.com.br/api/data

Headers obrigatórios

Body (JSON)

Respostas HTTP

4. Estrutura da Resposta (200 OK)

A resposta é um JSON com os seguintes objetos de nível superior:

{
  "apiStatus": {
    "brasilapi": "online",   // status da BrasilAPI
    "viacep":    "online",   // status da ViaCEP
    "bcb":       "offline"   // status do BCB Olinda (opcional)
  },
  "_meta": {
    "sources":  ["BrasilAPI", "ViaCEP"],
    "warnings": [{ "api": "BCB Olinda", "reason": "NOT_FOUND" }]
  },
  "cadastro":    { ... },    // dados da Receita Federal (ver seção 5)
  "localizacao": { ... },    // dados de endereço enriquecidos via ViaCEP (ver seção 6)
  "rating":      { ... },    // rating calculado pela API RFN (pode divergir do CorpInfo)
  "_coords":     { "lat": -19.92, "lng": -43.94 },  // coordenadas por UF para mapa
  "_auth": {
    "systemId": "14aa8fb8-...",        // systemId validado
    "app":      "axio.metadax.com.br", // aplicação autorizada
    "degraded": false                  // true se systemsStatus estava offline
  }
}

5. Campos: cadastro

Todos os campos são fornecidos pela BrasilAPI (Receita Federal) via RFN. Campos numéricos não estão entre aspas no JSON.

6. Campos: localizacao

Dados enriquecidos via ViaCEP. Prefira estes campos para exibição de endereço, pois têm formatação consistente e incluem estado e região.

7. Campos: cadastro.qsa[]

Cada objeto do array representa um sócio ou administrador cadastrado na Receita Federal.

8. Campos: CNAEs

CNAE Principal

Retornado como campos soltos em cadastro:

CNAEs Secundários (cnaes_secundarios[])

9. Campos: regime_tributario[]

Histórico do regime tributário da empresa. Cada entrada representa um ano fiscal.

10. Algoritmo de Rating A–F (AXIO)

Critérios e pontuação

Conversão score → nota

{ "error": "CODIGO_DO_ERRO", "message": "Descrição legível", "docs": "URL" }

curl -X POST https://axio.metadax.com.br/api/data \
  -H "Content-Type: application/json" \
  -H "X-Metadax-Key: 14aa8fb8-c927-4f6d-89b2-57bbede12406" \
  -d '{"cnpj":"10292923000118"}'

const response = await fetch('/api/data', {
  method: 'POST',
  headers: {
    'Content-Type':  'application/json',
    'X-Metadax-Key': window.__METADAX_KEY__,  // injetado no build
  },
  body: JSON.stringify({ cnpj: '65.640.808/0001-89' }),
});

const data = await response.json();

// Campos principais:
const c = data.cadastro;
const l = data.localizacao;

console.log(c.razao_social);                     // "METADAX CONSULTORIA LTDA"
console.log(c.descricao_situacao_cadastral);     // "ATIVA"
console.log(c.capital_social);                   // 73000
console.log(String(c.cnae_fiscal));              // "6201501" (converter para string!)
console.log(l.estado + ' / ' + l.regiao);       // "Minas Gerais / Sudeste"

// QSA:
c.qsa.forEach(s => {
  console.log(s.nome_socio, s.qualificacao_socio, s.data_entrada_sociedade);
});

// CNAEs secundários:
c.cnaes_secundarios.forEach(cn => {
  console.log(String(cn.codigo), cn.descricao);
});

const https = require('https');

function consultarCNPJ(cnpj, systemKey) {
  return new Promise((resolve, reject) => {
    const body = JSON.stringify({ cnpj });
    const req  = https.request({
      hostname: 'axio.metadax.com.br',
      path:     '/api/data',
      method:   'POST',
      headers: {
        'Content-Type':   'application/json',
        'Content-Length': Buffer.byteLength(body),
        'X-Metadax-Key':  systemKey,
      },
    }, (res) => {
      let data = '';
      res.on('data', c => { data += c; });
      res.on('end', () => resolve(JSON.parse(data)));
    });
    req.on('error', reject);
    req.write(body);
    req.end();
  });
}

const dados = await consultarCNPJ('65.640.808/0001-89', process.env.METADAX_API_KEY);
console.log(dados.cadastro.razao_social);

Exemplo: METADAX CONSULTORIA LTDA (65.640.808/0001-89)

13. Variáveis de Ambiente (Vercel)

Configure no painel Vercel em Project → Settings → Environment Variables:

Configuração Vercel (vercel.json)

{
  "build": {
    "env": {
      "METADAX_API_KEY": "@metadax-api-key",
      "METADAX_APP_URL": "axio.metadax.com.br"
    }
  },
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "no-store" },
        { "key": "X-Content-Type-Options", "value": "nosniff" }
      ]
    }
  ]
}