# Status das SEFAZs

> Consulte o status da SEFAZ de cada estado para NF-e, NFC-e e CT-e.

URL: https://docs.fiscalapi.com.br/docs/sefaz-monitor/status-sefaz


`GET` **`/api/v1/sefaz/status`**

Retorna o status dos serviços de autorização da SEFAZ por estado, para NF-e, NFC-e e CT-e. Cada resposta reflete uma leitura feita há no máximo 2 minutos; o horário dela vem em `timestamp`.

Útil para verificar se uma SEFAZ está operando normalmente antes de enviar documentos fiscais, ou para exibir um painel de status no seu sistema.

## ## Autenticação

Envie sua chave no header `X-API-Key`. Veja [Autenticação](/docs/getting-started/authentication) para detalhes.

## ## Parâmetros de consulta

| Nome  | Tipo   | Obrigatório | Padrão | Descrição                                         |
| ----- | ------ | ----------- | ------ | ------------------------------------------------- |
| `doc` | string | Não         | `nfe`  | Tipo de documento fiscal: `nfe`, `nfce` ou `cte`. |

## ## Exemplos de código

<Tabs items="[&#x22;curl&#x22;, &#x22;JavaScript&#x22;, &#x22;Python&#x22;, &#x22;PHP&#x22;, &#x22;C#&#x22;]">
  <Tab value="curl">
    ```bash
    curl -X GET "https://api.fiscalapi.com.br/api/v1/sefaz/status?doc=nfe" \
      -H "X-API-Key: fapi_sua_chave_aqui"
    ```
  </Tab>

  <Tab value="JavaScript">
    ```javascript
    const response = await fetch(
      "https://api.fiscalapi.com.br/api/v1/sefaz/status?doc=nfe",
      { headers: { "X-API-Key": "fapi_sua_chave_aqui" } }
    );
    const data = await response.json();

    // Filtrar estados com problema
    const problemas = data.states.filter(s => s.status_code > 1);
    console.log(`${problemas.length} estados com problema`);
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    response = requests.get(
        "https://api.fiscalapi.com.br/api/v1/sefaz/status",
        headers={"X-API-Key": "fapi_sua_chave_aqui"},
        params={"doc": "nfe"},
    )
    data = response.json()

    # Filtrar estados com problema
    problemas = [s for s in data["states"] if s["status_code"] > 1]
    print(f"{len(problemas)} estados com problema")
    ```
  </Tab>

  <Tab value="PHP">
    ```php
    $response = Http::withHeaders([
        'X-API-Key' => 'fapi_sua_chave_aqui',
    ])->get('https://api.fiscalapi.com.br/api/v1/sefaz/status', [
        'doc' => 'nfe',
    ]);
    $data = $response->json();

    // Filtrar estados com problema
    $problemas = array_filter($data['states'], fn($s) => $s['status_code'] > 1);
    ```
  </Tab>

  <Tab value="C#">
    ```csharp
    var client = new HttpClient();
    client.DefaultRequestHeaders.Add("X-API-Key", "fapi_sua_chave_aqui");
    var response = await client.GetAsync(
        "https://api.fiscalapi.com.br/api/v1/sefaz/status?doc=nfe"
    );
    var json = await response.Content.ReadAsStringAsync();
    ```
  </Tab>
</Tabs>

## ## Resposta

### ### Campos de nível superior

| Campo       | Tipo   | Descrição                                             |
| ----------- | ------ | ----------------------------------------------------- |
| `doc`       | string | Tipo de documento consultado: `nfe`, `nfce` ou `cte`. |
| `timestamp` | string | Momento da leitura, em ISO 8601 (UTC).                |
| `states`    | array  | Lista com o status de cada estado (27 itens).         |

### ### Campos de cada estado (`states[]`)

| Campo         | Tipo    | Descrição                                                                                                             |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `uf`          | string  | Sigla do estado (ex: `SP`, `MT`, `RJ`).                                                                               |
| `status_code` | integer | Código numérico do status (0 a 5).                                                                                    |
| `status`      | string  | Descrição legível do status.                                                                                          |
| `status_avg`  | number  | Média dos códigos de status no período (de 1 a 5; `0.0` na UF sem leitura). O `status_code` é esse valor arredondado. |

### ### Códigos de status

| Código | Status                                          | Descrição                                                                                                |
| ------ | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `0`    | `Indisponivel` (sem acento, como a API devolve) | Sem leitura para esta UF no momento da coleta. Estado transitório, costuma normalizar no ciclo seguinte. |
| `1`    | Normal                                          | SEFAZ respondendo dentro do esperado.                                                                    |
| `2`    | Lento                                           | Respostas mais lentas que o normal.                                                                      |
| `3`    | Muito lento                                     | Respostas muito lentas.                                                                                  |
| `4`    | Erro                                            | SEFAZ retornando erro.                                                                                   |
| `5`    | Timeout                                         | SEFAZ não respondeu dentro do tempo limite.                                                              |

### ### Exemplo de resposta

```json
{
  "doc": "nfe",
  "timestamp": "2026-04-06T15:30:00.000000+00:00",
  "states": [
    {
      "uf": "AC",
      "status_code": 2,
      "status": "Lento",
      "status_avg": 2.1834
    },
    {
      "uf": "AL",
      "status_code": 1,
      "status": "Normal",
      "status_avg": 1.0712
    },
    {
      "uf": "AM",
      "status_code": 1,
      "status": "Normal",
      "status_avg": 1.1234
    },
    {
      "uf": "SP",
      "status_code": 1,
      "status": "Normal",
      "status_avg": 1.0521
    }
  ]
}
```

<Callout type="info">
  A resposta sempre inclui as 27 UFs brasileiras (26 estados + DF), ordenadas alfabeticamente pela sigla. Quando uma UF fica sem leitura, ela vem com `status_code: 0` (`"status": "Indisponivel"`) em vez de ser omitida.
</Callout>

## ## Casos de uso

* **Painel de status:** Exiba um dashboard com o status de cada SEFAZ para sua equipe fiscal.
* **Verificação pré-envio:** Antes de transmitir um lote de NF-e, verifique se a SEFAZ do estado está operando normalmente.
* **Alertas automáticos:** Configure alertas quando um estado muda de `Normal` para `Lento`, `Erro` ou `Timeout`.
* **Decisão de contingência:** Use o status para decidir automaticamente quando ativar o modo de contingência (SVC-AN/SVC-RS).

## ## Códigos de erro

| Código                       | HTTP Status | Descrição                                                  |
| ---------------------------- | ----------- | ---------------------------------------------------------- |
| `MONITOR_INDISPONIVEL`       | 502         | Não foi possível consultar o status das SEFAZs no momento. |
| Erro de validação (`detail`) | 422         | O parâmetro `doc` deve ser `nfe`, `nfce` ou `cte`.         |