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/` — Registrar emissão

Cria um novo registro de certidão. Aceita pdf_base64 opcional no payload — campo grande, mas necessário se você quiser baixar o PDF depois via /{id}/pdf.

Body (CertidaoNegativaCreate):

{
  "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
}

Resposta 200 OK:

{
  "success": true,
  "message": "Certidão registrada com sucesso!",
  "data": { "id": 9821, "id_cliente": 487, "tipo": "RECEITA FEDERAL", "status": "Concluido" }
}

Escopo: certidao_negativa:write.

GET `/certidao-negativa/stats` — Analytics

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

Escopo: certidao_negativa:read.

GET `/certidao-negativa/monitoring` — Dados de monitoramento

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

Escopo: certidao_negativa:read.

GET `/certidao-negativa/monitoring/list` — Listas por categoria

Retorna listas (não contadores) do monitoramento, segmentadas por categoria.

Query params:

Param	Tipo	Descrição
`tipo`	`string?`	Filtra por tipo (ex.: `SEFAZ BAHIA`, `FGTS`, `RECEITA FEDERAL`).
`categoria`	`string?`	Uma de: `sem_certidao`, `com_pendencia`, `exigibilidade_suspensa`, `total_sucesso`, `total_vencidas`, `total_falhas`.
`limit`	`int?`	1–10000. Se omitido, retorna tudo (cuidado com volume).
`offset`	`int`	Default `0`.

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

Escopo: certidao_negativa:read.

GET `/certidao-negativa/{certidao_id}` — Detalhe por 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).

Resposta 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/` — Listar com filtros

Lista paginada sem pdf_base64 (ver schema CertidaoNegativaListItem abaixo).

Query params:

Param	Tipo	Descrição
`customer_id`	`int?`	Filtra por `id_cliente`.
`tipo`	`string?`	Case-insensitive. Ex.: `FGTS`, `RECEITA FEDERAL`.
`status`	`string?`	Case-insensitive. Ex.: `Concluido`, `Falha`.
`start_date`	`datetime?`	`data_hora_emissao >= start_date`.
`end_date`	`datetime?`	`data_hora_emissao <= end_date`.
`limit`	`int?`	1–500. Se omitido, retorna todos que casarem.
`offset`	`int`	Default `0`.

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

Escopo: certidao_negativa:read.

PUT `/certidao-negativa/{certidao_id}` — Atualizar

Atualiza campos mutáveis de uma certidão. Body (CertidaoNegativaUpdate):

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

Escopo: certidao_negativa:write.

DELETE `/certidao-negativa/{certidao_id}` — Deletar

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

Escopo: certidao_negativa:write.

GET `/certidao-negativa/{certidao_id}/pdf` — Download binário

Retorna application/pdf com header Content-Disposition: inline; filename=certidao_<id>.pdf. Forma recomendada para abrir o PDF no navegador ou anexar em pipelines.

Escopo: certidao_negativa:read.

POST `/certidao-negativa/{certidao_id}/enviar-email/{email}` — Enviar por e-mail

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).

Resposta 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}` — Enviar por WhatsApp

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

Escopo: certidao_negativa:write.

Schema `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.