Certidão Negativa

Gestão de Certidões Negativas de Débito (CND) emitidas pela Alcance Contabilidade para seus clientes - abrangendo Receita Federal, FGTS, SEFAZ Salvador e SEFAZ Bahia. Os endpoints cobrem registro de emissões, consulta com filtros, analytics, monitoramento por categoria de pendência, download do PDF e envio por e-mail/WhatsApp.

Base path

/api/v1/certidao-negativa

Todos os endpoints exigem header Authorization: Bearer <API_KEY> e a API Key emitida pela WebApiAlcance precisa carregar os escopos abaixo.

Escopos necessários

Escopo	Endpoints cobertos
`certidao_negativa:read`	`GET /`, `GET /{id}`, `GET /{id}/pdf`, `GET /stats`, `GET /monitoring`, `GET /monitoring/list`
`certidao_negativa:write`	`POST /`, `PUT /{id}`, `DELETE /{id}`, `POST /{id}/enviar-email/{email}`, `POST /{id}/enviar-whatsapp/{numero}`

Endpoints

`POST /certidao-negativa/`

Registra uma nova certidão. Aceita pdf_base64 opcional no payload - campo grande, mas necessário se você quiser baixar o PDF depois via /{id}/pdf.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (CertidaoNegativaCreate): id_usuario, id_cliente, tipo e status são obrigatórios; observacao, data_validade, pdf_base64, negativa e motivo são opcionais.

Request

{
  "id_usuario": 12,
  "id_cliente": 487,
  "tipo": "RECEITA FEDERAL",
  "status": "Concluido",
  "observacao": "Emissão automática via rotina diária",
  "data_validade": "2026-08-14T00:00:00",
  "pdf_base64": "JVBERi0xLjcKJeLjz9MK...",
  "negativa": true,
  "motivo": null
}

Response 200 OK

{
  "success": true,
  "message": "Certidão registrada com sucesso!",
  "data": {
    "id": 9821,
    "id_usuario": 12,
    "id_cliente": 487,
    "tipo": "RECEITA FEDERAL",
    "status": "Concluido",
    "observacao": "Emissão automática via rotina diária",
    "data_hora_emissao": "2026-05-15T08:14:22",
    "data_validade": "2026-08-14T00:00:00",
    "negativa": true,
    "motivo": null
  }
}

Escopo: certidao_negativa:write

`GET /certidao-negativa/stats`

Retorna estatísticas consolidadas (totais por tipo, status, taxa de sucesso, médias de validade). Útil para dashboards executivos.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Estatísticas geradas com sucesso!",
  "data": {
    "total": 1284,
    "por_tipo": {
      "RECEITA FEDERAL": 412,
      "FGTS": 388,
      "SEFAZ BAHIA": 301,
      "SEFAZ SALVADOR": 183
    },
    "por_status": {
      "Concluido": 1190,
      "Falha": 94
    },
    "taxa_sucesso": 0.9268
  }
}

Escopo: certidao_negativa:read

`GET /certidao-negativa/monitoring`

Retorna contadores agregados das categorias de monitoramento (sem listar registros). Pareie com /monitoring/list quando precisar dos itens.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Dados de monitoramento gerados com sucesso!",
  "data": {
    "sem_certidao": 37,
    "com_pendencia": 21,
    "exigibilidade_suspensa": 8,
    "total_sucesso": 1190,
    "total_vencidas": 64,
    "total_falhas": 94
  }
}

Escopo: certidao_negativa:read

`GET /certidao-negativa/monitoring/list`

Retorna listas (não contadores) do monitoramento, segmentadas por categoria. Categoria inválida retorna 400 Bad Request.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`tipo`	`str`	query	não	Filtra por tipo (ex.: `SEFAZ BAHIA`, `FGTS`, `RECEITA FEDERAL`).
`categoria`	`str`	query	não	Uma de: `sem_certidao`, `com_pendencia`, `exigibilidade_suspensa`, `total_sucesso`, `total_vencidas`, `total_falhas`.
`limit`	`int`	query	não	1-10000. Se omitido, retorna tudo (cuidado com volume).
`offset`	`int`	query	não	Default `0`.

Exemplo: GET /certidao-negativa/monitoring/list?tipo=SEFAZ BAHIA&categoria=com_pendencia&limit=50.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Listas de monitoramento geradas com sucesso!",
  "data": {
    "com_pendencia": [
      {
        "id": 9754,
        "id_cliente": 512,
        "tipo": "SEFAZ BAHIA",
        "status": "Concluido",
        "negativa": false,
        "motivo": "Débitos de ICMS em aberto",
        "data_hora_emissao": "2026-05-10T07:02:11",
        "data_validade": "2026-08-08T00:00:00"
      }
    ]
  }
}

Escopo: certidao_negativa:read

`GET /certidao-negativa/{certidao_id}`

Retorna CertidaoNegativaRead com pdf_base64 incluído. Use quando precisar do conteúdo binário em base64 (ex.: anexar a um e-mail externo). Quando não encontrada, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`certidao_id`	`int`	path	sim	ID interno da certidão

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Certidão encontrada com sucesso!",
  "data": {
    "id": 9821,
    "id_usuario": 12,
    "id_cliente": 487,
    "tipo": "RECEITA FEDERAL",
    "status": "Concluido",
    "observacao": null,
    "data_hora_emissao": "2026-05-15T08:14:22",
    "data_validade": "2026-08-14T00:00:00",
    "pdf_base64": "JVBERi0xLjcK...",
    "negativa": true,
    "motivo": null
  }
}

Escopo: certidao_negativa:read

`GET /certidao-negativa/`

Lista paginada sem pdf_base64 (ver schema CertidaoNegativaListItem abaixo). Lista vazia é estado válido - retorna 200 OK com data: [].

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`customer_id`	`int`	query	não	Filtra por `id_cliente`.
`tipo`	`str`	query	não	Case-insensitive. Ex.: `FGTS`, `RECEITA FEDERAL`.
`status`	`str`	query	não	Case-insensitive. Ex.: `Concluido`, `Falha`.
`start_date`	`datetime`	query	não	`data_hora_emissao >= start_date`.
`end_date`	`datetime`	query	não	`data_hora_emissao <= end_date`.
`limit`	`int`	query	não	1-500. Se omitido, retorna todos que casarem.
`offset`	`int`	query	não	Default `0`.

Exemplo: GET /certidao-negativa/?customer_id=487&tipo=FGTS&status=Concluido&start_date=2026-01-01&limit=50.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Certidões encontradas com sucesso!",
  "data": [
    {
      "id": 9821,
      "id_usuario": 12,
      "id_cliente": 487,
      "tipo": "RECEITA FEDERAL",
      "status": "Concluido",
      "observacao": null,
      "data_hora_emissao": "2026-05-15T08:14:22",
      "data_validade": "2026-08-14T00:00:00",
      "negativa": true,
      "motivo": null
    }
  ]
}

Escopo: certidao_negativa:read

`PUT /certidao-negativa/{certidao_id}`

Atualiza campos mutáveis de uma certidão. O body é um CertidaoNegativaUpdate com campos parciais - somente observacao, status, pdf_base64 e motivo podem ser alterados.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`certidao_id`	`int`	path	sim	ID da certidão

Request (CertidaoNegativaUpdate - todos os campos opcionais)

{
  "observacao": "Reemitida após indisponibilidade do Portal Receita",
  "status": "Concluido",
  "pdf_base64": "JVBERi0xLjcK...",
  "motivo": null
}

Response 200 OK

{
  "success": true,
  "message": "Certidão atualizada com sucesso!",
  "data": {
    "id": 9821,
    "id_usuario": 12,
    "id_cliente": 487,
    "tipo": "RECEITA FEDERAL",
    "status": "Concluido",
    "observacao": "Reemitida após indisponibilidade do Portal Receita",
    "data_hora_emissao": "2026-05-15T08:14:22",
    "data_validade": "2026-08-14T00:00:00",
    "negativa": true,
    "motivo": null
  }
}

Escopo: certidao_negativa:write

`DELETE /certidao-negativa/{certidao_id}`

Remove fisicamente o registro. Não exposto via MCP (operação destrutiva irreversível) - uso direto da API apenas.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`certidao_id`	`int`	path	sim	ID da certidão

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Certidão deletada com sucesso!",
  "data": true
}

Escopo: certidao_negativa:write

`GET /certidao-negativa/{certidao_id}/pdf`

Retorna application/pdf com header Content-Disposition: inline; filename=certidao_<id>.pdf. Forma recomendada para abrir o PDF no navegador ou anexar em pipelines. Quando a certidão não tem PDF, retorna erro no envelope padrão.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`certidao_id`	`int`	path	sim	ID da certidão

Request

Sem corpo de requisição.

Response 200 OK

Content-Type: application/pdf
Content-Disposition: inline; filename=certidao_9821.pdf
 
<conteúdo binário do PDF>

Escopo: certidao_negativa:read

`POST /certidao-negativa/{certidao_id}/enviar-email/{email}`

Envia o PDF da certidão como anexo via SMTP corporativo da Alcance. Se email for omitido, usa o e-mail cadastrado no cliente (customer.email).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`certidao_id`	`int`	path	sim	ID da certidão
`email`	`str`	path	não	E-mail de destino. Se omitido, usa o do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "mensagem": "Certidão enviada com sucesso por e-mail.",
  "email_destino": "financeiro@empresa.com.br"
}

Escopo: certidao_negativa:write

`POST /certidao-negativa/{certidao_id}/enviar-whatsapp/{numero}`

Envia o PDF via ZapContabil. Se numero for omitido, usa o celular do cliente.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`certidao_id`	`int`	path	sim	ID da certidão
`numero`	`str`	path	não	Número de destino. Se omitido, usa o celular do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "mensagem": "Certidão enviada com sucesso via WhatsApp.",
  "status": 200,
  "whatsapp_response": {
    "id": "msg_9f2c1a",
    "status": "sent"
  }
}

Escopo: certidao_negativa:write

Schemas

`CertidaoNegativaListItem`

Schema enxuto retornado em GET /certidao-negativa/. NÃO inclui pdf_base64 (campo Text enorme - excluído para evitar payloads gigantes).

Campo	Tipo	Descrição
`id`	`int`	Identificador único da certidão.
`id_usuario`	`int`	Usuário Alcance que registrou a emissão.
`id_cliente`	`int`	Cliente vinculado (FK `customers.id`).
`tipo`	`string`	`RECEITA FEDERAL`, `FGTS`, `SEFAZ BAHIA`, `SEFAZ SALVADOR`.
`status`	`string`	`Concluido`, `Falha`, `Em andamento`.
`observacao`	`string?`	Observação livre.
`data_hora_emissao`	`datetime`	Quando o registro foi criado/emitido.
`data_validade`	`datetime?`	Validade da certidão (geralmente 90 ou 180 dias).
`negativa`	`bool?`	`true` = sem pendências; `false` = com pendências.
`motivo`	`string?`	Motivo da pendência / falha, quando aplicável.

Categorias do monitoramento

Valores aceitos pelo query param categoria em /monitoring/list (e chaves retornadas em /monitoring):

Categoria	Significado
`sem_certidao`	Clientes que ainda não possuem certidão emitida no período.
`com_pendencia`	Certidões emitidas com pendências (`negativa = false`).
`exigibilidade_suspensa`	Pendências cuja exigibilidade está suspensa (parcelamento, liminar).
`total_sucesso`	Emissões bem-sucedidas no período.
`total_vencidas`	Certidões cujo `data_validade` já passou.
`total_falhas`	Tentativas de emissão que falharam (timeouts, instabilidade do portal).

Notas

PDF nunca volta na listagem

A listagem GET /certidao-negativa/ não retorna pdf_base64 por padrão - o campo é enorme e estourava payloads em consultas com muitos itens. Para obter o PDF de uma certidão específica, use GET /certidao-negativa/{id} (devolve pdf_base64 no JSON) ou GET /certidao-negativa/{id}/pdf (binário com Content-Disposition). A versão binária é preferida para download e visualização inline no navegador.

Filtros case-insensitive

tipo e status em GET / são case-insensitive - fgts, FGTS e Fgts retornam o mesmo conjunto.