Infraestrutura

Endpoints de infraestrutura da WebApiAlcance - o domínio infra reúne dois grupos com níveis de proteção muito diferentes: health checks públicos (usados pelo smoke test do deploy e por monitoramento externo) e operações internas com escopo (reset de pastas do servidor, controle dos observadores de arquivos, importação de clientes por planilha e pipelines de sincronização PGDAS-D do Simples Nacional).

Dois grupos, duas proteções

Este domínio monta dois routers sob o mesmo prefixo /infra, mas com proteções distintas:

Health checks (/infra/health/*) - PÚBLICOS. Não exigem token nem escopo. São chamados pelo smoke test do deploy (scripts/deploy.ps1) e por monitoramento externo.
Operações (/infra/...) - EXIGEM escopo infra:read/infra:write além de um token válido. Cobrem ações destrutivas/operacionais (reset de arquivos, observers, import, pipelines).

Nunca adicione rotas operacionais ao grupo de health, nem confie no health como se fosse autenticado.

O Swagger oficial está em api.contabilidadealcance.com.br/docs. Para o fluxo de autenticação das operações, veja Autenticação.

Base path

/api/v1/infra

Ambos os routers (health e operações) são montados sob este mesmo prefixo no agregador da v1.

Escopos necessários

Health checks (/infra/health/api, /infra/health/serpro) - nenhum escopo. São públicos (registrados sem a dependência de escopo).
Operações - exigem token válido e escopo:
- infra:read - ações de leitura (métodos GET).
- infra:write - ações de escrita/execução (métodos POST/PUT/PATCH/DELETE).

O escopo é derivado da rota: o prefixo /infra vira o recurso infra, e o método HTTP define a ação (read para GET, write para os demais). Como as operações abaixo são todas POST, na prática exigem infra:write.

As operações são internas e potencialmente destrutivas (apagam arquivos do servidor, param/iniciam observadores, disparam sincronizações em massa). Emita API Keys restritas com o escopo infra:write apenas para os serviços que realmente precisam acioná-las - nunca globais.

Endpoints

Os endpoints /infra/health/* pertencem ao health_router e são públicos (não exigem token nem escopo); retornam payloads simples que não seguem obrigatoriamente o envelope { success, message, data }. Os demais pertencem ao ops_router e exigem token válido + escopo infra:write.

`GET /infra/health/api`

Verifica o status da API e a conectividade com o banco de dados. Executa um SELECT 1 para confirmar que o banco responde.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "ok",
  "database": "connected"
}

Se o banco não responder, retorna status: "error" e database: "disconnected". Este retorno é um payload direto (não usa o envelope padrão).

Escopo: público (não exige API Key)

`GET /infra/health/serpro`

Verifica a conectividade com o serviço SERPRO: se o certificado mTLS pode ser carregado e se é possível obter um token de autenticação. A resposta segue o schema SerproPing.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "online": true,
  "mtls_configurado": true,
  "autenticado": true,
  "erro": null,
  "extras": {
    "token_expires_at": "2026-07-03T12:00:00"
  }
}

Quando algo falha, mtls_configurado/autenticado vêm false e erro traz a mensagem correspondente.

Escopo: público (não exige API Key)

`POST /infra/start-observers/`

Inicia os observadores de arquivos no servidor (monitoram pastas para processamento automático).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query, nem corpo de requisição.

Request

Sem corpo de requisição.

Response 200 OK

{
  "message": "Observadores iniciados com sucesso"
}

Este retorno é um payload direto (não usa o envelope padrão).

Escopo: infra:write

`POST /infra/stop-observer/`

Pausa/interrompe os observadores de arquivos.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query, nem corpo de requisição.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Observeres interrompidos",
  "data": null
}

Escopo: infra:write

`POST /infra/files/downloads/reset`

Exclui todos os arquivos da pasta de downloads do servidor.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query, nem corpo de requisição.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Arquivos excluidos com sucesso!",
  "data": null
}

Em caso de falha, retorna envelope de erro com message: "Erro ao deletar arquivos, verificar log.".

Escopo: infra:write

`POST /infra/files/acessorias/reset`

Exclui todos os arquivos da pasta do acessorias do servidor.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query, nem corpo de requisição.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Arquivos excluidos com sucesso!",
  "data": null
}

Em caso de falha, retorna envelope de erro com message: "Erro ao deletar arquivos, verificar log.".

Escopo: infra:write

`POST /infra/files/acessorias/backup/reset`

Exclui todos os arquivos da pasta de backup do acessorias do servidor.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query, nem corpo de requisição.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Arquivos excluidos com sucesso!",
  "data": null
}

Em caso de falha, retorna envelope de erro com message: "Erro ao deletar arquivos, verificar log.".

Escopo: infra:write

`POST /infra/files/tmp/reset`

Exclui todos os arquivos da pasta de upload (temporários) do servidor.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query, nem corpo de requisição.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Arquivos excluidos com sucesso!",
  "data": null
}

Em caso de falha, retorna envelope de erro com message: "Erro ao deletar arquivos, verificar log.".

Escopo: infra:write

`POST /infra/customers/import`

Importa uma planilha Excel (.xlsx) contendo dados de clientes e persiste no banco. O arquivo é enviado como multipart/form-data no campo arquivo.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. O envio é multipart/form-data, com o campo abaixo:

Parâmetro	Tipo	Local	Obrigatório	Descrição
`arquivo`	`file`	form	sim	Planilha `.xlsx` com os clientes.

Colunas obrigatórias na planilha: Razão Social *, Nome Fantasia *, CPF/CNPJ *, Telefone *, Celular *, E-mail *, Endereço *, Número *, Bairro *, Cidade *, Estado *, CEP *, Login GOV *, Senha GOV *, Regime Tributário *.

Request

Envio multipart/form-data com o campo arquivo (não usa corpo JSON). Validações: o arquivo precisa ter extensão .xlsx (senão 400 Bad Request); colunas ausentes retornam 400 listando o que faltou; erros de processamento retornam 422 Unprocessable Entity.

Response 200 OK

{
  "success": true,
  "message": "Arquivo processado com sucesso.",
  "data": {
    "errors": []
  }
}

Quando há linhas com erro, a message acrescenta a contagem (ex.: " Houve 3 linha(s) com erro.") e data traz o resumo (summary) do processamento.

Escopo: infra:write

`POST /infra/pipeline/pgdasd/sincronizar-declaracoes/unico`

Consulta as declarações PGDAS-D (Simples Nacional) de um contribuinte no SERPRO e insere/atualiza automaticamente os registros no banco (modelo DeclaracaoSN).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (OnlyContribuintePayload). O campo dados deve conter anoCalendario ou periodoApuracao; em contribuinte.tipo, 1 = PF (CPF) e 2 = PJ (CNPJ).

Request

{
  "dados": { "anoCalendario": 2025 },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "mensagem": "Sincronização concluída com sucesso.",
  "ano_calendario": 2025,
  "criados": [202501, 202502],
  "atualizados": [202412],
  "total_periodos": 3
}

Se a consulta ao SERPRO falhar, retorna 400 Bad Request com detail: "Erro ao consultar declarações PGDAS-D.".

Escopo: infra:write

`POST /infra/pipeline/pgdasd/sincronizar-declaracoes/all`

Sincroniza automaticamente as declarações PGDAS-D de todos os clientes do regime Simples Nacional. Ignora filiais (processa apenas matrizes - ordem 0001 no CNPJ) e aplica um intervalo entre chamadas ao SERPRO.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (AnoPayload), com o campo ano (ano-calendário a sincronizar).

Request

{
  "ano": 2025
}

Response 200 OK

{
  "mensagem": "Sincronização concluída para 42 clientes MATRIZES do Simples Nacional.",
  "clientes_processados": 42,
  "filiais_ignoradas": 5,
  "registros_criados": 120,
  "registros_atualizados": 30,
  "erros": []
}

Se nenhum cliente do Simples Nacional for encontrado, retorna 404 Not Found com detail: "Nenhum cliente do Simples Nacional encontrado.".

Escopo: infra:write

Schemas

`SerproPing`

Retornado por GET /infra/health/serpro.

Campo	Tipo	Notas
`online`	`bool`	Indica que a verificação foi executada (API online).
`mtls_configurado`	`bool`	O certificado mTLS pôde ser carregado.
`autenticado`	`bool`	Foi possível obter token de acesso no SERPRO.
`erro`	`str \| null`	Mensagem de erro, quando houver.
`extras`	`object`	Dados adicionais (ex.: `token_expires_at`). Default `{}`.

Notas

Health não é autenticação

Os endpoints /infra/health/* são públicos por design (smoke test do deploy e monitoramento externo). Não os use como prova de autorização e não coloque nada sensível em suas respostas.

As operações seguem, em geral, o envelope { success, message, data } (ou { success: false, ... } em erro). Os health checks e alguns retornos simples (ex.: start-observers) podem devolver payloads diretos, conforme documentado acima.
Os pipelines PGDAS-D dependem de conectividade com o SERPRO - verifique antes com GET /infra/health/serpro.
A sincronização em massa (.../all) é demorada: processa cliente a cliente com espera entre chamadas e acumula falhas individuais no array erros sem interromper o lote.