FaturaReceber
Serviço REST para gerar e cancelar Faturas a Receber
(tabela SE1, titulo do tipo FT) via rotina
automática FINA280 do Protheus. Não é CRUD.
A semântica é de agrupamento: o servidor consolida vários títulos SE1
de cobrança em um novo título de fatura.
Endpoint OAuth2
Sem credenciais? Rode ./src/scripts/get-token.sh na
biblioteca e cole o access_token aqui.
Vinculação com o ERP
Convenções
Endpoint de processo, não CRUD. O servidor não cria
títulos individuais — ele agrupa títulos SE1 já
existentes em um novo título de fatura
(E1_TIPO=FT). Alteração de fatura passa por
_cancelar + _gerar.
Verbo no path. O endpoint expõe verbos de ação
(/_gerar, /_cancelar) em vez de mapear
para verbo HTTP. Isso reflete a semântica do FINA280,
que não opera sobre uma chave natural pré-existente.
Numero auto. Em POST /_gerar,
numFatura aceita "AUTO" (ou string vazia)
para o servidor gerar via GetSXENum interno do
FINA280.
Padding obrigatório. Chaves
(E1_PREFIXO, E1_TIPO, E1_NUM,
E1_CLIENTE, E1_LOJA) são aplicadas com
PadR(..., TamSX3(...)[1]) antes do MsExecAuto.
Cancelamento por número. O
POST /_cancelar recebe numeroFatura
(E1_NUM da fatura tipo FT); o servidor localiza o RECNO via
DbSeek e dispara FINA280 op=4.
WSDATA data reservado. O endpoint
usa dataref no lugar de data em path/query
(palavra reservada do framework HTTPREST que causa 500 silencioso).
Faturas a Receber
Geração, cancelamento e inspeção das faturas SE1 (E1_TIPO=FT) via FINA280Descrição
Executa FINA280 em operação 3 (geração)
para agrupar títulos SE1 de cobrança em um novo título de fatura
(E1_TIPO=FT). Os títulos originais permanecem em SE1
vinculados ao E1_NUMFAT da nova fatura.
numFatura="AUTO"ou vazio ⇒ servidor gera viaGetSXENum.titulos[]= array de RECNOs (R_E_C_N_O_) dos SE1 a agrupar — todos devem ser do mesmo cliente/loja.- Validações: campos obrigatórios (
cliente,loja,natureza,condicaoPgto) +titulos[]não vazio. - Padding aplicado nas chaves antes do
MsExecAuto.
Cenário
GerarFaturaRequest).
Request body
FAT).FT; marca como fatura)."AUTO" ou vazio ⇒ servidor gera.1 = R$).Exemplo da requisição (cenário ativo)
POST https://erpapi.jetme.com.br/api/99/01/WsFaturaRec/_gerar Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Content-Type: application/json Accept: application/json { "prefixo": "FT9", "tipo": "FT", "numFatura": "AUTO", "natureza": "201", "cliente": "000001", "loja": "01", "condicaoPgto": "001", "moeda": 1, "titulos": [12345] }
POST https://erpapi.jetme.com.br/api/99/01/WsFaturaRec/_gerar Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Content-Type: application/json Accept: application/json { "prefixo": "FT9", "tipo": "FT", "numFatura": "FAT00099", "natureza": "201", "cliente": "000001", "loja": "01", "condicaoPgto": "001", "moeda": 1, "titulos": [12345, 12346, 12347] }
Respostas
data com a chave gravada (prefixo, tipo, numFatura, cliente, loja, totalTitulos).titulos vazio, ou FINA280 rejeitou (cliente/natureza/condição inválidos). Tier: business-error.Descrição
Localiza o título de fatura (SE1 com E1_TIPO=FT
e E1_NUM = numeroFatura) pelo seu RECNO e dispara
FINA280 op=4. Os títulos de cobrança originais
voltam ao estado anterior ao agrupamento (sem
E1_NUMFAT).
Campo motivos: texto livre
apenas para auditoria do chamador — não é gravado em SE1.
Cenário
Request body
FT a cancelar.Exemplo da requisição (cenário ativo)
POST https://erpapi.jetme.com.br/api/99/01/WsFaturaRec/_cancelar Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Content-Type: application/json Accept: application/json { "numeroFatura": "FAT00099", "motivos": "Cliente solicitou novo parcelamento" }
Respostas
numeroFatura, motivos e recno.numeroFatura ausente.numeroFatura+tipo=FT na filial. Tier: not-found.FINA280 op=4 rejeitou o cancelamento (ex: títulos originais já baixados). Tier: business-error.Descrição
Retorna o cabeçalho do título de fatura SE1 identificado por
tipo=recno + valor=<n>. Aceita
também tipo=msuid quando o ambiente expõe o
E1_MSUID (HTTP 501 caso ausente).
Cenário
Query parameters
recno ou msuid.recno, inteiro positivo.Exemplo da requisição (cenário ativo)
GET https://erpapi.jetme.com.br/api/99/01/WsFaturaRec/_byid?tipo=recno&valor=98765 Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Accept: application/json
Respostas
Fatura sob data.tipo fora de recno|msuid.tipo=msuid com ambiente sem E1_MSUID.Descrição
Pagina sobre SE1 filtrando apenas
E1_TIPO=FT. Default orderBy=chave
com page/pageSize; delta-sync
incremental via orderBy=recno +
cursor.
Cenário
Query parameters (todos opcionais)
chave (default) ou recno para delta-sync.orderBy=recno).Exemplo da requisição (cenário ativo)
GET https://erpapi.jetme.com.br/api/99/01/WsFaturaRec/_list?pageSize=10 Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Accept: application/json
Respostas
fields com campo inválido.Schemas
Definições canônicas — campos com origemSX3 rastreável
POST /_gerar. Todos
os RECNOs em titulos precisam apontar para SE1 do
mesmo cliente/loja declarados.
FT marca como fatura."AUTO" ou vazio = servidor gera via GetSXENum.1 = R$.POST /_cancelar.E1_TIPO=FT). Os títulos originais ficam vinculados
via E1_NUMFAT.
FT para fatura).POST /_gerar, data
traz prefixo, tipo, numFatura,
cliente, loja e
totalTitulos. Em POST /_cancelar,
data traz numeroFatura,
motivos e recno.
true em sucesso.false em erros.Cenários
Catálogo de combinações de payload reconhecidas pelos métodos.Quando usar: cliente único, duplicata isolada, ERP do cliente final aceita o número que o Protheus definir.
Resultado: 201 com envelope trazendo a chave da fatura gravada.
FT9FTAUTO — servidor gera.20100000101001[12345] — um RECNO.Quando usar: consolidação mensal de cobrança ao mesmo cliente; número de fatura precisa bater com referência externa (boleto, ERP-cliente).
Pré-condição: todos os RECNOs apontam para SE1 do mesmo
cliente+loja e não estão
ainda agrupados em outra fatura.
FT9FAT00099 — número forçado.[12345, 12346, 12347] — 3 RECNOs.gerar-fatura-minima.numeroFatura. Os títulos originais voltam a aparecer
isolados em SE1 (sem E1_NUMFAT).
Quando usar: correção de fatura gerada por engano, renegociação, mudança de condição de pagamento.
Próximo passo:
POST /_gerar
com a composição correta.
FAT00099Quando usar: follow-up de
POST /_gerar
que devolveu RECNO; inspeção pontual durante debug.
recnoE1_TIPO=FT) na filial
corrente. Default orderBy=chave; use
orderBy=recno+cursor para sync
incremental.
Quando usar: dashboard de faturas abertas; auditoria periódica.
recno + cursor para retomar onde parou.Pendências conhecidas (rev1)
Sem _search nem busca por número.
Para localizar fatura pelo E1_NUM, hoje só via
GET /_list?numero=FAT00099 (filtro exato com scan).
Endpoint dedicado de busca rápida pendente.
Listagem por scan, sem TCGenQry.
GET /_list ainda usa DbSeek+
While sobre SE1 com filtro E1_TIPO=FT. Em
bases com volume alto, considerar migração para
TCGenQry via U_RestSug (conforme padrão
consolidado em CLAUDE.md).
Campos E1_EMISSAO/E1_VENCTO
como string crua. Datas retornadas no GET seguem o
padrão do U_RestMnt (string AAAAMMDD);
ainda não há serialização Date-aware uniforme.