ERP fiscal, contábil e custos

Esta seção reúne o lado fiscal e contábil do ERP do seller: os dados tributários dele, as notas registradas, o plano de contas, o arquivo que vai ao contador e o custo dos produtos para calcular margem. São rotas de cadastro e consulta; a emissão de nota no balcão acontece no PDV.

Como funciona

1. Cadastrar o perfil fiscal
   PUT /fiscal/profile com o regime e os códigos padrão.
2. Montar o plano de contas
   POST /contabil/accounts para ao menos uma conta de receita, ativo e passivo.
3. Exportar ao fim do mês
   POST /contabil/exports e depois GET .../download.
4. Acompanhar margens
   GET /custos para custo e margem de cada produto.

Conceitos importantes

CFOP, NCM e CNAE

Códigos brasileiros usados em nota fiscal: o CFOP classifica a operação (por exemplo, 5102 é venda de mercadoria dentro do estado), o NCM classifica o produto e o CNAE classifica a atividade da empresa. Esta API guarda o texto como você envia.

Regras de imposto

Regras de imposto e configuração tributária do seller têm rotas próprias, fora desta seção.

Autenticação e escopo

Todas as rotas ficam sob /api/v1/vendor/erp e pedem o token de um usuário seller (lojista), enviado em Authorization: Bearer $TOKEN. Um seller é um vendedor que opera dentro do marketplace da loja, com catálogo, pedidos e financeiro próprios. O token de administrador recebe 403 aqui. Veja Tokens.

O seller é descoberto pelo token. Nenhuma rota aceita vendor_id no corpo ou na URL, e um registro de outro seller responde como se não existisse (404). Não há checagem de privilégio por função do ERP: qualquer usuário seller aprovado da loja que tenha um token válido alcança todas as rotas.

Dinheiro, quantidades e datas

Todo valor monetário é um inteiro em centavos (4990 = R$ 49,90) e o nome do campo termina em _cents. Quantidades são inteiros. Datas de vencimento e de período são YYYY-MM-DD; carimbos de data e hora são RFC 3339 em UTC. Veja Ids, dinheiro e datas.

Erros e listas

O corpo de erro é {"error": "texto"}, às vezes com detail. As mensagens de validação do ERP vêm em inglês, muitas com o prefixo vendorerp:, e algumas em português; as tabelas de erros mostram o texto como o servidor devolve. Regra geral: 400 para validação e para transição de estado inválida, 404 quando o registro não existe (a decisão é feita procurando a palavra not found na mensagem), 500 quando um id de filtro ou de caminho não é um UUID válido. Veja Erros.

As listas respondem {"<plural>": [...], "total": N}. Quando a rota é paginada, total é a contagem de todas as páginas; quando não é, é o tamanho do vetor. Apagar é sempre exclusão lógica (soft delete): o registro some das listas, mas não é destruído. Veja Paginação.

Endpoints

Erros comuns

• Esperar uma nota na lista de notas fiscais depois de emitir NFC-e no PDV: a lista é outro registro.
• Usar a exportação contábil como razão completo: ela traz totais de criação de títulos e de vendas do PDV.
• Repetir o code de uma conta contábil (400).
• Ler margin_pct de produto sem custo (has_cost: false): o valor é 100%.
• Gravar custo de um produto que não é do seller (404 product not found).
• Mandar PUT /fiscal/profile parcial: os campos omitidos são apagados.

Próximos passos