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 exposta via HTTPS em https://api.contabilidadealcance.com.br. 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).
- Processamento assíncrono de automações longas e integrações com órgãos governamentais.
- 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 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, contratos tipados.
- Autenticação dupla - JWT para login de usuários e API Key para automações (incluindo o MCP).
- Escopos
recurso:acaopor API Key - cada credencial recebe apenas as permissões mínimas necessárias, nunca acesso global. - Processamento assíncrono - operações que dependem de raspagem, geração de PDF ou integrações externas retornam
task_idimediatamente, 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.brOs 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 assíncronas, incluindo integrações com o Acessorias. - Integra Contador (
/integra-contador/sn,/integra-contador/dctf,/integra-contador/mit,/integra-contador/radar/pagamentos) - consultas e emissão de documentos na API SERPRO com certificado digital da Alcance. - DCTFWeb (
/dctfweb) - superfície consolidada da DCTFWeb: registro de guias e recibos, emissão/coleta em lote, os catálogos de categorias e sistemas de origem e a transmissão da declaração (/dctfweb/transmissao,/dctfweb/situacao) - que exige login de usuário (sessão); credenciais de integração recebem403. Os caminhos antigos (/dctfweb-guias,/dctfweb-recibos,/integra-contador/radar/guias,/integra-contador/radar/recibos) seguem vivos como alias deprecado - ver DCTFWeb: visão geral. - 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 (
/dominio-web,/situacao-fiscal,/situacao-fiscal-detalhamento,/declaracao-sn,/relatorio-iss-data) - dados estruturais e de referência consumidos pelas automações.
A página de Endpoints detalha cada um destes agrupamentos com os caminhos completos, métodos HTTP e escopos exigidos.
Próximos passos
Autenticação
Como obter e usar a API Key - header `Authorization: Bearer`, JWT de login e diferenças entre os dois caminhos de auth.
Escopos
Modelo `recurso:acao` aplicado por API Key - catálogo de escopos disponíveis e princípio do menor privilégio.
Endpoints
Referência completa dos endpoints REST agrupados por domínio funcional - clientes, certidões, lembretes e mais.