{
  "_comment": "Exemplos de resposta JSON da CNPJ API — padrão fechado de envelope",

  "GET /api/v1/cnpj/07526557011659 — sucesso": {
    "success": true,
    "code": "CNPJ_FOUND",
    "message": "Dados do CNPJ obtidos com sucesso.",
    "data": {
      "tax_id": "07526557011659",
      "company_root": "07526557",
      "is_head": false,
      "alias": "Filial Manaus",
      "company_name": "AMBEV S.A.",
      "equity": "58226035176.01",
      "nature": {
        "id": 2046,
        "text": "Sociedade Anônima Aberta"
      },
      "size": {
        "id": 5,
        "acronym": "DEMAIS",
        "text": "Demais"
      },
      "simples_optant": false,
      "simei_optant": false,
      "status": {
        "id": 2,
        "text": "Ativa",
        "date": "2023-07-31"
      },
      "founded": "2023-07-31",
      "updated_at": "2025-01-03T20:40:19Z",
      "address": {
        "street": "Avenida Constantino Nery",
        "number": "2575",
        "details": null,
        "district": "Flores",
        "city": "Manaus",
        "state": "AM",
        "zip": "69058795",
        "municipality": 1302603,
        "country": {
          "id": 76,
          "name": "Brasil"
        }
      },
      "main_activity": {
        "id": 1113502,
        "text": "Fabricação de cervejas e chopes"
      }
    },
    "meta": {
      "timestamp": "2026-03-22T14:30:00Z",
      "requestId": "20260322143000-a1b2c3d4e5f6"
    },
    "errors": []
  },

  "GET /api/v1/cnpj/00000000000000 — CNPJ inválido": {
    "success": false,
    "code": "VALIDATION_ERROR",
    "message": "CNPJ inválido.",
    "data": null,
    "meta": {
      "timestamp": "2026-03-22T14:30:01Z",
      "requestId": "20260322143001-b2c3d4e5f6a1"
    },
    "errors": [
      {
        "field": "cnpj",
        "message": "CNPJ com todos os dígitos iguais não é válido."
      }
    ]
  },

  "GET /api/v1/cnpj/11222333000181 — não encontrado": {
    "success": false,
    "code": "NOT_FOUND",
    "message": "CNPJ não encontrado.",
    "data": null,
    "meta": {
      "timestamp": "2026-03-22T14:30:02Z",
      "requestId": "20260322143002-c3d4e5f6a1b2"
    },
    "errors": [
      {
        "field": "cnpj",
        "message": "O CNPJ 11222333000181 não foi localizado na base de dados."
      }
    ]
  },

  "GET /api/v1/cnpj/07526557011659/completo — sucesso (resumido)": {
    "success": true,
    "code": "CNPJ_FULL_FOUND",
    "message": "Dados completos do CNPJ obtidos com sucesso.",
    "data": {
      "tax_id": "07526557011659",
      "company_root": "07526557",
      "is_head": false,
      "alias": "Filial Manaus",
      "company_name": "AMBEV S.A.",
      "equity": "58226035176.01",
      "nature": { "id": 2046, "text": "Sociedade Anônima Aberta" },
      "size": { "id": 5, "acronym": "DEMAIS", "text": "Demais" },
      "simples_optant": false,
      "simei_optant": false,
      "status": { "id": 2, "text": "Ativa", "date": "2023-07-31" },
      "founded": "2023-07-31",
      "updated_at": "2025-01-03T20:40:19Z",
      "address": {
        "street": "Avenida Constantino Nery",
        "number": "2575",
        "details": null,
        "district": "Flores",
        "city": "Manaus",
        "state": "AM",
        "zip": "69058795",
        "municipality": 1302603,
        "country": { "id": 76, "name": "Brasil" }
      },
      "main_activity": { "id": 1113502, "text": "Fabricação de cervejas e chopes" },
      "phones": [
        { "type": "LANDLINE", "area": "19", "number": "33135680" }
      ],
      "emails": [
        { "ownership": "CORPORATE", "address": "opobrigaces@ambev.com.br", "domain": "ambev.com.br" }
      ],
      "members": [
        { "name": "Felipe Moreira Haddad Baruque", "tax_id": "***787888**", "age": "41-50", "role_id": 10, "role": "Diretor", "since": "2022-12-26" }
      ],
      "side_activities": [
        { "id": 1122401, "text": "Fabricação de refrigerantes", "type": "SIDE" }
      ],
      "registrations": [
        { "number": "054591406", "state": "AM", "enabled": true, "status_id": 1, "status_text": "Sem restrição", "status_date": "2024-04-03", "type_id": 1, "type_text": "IE Normal" }
      ],
      "suframa": [
        {
          "number": "220120838",
          "since": "2024-04-12",
          "approved": true,
          "approval_date": "1987-09-24",
          "status_id": 1,
          "status_text": "Ativa",
          "incentives": [
            { "tribute": "IPI",  "benefit": "Isenção", "purpose": "Consumo Interno, Industrialização e Utilização", "basis": "Decreto 7.212 de 2010 (Art. 81)" },
            { "tribute": "ICMS", "benefit": "Isenção", "purpose": "Industrialização e Comercialização",             "basis": "Convênio ICMS n° 65 de 1988" }
          ]
        }
      ]
    },
    "meta": {
      "timestamp": "2026-03-22T14:30:03Z",
      "requestId": "20260322143003-d4e5f6a1b2c3"
    },
    "errors": []
  },

  "GET /api/v1/raiz/07526557/filiais — sucesso": {
    "success": true,
    "code": "BRANCHES_FOUND",
    "message": "Filiais encontradas com sucesso.",
    "data": [
      {
        "tax_id": "07526557000174",
        "is_head": true,
        "alias": "Matriz São Paulo",
        "status": "Ativa",
        "city": "São Paulo",
        "state": "SP",
        "main_activity": { "id": 1113502, "text": "Fabricação de cervejas e chopes" }
      },
      {
        "tax_id": "07526557011659",
        "is_head": false,
        "alias": "Filial Manaus",
        "status": "Ativa",
        "city": "Manaus",
        "state": "AM",
        "main_activity": { "id": 1113502, "text": "Fabricação de cervejas e chopes" }
      }
    ],
    "meta": {
      "timestamp": "2026-03-22T14:30:04Z",
      "requestId": "20260322143004-e5f6a1b2c3d4"
    },
    "errors": []
  },

  "Sem X-API-Key — 401": {
    "success": false,
    "code": "AUTHENTICATION_ERROR",
    "message": "Autenticação necessária.",
    "data": null,
    "meta": {
      "timestamp": "2026-03-22T14:30:05Z",
      "requestId": "20260322143005-f6a1b2c3d4e5"
    },
    "errors": [
      { "field": null, "message": "O header X-API-Key é obrigatório." }
    ]
  },

  "X-API-Key inválida — 401": {
    "success": false,
    "code": "AUTHENTICATION_ERROR",
    "message": "API key inválida.",
    "data": null,
    "meta": {
      "timestamp": "2026-03-22T14:30:06Z",
      "requestId": "20260322143006-a1b2c3d4e5f6"
    },
    "errors": [
      { "field": null, "message": "A API key fornecida não é válida ou está inativa." }
    ]
  },

  "POST /api/v1/admin/api-keys — criação": {
    "success": true,
    "code": "API_KEY_CREATED",
    "message": "API key criada com sucesso. Guarde a chave — ela não será exibida novamente.",
    "data": {
      "id": 1,
      "client_name": "Meu Sistema",
      "client_description": "Acesso à consulta de CNPJs",
      "api_key": "a3f1b2c4d5e6f7081234567890abcdef1234567890abcdef1234567890abcdef",
      "is_active": true,
      "expires_at": null,
      "last_used_at": null,
      "created_at": "2026-03-22T14:30:07Z",
      "updated_at": "2026-03-22T14:30:07Z"
    },
    "meta": {
      "timestamp": "2026-03-22T14:30:07Z",
      "requestId": "20260322143007-b2c3d4e5f6a1"
    },
    "errors": []
  },

  "Rota não encontrada — 404": {
    "success": false,
    "code": "ROUTE_NOT_FOUND",
    "message": "Rota não encontrada.",
    "data": null,
    "meta": {
      "timestamp": "2026-03-22T14:30:08Z",
      "requestId": "20260322143008-c3d4e5f6a1b2"
    },
    "errors": [
      { "field": null, "message": "O caminho requisitado não existe nesta API." }
    ]
  },

  "Método não permitido — 405": {
    "success": false,
    "code": "METHOD_NOT_ALLOWED",
    "message": "Método HTTP não permitido para esta rota.",
    "data": null,
    "meta": {
      "timestamp": "2026-03-22T14:30:09Z",
      "requestId": "20260322143009-d4e5f6a1b2c3"
    },
    "errors": [
      { "field": null, "message": "Verifique o método HTTP utilizado." }
    ]
  }
}