Fiscal (Brasil)

O módulo Fiscal trata as obrigações de nota fiscal envolvidas no repasse de comissões a afiliados. Todo afiliado é pessoa jurídica; o módulo cobre a Nota Fiscal (NF) emitida pelo afiliado e a política fiscal configurável por organização. Tudo é Brasil-específico e foi desenhado para que a organização (dona do programa) cumpra suas obrigações sobre os pagamentos. Os valores são sempre inteiros em centavos; alíquotas e percentuais em basis points (bps; 100 bps = 1%). Para entender de onde vem o valor a pagar, veja Payouts e Comissões.

Exigência de nota fiscal

Todo afiliado é pessoa jurídica. A exigência de NF não vem de um regime declarado pelo afiliado: ela é definida pela política fiscal da organização, via o campo nfMode. Quando nfMode é affiliate_uploads, o afiliado envia a NF (upload de PDF/XML) antes da liquidação do payout.

A exigência de NF é uma decisão da organização (política nfMode), não do afiliado. Com nfMode: "affiliate_uploads", todo payout passa pelo gate de NF: a liquidação só acontece depois que a NF é validada.

Política fiscal

Cada organização tem uma política fiscal. O default, quando você ainda não configurou nada, é { nfMode: "affiliate_uploads" }.

string

default:"affiliate_uploads"

Modo de emissão da NF. Apenas affiliate_uploads é aceito: o afiliado (ou você, via API) envia o PDF/XML antes da liquidação. Qualquer outro valor é rejeitado com 400.

Consulte ou atualize com GET /settings/fiscal-policy e PUT /settings/fiscal-policy. Atualizar exige papel owner/admin e registra a mudança no evento settings.updated.

curl https://api.userepass.com/settings/fiscal-policy \
  -H 'Authorization: Bearer rstr_...'

curl -X PUT https://api.userepass.com/settings/fiscal-policy \
  -H 'Authorization: Bearer rstr_...' \
  -H 'Content-Type: application/json' \
  -d '{ "nfMode": "affiliate_uploads" }'

{
  "nfMode": "affiliate_uploads"
}

Nota Fiscal (PJ)

A entidade central é a nota fiscal (invoice, prefixo inv_). Ela não nasce neste módulo: é criada junto com a execução de um Payout, quando a política exige NF (nfMode: "affiliate_uploads"). O módulo Fiscal cobre o restante do ciclo: envio, validação, rejeição, consulta e download.

Ciclo de vida

Estado	Significado
`pending`	Obrigação criada com o payout; NF ainda não enviada.
`validated`	NF enviada e aprovada na validação automática. Libera a liquidação do payout.
`rejected`	NF reprovada (automática por divergência, ou manual pelo operador). Reabre a pendência; permite reenvio.
`canceled`	Payout cancelado; a obrigação morre junto. Terminal.

A liquidação (PIX) de um payout com invoice associada só ocorre depois que ela está validated. Enquanto não estiver, o payout permanece scheduled. Payouts sem invoice (modo diferente de affiliate_uploads) não são segurados por esse gate.

Enviar a NF (submit)

POST /invoices/:invoiceId/submit recebe o arquivo da NF e os metadados declarados. É multipart: uma única parte de arquivo (PDF/XML, no máximo 5 MB) mais os campos de texto.

file

required

O documento. MIME em application/pdf, application/xml ou text/xml. Máximo 5 MB (excedente → 413).

string

required

Número da NF (1 a 60 caracteres).

string

Série da NF (1 a 20 caracteres). Opcional.

string

required

CNPJ do emissor. Aceita formatação (12.345.678/0001-90); normalizado para 14 dígitos. Menos de 14 dígitos → 400.

integer

required

Valor declarado da NF em centavos (inteiro ≥ 1).

string

required

Tomador declarado (1 a 255 caracteres). Deve bater com a razão social da organização.

cURL

curl -X POST https://api.userepass.com/invoices/inv_01J8.../submit \
  -H 'Authorization: Bearer rstr_...' \
  -H 'Idempotency-Key: a1b2c3d4-...' \
  -F '[email protected];type=application/pdf' \
  -F 'nfNumber=12345' \
  -F 'nfSeries=1' \
  -F 'issuerCnpj=12.345.678/0001-90' \
  -F 'declaredAmountCents=150000' \
  -F 'recipientName=Minha Loja LTDA'

O submit é aceito apenas a partir dos estados pending ou rejected (caso contrário, 409). Ele armazena o arquivo com os metadados declarados, roda a validação na hora e emite dois eventos: invoice.submitted e, conforme o resultado, invoice.validated ou invoice.rejected.

O upload é guardado antes da validação. Uma NF reprovada por divergência ainda fica armazenada; o reenvio sobrescreve o arquivo. O Idempotency-Key é suportado em todas as rotas POST. Veja Idempotência.

Validação automática

A validação compara os metadados declarados contra os dados de cadastro. O conteúdo do arquivo não é lido: apenas os campos enviados são confrontados.

Verificação	Falha
CNPJ do emissor = CNPJ do afiliado	`issuer_cnpj_mismatch`
Afiliado tem CNPJ cadastrado	`affiliate_cnpj_missing`
Valor declarado = valor do payout	`amount_mismatch`
Tomador = razão social da organização	`recipient_mismatch`

Nomes são normalizados (trim, lowercase, espaços colapsados) e CNPJs reduzidos a dígitos antes da comparação. Quando há falha, a invoice vai para rejected, os códigos são gravados em validationErrors e o reenvio é permitido.

Revalidar e rejeitar

Revalidar: POST /invoices/:id/validate

Reroda a validação com os metadados já gravados e os dados atuais de afiliado, payout e organização. Útil quando o operador corrige, por exemplo, o CNPJ do afiliado no cadastro depois de uma rejeição automática, sem reenviar o arquivo. Exige envio prévio (issuerCnpj/declaredAmountCents/recipientName preenchidos) e invoice não canceled, senão 409. Emite invoice.validated ou invoice.rejected com revalidated: true. Exige papel owner/admin.

Rejeitar manualmente: POST /invoices/:id/reject

Rejeição manual do operador, com motivo. Aceita origem validated ou rejected; não pode rejeitar pending (nunca enviada) nem canceled (409). Reabre a pendência e emite invoice.rejected com manual: true e o reason. Exige papel owner/admin.

Cobrar novamente: POST /invoices/:id/remind

Lembra o afiliado de enviar a NF pendente (só vale em pending, senão 409). Não muda o estado da nota: dispara a notificação e registra invoice.reminder_sent no event store. Exige papel owner/admin. Para o arquivo de NFs por competência, GET /invoices aceita created_after/created_before.

Consultar e baixar: GET /invoices, GET /invoices/:id, GET /invoices/:id/file

A listagem é paginada por cursor (veja Paginação) e aceita os filtros affiliate_id, payout_id e status. O download (/file) devolve uma URL temporária (válida por 15 minutos) e exige papel owner/admin. Documentos ficam guardados por no mínimo 5 anos.

Fluxo completo: do nascimento à liquidação

Uma NF pending ou rejected de um payout anterior do mesmo afiliado bloqueia um novo run (motivo pending_invoice). Quando a NF é exigida e o afiliado está sem CNPJ cadastrado, o payout também é bloqueado (incomplete_payout_profile), pois o CNPJ é insumo da validação. Veja Payouts.

Retenção de documentos e LGPD

Guarda mínima de 5 anos

Todos os documentos fiscais (NFs, comprovantes, relatórios) ficam disponíveis por no mínimo 5 anos (prazo decadencial tributário). O download é feito via URL temporária, válida por 15 minutos.

LGPD

Dados fiscais e financeiros são retidos pelo prazo legal mesmo após a exclusão de conta solicitada pelo afiliado; os demais dados pessoais são anonimizados na exclusão. A base legal é registrada por categoria de dado.

Eventos de domínio

Toda mudança de estado emite um evento, que você pode assinar via webhook. Os relatórios e consultas (GET) são somente leitura e não emitem eventos. Veja o catálogo de eventos e o Event Store.

Evento	Quando
`invoice.created`	No run de payout, quando a obrigação nasce `pending` (emitido por Payouts).
`invoice.submitted`	No submit, sempre: antes do resultado da validação.
`invoice.validated`	Submit aprovado ou revalidação válida (com `revalidated: true`).
`invoice.rejected`	Submit/revalidação inválida (`validationErrors`) ou rejeição manual (`manual: true`).
`invoice.canceled`	No cancel do payout (emitido por Payouts).
`settings.updated`	No `PUT /settings/fiscal-policy` (`key: "fiscal_policy"`, com `before`/`after`).

Resumo das rotas

Método	Caminho	Papel	Idempotência
POST	`/invoices/:invoiceId/submit`	qualquer membro	sim
GET	`/invoices`	qualquer membro	n/a
GET	`/invoices/:invoiceId`	qualquer membro	n/a
POST	`/invoices/:invoiceId/validate`	owner/admin	sim
POST	`/invoices/:invoiceId/reject`	owner/admin	sim
GET	`/invoices/:invoiceId/file`	owner/admin	n/a
GET	`/settings/fiscal-policy`	qualquer membro	n/a
PUT	`/settings/fiscal-policy`	owner/admin	n/a

Todas as rotas exigem autenticação por sessão ou API key. Para os campos exatos de request e response, veja a aba Referência da API.

Próximos passos

Payouts

Onde a invoice nasce e o gate de liquidação por NF validada.

Comissões

A origem dos valores que viram payout e, depois, NF.

Afiliados

Onde o CNPJ do afiliado é cadastrado.

Idempotência

Como reenviar com segurança o submit e demais POSTs.

Introdução

Convenções da API

Conceitos

Webhooks & Eventos

Guias

Fiscal (Brasil)

Exigência de nota fiscal

Política fiscal

Nota Fiscal (PJ)

Ciclo de vida

Enviar a NF (submit)

Validação automática

Revalidar e rejeitar

Fluxo completo: do nascimento à liquidação

Retenção de documentos e LGPD

Eventos de domínio

Resumo das rotas

Próximos passos

Payouts

Comissões

Afiliados

Idempotência

​Exigência de nota fiscal

​Política fiscal

​Nota Fiscal (PJ)

​Ciclo de vida

​Enviar a NF (submit)

​Validação automática

​Revalidar e rejeitar

​Fluxo completo: do nascimento à liquidação

​Retenção de documentos e LGPD

​Eventos de domínio

​Resumo das rotas

​Próximos passos

Payouts

Comissões

Afiliados

Idempotência

Exigência de nota fiscal

Política fiscal

Nota Fiscal (PJ)

Ciclo de vida

Enviar a NF (submit)

Validação automática

Revalidar e rejeitar

Fluxo completo: do nascimento à liquidação

Retenção de documentos e LGPD

Eventos de domínio

Resumo das rotas

Próximos passos