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/infraEscopos necessários
GET /infra/health/api- nenhum escopo. É público.GET /infra/health/serpro- token válido e escopoinfra:read.- Operações administrativas (
POST) - token válido e escopoinfra: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â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). 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.
| 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 {}. |
Health não é autenticação
GET /infra/health/api é público por design. Não o use como prova de autorização.