Contábil: Guias Fiscais

Endpoints da WebApiAlcance para o registro de guias fiscais (guia_fiscal) de um cliente - DAS, DARF, GPS, ISS e outros tipos (campo livre), vinculadas a uma competência, com valor total, componentes discriminados (ex.: principal, multa, juros) e um PDF opcional anexado. As Guias Fiscais alimentam o cruzamento em Regras de Análise (tipos guia_vs_conta, guia_presente e guia_consistencia).

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/guia-fiscal

Escopos necessários

guia_fiscal:read - listagem, detalhe e download do PDF
guia_fiscal:write - criação, anexo do PDF, atualização e exclusão

O escopo é derivado do prefixo público da rota: /guia-fiscal vira o recurso guia_fiscal (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PATCH/DELETE).

Envelope de resposta

Exceto o download do PDF (que devolve bytes), toda resposta segue o envelope padrão da WebApi:

{
  "status": "success",
  "message": "Mensagem em PT-BR",
  "data": {}
}

DELETE /guia-fiscal/{guia_id} responde 204 No Content, sem corpo. Erros de regra de negócio (guia não encontrada, arquivo inválido) respondem { "message": "<mensagem>" } no status HTTP correspondente.

Endpoints

`POST /guia-fiscal/`

Cria o registro de uma guia fiscal, com seus componentes de valor (opcional).

Parâmetros

Sem parâmetros de rota ou query - o corpo é um GuiaFiscalCreate.

Request

{
  "id_cliente": 1234,
  "tipo": "DAS",
  "competencia": "2026-07-01",
  "vencimento": "2026-08-20",
  "descricao": "DAS Simples Nacional - julho/2026",
  "valor_total": 1245.0,
  "observacao": null,
  "componentes": [
    { "nome": "principal", "valor": 1200.0, "ordem": 1 },
    { "nome": "juros", "valor": 45.0, "ordem": 2 }
  ]
}

Response 201 Created

{
  "status": "success",
  "message": "Guia criada com sucesso",
  "data": {
    "id": 3301,
    "id_usuario_created": 7,
    "id_cliente": 1234,
    "tipo": "DAS",
    "competencia": "2026-07-01",
    "vencimento": "2026-08-20",
    "descricao": "DAS Simples Nacional - julho/2026",
    "valor_total": 1245.0,
    "observacao": null,
    "nome_arquivo_original": null,
    "tem_anexo": false,
    "data_hora_criacao": "2026-08-05T09:00:00-03:00",
    "componentes": [
      { "id": 501, "nome": "principal", "valor": 1200.0, "ordem": 1 },
      { "id": 502, "nome": "juros", "valor": 45.0, "ordem": 2 }
    ]
  }
}

Escopo: guia_fiscal:write

`GET /guia-fiscal/`

Lista as guias de um cliente dentro de um período de competência.

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Observações
`id_cliente`	`int`	sim	`> 0`.
`periodo_inicio`	`date`	sim	Início do período de competência (`AAAA-MM-DD`).
`periodo_fim`	`date`	sim	Fim do período de competência (`AAAA-MM-DD`).

periodo_inicio posterior a periodo_fim retorna 422 com { "message": "Inicio nao pode ser posterior ao fim." }.

Request

GET /api/v1/guia-fiscal/?id_cliente=1234&periodo_inicio=2026-01-01&periodo_fim=2026-12-31

Response 200 OK

{
  "status": "success",
  "message": "Guias recuperadas com sucesso",
  "data": [
    {
      "id": 3301,
      "id_usuario_created": 7,
      "id_cliente": 1234,
      "tipo": "DAS",
      "competencia": "2026-07-01",
      "vencimento": "2026-08-20",
      "descricao": "DAS Simples Nacional - julho/2026",
      "valor_total": 1245.0,
      "observacao": null,
      "nome_arquivo_original": "DAS_julho_2026.pdf",
      "tem_anexo": true,
      "data_hora_criacao": "2026-08-05T09:00:00-03:00",
      "componentes": [
        { "id": 501, "nome": "principal", "valor": 1200.0, "ordem": 1 },
        { "id": 502, "nome": "juros", "valor": 45.0, "ordem": 2 }
      ]
    }
  ]
}

Lista vazia retorna 200 OK com data: [] e a mensagem "Nenhuma guia encontrada.".

Escopo: guia_fiscal:read

`POST /guia-fiscal/{guia_id}/arquivo`

Anexa (ou substitui) o PDF da guia. Upload multipart/form-data.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`guia_id`	`int`	rota	sim	ID da guia.
`arquivo`	file	form	sim	O PDF a anexar.

Limites do upload

Extensão precisa ser .pdf e o conteúdo é validado como PDF real (assinatura mínima). Arquivos que excedem o limite de tamanho aceito pelo servidor (10 MB por padrão) são recusados com 413 Request Entity Too Large. A rota também está sujeita a rate limit no bucket upload_guia_fiscal (15 requisições/min por IP).

Request

POST /api/v1/guia-fiscal/3301/arquivo
Content-Type: multipart/form-data; boundary=...
 
arquivo=@DAS_julho_2026.pdf

Response 200 OK

{
  "status": "success",
  "message": "Arquivo anexado",
  "data": {
    "id": 3301,
    "id_usuario_created": 7,
    "id_cliente": 1234,
    "tipo": "DAS",
    "competencia": "2026-07-01",
    "vencimento": "2026-08-20",
    "descricao": "DAS Simples Nacional - julho/2026",
    "valor_total": 1245.0,
    "observacao": null,
    "nome_arquivo_original": "DAS_julho_2026.pdf",
    "tem_anexo": true,
    "data_hora_criacao": "2026-08-05T09:00:00-03:00",
    "componentes": [
      { "id": 501, "nome": "principal", "valor": 1200.0, "ordem": 1 },
      { "id": 502, "nome": "juros", "valor": 45.0, "ordem": 2 }
    ]
  }
}

Extensão diferente de .pdf retorna 422 com { "message": "Extensao invalida: envie um arquivo .pdf." }; conteúdo que não parece um PDF válido retorna 422 com { "message": "Arquivo nao parece ser um PDF valido." }; guia_id inexistente retorna 404. Anexar um novo arquivo substitui o anterior (o antigo é removido do armazenamento).

Escopo: guia_fiscal:write

`GET /guia-fiscal/{guia_id}/arquivo`

Baixa o PDF anexado à guia.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`guia_id`	`int`	rota	sim	ID da guia.

Response 200 OK

Content-Type: application/pdf
Corpo: bytes do PDF, com o nome original do arquivo no cabeçalho de download.

Retorna 404 com { "message": "Arquivo nao encontrado." } quando a guia não existe, quando não há PDF anexado, ou quando o arquivo não é encontrado no armazenamento.

Sem envelope

Diferente das demais rotas deste domínio, esta não responde { status, message, data } - o corpo é o PDF.

Escopo: guia_fiscal:read

`GET /guia-fiscal/{guia_id}`

Busca uma guia pelo ID, com seus componentes.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`guia_id`	`int`	rota	sim	ID da guia.

Response 200 OK

{
  "status": "success",
  "message": "Guia encontrada",
  "data": {
    "id": 3301,
    "id_usuario_created": 7,
    "id_cliente": 1234,
    "tipo": "DAS",
    "competencia": "2026-07-01",
    "vencimento": "2026-08-20",
    "descricao": "DAS Simples Nacional - julho/2026",
    "valor_total": 1245.0,
    "observacao": null,
    "nome_arquivo_original": "DAS_julho_2026.pdf",
    "tem_anexo": true,
    "data_hora_criacao": "2026-08-05T09:00:00-03:00",
    "componentes": [
      { "id": 501, "nome": "principal", "valor": 1200.0, "ordem": 1 },
      { "id": 502, "nome": "juros", "valor": 45.0, "ordem": 2 }
    ]
  }
}

ID inexistente retorna 404 com { "message": "Guia fiscal nao encontrada." }.

Escopo: guia_fiscal:read

`PATCH /guia-fiscal/{guia_id}`

Atualiza campos da guia. id_cliente e tipo são imutáveis - ausentes do schema de atualização.

Parâmetros

guia_id na rota; corpo em GuiaFiscalUpdate.

componentes: null mantém, lista substitui

Quando componentes é omitido (ou null), os componentes atuais são preservados. Quando enviado como lista (mesmo vazia), substitui todos os componentes existentes.

Request

{
  "valor_total": 1300.0,
  "componentes": [
    { "nome": "principal", "valor": 1200.0, "ordem": 1 },
    { "nome": "juros", "valor": 45.0, "ordem": 2 },
    { "nome": "multa", "valor": 55.0, "ordem": 3 }
  ]
}

Response 200 OK

{
  "status": "success",
  "message": "Guia atualizada",
  "data": {
    "id": 3301,
    "id_usuario_created": 7,
    "id_cliente": 1234,
    "tipo": "DAS",
    "competencia": "2026-07-01",
    "vencimento": "2026-08-20",
    "descricao": "DAS Simples Nacional - julho/2026",
    "valor_total": 1300.0,
    "observacao": null,
    "nome_arquivo_original": "DAS_julho_2026.pdf",
    "tem_anexo": true,
    "data_hora_criacao": "2026-08-05T09:00:00-03:00",
    "componentes": [
      { "id": 503, "nome": "principal", "valor": 1200.0, "ordem": 1 },
      { "id": 504, "nome": "juros", "valor": 45.0, "ordem": 2 },
      { "id": 505, "nome": "multa", "valor": 55.0, "ordem": 3 }
    ]
  }
}

ID inexistente retorna 404 com { "message": "Guia fiscal nao encontrada." }.

Escopo: guia_fiscal:write

`DELETE /guia-fiscal/{guia_id}`

Remove a guia. Se houver PDF anexado, ele também é removido do armazenamento.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`guia_id`	`int`	rota	sim	ID da guia.

Response 204 No Content

Sem corpo de resposta. ID inexistente retorna 404 com { "message": "Guia fiscal nao encontrada." }.

Escopo: guia_fiscal:write

Schemas

`GuiaFiscalCreate`

Corpo de POST /guia-fiscal/.

Campo	Tipo	Obrigatório	Observações
`id_cliente`	`int`	sim	`> 0`.
`tipo`	`str` (1-40)	sim	Campo livre - ex.: `DAS`, `DARF`, `GPS`, `ISS`.
`competencia`	`date`	sim	`AAAA-MM-DD`.
`vencimento`	`date`	não	`AAAA-MM-DD`.
`descricao`	`str` (≤ 255)	não	-
`valor_total`	`float`	não	`>= 0`. Default `0`.
`observacao`	`str`	não	-
`componentes`	`List[ComponenteIn]`	não	Default `[]`.

`GuiaFiscalUpdate`

Corpo de PATCH /guia-fiscal/{guia_id}. Todos os campos são opcionais. id_cliente e tipo não fazem parte deste schema.

Campo	Tipo	Observações
`competencia`	`date`	-
`vencimento`	`date`	-
`descricao`	`str` (≤ 255)	-
`valor_total`	`float`	-
`observacao`	`str`	-
`componentes`	`List[ComponenteIn]` \| `null`	`null`/omitido mantém os atuais; lista (mesmo vazia) substitui todos.

`ComponenteIn`

Item de componentes[] em GuiaFiscalCreate/GuiaFiscalUpdate.

Campo	Tipo	Obrigatório	Observações
`nome`	`str` (1-60)	sim	Ex.: `principal`, `multa`, `juros`.
`valor`	`float`	não	`>= 0`. Default `0`.
`ordem`	`int`	não	Ordem de exibição. Default `0`.

`ComponenteRead`

Item de componentes[] em GuiaFiscalRead.

Campo	Tipo	Notas
`id`	`int`	ID interno do componente.
`nome`	`str`	-
`valor`	`float`	-
`ordem`	`int`	-

`GuiaFiscalRead`

data de POST, GET /{guia_id}, GET / (itens da lista), PATCH e POST /{guia_id}/arquivo.

Campo	Tipo	Notas
`id`	`int`	ID da guia.
`id_usuario_created`	`int` \| `null`	Usuário que criou o registro.
`id_cliente`	`int`	-
`tipo`	`str`	-
`competencia`	`date`	-
`vencimento`	`date` \| `null`	-
`descricao`	`str` \| `null`	-
`valor_total`	`float`	-
`observacao`	`str` \| `null`	-
`nome_arquivo_original`	`str` \| `null`	Nome do PDF anexado (quando houver).
`tem_anexo`	`bool`	`true` quando há PDF gravado.
`data_hora_criacao`	`datetime`	Localizado em `America/Sao_Paulo`.
`componentes`	`List[ComponenteRead]`	-

Notas

Ordem de rotas (FastAPI): POST/GET /{guia_id}/arquivo (paths estáticos com sufixo) são declaradas antes de GET /{guia_id} (path dinâmico), para não colidir com a rota de detalhe.
O PDF nunca é incluído nas respostas JSON - só em GET /{guia_id}/arquivo.
GET /guia-fiscal/ sempre exige id_cliente e o período (periodo_inicio/periodo_fim) - não há listagem geral sem cliente.
Excluir a guia remove também o PDF anexado do armazenamento.