Ir para o conteúdo principal

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: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:**Endpoint: Configurada via `SEF_SC_API_URL`SEF_SC_API_URL (padrão: `https://sat.sef.sc.gov.br/api/cnd/Certidao/Gerar`Gerar).
    *
    • **
  • Solicitante Padrão:** `CPFCNPJ_SOLICITANTE_PADRAO`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", 

// Identificacao.Type = "Cnpj" se len == 14, caso contrário "Cpf"

{
  "Identificacao": {
    "Type": "Cnpj",
    "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:

|

| | | |
|:---|:---|:--- | :--- |
| `Negativa` | `APROVADO` | `NEGATIVA` | |
|`Positiva`|`REPROVADO`|`POSITIVA` | |
|`PositivaComEfeitoNegativa`|`APROVADO`|`POSITIVA_NEGATIVA` | |
|* |`PENDENTE`| `INDEFINIDO` | |

###

Tipo Retornado (SEF-SC) Status Interno Tipo da Certidão Observação / Mensagem
Negativa APROVADO NEGATIVA Sem pendências.
Positiva REPROVADO POSITIVA Apresenta pendências na SEF-SC.
PositivaComEfeitoNegativa APROVADO POSITIVA_NEGATIVA Certidão positiva com efeito de negativa.
Qualquer outro*outro
 PENDENTE INDEFINIDO Tipo de certidão não reconhecido.

Tratamento de Datas

*

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

    | Cenário de Erro | Status de Obtenção | Mensagem de Retorno |
    | :--- | :--- | :--- |
    | Solicitante ausente (no contexto e no ambiente) | `ERRO_INTERNO` | *"É necessário informar o CPF do solicitante ou definir a variável..."* |
    | Falha física de rede / Timeout | `FALHA_COMUNICACAO` | Descrição técnica da exceção capturada. |
    | Resposta JSON corrompida ou inválida | `ERRO_INTERNO` | *"Resposta inválida de SEF-SC (JSON não é um dicionário)"* |
    | `ResultCode` diferente de `"OK"` | `ERRO_INTERNO` | Detalhes do erro e mensagens retornadas pela API da SEF-SC. |
    | Retorno sem o nó `"Data"` | `DOCUMENTO_NAO_ENCONTRADO` | Retorno vazio da API. |

Voltar ao topo