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 agenda uma task, 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.
Base path
/api/v1/automationAs 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ãoPOST).
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.
user_id e cliente inativo
Nas rotas que enfileiram automação, o user_id informado precisa ser o do próprio usuário autenticado (ou o usuário da credencial). Enviar o user_id de outro usuário resulta em 403, exceto para usuários com permissão adicional.
Cliente inativo resulta em 409 ("Cliente inativo: automações bloqueadas.") nas rotas individuais. Nos lotes, o cliente inativo não derruba a chamada: vira item FALHA e o customer_id (ou o arquivo, em aliquota_iss) é listado em ignorados_inativos.
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 { status, message, data }; as rotas que agendam tasks 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 (tipo tff_salvador) e agenda a task.
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 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": "..."
}
],
"ignorados_inativos": []
}Cliente inativo vira item FALHA (erro: "Cliente inativo: automações bloqueadas."), conta em falhas e seu customer_id também entra em ignorados_inativos.
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 (tipo alvara_salvador) e agenda a task.
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
{
"status": "success",
"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) 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" },
{ "customer_id": 1002, "erro": "Cliente inativo: automações bloqueadas." }
],
"ignorados_inativos": [1002]
}ignorados_inativos lista os customer_id de clientes inativos, que também aparecem em itens com erro e contam em falhas.
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 agenda task) - 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": {},
"ignorados_inativos": []
}ignorados_inativos lista os nomes dos arquivos que não foram enviados por pertencerem a cliente inativo. Se todos os arquivos forem de cliente inativo, retorna o envelope de erro com a mensagem "Cliente inativo: automações bloqueadas. Nenhum arquivo enviado (N de cliente inativo)." e details: { "ignorados_inativos": [...] }.
Se o usuário não existir ou o processamento falhar, retorna o envelope de erro error_response ({ status: "error", 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/selected/
Enfileira um tipo de certidão negativa para vários clientes de uma vez. Para cada cliente cria um Worker e agenda a mesma task das rotas individuais do tipo escolhido.
Parâmetros
Sem parâmetros de rota ou query - os dados vão no corpo (CertidaoLoteRequest, ver Schemas).
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
user_id | int | sim | ID do usuário solicitante. Inexistente retorna 404 ("Usuário não encontrado"). |
tipo | str | sim | RECEITA FEDERAL, FGTS, TRABALHISTA, SEFAZ BAHIA ou SEFAZ SALVADOR. |
customer_ids | List[int] | sim | De 1 a 2000 IDs. Repetidos são removidos, preservando a ordem. |
Request
{
"user_id": 42,
"tipo": "FGTS",
"customer_ids": [101, 102, 103, 999]
}Response 200 OK
{
"status": "enfileirado",
"total": 4,
"enfileirados": 1,
"falhas": 2,
"itens": [
{
"customer_id": 101,
"worker_id": 830,
"task_id": "d6e1f4b5-3c7a-4b0d-9e4f-5a8d9c1b2f3a",
"status": "ENFILEIRADO",
"message": "Enfileirado com sucesso",
"erro": null
},
{ "customer_id": 102, "status": "IGNORADO", "message": "Já em andamento" },
{ "customer_id": 103, "status": "FALHA", "erro": "Cliente inativo: automações bloqueadas." },
{ "customer_id": 999, "status": "FALHA", "erro": "Cliente não encontrado" }
],
"ignorados_inativos": [103],
"ignorados_em_andamento": [102]
}Regras por cliente (nenhuma derruba o lote):
- Inexistente, inativo ou sem CNPJ cadastrado vira item
FALHAcom o motivo emerro. Os inativos também entram emignorados_inativos. - Emissão do mesmo tipo já agendada ou em execução (janela de 6 horas) vira item
IGNORADO("Já em andamento"), listado emignorados_em_andamentoe fora defalhas. - Falha ao enfileirar vira item
FALHAcom"Não foi possível enfileirar este cliente. Tente novamente.".
403 se o user_id for de outro usuário e o chamador não tiver permissão adicional.
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 (tipo certidao_sefaz_salvador) e agenda a task. 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
{
"status": "success",
"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 (tipo certidao_sefaz_bahia) e agenda a task. 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
{
"status": "success",
"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 consulta automatizada no portal da Receita. Valida usuário, cliente e cpfecnpj; cria um Worker (tipo certidao_receita_federal) e agenda a task. 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
{
"status": "success",
"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 da consulta no portal. O resultado é gravado como as demais certidões de Receita Federal. Cria um Worker (tipo certidao_receita_federal) e agenda a task.
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
{
"status": "success",
"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 (tipo certidao_trabalhista) e agenda a task. 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
{
"status": "success",
"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 (tipo certidao_fgts) e agenda a task. 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
{
"status": "success",
"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 (tipo relatorio_iss) e agenda a task. 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
{
"status": "success",
"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 (tipo iss_guias) e agenda a task. 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
{
"status": "success",
"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
POST /automation/ekontrol/sync-aniversariantes
Enfileira a sincronização de aniversariantes com o e-Kontrol, que lê todas as empresas do e-Kontrol. Cria um Worker e retorna de imediato (padrão assíncrono). Este endpoint fica sob o prefixo /automation/ekontrol (tag Automation: e-Kontrol), e não sob /automation/tax.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query nem corpo.
Request
POST /api/v1/automation/ekontrol/sync-aniversariantesResponse 200 OK
{
"status": "success",
"message": "Sincronização de aniversariantes agendada com sucesso.",
"data": {
"worker_id": 8421
}
}Acompanhe a execução com GET /worker-automation/{worker_id} (status, progress e o resumo em metadata_json) e cancele com POST /worker-automation/{worker_id}/cancel. Veja Worker Automation.
Erros
403 sem a permissão adicional exigida; 409 se já houver uma sincronização de aniversariantes agendada ou em execução (cancele a travada pelo /cancel); 429 se o limite de requisições for excedido; 503 se o processamento estiver indisponível (a sincronização não é agendada).
Escopo: automation:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
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 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 (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). |
ignorados_inativos | List[int] | IDs de clientes inativos. Também aparecem em itens como FALHA e contam em falhas. |
CertidaoLoteRequest
Corpo de POST /automation/tax/certidao-negativa/selected/.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
user_id | int | sim | ID do usuário solicitante. |
tipo | str | sim | RECEITA FEDERAL, FGTS, TRABALHISTA, SEFAZ BAHIA ou SEFAZ SALVADOR. |
customer_ids | List[int] | sim | 1 a 2000 itens; repetidos são removidos. |
CertidaoLoteItem
| Campo | Tipo | Observações |
|---|---|---|
customer_id | int | Cliente do item. |
worker_id | int | null | Presente quando ENFILEIRADO. |
task_id | str | null | UUID da task, quando ENFILEIRADO. |
status | "ENFILEIRADO" | "FALHA" | "IGNORADO" | Resultado do item. |
message | str | null | Mensagem de sucesso ou de item ignorado. |
erro | str | null | Motivo, quando FALHA. |
CertidaoLoteResponse
| Campo | Tipo | Observações |
|---|---|---|
status | "enfileirado" | Status geral do lote. |
total | int | Total de clientes (após remover repetidos). |
enfileirados | int | Itens ENFILEIRADO. |
falhas | int | Itens FALHA (inclui os de cliente inativo). |
itens | List[CertidaoLoteItem] | Resultado na ordem de customer_ids. |
ignorados_inativos | List[int] | IDs de clientes inativos (já contados em falhas). |
ignorados_em_andamento | List[int] | IDs com emissão do mesmo tipo em andamento (itens IGNORADO, fora de falhas). |
Notas
- Padrão assíncrono. Salvo
aliquota_iss/process-and-sendecomparacao-nfe/process(que são síncronos), todas as rotas criam um Worker e agendam uma task, retornando de imediato. Use oworker_id/task_idretornado e consulte o andamento em Worker Automation - em especialGET /worker-automation/status/{task_id}. - Escopo compartilhado. O escopo
automationtambém habilita o subdomínio Automation: Acessorias, pois deriva apenas do 1º segmento da rota. - Envelope. As respostas de sucesso seguem
{ status: "success", message, data }(viasuccess_response) e as de erro{ status: "error", message, ... }(viaerror_response). Algumas validações das rotas de certidão/alvará retornam o formato simplificado{ "error": "..." }.