integração sefsc <> sct

# Integração SEF-SC — Certidão Negativa de Débitos (CND)

Este documento descreve a integração com a API da Secretaria de Estado da Fazenda de Santa Catarina (SEF-SC) para a emissão automática de CND Estadual (CNPJ ou CPF).

---

## 1. Visão Geral do Fluxo

O processo de obtenção do documento segue as seguintes etapas:

```
[Início]
│
├── 1. Recupera CPF do Solicitante (Contexto ou Env Var)
├── 2. Identifica tipo do contribuinte (CPF vs CNPJ pelo tamanho)
├── 3. Envia requisição POST para a API SEF-SC
├── 4. Valida a estrutura de retorno (ResultCode, Data)
├── 5. Mapeia o Tipo da Certidão (Status e Regras de Validade)
└── 6. Decodifica o PDF (Base64) e gera o Resultado
```

---

## 2. Configurações e Variáveis de Ambiente

* **URL do Endpoint:** Configurada via `SEF_SC_API_URL` (padrão: `https://sat.sef.sc.gov.br/api/cnd/Certidao/Gerar`).
* **Solicitante Padrão:** `CPFCNPJ_SOLICITANTE_PADRAO`. Utilizado como *fallback* caso nenhum CPF do solicitante seja fornecido no contexto da requisição.

---

## 3. Estrutura de Comunicação da API

### Requisição (POST)
O payload exige a identificação do contribuinte consultado e o CPF do solicitante.

```json
{
"Identificacao": {
"Type": "Cnpj", // "Cnpj" se len == 14, caso contrário "Cpf"
"Value": "12075748000132"
},
"CpfSolicitante": {
"Type": "Cpf",
"Value": "00000000000"
}
}
```

### Resposta de Sucesso (Exemplo)
```json
{
"ResultCode": "OK",
"Data": {
"Numero": "250140126228731",
"Identificacao": {
"Type": "Cnpj",
"Value": "12075748000132"
},
"Nome": "CONSORCIO INTERFEDERATIVO SANTA CATARINA",
"Tipo": "Negativa",
"DataEmissao": "2025-04-22T15:47:40",
"DataValidade": "2025-10-19T15:47:40",
"Situacao": "Valida",
"OrigemDebitos": null,
"ArquivoCndPdf": {
"CND": "250140126228731",
"Nome": "CND_250140126228731.pdf",
"Dados": "<Conteudo do arquivo em base64>",
"ContentType": "application/pdf"
}
},
"Messages": null
}
```

---

## 4. Regras de Negócio e Processamento de Dados

### Mapeamento de Status do Documento

A partir do campo `"Tipo"` retornado na resposta, define-se o status interno:

### Tratamento de Datas

* **Timezone:** Se a string de data da API não contiver fuso horário explícito, é assumido o sufixo `-03:00` (horário de Brasília).
* **Ajuste para Certidão Positiva:** Caso a certidão seja classificada como `POSITIVA`, a data de validade é ajustada para o final do mesmo dia da emissão (`23:59:59.999999`).

### Processamento do PDF

* Se houver o nó `ArquivoCndPdf` contendo a chave `Dados`, o sistema realiza a decodificação de Base64 para Bytes.
* O arquivo é salvo internamente como `cnd-estadual-sc.pdf`. Falhas de decodificação geram alertas em log, mas não interrompem o fluxo principal.

---

## 5. Tratamento de Erros e Exceções