> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sherlocker.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Benefício Social

> Benefício social do governo federal ou renúncia fiscal

Um **Benefício Social** representa um pagamento de programa social do governo federal vinculado a um CPF, ou uma renúncia fiscal vinculada a um CNPJ.

## Programas disponíveis

| Programa                | Descrição                                                        |
| ----------------------- | ---------------------------------------------------------------- |
| **Auxílio Brasil**      | Programa de transferência de renda (substituto do Bolsa Família) |
| **Bolsa Família**       | Programa histórico de transferência de renda                     |
| **Auxílio Emergencial** | Pagamentos durante a pandemia (2020-2021)                        |
| **BPC**                 | Benefício de Prestação Continuada (idosos e deficientes)         |

## Resposta

```json theme={null}
{
  "cpf": "91805040600",
  "nome": "João Da Silva",
  "total": 1,
  "auxilio_brasil": [],
  "auxilio_emergencial": [
    {
      "nis_beneficiario": "12345678901",
      "nis_responsavel": "12345678901",
      "mes_disponibilizacao": "2020-04",
      "uf": "MG",
      "codigo_municipio": "3106200",
      "nome_municipio": "Belo Horizonte",
      "enquadramento": "EXTRACAD",
      "parcela": "1",
      "observacao": null,
      "valor_beneficio": 1200.00
    }
  ],
  "bolsa_familia": [],
  "bpc": []
}
```

| Campo                 | Tipo    | Descrição                                                            |
| --------------------- | ------- | -------------------------------------------------------------------- |
| `cpf`                 | string  | CPF consultado (apenas dígitos)                                      |
| `nome`                | string  | Nome do beneficiário (Title Case). String vazia quando não resolvido |
| `total`               | integer | Total de benefícios encontrados (soma das quatro listas)             |
| `auxilio_brasil`      | array   | Parcelas do Auxílio Brasil                                           |
| `auxilio_emergencial` | array   | Parcelas do Auxílio Emergencial                                      |
| `bolsa_familia`       | array   | Parcelas do Bolsa Família                                            |
| `bpc`                 | array   | Parcelas do BPC                                                      |

## Auxílio Brasil / Bolsa Família

Ambos compartilham o mesmo formato.

```json theme={null}
{
  "nis_favorecido": "12345678901",
  "mes_competencia": "2023-01",
  "mes_referencia": "2023-01",
  "uf": "MG",
  "codigo_municipio": "3106200",
  "nome_municipio": "Belo Horizonte",
  "valor_parcela": 600.00
}
```

| Campo              | Tipo           | Descrição                      |
| ------------------ | -------------- | ------------------------------ |
| `nis_favorecido`   | string         | NIS do favorecido              |
| `mes_competencia`  | string         | Mês de competência (YYYY-MM)   |
| `mes_referencia`   | string         | Mês de referência (YYYY-MM)    |
| `uf`               | string         | UF                             |
| `codigo_municipio` | string         | Código do município            |
| `nome_municipio`   | string         | Nome do município (Title Case) |
| `valor_parcela`    | number \| null | Valor da parcela em R\$        |

## Auxílio Emergencial

```json theme={null}
{
  "nis_beneficiario": "12345678901",
  "nis_responsavel": "12345678901",
  "mes_disponibilizacao": "2020-04",
  "uf": "MG",
  "codigo_municipio": "3106200",
  "nome_municipio": "Belo Horizonte",
  "enquadramento": "EXTRACAD",
  "parcela": "1",
  "observacao": null,
  "valor_beneficio": 1200.00
}
```

| Campo                  | Tipo           | Descrição                              |
| ---------------------- | -------------- | -------------------------------------- |
| `nis_beneficiario`     | string         | NIS do beneficiário                    |
| `nis_responsavel`      | string         | NIS do responsável                     |
| `mes_disponibilizacao` | string         | Mês de disponibilização (YYYY-MM)      |
| `uf`                   | string         | UF                                     |
| `codigo_municipio`     | string         | Código do município                    |
| `nome_municipio`       | string         | Nome do município (Title Case)         |
| `enquadramento`        | string         | Enquadramento (`EXTRACAD`, `CADÚNICO`) |
| `parcela`              | string         | Número da parcela (1, 2, 3...)         |
| `observacao`           | string \| null | Observações (null quando não há)       |
| `valor_beneficio`      | number \| null | Valor do benefício em R\$              |

## BPC (Benefício de Prestação Continuada)

```json theme={null}
{
  "nis_beneficiario": "12345678901",
  "mes_competencia": "2023-01",
  "mes_referencia": "2023-01",
  "uf": "MG",
  "codigo_municipio": "3106200",
  "nome_municipio": "Belo Horizonte",
  "numero_beneficio": "1234567890",
  "beneficio_judicial": "Não",
  "valor_parcela": 1320.00
}
```

| Campo                | Tipo           | Descrição                                                 |
| -------------------- | -------------- | --------------------------------------------------------- |
| `nis_beneficiario`   | string         | NIS do beneficiário                                       |
| `mes_competencia`    | string         | Mês de competência (YYYY-MM)                              |
| `mes_referencia`     | string         | Mês de referência (YYYY-MM)                               |
| `uf`                 | string         | UF                                                        |
| `codigo_municipio`   | string         | Código do município                                       |
| `nome_municipio`     | string         | Nome do município (Title Case)                            |
| `numero_beneficio`   | string         | Número do benefício                                       |
| `beneficio_judicial` | string         | Se foi concedido judicialmente (texto bruto, ex: `"Não"`) |
| `valor_parcela`      | number \| null | Valor da parcela em R\$                                   |

## Renúncias Fiscais (Pessoa Jurídica)

```json theme={null}
{
  "ano_calendario": "2023",
  "cnpj": "12345678000199",
  "razao_social": "Empresa Ltda",
  "nome_fantasia": "Empresa",
  "codigo_cnae": "64221",
  "cnae": "Bancos múltiplos, com carteira comercial",
  "municipio": "São Paulo",
  "uf": "SP",
  "tipo_renuncia": "Declarado pelo Contribuinte para Apuração do IRPJ e da CSLL",
  "beneficio_fiscal": "Empresa Cidadã",
  "fundamento_legal": "Lei 11.770/2008",
  "descricao": "Salário-maternidade/paternidade estendido",
  "tributo": "IRPJ",
  "forma_tributacao": "Lucro Real",
  "valor_renuncia_fiscal": "50000.00"
}
```

| Campo                   | Tipo           | Descrição                                 |
| ----------------------- | -------------- | ----------------------------------------- |
| `ano_calendario`        | string         | Ano-base da renúncia                      |
| `cnpj`                  | string         | CNPJ da empresa beneficiária              |
| `razao_social`          | string         | Razão social                              |
| `nome_fantasia`         | string         | Nome fantasia                             |
| `codigo_cnae`           | string \| null | Código CNAE                               |
| `cnae`                  | string \| null | Descrição CNAE                            |
| `municipio`             | string         | Município                                 |
| `uf`                    | string \| null | UF                                        |
| `tipo_renuncia`         | string         | Tipo da renúncia                          |
| `beneficio_fiscal`      | string         | Nome do benefício fiscal                  |
| `fundamento_legal`      | string         | Base legal                                |
| `descricao`             | string         | Descrição detalhada                       |
| `tributo`               | string         | Tributo afetado (IRPJ, CSLL, PIS, COFINS) |
| `forma_tributacao`      | string \| null | Regime de tributação                      |
| `valor_renuncia_fiscal` | string         | Valor em R\$                              |

## Endpoints

| Rota                          | Descrição                  |
| ----------------------------- | -------------------------- |
| `GET /beneficios/cpf/{cpf}`   | Benefícios sociais por CPF |
| `GET /beneficios/cnpj/{cnpj}` | Renúncias fiscais por CNPJ |