Declaração Simples Nacional

Endpoints da WebApiAlcance para gerenciar os registros de Declaração do Simples Nacional - as apurações mensais (PGDAS-D) e seus respectivos DAS (Documento de Arrecadação do Simples Nacional) por cliente e período. Cobrem o registro de novas declarações, listagem geral, consulta por ID ou pelo número da declaração, atualização, exclusão, um resumo consolidado (geral e por cliente) e a baixa de pagamento do DAS.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/declaracao-sn

Escopos necessários

declaracao_sn:read - listagem, consulta por ID, consulta por número da declaração e resumo consolidado
declaracao_sn:write - registro, atualização, exclusão e baixa de pagamento

O escopo é derivado da rota: o prefixo /declaracao-sn vira o recurso declaracao_sn (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

`POST /declaracao-sn/`

Registra um novo registro de declaração do Simples Nacional (apuração PGDAS-D e o respectivo DAS) vinculado a um cliente e período. Todos os campos são opcionais, permitindo registro incremental (ex.: criar a apuração antes de o DAS ser emitido).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (DeclaracaoSNCreate).

Request

{
  "id_usuario": 12,
  "id_cliente": 487,
  "mes": 5,
  "ano": 2026,
  "periodo_apuracao": 202605,
  "numero_declaracao": "07052026000123456",
  "numero_das": "00007052026000098765",
  "data_hora_emissao_das": "2026-06-10T08:14:22",
  "das_pago": false,
  "tipo_operacao": "APURACAO",
  "status_processo": "EMITIDO",
  "saldo": 1543.87
}

Response 201 Created

{
  "success": true,
  "message": "Registro de declaração SN criado com sucesso",
  "data": {
    "id": 3120,
    "id_usuario": 12,
    "id_cliente": 487,
    "data_insercao": "2026-06-10T08:14:22",
    "data_atualizacao": null,
    "mes": 5,
    "ano": 2026,
    "periodo_apuracao": 202605,
    "numero_declaracao": "07052026000123456",
    "numero_das": "00007052026000098765",
    "data_hora_emissao_das": "2026-06-10T08:14:22",
    "data_pagamento": null,
    "das_pago": false,
    "tipo_operacao": "APURACAO",
    "status_processo": "EMITIDO",
    "saldo": 1543.87
  }
}

Escopo: declaracao_sn:write

`GET /declaracao-sn/`

Lista todos os registros de declaração do Simples Nacional. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhum registro encontrado.".

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": "Registros recuperados com sucesso",
  "data": [
    {
      "id": 3120,
      "id_usuario": 12,
      "id_cliente": 487,
      "data_insercao": "2026-06-10T08:14:22",
      "data_atualizacao": null,
      "mes": 5,
      "ano": 2026,
      "periodo_apuracao": 202605,
      "numero_declaracao": "07052026000123456",
      "numero_das": "00007052026000098765",
      "data_hora_emissao_das": "2026-06-10T08:14:22",
      "data_pagamento": null,
      "das_pago": false,
      "tipo_operacao": "APURACAO",
      "status_processo": "EMITIDO",
      "saldo": 1543.87
    }
  ]
}

Escopo: declaracao_sn:read

`GET /declaracao-sn/{id}`

Detalha um registro pelo ID inteiro. Quando não encontrado, retorna o envelope de erro com message: "Registro não encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id`	`int`	path	sim	ID interno do registro de declaração

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro encontrado com sucesso",
  "data": {
    "id": 3120,
    "id_usuario": 12,
    "id_cliente": 487,
    "data_insercao": "2026-06-10T08:14:22",
    "data_atualizacao": null,
    "mes": 5,
    "ano": 2026,
    "periodo_apuracao": 202605,
    "numero_declaracao": "07052026000123456",
    "numero_das": "00007052026000098765",
    "data_hora_emissao_das": "2026-06-10T08:14:22",
    "data_pagamento": null,
    "das_pago": false,
    "tipo_operacao": "APURACAO",
    "status_processo": "EMITIDO",
    "saldo": 1543.87
  }
}

Escopo: declaracao_sn:read

`GET /declaracao-sn/declaracao/{numero_declaracao}`

Detalha um registro pelo número da declaração (string) gerado no PGDAS-D. Quando não encontrado, retorna o envelope de erro com message: "Registro não encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`numero_declaracao`	`str`	path	sim	Número da declaração gerado no PGDAS-D

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro encontrado com sucesso",
  "data": {
    "id": 3120,
    "id_usuario": 12,
    "id_cliente": 487,
    "data_insercao": "2026-06-10T08:14:22",
    "data_atualizacao": null,
    "mes": 5,
    "ano": 2026,
    "periodo_apuracao": 202605,
    "numero_declaracao": "07052026000123456",
    "numero_das": "00007052026000098765",
    "data_hora_emissao_das": "2026-06-10T08:14:22",
    "data_pagamento": null,
    "das_pago": false,
    "tipo_operacao": "APURACAO",
    "status_processo": "EMITIDO",
    "saldo": 1543.87
  }
}

Escopo: declaracao_sn:read

`PUT /declaracao-sn/{id}`

Atualiza um registro existente. O body é um DeclaracaoSNUpdate com campos parciais - somente o que vier preenchido é alterado. Quando não encontrado, retorna o envelope de erro com message: "Registro não encontrado para atualização.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id`	`int`	path	sim	ID do registro

Request (DeclaracaoSNUpdate - todos os campos opcionais)

{
  "numero_declaracao": "07052026000123456",
  "saldo": 1620.45
}

Response 200 OK

{
  "success": true,
  "message": "Registro atualizado com sucesso",
  "data": {
    "id": 3120,
    "id_usuario": 12,
    "id_cliente": 487,
    "data_insercao": "2026-06-10T08:14:22",
    "data_atualizacao": "2026-07-03T10:22:00",
    "mes": 5,
    "ano": 2026,
    "periodo_apuracao": 202605,
    "numero_declaracao": "07052026000123456",
    "numero_das": "00007052026000098765",
    "data_hora_emissao_das": "2026-06-10T08:14:22",
    "data_pagamento": null,
    "das_pago": false,
    "tipo_operacao": "APURACAO",
    "status_processo": "EMITIDO",
    "saldo": 1620.45
  }
}

Escopo: declaracao_sn:write

`DELETE /declaracao-sn/{id}`

Remove um registro de declaração do Simples Nacional pelo ID. Quando não encontrado, retorna o envelope de erro com message: "Registro não encontrado para exclusão.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id`	`int`	path	sim	ID do registro

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro excluído com sucesso",
  "data": null
}

Escopo: declaracao_sn:write

`GET /declaracao-sn/resume/all`

Obtém um resumo consolidado das declarações do Simples Nacional - visão geral, segmentação por cliente, detalhamento de inadimplência por faixa de atraso e dados para gráficos. Útil para dashboards e acompanhamento de inadimplência do DAS.

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": "Resumo obtido com sucesso",
  "data": {
    "resumo_geral": {
      "pagos": 128,
      "pendentes": 14,
      "exibilidade_suspensa": 6,
      "total": 148,
      "taxa_adimplencia": "89.51%",
      "clientes_adimplentes": 77,
      "clientes_inadimplentes": 9,
      "clientes_exibilidade_suspensa": 4,
      "atraso_medio_dias": 12.75
    },
    "por_cliente": [
      {
        "id_cliente": 487,
        "cliente": "Comércio Exemplo LTDA",
        "cpfecnpj": "12.345.678/0001-90",
        "total_declaracoes": 6,
        "pagos": 5,
        "pendentes": 1,
        "competencias_pagas": ["01/2026", "02/2026", "03/2026", "04/2026", "05/2026"],
        "declaracoes_pendentes": [{ "id": 3121, "competencia": "06/2026" }],
        "competencias_exibilidade_suspensa": []
      }
    ],
    "detalhamento_inadimplencia": {
      "ate_30_dias": 8,
      "30_60_dias": 4,
      "acima_60_dias": 2,
      "por_cliente": {
        "Comércio Exemplo LTDA": {
          "total_pendentes": 1,
          "risco_baixo": 1,
          "risco_medio": 0,
          "risco_alto": 0
        }
      }
    },
    "graficos": {
      "evolucaoAdimplencia": {
        "2026": [
          { "mes": "Janeiro", "taxa": 92.5 },
          { "mes": "Fevereiro", "taxa": 90.0 }
        ]
      },
      "distribucaoPorStatus": [
        { "status": "PAGO", "quantidade": 128 },
        { "status": "EMITIDO", "quantidade": 14 }
      ],
      "valoresPorCategoria": [{ "categoria": "APURACAO", "quantidade": 148 }]
    }
  }
}

Escopo: declaracao_sn:read

`PUT /declaracao-sn/paid/{id}`

Dá baixa de pagamento em uma declaração do Simples Nacional, marcando o DAS como pago. O body é um DeclaracaoSNPaid com todos os campos opcionais - tipicamente das_pago: true, data_atualizacao, status_processo e uma observacao.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id`	`int`	path	sim	ID do registro

Request

{
  "das_pago": true,
  "data_atualizacao": "2026-07-03T10:22:00",
  "status_processo": "PAGO",
  "observacao": "Baixa manual após conciliação bancária"
}

Response 200 OK

{
  "success": true,
  "message": "Registro de pagamento de declaração SN atualizado com sucesso",
  "data": {
    "das_pago": true,
    "data_atualizacao": "2026-07-03T10:22:00",
    "status_processo": "PAGO",
    "observacao": "Baixa manual após conciliação bancária"
  }
}

Escopo: declaracao_sn:write

Schemas

`DeclaracaoSNCreate`

Estende o DeclaracaoSNBase. Todos os campos são opcionais no registro.

Campo	Tipo	Obrigatório	Observações
`id`	`int?`	não	Normalmente omitido no registro (gerado pelo banco).
`id_usuario`	`int?`	não	Usuário Alcance que registrou a declaração.
`id_cliente`	`int?`	não	Cliente vinculado (FK `customers.id`).
`data_insercao`	`datetime?`	não	Data/hora de inserção do registro.
`data_atualizacao`	`datetime?`	não	Data/hora da última atualização.
`mes`	`int?`	não	Mês de competência da apuração.
`ano`	`int?`	não	Ano de competência da apuração.
`periodo_apuracao`	`int?`	não	Período de apuração (ex.: `202605`).
`numero_declaracao`	`str?`	não	Número da declaração gerado no PGDAS-D.
`numero_das`	`str?`	não	Número do DAS emitido.
`data_hora_emissao_das`	`datetime?`	não	Data/hora de emissão do DAS.
`data_pagamento`	`datetime?`	não	Data em que o DAS foi pago.
`das_pago`	`bool?`	não	Indica se o DAS já foi pago.
`tipo_operacao`	`str?`	não	Tipo de operação da declaração.
`status_processo`	`str?`	não	Situação do processamento da declaração.
`saldo`	`float?`	não	Valor apurado / saldo do DAS.

`DeclaracaoSNUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados.

Campo	Tipo	Observações
`numero_declaracao`	`str?`	Novo número da declaração.
`saldo`	`float?`	Novo valor apurado / saldo do DAS.

`DeclaracaoSNOut`

Estende o DeclaracaoSNBase, com id sempre presente. Retornado no registro, na listagem e nas consultas por ID / número.

Campo	Tipo	Notas
`id`	`int`	Identificador do registro.
`id_usuario`	`int?`	Usuário Alcance que registrou a declaração.
`id_cliente`	`int?`	Cliente vinculado (FK `customers.id`).
`data_insercao`	`datetime?`	Data/hora de inserção do registro.
`data_atualizacao`	`datetime?`	Data/hora da última atualização.
`mes`	`int?`	Mês de competência.
`ano`	`int?`	Ano de competência.
`periodo_apuracao`	`int?`	Período de apuração (ex.: `202605`).
`numero_declaracao`	`str?`	Número da declaração (PGDAS-D).
`numero_das`	`str?`	Número do DAS emitido.
`data_hora_emissao_das`	`datetime?`	Data/hora de emissão do DAS.
`data_pagamento`	`datetime?`	Data em que o DAS foi pago.
`das_pago`	`bool?`	Indica se o DAS já foi pago.
`tipo_operacao`	`str?`	Tipo de operação da declaração.
`status_processo`	`str?`	Situação do processamento.
`saldo`	`float?`	Valor apurado / saldo do DAS.

`DeclaracaoSNPaid`

Payload da baixa de pagamento (PUT /declaracao-sn/paid/{id}). Todos os campos são opcionais.

Campo	Tipo	Observações
`das_pago`	`bool?`	Marca o DAS como pago (`true`).
`data_atualizacao`	`datetime?`	Data/hora da baixa de pagamento.
`status_processo`	`str?`	Nova situação do processo (ex.: `PAGO`).
`observacao`	`str?`	Observação livre sobre a baixa.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
A consulta por ID (GET /declaracao-sn/{id}) usa id inteiro, enquanto a consulta por número (GET /declaracao-sn/declaracao/{numero_declaracao}) usa a string do número da declaração - os dois caminhos não conflitam por terem segmentos distintos.
GET /declaracao-sn/resume/all e PUT /declaracao-sn/paid/{id} usam sub-caminhos estáticos (resume, paid), então não são interpretados como um id.
Relaciona-se com Customers, que fornece os dados dos clientes referenciados por id_cliente.