Infraestrutura

Endpoints de infraestrutura da WebApiAlcance: o health check público da API e a verificação de conectividade com o SERPRO (exige escopo).

Para o fluxo de autenticação, veja Autenticação.

Base path

/api/v1/infra

Escopos necessários

  • GET /infra/health/api - nenhum escopo. É público.
  • GET /infra/health/serpro - token válido e escopo infra:read.
  • Operações administrativas (POST) - token válido e escopo infra:write.

Endpoints

Os health checks retornam payloads simples que não seguem o envelope { status, message, data }.

GET /infra/health/api

Verifica se a API está respondendo.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "ok"
}

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 o tipo do erro.

Escopo: infra:read

Operações administrativas (acesso restrito)

Uso interno do escritório

As rotas desta seção são de uso interno, operam sobre o servidor e várias são destrutivas e irreversíveis. Chame-as apenas a partir de processos autorizados e com confirmação humana.

POST /infra/start-observers/

Inicia os observadores de arquivos do servidor, que 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

Operação interna, restrita a credenciais com o escopo indicado; sem ele, a resposta é 403.

POST /infra/stop-observer/

Pausa 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

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

Escopo: infra:write

Operação interna, restrita a credenciais com o escopo indicado; sem ele, a resposta é 403.

POST /infra/files/downloads/reset

Exclui todos os arquivos da pasta temporária 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

{
  "status": "success",
  "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

Operação interna, restrita a credenciais com o escopo indicado; sem ele, a resposta é 403.

POST /infra/files/acessorias/reset

Exclui todos os arquivos da pasta de arquivos do Acessórias no 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

{
  "status": "success",
  "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

Operação interna, restrita a credenciais com o escopo indicado; sem ele, a resposta é 403.

POST /infra/files/acessorias/backup/reset

Exclui todos os arquivos da pasta de backup dos arquivos do Acessórias no 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

{
  "status": "success",
  "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

Operação interna, restrita a credenciais com o escopo indicado; sem ele, a resposta é 403.

POST /infra/files/tmp/reset

Exclui todos os arquivos da pasta de uploads 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

{
  "status": "success",
  "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

Operação interna, restrita a credenciais com o escopo indicado; sem ele, a resposta é 403.

POST /infra/customers/import

Importa uma planilha Excel (.xlsx) com 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âmetroTipoLocalObrigatórioDescrição
arquivofileformsimPlanilha .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). 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

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

Quando há linhas com erro, a message acrescenta a contagem de linhas com erro e data traz o resumo (summary) do processamento.

Escopo: infra:write

Operação interna, restrita a credenciais com o escopo indicado; sem ele, a resposta é 403.

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

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

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. Os dados vão no corpo (OnlyContribuintePayload): 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 { "message": "Erro ao consultar declarações PGDAS-D." }. Cliente inativo retorna 409 ("Cliente inativo: automações bloqueadas.").

Escopo: infra:write

Operação interna, restrita a credenciais com o escopo indicado; sem ele, a resposta é 403.

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

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

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. O corpo (AnoPayload) traz 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": [],
  "inativos_ignorados": 3
}

inativos_ignorados é a quantidade de clientes que não foram sincronizados por estarem inativos. Se nenhum cliente do Simples Nacional for encontrado, retorna 404 Not Found com { "message": "Nenhum cliente do Simples Nacional encontrado." }.

A sincronização em massa é demorada: processa cliente a cliente e acumula falhas individuais em erros sem interromper o lote. Verifique antes a conectividade com GET /infra/health/serpro.

Escopo: infra:write

Operação interna, restrita a credenciais com o escopo indicado; sem ele, a resposta é 403.

Schemas

SerproPing

Retornado por GET /infra/health/serpro.

CampoTipoNotas
onlineboolIndica que a verificação foi executada (API online).
mtls_configuradoboolO certificado mTLS pôde ser carregado.
autenticadoboolFoi possível obter token de acesso no SERPRO.
errostr | nullMensagem de erro, quando houver.
extrasobjectDados adicionais (ex.: token_expires_at). Default {}.

Health não é autenticação

GET /infra/health/api é público por design. Não o use como prova de autorização.