rev1-2026-05-16

DocFiscalSaida

Inclusão / exclusão de Nota Fiscal de Saída (cabeçalho SF2 + itens SD2) via wrapper MATA920 (MsExecAuto). Métodos expostos: POST, DELETE e GET. F2_DOC é a chave de negócio no path. Não há PUT — alteração de NF emitida é exclusivamente pela rotina MATA920 do ERP.

Bloqueio TOTVS: a SF2/SD2 não tem flag de bloqueio próprio (SF2 não tem C5_MSBLQL). O bloqueio relevante mora em SA1 (cliente, via U_C980Blq) e SB1 (produto). Validação acontece no wrapper U_MT920Exc — tentativa de incluir com cliente ou produto bloqueado retorna 422 com a mensagem do MsExecAuto.

Vinculação com o ERP

Tabela mestre SF2 NF de saída · cabeçalho

Tabela detalhe SD2 Itens da NF de saída

Rotina automática MATA920 MsExecAuto · op 3/5

Wrapper AdvPL U_MT920Exc src/lib/MAT/MT920EXC.prw

Fonte REST WsSF2.prw src/api/DocFiscalSaida/

Chave externa F2_DOC no path · 6 chars

Dependências de ambiente

Cadastro

Cliente (SA1)

validado via DbSeek(xFilial("SA1") + F2_CLIENTE + F2_LOJA) antes do MsExecAuto; cliente inexistente → 422.

Cadastro

Produto (SB1)

cada item valida D2_COD em SB1 antes da composição do aItens do MATA920.

Cadastro

Condição (SE4) e TES (SF4)

validação delegada ao MATA920; mensagem do GetAutoGRLog retorna 422 quando o código não existe.

Out of scope

Rateio AGG e grade SD2

Não suportados nesta revisão. Pedidos com rateio múltiplo ou produtos com grade precisam usar a tela MATA920 do ERP.

Convenções

Envelope canônico. Toda resposta usa { success: bool, message: string, data: object|string }. Erros têm success=false + message com causa; sucessos retornam o F2_DOC em data.F2_DOC.

Chave no path. POST e DELETE usam {chave} como path-param (F2_DOC, até 6 chars, padding via PadR).

Datas em ISO. F2_EMISSAO e C6_ENTREG aceitam tanto AAAAMMDD quanto YYYY-MM-DD — conversão interna usa SToD(StrTran(v,"-","")).

Sem PUT. WsSF2 expõe apenas POST, DELETE e GET. Alteração de NF emitida deve ser feita pela rotina MATA920 do ERP.

Whitelist de campos. Cabeçalho aceita apenas F2_TIPO, F2_CLIENTE, F2_LOJA, F2_COND, F2_EMISSAO, F2_ESPECIE, F2_SERIE, F2_CHVNFE. Itens aceitam D2_COD, D2_QUANT, D2_PRCVEN, D2_TES, D2_LOCAL, D2_PEDIDO, D2_ITEMPC. Campos fora dessa lista são ignorados.

Documento Fiscal de Saída — mutação

Inclusão / exclusão via MATA920 (sem PUT).

POST /WsDocFiscalSaida/INCLUIR/NF000001 Inclui NF de saída — MATA920 op=3

Descrição

Inclui NF de saída em SF2/SD2. {chave} (F2_DOC) deve ser único — duplicidade retorna 409. Cliente em SA1 e produto(s) em SB1 são validados antes da chamada ao MATA920; falhas viram 422 com a mensagem do GetAutoGRLog.

Path parameter

chavestring · max 6 · obrigatório

Valor a ser usado como F2_DOC. Padding com espaço à direita até TamSX3('F2_DOC')[1].

Cenário

Request body

application/json DocFiscalSaidaPayload · obrigatório

Envelope { cabecalho: {...}, itens: [...] }. Schema em DocFiscalSaidaPayload.

cabecalho.F2_CLIENTEstring · obrigatório

Código do cliente em SA1.

cabecalho.F2_LOJAstring · opcional

Loja do cliente. Default "01" quando omitido.

cabecalho.F2_CONDstring · opcional

Condição de pagamento (SE4).

cabecalho.F2_EMISSAOstring (date) · opcional

Data ISO YYYY-MM-DD ou AAAAMMDD.

itens[].D2_CODstring · obrigatório

Produto (SB1).

itens[].D2_QUANTnumber · obrigatório

Quantidade vendida.

itens[].D2_PRCVENnumber · opcional

Preço unitário. Quando omitido, MATA920 busca da tabela de preços.

itens[].D2_TESstring · opcional

TES (SF4). Quando omitido, MATA920 resolve via matriz de TES da venda.

Mínimo viável. Cliente + 1 item; MATA920 resolve condição/TES/preço a partir do cadastro.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsDocFiscalSaida/INCLUIR/NF000001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json

{
  "cabecalho": {
    "F2_CLIENTE": "NF000001"
  },
  "itens": [
    {
      "D2_COD": "P0001",
      "D2_QUANT": 10
    }
  ]
}

Realístico. Cabeçalho completo com condição/data, 2 itens com preço e TES explícitos.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsDocFiscalSaida/INCLUIR/NF000001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json

{
  "cabecalho": {
    "F2_TIPO": "N",
    "F2_CLIENTE": "NF000001",
    "F2_LOJA": "01",
    "F2_COND": "001",
    "F2_EMISSAO": "2026-05-17",
    "F2_SERIE": "API_TESTE"
  },
  "itens": [
    {
      "D2_COD": "P0001",
      "D2_QUANT": 5,
      "D2_PRCVEN": 120.00,
      "D2_TES": "501",
      "D2_LOCAL": "01"
    },
    {
      "D2_COD": "P0002",
      "D2_QUANT": 2,
      "D2_PRCVEN": 350.00,
      "D2_TES": "501"
    }
  ]
}

Respostas

201

NF criada. data.F2_DOC retorna o número informado no path.

400

Número ausente/inválido, payload mal-formado, JSON inválido.

409

NF já cadastrada com esse número.

422

Cliente/produto inexistente, ou erro do MATA920 (TES não encontrado, condição inválida, regra de bloqueio).

401

Token ausente ou expirado.

DELETE /WsDocFiscalSaida/EXCLUIR/NF000001 Exclui NF de saída — MATA920 op=5

Descrição

Exclui a NF de saída. O endpoint reconstrói o array de itens mínimo (D2_ITEM + D2_COD) a partir do SD2 e passa para MATA920 op=5. NFs com liberação ativa ficam barradas pelo MATA920 → 422.

Cenário

Exemplo

Exclusão direta. Sem body — só o número no path.

RequestHTTP/1.1

DELETE https://erpapi.jetme.com.br/api/99/01/WsDocFiscalSaida/EXCLUIR/NF000001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…

Respostas

200

Excluído com sucesso.

404

NF não localizada.

422

NF com liberação ativa ou regra do MATA920.

Consulta

Consulta por número, listagem paginada e typeahead.

GET /WsDocFiscalSaida/NF000001 NF por número (cabeçalho + itens)

Descrição

Devolve cabeçalho e itens da NF em data.{cabecalho,itens}. 404 quando o número não existe.

Cenário

Exemplo

RequestHTTP/1.1

GET https://erpapi.jetme.com.br/api/99/01/WsDocFiscalSaida/NF000001

Response 200application/json

{
  "success": true,
  "data": {
    "cabecalho": {
      "F2_DOC": "NF000001",
      "F2_CLIENTE": "NF000001",
      "F2_LOJA": "01",
      "F2_EMISSAO": "20260517"
    },
    "itens": [
      { "D2_ITEM": "01", "D2_COD": "P0001", "D2_QUANT": 10 }
    ]
  }
}

GET /WsDocFiscalSaida/_list Listagem paginada com filtros

Descrição

Itera SF2 em ordem do índice 1 (C5_FILIAL+F2_DOC) com filtros opcionais num, cliente, loja e emissao. Paginação via page/pageSize.

Query parameters

numstring · opcional

Prefixo de F2_DOC.

clientestring · opcional

Match exato de F2_CLIENTE.

lojastring · opcional

Match exato de F2_LOJA.

emissaostring · opcional

AAAAMMDD — match exato.

pageinteger · default 1

Página solicitada.

pageSizeinteger · default 50, max 500

Tamanho da página.

Cenário

Exemplo

RequestHTTP/1.1

GET https://erpapi.jetme.com.br/api/99/01/WsDocFiscalSaida/_list?cliente=NF000001&page=1&pageSize=25

GET /WsDocFiscalSaida/_search Typeahead por F2_DOC

Descrição

Busca via TCGenQry em SF2 com F2_DOC LIKE <q>% (helper U_RestSug). Mínimo 2 caracteres em q; limite default 10 (max 25).

Query parameters

qstring · min 2 · obrigatório

Prefixo numérico do F2_DOC.

limitinteger · default 10, max 25

Limite de sugestões.

Cenário

Exemplo

RequestHTTP/1.1

GET https://erpapi.jetme.com.br/api/99/01/WsDocFiscalSaida/_search?q=0000&limit=5

Schemas

Componentes do contrato OpenAPI

DocFiscalSaidaPayload

object

Envelope de entrada do POST. Cabeçalho + array de itens.

cabecalhoCabecalho · obrigatório no POST

Ver Cabecalho.

itensarray[Item] · obrigatório no POST

Array de itens. Ver Item.

Cabecalho

object · SF2

Cabeçalho da NF de saída. Whitelist do CAMPOS_CAB_ALLOW em WsSF2.prw.

F2_TIPOstring · opcionalSF2.F2_TIPO

"N"=normal (default).

F2_CLIENTEstring · obrigatório (POST)SF2.F2_CLIENTE

Código do cliente em SA1.

F2_LOJAstring · default 01SF2.F2_LOJA

Loja do cliente.

C5_LOJAENTstring · opcionalSF2.C5_LOJAENT

Loja de entrega.

F2_CONDstring · opcionalSF2.F2_COND

Condição de pagamento (SE4).

C5_VEND1string · opcionalSF2.C5_VEND1

Vendedor (SA3).

C5_TRANSPstring · opcionalSF2.C5_TRANSP

Transportadora (SA4).

C5_TPFRETEstring · opcionalSF2.C5_TPFRETE

Tipo de frete (C/F/T/S/R).

F2_EMISSAOstring (date) · opcionalSF2.F2_EMISSAO

ISO ou AAAAMMDD. Default = data do servidor.

F2_ESPECIEstring · opcionalSF2.F2_ESPECIE

Observação livre.

F2_SERIEstring · opcionalSF2.F2_SERIE

Origem da integração (rastreabilidade).

C5_IDEXTstring · opcionalSF2.C5_IDEXT

ID externo (legado rev0). Não usado como chave em rev1; só rastreamento.

Item

object · SD2

Item da NF de saída. Whitelist do CAMPOS_ITEM_ALLOW.

LINPOSstring · não usado (sem PUT)

Não aplicável — WsSF2 não tem método PUT.

AUTDELETAstring · não usado (sem PUT)

Não aplicável — WsSF2 não tem método PUT.

D2_CODstring · obrigatório (POST)SD2.D2_COD

Produto (SB1, 15 chars).

D2_QUANTnumber · obrigatório (POST)SD2.D2_QUANT

Quantidade vendida.

D2_PRCVENnumber · opcionalSD2.D2_PRCVEN

Preço unitário (MATA920 resolve quando omitido).

C6_PRUNITnumber · opcionalSD2.C6_PRUNIT

Preço unitário sem impostos.

C6_VALORnumber · opcionalSD2.C6_VALOR

Valor total da linha.

D2_TESstring · opcionalSD2.D2_TES

TES (SF4, 3 chars). MATA920 resolve via matriz quando omitido.

D2_LOCALstring · default 01SD2.D2_LOCAL

Armazém.

C6_OPERstring · opcionalSD2.C6_OPER

Operação.

C6_ENTREGstring (date) · opcionalSD2.C6_ENTREG

Data de entrega. ISO ou AAAAMMDD.

EnvelopeSucesso

object · envelope

Envelope canônico de sucesso. Mesmo formato em todos os endpoints da biblioteca.

successboolean

true.

messagestring

Texto descritivo da operação concluída.

dataobject

Payload de retorno (e.g. { F2_DOC: "NF000001" } em POST, ou { cabecalho, itens } em GET).

EnvelopeErro

object · envelope

Envelope canônico de erro. Mesma forma do sucesso, com success=false.

successboolean

false.

messagestring

Causa do erro. Para erros do MATA920, traz o GetAutoGRLog com linhas separadas por /.

datastring

Vazio ("").

Cenários

Combinações testáveis dos endpoints — alinhadas 1-pra-1 com examples: do YAML.

incluir-minimo

POST /WsDocFiscalSaida/INCLUIR/{chave}

Caminho feliz mínimo: cliente + 1 item. MATA920 resolve TES/condição/preço pelo cadastro. (POST NF de saída)

cabecalho.F2_CLIENTE

NF000001

itens[0].D2_COD

P0001

itens[0].D2_QUANT

incluir-completo

POST /WsDocFiscalSaida/INCLUIR/{chave}

Caminho realístico: cabeçalho com condição/data/origem, 2 itens com preço e TES explícitos.

cabecalho

F2_TIPO=N, F2_CLIENTE=NF000001/01, F2_COND=001, F2_EMISSAO=2026-05-17, F2_SERIE=API_TESTE

itens[0]

P0001 · qtd 5 · prc 120 · TES 501 · armazém 01

itens[1]

P0002 · qtd 2 · prc 350 · TES 501

excluir

DELETE /WsDocFiscalSaida/EXCLUIR/{chave}

Exclusão direta sem body. Falha quando há liberação ativa.

path.chave

NF000001 (F2_DOC existente)

consulta-byid

GET /WsDocFiscalSaida/{chave}

Retorna cabeçalho + itens da NF de saída.

path.chave

NF000001

listagem

GET /WsDocFiscalSaida/_list

NFs de saída do cliente NF000001, paginação 25 por página.

cliente

NF000001

page

pageSize

typeahead

GET /WsDocFiscalSaida/_search

Sugestões de F2_DOC começando em "0000", limite 5.

"0000"

limit

Pendências conhecidas (rev2)

Rateio AGG não suportado. Pedidos que precisam de rateio múltiplo por centro de custo precisam usar a tela MATA920 do ERP. Adicionar suporte exige extensão do aCab com array aRateio — não escopado nesta revisão.

Grade SD2 não suportada. Produtos com grade (variação/tamanho) não podem ser incluídos por este endpoint — MATA920 espera estrutura especial em aCab[?][SC9] que não está mapeada.

Smoke test E2E pendente. Validação automática requer fixtures estáveis de SA1, SB1, SE4 e SF4 no ambiente. Hoje a validação roda manual via Postman a partir do openapi.yaml. Ver README.md do endpoint.

Bloqueio TOTVS SF2/SD2 ausente. A tabela SF2 não tem C5_MSBLQL nesta base. O bloqueio efetivo herda de SA1 (cliente) e SB1 (produto) via U_C980Blq no wrapper U_MT920Exc.