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

Exportações e downloads

Pede um pacote contábil de um mês, acompanha o processamento, baixa o ZIP e consulta quem baixou.

Um pacote é o arquivo que o contador importa no sistema dele. Há um pacote por tipo e competência: pedir de novo o mesmo par recoloca o trabalho na fila e substitui o arquivo anterior. O arquivo é produzido em segundo plano, então a resposta do pedido é 202 e você consulta a lista até o estado ficar done.

Pedir um pacote

Enfileira a geração. Nada é gerado dentro da requisição.

POST/api/v1/admin/accounting/exportsAdmin

Pede um pacote de exportação

Corpo da requisição

kindstringobrigatório

xml_zipdominiocontmaticcsv

Tipo do pacote.

competencestringobrigatório

Mês: YYYY-MM ou YYYY-MM-DD.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/accounting/exports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "csv",
    "competence": "2026-09"
  }'

Resposta

202Pacote enfileirado

json

{
  "id": "132c3ee6-c9a3-4943-9d94-c06c1758ef3a",
  "kind": "csv",
  "competence": "2026-09",
  "status": "queued",
  "warnings": [],
  "created_at": "2026-10-11T14:05:00Z"
}

Campos da resposta

iduuid

Id do pacote (usado no download).

kindstring

xml_zipdominiocontmaticcsv

Tipo do pacote.

competencestring

Mês contábil, YYYY-MM.

statusstring

queuedrunningdonefailed

Estado do processamento.

warningsarray

Avisos em texto (em português), por exemplo eventos sem de-para.

error_msgstring

Presente só quando status é failed.

created_atstring

Criação ou último novo pedido (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	`kind` inválido, competência fora do formato ou corpo inválido.	`{"error":"export_failed","detail":"invalid export kind \"x\""}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `export_accounting` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"export_accounting"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`

Listar pacotes

Sem filtro, devolve até 100 pacotes, dos meses mais recentes para os mais antigos. Com competence, devolve só os do mês, ordenados por tipo.

GET/api/v1/admin/accounting/exportsAdmin

Lista pacotes de exportação

Parâmetros de consulta

competencestring

YYYY-MM ou YYYY-MM-DD.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/accounting/exports?competence=2026-09" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pacotes

json

{
  "jobs": [
    {
      "id": "132c3ee6-c9a3-4943-9d94-c06c1758ef3a",
      "kind": "csv",
      "competence": "2026-09",
      "status": "done",
      "warnings": [
        "Eventos sem de-para exportados como NAO_MAPEADO.",
        "Financeiro Essencial ausente: recebimento/pagamento/taxa_gateway indisponíveis."
      ],
      "created_at": "2026-10-11T14:05:00Z"
    }
  ]
}

Campos da resposta

jobsarray

Pacotes, sempre um array.

iduuid

Id do pacote (usado no download).

kindstring

xml_zipdominiocontmaticcsv

Tipo do pacote.

competencestring

Mês contábil, YYYY-MM.

statusstring

queuedrunningdonefailed

Estado do processamento.

warningsarray

Avisos em texto (em português), por exemplo eventos sem de-para.

error_msgstring

Presente só quando status é failed.

created_atstring

Criação ou último novo pedido (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	`competence` fora do formato.	`{"error":"list_failed","detail":"invalid competence \"abc\" (want YYYY-MM or YYYY-MM-DD)"}`
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"}`

Baixar o pacote

Entrega o ZIP em application/zip com Content-Disposition: attachment; filename="contabil_<tipo>_<YYYY-MM>.zip". Não existe URL pública: este é o único caminho, e cada download é gravado na trilha de auditoria (usuário, IP e horário).

GET/api/v1/admin/accounting/exports/{id}/downloadAdmin

Baixa o ZIP do pacote

Parâmetros de caminho

iduuidobrigatório

Id do pacote.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/accounting/exports/132c3ee6-c9a3-4943-9d94-c06c1758ef3a/download" \
  -H "Authorization: Bearer $TOKEN" \
  -o contabil_csv_2026-09.zip

Resposta

200Arquivo ZIP

Corpo binário (ZIP). Para dominio, contmatic e csv o ZIP contém o layout e MANIFESTO.txt com contagem e soma em centavos por evento.

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"}`
404	Pacote inexistente ou ainda não pronto (`queued`, `running` ou `failed`). A mensagem diz o estado.	`{"error":"download_failed","detail":"export not ready (status queued)"}`

Consultar a trilha de downloads

Lista quem baixou cada pacote, do mais recente ao mais antigo, até 500 registros.

GET/api/v1/admin/accounting/downloadsAdmin

Trilha de downloads

Parâmetros de consulta

competencestring

Filtra pela competência do pacote baixado.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/accounting/downloads?competence=2026-09" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Downloads

json

{
  "entries": [
    {
      "user_email": "contador@escritorio.example.com",
      "kind": "csv",
      "competence": "2026-09",
      "ip_address": "203.0.113.10",
      "downloaded_at": "2026-10-11T14:20:00Z"
    }
  ]
}

Campos da resposta

entries[].user_emailstring

E-mail de quem baixou (vazio se o usuário foi removido).

entries[].kindstring

Tipo do pacote.

entries[].competencestring

Mês do pacote.

entries[].ip_addressstring

IP de origem.

entries[].downloaded_atstring

Horário (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	`competence` fora do formato.	`{"error":"list_failed","detail":"invalid competence \"abc\" (want YYYY-MM or YYYY-MM-DD)"}`
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"}`

Veja também

Exportação contábil

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

Exportações e downloads

Pede um pacote contábil de um mês, acompanha o processamento, baixa o ZIP e consulta quem baixou.

Pedir um pacote

Enfileira a geração. Nada é gerado dentro da requisição.

POST/api/v1/admin/accounting/exportsAdmin

Pede um pacote de exportação

Corpo da requisição

kindstringobrigatório

xml_zipdominiocontmaticcsv

Tipo do pacote.

competencestringobrigatório

Mês: YYYY-MM ou YYYY-MM-DD.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/accounting/exports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "csv",
    "competence": "2026-09"
  }'

Resposta

202Pacote enfileirado

json

{
  "id": "132c3ee6-c9a3-4943-9d94-c06c1758ef3a",
  "kind": "csv",
  "competence": "2026-09",
  "status": "queued",
  "warnings": [],
  "created_at": "2026-10-11T14:05:00Z"
}

Campos da resposta

iduuid

Id do pacote (usado no download).

kindstring

xml_zipdominiocontmaticcsv

Tipo do pacote.

competencestring

Mês contábil, YYYY-MM.

statusstring

queuedrunningdonefailed

Estado do processamento.

warningsarray

Avisos em texto (em português), por exemplo eventos sem de-para.

error_msgstring

Presente só quando status é failed.

created_atstring

Criação ou último novo pedido (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	`kind` inválido, competência fora do formato ou corpo inválido.	`{"error":"export_failed","detail":"invalid export kind \"x\""}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `export_accounting` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"export_accounting"}`
403	O módulo Exportação Contábil (`accounting-export`) está desligado na loja.	`{"error":"module_disabled","module":"accounting-export"}`

Listar pacotes

Sem filtro, devolve até 100 pacotes, dos meses mais recentes para os mais antigos. Com competence, devolve só os do mês, ordenados por tipo.

GET/api/v1/admin/accounting/exportsAdmin

Lista pacotes de exportação

Parâmetros de consulta

competencestring

YYYY-MM ou YYYY-MM-DD.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/accounting/exports?competence=2026-09" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pacotes

json

{
  "jobs": [
    {
      "id": "132c3ee6-c9a3-4943-9d94-c06c1758ef3a",
      "kind": "csv",
      "competence": "2026-09",
      "status": "done",
      "warnings": [
        "Eventos sem de-para exportados como NAO_MAPEADO.",
        "Financeiro Essencial ausente: recebimento/pagamento/taxa_gateway indisponíveis."
      ],
      "created_at": "2026-10-11T14:05:00Z"
    }
  ]
}

Campos da resposta

jobsarray

Pacotes, sempre um array.

iduuid

Id do pacote (usado no download).

kindstring

xml_zipdominiocontmaticcsv

Tipo do pacote.

competencestring

Mês contábil, YYYY-MM.

statusstring

queuedrunningdonefailed

Estado do processamento.

warningsarray

Avisos em texto (em português), por exemplo eventos sem de-para.

error_msgstring

Presente só quando status é failed.

created_atstring

Criação ou último novo pedido (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	`competence` fora do formato.	`{"error":"list_failed","detail":"invalid competence \"abc\" (want YYYY-MM or YYYY-MM-DD)"}`
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"}`

Baixar o pacote

GET/api/v1/admin/accounting/exports/{id}/downloadAdmin

Baixa o ZIP do pacote

Parâmetros de caminho

iduuidobrigatório

Id do pacote.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/accounting/exports/132c3ee6-c9a3-4943-9d94-c06c1758ef3a/download" \
  -H "Authorization: Bearer $TOKEN" \
  -o contabil_csv_2026-09.zip

Resposta

200Arquivo ZIP

Corpo binário (ZIP). Para dominio, contmatic e csv o ZIP contém o layout e MANIFESTO.txt com contagem e soma em centavos por evento.

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"}`
404	Pacote inexistente ou ainda não pronto (`queued`, `running` ou `failed`). A mensagem diz o estado.	`{"error":"download_failed","detail":"export not ready (status queued)"}`

Consultar a trilha de downloads

Lista quem baixou cada pacote, do mais recente ao mais antigo, até 500 registros.

GET/api/v1/admin/accounting/downloadsAdmin

Trilha de downloads

Parâmetros de consulta

competencestring

Filtra pela competência do pacote baixado.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/accounting/downloads?competence=2026-09" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Downloads

json

{
  "entries": [
    {
      "user_email": "contador@escritorio.example.com",
      "kind": "csv",
      "competence": "2026-09",
      "ip_address": "203.0.113.10",
      "downloaded_at": "2026-10-11T14:20:00Z"
    }
  ]
}

Campos da resposta

entries[].user_emailstring

E-mail de quem baixou (vazio se o usuário foi removido).

entries[].kindstring

Tipo do pacote.

entries[].competencestring

Mês do pacote.

entries[].ip_addressstring

IP de origem.

entries[].downloaded_atstring

Horário (RFC 3339).

Erros

Status	Quando	Corpo de exemplo
400	`competence` fora do formato.	`{"error":"list_failed","detail":"invalid competence \"abc\" (want YYYY-MM or YYYY-MM-DD)"}`
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"}`

Veja também

Exportação contábil