API atual/Referência completa/Exportação contábil

Períodos e fechamento

Lista os últimos 13 meses, fecha um mês passado e reabre um mês fechado com justificativa.

Fechar um mês diz ao sistema que o contador já recebeu os dados e que o mês não deve mais mudar. Um mês fechado bloqueia operações retroativas nos pedidos daquele mês (por exemplo, um reembolso). Só meses já encerrados podem ser fechados, e notas fiscais em processamento ou rejeitadas impedem o fechamento.

Listar períodos

Sempre devolve os 13 meses mais recentes, do mês atual para trás, mesmo que nunca tenham sido tocados (aparecem como open). Para meses abertos, calcula as pendências na hora.

GET/api/v1/admin/accounting/periodsAdmin

Lista os períodos

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/accounting/periods" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Períodos

json

{
  "periods": [
    {
      "competence": "2026-10",
      "status": "open",
      "closed_at": null,
      "closed_by_email": "",
      "pending_issues": []
    },
    {
      "competence": "2026-08",
      "status": "open",
      "closed_at": null,
      "closed_by_email": "",
      "pending_issues": [
        "1 nota(s) em processamento",
        "1 nota(s) rejeitada(s)"
      ]
    },
    {
      "competence": "2026-09",
      "status": "closed",
      "closed_at": "2026-10-11T14:30:00Z",
      "closed_by_email": "contador@escritorio.example.com",
      "pending_issues": []
    }
  ]
}

Campos da resposta

periodsarray

13 itens.

competencestring

Mês, YYYY-MM.

statusstring

openclosed

open ou closed.

closed_atstring|null

Quando foi fechado (RFC 3339). Depois de reabrir, o campo continua com o último fechamento.

closed_by_emailstring

Quem fechou, vazio se nunca fechado.

pending_issuesarray

Textos de pendências que impedem o fechamento (notas em processamento ou rejeitadas). Vazio para meses fechados.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `view_accounting` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"view_accounting"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`

Fechar um mês

Fecha o mês de forma atômica: só uma chamada concorrente vence. Emite o evento accounting.period.closed para integrações.

POST/api/v1/admin/accounting/periods/{competence}/closeAdmin

Fecha um período

Parâmetros de caminho

competencestringobrigatório

YYYY-MM ou YYYY-MM-DD.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/accounting/periods/2026-09/close" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Mês fechado

json

{
  "competence": "2026-09",
  "status": "closed",
  "closed_at": "2026-10-11T14:30:00Z",
  "closed_by_email": "contador@escritorio.example.com",
  "pending_issues": []
}

Campos da resposta

competencestring

Mês, YYYY-MM.

statusstring

openclosed

open ou closed.

closed_atstring|null

Quando foi fechado (RFC 3339). Depois de reabrir, o campo continua com o último fechamento.

closed_by_emailstring

Quem fechou, vazio se nunca fechado.

pending_issuesarray

Textos de pendências que impedem o fechamento (notas em processamento ou rejeitadas). Vazio para meses fechados.

Erros

Status	Quando	Corpo de exemplo
400	Mês corrente ou futuro, ou competência fora do formato.	`{"error":"close_failed","detail":"cannot close the current or a future competence (2026-10): only completed past months can be closed"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `close_accounting_period` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"close_accounting_period"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`
409	Há notas em processamento ou rejeitadas no mês.	`{"error":"pending_issues","issues":["1 nota(s) em processamento"]}`
409	O mês já estava fechado (corrida entre duas chamadas).	`{"error":"already_closed"}`

Reabrir um mês

Volta o mês para open. O motivo é obrigatório e fica registrado junto com quem reabriu e quando.

POST/api/v1/admin/accounting/periods/{competence}/reopenAdmin

Reabre um período

Parâmetros de caminho

competencestringobrigatório

YYYY-MM ou YYYY-MM-DD.

Corpo da requisição

reasonstringobrigatório

Justificativa. Não pode ser vazia.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/accounting/periods/2026-09/reopen" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Nota fiscal complementar emitida depois do fechamento."
  }'

Resposta

200Mês reaberto

json

{
  "competence": "2026-09",
  "status": "open",
  "closed_at": "2026-10-11T14:30:00Z",
  "closed_by_email": "contador@escritorio.example.com",
  "pending_issues": []
}

Campos da resposta

competencestring

Mês, YYYY-MM.

statusstring

openclosed

open ou closed.

closed_atstring|null

Quando foi fechado (RFC 3339). Depois de reabrir, o campo continua com o último fechamento.

closed_by_emailstring

Quem fechou, vazio se nunca fechado.

pending_issuesarray

Textos de pendências que impedem o fechamento (notas em processamento ou rejeitadas). Vazio para meses fechados.

Erros

Status	Quando	Corpo de exemplo
400	Motivo vazio, mês que não está fechado ou competência inválida.	`{"error":"reopen_failed","detail":"reason required"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_accounting` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_accounting"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`

Veja também

Exportação contábil

API atual/Referência completa/Exportação contábil

Períodos e fechamento

Lista os últimos 13 meses, fecha um mês passado e reabre um mês fechado com justificativa.

Listar períodos

Sempre devolve os 13 meses mais recentes, do mês atual para trás, mesmo que nunca tenham sido tocados (aparecem como open). Para meses abertos, calcula as pendências na hora.

GET/api/v1/admin/accounting/periodsAdmin

Lista os períodos

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/accounting/periods" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Períodos

json

{
  "periods": [
    {
      "competence": "2026-10",
      "status": "open",
      "closed_at": null,
      "closed_by_email": "",
      "pending_issues": []
    },
    {
      "competence": "2026-08",
      "status": "open",
      "closed_at": null,
      "closed_by_email": "",
      "pending_issues": [
        "1 nota(s) em processamento",
        "1 nota(s) rejeitada(s)"
      ]
    },
    {
      "competence": "2026-09",
      "status": "closed",
      "closed_at": "2026-10-11T14:30:00Z",
      "closed_by_email": "contador@escritorio.example.com",
      "pending_issues": []
    }
  ]
}

Campos da resposta

periodsarray

13 itens.

competencestring

Mês, YYYY-MM.

statusstring

openclosed

open ou closed.

closed_atstring|null

Quando foi fechado (RFC 3339). Depois de reabrir, o campo continua com o último fechamento.

closed_by_emailstring

Quem fechou, vazio se nunca fechado.

pending_issuesarray

Textos de pendências que impedem o fechamento (notas em processamento ou rejeitadas). Vazio para meses fechados.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `view_accounting` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"view_accounting"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`

Fechar um mês

Fecha o mês de forma atômica: só uma chamada concorrente vence. Emite o evento accounting.period.closed para integrações.

POST/api/v1/admin/accounting/periods/{competence}/closeAdmin

Fecha um período

Parâmetros de caminho

competencestringobrigatório

YYYY-MM ou YYYY-MM-DD.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/accounting/periods/2026-09/close" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Mês fechado

json

{
  "competence": "2026-09",
  "status": "closed",
  "closed_at": "2026-10-11T14:30:00Z",
  "closed_by_email": "contador@escritorio.example.com",
  "pending_issues": []
}

Campos da resposta

competencestring

Mês, YYYY-MM.

statusstring

openclosed

open ou closed.

closed_atstring|null

Quando foi fechado (RFC 3339). Depois de reabrir, o campo continua com o último fechamento.

closed_by_emailstring

Quem fechou, vazio se nunca fechado.

pending_issuesarray

Textos de pendências que impedem o fechamento (notas em processamento ou rejeitadas). Vazio para meses fechados.

Erros

Status	Quando	Corpo de exemplo
400	Mês corrente ou futuro, ou competência fora do formato.	`{"error":"close_failed","detail":"cannot close the current or a future competence (2026-10): only completed past months can be closed"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `close_accounting_period` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"close_accounting_period"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`
409	Há notas em processamento ou rejeitadas no mês.	`{"error":"pending_issues","issues":["1 nota(s) em processamento"]}`
409	O mês já estava fechado (corrida entre duas chamadas).	`{"error":"already_closed"}`

Reabrir um mês

Volta o mês para open. O motivo é obrigatório e fica registrado junto com quem reabriu e quando.

POST/api/v1/admin/accounting/periods/{competence}/reopenAdmin

Reabre um período

Parâmetros de caminho

competencestringobrigatório

YYYY-MM ou YYYY-MM-DD.

Corpo da requisição

reasonstringobrigatório

Justificativa. Não pode ser vazia.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/accounting/periods/2026-09/reopen" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Nota fiscal complementar emitida depois do fechamento."
  }'

Resposta

200Mês reaberto

json

{
  "competence": "2026-09",
  "status": "open",
  "closed_at": "2026-10-11T14:30:00Z",
  "closed_by_email": "contador@escritorio.example.com",
  "pending_issues": []
}

Campos da resposta

competencestring

Mês, YYYY-MM.

statusstring

openclosed

open ou closed.

closed_atstring|null

Quando foi fechado (RFC 3339). Depois de reabrir, o campo continua com o último fechamento.

closed_by_emailstring

Quem fechou, vazio se nunca fechado.

pending_issuesarray

Textos de pendências que impedem o fechamento (notas em processamento ou rejeitadas). Vazio para meses fechados.

Erros

Status	Quando	Corpo de exemplo
400	Motivo vazio, mês que não está fechado ou competência inválida.	`{"error":"reopen_failed","detail":"reason required"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_accounting` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_accounting"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`

Veja também

Exportação contábil