API — WebApiAlcance

API HTTPS dos sistemas internos da Alcance Contabilidade — núcleo central do hub de automações contábeis, fiscais, financeiras e administrativas.

O que é a WebApi

A WebApiAlcance é uma aplicação FastAPI (Python 3.13) executada on-premise em um servidor Windows, supervisionada por NSSM, e exposta à internet via Cloudflare com endereçamento dinâmico (DDNS). Ela centraliza acesso a dados e operações da plataforma e é consumida por quatro tipos de cliente:

• Sistema web interno (e-Continuo, Acessorias e demais ferramentas operacionais da Alcance).
• Workers Celery que executam automações longas, raspagens de dados e integrações com a SERPRO.
• Gateway MCP (este projeto), que traduz a WebApi para clientes de IA via Model Context Protocol.
• Operadores humanos com login JWT, para inspeção pontual via Swagger ou clientes REST.

A arquitetura segue Clean Architecture e Domain-Driven Design, com domínios bem delimitados e separação clara entre infraestrutura, casos de uso e regras de negócio.

Características

• FastAPI — validação automática via Pydantic, geração nativa de OpenAPI e documentação interativa.
• Autenticação dupla — JWT para operadores humanos e API Key para automações (incluindo o MCP).
• Escopos recurso:acao por API Key — cada credencial recebe apenas as permissões mínimas necessárias, nunca acesso global.
• Tasks longas via Celery — operações que dependem de raspagem, geração de PDF ou integrações externas retornam task_id imediatamente, sem bloquear o cliente.
• Resposta padrão envelopada no formato { status, message, data }, garantindo previsibilidade na hora de parsear no consumidor.

Endpoint base

Toda chamada à WebApi parte da URL pública abaixo, sempre via HTTPS:

https://api.contabilidadealcance.com.br

Os recursos REST ficam sob o prefixo /api/v1/.... Por exemplo, a listagem de clientes está em /api/v1/customers.

Domínios funcionais

A API organiza seus endpoints em domínios coerentes. Cada grupo abaixo reúne um conjunto de rotas relacionadas:

• Clientes (/customers, /customer-qsa, /customer-account-ns, /carteira-cliente, /grupo-carteira) — cadastro PF/PJ, dados fiscais, quadro societário (QSA) e contas no sistema NS.
• Certidões Negativas (/certidao-negativa) — emissão e consulta de CND, FGTS, SEFAZ municipal/estadual, com download de PDF binário.
• Lembretes (/lembretes, /config-envio, /agendamento-automation) — criação, agendamento e envio automático de lembretes via WhatsApp Business.
• Worker Automation (/worker-automation, /automation, /automation/acessorias) — registro e disparo de automações no Celery, incluindo integrações com o Acessorias.
• Integra Contador (/integra-contador/sn, /integra-contador/dctf, /integra-contador/mit, /integra-contador/radar/...) — consultas e emissão de documentos na API SERPRO com certificado digital da Alcance.
• Conversores (/conversor-extract, /conversor-report) — automações de extratos e relatórios bancários.
• Movimentações financeiras (/caixa-cartao, /caixa-especie, /movimentacao-bancaria, /movimentacao-estoque, /juros-descontos-compromisso, /adiantamento-fornecedor, /compras-estoque) — lançamentos importados do SaaS contábil de origem.
• Configurações e referência (/api-keys, /scopes, /dominio-web, /situacao-fiscal, /situacao-fiscal-detalhamento, /declaracao-sn, /relatorio-iss-data, /nfe-salvador-medicos) — gestão de credenciais, escopos e dados estruturais consumidos pelas automações.

A página de Endpoints detalha cada um destes agrupamentos com os caminhos completos, métodos HTTP e escopos exigidos.

Documentação interativa

A própria WebApi expõe duas interfaces auto-geradas a partir da definição OpenAPI ao vivo — use-as para inspecionar contratos, schemas e testar chamadas com a API Key:

• Swagger UI — https://api.contabilidadealcance.com.br/docs
• ReDoc — https://api.contabilidadealcance.com.br/redoc

Próximos passos