VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/ERP Fiscal, contábil e custos

Exportação contábil

Gera, lista e baixa o arquivo de lançamentos do período para o contador.

Listar exportações

Devolve as 200 exportações mais recentes, sem paginação.

GET/api/v1/vendor/erp/contabil/exportsSeller

Lista as exportações contábeis

Exemplo de requisição: Listar exportações

bash
curl "$BASE_URL/api/v1/vendor/erp/contabil/exports" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar exportações

200Exportações
json
{
  "exports": [
    {
      "id": "0a097287-d6f3-4611-a99e-c8540780f66b",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "period_start": "2026-09-01",
      "period_end": "2026-09-30",
      "format": "csv",
      "status": "done",
      "row_count": 3,
      "file_url": "/api/v1/vendor/erp/contabil/exports/0a097287-d6f3-4611-a99e-c8540780f66b/download",
      "created_at": "2026-10-11T14:30:00Z",
      "completed_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

exportsarray

Exportações.

iduuid
Id da exportação.
vendor_iduuid
Seller dono.
period_startstring
Início do período.
period_endstring
Fim do período.
formatstring
csvxml
Formato do arquivo.
statusstring
pendingprocessingdoneerror
Situação. A geração é imediata, então a resposta de criação já vem done.
row_countinteger
Linhas de lançamento no arquivo.
file_urlstring
Caminho relativo para baixar o arquivo (a mesma rota de download), a ser usado com o domínio da loja.
errorstring
Motivo, quando error. Ausente caso contrário.
created_atdatetime
Criação.
completed_atdatetime
Conclusão. Ausente se não concluída.
totalinteger
Quantidade devolvida.

Erros: Listar exportações

StatusQuandoCorpo
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Gerar exportação

Monta o arquivo de lançamentos do período para o contador. A geração é síncrona: a resposta já traz a exportação pronta para baixar. O arquivo é um resumo, não um razão completo: no máximo três linhas por exportação, uma por origem que teve movimento no período (ver o aviso).

POST/api/v1/vendor/erp/contabil/exportsSeller

Gera uma exportação contábil

Corpo da requisição

period_startstringobrigatório
Início YYYY-MM-DD, inclusivo.
period_endstringobrigatório
Fim YYYY-MM-DD, inclusivo. Não pode ser anterior ao início.
formatstringpadrão: csv
csvxml
Formato do arquivo.

Exemplo de requisição: Gerar exportação

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/contabil/exports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "period_start": "2026-09-01",
  "period_end": "2026-09-30",
  "format": "csv"
}'

Resposta: Gerar exportação

201Exportação gerada
json
{
  "id": "0a097287-d6f3-4611-a99e-c8540780f66b",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "period_start": "2026-09-01",
  "period_end": "2026-09-30",
  "format": "csv",
  "status": "done",
  "row_count": 3,
  "file_url": "/api/v1/vendor/erp/contabil/exports/0a097287-d6f3-4611-a99e-c8540780f66b/download",
  "created_at": "2026-10-11T14:30:00Z",
  "completed_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

iduuid
Id da exportação.
vendor_iduuid
Seller dono.
period_startstring
Início do período.
period_endstring
Fim do período.
formatstring
csvxml
Formato do arquivo.
statusstring
pendingprocessingdoneerror
Situação. A geração é imediata, então a resposta de criação já vem done.
row_countinteger
Linhas de lançamento no arquivo.
file_urlstring
Caminho relativo para baixar o arquivo (a mesma rota de download), a ser usado com o domínio da loja.
errorstring
Motivo, quando error. Ausente caso contrário.
created_atdatetime
Criação.
completed_atdatetime
Conclusão. Ausente se não concluída.

Erros: Gerar exportação

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400Datas ausentes ou em outro formato.{"error":"vendorerp: period_start and period_end must be YYYY-MM-DD"}
400Início depois do fim.{"error":"vendorerp: period_start must be <= period_end"}
400Formato inválido.{"error":"vendorerp: format must be csv|xml"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}
O que o arquivo realmente contém

Cada linha é um total do período: receita das vendas do PDV (pela data da venda), total de contas a receber criadas no período e total de contas a pagar criadas no período. Todos os valores são positivos, a data é sempre o fim do período e a conta usada é a primeira conta ativa do tipo revenue, asset ou liability do plano de contas, ou um código padrão (3.1.1, 1.1.2, 2.1.1) se não houver. Um período sem movimento gera um arquivo só com o cabeçalho. Não é uma escrituração por partidas dobradas.

Baixar exportação

Devolve o arquivo (não JSON) como anexo. O nome é contabil_<início>_<fim>.csv ou .xml, com as datas sem hífen.

GET/api/v1/vendor/erp/contabil/exports/{id}/downloadSeller

Baixa o arquivo de uma exportação

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da exportação.

Exemplo de requisição: Baixar exportação

bash
curl -OJ "$BASE_URL/api/v1/vendor/erp/contabil/exports/0a097287-d6f3-4611-a99e-c8540780f66b/download" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Baixar exportação

200Arquivo CSV
csv
data,conta_codigo,conta_nome,tipo,descricao,valor_centavos
2026-09-30,3.1.1,Receita de vendas,revenue,Vendas PDV do período (42 lançamentos),1450000

Erros: Baixar exportação

StatusQuandoCorpo
404A exportação não existe ou é de outro seller.{"error":"export not found"}
500O id não é um UUID válido.{"error":"failed to download export","detail":"..."}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}
Resposta de arquivo

Status 200 com Content-Type: text/csv; charset=utf-8 (ou application/xml; charset=utf-8) e Content-Disposition: attachment. O CSV tem o cabeçalho data,conta_codigo,conta_nome,tipo,descricao,valor_centavos.

Veja também

  • Plano de contas
Anterior
Plano de contas
Próxima
Custos e margem
Nesta página
  • Listar exportações
  • Exemplo de requisição: Listar exportações
  • Resposta: Listar exportações
  • Erros: Listar exportações
  • Gerar exportação
  • Exemplo de requisição: Gerar exportação
  • Resposta: Gerar exportação
  • Erros: Gerar exportação
  • Baixar exportação
  • Exemplo de requisição: Baixar exportação
  • Resposta: Baixar exportação
  • Erros: Baixar exportação
  • Veja também