Automation: Tax

Endpoints da WebApiAlcance para automação tributária (fiscal). Cobrem a emissão da TFF Salvador, geração do alvará de funcionamento (Salvador), processamento da alíquota de ISS, comparação de relatórios de NF-e, emissão de certidões negativas (Sefaz Salvador, Sefaz Bahia, Receita Federal, Trabalhista e FGTS) e a geração de relatórios e guias de ISS Salvador.

A maioria das rotas cria um Worker e enfileira uma task Celery, retornando de imediato (padrão assíncrono). Para acompanhar o andamento da execução, consulte o task_id/worker_id retornado via Worker Automation.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs (tag Automation: Tax).

Base path

/api/v1/automation

As rotas deste domínio ficam sob o prefixo /tax - ou seja, o caminho completo de cada endpoint é /api/v1/automation/tax/....

Escopos necessários

automation:read - leitura (não há rotas de leitura neste subdomínio; todas as rotas abaixo são de escrita).
automation:write - execução/enfileiramento das automações (todas as rotas são POST).

O escopo é derivado apenas do 1º segmento da rota: /automation/... → recurso automation, e o método HTTP define a ação (write para POST).

Escopo compartilhado com Automation: Acessorias

Como o escopo deriva somente do primeiro segmento do caminho, o recurso automation é compartilhado entre este subdomínio (/automation/tax) e o subdomínio Automation: Acessorias (/automation/acessorias). Uma API Key com automation:write habilita ambos os subdomínios ao mesmo tempo - não há como conceder acesso a apenas um deles via escopo.

Endpoints

Todas as rotas são POST e exigem o escopo automation:write. Salvo indicação em contrário, o retorno segue o envelope padrão { success, message, data }; as rotas que enfileiram tasks Celery devolvem worker_id e/ou task_id para acompanhamento.

`POST /automation/tax/tff/salvador/scraper/v2/`

Enfileira a automação da TFF Salvador para um único cliente. Cria um Worker (fila scraping, tipo tff_salvador) e dispara a task Celery tff_salvador.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (TffScraperRequest): user_id (obrigatório) e customer_id (obrigatório).

Request

{
  "user_id": 42,
  "customer_id": 101
}

Response 200 OK

{
  "worker_id": 812,
  "task_id": "a3f8c1e2-9b4d-4e7a-8c1f-2d5b6a8e9f0c",
  "message": "Automação TFF Salvador enfileirada com sucesso."
}

Escopo: automation:write

`POST /automation/tax/tff/salvador/scraper/selected/v2/`

Enfileira a automação da TFF Salvador para vários clientes de uma vez. Itera a lista de customer_ids, criando um Worker e uma task Celery tff_salvador por cliente; falhas individuais não interrompem o lote.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (TffBatchRequest): user_id (obrigatório) e customer_ids (obrigatório, lista de int).

Request

{
  "user_id": 42,
  "customer_ids": [101, 102, 999]
}

Response 200 OK

{
  "status": "enfileirado",
  "total": 3,
  "enfileirados": 2,
  "falhas": 1,
  "itens": [
    {
      "customer_id": 101,
      "worker_id": 813,
      "task_id": "b4c9d2f3-1a5e-4f8b-9c2d-3e6b7a9f0d1e",
      "status": "ENFILEIRADO",
      "message": "Enfileirado com sucesso",
      "erro": null
    },
    {
      "customer_id": 999,
      "worker_id": null,
      "task_id": null,
      "status": "FALHA",
      "erro": "..."
    }
  ]
}

Escopo: automation:write

`POST /automation/tax/alvara_funcionamento/salvador/scraper/v2`

Enfileira a geração do alvará de funcionamento (Salvador) para um único cliente. Valida a existência do usuário e do cliente e a presença de inscricao_municipal, representante (CPF) e cpfecnpj antes de enfileirar. Cria um Worker (fila scraping, tipo alvara_salvador) e dispara a task scraper_alvara_salvador.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	query	sim	ID do usuário solicitante.
`customer_id`	`int`	query	sim	ID do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Automação agendada com sucesso.",
  "data": null
}

Se alguma validação falhar, retorna { "error": "..." } (ex.: "Inscrição municipal não cadastrada", "CPF do representante não encontrado", "CNPJ do cliente não encontrado").

Escopo: automation:write

`POST /automation/tax/alvara_funcionamento/salvador/scraper/selected/v2`

Enfileira a geração do alvará de funcionamento (Salvador) para vários clientes. Cada cliente é validado individualmente; os que passam são enfileirados (Worker + task scraper_alvara_salvador) e os que falham entram na lista de falhas.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	query	sim	ID do usuário solicitante.
`customer_ids`	`List[int]`	query	sim	Lista de IDs de clientes.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "enfileirado",
  "total": 5,
  "enfileirados": 4,
  "falhas": 1,
  "itens": [
    {
      "customer_id": 101,
      "worker_id": 820,
      "task_id": "c5d0e3a4-2b6f-4a9c-8d3e-4f7c8b0a1e2f",
      "status": "ENFILEIRADO",
      "message": "Enfileirado com sucesso",
      "erro": null
    },
    { "customer_id": 999, "erro": "Cliente não encontrado" }
  ]
}

Se o user_id não existir, retorna { "status": "error", "message": "Usuário não encontrado" }.

Escopo: automation:write

`POST /automation/tax/aliquota_iss/process-and-send`

Executa o processo completo da alíquota de ISS: recebe upload de um ou mais arquivos PDF, extrai os dados e envia os resultados por e-mail aos clientes. Processamento síncrono (não enfileira Celery) - a resposta já traz os dados processados.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	query	sim	ID do usuário solicitante.
`files`	`List[UploadFile]`	form-data	sim	Um ou mais arquivos PDF.

Request

Corpo multipart/form-data com o campo files (um ou mais arquivos PDF). Não há corpo JSON.

Response 200 OK

{
  "status": "success",
  "message": "Arquivos processados e enviados para o(os) cliente(es) com sucesso",
  "data": {}
}

Se o usuário não existir ou o processamento falhar, retorna o envelope de erro error_response ({ success: false, message, ... }).

Escopo: automation:write

`POST /automation/tax/comparacao-nfe/process`

Processa e compara relatórios de NF-e (serviço ou entrada). Processamento síncrono - retorna o resultado já com a razão social preenchida por cliente. Também registra um log da comparação.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	query	sim	ID do usuário solicitante.
`tipo`	`"NF-e Serviço"` \| `"NF-e Entrada"`	query	não	Tipo de relatório a comparar. Default `"NF-e Serviço"`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Processamento concluído!",
  "data": []
}

Em caso de erro (ex.: usuário não encontrado), retorna o envelope error_response.

Escopo: automation:write

`POST /automation/tax/certidao-negativa-salvador/scraper/`

Enfileira a emissão da certidão negativa da Sefaz Salvador. Valida usuário, cliente e cpfecnpj; cria um Worker (fila certidao, tipo certidao_sefaz_salvador) e dispara a task scraper_certidao_sefaz_salvador. Registra log da emissão.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	query	sim	ID do usuário.
`customer_id`	`int`	query	sim	ID do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Automação agendada com sucesso.",
  "data": null
}

Validações que falham retornam { "error": "..." }.

Escopo: automation:write

`POST /automation/tax/certidao-negativa-bahia/scraper/`

Enfileira a emissão da certidão negativa da Sefaz Bahia. Valida usuário, cliente e cpfecnpj; cria um Worker (fila certidao, tipo certidao_sefaz_bahia) e dispara a task scraper_certidao_sefaz_bahia. Registra log da emissão.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	query	sim	ID do usuário.
`customer_id`	`int`	query	sim	ID do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Automação da Sefaz BA agendada com sucesso.",
  "data": null
}

Escopo: automation:write

`POST /automation/tax/certidao-negativa-receita-federal/scraper/`

Enfileira a emissão da certidão negativa da Receita Federal via scraper Selenium. Valida usuário, cliente e cpfecnpj; cria um Worker (fila certidao, tipo certidao_receita_federal) e dispara a task scraper_certidao_receita_federal. Registra log da emissão.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	query	sim	ID do usuário.
`customer_id`	`int`	query	sim	ID do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Automação da Receita Federal agendada com sucesso.",
  "data": null
}

Escopo: automation:write

`POST /automation/tax/certidao-negativa-receita-federal/v2/`

Versão v2 da certidão da Receita Federal: emite via API SERPRO (Consulta CND) em vez do scraper Selenium. Persiste no mesmo local (tabela certidao_negativa, tipo "RECEITA FEDERAL") e requer contrato/credencial próprios da CND (SERPRO_CND_*). Cria um Worker (fila certidao, tipo certidao_receita_federal) e dispara a task certidao_receita_federal_cnd.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	query	sim	ID do usuário.
`customer_id`	`int`	query	sim	ID do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Emissão da certidão da Receita Federal (via SERPRO CND) agendada com sucesso.",
  "data": null
}

Escopo: automation:write

`POST /automation/tax/certidao-negativa-trabalhista/scraper/`

Enfileira a emissão da Certidão Negativa Trabalhista. Valida usuário, cliente e cpfecnpj; cria um Worker (fila certidao, tipo certidao_trabalhista) e dispara a task scraper_certidao_trabalhista. Registra log da emissão.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	query	sim	ID do usuário.
`customer_id`	`int`	query	sim	ID do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Automação da Certidão Negativa Trabalhista agendada com sucesso.",
  "data": null
}

Escopo: automation:write

`POST /automation/tax/certidao-negativa-fgts/scraper/`

Enfileira a emissão da Certidão Negativa FGTS. Valida usuário, cliente e cpfecnpj; cria um Worker (fila certidao, tipo certidao_fgts) e dispara a task scraper_certidao_fgts. Registra log da emissão.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	query	sim	ID do usuário.
`customer_id`	`int`	query	sim	ID do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Automação da Certidão Negativa FGTS agendada com sucesso.",
  "data": null
}

Escopo: automation:write

`POST /automation/tax/iss/relatorios/scraper/`

Enfileira a geração dos Relatórios de ISS Salvador. Valida usuário e cliente; cria um Worker (fila scraping, tipo relatorio_iss) e dispara a task scraper_iss_relatorio. Registra log da geração.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	query	sim	ID do usuário.
`customer_id`	`int`	query	sim	ID do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Automação da geração de Relatórios ISS Salvador agendada com sucesso.",
  "data": null
}

Escopo: automation:write

`POST /automation/tax/iss/guias/scraper/`

Enfileira a geração das Guias de ISS Salvador. Valida usuário, cliente e inscricao_municipal; cria um Worker (fila scraping, tipo iss_guias) e dispara a task scraper_iss_guias. Registra log da geração.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`user_id`	`int`	query	sim	ID do usuário.
`customer_id`	`int`	query	sim	ID do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Automação da geração das Guias do ISS Salvador agendada com sucesso.",
  "data": null
}

Se a inscrição municipal não estiver cadastrada, retorna o envelope error_response.

Escopo: automation:write

Schemas

`TffScraperRequest`

Campo	Tipo	Obrigatório	Observações
`user_id`	`int`	sim	ID do usuário solicitante.
`customer_id`	`int`	sim	ID do cliente-alvo da automação.

`TffEnqueueResponse`

Campo	Tipo	Notas
`worker_id`	`int`	ID do Worker criado (consultável via Worker Automation).
`task_id`	`str`	UUID da task Celery enfileirada.
`message`	`str`	Mensagem de confirmação.

`TffBatchRequest`

Campo	Tipo	Obrigatório	Observações
`user_id`	`int`	sim	ID do usuário solicitante.
`customer_ids`	`List[int]`	sim	Lista de IDs de clientes do lote.

`TffBatchItem`

Campo	Tipo	Obrigatório	Observações
`customer_id`	`int`	sim	ID do cliente processado.
`worker_id`	`int` \| `null`	não	ID do Worker criado (ausente em falha).
`task_id`	`str` \| `null`	não	UUID da task Celery (ausente em falha).
`status`	`"ENFILEIRADO"` \| `"FALHA"`	sim	Resultado do item no lote.
`message`	`str` \| `null`	não	Mensagem de sucesso.
`erro`	`str` \| `null`	não	Descrição do erro, quando `status` = `FALHA`.

`TffBatchEnqueueResponse`

Campo	Tipo	Notas
`status`	`"enfileirado"`	Status geral do lote.
`total`	`int`	Total de clientes recebidos.
`enfileirados`	`int`	Quantidade enfileirada com sucesso.
`falhas`	`int`	Quantidade que falhou.
`itens`	`List[TffBatchItem]`	Resultado item a item (ver acima).

Notas

Padrão assíncrono (Celery). Salvo aliquota_iss/process-and-send e comparacao-nfe/process (que são síncronos), todas as rotas criam um Worker e enfileiram uma task Celery, retornando de imediato. Use o worker_id/task_id retornado e consulte o andamento em Worker Automation - em especial GET /worker-automation/status/{task_id}.
Filas utilizadas. Certidões (Sefaz Salvador/Bahia, Receita Federal, Trabalhista, FGTS) vão para a fila certidao; TFF Salvador, alvará e relatórios/guias de ISS vão para a fila scraping.
Escopo compartilhado. O escopo automation também habilita o subdomínio Automation: Acessorias, pois deriva apenas do 1º segmento da rota.
Envelope. As respostas de sucesso seguem { success: true, message, data } (via success_response) e as de erro { success: false, message, ... } (via error_response). Algumas validações das rotas de certidão/alvará retornam o formato simplificado { "error": "..." }.