Integra Contador: Simples Nacional

Endpoints da WebApiAlcance para o domínio Simples Nacional (SN) da integração Serpro Integra Contador. Reúnem as operações de PGDAS-D (entrega e geração do DAS, consulta de declarações, recibos e extrato), DEFIS (transmissão e consulta da declaração anual) e Regime de Apuração (opção pelo regime e consultas). Cada requisição é encaminhada de forma síncrona ao Serpro (Integra Contador) e a resposta do Serpro é devolvida no envelope padrão da WebApi.

Todos os endpoints exigem autenticação - veja Autenticação para o fluxo de API Key. Os escopos deste domínio são compartilhados: o recurso deriva do primeiro segmento da rota (integra-contador → integra_contador), portanto uma API Key com integra_contador:read / integra_contador:write habilita simultaneamente Simples Nacional (SN), DCTFWeb, MIT e Radar. Não há escopo específico por sub-domínio. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/integra-contador/sn

Escopos necessários

integra_contador:read - reservado para operações de leitura (GET) do domínio Integra Contador.
integra_contador:write - todos os endpoints SN abaixo, pois são POST.

O escopo é derivado da rota: o primeiro segmento /integra-contador vira o recurso integra_contador (hífen → underscore) e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE). Como todo endpoint SN usa POST, todos exigem integra_contador:write - inclusive as operações nomeadas como "consultar".

Escopo compartilhado entre domínios

O recurso integra_contador é o mesmo para SN, DCTFWeb, MIT e Radar, porque todos compartilham o prefixo /integra-contador. Conceder integra_contador:write a uma API Key libera operações de escrita em todos esses sub-domínios de uma só vez. Leve isso em conta ao emitir chaves com menor privilégio.

Envelope de requisição

Todos os endpoints recebem o mesmo envelope OnlyContribuintePayload: o cliente envia apenas dados (objeto específico da operação) e contribuinte. O contratante e o autor do pedido são fixos no servidor (via .env) e não são enviados pelo cliente.

{
  "dados": { "...": "campos específicos da operação" },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Ver Schema ParteIdentificacao para o objeto contribuinte.

Endpoints

`POST /integra-contador/sn/pgdasd/entregar-declaracao`

Entrega (transmite) a declaração do PGDAS-D ao Serpro. Diferentemente das demais rotas, o campo dados é repassado sem validação de schema - o conteúdo é encaminhado como recebido ao serviço pgdasd_entregar_declaracao.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados (objeto livre da declaração) e contribuinte.

Request

{
  "dados": { "...": "conteúdo da declaração PGDAS-D" },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

`POST /integra-contador/sn/pgdasd/gerar-das`

Gera/emite o DAS do PGDAS-D para um período de apuração. Valida dados contra PGDASDGerarDasDados e retorna 422 com hint e example quando faltam campos obrigatórios.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados do tipo PGDASDGerarDasDados e contribuinte.

Request

{
  "dados": { "periodoApuracao": "202508", "dataConsolidacao": "20/08/2025" },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

`POST /integra-contador/sn/pgdasd/consultar-declaracoes`

Consulta declarações do PGDAS-D. Valida dados contra PGDASDConsultarDeclaracoesDados - é obrigatório informar pelo menos um entre anoCalendario e periodoApuracao.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados do tipo PGDASDConsultarDeclaracoesDados e contribuinte.

Request

{
  "dados": { "anoCalendario": 2018 },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

`POST /integra-contador/sn/pgdasd/consultar-ultima-declaracao-recibo`

Consulta o recibo da última declaração transmitida em um período. Valida dados contra PGDASDUltimaDeclaracaoReciboDados.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados do tipo PGDASDUltimaDeclaracaoReciboDados e contribuinte.

Request

{
  "dados": { "periodoApuracao": "202508" },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

`POST /integra-contador/sn/pgdasd/consultar-declaracao-recibo`

Consulta o recibo de uma declaração específica pelo seu número. Valida dados contra PGDASDConsultarDeclaracaoReciboDados.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados do tipo PGDASDConsultarDeclaracaoReciboDados e contribuinte.

Request

{
  "dados": { "numeroDeclaracao": "2025.08.123456" },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

`POST /integra-contador/sn/pgdasd/consultar-extrato-das`

Consulta o extrato/situação de uma guia DAS. Valida dados contra PGDASDConsultarExtratoDasDados.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados do tipo PGDASDConsultarExtratoDasDados e contribuinte.

Request

{
  "dados": { "numeroDas": "0244552261408202500157900" },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

`POST /integra-contador/sn/pgdasd/gerar-das-avulso`

Gera um DAS avulso (fora do fluxo padrão da declaração). Valida dados contra PGDASDGerarDasAvulsoDados.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados do tipo PGDASDGerarDasAvulsoDados e contribuinte.

Request

{
  "dados": {
    "anoCalendario": 2025,
    "mesApuracao": 8,
    "dataPagamento": "20/08/2025",
    "demais": { "codigoReceita": "1800", "valorPrincipal": 150.23 }
  },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

`POST /integra-contador/sn/defis/transmitir`

Transmite a DEFIS (Declaração de Informações Socioeconômicas e Fiscais) ao Serpro. Valida dados contra DEFISTransmitirDados.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados do tipo DEFISTransmitirDados e contribuinte.

Request

{
  "dados": { "conteudoAssinado": "<base64>", "metadados": {} },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

`POST /integra-contador/sn/defis/consultar-declaracoes`

Consulta as declarações DEFIS de um ano-calendário. Valida dados contra DEFISConsultarDeclaracoesDados.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados do tipo DEFISConsultarDeclaracoesDados e contribuinte.

Request

{
  "dados": { "anoCalendario": 2024 },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

`POST /integra-contador/sn/regime/efetuar-opcao`

Efetua a opção pelo regime de apuração do Simples Nacional. Valida dados contra RegimeEfetuarOpcaoDados.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados do tipo RegimeEfetuarOpcaoDados e contribuinte.

Request

{
  "dados": { "anoCalendario": 2025, "parametros": {} },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

`POST /integra-contador/sn/regime/consultar-anos`

Consulta os anos-calendário disponíveis para opção de regime. Valida dados contra RegimeConsultarAnosDados - todos os campos são opcionais.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados do tipo RegimeConsultarAnosDados e contribuinte.

Request

{
  "dados": { "filtro": {} },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

`POST /integra-contador/sn/regime/consultar-opcao`

Consulta a opção de regime de um ano-calendário. Valida dados contra RegimeConsultarOpcaoDados.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados do tipo RegimeConsultarOpcaoDados e contribuinte.

Request

{
  "dados": { "anoCalendario": 2025 },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

`POST /integra-contador/sn/regime/consultar-resolucao`

Consulta uma resolução do regime de apuração pelo seu número. Valida dados contra RegimeConsultarResolucaoDados.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - o corpo usa o envelope OnlyContribuintePayload, com dados do tipo RegimeConsultarResolucaoDados e contribuinte.

Request

{
  "dados": { "numero": "RESOL-XYZ-2025" },
  "contribuinte": { "tipo": 2, "numero": "00000000000000" }
}

Response 200 OK

{
  "success": true,
  "message": "Operação realizada com sucesso.",
  "data": { "...": "retorno do Serpro (Integra Contador)" }
}

Escopo: integra_contador:write

Schemas

`ParteIdentificacao`

Objeto contribuinte presente em toda requisição.

Campo	Tipo	Obrigatório	Observações
`tipo`	`int`	sim	`1` = Pessoa Física (CPF) · `2` = Pessoa Jurídica (CNPJ).
`numero`	`str`	sim	CPF ou CNPJ, preferencialmente apenas dígitos.

`PGDASDGerarDasDados`

Campo	Tipo	Obrigatório	Observações
`periodoApuracao`	`str`	sim	Formato `AAAAMM` (6 dígitos).
`dataConsolidacao`	`str`	não	`DD/MM/AAAA`, quando aplicável.

`PGDASDConsultarDeclaracoesDados`

Exige pelo menos um entre anoCalendario e periodoApuracao.

Campo	Tipo	Obrigatório	Observações
`anoCalendario`	`int`	condicional	Ano-calendário da consulta.
`periodoApuracao`	`str`	condicional	Período de apuração.

`PGDASDUltimaDeclaracaoReciboDados`

Campo	Tipo	Obrigatório	Observações
`periodoApuracao`	`str`	sim	Período de apuração.

`PGDASDConsultarDeclaracaoReciboDados`

Campo	Tipo	Obrigatório	Observações
`numeroDeclaracao`	`str`	sim	Número da declaração transmitida.

`PGDASDConsultarExtratoDasDados`

Campo	Tipo	Obrigatório	Observações
`numeroDas`	`str`	sim	Identificador da guia DAS para extrato/situação.

`PGDASDGerarDasAvulsoDados`

Campo	Tipo	Obrigatório	Observações
`anoCalendario`	`int`	sim	Ano-calendário.
`mesApuracao`	`int`	sim	Mês de apuração.
`dataPagamento`	`str`	sim	`DD/MM/AAAA`.
`demais`	`dict`	não	Metadados variáveis (ex.: `codigoReceita`, `valorPrincipal`).

`DEFISTransmitirDados`

Campo	Tipo	Obrigatório	Observações
`conteudoAssinado`	`str`	sim	Base64 do conteúdo assinado.
`metadados`	`dict`	não	Metadados opcionais.

`DEFISConsultarDeclaracoesDados`

Campo	Tipo	Obrigatório	Observações
`anoCalendario`	`int`	sim	Ano-calendário.

`RegimeEfetuarOpcaoDados`

Campo	Tipo	Obrigatório	Observações
`anoCalendario`	`int`	sim	Ano-calendário da opção.
`parametros`	`dict`	não	Parâmetros adicionais.

`RegimeConsultarAnosDados`

Campo	Tipo	Obrigatório	Observações
`filtro`	`dict`	não	Filtro opcional da consulta.

`RegimeConsultarOpcaoDados`

Campo	Tipo	Obrigatório	Observações
`anoCalendario`	`int`	sim	Ano-calendário.

`RegimeConsultarResolucaoDados`

Campo	Tipo	Obrigatório	Observações
`numero`	`str`	sim	Número da resolução consultada.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
O envelope de entrada é sempre OnlyContribuintePayload: o cliente envia apenas dados e contribuinte. Os campos contratante e autorPedidoDados da integração Serpro são fixados no servidor via .env e não trafegam na requisição.
Validação de dados: exceto por POST /pgdasd/entregar-declaracao (que repassa dados sem validação), todos os endpoints validam dados contra o schema Pydantic correspondente e retornam 422 Unprocessable Entity com hint (campos obrigatórios ausentes) e example quando o payload está incompleto.
As chamadas são síncronas ao Serpro (Integra Contador) via make_client() - não disparam tasks Celery. A latência depende da resposta do Serpro.
Este router compartilha o mesmo módulo dos routers DCTFWeb e MIT, montados sob /integra-contador/dctf e /integra-contador/mit, respectivamente, e sujeitos ao mesmo escopo integra_contador.