DocumentoEntrada
CRUD de Documento de Entrada (Nota Fiscal de Entrada, tabelas
SF1/SD1) via MsExecAuto da rotina
padrão MATA103. Identificador externo é a chave composta
natural filial-doc-serie-fornece-loja; o campo
F1_TIPO integra o índice físico mas trafega no body/query
(default "N" = Normal). No POST sem
{key}, o servidor gera F1_DOC via
GetSXENum + Soma1.
https://erpapi.jetme.com.br/api/99/01
Empresa 99 · Filial 01
Endpoint OAuth2
Sem credenciais? Você pode pegar o token rodando
./src/scripts/get-token.sh na biblioteca e
colar o access_token aqui no campo de refresh
(ou clique em "Logout" para limpar e voltar ao fake).
Convenções
Identificador externo. A chave composta da
SF1 é filial-doc-serie-fornece-loja (5 partes
separadas por hífen). Exemplo:
01-999998-UNI-000001-01. O campo tipo
(F1_TIPO) integra o índice físico mas vem no body/query —
default "N" (Normal). Para a chave técnica
(recno/msuid), use
/_byid?tipo=recno|msuid&valor=….
POST sem {key} auto-gera F1_DOC.
A rota POST /WsDocumentoEntrada/INCLUIR (sem chave no path)
monta o próximo F1_DOC via GetSXENum +
Soma1 em loop, dentro da chave
(filial/serie/fornece/loja/tipo). Quando o cliente quer impor o número,
use POST /WsDocumentoEntrada/INCLUIR/{key}; se a chave já
existir, a rota retorna 409.
Itens são obrigatórios em POST e PUT.
O body precisa conter o array itens não-vazio. Para cada
item, cod, quant (> 0), vunit
(> 0) e tes são obrigatórios; um é
resolvido a partir de B1_UM da SB1 quando
omitido. local tem default "01".
Sem bloqueio TOTVS na SF1. Diferente dos
cadastros (SA1/SA2/SB1), a
SF1 não expõe o par *_MSBLQL/*_MSBLQD
— não há caminho de "desbloqueio" no PUT. O que existe é
bloqueio de produto (B1_MSBLQL="1"),
checado item a item antes do MATA103; um item com produto
bloqueado provoca 400 antes mesmo de chamar o MsExecAuto.
Formato de data. emissao trafega como
string YYYYMMDD (8 dígitos numéricos, sem hífen). A
conversão interna usa StoD(). Valor que não represente
data válida retorna 400 antes do MsExecAuto.
Paginação e delta-sync. /_list usa
page/pageSize (default 50, máx
500). Para sincronização incremental, alterne para
orderBy=recno e use since/cursor
conforme o nextCursor retornado. Cada chave externa
(filial/doc/serie/fornece/loja) aparece uma vez na
listagem — variações por F1_TIPO são colapsadas.
DocumentoEntrada
CRUD por chave composta filial-doc-serie-fornece-lojaF1_DOC
Descrição
Inclui Documento de Entrada via MATA103 modo 3
(MsExecAuto). O servidor gera F1_DOC usando
GetSXENum("SF1","F1_DOC") e avança com Soma1
até encontrar o próximo slot livre dentro da chave
(filial/serie/fornece/loja/tipo).
Use esta rota quando o cliente não quer impor o
número do documento.
- Body completo em
DocumentoPayload. - Resposta com a chave técnica preenchida em
data.
Request body
itens. Campo doc é
ignorado nesta rota (o servidor sempre auto-gera).
POST https://erpapi.jetme.com.br/api/99/01/WsDocumentoEntrada/INCLUIR Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Content-Type: application/json Accept: application/json { "filial": "01", "serie": "UNI", "fornece": "000001", "loja": "01", "tipo": "N", "formul": "S", "emissao": "20991231", "cond": "001", "especie": "SPED", "status": "A", "itens": [ { "cod": "PA001", "quant": 10, "vunit": 5.50, "local": "01", "tes": "001" }, { "cod": "PA002", "quant": 5, "vunit": 12, "local": "01", "tes": "001" } ] }
Respostas
CrudResponse com data = chave técnica completa (filial/doc/serie/fornece/loja/tipo/linhas + ids técnicos).emissao fora do formato YYYYMMDD, item sem cod/tes, quant/vunit ≤ 0, produto inexistente ou bloqueado. Tier: validation-error.MATA103 rejeitou o payload (TES inválida, fornecedor sem cadastro, condição inexistente etc.). data traz o token do NomeAutoLog. Tier: business-error.Recover Using).doc forçado pelo cliente
Descrição
Inclui Documento de Entrada via MATA103 modo 3,
porém com F1_DOC determinado pelo cliente através do
{key}. Os 5 segmentos da {key} têm
precedência sobre os campos homônimos do body. Se a chave já
existir, o servidor retorna 409 sem tentar o
MsExecAuto.
Path parameter
<filial>-<doc>-<serie>-<fornece>-<loja>. Pattern: ^[^-]+-[^-]+-[^-]+-[^-]+-[^-]+$.Request body
{key} são sobrescritos pelo path.
POST https://erpapi.jetme.com.br/api/99/01/WsDocumentoEntrada/INCLUIR/01-999998-UNI-000001-01 Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Content-Type: application/json Accept: application/json { "tipo": "N", "formul": "S", "emissao": "20991231", "cond": "001", "especie": "SPED", "status": "A", "itens": [ { "cod": "PA001", "quant": 10, "vunit": 5.50, "local": "01", "tes": "001" } ] }
Respostas
CrudResponse.MATA103 rejeitou (TES, fornecedor, condição etc.). Tier: business-error.Descrição
Retorna o cabeçalho (SF1) e o array de linhas
(SD1) do documento identificado pela
{key}. Os campos retornados respeitam o whitelist
CAMPOS_GET (cabeçalho) e CAMPOS_GET_ITEM
(linhas) definidos no .prw.
Path parameter
<filial>-<doc>-<serie>-<fornece>-<loja>.Query parameters
F1_TIPO. Default "N" = Normal.NDBCChamada de exemplo
GET https://erpapi.jetme.com.br/api/99/01/WsDocumentoEntrada/01-999998-UNI-000001-01 Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Accept: application/json
GET https://erpapi.jetme.com.br/api/99/01/WsDocumentoEntrada/01-999998-UNI-000001-01?tipo=D Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Accept: application/json
Respostas
{ success: true, data: DocumentoConsulta } com header (campos F1_*) e linhas[] (campos D1_*).Descrição
Altera o documento via MATA103 modo 4.
O body deve conter cabeçalho completo coerente + array
itens revisado — o MsExecAuto faz o
espelhamento da SD1 a partir do array enviado.
Campos da {key} sobrescrevem os homônimos do body.
Path parameter
<filial>-<doc>-<serie>-<fornece>-<loja>.Request body
itens completo (substitui o
conjunto atual de linhas). Schema completo em
DocumentoPayload.
PUT https://erpapi.jetme.com.br/api/99/01/WsDocumentoEntrada/ALTERAR/01-999998-UNI-000001-01 Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Content-Type: application/json Accept: application/json { "tipo": "N", "formul": "S", "emissao": "20991231", "cond": "001", "especie": "SPED", "status": "A", "itens": [ { "cod": "PA001", "quant": 20, "vunit": 5.50, "local": "01", "tes": "001" } ] }
Respostas
CrudResponse com chave + contagem de linhas.MATA103 rejeitou a alteração (TES, fornecedor, fechamento contábil etc.). Tier: business-error.Descrição
Exclui o documento via MATA103 modo 5.
O servidor lê o cabeçalho da SF1 posicionada (em vez
de exigir body) e percorre a SD1 para montar o
array mínimo de itens passado ao MsExecAuto. O
MATA103 rejeita exclusão quando há dependências
downstream (títulos gerados, movimentação de estoque
contabilizada etc.) — nesses casos o retorno é 422.
Path parameter
Query parameters
F1_TIPO. Default "N".Chamada de exemplo
DELETE https://erpapi.jetme.com.br/api/99/01/WsDocumentoEntrada/EXCLUIR/01-999998-UNI-000001-01 Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Accept: application/json
Respostas
CrudResponse.MATA103 (dependências: títulos a pagar gerados, lançamento contábil, estoque já movimentado etc.). Tier: business-error.Descrição
Busca o documento por id técnico — útil para integrações que
persistem o recno da SF1 ou o
F1_MSUID e querem reconfirmar o registro sem
reconstruir a chave de negócio. Mesmo schema de resposta do
GET /{key}.
Query parameters
recnomsuidtipo=recno, string quando tipo=msuid).Chamada de exemplo
GET https://erpapi.jetme.com.br/api/99/01/WsDocumentoEntrada/_byid?tipo=recno&valor=1234 Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Accept: application/json
GET https://erpapi.jetme.com.br/api/99/01/WsDocumentoEntrada/_byid?tipo=msuid&valor=9f7a3e2c4b8d1a0e Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Accept: application/json
Respostas
{ success: true, data: DocumentoConsulta }.tipo/valor ausente, tipo fora do enum, valor não-positivo para recno. Tier: validation-error.msuid requer F1_MSUID, que não está disponível neste ambiente (campo ausente no dicionário).Listagem
Listagem paginada por filtros, com modo delta-syncDescrição
Lista documentos distintos por chave externa (filial/doc/serie/fornece/loja),
com filtros opcionais. Variações de F1_TIPO sobre a
mesma chave externa são colapsadas em uma linha única. Suporta
dois modos:
orderBy=chave(default) — paginação porpage/pageSize, ordem pelo índice 1 daSF1.orderBy=recno— keyset porRecNo(), ideal para sync incremental; retornanextCursor.
Query parameters
xFilial("SF1") da sessão.AllTrim).SA2).1, mínimo 1). Usado apenas em orderBy=chave.50, máx 500).chave.chaverecnoRecNo() >= since. Combinável com orderBy=chave.orderBy=recno, o servidor faz DbGoTo(cursor) + DbSkip() antes de iniciar a página. Use o nextCursor da página anterior.Chamada de exemplo
GET https://erpapi.jetme.com.br/api/99/01/WsDocumentoEntrada/_list?fornece=000001&loja=01&page=1&pageSize=50 Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Accept: application/json
GET https://erpapi.jetme.com.br/api/99/01/WsDocumentoEntrada/_list?orderBy=recno&cursor=0&pageSize=200 Authorization: Bearer eyJhbGciOiJIUzI1NiIs… Accept: application/json
Respostas
data (array de ListItem), orderBy, pageSize, count; page em orderBy=chave ou nextCursor em orderBy=recno.orderBy inválido, pageSize > 500 etc.). Tier: validation-error.Schemas
Definições canônicas — campos com origemSX3 rastreável
POST e PUT. Cabeçalho da
NF (campos F1_*) + array itens com
ItemDocumento. No
POST /INCLUIR/{key} e PUT /ALTERAR/{key},
os 5 segmentos da {key} sobrescrevem os campos
homônimos do body.
POST /INCLUIR (servidor gera via GetSXENum); obrigatório indiretamente quando {key} está presente.SA2)."N".NDBC"S") ou numeração automática ("N"). Default "S". Quando "N", o servidor omite F1_DOC do array do MATA103 para deixar a numeração nativa atuar.SN^\d{8}$.SE4)."SPED"."A".MATA103 se vier preenchida.ItemDocumento.SD1) da NF. O campo D1_ITEM é
gerado pelo servidor (StrZero(nX, 4)); D1_TOTAL
é calculado como quant * vunit. D1_UM é
resolvida via SB1.B1_UM quando um não
vem no payload.
SB1 e não estar bloqueado (B1_MSBLQL != "1").SB1.B1_UM."01". Precisa existir na SBE.SF4). Determina geração de títulos, movimentação de estoque, impostos etc./{key} e
/_byid. Inclui chave externa, contagem de linhas,
cabeçalho serializado (header: campos F1_*
do whitelist CAMPOS_GET) e array de linhas
(linhas[]: campos D1_* do whitelist
CAMPOS_GET_ITEM), mais ids técnicos.
linhas[].F1_* do whitelist (F1_FILIAL, F1_DOC, F1_SERIE, F1_FORNECE, F1_LOJA, F1_TIPO, F1_FORMUL, F1_EMISSAO, F1_COND, F1_ESPECIE, F1_STATUS, F1_VALMERC, F1_VALBRUT).D1_* do whitelist (D1_ITEM, D1_COD, D1_UM, D1_QUANT, D1_VUNIT, D1_TOTAL, D1_LOCAL, D1_TES).RecNo() da SF1).msuid./_list — uma por chave
externa distinta. Não inclui linhas (SD1) nem o
cabeçalho completo.
DToS().RecNo() da SF1).data traz a chave técnica gerada (filial/doc/serie/fornece/loja/tipo)
com contagem de linhas e ids técnicos; em PUT/DELETE é equivalente
(sem geração de chave, mas com os ids reconfirmados).
true em respostas de sucesso.data pode conter o
token interno da causa (mensagem do NomeAutoLog em
caso de 422) para tratamento programático, quando aplicável.
false em erros.MsExecAuto).