# VC Digital: automação de guias vencidas

## Objetivo

Permitir que o VC Digital acione o desktop SEFIN para:

- setar a empresa correta
- abrir a carteira certa da controladora
- localizar apenas guias vencidas
- consumir apenas as datas reais oferecidas pela SEFIN
- emitir `1` ou `2` guias vencidas por job
- reenviar os novos documentos ao ICMS SaaS
- disponibilizar o resultado atualizado para o painel fiscal

## Endpoint

- `GET /api/internal/fiscal-documents/due-options`
- `POST /api/internal/orchestrator/jobs`
- `GET /api/internal/orchestrator/jobs`

Usa o mesmo header:

- `Authorization: Bearer <token-da-controladora>`

## Fluxo recomendado

1. consultar `due-options` por `numeroDocumento + parcela`
2. verificar se a guia ja esta pronta para consumo no ICMS
3. escolher `targetDueDate` somente dentro de `availableDueDates[]`
4. criar o job no orquestrador
5. acompanhar `GET /api/internal/orchestrator/jobs?numeroDocumento=...&parcela=...`
6. depois de `CONCLUIDO`, voltar em `GET /api/internal/fiscal-documents`

## Automacao D+1 da vitrine

Quando a guia vencer nas pastas locais e chegar `D+1`:

1. o desktop local identifica empresas em `companies_due_yesterday_pending_review`
2. gera uma fila automatica de recálculo com relatório próprio
3. se o modo autônomo estiver ligado, dispara `lote expresso` dessas empresas
4. emite a nova guia recalculada usando apenas datas reais da SEFIN
5. reenviа o novo artefato ao ICMS SaaS
6. o ICMS passa a expor o artefato mais novo como documento vigente da vitrine
7. o VC Digital deve reconsumir o endpoint principal e substituir o documento anterior

Regra publicada:

- não apagar histórico bruto no ICMS como primeira opção
- a substituição operacional deve ocorrer pelo artefato mais novo
- usar `POST /api/internal/fiscal-documents/force-republish` apenas quando o VC Digital já tiver importado o artefato antigo e precisar de um `artifactId` novo para refresh explícito
- se `recalculada = true`, o consumo deve seguir `vencimentoEmitido`
- a vitrine do VC Digital deve considerar `dueDateReal` como a data fiscal vigente

## Payload recomendado

```json
{
  "controladoraId": 1,
  "commandType": "fetch_company_documents",
  "companyId": 3,
  "companyKey": "00000000285056 - DROGA MIL COMERCIO DE MEDICAMENTOS LTDA",
  "cnpj": "34754978000160",
  "year": 2026,
  "overdueOnly": true,
  "overdueGuideLimit": 2,
  "consumeAvailableDueDates": true,
  "priority": 80,
  "requestedBy": "VC Digital",
  "notes": "Atualizar guias vencidas com datas reais da SEFIN"
}
```

## Payload recomendado para remissao pontual

```json
{
  "controladoraId": 1,
  "commandType": "fetch_numero_documento",
  "companyId": 97,
  "cnpj": "0000006559719",
  "numeroDocumento": "20261600483103",
  "parcela": "00",
  "year": 2026,
  "targetDueDate": "2026-03-31",
  "consumeAvailableDueDates": true,
  "force": true,
  "requestedBy": "VC Digital",
  "notes": "Reemissao pontual para envio ao cliente"
}
```

## Semântica dos campos novos

- `parcela`
  - identifica a linha correta quando o mesmo `numeroDocumento` tiver mais de uma obrigação
  - o desktop filtra exatamente `numeroDocumento + parcela`

- `targetDueDate`
  - data alvo desejada para a reemissão
  - aceita `YYYY-MM-DD` ou `DD/MM/YYYY`
  - só pode ser usada se existir em `availableDueDates[]`
  - se a data não existir, o job falha com erro funcional e devolve a lista válida

- `overdueOnly`
  - `true`: o desktop processa apenas guias vencidas
  - `false` ou ausente: segue o fluxo normal da empresa

- `overdueGuideLimit`
  - `1`: emite uma guia vencida
  - `2`: emite até duas guias vencidas
  - valores fora desse intervalo são limitados pelo desktop

- `consumeAvailableDueDates`
  - `true`: o desktop usa apenas as datas oferecidas no seletor da SEFIN
  - não cria data artificial para guia em dia
  - quando a guia estiver vencida, a data final sai da própria lista da SEFIN
  - se `vencimento_lista` estiver presente na lista da SEFIN, essa data passa a ser a preferencial
  - se a guia for de `02/2026` e `31/03/2026` estiver disponivel, o desktop emite `31/03/2026`

## Comportamento publicado do desktop

1. recebe o job do orquestrador
2. seleciona a controladora
3. seleciona a empresa correta pelo `companyId`, `cnpj` ou `companyKey`
4. abre `Consulta Débitos`
5. filtra apenas guias vencidas quando `overdueOnly = true`
6. se `commandType = fetch_numero_documento`, entra em `single-document mode`
7. nesse modo, limita a execução à `guia + parcela` pedida e encerra logo após concluir
8. limita a emissão em `1` ou `2` guias quando `overdueGuideLimit` vier preenchido
9. abre a página do DARE
10. lê `availableDueDates` diretamente da SEFIN
11. resolve o CAPTCHA
12. baixa DARE e extrato
13. reenvia ao ICMS SaaS
14. o endpoint fiscal passa a expor o vencimento novo em `dueDateReal`

## Snapshot validado em 2026-03-16

- `20` guias unicas com `vencimento_lista = 31/03/2026` estavam sendo emitidas com datas intermediarias e foram marcadas para correção no catalogo local
- `12` guias unicas de `02/2026` ja possuem evidencia real de substituicao para `31/03/2026`
- `77` entradas do catalogo local foram corrigidas ou deixadas pendentes de republicacao para o ICMS SaaS

## Consumo no endpoint fiscal

Depois do processamento, o VC Digital deve voltar ao endpoint:

- `GET /api/internal/fiscal-documents`
- `GET /api/internal/orchestrator/jobs?numeroDocumento=...&parcela=...`

Campos de interesse:

- `dueDate`
- `dueDateReal`
- `dueDateSource`
- `vencimentoOriginal`
- `vencimentoEmitido`
- `availableDueDates`
- `recalculada`
- `result_selected_due_date`
- `result_available_due_dates`

## Regra operacional

- guia não vencida: não recalcular por automação
- guia vencida: usar somente `availableDueDates` da SEFIN
- quando `vencimentoOriginal = 31/03/2026` e essa data existir em `availableDueDates`, consumir `31/03/2026`
- quando a guia original for de `02/2026` e `31/03/2026` estiver disponivel, substituir a versao vencida pela guia emitida para `31/03/2026`
- se o ICMS SaaS devolver a mesma guia com novo artefato, o VC Digital deve substituir a anterior
- no monitor D+1, a empresa entra em fila automática de recálculo no desktop antes do outro time tentar consumir manualmente uma guia vencida

## Exemplo de resposta esperada do orquestrador

```json
{
  "error": false,
  "created": true,
  "reason": "created",
  "message": "Job criado."
}
```