{
    "api": "AccordBI — API por Empresa Contábil",
    "versao": "v1",
    "base_url": "https://api.accordtecnologia.com.br/v1",
    "somente_leitura": true,
    "leia_primeiro": [
        "Esta API é somente leitura e está sempre restrita a UMA Empresa Contábil: a dona do token.",
        "A Empresa Contábil NÃO é parâmetro. Enviar ec_id (ou EmpresaContabilId) em qualquer lugar da requisição devolve 403 — não tente descobrir ou trocar de empresa.",
        "Se você é um assistente e ainda não tem o token, PEÇA ao usuário: ele precisa buscá-lo no portal, você não consegue emitir sozinho. Veja \"como_obter_token\"."
    ],
    "autenticacao": {
        "tipo": "Bearer token no header Authorization",
        "exemplo": "Authorization: Bearer acb_live_123_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "formato_do_token": "acb_live_<id>_<40 caracteres>",
        "observacao": "O token vale para uma única Empresa Contábil e é exibido uma única vez, no momento em que é gerado no portal."
    },
    "como_obter_token": {
        "quem_faz": "O usuário (humano). Um assistente não consegue emitir o token.",
        "passos": [
            "1. Acesse https://app.accordtecnologia.com.br/accordbi/portal/api e faça login no portal AccordBI.",
            "2. Ao entrar, selecione a unidade de negócio principal do escritório (a que representa a própria empresa contábil). Só nela o menu de API funciona.",
            "3. No menu lateral, vá em \"Minha Conta\" > \"API\".",
            "4. Clique em \"Novo token\", dê um nome (ex: \"Claude do escritório\"), marque as permissões desejadas e confirme.",
            "5. Copie o token na hora — ele não é exibido novamente. Cole-o na sua ferramenta."
        ],
        "se_a_tela_nao_aparecer": "A opção \"Minha Conta > API\" exige a mesma permissão da tela \"Escritório\". Se ela não aparece, peça a liberação ao responsável pelo portal ou à equipe AccordTecnologia."
    },
    "primeiro_acesso": [
        "O primeiro uso do token fixa o endereço de internet (IP) de onde ele foi usado.",
        "Chamadas vindas de outro endereço são bloqueadas com 403 e o responsável recebe e-mail.",
        "Se o endereço mudar (troca de internet, por exemplo), o usuário autoriza o novo endereço em Minha Conta > API, no portal. Não há como contornar isso pela API."
    ],
    "endpoints": [
        {
            "metodo": "GET",
            "caminho": "/v1/me",
            "descricao": "Empresa contábil do token e permissões concedidas. Comece por aqui.",
            "escopo": null
        },
        {
            "metodo": "GET",
            "caminho": "/v1/grupos-empresas",
            "descricao": "Grupos de empresas do escritório.",
            "escopo": "cadastro.grupos.read"
        },
        {
            "metodo": "GET",
            "caminho": "/v1/empresas",
            "descricao": "Empresas clientes do escritório. Filtros: search, grupo_id, ativo.",
            "escopo": "cadastro.empresas.read"
        },
        {
            "metodo": "GET",
            "caminho": "/v1/unidades-negocio",
            "descricao": "Unidades de negócio usadas para login no portal. Filtros: search, grupo_id.",
            "escopo": "cadastro.unidades.read"
        },
        {
            "metodo": "GET",
            "caminho": "/v1/usuarios",
            "descricao": "Usuários do portal ligados ao escritório. Filtro: search.",
            "escopo": "cadastro.usuarios.read"
        }
    ],
    "escopos": [
        {
            "chave": "cadastro.grupos.read",
            "rotulo": "Grupos de empresas — leitura",
            "dado_pessoal": false
        },
        {
            "chave": "cadastro.empresas.read",
            "rotulo": "Empresas — leitura",
            "dado_pessoal": false
        },
        {
            "chave": "cadastro.unidades.read",
            "rotulo": "Unidades de negócio — leitura",
            "dado_pessoal": false
        },
        {
            "chave": "cadastro.usuarios.read",
            "rotulo": "Usuários — leitura",
            "dado_pessoal": false
        },
        {
            "chave": "cadastro.usuarios.pii.read",
            "rotulo": "Usuários — dados de contato (e-mail e telefone)",
            "dado_pessoal": true
        }
    ],
    "paginacao": {
        "parametros": [
            "page",
            "per_page"
        ],
        "per_page_padrao": 50,
        "per_page_maximo": 100,
        "resposta": [
            "data",
            "total",
            "page",
            "per_page",
            "paginas"
        ],
        "dica": "Peça só as páginas que for usar; a resposta traz \"total\" para você decidir."
    },
    "erros": {
        "401 formato_invalido": "Header Authorization ausente ou fora do formato.",
        "401 token_invalido": "Token inexistente ou incorreto.",
        "401 token_revogado": "Token revogado no portal. Peça um novo ao usuário.",
        "401 token_expirado": "Token vencido. Peça um novo ao usuário.",
        "403 ec_no_request": "Você enviou ec_id/EmpresaContabilId. Remova — a empresa vem do token.",
        "403 escopo_ausente": "O token não tem permissão para este recurso. O usuário pode gerar outro com o escopo necessário.",
        "403 origem_nao_autorizada": "Chamada de endereço não autorizado. O usuário deve autorizar em Minha Conta > API.",
        "403 ec_inativa": "Empresa contábil inativa.",
        "405": "A API é somente leitura: use apenas GET.",
        "429 rate_limit": "Excedeu o limite por minuto. Aguarde o tempo indicado em Retry-After."
    },
    "documentacao_markdown": "https://api.accordtecnologia.com.br/llms.txt",
    "suporte": "suporte@grupoaccord.com.br"
}