FaturaPagar
Serviço REST para gerar Faturas a Pagar (tabela
SE2, título do tipo FT) via rotina
automática FINA290 do Protheus. Não é CRUD.
Agrupa títulos SE2 de contas a pagar do mesmo fornecedor em um novo
título de fatura. Cancelamento não é suportado — a
documentação oficial da TDN canoniza apenas a inclusão
(nOpc=3).
Endpoint OAuth2
Sem credenciais? Rode ./src/scripts/get-token.sh e
cole o access_token aqui.
Vinculação com o ERP
Convenções
Endpoint de processo, não CRUD. O servidor agrupa
títulos SE2 já existentes em um novo título de fatura
(E2_TIPO=FT). Os títulos originais permanecem em SE2
referenciando a nova fatura via E2_NUMFAT.
Sem cancelamento. A documentação oficial da TDN
do FINA290 canoniza apenas nOpc=3. Não
existe caminho ExecAuto documentado para cancelamento — o endpoint
não expõe _cancelar.
Verbo no path. A composição
POST /WsFaturaPag/_gerar torna explícito que a
operação é de criação de agrupamento.
Particularidade da assinatura FINA290. Diferente
das demais rotinas FINA*, o MsExecAuto da FINA290
recebe nOpc como segundo argumento literal e o array
como terceiro (MsExecAuto({|x,y| FINA290(x,y)}, 3, aFatPag)).
O wrapper U_FN290Exc encapsula essa particularidade.
Ajustes financeiros. Campos
acrescimo e decrescimo ajustam o valor
consolidado da fatura (default 0). Útil para aplicar desconto ou
juros consolidado no agrupamento.
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 Pagar
Geração e inspeção das faturas SE2 (E2_TIPO=FT) via FINA290Descrição
Executa FINA290 em operação 3
(inclusão) para agrupar títulos SE2 de contas a pagar em um
novo título de fatura (E2_TIPO=FT).
numFatura="AUTO"ou vazio ⇒ servidor gera internamente.titulos[]= array de RECNOs SE2 a agrupar — todos devem ser do mesmo fornecedor/loja.- Internamente o endpoint posiciona cada RECNO em SE2 e converte para o vetor de 8 posições da chave que o
FINA290espera. - Validações: campos obrigatórios (
fornecedor,loja,natureza,condicaoPgto) +titulos[]não vazio. - Datas opcionais (
dataDe,dataAte) default =dDataBase.
Cenário
acrescimo
e decrescimo ficam no body opcional).
Request body
FAT).FT)."AUTO" ou vazio ⇒ servidor gera.1).Exemplo da requisição (cenário ativo)
POST https://erpapi.jetme.com.br/api/99/01/WsFaturaPag/_gerar Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Content-Type: application/json Accept: application/json { "prefixo": "FT9", "tipo": "FT", "numFatura": "AUTO", "natureza": "201", "fornecedor": "000002", "loja": "01", "condicaoPgto": "001", "moeda": 1, "titulos": [54321, 54322], "acrescimo": 0, "decrescimo": 0 }
Respostas
data com a chave gravada (prefixo, tipo, numFatura, fornecedor, loja, totalTitulos).titulos vazio, RECNO SE2 inexistente, ou FINA290 rejeitou. Tier: business-error.Descrição
Retorna o cabeçalho do título de fatura SE2 identificado por
tipo=recno + valor=<n>. Aceita
também tipo=msuid quando o ambiente expõe
E2_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/WsFaturaPag/_byid?tipo=recno&valor=98765 Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Accept: application/json
Respostas
FaturaPag sob data.tipo fora de recno|msuid.tipo=msuid com ambiente sem E2_MSUID.Descrição
Pagina sobre SE2 filtrando apenas
E2_TIPO=FT. Default orderBy=chave;
delta-sync via orderBy=recno + cursor.
Cenário
Query parameters (todos opcionais)
chave (default) ou recno.Exemplo da requisição (cenário ativo)
GET https://erpapi.jetme.com.br/api/99/01/WsFaturaPag/_list?pageSize=10 Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Accept: application/json
Respostas
Schemas
Definições canônicas — campos com origemSX3 rastreável
POST /_gerar. RECNOs
em titulos precisam ser do mesmo
fornecedor/loja declarados.
FT marca como fatura."AUTO" ou vazio = servidor gera.dDataBase).dDataBase).E2_TIPO=FT). Os títulos originais ficam vinculados
via E2_NUMFAT.
FT para fatura).POST /_gerar, data
traz prefixo, tipo, numFatura,
fornecedor, loja e
totalTitulos.
true em sucesso.false.Cenários
Catálogo de combinações de payload reconhecidas pelos métodos.Quando usar: consolidação periódica de contas a pagar do mesmo fornecedor (boletos avulsos viram fatura única).
Pré-condição: todos os RECNOs apontam para SE2 do mesmo
fornecedor+loja e não
estão agrupados em outra fatura.
Resultado: 201 com envelope trazendo a chave gravada.
Variantes não-smoke: incluir
acrescimo/decrescimo para aplicar
ajustes; informar numFatura não-AUTO
para forçar número.
FT9AUTO — servidor gera.20100000201001[54321, 54322]Quando usar: follow-up de
POST /_gerar que devolveu RECNO; inspeção pontual
durante debug.
recnoE2_TIPO=FT) na
filial corrente. Default orderBy=chave; use
orderBy=recno+cursor para sync
incremental.
Quando usar: dashboard de faturas em aberto a pagar; relatórios de contas a pagar consolidadas.
recno + cursor para retomar onde parou.Pendências conhecidas (rev1)
Sem cancelamento. TDN não documenta caminho
ExecAuto para cancelamento de fatura a pagar. Correções demandam
intervenção manual no SIGAFIN (FINA290 interativo) ou desfazer
via SQL/script. Endpoint _cancelar não será exposto
até existir suporte oficial.
Listagem por scan. GET /_list usa
DbSeek+While com filtro
E2_TIPO=FT. Bases volumosas podem se beneficiar de
migração para TCGenQry via U_RestSug.
Campos data como string crua. Datas retornadas
no GET seguem o padrão do U_RestMnt (string
AAAAMMDD); serialização Date-aware uniforme pendente.