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/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.

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âmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário solicitante.
customer_idintquerysimID 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âmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário solicitante.
customer_idsList[int]querysimLista 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âmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário solicitante.
filesList[UploadFile]form-datasimUm 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âmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário solicitante.
tipo"NF-e Serviço" | "NF-e Entrada"querynãoTipo 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).

CampoTipoObrigatórioObservações
user_idintsimID do usuário solicitante. Inexistente retorna 404 ("Usuário não encontrado").
tipostrsimRECEITA FEDERAL, FGTS, TRABALHISTA, SEFAZ BAHIA ou SEFAZ SALVADOR.
customer_idsList[int]simDe 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 FALHA com o motivo em erro. Os inativos também entram em ignorados_inativos.
  • Emissão do mesmo tipo já agendada ou em execução (janela de 6 horas) vira item IGNORADO ("Já em andamento"), listado em ignorados_em_andamento e fora de falhas.
  • Falha ao enfileirar vira item FALHA com "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âmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário.
customer_idintquerysimID 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âmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário.
customer_idintquerysimID 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âmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário.
customer_idintquerysimID 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âmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário.
customer_idintquerysimID 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âmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário.
customer_idintquerysimID 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âmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário.
customer_idintquerysimID 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âmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário.
customer_idintquerysimID 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âmetroTipoLocalObrigatórioDescrição
user_idintquerysimID do usuário.
customer_idintquerysimID 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-aniversariantes

Response 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

CampoTipoObrigatórioObservações
user_idintsimID do usuário solicitante.
customer_idintsimID do cliente-alvo da automação.

TffEnqueueResponse

CampoTipoNotas
worker_idintID do Worker criado (consultável via Worker Automation).
task_idstrUUID da task enfileirada.
messagestrMensagem de confirmação.

TffBatchRequest

CampoTipoObrigatórioObservações
user_idintsimID do usuário solicitante.
customer_idsList[int]simLista de IDs de clientes do lote.

TffBatchItem

CampoTipoObrigatórioObservações
customer_idintsimID do cliente processado.
worker_idint | nullnãoID do Worker criado (ausente em falha).
task_idstr | nullnãoUUID da task (ausente em falha).
status"ENFILEIRADO" | "FALHA"simResultado do item no lote.
messagestr | nullnãoMensagem de sucesso.
errostr | nullnãoDescrição do erro, quando status = FALHA.

TffBatchEnqueueResponse

CampoTipoNotas
status"enfileirado"Status geral do lote.
totalintTotal de clientes recebidos.
enfileiradosintQuantidade enfileirada com sucesso.
falhasintQuantidade que falhou.
itensList[TffBatchItem]Resultado item a item (ver acima).
ignorados_inativosList[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/.

CampoTipoObrigatórioObservações
user_idintsimID do usuário solicitante.
tipostrsimRECEITA FEDERAL, FGTS, TRABALHISTA, SEFAZ BAHIA ou SEFAZ SALVADOR.
customer_idsList[int]sim1 a 2000 itens; repetidos são removidos.

CertidaoLoteItem

CampoTipoObservações
customer_idintCliente do item.
worker_idint | nullPresente quando ENFILEIRADO.
task_idstr | nullUUID da task, quando ENFILEIRADO.
status"ENFILEIRADO" | "FALHA" | "IGNORADO"Resultado do item.
messagestr | nullMensagem de sucesso ou de item ignorado.
errostr | nullMotivo, quando FALHA.

CertidaoLoteResponse

CampoTipoObservações
status"enfileirado"Status geral do lote.
totalintTotal de clientes (após remover repetidos).
enfileiradosintItens ENFILEIRADO.
falhasintItens FALHA (inclui os de cliente inativo).
itensList[CertidaoLoteItem]Resultado na ordem de customer_ids.
ignorados_inativosList[int]IDs de clientes inativos (já contados em falhas).
ignorados_em_andamentoList[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-send e comparacao-nfe/process (que são síncronos), todas as rotas criam um Worker e agendam uma task, 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}.
  • 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 { status: "success", message, data } (via success_response) e as de erro { status: "error", message, ... } (via error_response). Algumas validações das rotas de certidão/alvará retornam o formato simplificado { "error": "..." }.