# Changelog Curto da Integração VC Digital

Atualizado em:
- `2026-05-13`

Público:
- time do `app.vcnodigital.com`

## O que mudou no contrato

### 1. Chave de identificação ficou mais rígida

Agora o app deve identificar documento por:
- `guideId + documentType`

Fallback aceito:
- `companyId + numeroDocumento + parcela + documentType`

Não usar:
- `numeroDocumento` sozinho

Motivo:
- evita mistura entre empresas
- evita mistura entre parcelas
- evita sobrescrever documento antigo com versão errada

### 2. O fluxo padrão agora é orientado a evento

Ordem recomendada:
1. `GET /api/internal/fiscal-documents/upload-events`
2. `GET /api/internal/fiscal-documents?pending_only=1`
3. importar `documents[]`
4. `POST /api/internal/fiscal-documents/mark-exported`
5. `POST /api/internal/fiscal-documents/mark-delivered`

### 3. Documento final continua vindo de `documents[]`

Regra:
- usar `documents[]` para consumo normal
- usar `auditArtifacts[]` só em suporte/auditoria

Importante:
- `extrato_*` sozinho não deve ser tratado como documento final

### 4. Reemissão agora precisa consultar datas reais antes

Antes de abrir job:
- chamar `GET /api/internal/fiscal-documents/due-options`

Só depois:
- `POST /api/internal/orchestrator/jobs`

### 5. Substituição de documento antigo ficou explícita

Quando a mesma chave voltar com novo `artifactId`:
- substituir o documento vigente no app
- isso vale para reemissão normal e para `force-republish`

### 6. Pagamento inferido tem feed próprio

Novo consumo operacional:
- `GET /api/internal/fiscal-documents/payment-events`

Ao receber `SEFIN_PAYMENT_INFERRED`:
- tirar da vitrine
- mover para histórico local

## Ação esperada do time do app

- ajustar deduplicação para usar a chave nova
- consumir `upload-events` e `payment-events` com cursor
- tratar `documents[]` como fonte final
- confirmar `mark-exported` só após importação real
- confirmar `mark-delivered` só após envio real ao cliente

## Documentos para começar

- `GET /docs/vc-digital-consumo-app.md`
- `GET /docs/vc-digital.md`
- `GET /docs/vc-digital-curl-examples.txt`