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:acao por 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_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 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 recebem 403. 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