API idworks (sa-east-1)

Documentação dos endpoints da API idworks. Cobre Contas a Pagar, Contas a Receber (incluindo conciliação de adquirentes e marketplace), Contas Bancárias, Extrato Bancário, Marcas e Fornecedores.

Gerado em 2026-05-26 · 27 endpoints.

Convenções

• Autenticação: header Authorization com JWT (com ou sem prefixo Bearer). Validado pelo autorizador da API.
• Mensagens de erro vêm prefixadas, e cada prefixo corresponde a um status HTTP:
  • [BadRequest] ... → 400
  • Error: ... → 500
  • resposta sem prefixo → 200
• Formato de erro: { "errorMessage": "<prefixo> ...mensagem..." }.

Os endpoints documentados nesta página retornam apenas 200, 400 e 500.

Índice de endpoints

Contas Bancárias

Método	Rota	Função	Descrição
GET	/accounts/bank-account	bankAccountList	Lista contas bancárias da empresa, com saldo atual e previsto.
POST	/accounts/bank-account	bankAccountPost	Cadastra uma conta bancária.
PUT	/accounts/bank-account/{idbankaccount}	bankAccountPut	Atualiza uma conta bancária ou aplica ajuste de saldo inicial.
DELETE	/accounts/bank-account/{idbankaccount}	bankAccountDelete	Inativa uma conta bancária.

Conciliação Bancária

Método	Rota	Função	Descrição
GET	/accounts/bank-statement	bankStatementList	Extrato bancário (interno ou bancário) com saldos e conciliação.
POST	/accounts/bank-statement	bankStatementPost	Vincula títulos ou transferências a um lançamento bancário/de adquirente.
POST	/accounts/bank-statement/transfer	bankStatementTransferPost	Cria uma transferência entre contas bancárias (gera débito + crédito).
DELETE	/accounts/bank-statement/transfer/{idbankstatement}	bankStatementTransferDelete	Exclui uma transferência (remove as duas pontas).

Regras de Conciliação Bancária

Método	Rota	Função	Descrição
GET	/accounts/bank-statement/conciliation-rule	bankStatementConciliationRuleList	Lista regras de conciliação automática.
POST	/accounts/bank-statement/conciliation-rule	bankStatementConciliationRulePost	Cadastra uma regra de conciliação automática.
PUT	/accounts/bank-statement/conciliation-rule/{idbankstatementconciliationrule}	bankStatementConciliationRulePut	Atualiza uma regra de conciliação automática.
DELETE	/accounts/bank-statement/conciliation-rule/{idbankstatementconciliationrule}	bankStatementConciliationRuleDelete	Exclui uma regra de conciliação automática.

Fluxo de Caixa

Método	Rota	Função	Descrição
GET	/accounts/cash-flow	cashFlowList	Fluxo de caixa consolidado por plano de contas (resumo) ou detalhamento de uma célula.

Plano de Contas

Método	Rota	Função	Descrição
GET	/type/account/type	typeAccountTypeList	Lista o plano de contas (em árvore ou lista plana).
POST	/type/account/type	typeAccountTypePost	Cadastra um plano de contas (raiz ou filho de outro).
PUT	/type/account/type/{idtypeaccount}	typeAccountTypePut	Atualiza um plano de contas.
DELETE	/type/account/type/{idtypeaccount}	typeAccountTypeDelete	Inativa um plano de contas (com regras de bloqueio).
GET	/type/account/type/category	typeAccountCategoryList	Lista o catálogo fixo de categorias do plano de contas.

Tipo Documento

Método	Rota	Função	Descrição
GET	/type/account/document	typeAccountDocumentList	Lista tipos de documento ativos da empresa, com flags de padrão para pedidos e compras.
POST	/type/account/document	typeAccountDocumentPost	Cadastra um tipo de documento.
PUT	/type/account/document/{idtypedocument}	typeAccountDocumentPut	Atualiza descrição e flags de padrão de um tipo.
DELETE	/type/account/document/{idtypedocument}	typeAccountDocumentDelete	Inativa um tipo (bloqueia quando está em uma parametrização GNRE).

Tipo Pedido

Método	Rota	Função	Descrição
GET	/type/order/type	typeOrderTypeList	Lista tipos de pedido ativos da empresa, com descrições resolvidas.
POST	/type/order/type	orderTypeOrderPost	Cadastra um tipo de pedido.
GET	/type/order/type/{idordertype}	orderTypeOrderGet	Detalha um tipo de pedido, com regras fiscais por departamento.
PUT	/type/order/type/{idordertype}	orderTypeOrderPut	Atualiza um tipo de pedido.
DELETE	/type/order/type/{idordertype}	orderTypeOrderDelete	Inativa um tipo (com regras de bloqueio).

DE-PARA CFOP recebimento

Método	Rota	Função	Descrição
GET	/purchase/cfop-inbound	purchaseCfopInboundList	Lista regras de reescrita de CFOP no recebimento.
POST	/purchase/cfop-inbound	purchaseCfopInboundPost	Cadastra uma regra (par CfopFrom → CfopTo).
PUT	/purchase/cfop-inbound/{idstockkeepingunitpurchasecfopinbound}	purchaseCfopInboundPut	Atualiza uma regra existente.
DELETE	/purchase/cfop-inbound/{idstockkeepingunitpurchasecfopinbound}	purchaseCfopInboundDelete	Exclui (fisicamente) uma regra.

Webhook

Método	Rota	Função	Descrição
GET	/webhook	webhookList	Lista o histórico de envios de webhook (logs), com filtros por tópico, status e data.

Perfil de Acesso

Método	Rota	Função	Descrição
GET	/user/privilege-group	userPrivilegeGroupList	Lista perfis de acesso ativos da empresa.
POST	/user/privilege-group	userPrivilegeGroupPost	Cria um perfil vazio (só com nome).
GET	/user/privilege-group/{idprivilegegroup}	userPrivilegeGroupGet	Detalha um perfil com os privilégios atribuídos, agrupados por área e módulo.
PUT	/user/privilege-group/{idprivilegegroup}	userPrivilegeGroupPut	Renomeia um perfil.
DELETE	/user/privilege-group/{idprivilegegroup}	userPrivilegeGroupDelete	Inativa um perfil (bloqueado quando vinculado a usuários).
POST	/user/privilege-group/{idprivilegegroup}/resource	userPrivilegeGroupResourcePost	Substitui a lista de privilégios atribuídos ao perfil (sobrescreve).

Ações em Massa

Método	Rota	Função	Descrição
GET	/job	jobsResultList	Lista jobs disparados pela empresa, do mais recente para o mais antigo.
POST	/job	jobsResultPost (via asyncLambdaGateway)	Dispara um job (upload de planilha + processamento assíncrono).
GET	/job/{idjob}	jobsResultGet	Detalha um job com resultados linha-a-linha e URL pré-assinada do arquivo.

Integrações

Método	Rota	Função	Descrição
GET	/company/integration	companyParameterList	Lista integrações configuradas pela empresa, com tipo, status e reputação.
POST	/company/integration	companyParameterPost	Cria uma integração vazia a partir de um IDTypeCompanyIntegration.
GET	/company/integration/{idcompanyintegration}	companyParameterGet	Detalha as parametrizações da integração (chave/valor + grupo + tipo + lista de opções).
PUT	/company/integration/{idcompanyintegration}	companyIntegrationPut	Atualiza nome e status da integração.
DELETE	/company/integration/{idcompanyintegration}	companyIntegrationDelete	Inativa a integração (bloqueada por fornecedor/conta/anúncios).
GET	/company/integration/{idcompanyintegration}/check	companyIntegrationCheckGet	Verifica credenciais (chamada síncrona ao Worker).
PUT	/company/integration/{idcompanyintegration}/parameter	companyParameterPut	Sobrescreve (upsert) valores de parametrizações da integração.
POST	/company/integration/{idcompanyintegration}/parameter/import	companyParameterImportPost	Dispara importação automática de anúncios (proxy para Worker).

Produção

Método	Rota	Função	Descrição
GET	/sku/production	skuProductionList	Lista ordens de produção, com filtros por SKU, status e data.
POST	/sku/production	skuProductionPost	Cria uma OP — consome componentes do kit do SKU produzido e copia etapas da linha de produção.
GET	/sku/production/{idstockkeepingunitproduction}	skuProductionGet	Detalha uma OP — itens consumidos, etapas, custos e tempos.
PUT	/sku/production/{idstockkeepingunitproduction}	skuProductionPut	Atualiza campos da OP (descrição, data estimada, status, pedido).
DELETE	/sku/production/{idstockkeepingunitproduction}	skuProductionDelete	Cancela a OP — reverte movimentos de insumos e marca como cancelada.
POST	/sku/production/{idstockkeepingunitproduction}/finish	skuProductionFinishPost	Finaliza a OP — cria recebimento, lança produto produzido e fecha movimentos.
POST	/sku/production/{idstockkeepingunitproduction}/sku	skuProductionSkuPost	Adiciona um insumo extra consumido na OP.
PUT	/sku/production/{idstockkeepingunitproduction}/sku/{idskumovement}	skuProductionSkuPut	Atualiza um insumo (quantidade, armazém, custo, observações).
DELETE	/sku/production/{idstockkeepingunitproduction}/sku/{idskumovement}	skuProductionSkuDelete	Remove um insumo da OP.
PUT	/sku/production/{idstockkeepingunitproduction}/steps/{idstockkeepingunitproductionsteps}	skuProductionStepsPut	Atualiza o status e o tempo gasto de uma etapa da OP.
GET	/sku/production/line	skuProductionLineList	Lista linhas de produção da empresa com suas etapas.
POST	/sku/production/line	skuProductionLinePost	Cria uma linha de produção (sem etapas).
PUT	/sku/production/line/{idstockkeepingunitproductionline}	skuProductionLinePut	Atualiza nome e flag de padrão de uma linha.
DELETE	/sku/production/line/{idstockkeepingunitproductionline}	skuProductionLineDelete	Exclui uma linha (bloqueada quando há etapas ou produtos vinculados).
POST	/sku/production/line/{idstockkeepingunitproductionline}/steps	skuProductionLineStepPost	Cria uma etapa na linha de produção.
PUT	/sku/production/line/{idstockkeepingunitproductionline}/steps/{idstockkeepingunitproductionlinesteps}	skuProductionLineStepPut	Atualiza nome e ordem de uma etapa.
DELETE	/sku/production/line/{idstockkeepingunitproductionline}/steps/{idstockkeepingunitproductionlinesteps}	skuProductionLineStepDelete	Remove uma etapa de uma linha.

Mensagem Tracking

Método	Rota	Função	Descrição
GET	/carrier/tracking-template	trackingTemplateList	Lista templates de mensagem tracking ativos da empresa.
POST	/carrier/tracking-template	trackingTemplatePost	Cria um template (e-mail ou WhatsApp) para um status de tracking.
PUT	/carrier/tracking-template/{idcarriertrackingtemplate}	trackingTemplatePut	Atualiza um template existente (atualização parcial).
DELETE	/carrier/tracking-template/{idcarriertrackingtemplate}	trackingTemplateDelete	Remove fisicamente um template.

Regras Simulação Frete

Método	Rota	Função	Descrição
GET	/carrier/quotation/rule	carrierQuotationRuleList	Lista regras de simulação de frete ordenadas por Priority ASC (Ativas + Inativas; Excluídas ficam ocultas).
POST	/carrier/quotation/rule	carrierQuotationRulePost	Cria uma regra com 1+ condições e 1 ação (valida cada condição pelo seu tipo).
GET	/carrier/quotation/rule/{idcarrierquotationrule}	carrierQuotationRuleGet	Detalha uma regra (condições + histórico de alterações).
PUT	/carrier/quotation/rule/{idcarrierquotationrule}	carrierQuotationRulePut	Atualiza a regra; faz diff das condições e gera log (DE: x PARA: y / <Cond>_Adicionado / <Cond>_Removido).
DELETE	/carrier/quotation/rule/{idcarrierquotationrule}	carrierQuotationRuleDelete	Soft delete (Status = 2). Regrava o cache Redis.

Erros Simulação Frete

Método	Rota	Função	Descrição
GET	/carrier/quotation/error	carrierQuotationErrorList	Lista os 3000 erros mais recentes gerados pelo endpoint público de cotação de frete (sem CRUD).

Tracking

Método	Rota	Função	Descrição
GET	/orders/tracking	orderTrackingList	Lista pedidos em rastreamento com último status do tracking, datas de entrega e indicadores de pontualidade (até 3000 por página).

Log Pedidos

Método	Rota	Função	Descrição
GET	/orders/log	ordersLogList	Histórico de ações executadas em cada pedido (OrderEvents) com EventDescription, executor, resultado (Erro/Sucesso/Inativo) e data. Somente leitura, paginação fixa em 5000 itens/página.

Orçamentos

A tela Orçamentos (/app/budgets, módulo 81) consome endpoints já documentados em outras tags:

• GET /orders (OrdersGet) com Budget=1 — data source da lista. Detalhes na tag Outbound.
• PUT /orders/{idorder}/status (orderStatusPut) — usado pela ação Cancelar (IDOrderStatusTo=100) e pela conversão de orçamento para pedido (IDOrderStatusTo=0, gateado por PrivilegeConvertBudgetToOrder).

Notas Fiscais

Método	Rota	Função	Descrição
GET	/invoice	companyInvoiceList	Lista NFs do grupo (CompanyMain) com pedido, status, tipo, modelo e faturador. Quando IDStatusInvoice inclui 0, complementa com pedidos sem NF (linhas pendentes).
POST	/invoice	companyInvoicePost	Reserva/registra numeração de NF sem pedido (botão Gerar Numeração NF).
POST	/invoice/{idnfcompany}/disable	invoiceDisablePost (PHP)	Inutiliza NF não emitida na SEFAZ (modal Inutilizar NF).

Notas Fiscais de Serviço

Método	Rota	Função	Descrição
GET	/invoice-service	invoiceServiceList	Lista NFS-e da empresa (paginação fixa em 1000/página).
POST	/invoice-service	invoiceServicePost	Cria NFS-e em status Pendente; valida Inscrição Municipal, endereço e elegibilidade do município (NfseIssue=1).
DELETE	/invoice-service/{idserviceorder}	invoiceServiceDelete	Exclui NFS-e. Bloqueada quando IDStatusInvoice > 1 ou há conta a receber paga/parcial vinculada.
POST	/invoice-service/{idserviceorder}/invoice	invoiceServiceInvoicePost	Emite a NFS-e na prefeitura via worker PHP (/nfe/invoiceservicesingle.php).

GNRE / Apuração DIFAL

Método	Rota	Função	Descrição
GET	/orders/gnre	orderGnreList	Lista guias GNRE (default) ou apuração DIFAL (Summary=1). Mesmo handler para as duas telas. Paginação fixa em 5000 itens/página.
POST	/orders/gnre	orderGnrePost	Gera GNRE em massa para uma lista de IDOrder. Exige NF principal emitida (IDStatusInvoice=3).
POST	/orders/gnre/file	gnreFileDownload	Baixa ZIP com os PDFs das guias selecionadas (lista de IDGnre). URL S3 assinada por 2 dias + e-mail com o link.
GET	/orders/gnre/{idgnre}	gnreFileGet (PHP)	Devolve o PDF de uma guia individual. Handler em PHP — shape não confirmado neste repo.

Grupo Endereços

Método	Rota	Função	Descrição
GET	/sku/location/group	skuLocationGroupList	Lista grupos de endereços da empresa.
POST	/sku/location/group	skuLocationGroupPost	Cria um grupo (nome único por empresa).
PUT	/sku/location/group/{idstockkeepingunitlocationgroup}	skuLocationGroupPut	Atualiza o nome do grupo.
DELETE	/sku/location/group/{idstockkeepingunitlocationgroup}	skuLocationGroupDelete	Exclusão física (bloqueada quando há endereços vinculados).

Centro de Distribuição

Método	Rota	Função	Descrição
GET	/sku/distribution-center	skuDistributionCenterList	Lista CDs da empresa (respeita restrição de CDs do usuário).
POST	/sku/distribution-center	skuDistributionCenterPost	Cria CD (nome único; Default=1 zera os demais).
PUT	/sku/distribution-center/{idstockkeepingunitdistributioncenter}	skuDistributionCenterPut	Atualiza dados do CD.
DELETE	/sku/distribution-center/{idstockkeepingunitdistributioncenter}	skuDistributionCenterDelete	Exclusão física com 8 regras de bloqueio em cascata.

Coleções

Método	Rota	Função	Descrição
GET	/sku/collection	skuCollectionList	Lista coleções da empresa (ordenadas por nome).
POST	/sku/collection	skuCollectionPost	Cria coleção; reinvoca a lista e devolve a coleção criada.
PUT	/sku/collection/{idstockkeepingunitcollection}	skuCollectionPut	Renomeia a coleção.
DELETE	/sku/collection/{idstockkeepingunitcollection}	skuCollectionDelete	Exclusão física (bloqueada quando há SKUs associados).

Grupo SKU

Método	Rota	Função	Descrição
GET	/sku/group	skuGroupList	Lista grupos de SKU equivalentes da empresa.
POST	/sku/group	skuGroupPost	Cria grupo; reinvoca a lista e devolve o grupo criado.
PUT	/sku/group/{idstockkeepingunitgroup}	skuGroupPut	Renomeia o grupo.
DELETE	/sku/group/{idstockkeepingunitgroup}	skuGroupDelete	Exclusão física (bloqueada quando há SKUs ou códigos similares vinculados).

Códigos Similares SKU

Método	Rota	Função	Descrição
GET	/sku/similar-code	skuSimilarCodeList	Lista códigos similares da empresa com o grupo SKU resolvido.
POST	/sku/similar-code	skuSimilarCodePost	Cria código vinculado a um grupo; reinvoca a lista. Único por grupo.
GET	/sku/similar-code/tag	skuSimilarCodeTagList	Lista as tags em uso (autocomplete do campo SkuSimilarCodeTag).
PUT	/sku/similar-code/{idstockkeepingunitsimilarcode}	skuSimilarCodePut	Atualiza grupo, código e/ou tag; reinvoca a lista.
DELETE	/sku/similar-code/{idstockkeepingunitsimilarcode}	skuSimilarCodeDelete	Exclusão física (sem regras de bloqueio).

Tipo Variações (Grade)

Método	Rota	Função	Descrição
GET	/type/sku/variation	typeSkuVariationList	Lista variações Ativas da empresa, já com a grade de valores.
POST	/type/sku/variation	typeSkuVariationPost	Cria variação; reinvoca a lista. Ordem única por empresa.
GET	/type/sku/variation/type	typeProductVariationType	Lista os tipos padrão do sistema (Cor, Tamanho, Voltagem…).
GET	/type/sku/variation/{idtypeskuvariation}	typeSkuVariationGet	Detalha uma variação com sua grade.
PUT	/type/sku/variation/{idtypeskuvariation}	typeSkuVariationPut	Atualiza tipo/nome/ordem da variação.
DELETE	/type/sku/variation/{idtypeskuvariation}	typeSkuVariationDelete	Exclui variação (grade em cascata); bloqueada quando há SKU usando.
GET	/type/sku/variation/{idtypeskuvariation}/value	skuVariationValueList	Lista os valores da grade da variação.
POST	/type/sku/variation/{idtypeskuvariation}/value	skuVariationValuePost	Adiciona valor à grade; reinvoca o detalhe da variação.
PUT	/type/sku/variation/{idtypeskuvariation}/value/{idtypeskuvariationvalue}	skuVariationValuePut	Atualiza nome/ordem do valor da grade.
DELETE	/type/sku/variation/{idtypeskuvariation}/value/{idtypeskuvariationvalue}	skuVariationValueDelete	Remove valor da grade; bloqueada quando há SKU usando.

Categorias

Método	Rota	Função	Descrição
GET	/category	categoryList	Lista categorias em árvore (Type=Tree) ou recursiva com trilha.
POST	/category	categoryPost	Cria categoria; reinvoca o detalhe e devolve a categoria criada.
GET	/category/{idcategory}	categoryGet	Detalha a categoria, incluindo o nome da categoria pai.
PUT	/category/{idcategory}	categoryPut	Atualiza a categoria (não pode ser superior dela mesma).
DELETE	/category/{idcategory}	categoryDelete	Soft delete (Status=0); bloqueado quando há produtos ativos ou filhos.
GET	/category/{idcategory}/sku-specification	skuSpecificationFieldList	Lista especificações da categoria (herdadas dos ancestrais).
POST	/category/{idcategory}/sku-specification	skuSpecificationFieldIdPost	Cria especificação na categoria.
GET	/category/{idcategory}/sku-specification/{idstockkeepingunitspecificationsfieldid}	skuSpecificationFieldIdGet	Detalha a especificação com seus valores.
PUT	/category/{idcategory}/sku-specification/{idstockkeepingunitspecificationsfieldid}	skuSpecificationFieldIdPut	Atualiza a especificação.
POST	/category/{idcategory}/sku-specification/{idstockkeepingunitspecificationsfieldid}	skuSpecificationFieldValuePost	Adiciona um valor à especificação.
DELETE	/category/{idcategory}/sku-specification/{idstockkeepingunitspecificationsfieldid}	skuSpecificationFieldIdDelete	Exclui a especificação.
PUT	/category/{idcategory}/sku-specification/{idstockkeepingunitspecificationsfieldid}/{idstockkeepingunitspecificationsfieldvalues}	skuSpecificationFieldValuePut	Atualiza um valor da especificação.
DELETE	/category/{idcategory}/sku-specification/{idstockkeepingunitspecificationsfieldid}/{idstockkeepingunitspecificationsfieldvalues}	skuSpecificationFieldValueDelete	Exclui um valor da especificação.
GET	/type/sku/specification/field-type	typeSkuSpecificationFieldTypeList	Lista os tipos de campo de especificação (texto, número, lista…).

Fornecedores e SKUs

Tela consolidada (/app/skussuppliers, módulo 68) que lista, em modo de leitura, todos os vínculos SKU × fornecedor da empresa. A criação, a edição e a exclusão individuais de cada vínculo acontecem na aba Fornecedores do cadastro do produto; nesta tela ficam a importação e a exclusão em lote.

Método	Rota	Função	Descrição
GET	/sku/supplier	skuSupplierList	Lista consolidada dos vínculos SKU × fornecedor com 14+ filtros (SKU/nome/código de barras/marca/categoria/código fornecedor/integração); paginado em 5000. A coluna de custo retornada depende de UseCostFromCostSet.
GET	/sku/supplier/{idsku}	skuSupplierGet	Lista os vínculos de fornecedor de um SKU (opcionalmente filtrado por IDStockKeepingUnitSuplierCode).
POST	/sku/supplier/{idsku}	skuSupplierPost	Cria o vínculo SKU × fornecedor (IDSupplier, QuantityMultiply, SupplierCode). Bloqueia código+fornecedor já cadastrados.
PUT	/sku/supplier/{idsku}/{idstockkeepingunitsupliercode}	skuSupplierPut	Atualiza o vínculo existente (mesmas validações do POST).
DELETE	/sku/supplier/{idsku}/{idstockkeepingunitsupliercode}	skuSupplierDelete	Remove o vínculo SKU × fornecedor.

Preços

CRUD de preços por SKU × Política Comercial × vigência. Cada SKU pode ter vários preços ativos ao mesmo tempo, um por combinação política + intervalo de datas. Na venda, o sistema escolhe o preço cuja política comercial casa com o canal/regra usada e cuja vigência cobre o momento atual. Políticas relativas (calculadas a partir de outra política base) têm preços bloqueados para edição.

Método	Rota	Função	Descrição
GET	/sku/pricing	skuPricingList	Lista preços com 14+ filtros (SKU/nome/código de barras/fornecedor/categoria/marca/política/vigência), paginado em 2000. Retorna preço + custo + valor de estoque + markup calculado + tipo da política.
POST	/sku/pricing/{idsku}	skuPricingPost	Cria preço (PriceList, PriceSell, DateFrom, DateTo, IDCompanySalesPolicy). Política omitida usa a Default da empresa. Querystring UpdateIfPossible=1 faz upsert. Para política relativa (tipo 3), recalcula preço a partir da base. Dispara webhook SQS, atualiza timestamp do SKU, e recalcula kit pai (quando o kit tem KitAutomaticPricingUpdate=1).
PUT	/sku/pricing/{idsku}/{idstockkeepingunitpricing}	skuPricingPut	Atualiza preço existente (mesmos efeitos cruzados do POST).
DELETE	/sku/pricing/{idsku}/{idstockkeepingunitpricing}	skuPricingDelete	Remove preço.

Parametrizações que afetam: BlockZeroPrice (bloqueia PriceSell=0), BlockDifferentPriceSameSalesPolicy (bloqueia duplicidade SKU+política), AutomaticHubSkuPricingUpdate (sincroniza preço com canais de venda automaticamente).

Pedidos

Tela master das vendas (/app/orders, módulo 1). 38 endpoints diretos sob /orders cobrindo CRUD, finalização, alteração de status, itens, pagamentos, faturamento, devolução, pacotes/etiquetas, anexos, cotação de frete, EDI, GNRE, tracking, integração com canal. A ficha do pedido tem 12 abas controladas por privilégios PrivilegeOrderTab*.

Endpoints principais:

Método	Rota	Função	Descrição
GET	/orders	orderList	Listagem com 50+ filtros (status, datas, cliente, valor, canal, transportadora…), paginado em 2000.
POST	/orders	orderPost	Cria pedido (cabeçalho, itens, pagamentos, endereços).
GET	/orders/{idorder}	orderGet	Ficha completa do pedido.
PUT	/orders/{idorder}	orderPut	Atualiza cabeçalho/itens/pagamentos.
DELETE	/orders/{idorder}	orderDelete	Exclui (bloqueado quando há NF emitida, movimento de estoque ou pagamento conciliado).
POST	/orders/{idorder}/duplicate	orderDuplicatePost	Clona o pedido em status Aberto.
POST	/orders/{idorder}/start-handling	orderStartHandlingPost	Finaliza o pedido (Aberto → próximo status conforme Tipo de Pedido).
POST	/orders/{idorder}/status	orderStatusPost	Força alteração de status (privilégio Atualizar Status Pedidos).
POST	/orders/{idorder}/sku	orderSkuPost	Adiciona item ao pedido.
PUT	/orders/{idorder}/sku/{idskumovement}	orderSkuPut	Atualiza item (quantidade, preço, desconto).
DELETE	/orders/{idorder}/sku/{idskumovement}	orderSkuDelete	Remove item.
POST	/orders/{idorder}/payment	orderPaymentPost	Adiciona pagamento.
PUT	/orders/{idorder}/payment/{idaccountpayablereceivable}	orderPaymentPut	Atualiza pagamento.
DELETE	/orders/{idorder}/payment/{idaccountpayablereceivable}	orderPaymentDelete	Remove pagamento.
POST	/orders/{idorder}/invoice	orderInvoicePost	Gera NF-e/NFCe.
POST	/orders/{idorder}/invoice/check	orderInvoiceCheckPost	Valida cadastro antes de gerar a NF.
POST	/orders/{idorder}/invoice/simulation	orderInvoiceSimulationPost	Simula a NF (cálculo de impostos sem emitir).
POST	/orders/{idorder}/invoice/upload	orderInvoiceUploadPost	Upload de XML/PDF de NF emitida externamente.
PUT	/orders/{idorder}/invoice/{nfenumber}	orderInvoicePut	Atualiza/cancela uma NF específica (CC-e, cancelamento).
POST	/orders/{idorder}/return	orderReturnPost	Gera devolução (Reversa).
POST	/orders/{idorder}/packages	orderPackagesPost	Adiciona pacote.
PUT	/orders/{idorder}/packages/{idpackage}	orderPackagesPut	Atualiza pacote (rastreio, dimensões).
DELETE	/orders/{idorder}/packages/{idpackage}	orderPackagesDelete	Remove pacote.
GET	/orders/{idorder}/label	orderLabelGet	Gera ZPL da etiqueta.
GET	/orders/{idorder}/carrier/quotation	orderCarrierQuotationGet	Cotação de frete em tempo real.
POST	/orders/{idorder}/carrier/edi	orderCarrierEdiPost	Envia EDI da transportadora.
POST	/orders/{idorder}/promotion	orderPromotionPost	Aplica promoção PDV.
POST	/orders/{idorder}/file	orderFilePost	Anexa arquivo ao pedido (foto, contrato, comprovante de entrega — query IDTypeOrderFile).
DELETE	/orders/{idorder}/file/{idorderscustomfile}	orderFileDelete	Remove anexo.
GET	/orders/log	orderLogList	Histórico geral de eventos.
GET	/orders/tag	orderTagList	Tags disponíveis.
GET	/orders/template	orderTemplateList	Templates de pedido.
GET	/orders/tracking	orderTrackingList	Status de tracking dos pedidos.
POST	/orders/invoice-xml	orderInvoiceXmlPost	Baixa XML(s) de NF em lote.
POST	/orders/invoice-xml/import	orderInvoiceXmlImportPost	Importa XML de NF de entrada.

Outros endpoints relacionados: /orders/gnre (GNRE), /orders/hub (Pedidos Integrados — documentado em tag própria), /orders/package (Pré-Romaneio — documentado em tag própria).

Produtos e SKUs

Tela master do catálogo (/app/skus em modo SKUs, /app/listproducts em modo Produtos). 87 endpoints sob /sku cobrindo CRUD do SKU, variações, imagens, kits, fornecedores, especificações, preços, lotes, endereços, séries, anúncios, movimentos, produção e mais. A ficha do SKU tem 22 abas controladas por privilégios PrivilegeSkuTab* e pelo tipo do produto.

Endpoints principais:

Método	Rota	Função	Descrição
GET	/sku	skuList	Listagem com 30+ filtros (categoria, marca, fornecedor, faturador, status, lote, faixa de preço/custo, sem imagem, sem anúncio…), paginado em 2000. Suporta dois modos: SKUs (default) e Produtos (?ListProducts=1).
POST	/sku	skuPost	Cria SKU; aceita 1 ou vários em lote (modal Novo Produto lista SKUs variantes antes de salvar).
GET	/sku/{idsku}	skuGet	Ficha completa do SKU com arrays de relações (códigos de barras, fornecedores, especificações, etc.).
PUT	/sku/{idsku}	skuPut	Atualiza qualquer campo (parcial — só os campos enviados).
DELETE	/sku/{idsku}	skuDelete	Exclusão (soft IDStatusSku=0 ou física conforme cenário).
GET	/sku/{idsku}/label	skuLabelGet	Gera ZPL da etiqueta do SKU.
POST	/sku/{idsku}/cost/recalculate	skuCostRecalculatePost	Recalcula custo médio e último custo a partir do histórico de entradas.

Sub-recursos com tela própria documentada em outras tags: Códigos de Barras (/sku/{idsku}/barcode, /sku/{idsku}/barcodepackage), Imagens (/sku/image/{idsku}), Kit (/sku/kit/{idsku}), Especificações (/sku/specification/{idsku}), Fornecedores SKU (/sku/supplier/{idsku}), Categorias Similares (/sku/similarcategory/{idsku}), Variação (/sku/variation/{idsku}, /sku/{idsku}/variation), Grupo SKU (/sku/{idsku}/group), Coleção (/sku/{idsku}/collection), Serial/IMEI (/sku/{idsku}/serial), Preços (/sku/pricing/{idsku}), Promoção PDV (/sku/promotion), Tags (/sku/tag), Templates (/sku/template), Log (/sku/log), Movimentos (/sku/movement), Lotes (/sku/batch), Endereços (/sku/location), Saldo (/sku/balance, /sku/warehouse), Inventário (/sku/inventory, /sku/inventory-summary), Produção (/sku/production), Ressuprimento (/sku/resupply), Códigos Similares (/sku/similar-code), Pacote (/sku/package), Distribuição (/sku/distribution-center).

Departamento Fiscal

Estrutura em três níveis (Departamento → CFOPs → ICMS por estado) que define os impostos aplicados em cada produto na emissão da NF-e/NFCe. O Departamento é amarrado no SKU; a tela decide o CFOP pela direção da operação (saída/entrada) e estado da matriz × destinatário, e dentro do CFOP escolhe a regra ICMS pelo estado destino.

Método	Rota	Função	Descrição
GET	/tax	taxList	Lista departamentos Ativos (id + descrição + conta). Filtros: IDCompany, IDTaxDepartment, TaxDepartmentDescription. Limite 2000.
POST	/tax	taxPost	Cria departamento (TaxDepartmentDescription único por conta). Reinvoca taxGet e devolve o registro criado.
GET	/tax/{idtaxdepartment}	taxGet	Detalha departamento + array Cfop[] agregado (todos os campos federais — PIS/COFINS/IPI saída/entrada, IBS/CBS, 4 CFOPs por direção/estado, switches, descrições de CST resolvidas via JOINs). Filtro IDCompany restringe a uma matriz/filial.
PUT	/tax/{idtaxdepartment}	taxPut	Atualiza descrição do departamento.
DELETE	/tax/{idtaxdepartment}	taxDelete	Soft delete (Status=0); bloqueado quando há SKU usando ou regra de Tipo de Pedido apontando para o departamento.
POST	/tax/{idtaxdepartment}/cfop	taxCfopPost	Cria uma regra fiscal (CFOP) no departamento — dezenas de campos com regras condicionais por switch (NfeExport, IssueNFCe, IncludeIPI).
GET	/tax/{idtaxdepartment}/cfop/{idtax}	taxCfopGet	Detalha o CFOP + array Icms[] com as regras por estado.
PUT	/tax/{idtaxdepartment}/cfop/{idtax}	taxCfopPut	Atualiza a regra fiscal.
DELETE	/tax/{idtaxdepartment}/cfop/{idtax}	taxCfopDelete	Exclui a regra fiscal (com as regras ICMS por estado em cascata).
POST	/tax/{idtaxdepartment}/cfop/{idtax}/interstate	taxInterstatePost	Cria regra ICMS para um estado destino dentro do CFOP. Campos habilitados/desabilitados dinamicamente conforme IcmsCst.
PUT	/tax/{idtaxdepartment}/cfop/{idtax}/interstate/{idtaxinterstate}	taxInterstatePut	Atualiza regra ICMS.
DELETE	/tax/{idtaxdepartment}/cfop/{idtax}/interstate/{idtaxinterstate}	taxInterstateDelete	Exclui regra ICMS de um estado.

Armazéns

Método	Rota	Função	Descrição
GET	/sku/warehouse	skuWareHouseList	Lista armazéns Ativos da empresa (com tipo resolvido).
POST	/sku/warehouse	skuWareHousePost	Cria armazém e endereço padrão homônimo dentro dele.
PUT	/sku/warehouse/{idstockkeepingunitwarehouse}	skuWareHousePut	Atualiza dados do armazém.
DELETE	/sku/warehouse/{idstockkeepingunitwarehouse}	skuWareHouseDelete	Soft delete (Status=0); bloqueado quando há endereço ou de/para vinculado.

Categoria Armazenagem

Método	Rota	Função	Descrição
GET	/sku/location/category	skuLocationCategoryList	Lista categorias Ativas.
POST	/sku/location/category	skuLocationCategoryPost	Cria categoria (nome único por empresa).
PUT	/sku/location/category/{idstockkeepingunitlocationcategory}	skuLocationCategoryPut	Atualiza o nome.
DELETE	/sku/location/category/{idstockkeepingunitlocationcategory}	skuLocationCategoryDelete	Soft delete (IsActive=0 + prefixo no nome); bloqueado quando há endereço ou SKU vinculado.

Movimentação Estoque

Método	Rota	Função	Descrição
GET	/sku/movement	skuMovementList	Histórico de movimentações. Modos via Type: padrão (listagem), Kardex/kardex (cronológico por SKU + armazém), KardexLocation (por endereço), SkuInbound (entradas + NF-e de compra), SkuOutbound (saídas + NF-e de venda + pedido), SkuFiscalConciliation (árvore recursiva de lotes).
POST	/sku/movement/transfer	skuMovementTransferPost	Transfere quantidade entre armazéns (warehouse → warehouse) ou entre lotes/endereços (IDBatchFrom + IDBatchTo/IDStockKeepingUnitLocationTo). Gera duas movimentações (saída + entrada), reprocessa pedidos em "Falta produto" no destino e publica webhook SkuBalanceTransfer.
POST	/sku/{idsku}/cost/recalculate	skuCostRecalculatePost	Despacha o recálculo do custo médio do SKU a partir do histórico de movimentações. Processamento assíncrono (handler PHP via asyncLambdaGateway).

Cesto Picking

Método	Rota	Função	Descrição
GET	/fulfillment/picking/basket	orderFulfillmentPickingBasketList	Lista cestos Ativos com pedido amarrado e histórico.
POST	/fulfillment/picking/basket	orderFulfillmentPickingBasketPost	Cria cesto (ExternalId único por CD).
PUT	/fulfillment/picking/basket/{idpickinglisbasket}	orderFulfillmentPickingBasketPut	Atualiza dimensões/CD; enviar IDOrder=null desvincula pedido.
DELETE	/fulfillment/picking/basket/{idpickinglisbasket}	orderFulfillmentPickingBasketDelete	Soft delete (status=0 + libera ExternalId).
GET	/fulfillment/picking/basket/{idpickinglisbasket}/label	purchaseLabelGet	Gera ZPL da etiqueta do cesto.

Reversa / Devolução

A tela reaproveita o componente da tela de Compras com o filtro ReturnOrder=1 aplicado em todas as chamadas — ou seja, usa os mesmos endpoints do recebimento de compra (/purchase, /purchase/{idpurchase}, /purchase/{idpurchase}/check, /purchase/{idpurchase}/invoice, /purchase/{idpurchase}/label, /purchase/xml, /purchase/feed, etc.) restritos a registros cujo ReturnOrder = 1 (devolução de venda) em vez de 0 (recebimento de compra).

Característica	Compras	Reversa / Devolução
Rota frontend	/app/purchase	/app/orderreturn
Filtro nos endpoints	ReturnOrder=0	ReturnOrder=1
Origem do produto	Fornecedor (StockKeepingUnitBuyOrder)	Cliente (devolução de Orders)
Privilégios	PrivilegePurchase*	PrivilegeOrderReturn*

A documentação detalhada dos endpoints está sob a tag Compras (a documentar em rodada futura). Os privilégios exclusivos desta tela estão na seção do FAQ correspondente.

CTe

Tela de caixa de entrada dos CT-e (Conhecimentos de Transporte Eletrônicos) emitidos contra o CNPJ da empresa (frontend Ctes, /app/ctes, módulo 15, privilégio PrivilegeCTeView). O idworks consulta a SEFAZ automaticamente, traz o XML e a DANFE, e a partir desta tela o time fiscal/financeiro cria a conta a pagar da transportadora, baixa o XML/DANFE (individual ou em lote) e usa o CT-e para conferir peso e valores cobrados vs. simulados.

Método	Rota	Função	Descrição
GET	/cte	cteFeedGet	Lista do feed. Paginação fixa em 1000 por página. Vincula automaticamente o pedido a partir da chave da NF-e citada no CT-e. Suporta modo FreightConciliation=1 para análise de divergência com leilão de frete.
GET	/cte/invoice-xml?Folder=Cte&Type=XML|PDF&token=…&File=…	cteFeedXmlGet	PHP. Proxy que serve o XML/PDF individual do S3. Não chamado direto pelo frontend — as URLs já vêm prontas em XmlFile/XmlDanfe do payload de GET /cte.
POST	/cte/invoice-xml	cteFeedXmlDownload	Baixa em lote os XMLs dos CT-e selecionados. Body é array de IDCarrierInvoice. Devolve URL pré-assinada do zip.
POST	/accounts/payable	accountsPayablePost	Endpoint reaproveitado para criar a conta a pagar a partir do CT-e (documentado na tag Contas a Pagar). O modal Criar Contas a Pagar desta tela monta o body com IDSupplier (transportadora), Value, DocumentNumber (CTeNumber), datas e os campos preenchidos pelo usuário (DateDue, IDTypeDocument, IDTypeAccountPayableReceivable).
GET	/supplier?IDTypeSupplier=2,7&TypeSupplier=Transportadora&SupplierCpfCnpj=…	supplierList	Localiza a transportadora ativa pelo CNPJ do CT-e antes de abrir o modal. Quando retorna vazio, o modal mostra Não foi localizado transportadora no sistema. e fecha.

Privilégios (TypeUserPrivilege módulo 15):

• PrivilegeCTeView (id 53) — acesso à tela.
• PrivilegeCTeDownload (id 46) — ícone Baixar XML na linha e opção em Mais Ações (lote).

Nenhuma parametrização da empresa altera esta tela — o conteúdo vem direto da SEFAZ. Configurações que afetam as colunas de simulação (R$ frete simulado / R$ frete diferença) ficam nas telas Simulação Frete e no cadastro de transportadora (CarrierAuction=1 em Fornecedores).

Feed Nota Fiscal

Tela de caixa de entrada das NF-e de produto emitidas contra o CNPJ da empresa (frontend Feeds, /app/feeds, módulo 7, privilégio PrivilegeNFeFeedView). O idworks consulta a SEFAZ automaticamente, traz o XML e a DANFE, e a partir desta tela o time fiscal manifesta a nota perante a SEFAZ, cria o recebimento (importa os itens e movimenta estoque), cria contas a pagar (sem mexer no estoque), organiza com tags e baixa XML/DANFE individualmente ou em lote.

Método	Rota	Função	Descrição
GET	/purchase/feed	purchaseFeed	Lista do feed. Paginação fixa em 500 por página. Retorna a NF + descrição de tipo/situação/evento + eventual recebimento criado + eventual conta a pagar + tags + URLs assinadas para XML/DANFE.
PUT	/purchase/feed/{idnfevents}	purchaseFeedPut	Sincroniza as tags internas (NfEventsTag) com o array enviado.
POST	/purchase/feed/{idnfevents}/manifest	purchaseFeedManifestPut	PHP. Manifesta a NF na SEFAZ. Eventos aceitos: 210200 Confirmação, 210210 Ciência, 210220 Desconhecimento, 210240 Operação não Realizada (este exige Comments com 15-255 caracteres). Irreversível.
POST	/purchase/feed/invoice-xml	purchaseFeedXmlGet	Baixa em lote os XMLs (array de <chave>.xml). Compacta em zip no S3 e devolve URL pré-assinada (TTL 2 dias) + envia link por e-mail ao usuário.
POST	/purchase/feed/invoice-danfe	purchaseFeedDanfeBulkPost	PHP. Equivalente para PDFs de DANFE. Body é array de IDNfEvents.
GET	/purchase/feed/tag	purchaseFeedTagList	Lista as tags distintas já cadastradas no feed da empresa. Usado pelo seletor de tags e pelo filtro.
POST	/purchase/xml	purchaseInvoiceXmlPost	Cria recebimento (OnlyPayment=0, default — invoca worker PHP que importa itens e movimenta estoque) ou apenas contas a pagar (OnlyPayment=1). Identifica a nota via IDNfEvents (feed), IDOrder (nota de saída — fluxo de devolução) ou XML cru no body. ImportType define o critério de casamento dos SKUs (4 Todos, 1 Código Fornecedor, 2 GTIN, 3 Código de Referência).
GET	/type/invoice/event?Type=2	typeInvoiceEventList	Lista as operações de manifestação disponíveis. Usada pelo seletor Operação dos modais Manifestar (individual e em lote).

Parametrização (grupo Feed):

• NfeEmail — Envia e-mail automático ao cadastro de notificação da empresa sempre que uma nota nova cai no feed.

Outras telas que influenciam a criação do recebimento (não são parametrizações):

• DE/PARA CFOP Recebimento (/app/cfopinbound) — converte automaticamente CFOPs interestaduais do XML para CFOPs internos no momento da criação do recebimento.
• Plano de Contas padrão para compras — sem ele, POST /purchase/xml?OnlyPayment=1 falha com [BadRequest] - Plano de contas padrão para compras não cadastrado.
• Tipo Documento padrão — usado para popular o tipo de documento da conta a pagar.

Privilégios (TypeUserPrivilege módulo 7):

• PrivilegeNFeFeedView (id 30) — acesso à tela.
• PrivilegeNFeFeedDownload (id 20) — ícone Baixar XML na linha e opção Baixar XML em Mais Ações (lote).

Outbound

Tela de entrada do fluxo de saída do CD (frontend Outbound, /app/pickinglist, módulo 22, privilégio PrivilegePickingPackingView). Lista os pedidos prontos para começar a expedição (filtro default IDStatusOrder=1 — Fechado) e permite gerar picking-list(s) em lote a partir da seleção (Mais Ações → Gerar Picking-List), abrir um pedido para editar e cancelar pedidos no status Aberto. As três colunas de valor (ValueProduct, ValueShipping, ValueOrder) só aparecem quando o usuário tem PrivilegePurchaseViewValues.

Método	Rota	Função	Descrição
GET	/orders	ordersList	Lista de pedidos. Endpoint compartilhado (Pedidos, Retirada em Mãos, Outbound, etc.) — o que muda em cada tela é o subconjunto de querystrings. Paginação fixa em 2000 itens/página. Documentado aqui por ser o data source principal do Outbound.
PUT	/orders/{idorder}/status	orderStatusPut	Transição de status do pedido. Usado pelo botão Cancelar desta tela (com IDOrderStatusTo=90), mas serve a todas as transições válidas configuradas em TypeStatusOrderRule.
POST	/fulfillment/picking	orderFulfillmentPickingPost	Gera picking-list(s) a partir dos pedidos selecionados. Documentado em detalhes na seção Picking List; a ação parte daqui.

Parametrizações consumidas pelo frontend da tela na geração de picking-list em massa (grupo Logística (WMS) → Picking exceto indicado):

• AutoGeneratePicking — Ao gerar a picking-list pelo Outbound, o frontend já chama start + finish em sequência e abre o Packing em vez da tela Picking List.
• QuantityOfOrdersWhenGeneratingPickingList — Limite máximo de pedidos por picking-list gerada. Seleção maior é fatiada em várias chamadas a POST /fulfillment/picking.
• ShareDataWithRelatedCompanies (grupo Logística (WMS)) — Quando ativa, a seleção de pedidos de várias contas relacionadas vai para uma única picking-list; sem ela, o frontend gera uma chamada por conta.

As parametrizações que afetam o backend da geração (IgnoreBalanceStartPickinglist, CheckSalesChannelOrderStatusCreatePickingList, OnlyAllowPickingWithLabel, UseShippingHandlingTimeInPickingPriority, StartFinishPicking, SplitOrderDifferentLocationGroup, etc.) estão descritas na seção Picking List e no endpoint POST /fulfillment/picking.

Privilégios consumidos pela tela:

• PrivilegePickingPackingView (módulo 22, id 121) — acesso à tela.
• PrivilegePickingPackingCreate (módulo 59, id 122) — ação Gerar Picking-List.
• PrivilegeOrderEdit (módulo 1, id 8) — botão Editar (ícone lápis).
• PrivilegeOrderDelete (módulo 1, id 68) — botão Cancelar (ícone lixeira), habilitado apenas quando IDStatusOrder=0.
• PrivilegeOrderView (módulo 1, id 24) — abrir pedido por duplo-clique.
• PrivilegePurchaseView (módulo 3, id 26) — fallback para abrir pedido por duplo-clique.
• PrivilegePurchaseViewValues (módulo 3, id 714) — exibe as colunas ValueProduct, ValueShipping, ValueOrder.

Picking List

Tela de supervisão da separação no CD (frontend PickingListPrint, /app/pickinglistprint, módulo 59). Esta tela não cria picking-lists — consome (a criação vive em Saída de Pedidos e na geração automática). Aqui o supervisor atribui colaborador, ajusta prioridade/tipo, consolida, imprime a folha, inicia/finaliza a coleta e trata inconformidades reportadas pelo celular (WMS).

Método	Rota	Função	Descrição
POST	/fulfillment/picking	orderFulfillmentPickingPost	PHP. Gera picking-list(s) a partir de pedidos. Agrupa por combinação de IDStockKeepingUnitLocationGroup (mesmo CD obrigatório). Idempotência via Redis (5 s). Resolve prioridade pela PickingListConfiguration ativa. Saldo insuficiente → status 24/93/11 no pedido. OnlyValidate=1 retorna {HasBalance, AvailableResupply} sem criar.
GET	/fulfillment/picking/picking-list	orderFulfillmentPickingListList	Lista (limite 5 000) ordenada por PickingListPriority. Filtros: status, ID, colaborador, cesto, CD, faixas de datas (criação, picking, packing, entrega). ACL de CD aplicada.
GET	/fulfillment/picking/picking-list/{id}	orderFulfillmentPickingListGet	Detalhe com rota serpentina otimizada (Floor DESC → Street ASC → Module alterna ASC/DESC por paridade → LocationSide direita/esquerda → Column/Level). ?Grouped=1 agrupa por endereço. ?Draft=1 retorna rascunho do Redis (TTL 4 d).
PUT	/fulfillment/picking/picking-list/{id}	orderFulfillmentPickingListPut	Atualiza RecordUserCreatedStartPicking, IDTypePickingList, PickingListPriority ou IDPickingListStatus (apenas valores 4, 6 ou 7 — outros transitions usam Start/Finish/Generate). ?Draft=1 grava no Redis sem persistir. Valida função do colaborador (IDUserJobPosition=3).
POST	/fulfillment/picking/picking-list/{id}/start	orderFulfillmentPickingListStart	Status 1 → 2. Todos os pedidos precisam estar em IDStatusOrder=3. Regra de uma lista iniciada por colaborador (configurável via UserCanStartMoreThanOnePickingList). Enfileira NF (SQS invoice.fifo) se InvoiceAfterPickingListStart=1 (global ou por integração).
POST	/fulfillment/picking/picking-list/{id}/finish	orderFulfillmentPickingListFinish	Status 2/6/7 → 3. UPDATE blanket nos pedidos para status 4 — sobrescreve até NC/ressuprimento. Validação aceita pedidos em {2,4,10,24}. Enfileira NF se InvoiceAfterPicking=1. Body opcional para vincular cestos (PickingListBasket).
POST	/fulfillment/packing/picking-list/{id}/merge	orderFulfillmentPickingListMerge	Mescla picking-list origem (path) na destino (IDPickingList no body). Ambas em status 1. URL começa com /packing/ (legado). Não recomputa prioridade da destino; PickingBasket é preservado (potencial colisão de sequenciais).
DELETE	/fulfillment/picking/picking-list/{id}/order/{idorder}	orderFulfillmentPickingListOrderDelete	Remove pedido. {id} no path é ignorado — handler usa Orders.IDPickingList. Validação IDStatusOrder ≤ 5 (mensagem misleading \"Pedido não esta no status Segurar Pedido\"). Transição automática conforme presença de NC: 1-3+NC→10 (Picking NC), 4+NC→14 (Packing NC), 5→13 (Tratativa), 1-4 sem NC→1 (Fechado).
PUT	/fulfillment/picking/picking-list/{id}/order/{idorder}/sku/{idskumovement}	orderFulfillmentSkuNonconformityPut	Registra inconformidade (IDTypeFulfillmentNonconformity 1=Avaria, 2=Vencido, 5=Falta, 6=Ressuprimento). Sem TransferIfPossible=1: marca o movimento. Com: divide o movimento se NC<Qty, invoca skuMovementTransferPost para o armazém parametrizado, dispara batchqueue.php para realocar batch. ?ReturnPickingList=1 retorna detalhe da lista em vez do pedido.

Parametrizações mais impactantes (grupo Logística (WMS) -> Packing exceto indicado):

• UserCanStartMoreThanOnePickingList — relaxa regra de uma lista iniciada por colaborador.
• InvoiceAfterPickingListStart / InvoiceAfterPicking — disparam emissão de NF na fila SQS no Start ou no Finish.
• AutomaticTransferNonConformityInPicking{Missing,BestBefore,Damage}Warehouse — endereços para transferência automática do tipo correspondente.
• ShareDataWithRelatedCompanies — permite seleção cruzada entre contas.
• ShowCompletePickingListStatus — habilita status 6 e 7 (dupla conferência).
• UseShippingHandlingTimeInPickingPriority — soma (ShippingDate - hoje) à prioridade base.
• StartFinishPicking — força Start+Finish ao final da geração.
• IgnoreBalanceStartPickinglist — permite gerar mesmo sem saldo.
• SplitOrderDifferentLocationGroup — divide pedido em filhos quando spans >1 LocationGroup (apenas VTEX/idworks).
• CheckSalesChannelOrderStatusCreatePickingList — re-valida cancelamento no canal.
• OnlyAllowPickingWithLabel — só inclui pedido com etiqueta de canal disponível.

Privilégios (TypeUserPrivilege módulo 59): PrivilegePickingListPrintView, PrivilegePickingPackingCreate (Gerar), PrivilegePickingPackingEdit (Iniciar/Finalizar), PrivilegePickingPackingDelete (Remover pedido + inconformidade), PrivilegeCollaboratorsAssignmentPickingList (Atribuir colaborador), PrivilegePickingAllowEditQuantity (quantidade no celular), PrivilegePickingListMerge (Consolidar).

Packing

Tela de conferência por bipagem, embalagem, peso e faturamento (frontend Packing, /app/packing, módulo 58). O operador bipa cada item de uma picking-list para conferir contra o pedido, define embalagem/peso/quantidade de volumes, e ao concluir o sistema cria os volumes (Packages), emite a NF-e, gera a etiqueta e move o pedido para o próximo estágio (status 6 Aguardando expedição, 7 Enviado ou 22 Aguardando romaneio).

Método	Rota	Função	Descrição
POST	/fulfillment/packing/order/{idorder}	orderFulfillmentPackingIDOrderPost	Coração do fluxo. Recebe Items (conferência), Volumes (peso/dimensões), Packages (embalagens) e QuantityPackages. Compara com StockKeepingUnitMovement da picking-list; em divergência, falha (a menos que PartialInvoice=1 e parametrização AllowPartialInvoice=1). Emite NF-e via worker PHP /nfe/invoice.php (skippa com NoInvoice=1). Querystring Draft=1 apenas grava o body como rascunho no Redis (TTL 4 dias). Debounce de 3 s via Redis md5 do body.
DELETE	/fulfillment/packing/order/{idorder}	orderFulfillmentPackingIDOrderDelete	Cancela o pedido (IDStatusOrder = 90). Libera reserva, cancela contas a receber, apaga volumes, registra OrderEvent IDEvent=19. Quando AutomaticTransferCancelWarehousePacking configurado, transfere itens para Devolução. Bloqueado se NF emitida ou pedido em romaneio.
GET	/fulfillment/packing/picking-list/{idpickinglist}	orderFulfillmentPackingListGet	Detalhe da picking-list para packing: lista pedidos com itens esperados (SKU, código de barras, endereço, série, kit) + Draft salvo no Redis (progresso de bipagem). Exclui itens cujo SKU é embalagem (Package=1).

O endpoint POST /fulfillment/packing/picking-list/{id}/merge é usado também pelo Packing (botão "Mesclar Picking Lists"), mas a documentação completa fica em Picking List acima — é o mesmo handler.

Parametrizações (grupo Logística (WMS) → Packing exceto indicado) consumidas pelos endpoints:

• AllowPartialInvoice — gateia PartialInvoice=1.
• AutomaticTransferPartialInvoiceWarehousePacking — endereço Quarentena para itens removidos no faturamento parcial.
• AutomaticTransferCancelWarehousePacking — endereço Devolução para itens no cancelamento.
• SetShippedAfterPacking — força status 7 (Enviado) após packing.
• IgnorePickingList (grupo Logística → Expedição) — desliga criação automática de romaneio após packing.

Demais parametrizações da tela (AddPackage, AddPackageWeight, ShowPackageQuantityModal, MaxWeightPerVolume, ConferenceFastPacking, customizações de DANFE simplificada, etc.) são consumidas apenas pelo frontend.

Privilégios (TypeUserPrivilege módulo 58): PrivilegePackingView, PrivilegePackingFastCheck, PrivilegePackingAllowCopyData, PrivilegePackingAllowEditQuantity, PrivilegeAllowPartialInvoice, PrivilegeAllowOrderCancelPacking, PrivilegePackingAllowAddExcessWeight, PrivilegePackingAllowPasteData.

Pré-Romaneio

Tela de bipagem para amarrar pacote ao romaneio (frontend PreCollection, /app/precollection). O operador bipa o código de rastreio do pacote (ou a chave de acesso da NF-e de 44 dígitos) e o código da transportadora; o sistema localiza o romaneio aberto correspondente (ou cria um novo) e amarra o item.

Método	Rota	Função	Descrição
GET	/orders/package	packageList	Lista pacotes com pedido, transportadora, rastreio, status do pedido/pacote, CD e romaneio atual. Restrito aos CDs habilitados ao usuário. Filtro nullCollection=1 traz apenas pacotes ainda sem romaneio.
POST	/fulfillment/packing/collection-list/order	orderFulfillmentCarrierCollectionListOrderPost	Amarra pacote (ou pedido inteiro, conforme PackagesOnOrdersCarrierCollectionList) a um romaneio em aberto, criando-o se necessário. Atualiza status do pedido para 6 (Aguardando expedição) quando vinha de 22 (Aguardando romaneio) e grava OrderEvent no histórico. Querystring NoInvoke=1 evita o lambda.invoke OrderGet final.

Modos controlados por parâmetros de empresa em Logística (WMS) → Expedição:

• PackagesOnOrdersCarrierCollectionList — desligado: amarra pedido inteiro; ligado: amarra pacote individual.
• AllowMultipleOrdersCarrierCollectionListPerOrder — no modo por pacote, permite pacotes do mesmo pedido em romaneios diferentes.
• OneCollectionListPerWorker — cria um romaneio aberto por combinação transportadora + CD + operador logado (em vez de apenas transportadora + CD).

Romaneio

Tela de acompanhamento, fechamento, finalização e assinatura do romaneio (frontend CollectionList, /app/collectionlist, módulo 57). Os romaneios chegam aqui já criados pelo Pré-Romaneio ou pelo Packing; esta tela controla o ciclo de vida deles até a retirada pela transportadora. Status (TypeStatusOrdersCarrierCollectionList): 1 Aberto · 2 Fechado · 3 Finalizado.

Método	Rota	Função	Descrição
GET	/fulfillment/packing/collection-list	orderFulfillmentCarrierCollectionListList	Lista romaneios com filtros (status CSV, intervalo de datas em RecordTimestampEnd, código, transportadora, CD, operador). Aplica ACL de CD do usuário. Anexos FileName1..5 retornados como URLs pré-assinadas do S3 (validade 48 h). Limite 500.
GET	/fulfillment/packing/collection-list/{id}	orderFulfillmentCarrierCollectionListGet	Detalhe com Orders (pedidos/volumes) e PedingPackages (volumes do mesmo pedido em outros romaneios — usado para avisar sobre split ao fechar). Substitui cabeçalho pelo faturador quando ShowCompanyInvoiceCarrierCollection=1.
POST	/fulfillment/packing/collection-list	orderFulfillmentCarrierCollectionListPost	Cria romaneio vazio em status 1 para um IDCarrier. Caso de uso raro — a maioria é criada pelo OrderPost (Pré-Romaneio) na primeira bipagem.
PUT	/fulfillment/packing/collection-list/{id}	orderFulfillmentCarrierCollectionListPut	Troca a transportadora do romaneio inteiro. Atualiza Orders.IDCarrier de todos os pedidos e zera IntegrationEdiCarrier. Grava OrderEvent IDEvent=31 em cada pedido. Bloqueado se já assinado.
POST	/fulfillment/packing/collection-list/{id}/close	orderFulfillmentCarrierCollectionListClosePost	Status 1 → 2. Quando PackagesOnOrdersCarrierCollectionList=1 e AllowMultipleOrdersCarrierCollectionListPerOrder=0, valida que não há split de pacotes em outros romaneios — bloqueia com lista dos pedidos pendentes.
POST	/fulfillment/packing/collection-list/{id}/open	orderFulfillmentCarrierCollectionListOpenPost	Status 2 → 1. Bloqueado se status atual é 3 (Finalizado não reabre).
POST	/fulfillment/packing/collection-list/{id}/finish	orderFulfillmentCarrierCollectionListFinishPost	Despacha o romaneio: status → 3, grava RecordTimestampEnd=NOW(), move Orders.IDStatusOrder para 7 (Enviado) ou 17 (Retirada, para IDCarrierType IN (30, 32)), define Packages.IDStatusPackage=1 + ShippingDate=NOW(), normaliza StockKeepingUnitMovement. Grava OrderEvent IDEvent=4 ou 46.
POST	/fulfillment/packing/collection-list/{id}/file	orderFulfillmentCarrierCollectionListFilePost	Salva assinatura do motorista. Sobe imagem da assinatura, anexos (até 3 fotos) e PDF do romaneio no S3 OrdersCarrierCollectionListFiles/. Grava SigningRecordTimestamp. Se AutoSendEmailToCarrier=1 e a transportadora tem CarrierCollectionListEmail, envia PDF por e-mail (SES ou SMTP IDTypeCompanyIntegration=51). Bloqueia toda edição posterior do romaneio.
POST	/fulfillment/packing/collection-list/{id}/merge	orderFulfillmentCarrierCollectionListMergePost	Mescla romaneios de origem dentro do destino. Destino + origens precisam estar em status 3, não assinados, mesma transportadora e mesma empresa. Origens são deletadas após migração de Orders/Packages. Não publicado em produção (handler existe mas sem rota em routes.json).
PUT	/fulfillment/packing/collection-list/{id}/order	orderFulfillmentCarrierCollectionListOrderPut	Remove pacotes específicos do romaneio (IDPackageArray) e reatribui transportadora aos pedidos. Os pedidos voltam para IDStatusOrder=22 (Aguardando expedição) com a nova IDCarrier. Bloqueado se romaneio já assinado.

Parametrizações (grupo Logística (WMS) → Expedição) que afetam este conjunto:

• PackagesOnOrdersCarrierCollectionList — modo por pacote vs. pedido.
• AllowMultipleOrdersCarrierCollectionListPerOrder — permite split de pacotes em romaneios distintos (desabilitado, o close bloqueia o split).
• OneCollectionListPerWorker — afeta o OrderPost (Pré-Romaneio), não este conjunto diretamente, mas é o que decide quantos romaneios aparecem em paralelo aqui.
• AutoSendEmailToCarrier + CCEmailsAutoSendEmailToCarrier — envio automático de PDF para a transportadora após assinatura.
• ShowCompanyInvoiceCarrierCollection — cabeçalho do PDF usa faturador em vez da empresa de venda.
• CompleteInfoCollectionList — folha impressa com 9 colunas (cidade, estado, valor, peso) em vez das 6 compactas. Esta é uma parametrização puramente de UI — os endpoints não a consomem.
• BeepOrdersCarrierCollectionList — exibe campo de bipagem do código do romaneio no topo da tela. UI-only, não afeta endpoints.
• IgnorePickingList — desliga a criação automática de romaneio ao final do packing. Afeta o fluxo upstream, não esses endpoints.

Privilégios (TypeUserPrivilege):

• PrivilegeCollectionListView (id 249, módulo 57) — acesso a esta tela e às ações de fechar, conferir, finalizar, assinar e imprimir.
• PrivilegeOrdersCarrierCollectionListFastCheck (id 637, módulo 57) — conferência rápida (F2) sem bipagem individual.
• PrivilegeCollectionChangeFinish (id 699, módulo 134 — Pré-Romaneio compartilhado) — alterar transportadora ou remover pacote de romaneio Finalizado.

Retirada em Mãos

A tela reaproveita o componente da tela de Pedidos com o filtro IDStatusOrder=17&Budget=0&SkuView=0 aplicado em todas as chamadas — ou seja, é uma "fila" de pedidos cujo status é Aguardando retirada (17) e que serão entregues em mãos ao cliente no balcão. Usa os mesmos endpoints de pedidos (/orders, /orders/{idorder}, etc.) restritos a esse status.

Característica	Pedidos	Retirada em Mãos
Rota frontend	/app/order	/app/orderwithdraw
Filtro nos endpoints	(todos)	IDStatusOrder=17&Budget=0&SkuView=0
Ação exclusiva	—	Assinar (comprovante de entrega)
Privilégios	PrivilegeOrder*	PrivilegeOrderWithdraw*

A ação Assinar abre um modal de comprovante de entrega que captura nome/documento de quem retira, assinatura digital (canvas), comentários e até 3 fotos de documento. Ao salvar, dispara:

Método	Rota	Função	Descrição
POST	/orders/{idorder}/file?IDTypeOrderFile=1	orderFilePost	Anexa o comprovante de retirada (assinatura PNG + dados do cliente + até 3 fotos) ao pedido.

A documentação detalhada dos demais endpoints está sob a tag Pedidos (a documentar em rodada futura). Os privilégios exclusivos desta tela estão na seção do FAQ correspondente.

Lotes e Endereços SKUs

Método	Rota	Função	Descrição
GET	/sku/batch	skuBatchList	Lista lotes (SKU × endereço) com saldo, validade, fabricação, imagem.
POST	/sku/batch/{idsku}	skuBatchPost	Cria lote no SKU em endereço específico.
PUT	/sku/batch/{idsku}	skuBatchPut (variante)	Atualiza lote com id no body.
PUT	/sku/batch/{idsku}/{idbatch}	skuBatchPut	Atualiza lote (validade, fabricação, endereço, comentário, padrão).
DELETE	/sku/batch/{idsku}/{idbatch}	skuBatchDelete	Exclui lote (bloqueado quando há saldo).

Ressuprimento

Método	Rota	Função	Descrição
GET	/sku/resupply	skuResupplyList	Lista ressuprimentos (com totais agregados).
POST	/sku/resupply	skuResupplyPost	Cria ressuprimento manual ou automático por pedido.
GET	/sku/resupply/{idstockkeepingunitresupplylist}	skuResupplyGet	Detalha ressuprimento.
PUT	/sku/resupply/{idstockkeepingunitresupplylist}	skuResupplyPut	Atualiza status, modalidade, prioridade, colaborador.
DELETE	/sku/resupply/{idstockkeepingunitresupplylist}	skuResupplyDelete	Exclui (bloqueado quando há itens pendentes).
POST	/sku/resupply/{idstockkeepingunitresupplylist}/merge	skuResupplyMergePost	Consolida vários ressuprimentos em um.
POST	/sku/resupply/{idstockkeepingunitresupplylist}/sku	skuResupplySkuPost	Adiciona item ao ressuprimento.
PUT	/sku/resupply/{idstockkeepingunitresupplylist}/sku/{idstockkeepingunitresupply}	skuResupplySkuPut	Atualiza item (quantidade, endereço destino, conclusão).
DELETE	/sku/resupply/{idstockkeepingunitresupplylist}/sku/{idstockkeepingunitresupply}	skuResupplySkuDelete	Remove item do ressuprimento.
GET	/type/sku/resupply	typeSkuRessuply	Lista tipos (Picking / Pulmão / Recebimento).
GET	/type/sku/resupply/status	typeSkuResuplyStatusList	Lista status (Aberto / Iniciado / Finalizado / Cancelado).

Estoque (/app/skustock)

Método	Rota	Função	Descrição
GET	/sku/balance	skuWareHouseBalanceList	Saldo consolidado por SKU × armazém com colunas QtyAvailable, QtyReserved, QtyProduction, QtyHandling, QtyOnStock (calculada pelo handler como soma das três anteriores), QtyBuyOrdem, QtyToReceipt e valor (InventoryValue, CostAverage) regido por UseCostFromCostSet. Aceita filtros amplos (canal, marca, fornecedor, tipo de armazém) e o filtro SinceDateLastRecordModification para integrações incrementais. Paginação de 400.

Inventário (legacy — /app/inventory)

Método	Rota	Função	Descrição
GET	/sku/inventory	skuInventoryList	Lista histórico de ajustes de saldo lançados pela tela legacy (uma linha por ajuste, com SKU, lote, armazém, quantidade contada, comentário, usuário e data). Paginação de 2000.
POST	/sku/inventory	skuInventoryPost	Lança array de ajustes — compara QuantityInventory contra o saldo do lote (ou contra o saldo disponível do SKU quando IDMovementType=3), gera movimentações de entrada/saída pela diferença, aplica custo (CostSet quando UseCostFromCostSet=1, senão CostAverage; quando zero, CostLastPurchase) e publica SkuBalanceAdjust na fila webhook.fifo. Itens inválidos não interrompem o processamento — vão para tempError.

Inventário (/app/sku/inventory)

Método	Rota	Função	Descrição
GET	/sku/inventory-summary	skuInventorySummaryList	Lista inventários da empresa com filtros por status, CD, armazém, data, código e colaborador.
POST	/sku/inventory-summary	skuInventorySummaryPost	Cria inventário (Endereço / SKU / Livre / Auditoria) e devolve o detalhe.
GET	/sku/inventory-summary/{IDStockKeepingUnitInventorySummary}	skuInventorySummaryGet	Detalha inventário com itens contados, fila de SKUs e fila de endereços (ordenada por trajeto serpentino).
PUT	/sku/inventory-summary/{IDStockKeepingUnitInventorySummary}	skuInventorySummaryPut	Encerra conferência (1ª / 2ª / 3ª) ou atribui colaborador.
DELETE	/sku/inventory-summary/{IDStockKeepingUnitInventorySummary}	skuInventorySummaryDelete	Cancela o inventário (sem gerar ajuste).
POST	/sku/inventory-summary/{IDStockKeepingUnitInventorySummary}/finish	skuInventorySummaryFinishPost	Finaliza o inventário e gera as entradas/saídas em StockKeepingUnitMovement.
POST	/sku/inventory-summary/{IDStockKeepingUnitInventorySummary}/sku	skuInventorySummarySkuPost	Adiciona SKU/endereço à fila ou lança quantidade contada (controlado por IDTypeQueue).
DELETE	/sku/inventory-summary/{IDStockKeepingUnitInventorySummary}/sku	skuInventorySummaryQueueDelete	Remove SKU ou endereço da fila de contagem.
PUT	/sku/inventory-summary/{IDStockKeepingUnitInventorySummary}/sku/{IDStockKeepingUnitInventoryItems}	skuInventorySummarySkuPut	Atualiza a quantidade contada de um item (conferência ativa decidida pelo status).
DELETE	/sku/inventory-summary/{IDStockKeepingUnitInventorySummary}/sku/{IDStockKeepingUnitInventoryItems}	skuInventorySummarySkuDelete	Remove uma linha de item lançada.

Agendamento

Método	Rota	Função	Descrição
GET	/purchase/schedule	purchaseScheduleList	Lista agendamentos com dados do recebimento, NF e status calculado dinamicamente.
POST	/purchase/schedule	purchaseSchedulePost	Cria agendamento (com ou sem recebimento amarrado).
PUT	/purchase/schedule/{idstockkeepingunitpurchaseschedule}	purchaseSchedulePut	Atualiza horário, observações ou recebimento.
DELETE	/purchase/schedule/{idstockkeepingunitpurchaseschedule}	purchaseScheduleDelete	Exclui agendamento.

Configuração Agendamento

Método	Rota	Função	Descrição
GET	/purchase/schedule/config	purchaseScheduleConfigList	Lista configurações de agenda de recebimento por CD (com quadro de horários da semana).
POST	/purchase/schedule/config	purchaseScheduleConfigPost	Cria configuração para um CD (regra: 1 CD = 1 configuração).
PUT	/purchase/schedule/config/{idstockkeepingunitpurchasescheduleconfig}	purchaseScheduleConfigPut	Atualiza parcialmente; timetable como [] apaga horários, array preenchido substitui em bloco.
DELETE	/purchase/schedule/config/{idstockkeepingunitpurchasescheduleconfig}	purchaseScheduleConfigDelete	Exclusão física (faixas de horário caem em cascata).

Configuração Picking List

Método	Rota	Função	Descrição
GET	/fulfillment/picking/configuration	orderFulfillmentPickingConfigurationList	Lista configurações de geração de picking list.
POST	/fulfillment/picking/configuration	orderFulfillmentPickingConfigurationPost	Cria uma configuração (nome único, janela horária, filtros).
PUT	/fulfillment/picking/configuration/{idpickinglistconfiguration}	orderFulfillmentPickingConfigurationPut	Atualiza parcialmente (limpa CSV ao enviar ""/[]).
DELETE	/fulfillment/picking/configuration/{idpickinglistconfiguration}	orderFulfillmentPickingConfigurationDelete	Exclusão física (sem regra de bloqueio).

Endereços

Método	Rota	Função	Descrição
GET	/sku/location	skuLocationList	Lista endereços (modo cadastro com OnlyLocation=1 ou modo legado com lote/saldo).
POST	/sku/location	skuLocationPost	Cria endereço(s) — individual ou em massa por faixa de módulo/coluna/nível (modo WMS).
PUT	/sku/location/{idstockkeepingunitlocation}	skuLocationPut	Atualiza dados do endereço (bloqueia troca de armazém quando há movimento).
DELETE	/sku/location/{idstockkeepingunitlocation}	skuLocationDelete	Exclusão física (bloqueada quando há lote/SKU vinculado).
GET	/sku/location/{idstockkeepingunitlocation}/label	purchaseLabelGet	Gera o ZPL da etiqueta do endereço.

Gestão Colaboradores

Método	Rota	Função	Descrição
GET	/user/workingday	userWorkingDayList	Lista colaboradores com escala, funções, supervisor, grupos e categorias de endereço.
POST	/user/workingday	userWorkingDayPost	Cadastra colaborador a partir de um usuário existente (1 por usuário por empresa).
PUT	/user/workingday/{idworkingday}	userWorkingDayPut	Atualiza parcialmente (proíbe colaborador ser próprio supervisor).
DELETE	/user/workingday/{idworkingday}	userWorkingDayDelete	Exclusão física (bloqueada quando o colaborador é supervisor de outro).

Simulação Frete

Método	Rota	Função	Descrição
GET	/carrier/quotation	carrierQuotationList	Lista simulações já rodadas (até 5000 por página).
POST	/carrier/quotation	carrierQuotationPost (php)	Roda uma simulação para CEP destino + lista de volumes/produtos; persiste cabeçalho e linhas por transportadora.
GET	/carrier/quotation/{idcarrierquotation}	carrierQuotationGet	Detalha uma simulação com todas as linhas por transportadora (Attended, prazo, componentes do preço, total).

Contas a Pagar

Método	Rota	Função	Descrição
GET	/accounts/payable	accountsPayableList	Lista contas a pagar com totais já calculados.
POST	/accounts/payable	accountsPayablePost	Cria contas a pagar, com suporte a recorrência e retenção.
POST	/accounts/payable/file	accountsPayableFileDownload	Gera ZIP com arquivos de contas selecionadas e envia por e-mail.
GET	/accounts/payable/{idaccountpayable}	accountsPayableGet	Detalha uma conta a pagar (com arquivos, pagamentos, histórico e contas filhas).
PUT	/accounts/payable/{idaccountpayable}	accountsPayablePut	Atualiza parcialmente uma conta a pagar.
DELETE	/accounts/payable/{idaccountpayable}	accountsPayableDelete	Exclui uma conta a pagar, com regras de bloqueio.
POST	/accounts/payable/{idaccountpayable}/bank-integration	accountsPayableBankPaymentPost	Envia a conta para pagamento via integração bancária.
POST	/accounts/payable/{idaccountpayable}/cost-center	accountsPayableReceivableCostCenterPost	Define/substitui o rateio de centros de custo.
POST	/accounts/payable/{idaccountpayable}/file	accountsFilePost	Anexa um arquivo à conta a pagar.
GET	/accounts/payable/{idaccountpayable}/file/{idfile}	accountsFileGet	Baixa um arquivo anexado.
DELETE	/accounts/payable/{idaccountpayable}/file/{idfile}	accountsFileDelete	Remove um arquivo anexado.
POST	/accounts/payable/{idaccountpayable}/payment	accountsPayablePaymentPost	Lança um pagamento na conta a pagar.
DELETE	/accounts/payable/{idaccountpayable}/payment/{idaccountpayment}	accountsPayablePaymentDelete	Cancela um pagamento lançado.

Contas a Receber

Método	Rota	Função	Descrição
GET	/accounts/receivable	accountsReceivableList	Lista contas a receber com totais já calculados.
POST	/accounts/receivable	accountsReceivablePost	Cria uma conta a receber.
GET	/accounts/receivable/conciliation	accountsReceivableConciliationList	Lista conciliações de adquirentes (com modo de auditoria de taxas).
PUT	/accounts/receivable/conciliation/{idaccountspayablereceivableconciliation}	accountsReceivableConciliationPut	Atualiza observações de uma conciliação.
GET	/accounts/receivable/marketplace-conciliation	accountsReceivableMarketplaceConciliationList	Lista conciliações de marketplace, com decomposição de taxas e contas internas vinculadas.
GET	/accounts/receivable/{idaccountreceivable}	accountsReceivableGet	Detalha uma conta a receber.
PUT	/accounts/receivable/{idaccountreceivable}	accountsReceivablePut	Atualiza parcialmente uma conta a receber.
DELETE	/accounts/receivable/{idaccountreceivable}	accountsPayableDelete	Exclui uma conta a receber (mesmo handler do payable, com regras de bloqueio).
POST	/accounts/receivable/{idaccountreceivable}/cost-center	accountsPayableReceivableCostCenterPost	Define/substitui o rateio de centros de custo.
POST	/accounts/receivable/{idaccountreceivable}/payment	accountsPayablePaymentPost	Lança um recebimento, incluindo vínculo com conciliações adquirente/marketplace.
DELETE	/accounts/receivable/{idaccountreceivable}/payment/{idaccountpayment}	accountsPayablePaymentDelete	Cancela um recebimento lançado.

Marcas

Método	Rota	Função	Descrição
GET	/brand	brandList	Lista marcas ativas, com busca textual opcional.
POST	/brand	brandPost	Cadastra uma marca.
GET	/brand/{idbrand}	brandGet	Detalha uma marca.
PUT	/brand/{idbrand}	brandPut	Atualiza parcialmente uma marca.
DELETE	/brand/{idbrand}	brandDelete	Inativa uma marca (bloqueia quando há produtos vinculados).

Fornecedores

Método	Rota	Função	Descrição
GET	/supplier	supplierList	Lista fornecedores e transportadoras ativos.
POST	/supplier	supplierPost	Cadastra um fornecedor (CNPJ é auto-preenchido pela Receita).
GET	/supplier/{idsupplier}	supplierGet	Detalha um fornecedor ou transportadora.
PUT	/supplier/{idsupplier}	supplierPut	Atualiza um fornecedor (atualização parcial).
DELETE	/supplier/{idsupplier}	supplierDelete	Inativa um fornecedor; preserva histórico financeiro.
POST	/supplier/{idsupplier}/contact	supplierContactPost	Adiciona um contato ao fornecedor.
PUT	/supplier/{idsupplier}/contact/{idsupplierscontact}	supplierContactPut	Atualiza um contato.
DELETE	/supplier/{idsupplier}/contact/{idsupplierscontact}	supplierContactDelete	Remove um contato.
POST	/supplier/{idsupplier}/cost-center	supplierCostCenterPost	Define o rateio padrão de centros de custo do fornecedor.
POST	/supplier/{idsupplier}/logo	supplierLogoPost	Sobe ou troca o logotipo (multipart ou URL).

Categorias de Fornecedores

Método	Rota	Função	Descrição
GET	/supplier/category	supplierCategoryList	Lista categorias de fornecedor ativas, com tipo já resolvido.
POST	/supplier/category	supplierCategoryPost	Cadastra uma categoria.
PUT	/supplier/category/{idsuppliercategory}	supplierCategoryPut	Atualiza descrição e tipo de uma categoria.
DELETE	/supplier/category/{idsuppliercategory}	supplierCategoryDelete	Inativa uma categoria (bloqueia quando há fornecedores ativos vinculados).

Tipo Pagamento

Método	Rota	Função	Descrição
GET	/type/order/payment	typeOrderPaymentList	Lista tipos de pagamento ativos da empresa.
POST	/type/order/payment	typeOrderPaymentPost	Cadastra um tipo de pagamento.
PUT	/type/order/payment/{idtypepayment}	typeOrderPaymentPut	Atualiza um tipo de pagamento (atualização total).
DELETE	/type/order/payment/{idtypepayment}	typeOrderPaymentDelete	Inativa um tipo de pagamento.
GET	/type/order/payment/{idtypepayment}/rate	typeOrderPaymentRateGet	Lista taxas adquirentes vinculadas ao tipo.
POST	/type/order/payment/{idtypepayment}/rate	typeOrderPaymentRatePost	Cadastra uma taxa adquirente (MDR + AR ou fixa).
PUT	/type/order/payment/{idtypepayment}/rate/{idtypepaymentrate}	typeOrderPaymentRatePut	Atualiza uma taxa adquirente.
DELETE	/type/order/payment/{idtypepayment}/rate/{idtypepaymentrate}	typeOrderPaymentRateDelete	Exclui uma taxa adquirente (exclusão física).

Centro de Custo

Método	Rota	Função	Descrição
GET	/type/account/cost-center	typeAccountCostCenterList	Lista centros de custo ativos da empresa.
POST	/type/account/cost-center	typeAccountCostCenterPost	Cadastra um centro de custo.
PUT	/type/account/cost-center/{idtypecostcenter}	typeAccountCostCenterPut	Atualiza descrição e código externo de um centro.
DELETE	/type/account/cost-center/{idtypecostcenter}	typeAccountCostCenterDelete	Inativa um centro de custo.

Etiquetas

Método	Rota	Função	Descrição
GET	/company/label	typeCompanyLabelList	Lista modelos de etiqueta cadastrados pela empresa.
POST	/company/label	typeCompanyLabelPost	Cadastra um modelo (Canvas ou ZPL bruto).
PUT	/company/label/{idcompanylabel}	typeCompanyLabelPut	Atualiza um modelo (parcial).
DELETE	/company/label/{idcompanylabel}	typeCompanyLabelDelete	Exclui um modelo (exclusão física).

Status Pedido

Método	Rota	Função	Descrição
GET	/type/order/status	typeOrderStatusList	Lista os status de pedido configurados para a empresa (nome local + cor + descrição padrão).
PUT	/type/order/status/{idstatusorder}	typeOrderStatusPut	Atualiza o nome local e a cor de um status (lista de status do sistema é fixa — sem POST/DELETE).

Política Comercial

Método	Rota	Função	Descrição
GET	/company/sales-policy	companySalesPolicyGet	Lista políticas comerciais (tabelas de preço) da empresa.
POST	/company/sales-policy	companySalesPolicyPost	Cadastra uma política (Normal, Custo médio ou Relativa a outra política).
PUT	/company/sales-policy/{idcompanysalespolicy}	companySalesPolicyPut	Atualiza uma política (parcial; políticas Relativas disparam recálculo assíncrono dos preços).
DELETE	/company/sales-policy/{idcompanysalespolicy}	companySalesPolicyDelete	Exclui uma política (bloqueia quando padrão, com preços, de/para, tipos de pedido ou promoções PDV vinculados).

Modalidade Transportadora

Método	Rota	Função	Descrição
GET	/carrier/modal	carrierModalList	Lista modalidades de transportadora da empresa.
POST	/carrier/modal	carrierModalPost	Cadastra uma modalidade (nome único por empresa).
PUT	/carrier/modal/{idcarriermodal}	carrierModalPut	Atualiza o nome da modalidade.
DELETE	/carrier/modal/{idcarriermodal}	carrierModalDelete	Exclui uma modalidade (bloqueia quando há transportadora ou hub vinculados).

Minhas Empresas

Método	Rota	Função	Descrição
GET	/company	companyGet	Detalha a empresa autenticada (com inscrições estaduais e créditos do Simples).
PUT	/company	companyPut	Atualiza dados cadastrais e configurações fiscais; gera log e flush de cache.
GET	/company/branch	companyBranchGet	Lista a empresa-matriz e suas filiais.
POST	/company/company-logo	companyLogoPost	Sobe ou troca o logotipo da empresa (multipart ou URL).
POST	/company/state-inscription	companyStateInscriptionPost	Cadastra uma inscrição estadual (validada por algoritmo oficial).
PUT	/company/state-inscription/{idstateinscription}	companyStateInscriptionPut	Atualiza uma inscrição estadual.
DELETE	/company/state-inscription/{idstateinscription}	companyStateInscriptionDelete	Remove uma inscrição estadual.
POST	/company/simples-cred	companySimplesCredPost	Cadastra créditos do Simples Nacional para um período.
PUT	/company/simples-cred/{idcompanysimplescred}	companySimplesCredPut	Atualiza créditos do Simples.
DELETE	/company/simples-cred/{idcompanysimplescred}	companySimplesCredDelete	Remove créditos do Simples.
POST	/company/certificate	companyCertificatePost (php)	Importa o certificado digital A1 (PFX + senha).

Relatórios

Método	Rota	Função	Descrição
GET	/company/report	companyReportList	Catálogo de relatórios disponíveis para a empresa (com filtros por relatório).
GET	/user/report	userReportList	Histórico de relatórios gerados pelo usuário autenticado.
POST	/user/report	userReportPost	Enfileira a geração de um relatório (assíncrono via SQS reports.fifo).

Comissão

Método	Rota	Função	Descrição
POST	/user/{iduser}/comission	userComissionPost	Adiciona uma regra de comissão para o vendedor (com vigência, %, limite de desconto, categoria opcional).
PUT	/user/{iduser}/comission/{idsalesmancomission}	userComissionPut	Atualiza uma regra de comissão.
DELETE	/user/{iduser}/comission/{idsalesmancomission}	userComissionDelete	Remove uma regra de comissão (exclusão física).

Usuários

Método	Rota	Função	Descrição
GET	/user	UserList	Lista os usuários da empresa (perfis, último login, status). Comission=1 retorna a apuração de comissões no período.
POST	/user	UserPost	Cria um usuário (e-mail e/ou documento). Reaproveita registro de pessoa já existente em outra conta.
GET	/user/{iduser}	UserGet	Detalha o usuário (cargos, perfis, comissão, vínculos de filial/CD/categoria fornecedor, logs de alteração e de acesso).
PUT	/user/{iduser}	UserPut	Atualiza o usuário (parcial). Troca de senha valida a política da empresa; trocar a de outro usuário exige privilégio.
DELETE	/user/{iduser}	UserDelete	Remove o vínculo do usuário com a empresa (o registro global persiste se houver outra conta vinculada).
GET	/user/{iduser}/privilege/privilege-group	iduserPrivilegeGroupGet	Lista os perfis de acesso vinculados ao usuário.
POST	/user/{iduser}/privilege/privilege-group	iduserPrivilegeGroupPost	Substitui o conjunto de perfis de acesso do usuário (lista completa de IDs).
POST	/user/{iduser}/company-invoice	userCompanyInvoicePost	Vincula uma empresa/filial faturadora ao usuário.
DELETE	/user/{iduser}/company-invoice/{idusercompanyinvoice}	userCompanyInvoiceDelete	Remove o vínculo de empresa/filial faturadora.
POST	/user/{iduser}/distribution-center	userCompanyDistributionCenterPost	Vincula um centro de distribuição ao usuário.
DELETE	/user/{iduser}/distribution-center/{idusercompanydistributioncenter}	userCompanyDistributionCenterDelete	Remove o vínculo de centro de distribuição.
POST	/user/{iduser}/supplier-category	userSupplierCategoryPost	Vincula uma categoria de fornecedor ao usuário.
DELETE	/user/{iduser}/supplier-category/{idusersuppliercategory}	userSupplierCategoryDelete	Remove o vínculo de categoria de fornecedor.
POST	/user/{iduser}/image	userImagePost	Define a foto de perfil do usuário (upload de arquivo ou download por URL).
POST	/user/{iduser}/verify	userVerifyPost	Confirma a senha do usuário (reautenticação) e devolve um token temporário.

Histórico Caixa

Método	Rota	Função	Descrição
GET	/store-front/cashier/history	storeFrontCashierHistoryList	Lista sessões de caixa do PDV (StoreFrontCashier), com filtros por caixa, operador, empresa e intervalo de abertura.
GET	/store-front/cashier/history/{idstorefrontcashier}	storeFrontCashierHistoryGet	Extrato detalhado da sessão: pedidos (OrderList), lançamentos bancários (TransactionList) e totais por tipo de pagamento (PaymentSummary).
PUT	/store-front/cashier/history/{idstorefrontcashier}/adjust/{idaccountpayablereceivable}	storeFrontCashierHistoryPut	Ajusta um recebimento da sessão (tipo de pagamento, NSU, TID, parcelas — alteração de parcelas dispara recálculo no worker PHP).

Promoção PDV

Método	Rota	Função	Descrição
GET	/sku/promotion	skuPromotionList	Lista promoções (StockKeepingUnitPromotion) — filtros por tipo, status, nome e dois intervalos de datas (DateFrom e DateTo).
POST	/sku/promotion	skuPromotionPost	Cria uma promoção dos 4 tipos suportados (1 Regular, 2 Compre e Ganhe, 3 Desconto Progressivo, 4 Compre Junto). Cada tipo tem regras de obrigatoriedade próprias. Atualiza cache Redis.
GET	/sku/promotion/{idstockkeepingunitpromotion}	skuPromotionGet	Detalhe completo com vínculos resolvidos (marcas, categorias, produtos, SKUs, faixas progressivas, brindes, tipos de pedido, políticas comerciais).
PUT	/sku/promotion/{idstockkeepingunitpromotion}	skuPromotionPut	Atualiza cabeçalho + sincroniza as listas vinculadas (diff insert/delete). Tipo da promoção é imutável.
DELETE	/sku/promotion/{idstockkeepingunitpromotion}	skuPromotionDelete	Exclusão física se nunca foi usada em pedidos; lógica (status = 0 Excluída) caso contrário, preservando histórico.
GET	/sku/promotion/sku/{idsku}	skuPromotionSkuGet	Lista as promoções vigentes aplicáveis a um SKU (usa cache Redis).
POST	/sku/promotion/order/validate	skuPromotionOrderValidateGet	Aplica as promoções ao carrinho do PDV em tempo real — recalcula preços, monta Promotions[] por item, persiste em StoreFrontCashierOrderTemp.
GET	/type/sku/promotion/type	typeSkuPromotionList	Lista dos tipos de promoção do sistema.
GET	/type/sku/promotion/status	typeSkuPromotionStatusList	Lista dos status possíveis (Excluída, Ativo, Programada, Finalizada, Inativa).

Transações TEF

Método	Rota	Função	Descrição
GET	/store-front/payment	storeFrontPaymentList	Lista transações de pagamento do PDV (StoreFrontCashierPayment) — filtros por caixa, faturador, terminal TEF, TID, autorização, status, datas de criação/cancelamento. Paginação de 2000 itens.
POST	/store-front/cashier/{idbankaccount}/payment	storeFrontPaymentPost (PHP)	Inicia uma cobrança TEF (PayGo/ControlPay), Pix StarkBank ou Pix Pagar.me conforme a integração da conta bancária do caixa.
GET	/store-front/cashier/{idbankaccount}/payment/{idstorefrontcashierpayment}	storeFrontPaymentGet (PHP)	Faz polling síncrono no adquirente (até 60 tentativas, 1s entre elas, 504 ao esgotar) e devolve o status final + TID/AuthId/Receipt/ReceiptBuyer.
DELETE	/store-front/cashier/{idbankaccount}/payment/{idstorefrontcashierpayment}	storeFrontPaymentDelete (PHP)	Cancela transação aprovada. PayGo exige TEFPassword (senha técnica). StarkBank não suporta (Pix só expira). Pagar.me chama CancelPix.
GET	/type/store-front/payment/status	typeStoreFrontPaymentStatus	Lista dos 8 status possíveis da transação (Pendente, Em pagamento, Creditado, Expirado, Cancelamento iniciado, Em cancelamento, Cancelado, Pagamento recusado).

Frente de Caixa

Método	Rota	Função	Descrição
GET	/store-front/cashier	storeFrontCashierList	Lista os caixas do PDV (BankAccount.BankNumber='000') com status (Aberto/Fechado), operador logado e saldo atual. Filtros por faturador e status.
GET	/store-front/cashier/{idbankaccount}	storeFrontCashierGet	Snapshot do caixa: saldo, Income/Outcome/AdjustIn/AdjustOut, PaymentSummary (por tipo), PaymentCategorySummary (por categoria), InvoiceSummary (por modelo NFCe/NFe) + 2 ZPLs (fechamento + resumo fiscal).
POST	/store-front/cashier/{idbankaccount}/open	storeFrontCashierOpenPost	Abre o caixa. Valida senha bcrypt, lock Redis 10s, regras anti-concorrência, configurações fiscais (com CheckConfigCashierOpen=1). Gera ajuste se InitialBalance diverge.
POST	/store-front/cashier/{idbankaccount}/close	storeFrontCashierClosePost	Fecha o caixa. Valida senha, gera ajuste de fechamento se FinalBalance diverge, grava CommentsClose.
POST	/store-front/cashier/{idbankaccount}/adjust	storeFrontCashierAdjustPost	Sangria (Type=2) ou reforço (Type=1). Sangria não pode exceder saldo. Retorna ZPL do recibo (base64+cp850).
GET	/store-front/cashier/{idbankaccount}/order-temp	storeFrontCashierOrderTempGet	Lista os rascunhos de pedido (StoreFrontCashierOrderTemp) salvos automaticamente no caixa pelo motor de promoções.
DELETE	/store-front/cashier/{idbankaccount}/order-temp/{idstorefrontcashierordertemp}	storeFrontCashierOrderTempDelete	Apaga um rascunho de pedido.

---

GET /accounts/bank-account

bankAccountList · autenticado

Retorna as contas bancárias ativas da empresa. Cada item traz o saldo atual e o saldo previsto até uma data futura. Aceita filtros opcionais por faturador e número do banco.

Query params

Nome	Tipo	Obrigatório	Descrição
DateForecast	string (date)	não	Data limite (inclusive) para BalanceForecast. Default: data atual.
IDCompanyInvoice	integer	não	Filtra contas cujo faturador corresponde a este id de empresa.
BankNumber	string (≤3)	não	Filtra pelo código Febraban do banco.

Resposta 200 — array de objetos do schema BankAccountListItem (BankAccount.* + extras):

[
  {
    "IDBankAccount": 1234,
    "Bank": "Banco do Brasil",
    "BankNumber": "001",
    "BankRouting": "1234-5",
    "AccountNumber": "67890",
    "AccountNumberDigit": "0",
    "MainIncome": 1,
    "MainPayment": 1,
    "Status": 1,
    "IDCompany": 99,
    "IDCompanyInvoice": 99,
    "IDCompanyIntegration": null,
    "TefTerminal": null,
    "IDTypeOrder": null,
    "RecordTimestamp": "2024-03-12T10:30:00Z",
    "AccountName": "exemplo",
    "AccountNameInvoice": "exemploInvoice",
    "CompanyNameCorporateNameInvoice": "Exemplo Faturador LTDA",
    "CompanyIntegrationName": null,
    "TypeOrder": null,
    "CompanyIntegration": null,
    "Balance": 12500.50,
    "BalanceForecast": 18250.30
  }
]

Erros

Status	Quando
400	Configuração de empresa inválida no contexto. [BadRequest] - Erro na configuração da empresa
500	Erro interno (prefixo Error:).

---

POST /accounts/payable

accountsPayablePost · autenticado

Cria uma ou mais contas a pagar. Suporta recorrência mensal, semanal ou personalizada, tratamento de feriado e fim de semana, retenção de impostos (que gera contas filhas e abate o valor da conta principal) e replicação automática dos centros de custo do fornecedor. A criação é registrada no histórico para auditoria. A resposta traz as contas recém-criadas no mesmo formato da listagem.

Request body — AccountsPayableCreate

Campo	Tipo	Obrigatório	Descrição
Comments	string (≤2000)	não	Observações.
DateCompetence	string (date)	não	Data de competência. String vazia é tratada como ausente.
DateDocument	string (date)	não	Data do documento. String vazia é tratada como ausente.
DateDue	string (date)	sim	Data de vencimento.
DocumentNumber	string (≤200)	não	Número do documento.
IDSupplier	integer	condicional	Identificador do fornecedor. Não pode vir junto com IDConsumer.
IDConsumer	integer	condicional	Identificador do cliente. Não pode vir junto com IDSupplier.
IDTypePayment	integer	não	Identificador do tipo de pagamento. Validado contra os tipos cadastrados para a empresa.
IDTypeDocument	integer	sim	Identificador do tipo de documento. Sem ele a operação aborta com Tipo documento não existe.
IDTypeAccountPayableReceivable	integer	sim	Identificador do plano de contas. Aborta com Plano de contas não existe se faltar.
Scheduled	integer (0/1)	não	Indica se a conta está agendada. Padrão 0.
Value	number	sim	Valor do título.
IDBankAccountForecast	integer	não	Se omitido e a empresa tem 1 conta bancária cadastrada, ela é preenchida automaticamente.
BankSlipBarCode	string (≤2000)	não	Código de barras do boleto.
IDOrder	integer	não	Identificador do pedido associado. Verificado contra os pedidos cadastrados.
IDCompanyInvoice	integer	não	Identificador da empresa faturadora. Padrão: a empresa autenticada.
ValueDiscount	number	não	Valor de desconto.
ValueInterest	number	não	Valor de juros.
ValuePenalty	number	não	Valor de multa.
Taxes	array	não	Lista de retenções (ver schema TaxRetentionItem).
Holiday	integer (1/2)	não	Como tratar feriado/fim de semana: 1=antecipar, 2=postergar.
PeriodType	integer (1/2/3)	não	Tipo de recorrência: 1=mensal, 2=semanal, 3=personalizado.
QuantityRepeat	integer	condicional	Obrigatório quando PeriodType for informado. Número total de ocorrências.
PeriodTypeValue	integer	condicional	PeriodType=1: 1-31 (dia do mês). =2: 0-6 (dia da semana). =3: intervalo em dias.

Item de Taxes[] — TaxRetentionItem

Campo	Tipo	Obrigatório
IDSupplier	integer	sim
Value	number	sim
DateDue	string (date)	sim

A soma de Taxes[*].Value é abatida do Value da conta principal e não pode ultrapassá-lo.

Resposta 200 — array com as contas recém-criadas. O formato exato dos itens não está confirmado neste piloto (a operação de listagem ainda não foi documentada). Trate como array<object> por enquanto.

Erros

Status	Quando
400	Várias condições — Fornecedor ou cliente precisa ser preenchido (apenas um dos dois); Empresa não existe; Fornecedor/Cliente/Faturador/Pedido/Conta bancária/Type Payment/Tipo documento/Plano de contas não existe; Fornecedor retenção é obrigatório / Valor retenção é obrigatório / Data vencimento retenção é obrigatória; Valor retenção superior ao valor do título; Fornecedores(s) retenção imposto não localizado(s): <ids>; regras de recorrência (Dia do mês precisa ser entre 1 e 31, Dia do semana precisa ser entre 0 e 6, Precisa enviar o intervalo, Precisa enviar o tipo de frequencia).
500	Erro interno (prefixo Error:).

---

GET /accounts/payable/{idaccountpayable}

accountsPayableGet · autenticado

Retorna a conta a pagar completa: dados próprios, status, fornecedor ou cliente, tipo de documento, tipo de pagamento, plano de contas, total da nota fiscal de origem, indicações de quais tipos de arquivo estão anexados, lista de pagamentos e arquivos, GNREs, histórico de alterações, centros de custo rateados e as contas filhas geradas por retenção de impostos.

⚠ Atenção: quando o id não existe ou a conta pertence a outra empresa, a resposta é 200 com [] (array vazio) — este endpoint não emite erro para "não encontrado".

Path params

Nome	Tipo	Obrigatório	Descrição
idaccountpayable	integer	sim	Identificador da conta a pagar.

Resposta 200 — array com 0 ou 1 elemento do schema AccountsPayableDetail:

[
  {
    "IDAccountPayableReceivable": 17,
    "IDTypeAccount": 1,
    "DateDue": "2026-05-30",
    "DateCompetence": "2026-05-01",
    "DateDocument": "2026-04-15",
    "DocumentNumber": "NF-123",
    "Comments": "exemplo",
    "Value": 1000.00,
    "ValueDiscount": 0,
    "ValueInterest": 0,
    "ValuePenalty": 0,
    "ValueTotal": 1000.00,
    "Scheduled": 0,
    "Forecast": 0,
    "IDSupplier": 42,
    "SupplierNameCorporateName": "Fornecedor X",
    "IDConsumer": null,
    "ConsumerNameCorporateName": null,
    "IDTypeAccountPayableReceivable": 7,
    "TypeAccountPaybleDescription": "Aluguel",
    "IDTypeDocument": 1,
    "TypeDocument": "Boleto",
    "IDTypePayment": 2,
    "TypePaymentDescription": "Transferência",
    "IDStatusAccountPayableReceivable": 0,
    "StatusAccountPayableReceivable": "Aberto",
    "IDBankAccountForecast": 1234,
    "Bank": "Banco do Brasil - 67890",
    "BankForecastAccountNumber": "67890",
    "IDCompanyInvoice": 99,
    "AccountNameInvoice": "exemplo",
    "CompanyNameCorporateNameInvoice": "Exemplo LTDA",
    "CompanyIntegration": null,
    "IDOrder": null,
    "IDAccountPayableReceivableMain": null,
    "TotalvNF": null,
    "BankSlipBarCode": null,
    "RecordTimestamp": "2026-04-15T14:00:00Z",
    "DocumentPdf": 1,
    "DocumentXml": 0,
    "DocumentBankSlip": 1,
    "DocumentPayment": 0,
    "Files": [],
    "Payments": [],
    "AccountsPayableReceivableLog": [],
    "AccountsPayableReceivableCostCenter": [],
    "RelatedAccountsPayableReceivable": []
  }
]

Erros

Status	Quando
500	Erro interno (prefixo Error:).

Schemas dos arrays da resposta

Files[] — FileAttachment

Arquivo anexado à conta. Pode representar uma GNRE ou um arquivo comum (PDF, XML, boleto, comprovante). Algumas chaves só aparecem em uma das ramificações.

Campo	Tipo	Obs.
RecordTimestamp	string (date-time)	Data e hora do anexo.
IDFile	integer	Identificador do arquivo. Para GNREs, é igual ao IDGnre.
IDTypeFile	string	Tipo como string. Para GNRE, valor fixo "1".
TypeFile	string	"GNRE" para guia GNRE; nome do tipo cadastrado nos demais.
FileUrl	string	URL completa para download, com token embutido.
IDGnre	integer	Apenas em itens GNRE.
IDAccountPayableReceivable	integer	Apenas em itens que não são GNRE.

Payments[] — BankStatementPayment

Lançamento do extrato bancário vinculado à conta.

Campo	Tipo	Obs.
DateTransactionTimestamp	string (date-time)	Formato ISO 8601 com sufixo Z.
IDBankAccount	integer	Conta bancária do lançamento.
IDBankStatement	integer	Identificador do lançamento.
TransactionDescription	string (≤100) ou null	Descrição da transação.
TransactionDocument	string (≤45) ou null	Documento (TID, NSU).
Value	number	Valor lançado (2 casas decimais).
Bank	string	Nome do banco.

AccountsPayableReceivableLog[] — AccountsPayableLogEntry

Entrada do histórico de alterações da conta, ordenada da mais recente para a mais antiga.

Campo	Tipo	Obs.
RecordTimestamp	string (date-time)	Formato ISO 8601 com sufixo Z.
IDAccountsPayableReceivableLog	integer	Id da entrada.
RecordUserCreated	integer	Id do usuário responsável.
Data	string (≤500) ou null	Resumo da alteração no formato chave: "DE: <valor> PARA: <valor>" (JSON serializado).
Login	string	Login do usuário.

AccountsPayableReceivableCostCenter[] — AccountsPayableCostCenter

Centro de custo associado, com a fração rateada do valor total.

Campo	Tipo	Obs.
IDTypeCostCenter	integer	Identificador do centro.
ValueRatio	number	Fração (4 casas decimais, ex.: 0.3500 = 35%).
TypeCostCenter	string (≤100)	Nome.
ExternalCode	string (≤45) ou null	Código para integração contábil.
Value	number	ValueTotal × ValueRatio, arredondado para 2 casas.

RelatedAccountsPayableReceivable[] — RelatedAccountsPayable

Conta filha gerada por retenção de impostos, com totais já calculados.

Campo	Tipo	Obs.
IDAccountPayableReceivable	integer	Id da conta filha.
DateDue	string (date)	Data de vencimento.
DateDocument	string (date) ou null	Data do documento.
DocumentNumber	string (≤200) ou null	Número do documento.
IDStatusAccountPayableReceivable	integer ou null	Identificador do status.
StatusAccountPayableReceivable	string ou null	Descrição do status.
IDConsumer	integer ou null	Cliente, quando aplicável.
ConsumerNameCorporateName	string ou null	Razão social do cliente.
IDSupplier	integer ou null	Fornecedor, quando aplicável.
SupplierNameCorporateName	string ou null	Razão social do fornecedor.
IDTypeAccount	integer	0=entrada (a receber), 1=saída (a pagar).
TypeAccountPaybleDescription	string ou null	Descrição do plano de contas.
Value	number	Valor base.
ValueDiscount	number	Desconto.
ValueInterest	number	Juros.
ValuePenalty	number	Multa.
ValueTotal	number	Value + ValuePenalty + ValueInterest - ValueDiscount.

---

PUT /accounts/payable/{idaccountpayable}

accountsPayablePut · autenticado

Atualiza a conta a pagar de forma parcial — apenas os campos enviados são alterados. Quando ChangeNextRepeat=1, propaga a alteração para todas as ocorrências futuras da mesma série de recorrência. A diferença campo a campo fica registrada no histórico. A resposta tem o mesmo formato de GET /accounts/payable/{idaccountpayable}.

Path params

Nome	Tipo	Obrigatório	Descrição
idaccountpayable	integer	sim	Identificador da conta a pagar.

Query params

Nome	Tipo	Obrigatório	Descrição
ChangeNextRepeat	integer (1)	não	Quando 1, propaga a alteração para ocorrências futuras da série.

Request body — AccountsPayableUpdate. Todos os campos são opcionais; veja o corpo do POST para a semântica (as mesmas validações são aplicadas aos identificadores informados). Observação: IDBankAccountForecast = "0" é ignorado (não atualiza).

Resposta 200 — mesmo formato do GET /accounts/payable/{idaccountpayable} (AccountsPayableDetail).

Erros

Status	Quando
400	Fornecedor ou cliente precisa ser preenchido (apenas um dos dois); Contas a pagar não existe; Fornecedor/Cliente/Faturador/Tipo pagamento/Conta bancária/Plano de contas não existe.
500	Erro interno (prefixo Error:).

---

DELETE /accounts/payable/{idaccountpayable}

accountsPayableDelete · autenticado

Exclui a conta a pagar e desvincula as GNREs associadas.

Regras:

• Não é possível excluir quando a conta está agendada.
• Não é possível excluir quando já existem pagamentos lançados.
• Quando a conta está vinculada a uma compra e a parametrização Não permitir excluir contas pagar com recebimento da empresa está ativa, a exclusão é bloqueada.
• Quando ChangeNextRepeat=1, também exclui as ocorrências futuras da mesma série de recorrência.
• Quando a conta está atrelada a um pedido ou ordem de serviço, registra o evento no histórico correspondente e devolve a representação atualizada do recurso pai. Caso contrário, devolve a string "sucesso".

Path params

Nome	Tipo	Obrigatório	Descrição
idaccountpayable	integer	sim	Identificador da conta a pagar.

Query params

Nome	Tipo	Obrigatório	Descrição
ChangeNextRepeat	integer (1)	não	Quando 1, também exclui as próximas ocorrências da série.

Resposta 200

• Quando sem pedido nem ordem de serviço associada:

  "sucesso"

• Quando há pedido ou ordem de serviço associada: objeto representando o pedido ou a ordem de serviço atualizada — schema não documentado neste piloto.

Erros

Status	Quando
400	Pagamento não existe; Título esta agendado e não pode ser excluído; Não é possível excluir um contas a pagar atrelado a um recebimento; Contas a pagar já tem pagamento.
500	Erro interno (prefixo Error:).

---

POST /accounts/payable/file

accountsPayableFileDownload · autenticado

Recebe uma lista de ids de contas a pagar, compacta todos os arquivos anexados num .zip, faz upload no S3 e envia o link de download para o e-mail do usuário autenticado. O link tem validade de 2 dias.

Body — JSON com array de ids (duas formas aceitas):

[1, 2, 3]

ou

{ "IDAccountPayableReceivable": [1, 2, 3] }

Resposta 200 — URL assinada do ZIP no S3 (string).

Erros

Status	Quando
400	IDs inválidos; Nenhum arquivo encontrado; Usuário não encontrado; Empresa inválida.

---

POST /accounts/payable/{idaccountpayable}/payment

accountsPayablePaymentPost · autenticado

Registra um pagamento na conta a pagar e atualiza o status conforme o saldo devedor resultante. Quando FinishIfPossible=1 e há pedido vinculado, tenta finalizar o pedido se todos os títulos estiverem pagos.

Path params

Nome	Tipo	Obrigatório	Descrição
idaccountpayable	integer	sim	Identificador da conta a pagar.

Query params

Nome	Tipo	Obrigatório	Descrição
FinishIfPossible	integer (1)	não	Quando 1, tenta finalizar o pedido vinculado se todos os títulos estiverem pagos.

Body

Campo	Tipo	Obrigatório	Descrição
IDBankAccount	integer	sim	Conta bancária onde o pagamento foi efetuado.
DateTransactionTimestamp	string (date-time)	sim	Data e hora da transação.
Value	number	não	Valor pago. Quando omitido, usa o saldo devedor total.
TransactionDescription	string	não	Descrição da transação (default "").
TransactionDocument	string	não	Documento da transação (default "").
IDAccountsPayableReceivableConciliation	integer	não	Conciliação bancária à qual este pagamento pertence.

Resposta 200 — conta a pagar atualizada (mesmo formato do GET /accounts/payable/{idaccountpayable}).

Erros

Status	Quando
400	Conta a receber/pagar não existe; Conta bancária não existe; Caixinha esta aberto e não pode ter pagamentos efetuados; Valor a conciliar divergente de valor do título e não há outro lançamento relacionado.

---

DELETE /accounts/payable/{idaccountpayable}/payment/{idaccountpayment}

accountsPayablePaymentDelete · autenticado

Remove o lançamento de pagamento e reverte o status da conta a pagar. Quando vinculado a uma conciliação bancária, desfaz o vínculo e recalcula o status da conciliação. Registra a exclusão no histórico.

Path params

Nome	Tipo	Obrigatório	Descrição
idaccountpayable	integer	sim	Identificador da conta a pagar.
idaccountpayment	integer	sim	Identificador do lançamento de pagamento (IDBankStatement).

Query params

Nome	Tipo	Obrigatório	Descrição
IDBankStatementConciliation	integer	não	Quando informado, bloqueia a exclusão se o pagamento pertencer a outra conciliação.

Resposta 200 — conta a pagar atualizada (mesmo formato do GET /accounts/payable/{idaccountpayable}).

Erros

Status	Quando
400	Pagamento não existe; Pagamento foi realizado em um caixa e não pode ser excluído; Caixinha esta aberto e não pode ter pagamentos efetuados; Não é possível excluir um pagamento vinculado a outra conciliação bancária; Problema ao deletar pagamento.

---

POST /accounts/payable/{idaccountpayable}/cost-center

accountsPayableReceivableCostCenterPost · autenticado

Substitui completamente o rateio de centros de custo da conta a pagar. Array vazio remove todos os centros. A soma de ValueRatio deve ser exatamente 1 (100%).

Path params

Nome	Tipo	Obrigatório	Descrição
idaccountpayable	integer	sim	Identificador da conta a pagar.

Body — array de objetos:

Campo	Tipo	Obrigatório	Descrição
IDTypeCostCenter	integer	sim	Identificador do centro de custo.
ValueRatio	number	sim	Proporção do rateio (ex.: 0.5 = 50%). Soma total deve ser 1.

Resposta 200 — conta a pagar atualizada ou "sucesso" quando o array foi vazio.

Erros

Status	Quando
400	Conta a receber/pagar não existe; Rateio precisa somar 100%; Centro de custo(s) não localizado(s): {ids}; Precisa enviar ao menos um centro de custo.

---

POST /accounts/payable/{idaccountpayable}/bank-integration

accountsPayableBankPaymentPost · autenticado

Aciona o worker PHP para processar o pagamento via integração bancária configurada. Após o envio, retorna a conta atualizada, salvo quando NoInvoke=1.

Path params

Nome	Tipo	Obrigatório	Descrição
idaccountpayable	integer	sim	Identificador da conta a pagar.

Query params

Nome	Tipo	Obrigatório	Descrição
NoInvoke	integer (1)	não	Quando 1, não busca a conta atualizada e devolve apenas "Sucesso".

Resposta 200 — conta a pagar atualizada ou "Sucesso" quando NoInvoke=1.

Erros

Status	Quando
400	Título precisa ser enviado; mensagens de erro do worker bancário.

---

POST /accounts/payable/{idaccountpayable}/file

accountsFilePost · autenticado

Faz upload de um arquivo via multipart/form-data e o vincula à conta a pagar.

Path params

Nome	Tipo	Obrigatório	Descrição
idaccountpayable	integer	sim	Identificador da conta a pagar.

Query params

Nome	Tipo	Obrigatório	Descrição
IDTypeFile	integer	sim	Tipo do arquivo: 1=Documento Fiscal PDF, 2=Documento Fiscal XML, 3=Boleto Bancário, 4=Comprovante Pagamento, 5=Carta de Correção PDF, 6=Carta de Correção XML, 7=Inutilização NF XML, 8=Cancelamento NF XML.

Body — multipart/form-data com campo file (binário).

Resposta 200 — conta a pagar atualizada com o novo arquivo em Files.

---

GET /accounts/payable/{idaccountpayable}/file/{idfile}

accountsFileGet · autenticado

Serve o arquivo diretamente do S3. O handler não foi localizado localmente; comportamento inferido a partir dos links gerados em accountsPayableGet.

⚠️ Handler não confirmado em código.

Path params

Nome	Tipo	Obrigatório	Descrição
idaccountpayable	integer	sim	Identificador da conta a pagar.
idfile	integer	sim	Identificador do arquivo.

Query params (conforme links gerados pelo sistema)

Nome	Tipo	Obrigatório	Descrição
View	integer (1)	não	Quando 1, serve o arquivo para visualização no browser.
token	string	não	Token de autenticação alternativo ao header Authorization.
File	string	não	Parâmetro de roteamento interno gerado pelo sistema.

Resposta 200 — conteúdo binário do arquivo.

---

DELETE /accounts/payable/{idaccountpayable}/file/{idfile}

accountsFileDelete · autenticado

Remove o arquivo do banco e retorna a conta a pagar atualizada.

Path params

Nome	Tipo	Obrigatório	Descrição
idaccountpayable	integer	sim	Identificador da conta a pagar.
idfile	integer	sim	Identificador do arquivo.

Resposta 200 — conta a pagar atualizada com o arquivo removido de Files.

Erros

Status	Quando
400	Arquivo não encontrado para esta conta.

---

POST /accounts/bank-account

bankAccountPost · autenticado

Cria uma conta bancária para a empresa. Marcar a conta como principal de recebimento ou pagamento desmarca automaticamente qualquer outra conta da mesma combinação de empresa e faturador.

Faturador, integração bancária e tipo de pedido (quando informados) são validados contra os cadastros da empresa.

Request body — BankAccountCreate

Campo	Tipo	Obrigatório	Descrição
Bank	string (≤100)	sim	Nome do banco.
BankNumber	string (≤3)	sim	Código Febraban.
BankRouting	string (≤45)	não	Agência.
AccountNumber	string (≤45)	não	Número da conta.
AccountNumberDigit	string (≤1)	não	Dígito verificador.
MainIncome	integer (0/1)	não	Padrão 0.
MainPayment	integer (0/1)	não	Padrão 0.
IDCompanyInvoice	integer	não	Faturador. Padrão: empresa do contexto.
IDCompanyIntegration	integer	não	Integração bancária associada.
IDTypeOrder	integer	não	Tipo de pedido habilitado para frente de caixa, com mesmo faturador.
TefTerminal	string (≤45)	não	Terminal TEF.

Resposta 200 — lista atualizada de contas bancárias (mesmo formato de GET /accounts/bank-account).

Erros

Status	Quando
400	Empresa não existe; Faturador não existe; Integração não existe; Tipo pedido não existe; Tipo pedido não esta habilitado para frente de caixa; Tipo pedido não esta habilitado para esta empresa/faturador, ajustar no cadastro.
500	Erro interno.

---

PUT /accounts/bank-account/{idbankaccount}

bankAccountPut · autenticado

Atualiza parcialmente uma conta bancária. Aceita dois modos disjuntos:

• Atualização de cadastro (padrão): altera dados como nome do banco, número, agência, número da conta, integração, faturador, terminal TEF e tipo de pedido. Vale a mesma regra do POST para conta principal de recebimento ou pagamento.
• Ajuste de saldo inicial: quando InitialBalance e InitialBalanceDate são enviados, o endpoint calcula a diferença entre o saldo desejado e o saldo atual até o dia anterior à data informada e insere um lançamento de ajuste no extrato. Diferença zero retorna erro.

Mudar BankNumber quando a conta atual é interna (000) e existe caixa aberto vinculado é bloqueado.

Path params

Nome	Tipo	Obrigatório	Descrição
idbankaccount	integer	sim	Identificador da conta bancária.

Request body — BankAccountUpdate. Todos os campos opcionais.

Campo	Tipo	Obs.
Bank, BankNumber, BankRouting, AccountNumber, AccountNumberDigit	string	Dados do banco.
MainIncome, MainPayment	integer (0/1)	Conta principal.
IDCompanyInvoice, IDCompanyIntegration, IDTypeOrder, TefTerminal	mistos	Relacionamentos.
InitialBalance	number	Ativa o modo de ajuste de saldo quando enviado junto com InitialBalanceDate.
InitialBalanceDate	string (date)	Data de referência do ajuste.

Resposta 200 — lista atualizada de contas bancárias.

Erros

Status	Quando
400	Empresa não existe; Faturador não existe; Integração não existe; Tipo pedido não existe; Tipo pedido não esta habilitado para frente de caixa; Tipo pedido não esta habilitado para esta empresa/faturador, ajustar no cadastro; Conta possui caixa aberto e não pode editado; Nenhum ajuste aplicado.
500	Erro interno.

---

DELETE /accounts/bank-account/{idbankaccount}

bankAccountDelete · autenticado

Inativa a conta bancária (não exclui o registro fisicamente).

Regras impeditivas:

• A conta não pode ter lançamentos de pagamento ou recebimento.
• A conta não pode estar vinculada como conta prevista em algum título a pagar ou receber.
• A conta não pode ter sido usada em abertura de caixa do PDV.

Path params

Nome	Tipo	Obrigatório	Descrição
idbankaccount	integer	sim	Identificador da conta bancária.

Resposta 200 — lista atualizada de contas bancárias.

Erros

Status	Quando
400	Conta bancária não existe; Conta bancária já possui pagamento / recebimento e não pode ser excluída; Contas a pagar/receber esta com esta conta bancária e não pode ser excluída; Conta bacária já foi utilizada em abertura de caixa (PDV) e não pode ser excluída.
500	Erro interno.

---

GET /accounts/bank-statement

bankStatementList · autenticado

Retorna lançamentos do extrato bancário. O comportamento muda conforme Source:

• Source=1 (extrato interno): lista os lançamentos do extrato do idworks com saldo corrente calculado linha a linha. Resposta é um objeto único (BankStatementInternalResponse) com PreviousBalance, Entries[], Receivables, Payables, FinalBalance.
• Source=2 (extrato bancário): lista lançamentos importados do banco, agrupados por IDBankStatementConciliation, com lista de contas internas (InternalAccounts[]) que casam com cada lançamento. Resposta é um array (BankStatementConciliationEntry[]).
• Source=1 com IDBankStatementConciliation (modo especial): retorna apenas as contas internas vinculadas a uma conciliação específica, como array.

Query params (principais)

Nome	Tipo	Obrigatório	Descrição
Source	integer (1/2)	sim	Modo de operação.
IDBankAccount	integer	não	Filtra por conta bancária.
IDTypeAccount	integer (0/1)	não	Tipo do lançamento: 0=entrada, 1=saída.
DateFrom, DateTo	string (date)	não	Período. Em Source=2, default 2025-01-01 quando omitido.
IDBankStatementConciliation	integer	não	Em Source=1, ativa o modo especial. Em Source=2, restringe ao grupo.
IDTypeStatusConciliation	integer	não	(Source=2) Status de conciliação.
OnlyTransfer	integer (1)	não	(Source=1) Apenas transferências.
Page	integer	não	Página de 5000 itens.

Resposta 200 — varia conforme Source (veja os schemas BankStatementInternalResponse, BankStatementConciliationEntry, BankStatementConciliationInternal).

Erros

Status	Quando
400	Erro na configuração da empresa; Valor inválido para Source (use '1' ou '2'); Falha ao listar extrato: <detalhe>.
500	Erro interno.

---

POST /accounts/bank-statement

bankStatementPost · autenticado

Vincula títulos a pagar/receber ou transferências entre contas a um único lançamento — bancário (IDBankStatementConciliation) ou de adquirente (IDAccountsPayableReceivableConciliation). Identifique exatamente uma conciliação e exatamente uma das listas (Accounts[] ou Transfers[]).

• Conciliação de adquirente com Accounts[]: gera os lançamentos do extrato interno, cria o vínculo na conciliação de adquirente e marca o status como Conciliação manual.
• Conciliação bancária com Accounts[]: o status final depende dos valores — 3 (manual) quando o total bate, 4 (parcial) quando ainda falta reconciliar.
• Quando o título já tem lançamento na mesma data, o lançamento existente é reaproveitado em vez de criar novo. Lançamentos já vinculados a outra conciliação bloqueiam a operação.
• Transfers[] liga transferências entre contas (lançamentos sem título associado) à conciliação. Transferências já conciliadas são rejeitadas.

O valor total das contas não pode ultrapassar o valor do lançamento de conciliação (comparação em módulo, para suportar estornos).

Body — veja BankStatementConciliationCreate.

Resposta 200 — array com 1 item (BankStatementConciliationCreateResponse) no mesmo formato de um item de GET /accounts/bank-statement?Source=2.

Erros

Status	Quando
400	Conciliação não selecionada / informada em duplicidade; conta bancária faltando ou não pertence à empresa; Accounts/Transfers ausentes ou inválidos; conciliação inexistente; valor dos lançamentos ultrapassa o título; divergência de data; título já conciliado em outra conciliação bancária; Falha ao processar conciliação.
500	Erro interno.

---

POST /accounts/bank-statement/transfer

bankStatementTransferPost · autenticado

Registra uma transferência entre duas contas bancárias da empresa, criando dois lançamentos no extrato interno: um de débito na conta de origem e um de crédito na conta de destino. Os lançamentos ficam ligados por uma referência (AccountsPayableReceivableBankStatementTransfer) que permite tratá-los como o mesmo movimento ao reconciliar.

A descrição informada é concatenada com o banco e o número da conta do outro lado nos dois lançamentos. Origem e destino não podem ser a mesma conta.

Body — veja BankStatementTransferCreate. Obrigatórios: IDBankFrom, IDBankTo, Value (> 0).

Resposta 200 — BankStatementTransferCreateResponse com IDAccountsPayableReceivableBankStatementTransfer, detalhes consolidados em Transfer e os dois lançamentos em InsertedTransactions[].

Erros

Status	Quando
400	Falta IDBankFrom/IDBankTo/Value; origem igual ao destino; valor ≤ 0; uma das contas não pertence à empresa; falha ao inserir o débito ou crédito; Falha ao processar transferência.
500	Erro interno.

---

DELETE /accounts/bank-statement/transfer/{idbankstatement}

bankStatementTransferDelete · autenticado

Remove uma transferência interna criada por POST /accounts/bank-statement/transfer. O endpoint aceita o id de qualquer um dos dois lados da transferência (débito ou crédito); a partir dele, identifica o par completo (via AccountsPayableReceivableBankStatementTransfer), valida que ambos os lançamentos pertencem à empresa e remove a referência da transferência e os dois lançamentos do extrato.

Resposta 200 — BankStatementTransferDeleteResponse com a referência removida e os dois lançamentos apagados (Debit e Credit).

Erros

Status	Quando
400	Empresa não encontrada; Lançamento não é uma transferência ou não foi encontrado; Uma ou ambas as transações não pertencem a esta empresa; Falha ao excluir as transações; Falha ao excluir transferência.
500	Erro interno.

---

GET /accounts/bank-statement/conciliation-rule

bankStatementConciliationRuleList · autenticado

Lista as regras de conciliação automática da empresa. Quando o extrato em OFX é importado, cada lançamento bancário é cruzado com essas regras para determinar se a conciliação acontece automaticamente, e contra qual tipo de movimento (título a pagar/receber ou transferência entre contas). Cada regra é restrita a uma conta bancária e a um tipo de transação.

Query params

Nome	Tipo	Obrigatório	Descrição
IDBankAccount	integer	não	Filtra por conta bancária.
IDBankStatementConciliationRule	integer	não	Retorna apenas a regra com este id.
Page	integer	não	Página (5000 itens).

Resposta 200 — array de BankStatementConciliationRuleListItem, com os campos da regra mais a descrição amigável de IDTypeRule e os nomes resolvidos da conta bancária, plano de contas, fornecedor, cliente, etc.

Erros

Status	Quando
400	Erro na configuração da empresa.
500	Erro interno.

---

POST /accounts/bank-statement/conciliation-rule

bankStatementConciliationRulePost · autenticado

Cadastra uma regra. O comportamento dos campos opcionais depende de IDTypeRule:

• IDTypeRule=1 (contas a pagar/receber) — IDBankAccountTo é descartado. Os campos IDTypeAccountPayableReceivable, IDTypeDocument, IDTypePayment, IDSupplier e IDConsumer funcionam como filtros adicionais para o casamento automático.
• IDTypeRule=2 (transferência) — IDBankAccountTo é obrigatório e não pode ser igual a IDBankAccount; os filtros de título são descartados.

Não é permitido repetir uma Description para a mesma conta bancária.

Body — BankStatementConciliationRuleCreate. Obrigatórios: IDBankAccount, IDTypeRule (e IDBankAccountTo quando IDTypeRule=2).

Resposta 200 — array com 1 item no formato de BankStatementConciliationRuleListItem.

Erros

Status	Quando
400	Empresa não existe; Já existe uma regra com a mesma descrição para essa conta bancária; Conta bancária obrigatória / Conta bancária não existe; Conta bancária destino obrigatória em regra do tipo transferência / Conta bancária destino não existe / Conta bancária destino e origem não podem ser igual; Tipo regra obrigatório / Tipo regra não existe; Tipo pagamento não existe / Tipo documento não existe; Fornecedor não existe / Cliente não existe; Erro ao criar regra.
500	Erro interno.

---

PUT /accounts/bank-statement/conciliation-rule/{idbankstatementconciliationrule}

bankStatementConciliationRulePut · autenticado

Atualiza uma regra. As mesmas regras condicionais de IDTypeRule valem (ver POST). Apenas os campos enviados no corpo são considerados na atualização; a unicidade da descrição por conta bancária também é validada.

Body — BankStatementConciliationRuleCreate (mesmo formato do POST).

Resposta 200 — array com 1 item no formato de BankStatementConciliationRuleListItem.

Erros

Status	Quando
400	Regra não existe; mesmas validações do POST (descrição duplicada, conta/destino inválidos, tipo regra inválido, etc.).
500	Erro interno.

---

DELETE /accounts/bank-statement/conciliation-rule/{idbankstatementconciliationrule}

bankStatementConciliationRuleDelete · autenticado

Remove a regra. Falha quando a regra não pertence a uma conta bancária da empresa autenticada.

Resposta 200 — a string "sucesso".

Erros

Status	Quando
400	Regra não existe.
500	Erro interno.

---

GET /accounts/cash-flow

cashFlowList · autenticado

Retorna o fluxo de caixa da empresa em dois modos, controlados por Type:

• Resumo (default, sem Type): consolidado mês a mês (ou dia a dia, com GroupBy=day) do previsto TotalValue e do realizado ValuePaid, agrupado por plano de contas. Cada item inclui a árvore completa do plano de contas em CategoryTree (array de strings). Cobre o ano inteiro definido em Year (ou o ano corrente quando omitido) e exclui contas com status Não lançado.
• Detalhe (Type=Detail): lista os títulos individuais (AccountsPayableReceivable) que compõem uma célula do resumo. Use IDTypeAccountPayableReceivable para restringir ao plano de contas selecionado e Date (primeiro dia do mês YYYY-MM-DD) combinado com DateType para restringir ao mês — DateType=DateDue filtra pelo vencimento (coluna Previsto); qualquer outro valor (a UI envia DatePayment) filtra pela data de pagamento lançado (coluna Realizado).

Valores são assinados pelo tipo de lançamento: contas a pagar (IDTypeAccount=1) entram negativas; contas a receber (IDTypeAccount=0) entram positivas.

Query params

Nome	Tipo	Obrigatório	Descrição
Year	integer	não	Ano de referência. Default: ano corrente.
GroupBy	string	não	month (default) ou day. Só vale no modo Resumo.
Type	string	não	Quando Detail, ativa o modo de detalhamento.
Date	string (date)	não	(Detalhe) Primeiro dia do mês a detalhar; o backend deriva o último dia do mesmo mês.
DateType	string	não	(Detalhe) DateDue filtra pelo vencimento; DatePayment (ou outro) filtra pela data do pagamento.
IDTypeAccountPayableReceivable	integer	não	(Detalhe) Restringe ao plano de contas selecionado.
IDBankAccountForecast	integer	não	Filtra pela conta bancária prevista do lançamento.
IDBankAccount	integer	não	Filtra por lançamentos com pelo menos um pagamento na conta bancária informada.
IDCompanyInvoice	integer	não	Filtra pela empresa faturadora (filial) do lançamento.

Resposta 200

• Modo Resumo: array de CashFlowSummaryItem — Month, Year, Date, TotalValue, TotalQty, ValuePaid, IDTypeAccount, IDTypeAccountPayableReceivable, IDTypeAccountPaybleFather, TypeAccountPaybleDescription, CategoryTree[], IDCompanyInvoice.
• Modo Detalhe: array de CashFlowDetailItem — AccountName, IDAccountPayableReceivable, IDStatusAccountPayableReceivable, StatusAccountPayableReceivable, DateCompetence, DateDue, IDTypeAccount, IDTypeAccountPayableReceivable, TypeAccountPaybleDescription, CategoryTree, IDTypePayment, TypePaymentDescription, Value, ValuePaid, SupplierNameCorporateName.

Erros

Status	Quando
400	Erro na configuração da empresa (empresa autenticada não tem identificador válido para a conta resolvida).
500	Erro interno.

---

GET /accounts/payable

accountsPayableList · autenticado

Lista contas a pagar com totais já calculados — valor total ValueTotal, valor pago ValuePaid, saldo devedor ValuePaymentPending. Aceita ~25 filtros: por status, valor, vencimento, documento, competência, último pagamento, registro, fornecedor, cliente, plano de contas, tipo de documento, tipo de pagamento, pedido, faturador, conta bancária prevista e do pagamento, e mais. Paginação por Page (5000 itens).

Quando a parametrização Permitir visualizar registros apenas fornecedores vinculados ao usuário da empresa está ativa, os resultados são restritos às categorias de fornecedor vinculadas ao usuário autenticado.

Query params (principais — a lista completa está no OpenAPI)

Nome	Tipo	Descrição
IDStatusAccountPayableReceivable	string	Lista de status separada por vírgula. Valores: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo, 6=Vence hoje. Default 0,1,2,3,5.
IDTypeEntity	integer (1/2)	1 apenas com cliente, 2 apenas com fornecedor.
DateDueFrom / DateDueTo	string (date)	Faixa de vencimento.
DateDocumentFrom / DateDocumentTo	string (date)	Faixa de data do documento.
DateCompetenceFrom / DateCompetenceTo	string (date)	Faixa de competência.
DateLastPaymentFrom / DateLastPaymentTo	string (date)	Faixa de último pagamento.
DateRecordTimestampFrom / DateRecordTimestampTo	string (date)	Faixa de registro.
ValueFrom / ValueTo	number	Faixa de valor.
IDSupplier, IDConsumer, IDTypePayment, IDTypeDocument, IDTypeAccountPayableReceivable, IDBankAccountForecast, IDBankAccount, IDOrder, IDCompanyInvoice	integer	Filtros por relacionamento.
Scheduled, Forecast	integer (0/1)	Flags.
DocumentNumber	string	Filtro pelo número do documento.
IDAccountPayableReceivable	string	Lista de ids para retornar lotes específicos.
Page	integer	Página (5000 itens). Default 0.

Resposta 200 — array de AccountsPayableListItem.

Erros

Status	Quando
400	Erro na configuração da empresa.
500	Erro interno.

---

GET /brand

brandList · autenticado

Lista marcas ativas da empresa. Aceita busca textual opcional contra o id e o nome.

Query params

Nome	Tipo	Obrigatório	Descrição
Search	string	não	Busca textual contra identificador IDBrand e nome Name. Cada espaço vira um curinga % internamente.

Resposta 200 — array de BrandListItem:

[
  { "AccountName": "exemplo", "IDBrand": 42, "Name": "Marca X", "IsActive": 1, "Status": "Ativo" }
]

Erros

Status	Quando
400	Erro na configuração da empresa.
500	Erro interno.

---

POST /brand

brandPost · autenticado

Cria uma marca. Apenas Name é efetivamente obrigatório: Description, Keywords e Title herdam o valor de Name quando ausentes ou vazios; IsActive assume 1, MenuHome assume 0, Score fica nulo.

Request body — BrandCreate

Campo	Tipo	Obrigatório	Descrição
Name	string (≤300)	sim	Nome da marca.
Description	string (≤300)	não	Padrão: Name.
Keywords	string (≤500)	não	Padrão: Name.
Title	string (≤300)	não	Padrão: Name.
IsActive	integer (0/1)	não	Padrão 1.
MenuHome	integer (0/1)	não	Padrão 0.
Score	integer	não	Padrão nulo.

Resposta 200 — array com 1 item, no formato Brand.

Erros

Status	Quando
400	Company não existe.
500	Erro interno.

---

GET /brand/{idbrand}

brandGet · autenticado

Retorna o cadastro completo de uma marca.

Path params

Nome	Tipo	Obrigatório	Descrição
idbrand	integer	sim	Identificador da marca.

Resposta 200 — array com 0 ou 1 item, no formato Brand:

[
  {
    "IDBrand": 42,
    "Name": "Marca X",
    "Description": "Marca X",
    "Keywords": "marca, x, exemplo",
    "Title": "Marca X",
    "IsActive": 1,
    "MenuHome": 0,
    "Score": null,
    "RecordTimestamp": "2024-09-01T10:30:00Z",
    "Status": 1
  }
]

Erros

Status	Quando
500	Erro interno.

(400 não é emitido por este endpoint — id inexistente devolve 200 [].)

---

PUT /brand/{idbrand}

brandPut · autenticado

Atualiza parcialmente uma marca. Apenas os campos enviados são alterados. A resposta é o detalhe da marca atualizada.

Path params

Nome	Tipo	Obrigatório	Descrição
idbrand	integer	sim	Identificador da marca.

Request body — BrandUpdate. Todos os campos opcionais.

Campo	Tipo
Name	string (≤300)
Description	string (≤300)
Keywords	string (≤500)
Title	string (≤300)
IsActive	integer (0/1)
MenuHome	integer (0/1)
Score	integer

Resposta 200 — array com 1 item, no formato Brand.

Erros

Status	Quando
400	Brand não existe.
500	Erro interno.

---

DELETE /brand/{idbrand}

brandDelete · autenticado

Inativa a marca (não exclui fisicamente). Bloqueada quando há produtos ativos vinculados.

Path params

Nome	Tipo	Obrigatório	Descrição
idbrand	integer	sim	Identificador da marca.

Resposta 200 — string literal:

"sucesso"

Erros

Status	Quando
400	marca não existe; Marca possui produto ativos. Alterar a marca no cadastro do item antes de excluir a marca.
500	Erro interno.

---

GET /supplier/{idsupplier}

supplierGet · autenticado

Retorna o cadastro completo de um fornecedor. O mesmo cadastro é usado para transportadoras — os campos com prefixo Carrier* e os relacionados a SRO dos Correios ficam preenchidos apenas quando o fornecedor opera como transportadora.

A resposta inclui descrições resolvidas dos relacionamentos (categoria, tipo de fornecedor, integração, banco, estado civil, plano de contas), campos calculados (SupplierType para distinguir PF/PJ pelo tamanho do SupplierCpfCnpj; CarrierRateUploadStatusDescription traduzindo o status do upload), e listas auxiliares: contatos, faixas SRO, uploads de tabela de frete e centros de custo padrão.

⚠ Atenção: quando o id não existe, não está ativo, ou não pertence à empresa autenticada, a resposta é 200 [] — este endpoint não emite erro para "não encontrado".

Path params

Nome	Tipo	Obrigatório	Descrição
idsupplier	integer	sim	Identificador do fornecedor (ou transportadora).

Resposta 200 — array com 0 ou 1 item, no formato SupplierDetail:

[
  {
    "IDSupplier": 42,
    "SupplierNameCorporateName": "Fornecedor Exemplo LTDA",
    "SupplierTradeName": "Fornecedor Exemplo",
    "SupplierCpfCnpj": "12345678000199",
    "SupplierType": 2,
    "SupplierEmail": "contato@exemplo.com",
    "SupplierTelephone": "(11) 99999-0000",
    "ShippingPostalCode": "01310-100",
    "ShippingCity": "São Paulo",
    "ShippingState": "SP",
    "CategoryDescription": "Matéria-prima",
    "TypeSupplier": "Fornecedor",
    "BankCode": "001",
    "Bank": "Banco do Brasil",
    "BankAgency": "1234-5",
    "BankCheckingAccount": "67890",
    "PixKey": "12345678000199",
    "AccountName": "exemplo",
    "RecordTimestamp": "2024-03-12T10:30:00Z",
    "ContentDeclarationStates": [],
    "Contacts": [],
    "CorreiosSRO": [],
    "CarrierTableUpload": [],
    "SuppliersCostCenter": []
  }
]

Erros

Status	Quando
500	Erro interno (prefixo Error:).

(400 não é emitido — id inexistente devolve 200 [].)

Schemas dos arrays da resposta

Contacts[] — SupplierContact

Contato do fornecedor.

Campo	Tipo	Obs.
IDSuppliersContact	integer	Id do contato.
ContactName	string ou null	Nome.
ContactEmail	string ou null	E-mail.
ContactTelephone	string ou null	Telefone.
ContactResponsability	string ou null	Cargo ou área.
RecordTimestamp	string (date-time)	Data e hora de cadastro.

CorreiosSRO[] — SupplierCorreiosSroRange

Faixa de números de SRO (rastreio) dos Correios disponível para a transportadora.

Campo	Tipo	Obs.
IDCorreiosSroRange	integer	Id da faixa.
Status	integer (0/1)	1 = faixa ativa.
Prefix	string ou null	Prefixo do código SRO.
RangeInitial	integer ou null	Primeiro número.
RangeFinal	integer ou null	Último número.
CurrentRange	integer ou null	Próximo número a ser usado.
DiffRange	integer	Quantidade ainda disponível na faixa quando ativa. Zero quando inativa.

CarrierTableUpload[] — SupplierCarrierTableUpload

Uploads de tabela de frete, do mais recente para o mais antigo.

Campo	Tipo	Obs.
IDCarrierTableUpload	integer	Id do upload.
FileName	string ou null	Nome do arquivo enviado.
UrlFile	string	URL completa para download, com token embutido.
RecordTimestamp	string (date-time)	Data e hora do upload (ISO 8601 com Z).
Main	integer (0/1)	1 apenas no upload mais recente (vigente).

SuppliersCostCenter[] — SupplierCostCenterAllocation

Rateio padrão de centro de custo aplicado aos títulos gerados.

Campo	Tipo	Obs.
IDTypeCostCenter	integer	Id do centro.
TypeCostCenter	string (≤100)	Nome do centro de custo.
ExternalCode	string (≤45) ou null	Código para integração contábil.
ValueRatio	number	Fração do total (4 casas decimais, ex.: 0.3500 = 35%).
RecordTimestamp	string (date-time)	Data e hora do cadastro do rateio.

---

GET /supplier/category

supplierCategoryList · autenticado

Lista as categorias ativas da empresa, ordenadas pela descrição. Cada item já vem com o tipo de fornecedor resolvido (TypeSupplier).

Quando a empresa autenticada é a all (multi-conta), o filtro de empresa não é aplicado e a resposta cobre todas as empresas vinculadas.

Query params

Nome	Tipo	Obrigatório	Descrição
IDSupplierCategory	integer	não	Filtra por identificador de categoria. Quando omitido, devolve todas as categorias ativas da empresa.

Resposta 200 — array de SupplierCategoryListItem:

[
  {
    "AccountName": "exemplo",
    "IDSupplierCategory": 142,
    "CategoryDescription": "Matéria-prima",
    "IDCompany": 99,
    "IDTypeSupplier": 1,
    "TypeSupplier": "Produto",
    "SuppliersCategoryStatus": 1,
    "RecordTimestamp": "2024-03-12T10:30:00Z"
  }
]

Valores possíveis para IDTypeSupplier / TypeSupplier:

IDTypeSupplier	TypeSupplier
1	Produto
2	Transportadora
3	Pessoal
4	Serviço
5	Insumo
6	Governo
7	Transportadora P/ Devoluções
8	Operador logístico
9	Outros

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno (prefixo Error:).

---

POST /supplier/category

supplierCategoryPost · autenticado

Cria uma categoria para a empresa autenticada. A resposta repete o formato da listagem (array com 1 item), já com o tipo de fornecedor resolvido.

Request body — SupplierCategoryCreate

Campo	Tipo	Obrigatório	Descrição
CategoryDescription	string (≤45)	sim	Nome (descrição) da categoria.
IDTypeSupplier	integer (1–9)	sim	Tipo de fornecedor. Ver tabela em GET /supplier/category.

Resposta 200 — array com 1 item, no formato SupplierCategoryListItem.

Erros

Status	Quando
400	[BadRequest] - Empresa não existe.
500	Erro interno (prefixo Error:).

---

PUT /supplier/category/{idsuppliercategory}

supplierCategoryPut · autenticado

Atualiza a descrição e/ou o tipo de fornecedor de uma categoria existente. Ambos os campos são considerados em toda chamada — não é uma atualização parcial: enviar somente um dos dois sobrescreverá o outro com vazio/nulo. A resposta repete o formato da listagem.

Path params

Nome	Tipo	Obrigatório	Descrição
idsuppliercategory	integer	sim	Identificador da categoria.

Request body — SupplierCategoryUpdate

Campo	Tipo	Obrigatório	Descrição
CategoryDescription	string (≤45)	sim	Nome (descrição) da categoria.
IDTypeSupplier	integer (1–9)	sim	Tipo de fornecedor. Ver tabela em GET /supplier/category.

Resposta 200 — array com 1 item, no formato SupplierCategoryListItem.

Erros

Status	Quando
400	[BadRequest] - Categoria fornecedor não existe (id desconhecido para a empresa, ou já inativa).
500	Erro interno (prefixo Error:).

---

DELETE /supplier/category/{idsuppliercategory}

supplierCategoryDelete · autenticado

Inativa a categoria (SuppliersCategoryStatus = 0). Não exclui fisicamente o registro. A exclusão é bloqueada quando há fornecedores ativos vinculados à categoria — nesse caso é preciso primeiro alterar a categoria no cadastro de cada fornecedor.

A resposta é a lista atualizada das categorias ativas da empresa (mesmo formato do GET /supplier/category).

Path params

Nome	Tipo	Obrigatório	Descrição
idsuppliercategory	integer	sim	Identificador da categoria.

Resposta 200 — array de SupplierCategoryListItem (lista atualizada).

Erros

Status	Quando
400	[BadRequest] - Categoria fornecedor não existe; [BadRequest] - Existem fornecedores nessa categoria, alterar a categoria dentro do cadastro do fornecedor antes de excluir.
500	Erro interno (prefixo Error:).

---

GET /accounts/receivable

accountsReceivableList · autenticado

Retorna as contas a receber da empresa, com totais calculados (ValueTotal, ValuePaid, ValuePaymentPending). Cada item traz também dados resolvidos do pedido associado, da nota fiscal de origem (quando há) e da integração. Paginação por Page (4000 itens por página).

Quando a parametrização Permitir visualizar registros apenas fornecedores vinculados ao usuário da empresa está ativa, os resultados são restritos às categorias de fornecedor vinculadas ao usuário autenticado.

Use IDTypeEntity=1 para trazer apenas títulos com cliente (cobrança) e IDTypeEntity=2 para apenas títulos com fornecedor (devolução/estorno).

Query params

Nome	Tipo	Default	Descrição
Page	integer	0	Página (4000 itens por página).
IDAccountPayableReceivable	string		Lista de ids separados por vírgula.
IDStatusAccountPayableReceivable	string	0,1,2,3,5	Lista de status separados por vírgula. 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo, 6=Vence hoje.
IDConsumer	integer		Filtra por cliente.
IDSupplier	integer		Filtra por fornecedor.
ConsumerNameCorporateName	string		Filtra pelo nome/razão social.
IDTypeEntity	integer (1/2)		1 apenas cliente, 2 apenas fornecedor.
DocumentNumber	string		Filtra pelo número do documento.
NfeNumber	integer		Número da nota fiscal de origem.
IDTypeAccountPayableReceivable	integer		Plano de contas.
IDTypePayment	integer		Tipo de pagamento.
IDTypeDocument	integer		Tipo de documento.
IDOrder	integer		Identificador interno do pedido.
Order	string		Número externo do pedido (OT-1234, ML-5678).
OrderFrom	string		Pedido de origem (canal de venda).
IDCompanyInvoice	integer		Empresa faturadora.
IDCompanyIntegration	integer		Integração originadora (marketplace/adquirente/ERP).
IDBankAccountForecast	integer		Conta bancária prevista.
IDBankAccount	integer		Conta bancária do pagamento lançado.
TID, NSU	string		Identificadores do adquirente.
TIDorNSU, NSUorTID	string		Buscam o mesmo valor em TID ou NSU (OR).
ValueFrom, ValueTo	number		Faixa de valor total (Value + Penalty + Interest - Discount).
DateDueFrom/To	string (date)		Faixa de vencimento.
DateDocumentFrom/To	string (date)		Faixa da data do documento.
DateCompetenceFrom/To	string (date)		Faixa de competência.
DateLastPaymentFrom/To	string (date)		Faixa do último pagamento (To inclusivo até 23:59).
DateRecordTimestampFrom/To	string (date)		Faixa de cadastro (To inclusivo até 23:59).
InvoiceDateFrom/To	string (date)		Faixa de emissão da nota fiscal de origem (To inclusivo até 23:59:59).

Resposta 200 — array de AccountsReceivableListItem. Vazio quando o usuário não tem acesso pela parametrização de governança ou não há matches.

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa (empresa autenticada sem idcompanylist válido).
500	Erro interno (prefixo Error:).

---

POST /accounts/receivable

accountsReceivablePost · autenticado

Cria uma nova conta a receber (sempre como entrada, IDTypeAccount=0). A resposta é a representação completa da conta recém-criada, no mesmo formato de GET /accounts/receivable/{idaccountreceivable} (objeto único em array).

Regras:

• IDConsumer e IDSupplier não podem ser enviados juntos — apenas um.
• Quando IDCompanyInvoice é omitido, assume a empresa autenticada.
• Strings vazias são tratadas como nulas — equivalentes a omitir o campo.

Request body — AccountsReceivableCreate

Campo	Tipo	Obrigatório	Descrição
DateDue	string (date)	sim	Data de vencimento.
Value	number	sim	Valor do título.
IDTypeDocument	integer	sim	Identificador do tipo de documento (validado).
IDTypeAccountPayableReceivable	integer	sim	Identificador do plano de contas (validado).
IDTypePayment	integer	sim	Identificador do tipo de pagamento (validado).
IDConsumer	integer	condicional	Cliente. Exclusivo com IDSupplier.
IDSupplier	integer	condicional	Fornecedor. Exclusivo com IDConsumer.
DateCompetence	string (date)	não	Competência.
DateDocument	string (date)	não	Emissão do documento.
DocumentNumber	string (≤200)	não	Número do documento.
Comments	string (≤2000)	não	Observações.
TID, NSU	string (≤45)	não	Identificadores do adquirente.
Installment, InstallmentTotal	integer	não	Parcela atual e total de parcelas.
IDBankAccountForecast	integer	não	Conta bancária prevista (validada contra a empresa).
IDCompanyInvoice	integer	não	Empresa faturadora. Quando diferente da empresa autenticada, precisa ser filial (CompanyMain).
ValueDiscount, ValueInterest, ValuePenalty	number	não	Componentes do valor.

Resposta 200 — array com 1 elemento do schema AccountsReceivableDetail.

Erros

Status	Mensagens prefixadas com [BadRequest]
400	Fornecedor ou cliente precisa ser preenchido (apenas um dos dois) · Empresa não existe · Cliente não existe / Fornecedor não existe · Faturador não existe · Type Payment não existe · Tipo documento não existe · Plano de contas não existe · IDBankAccountForecast não existe
500	Erro interno.

---

GET /accounts/receivable/{idaccountreceivable}

accountsReceivableGet · autenticado

Retorna a conta a receber completa: dados próprios, status, cliente ou fornecedor, tipo de documento, tipo de pagamento, plano de contas, banco previsto, integração originadora, lista de pagamentos lançados, arquivos anexados, histórico de alterações, centros de custo rateados e as contas filhas geradas por conciliação (taxa adquirente, comissão de marketplace, etc.).

⚠ Atenção: quando o id não existe ou a conta pertence a outra empresa, a resposta é 200 com [] (array vazio) — este endpoint não emite erro para "não encontrado".

Path params

Nome	Tipo	Obrigatório
idaccountreceivable	integer	sim

Resposta 200 — array com 0 ou 1 elemento do schema AccountsReceivableDetail. Os arrays auxiliares (Files, Payments, AccountsPayableReceivableLog, AccountsPayableReceivableCostCenter, RelatedAccountsPayableReceivable) seguem os mesmos schemas usados em contas a pagar — ver FileAttachment, BankStatementPayment, AccountsPayableLogEntry, AccountsPayableCostCenter e RelatedAccountsPayable no idworks.json.

Erros

Status	Quando
500	Erro interno (prefixo Error:).

---

PUT /accounts/receivable/{idaccountreceivable}

accountsReceivablePut · autenticado

Atualiza a conta a receber de forma parcial — apenas os campos enviados são alterados (PUT se comporta como PATCH). A diferença campo a campo é registrada no histórico de alterações (AccountsPayableReceivableLog).

Quando o título tem um boleto ou link de pagamento (ConsumerBankSlip) associado:

• Se o boleto está pago, a alteração de Value ou DateDue é bloqueada.
• Se o boleto está aberto ou cancelado, a alteração é propagada para o gateway (chamada interna ao serviço PHP de bankslip).

Quando IDSupplier é enviado, IDConsumer é zerado (e vice-versa). Quando há IDOrder ou IDServiceOrder vinculados, a alteração também é registrada no histórico do pedido/OS (evento 51).

Request body — AccountsReceivableUpdate: todos os campos opcionais (Comments, DateCompetence, DateDocument, DateDue, DocumentNumber, IDConsumer/IDSupplier, IDTypePayment, IDTypeDocument, IDTypeAccountPayableReceivable, Value, Installment, InstallmentTotal, TID, NSU, IDBankAccountForecast, ValueDiscount, ValueInterest, ValuePenalty, IDCompanyIntegration, IDCompanyInvoice, Forecast).

O valor "0" em IDBankAccountForecast é ignorado (não vira NULL).

Resposta 200 — array com a conta atualizada (AccountsReceivableDetail).

Erros

Status	Mensagens prefixadas com [BadRequest]
400	Conta a receber não existe · Fornecedor ou cliente precisa ser preenchido (apenas um dos dois) · Cliente não existe / Fornecedor não existe · Faturador não existe · Pagamento não existe · Banco não existe · Tipo documento não existe · Plano de contas não existe · Integração não existe · Boleto / link pagamento já esta pago e não pode ser alterado
500	Erro interno.

---

DELETE /accounts/receivable/{idaccountreceivable}

accountsPayableDelete · autenticado

Mesmo handler do DELETE de contas a pagar. Exclui a conta a receber, com as seguintes regras de bloqueio:

• Título agendado para pagamento automático (Scheduled=1).
• Já existe pelo menos um pagamento lançado.
• Título vinculado a uma compra (IDPurchase) e a parametrização Não permitir excluir contas pagar com recebimento está ativa.

A exclusão também limpa o vínculo de eventuais GNREs (Gnre.IDAccountsPayable). Quando o título nasceu de pedido ou ordem de serviço, registra um evento (50) no histórico.

Query params

Nome	Tipo	Descrição
ChangeNextRepeat	integer (1)	Quando 1, exclui também as próximas ocorrências da mesma série de recorrência (IDAccountPayableReceivableMain igual e DateDue posterior).

Resposta 200 — string "sucesso".

Erros

Status	Mensagens prefixadas com [BadRequest]
400	Pagamento não existe · Título esta agendado e não pode ser excluído · Não é possível excluir um contas a pagar atrelado a um recebimento · Contas a pagar já tem pagamento

---

POST /accounts/receivable/{idaccountreceivable}/cost-center

accountsPayableReceivableCostCenterPost · autenticado

Substitui completamente o rateio de centros de custo da conta a receber. A soma de ValueRatio de todos os itens deve ser exatamente 1 (100%). Enviar array vazio remove todos os centros. Os centros enviados precisam estar ativos e pertencer à empresa da conta.

Request body — array de AccountsPayableCostCenterSetItem:

Campo	Tipo	Obrigatório
IDTypeCostCenter	integer	sim
ValueRatio	number	sim

Resposta 200 — array com a conta atualizada (AccountsReceivableDetail), ou a string "sucesso" quando o array enviado foi vazio.

Erros

Status	Mensagens prefixadas com [BadRequest]
400	Conta a receber/pagar não existe · Rateio precisa somar 100% · Centro de custo(s) não localizado(s): <ids> · Precisa enviar ao menos um centro de custo

---

POST /accounts/receivable/{idaccountreceivable}/payment

accountsPayablePaymentPost · autenticado

Registra um pagamento na conta a receber, atualizando o status conforme o saldo pendente. Regras de negócio:

• Quando a conta tinha previsão (Forecast=1), a flag é zerada após o lançamento.
• Quando a conta não tinha banco previsto (IDBankAccountForecast), assume o banco do pagamento como previsão.
• Quando IDAccountsPayableReceivableConciliation é informado e o valor pago difere do título, o sistema procura outro lançamento relacionado pelo mesmo IDOrder/TID/NSU e redistribui a diferença entre os dois. Se não encontrar, falha. Adicionalmente, cria automaticamente o lançamento de taxa adquirente (IDTypeAccountPayableReceivable configurado na integração) abatendo o valor da comissão.
• Quando IDAccountsPayableReceivableConciliationMarketplace é informado, gera automaticamente contas filhas para comissão, antecipação, frete, cupom e impostos do marketplace conforme parametrização da integração.
• Pagamentos em conta de caixinha (BankNumber=000) só são aceitos com a caixinha fechada.
• Quando FinishIfPossible=1 e há pedido vinculado, tenta finalizar o pedido se todos os títulos estiverem pagos após este lançamento.

Query params

Nome	Tipo	Descrição
FinishIfPossible	integer (1)	Tenta finalizar o pedido vinculado se todos os títulos estiverem pagos.
query	integer (1)	Quando 1, retorna apenas "sucesso" (não invoca a recuperação completa). Útil em fluxos em massa.

Request body — AccountsReceivablePaymentCreate

Campo	Tipo	Obrigatório	Descrição
IDBankAccount	integer	sim	Conta bancária do recebimento.
DateTransactionTimestamp	string (date-time)	sim	Data e hora do recebimento.
Value	number	não	Valor recebido.
TransactionDescription	string (≤100)	não	Descrição livre. Default "".
TransactionDocument	string (≤45)	não	Documento associado (TID, comprovante). Default "".
IDAccountsPayableReceivableConciliation	integer	não	Conciliação adquirente associada (dispara redistribuição e geração de taxa).
IDAccountsPayableReceivableConciliationMarketplace	integer	não	Conciliação de marketplace associada (gera filhas de comissão/antecipação/frete/cupom/impostos).

Resposta 200 — array com a conta atualizada (AccountsReceivableDetail), ou a string "sucesso" quando query=1.

Erros

Status	Mensagens prefixadas com [BadRequest]
400	Conta a receber/pagar não existe · Conta bancária não existe · Caixinha esta aberto e não pode ter pagamentos efetuados · Valor a conciliar divergente de valor do título e não há outro lançamento relacionado · Conciliação marketplace inexistente · Erro ao criar lançamento de taxa adquirente

---

DELETE /accounts/receivable/{idaccountreceivable}/payment/{idaccountpayment}

accountsPayablePaymentDelete · autenticado

Remove o lançamento de pagamento e reverte o status da conta. Regras:

• Pagamentos lançados em caixa (IDStoreFrontCashier preenchido) não podem ser excluídos por esta rota.
• Pagamentos em caixinha (BankNumber=000) só podem ser excluídos com a caixinha fechada.
• Quando o pagamento está vinculado a uma conciliação bancária (BankStatementConciliationReference), desvincula e recalcula o status da conciliação (parcial ou não conciliado conforme as outras referências).
• Quando o pagamento está vinculado a uma conciliação adquirente ou marketplace, desvincula e reabre a conciliação correspondente.
• A exclusão é registrada no histórico da conta.

Path params

Nome	Tipo	Obrigatório
idaccountreceivable	integer	sim
idaccountpayment	integer	sim (IDBankStatement do lançamento).

Query params

Nome	Tipo	Descrição
IDBankStatementConciliation	integer	Quando informado, garante que o pagamento só seja excluído se pertencer a esta conciliação. Bloqueia exclusão se estiver em outra.

Resposta 200 — array com a conta atualizada (AccountsReceivableDetail).

Erros

Status	Mensagens prefixadas com [BadRequest]
400	Pagamento não existe · Pagamento foi realizado em um caixa e não pode ser excluído · Caixinha esta aberto e não pode ter pagamentos efetuados · Não é possível excluir um pagamento vinculado a outra conciliação bancária · Erro ao atualizar conciliação bancária · Erro ao verificar vínculos de conciliação · Problema ao deletar pagamento

---

GET /accounts/receivable/conciliation

accountsReceivableConciliationList · autenticado

Retorna as conciliações de adquirentes recebidas. Há dois modos de operação:

• Default (AuditRate omitido ou 0): lista as conciliações com seus vínculos a contas a receber e a lançamentos bancários, devolvendo valores brutos (TotalValue, ReceivedValue), taxas efetivas (MerchantDiscountRateEffectiveValue, AnticipationRateEffectiveValue) e a sugestão de IDTypePayment baseada no tipo de adquirente.
• Auditoria (AuditRate=1): compara as taxas efetivas pagas pelo adquirente com as taxas configuradas em TypePaymentRate, calculando os percentuais aplicados, esperados e a diferença em valor. Devolve também um IDAuditStatus:
  • 1 = verde (diferença mínima, OK)
  • 2 = azul (estorno ou diferença sem prejuízo)
  • 3 = amarelo (sem configuração de MDR e antecipação)
  • 4 = laranja (taxa configurada > 0 mas não aplicada)
  • 5 = vermelho (diferença acima da tolerância e com prejuízo)

Paginação por Page (5000 itens por página).

Query params principais (lista completa no idworks.json):

Nome	Tipo	Descrição
Page	integer (default 0)	Página de 5000.
AuditRate	integer (0/1)	Ativa modo de auditoria.
IDAuditStatus	string (csv)	Filtra por resultado de auditoria (apenas AuditRate=1).
IDAccountsPayableReceivableConciliation	integer	Filtra por id da conciliação.
IDCompanyIntegration	integer	Filtra pela integração adquirente.
IDTypePaymentFrom	integer	Tipo de pagamento do adquirente.
IDOrder	integer	Pedido vinculado (não aplicável em auditoria).
TID, NSU, ExternalIDOrderReference	string	Identificadores.
Status	integer	Status do adquirente (TypeAcquirerStatus).
ConciliationStatus	integer (1-4)	1=Não conciliado, 2=Automática, 3=Manual, 4=Parcial.
ReceivableIDBank	string	Banco em que o adquirente liberou.
IDTypeAcquirerReleaseType	integer	Tipo de liberação do adquirente.
SaleDateFrom/To	string (date)	Faixa de venda (To default 4000-01-01).
ReceivedDateFrom/To	string (date)	Faixa de recebimento (To default 4000-01-01).
RecordTimestampFrom/To	string (date)	Faixa de cadastro.

Resposta 200 — array. O schema do item depende de AuditRate:

• AuditRate=0 → AccountsReceivableConciliationListItem
• AuditRate=1 → AccountsReceivableConciliationAuditItem

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno.

---

PUT /accounts/receivable/conciliation/{idaccountspayablereceivableconciliation}

accountsReceivableConciliationPut · autenticado

Atualiza apenas o campo Comments da conciliação. Demais campos da conciliação não podem ser alterados por esta rota.

Path params

Nome	Tipo	Obrigatório
idaccountspayablereceivableconciliation	integer	sim

Request body — AccountsReceivableConciliationUpdate

Campo	Tipo	Descrição
Comments	string (≤255)	Observações sobre a conciliação.

Resposta 200 — array de AccountsReceivableConciliationListItem com a conciliação atualizada.

Erros

Status	Mensagens prefixadas com [BadRequest]
400	Conciliação não existe.
500	Erro interno.

---

GET /accounts/receivable/marketplace-conciliation

accountsReceivableMarketplaceConciliationList · autenticado

Retorna as conciliações de marketplace — os valores liberados por integrações de marketplace para cada pedido — já decompostos em comissão (MarketplaceFeeValue), antecipação (MarketplaceFinancingFeeValue), frete (MarketplaceShippingFeeValue), cupom (MarketplaceCouponValue) e impostos (MarketplaceTaxesValue).

Cada item agrupa as contas a receber/pagar internas vinculadas em InternalAccounts e soma os valores líquidos em ERPValueTotal, permitindo bater o que entrou no banco com o que o marketplace declara.

Paginação por page (5000 itens por página).

Query params principais:

Nome	Tipo	Descrição
page	integer (default 0)	Página de 5000.
IDCompanyIntegration	integer	Integração de marketplace.
IDOrder	integer	Pedido interno vinculado (via HubOrder).
OrderID	string	Identificador externo do pedido no marketplace.
TID	string	TID da conciliação.
IDTypeAcquirerStatus	integer	Status do marketplace.
IDTypeStatusConciliation	integer (1/3)	1=Não conciliado, 3=Manual.
Installment, InstallmentTotal	integer	Parcela e total.
SaleDateFrom/To	string (date)	Faixa de venda (To default 4000-01-01).
ReceivedDateFrom/To	string (date)	Faixa de recebimento (To default 4000-01-01).

Resposta 200 — array de AccountsReceivableMarketplaceConciliationItem. Cada item traz InternalAccounts[] com { IDBankStatement, IDAccountPayableReceivable, Document, Description, Value, IDTypeAccount } — Value vem positivo para contas a receber (IDTypeAccount=0) e negativo para contas a pagar (IDTypeAccount=1). ERPValueTotal é a soma desses valores e deve bater com ReceivedValue do marketplace.

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.

---

GET /type/account/type

typeAccountTypeList · autenticado

Lista os planos de contas ativos (Status=1) da empresa em dois formatos controlados por Type:

• Árvore (Type=Tree): itens raiz com seus descendentes em Children[]. Quando o plano tem ExternalCode, a descrição é prefixada (<código>-<descrição>). A categoria do plano é propagada do pai para os filhos.
• Lista plana (default, sem Type): array com todos os planos, cada item trazendo o caminho hierárquico em CategoryTree (texto separado por ->, da raiz até a folha).

Query params

Nome	Tipo	Obrigatório	Descrição
Type	string	não	Quando Tree, devolve árvore. Sem o parâmetro, devolve lista plana.
IDTypeAccount	integer	não	0 entrada (a receber), 1 saída (a pagar).
IDTypeCategoryAccountPayble	integer	não	Filtra pela categoria.
IDTypeAccountPayble	integer	não	(Árvore) Restringe ao plano com o id informado.

Resposta 200 — array de TypeAccountTreeNode (árvore) ou TypeAccountFlatItem (lista plana). Lista plana vazia retorna [].

Erros

Status	Quando
400	Erro na configuração da empresa.
500	Erro interno.

---

POST /type/account/type

typeAccountTypePost · autenticado

Cria um plano de contas (raiz ou filho). Quando IDTypeAccountPaybleFather é informado, o plano nasce como filho e a categoria informada é descartada (filho herda do pai). Marcar DefaultOrder=1 ou DefaultPurchase=1 desmarca automaticamente o plano anteriormente marcado como padrão da empresa.

Query params

Nome	Tipo	Obrigatório	Descrição
Type	string	não	Formato do plano na resposta (Tree por padrão).

Body — TypeAccountCreate. Obrigatório: TypeAccountPaybleDescription. IDTypeAccount default 1 (saída). ExternalCode/InternalCode, se informados, precisam ser únicos entre os planos ativos da empresa.

Resposta 200 — o plano recém-criado no formato indicado por Type.

Erros

Status	Quando
400	Empresa não existe; Plano de contas superior não existe; Já existe um plano com o mesmo cód. referência externo; Já existe um plano com o mesmo cód. referência interno; IDTypeCategoryAccountPayble não existe.
500	Erro interno.

---

PUT /type/account/type/{idtypeaccount}

typeAccountTypePut · autenticado

Atualiza o plano com o id informado. As mesmas regras do POST valem.

Diferença em relação ao POST: ao desmarcar (ou omitir) o flag DefaultOrder=1 (ou DefaultPurchase=1), o handler exige que outro plano na empresa esteja marcado como padrão — sempre é preciso ter exatamente um padrão de pedido e um de compra. Caso contrário, a operação falha.

Query params

Nome	Tipo	Obrigatório	Descrição
Type	string	não	Formato da lista retornada (Tree por padrão).

Body — TypeAccountCreate (mesmo formato do POST).

Resposta 200 — a lista completa do plano de contas (chama internamente o GET).

Erros

Status	Quando
400	Plano de contas não existe; Plano de contas superior não existe; Já existe um plano com o mesmo cód. referência externo; Já existe um plano com o mesmo cód. referência interno; IDTypeCategoryAccountPayble não existe; É preciso ter um plano de contas padrão para pedido; É preciso ter um plano de contas padrão para compras.
500	Erro interno.

---

DELETE /type/account/type/{idtypeaccount}

typeAccountTypeDelete · autenticado

Inativa o plano (soft delete — Status=0 e zera o pai). Bloqueios:

• Não é possível excluir um plano com filhos ativos — remova os filhos primeiro.
• Não é possível excluir um plano referenciado em uma parametrização GNRE (GnreIDTypeAccountPayableReceivable) — remova a parametrização primeiro.

Resposta 200 — a lista atual do plano de contas (formato lista plana).

Erros

Status	Quando
400	Plano de contas a receber/pagar não existe; Plano de contas esta na parametrização da empresa. Remover a parametrização antes de excluir o documento; Remover o plano de conta filho antes de excluir o pai.
500	Erro interno.

---

GET /type/account/type/category

typeAccountCategoryList · autenticado

Retorna o catálogo fixo de categorias do plano de contas (TypeAccountPaybleCategory). Compartilhado por todas as empresas — não há filtro por empresa nem por tipo. O identificador vem como string.

Resposta 200 — array de TypeAccountCategoryListItem (ordenado por descrição).

Erros

Status	Quando
500	Erro interno.

---

GET /type/account/document

typeAccountDocumentList · autenticado

Retorna os tipos de documento ativos da empresa, ordenados pela descrição. Cada item indica se o tipo está marcado como padrão para pedidos (DefaultOrder) e/ou para compras (DefaultPurchase). Quando a empresa autenticada é a all (multi-conta), retorna os tipos de todas as empresas vinculadas.

Resposta 200 — array de TypeDocumentListItem:

[
  {
    "AccountName": "exemplo",
    "TypeDocument": "Nota Fiscal",
    "DefaultPurchase": 1,
    "DefaultOrder": 0,
    "IDTypeDocument": "142"
  }
]

IDTypeDocument vem como string (o handler usa CAST(IDTypeDocument AS CHAR)).

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno (prefixo Error:).

---

POST /type/account/document

typeAccountDocumentPost · autenticado

Cria um tipo de documento para a empresa autenticada. Após gravar, o cache do API Gateway para /type/account/document é invalidado. A resposta é a lista completa atualizada dos tipos ativos da empresa (mesmo formato do GET /type/account/document).

Request body — TypeDocumentCreate

Campo	Tipo	Obrigatório	Descrição
TypeDocument	string (≤45)	sim	Descrição do tipo de documento.
DefaultOrder	integer (0/1)	não	1 para marcar como padrão para pedidos de venda; 0/ausente para não marcar.
DefaultPurchase	integer (0/1)	não	1 para marcar como padrão para compras; 0/ausente para não marcar.

Resposta 200 — array de TypeDocumentListItem (lista atualizada).

Erros

Status	Quando
400	[BadRequest] - Empresa não existe.
500	Erro interno (prefixo Error:).

---

PUT /type/account/document/{idtypedocument}

typeAccountDocumentPut · autenticado

Atualiza a descrição e os flags de padrão de um tipo de documento existente. Os três campos são considerados em toda chamada — não é atualização parcial: enviar somente um deles sobrescreverá os outros com vazio/nulo. Após gravar, o cache do API Gateway é invalidado e a resposta é a lista completa atualizada.

Path params

Nome	Tipo	Obrigatório	Descrição
idtypedocument	integer	sim	Identificador do tipo de documento.

Request body — TypeDocumentUpdate

Campo	Tipo	Obrigatório	Descrição
TypeDocument	string (≤45)	sim	Descrição do tipo de documento.
DefaultOrder	integer (0/1)	não	1 para marcar como padrão para pedidos de venda; 0/nulo para desmarcar.
DefaultPurchase	integer (0/1)	não	1 para marcar como padrão para compras; 0/nulo para desmarcar.

Resposta 200 — array de TypeDocumentListItem (lista atualizada).

Erros

Status	Quando
400	[BadRequest] - Tipo Documento não existe (id desconhecido para a empresa, ou já inativo).
500	Erro interno (prefixo Error:).

---

DELETE /type/account/document/{idtypedocument}

typeAccountDocumentDelete · autenticado

Inativa o tipo de documento (Status = 0). Não exclui fisicamente o registro. A exclusão é bloqueada quando o tipo está referenciado na parametrização Tipo de documento para criar contas a pagar GNRE operação da integração GNRE — nesse caso é preciso primeiro trocar a parametrização.

Após gravar, o cache do API Gateway é invalidado e a resposta é a lista completa atualizada dos tipos ativos da empresa.

Path params

Nome	Tipo	Obrigatório	Descrição
idtypedocument	integer	sim	Identificador do tipo de documento.

Resposta 200 — array de TypeDocumentListItem (lista atualizada).

Erros

Status	Quando
400	[BadRequest] - Tipo documento não existe; [BadRequest] - Tipo documento esta na parametrização da empresa. Remover a parametrização antes de excluir o documento.
500	Erro interno (prefixo Error:).

---

GET /type/order/type

typeOrderTypeList · autenticado

Lista os tipos de pedido ativos (Status=1) da empresa autenticada, com a descrição amigável da política comercial, do faturador, dos armazéns (padrão e devolução), do tipo de retorno simbólico e do tipo de devolução, do plano de contas, do centro de custo e da finalidade da NFe. Ordenado por nome.

Query params

Nome	Tipo	Obrigatório	Descrição
EnableFrenteCaixa	integer (0/1)	não	Quando 1, traz apenas tipos com Ativo Frente de Caixa.
IDCompanyInvoice	integer	não	Filtra pelo faturador configurado no tipo.
ServiceRequest	integer (0/1)	não	Quando 1, traz apenas tipos marcados como Ordem de Serviço.

Resposta 200 — array de TypeOrderListItem.

Erros

Status	Quando
400	Erro na configuração da empresa.
500	Erro interno.

---

POST /type/order/type

orderTypeOrderPost · autenticado

Cria um tipo de pedido. Apenas um tipo por empresa pode estar marcado como Default, Resend, Return ou SymbolicReturn — marcar qualquer um em 1 desmarca o anterior automaticamente.

A resposta é a lista completa atual dos tipos de pedido da empresa (mesmo formato do GET).

Body — TypeOrderCreate. Obrigatórios: TypeOrder, OrderPrefix, IDCompanySalesPolicy. TypeOrderOrderPriority aceita 0–10.

Erros

Status	Quando
400	Empresa não existe; Politica comercial não existe; Faturador não existe; Armazém não existe/Armazém devolução não existe; Tipo de pedido para retorno simbólico de armazenagem não localizado; Tipo de pedido de devolução não localizado; Plano de contas não existe; Centro de custo não existe; Prioridade pedido precisa ser entre 0 e 10.
500	Erro interno.

---

GET /type/order/type/{idordertype}

orderTypeOrderGet · autenticado

Detalha o tipo de pedido, acrescido da lista de regras fiscais por departamento (TypeOrderTax[]) — uma entrada por departamento fiscal cadastrado nos SKUs da empresa, com o IDTax já vinculado (ou nulo, se ainda não houver regra associada). Quando o id não existe, devolve [].

Resposta 200 — array com 0 ou 1 elemento de TypeOrderDetail.

Erros

Status	Quando
500	Erro interno.

---

PUT /type/order/type/{idordertype}

orderTypeOrderPut · autenticado

Atualiza um tipo de pedido. As mesmas regras de unicidade e validação do POST valem. A resposta é a lista completa atual de tipos.

Body — TypeOrderCreate (mesmo formato do POST).

Erros

Status	Quando
400	Tipo pedido não existe; mesmas validações do POST.
500	Erro interno.

---

DELETE /type/order/type/{idordertype}

orderTypeOrderDelete · autenticado

Inativa o tipo de pedido (soft delete — Status=0). Antes de inativar, remove todas as regras fiscais (TypeOrderTax) vinculadas.

Bloqueios:

• Tipo já usado em pedidos (Orders).
• Tipo configurado como de/para de armazém (HubWarehouse).
• Tipo configurado como de/para de política comercial (HubSalesPolicy).
• Tipo atrelado a uma conta bancária (BankAccount.IDTypeOrder).
• Tipo referenciado como retorno simbólico de armazenagem (IDTypeOrderSymbolicStorageReturn) por outro tipo.
• Tipo referenciado como devolução padrão (IDTypeOrderDefaultReturn) por outro tipo ativo.

A resposta é a lista completa atual.

Erros

Status	Quando
400	Tipo pedido não existe; Tipo de pedido já tem pedido criado e não pode ser excluído; Tipo de pedido tem de/para de armazém e não pode ser excluído; Tipo de pedido tem de/para de política comercial e não pode ser excluído; Tipo de pedido esta atrelado a conta bancária e não pode ser excluído; Tipo de pedido esta atrelado a tipo de pedido retorno simbólico armazenagem no tipo de pedido <descrição>; Tipo de pedido esta atrelado como tipo de pedido de devolução padrão no tipo de pedido <descrição>.
500	Erro interno.

---

GET /purchase/cfop-inbound

purchaseCfopInboundList · autenticado

Retorna todas as regras de reescrita de CFOP cadastradas pela empresa, ordenadas pelo CFOP de origem. Cada item já vem com a descrição oficial de cada CFOP (resolvida contra o catálogo nacional). Quando a empresa autenticada é a all (multi-conta), retorna as regras de todas as empresas vinculadas.

Resposta 200 — array de PurchaseCfopInboundListItem:

[
  {
    "AccountName": "exemplo",
    "IDStockKeepingUnitPurchaseCfopInbound": 12,
    "IDCompany": 99,
    "CfopFrom": 5102,
    "CfopFromDescription": "Venda de mercadoria adquirida ou recebida de terceiros",
    "CfopTo": 1102,
    "CfopToDescription": "Compra para comercialização",
    "RecordTimestamp": "2024-03-12T10:30:00Z"
  }
]

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno (prefixo Error:).

---

POST /purchase/cfop-inbound

purchaseCfopInboundPost · autenticado

Cria uma regra para a empresa autenticada. Validações:

• CfopFrom e CfopTo precisam existir no catálogo nacional de CFOPs.
• O par CfopFrom + CfopTo ainda não pode estar cadastrado para a empresa (chave única).

A resposta é a lista completa atualizada das regras da empresa (mesmo formato do GET /purchase/cfop-inbound).

Request body — PurchaseCfopInboundCreate

Campo	Tipo	Obrigatório	Descrição
CfopFrom	integer	sim	CFOP de origem (4 dígitos). Precisa existir no catálogo nacional.
CfopTo	integer	sim	CFOP de destino (4 dígitos). Precisa existir no catálogo nacional.

Resposta 200 — array de PurchaseCfopInboundListItem (lista atualizada).

Erros

Status	Quando
400	[BadRequest] - Esta regra já existe e não será adicionada novamente; [BadRequest] - CFOP de origem <X> não existe; [BadRequest] - CFOP de destino <X> não existe; [BadRequest] - Empresa não existe.
500	Erro interno (prefixo Error:).

---

PUT /purchase/cfop-inbound/{idstockkeepingunitpurchasecfopinbound}

purchaseCfopInboundPut · autenticado

Atualiza o par CfopFrom/CfopTo de uma regra existente. Os dois campos são considerados em toda chamada (não é atualização parcial). Aplica as mesmas validações do POST: catálogo nacional e não-duplicidade. A resposta é a lista completa atualizada.

Path params

Nome	Tipo	Obrigatório	Descrição
idstockkeepingunitpurchasecfopinbound	integer	sim	Identificador da regra.

Request body — PurchaseCfopInboundUpdate

Campo	Tipo	Obrigatório	Descrição
CfopFrom	integer	sim	CFOP de origem (4 dígitos). Precisa existir no catálogo nacional.
CfopTo	integer	sim	CFOP de destino (4 dígitos). Precisa existir no catálogo nacional.

Resposta 200 — array de PurchaseCfopInboundListItem (lista atualizada).

Erros

Status	Quando
400	[BadRequest] - De/Para de CFOP não existe; [BadRequest] - Esta regra já existe e não será adicionada novamente; [BadRequest] - CFOP de origem <X> não existe; [BadRequest] - CFOP de destino <X> não existe.
500	Erro interno (prefixo Error:).

---

DELETE /purchase/cfop-inbound/{idstockkeepingunitpurchasecfopinbound}

purchaseCfopInboundDelete · autenticado

Remove fisicamente o registro (não é exclusão lógica — não há flag de status na tabela). A operação é sempre permitida quando a regra pertence à empresa, sem regras de bloqueio. A resposta é a lista completa atualizada.

Path params

Nome	Tipo	Obrigatório	Descrição
idstockkeepingunitpurchasecfopinbound	integer	sim	Identificador da regra.

Resposta 200 — array de PurchaseCfopInboundListItem (lista atualizada).

Erros

Status	Quando
400	[BadRequest] - De/Para de CFOP não existe.
500	Erro interno (prefixo Error:).

---

GET /webhook

webhookList · autenticado

Retorna o histórico de envios de webhook da empresa, do mais recente para o mais antigo. Cada item é uma tentativa identificada pelo UUID da mensagem SQS original — o campo Attempts indica quantas vezes a tentativa foi retentada. Paginação por Page (2000 itens por página).

Como o registro nasce: quando uma ação habilitada no idworks ocorre (criar SKU, emitir NF, atualizar tracking, etc.), o handler enfileira a notificação na fila SQS webhook.fifo. O consumidor webhookPost lê a fila, busca no Redis a integração Webhook da empresa (IDTypeCompanyIntegration = 52) e suas parametrizações (endpoint, credenciais e flags por tópico). Se o tópico está ligado e o endpoint configurado, faz um POST JSON com timeout de 10 s e grava o resultado nesta tabela. Falhas devolvem o item para a fila, e a próxima execução incrementa Attempts no mesmo registro.

Query params

Nome	Tipo	Obrigatório	Descrição
Page	integer	não	Página zero-based. Cada página devolve no máximo 2000 itens. Default: 0.
Topic	string	não	Filtra pelo nome técnico do tópico (SkuPost, InvoiceIssue, OrderStatus, etc.). Match exato.
Status	integer (0/1)	não	1 = sucesso (destino respondeu 2xx); 0 = erro.
DateFrom	string (date)	não	Data inicial do RecordTimestamp (inclusive).
DateTo	string (date)	não	Data final do RecordTimestamp, inclusivo até 23:59:59.

Resposta 200 — array de WebhookLogListItem:

[
  {
    "IDWebhookLog": 56821934,
    "RecordTimestamp": "2024-03-12T10:30:00Z",
    "IDCompany": 99,
    "AccountName": "exemplo",
    "Topic": "SkuPost",
    "EndPoint": "https://api.cliente.com.br/webhook/idworks",
    "PostData": "{\"Topic\":\"SkuPost\",\"IDSku\":12345,\"Url\":\"/sku/12345\",\"AccountName\":\"exemplo\",\"ModificationTimestamp\":\"2024-03-12 10:30:00\"}",
    "ResponseData": "{\"ok\":true}",
    "Status": 1,
    "StatusName": "Sucesso",
    "Attempts": 1
  }
]

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno (prefixo Error:).

---

GET /user/privilege-group

userPrivilegeGroupList · autenticado

Retorna os perfis de acesso ativos da empresa, ordenados pelo nome. Cada item é só o cabeçalho do perfil — para ver a lista de privilégios atribuídos, use GET /user/privilege-group/{idprivilegegroup}. Quando a empresa autenticada é a all (multi-conta), retorna os perfis de todas as empresas vinculadas.

Resposta 200 — array de UserPrivilegeGroupListItem:

[
  {
    "AccountName": "exemplo",
    "IDUserPrivilegeGroup": 142,
    "PrivilegeGroupName": "Financeiro",
    "IDCompany": 99,
    "RecordUserCreated": 7,
    "IsConsumer": 0,
    "UserPrivilegeGroupStatus": 1,
    "RecordTimestamp": "2024-03-12T10:30:00Z"
  }
]

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno (prefixo Error:).

---

POST /user/privilege-group

userPrivilegeGroupPost · autenticado

Cria um perfil vazio para a empresa autenticada — só com o nome. Para atribuir os privilégios, chame em seguida POST /user/privilege-group/{idprivilegegroup}/resource com a lista de IDUserPrivilege. A resposta é o detalhe do perfil recém-criado (sem nenhum privilégio ainda — array vazio).

Request body — UserPrivilegeGroupCreate

Campo	Tipo	Obrigatório	Descrição
PrivilegeGroupName	string (≤100)	sim	Nome do perfil. Sem restrição de duplicidade.

Resposta 200 — array de UserPrivilegeGroupDetail (vazio logo após o POST).

Erros

Status	Quando
400	[BadRequest] - Company não existe.
500	Erro interno (prefixo Error:).

---

GET /user/privilege-group/{idprivilegegroup}

userPrivilegeGroupGet · autenticado

Retorna os privilégios atribuídos ao perfil, agrupados por área do menu (ModuleGroupDescription) e, dentro de cada área, por módulo (ModuleDescription).

⚠ A resposta NÃO traz privilégios disponíveis que ainda não foram atribuídos ao perfil — a tela do frontend cruza este resultado com GET /company/module (catálogo completo) para renderizar os checkboxes marcados e desmarcados.

Quando o perfil ainda está vazio (logo após o POST), a resposta é [].

Path params

Nome	Tipo	Obrigatório	Descrição
idprivilegegroup	integer	sim	Identificador do perfil.

Resposta 200 — array de UserPrivilegeGroupDetail:

[
  {
    "Module": [
      {
        "ModuleGroupDescription": "Financeiro",
        "ModuleDescription": "Contas a Pagar",
        "IDModule": 4,
        "Privilege": [
          { "UserPrivilege": "PrivilegeAccountsPayableView", "IDUserPrivilege": 11, "PrivilegeDescription": "Visualizar contas a pagar" },
          { "UserPrivilege": "PrivilegeAccountsPayableCreate", "IDUserPrivilege": 12, "PrivilegeDescription": "Criar contas a pagar" }
        ]
      }
    ]
  }
]

Erros

Status	Quando
500	Erro interno (prefixo Error:).

---

PUT /user/privilege-group/{idprivilegegroup}

userPrivilegeGroupPut · autenticado

Atualiza apenas o nome do perfil. Para alterar os privilégios, use POST /user/privilege-group/{idprivilegegroup}/resource.

Path params

Nome	Tipo	Obrigatório	Descrição
idprivilegegroup	integer	sim	Identificador do perfil.

Request body — UserPrivilegeGroupUpdate

Campo	Tipo	Obrigatório	Descrição
PrivilegeGroupName	string (≤100)	sim	Novo nome do perfil.

Resposta 200 — array de UserPrivilegeGroupDetail (mesmo formato do GET).

Erros

Status	Quando
400	[BadRequest] - Privelege Group não existe.
500	Erro interno (prefixo Error:).

---

DELETE /user/privilege-group/{idprivilegegroup}

userPrivilegeGroupDelete · autenticado

Inativa o perfil (UserPrivilegeGroupStatus = 0) e remove fisicamente todos os vínculos com privilégios (UserPrivilegeGroupResource). A exclusão é bloqueada quando o perfil ainda está vinculado a algum usuário (UserPrivilege).

Path params

Nome	Tipo	Obrigatório	Descrição
idprivilegegroup	integer	sim	Identificador do perfil.

Resposta 200 — array de UserPrivilegeGroupListItem (lista atualizada dos perfis ativos).

Erros

Status	Quando
400	[BadRequest] - Grupo privilégio não existe; [BadRequest] - Perfil de acesso esta vinculado a usuários e não pode ser excluído.
500	Erro interno (prefixo Error:).

---

POST /user/privilege-group/{idprivilegegroup}/resource

userPrivilegeGroupResourcePost · autenticado

Sobrescreve a lista de privilégios atribuídos ao perfil — não é incremento. O body é um array com os IDUserPrivilege que devem ficar atribuídos: tudo que estava antes e não está no array é removido, tudo que está no array passa a ser atribuído.

A cada chamada o sistema:

1. Grava um registro de auditoria em UserPrivilegeGroupLog com o usuário que fez a alteração, o Data enviado e o id do perfil.
2. Apaga todas as linhas de UserPrivilegeGroupResource do perfil e insere a nova lista.
3. Atualiza o cache Redis dos usuários vinculados a este perfil (chave UserPrivilege:<accountname>:<iduser>, TTL de 7 dias) com a nova lista de IDs de privilégio agregados de todos os perfis do usuário na empresa.
4. Chama internamente userPrivilegeGroupGet e devolve o detalhe do perfil atualizado.

⚠ A alteração só passa a valer para o usuário depois que ele faz logout e login de novo no sistema — o cache do navegador (do usuário) ainda guarda os privilégios da sessão atual.

Path params

Nome	Tipo	Obrigatório	Descrição
idprivilegegroup	integer	sim	Identificador do perfil.

Request body — array de IDUserPrivilege (inteiros). Pode ser vazio para deixar o perfil sem nenhum privilégio.

[11, 12, 138, 139, 140]

Resposta 200 — array de UserPrivilegeGroupDetail.

Erros

Status	Quando
400	[BadRequest] - Privilegio não existe.
500	Erro interno (prefixo Error:).

---

GET /job

jobsResultList · autenticado

Retorna os jobs disparados pela empresa, do mais recente para o mais antigo. Cada item é o cabeçalho do job — para ver os resultados linha a linha, use GET /job/{idjob}. Quando a empresa autenticada é a all (multi-conta), retorna jobs de todas as empresas vinculadas.

Query params

Nome	Tipo	Obrigatório	Descrição
IDTypeJob	integer	não	Filtra pelo tipo da ação. Match exato com TypeJob.IDTypeJob. Ex.: 1=Criar sku/produto, 3=Criar pedido, 6=Criar Contas a pagar, 7=Criar Contas a receber, 38=Importar extrato OFX, 41=Importar conciliação adquirente.

Resposta 200 — array de JobListItem (ordenado por RecordTimestamp DESC).

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno (prefixo Error:).

---

POST /job

jobsResultPost (via asyncLambdaGateway) · autenticado

Dispara um job de ação em massa a partir de um upload de planilha. O fluxo do handler:

1. Valida o IDTypeJob contra TypeJob (cada tipo aponta para uma função Lambda — skuFileTemplateImport, orderTemplateImport, etc.).
2. Faz upload do arquivo (multipart/form-data no campo file) para o S3 em Temp/<accountname>_<uuid>.<ext> e calcula o hash SHA-256 do conteúdo.
3. Se já existe um Jobs da mesma empresa com o mesmo hash ainda em processamento (StartedAt IS NOT NULL AND FinishedAt IS NULL), reaproveita o job e devolve o IDJob existente — bloqueio anti-duplicação.
4. Caso contrário, grava um novo Jobs e invoca a função Lambda associada assincronamente (InvocationType: Event).
5. Devolve IDJob ao cliente. O resultado real é gravado em JobsResult linha a linha pela função invocada, e o usuário recebe a confirmação por e-mail. Acompanhe via GET /job/{idjob}.

⚠ Limite do frontend: arquivos com mais de 5 MB são rejeitados antes do upload.

Query params

Nome	Tipo	Obrigatório	Descrição
IDTypeJob	integer	sim	Identificador do tipo de ação (TypeJob). Define qual função Lambda processa o arquivo.
IDBankAccount	integer	condicional	Obrigatório quando IDTypeJob = 38 (Importar extrato OFX). Vai como Metadata do job.
IDCompanyIntegration	integer	condicional	Obrigatório quando IDTypeJob = 41 (Importar conciliação adquirente). Vai como Metadata.
IDSupplier	integer	não	Usado por tabela de frete (IDTypeJob 4, 5, 10). Vai como Metadata.

Request body — multipart/form-data com campo file (planilha .xlsx ou .xls).

Resposta 200 — JobPostResponse:

{
  "IDJob": 12345,
  "Message": "Arquivo em processamento, aguardar resposta por email"
}

Erros

Status	Quando
400	[BadRequest] - Ação não encontrada; [BadRequest] - Erro ao processar ação em massa; [BadRequest] - IDBankAccount é obrigatório; [BadRequest] - IDCompanyIntegration é obrigatório. 400 sem corpo quando o file está ausente em uma ação que exige arquivo.
404	Empresa do accountname não localizada (sem corpo).
500	Erro interno (prefixo Error:).

---

GET /job/{idjob}

jobsResultGet · autenticado

Retorna o cabeçalho do job e o array Result com uma entrada por linha processada (aba Sheet, número da linha, status, descrição, id e nome do recurso afetado). A resposta também traz uma URL pré-assinada S3 (UrlFile) para baixar o arquivo enviado, válida por 2 dias.

Quando o idjob não pertence à empresa autenticada, a resposta é [].

Path params

Nome	Tipo	Obrigatório	Descrição
idjob	integer	sim	Identificador do job.

Query params

Nome	Tipo	Obrigatório	Descrição
Page	integer	não	Página zero-based da lista Result. Cada página devolve no máximo 5000 linhas. Default: 0.

Resposta 200 — array com 1 elemento do schema JobDetail (ou []):

[
  {
    "IDJob": 12345,
    "IDCompany": 99,
    "AccountName": "exemplo",
    "IDTypeJob": 6,
    "TypeJob": "Criar Contas a pagar",
    "Login": "joao@exemplo.com.br",
    "RecordTimestamp": "2024-03-12T10:30:00Z",
    "StartedAt": "2024-03-12T10:30:05Z",
    "FinishedAt": "2024-03-12T10:31:18Z",
    "IDFile": "exemplo_abc123.xlsx",
    "FileHash": "Yh+ScP3...=",
    "Metadata": null,
    "UrlFile": "https://s3.sa-east-1.amazonaws.com/idworks-bucket/Temp/exemplo_abc123.xlsx?X-Amz-...",
    "Result": [
      { "IDJobsResult": 7820001, "Sheet": "Sheet1", "Line": 2, "Status": 1, "StatusName": "Sucesso", "Description": "Conta criada", "ID": 80012, "Name": "Boleto fornecedor X" },
      { "IDJobsResult": 7820002, "Sheet": "Sheet1", "Line": 3, "Status": 0, "StatusName": "Erro",    "Description": "Fornecedor não cadastrado", "ID": null, "Name": null }
    ]
  }
]

Erros

Status	Quando
500	Erro interno (prefixo Error:).

---

GET /company/integration

companyParameterList · autenticado

Lista as integrações configuradas pela empresa. Cada item traz o tipo já resolvido (logo, nome, categoria, AuthUrl) e o nível de reputação consolidado a partir das parametrizações. Quando a empresa autenticada é a all (multi-conta), retorna integrações de todas as empresas vinculadas.

Query params

Nome	Tipo	Obrigatório	Descrição
IDTypeCompanyIntegrationCategory	string	não	Filtra por categoria do tipo. Aceita id único ou lista separada por vírgula (ex.: 1,4).
IDTypeCompanyIntegration	integer	não	Filtra pelo tipo (TypeCompanyIntegration.IDTypeCompanyIntegration).
IDCompanyIntegration	integer	não	Filtra pelo identificador específico da integração da empresa.
Status	integer (0/1/2/3)	não	1=Ativo, 2=Erro de autenticação, 3=Não autenticado, 0=Inativo.
GiftCard	integer (0/1)	não	Filtra pela flag TypeCompanyIntegration.GiftCard.

Resposta 200 — array de CompanyIntegrationListItem (ordenado por IntegrationName ASC).

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno (prefixo Error:).

---

POST /company/integration

companyParameterPost · autenticado

Cria uma CompanyIntegration a partir de um IDTypeCompanyIntegration. A integração nasce com Status = 3 (Não Autenticado) quando o tipo tem parametrização com Key = "Validate" no catálogo; caso contrário, com Status = 1 (Ativo). As parametrizações em si são preenchidas depois com PUT .../parameter.

Efeitos colaterais:

1. Atualiza o cache Redis CompanyIntegration:<idcompany> com as integrações ativas.
2. Invalida o cache do API Gateway para /company/integration e /company/integration?IDTypeCompanyIntegration=<id>.
3. Devolve o detalhe da integração recém-criada — array de parametrizações (vazio até o usuário preencher).

Request body — CompanyIntegrationCreate

Campo	Tipo	Obrigatório	Descrição
IDTypeCompanyIntegration	integer	sim	Tipo de integração. Precisa existir em TypeCompanyIntegration.
CompanyIntegrationName	string (≤500)	sim	Nome da integração (livre).

Resposta 200 — array de CompanyIntegrationParameter (vazio na criação).

Erros

Status	Quando
400	[BadRequest] - Tipo integração não existe; [BadRequest] - Empresa não existe.
500	Erro interno (prefixo Error:).

---

GET /company/integration/{idcompanyintegration}

companyParameterGet · autenticado

Retorna o conjunto de parametrizações que o tipo da integração expõe, com o valor gravado para a empresa e (quando aplicável) a lista de opções resolvida. Esta é a fonte da seção de configuração de cada integração na UI.

Cada item traz Key (técnica), KeyName (PT), Description, Type (string, password, boolean, list, multi_list, string_copy, url_get etc.), IDTypeCompanyParametersGroup + TypeCompanyParametersGroup (grupo lógico), Value (atual) e List (opções, quando aplicável).

⚠ Para tipos string_copy e url_get, o Value pode ser calculado pelo handler em vez de vir do banco — por exemplo, URLs de webhook personalizadas para a empresa, com tokens embutidos.

Modos:

• Sem Type: comportamento padrão (array de parametrizações).
• Type=ImportOffer: muda o retorno — devolve o último Jobs da empresa para esta integração com contadores QuantityProcessed, QuantityPending, QuantityTotal. Usado pela tela de importação automática de anúncios.

Path params

Nome	Tipo	Obrigatório	Descrição
idcompanyintegration	integer	sim	Identificador da integração.

Query params

Nome	Tipo	Obrigatório	Descrição
Type	string (ImportOffer)	não	Alterna o retorno para o resumo do último job de importação automática.

Resposta 200 — array de CompanyIntegrationParameter (ou de resumo de job quando Type=ImportOffer). Vazio ([]) quando a integração ainda não tem nenhuma parametrização gravada.

Erros

Status	Quando
500	Erro interno (prefixo Error:).

---

PUT /company/integration/{idcompanyintegration}

companyIntegrationPut · autenticado

Atualiza nome e status da integração. Os outros dados (tipo, parametrizações) ficam intocados. Quando Status = 1 (Ativo), o sistema atualiza o cache Redis CompanyParameter:<idcompanyintegration> com as parametrizações ativas e — se for tipo 16 (idworks) — também CompanyParameterIDWorks:<accountname>. Em qualquer status, atualiza CompanyIntegration:<idcompany> com a lista de integrações ativas.

Path params

Nome	Tipo	Obrigatório	Descrição
idcompanyintegration	integer	sim	Identificador da integração.

Request body — CompanyIntegrationUpdate

Campo	Tipo	Obrigatório	Descrição
CompanyIntegrationName	string (≤500)	não	Novo nome.
Status	integer (0/1)	não	Novo status. 1 reativa, 0 inativa (sem limpar Hub/parametrizações — isso é o DELETE).

Resposta 200 — array de CompanyIntegrationParameter (mesmo formato do GET).

Erros

Status	Quando
400	[BadRequest] - Integração não existe.
500	Erro interno (prefixo Error:).

---

DELETE /company/integration/{idcompanyintegration}

companyIntegrationDelete · autenticado

Inativa a integração (Status = 0, Show = 0) e remove fisicamente todas as parametrizações (CompanyParameters) e todos os mapas de Hub (HubCategory, HubBrand, HubCarrier, HubPayment, HubSalesPolicy, HubVariation, HubWarehouse).

Bloqueios por categoria:

• Transportadora (categoria 3): bloqueia quando há fornecedor ativo com esta integração. Fornecedores inativos são desvinculados (limpa IDCompanyIntegration).
• Banco / Adquirente / Gateway (categorias 2, 9, 4): bloqueia quando há conta bancária ativa vinculada. Contas inativas são desvinculadas.
• Anúncios: bloqueia quando há HubProduct apontando para esta integração — é preciso excluir os anúncios antes.

Path params

Nome	Tipo	Obrigatório	Descrição
idcompanyintegration	integer	sim	Identificador da integração.

Resposta 200 — array de CompanyIntegrationListItem (lista atualizada).

Erros

Status	Quando
400	[BadRequest] - Integração não existe; [BadRequest] - Existe fornecedor vinculado a essa integração, remover antes de excluir a integração; [BadRequest] - Existe conta bancária vinculada a essa integração, remover antes de excluir a integração; [BadRequest] - Integração possui anúncios, excluir antes de deletar a integração.
500	Erro interno (prefixo Error:).

---

GET /company/integration/{idcompanyintegration}/check

companyIntegrationCheckGet · autenticado

Faz uma checagem síncrona das credenciais da integração no sistema externo (chama um endpoint PHP do Worker). O endpoint chamado depende do tipo:

• Tipo 50 (Correios): /carrier/correios/credscheck.php
• Tipo 51 (E-mail): /admin/email/credscheck.php
• Outros com PathName definido: /saleschannel/<PathName>/credscheck.php

A resposta é o que o Worker devolver (formato varia por integração).

Path params

Nome	Tipo	Obrigatório	Descrição
idcompanyintegration	integer	sim	Identificador da integração.

Resposta 200 — objeto livre devolvido pelo Worker.

Erros

Status	Quando
400	[BadRequest] - Integração não encontrada; [BadRequest] - Integracão não tem consulta de status (tipo sem suporte ou Worker devolveu 404); mensagem do Worker em outros casos.
500	Erro interno (prefixo Error:).

---

PUT /company/integration/{idcompanyintegration}/parameter

companyParameterPut · autenticado

Sobrescreve (upsert) os valores das parametrizações da integração. O body é um array de {Key, Value} — para cada item, o handler:

1. Valida que a Key é uma parametrização válida do tipo da integração (TypeCompanyParameters com Type diferente de hidden, string_copy e url_validate).
2. Faz INSERT ... ON DUPLICATE KEY UPDATE em CompanyParameters (chave única IDCompanyIntegration + Key).
3. Grava o evento em CompanyParametersLog com o usuário e o body como Data.
4. Atualiza CompanyParameter:<idcompanyintegration> no Redis com o snapshot completo.
5. Para integração do tipo 16 (idworks), atualiza também CompanyParameterIDWorks:<accountname> com o snapshot "achatado" (chaves como propriedades).

Não é necessário enviar todas as parametrizações — só as que mudaram. A resposta repete o detalhe da integração (mesmo formato do GET).

Path params

Nome	Tipo	Obrigatório	Descrição
idcompanyintegration	integer	sim	Identificador da integração.

Request body — array de CompanyParameterValue:

[
  { "Key": "EndPoint", "Value": "https://api.cliente.com.br/webhook" },
  { "Key": "HeaderKeyAuth", "Value": "Authorization" },
  { "Key": "HeaderValueAuth", "Value": "Bearer abc123" },
  { "Key": "SkuPost", "Value": "1" }
]

Resposta 200 — array de CompanyIntegrationParameter.

Erros

Status	Quando
400	[BadRequest] - Integração não existe.
500	Erro interno (prefixo Error:).

---

POST /company/integration/{idcompanyintegration}/parameter/import

companyParameterImportPost · autenticado

Proxy para o Worker PHP: chama setup/saleschannel/automaticimportoffers.php passando accountname e idcompanyintegration (mais quaisquer outros parâmetros recebidos em query). Usado pela tela de importação direto do canal para popular o HubProductImportTemp da integração.

A resposta é o que o Worker devolver.

Path params

Nome	Tipo	Obrigatório	Descrição
idcompanyintegration	integer	sim	Identificador da integração.

Resposta 200 — objeto livre devolvido pelo Worker.

Erros

Status	Quando
400	Falha do Worker. Devolve o errorMessage recebido.
500	Erro interno (prefixo Error:).

---

GET /sku/production

skuProductionList · autenticado

Retorna as ordens de produção da empresa, com SKU produzido, status, armazém, pedido vinculado (quando há) e dados do usuário criador. Aceita filtros opcionais por id, SKU, status e faixa de data de cadastro.

Query params

Nome	Tipo	Obrigatório	Descrição
IDStockKeepingUnitProduction	integer	não	Filtra por id específico da OP.
IDSku	integer	não	Filtra pelo SKU produzido.
IDSkuCompany	string	não	Filtra pelo código externo do SKU.
IDTypeStatusSkuProduction	integer (1–4)	não	1=Finalizado, 2=Aberto, 3=Em andamento, 4=Cancelado.
DateFrom	string (date)	não	Faixa inicial de RecordTimestamp.
DateTo	string (date)	não	Faixa final, inclusivo até 23:59:59.

Resposta 200 — array de ProductionListItem.

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno.

---

POST /sku/production

skuProductionPost · autenticado

Cria uma OP para um SKU configurado com produção própria. Efeitos imediatos:

1. Gera lançamentos de consumo (StockKeepingUnitMovement tipo 1) para cada componente do kit do SKU, na quantidade necessária × Quantity, debitando o saldo do armazém indicado.
2. Valida que cada componente tem saldo suficiente — falha quando faltar.
3. Custo dos consumos segue a parametrização UseCostFromCostSet da empresa: quando ativa, usa CostSet do SKU; senão, calcula pelo saldo (InventoryValue / QtyAvailable).
4. Copia as etapas da StockKeepingUnitProductionLine vinculada ao SKU (ou da linha padrão da empresa) para StockKeepingUnitProductionSteps.
5. Status inicial = 2 (Aberto). A resposta é o detalhe da OP no formato de GET /sku/production/{idstockkeepingunitproduction}.

Request body — ProductionCreate

Campo	Tipo	Obrigatório	Descrição
IDSku	integer	sim	SKU a produzir. Precisa ter OwnProduction = 1.
Quantity	number	sim	Quantidade a produzir.
IDStockKeepingUnitWarehouse	integer	sim	Armazém de consumo e destino.
DateEstimated	string (date)	não	Data estimada de conclusão.
Comments	string (≤1000)	não	Observações.
IDOrder	integer	não	Pedido que originou a OP.

Resposta 200 — array com 1 item de ProductionDetail.

Erros

Status	Quando
400	[BadRequest] - Empresa não existe; [BadRequest] - Sku não existe; [BadRequest] - Sku não tem produção própria; [BadRequest] - Armazém não existe; [BadRequest] - Pedido não existe; [BadRequest] - Sku: <id> Quantidade disponível (<x>) menor que quantidade solicitada (<y>); [BadRequest] - Sku não tem saldo disponível.
500	Erro interno.

---

GET /sku/production/{idstockkeepingunitproduction}

skuProductionGet · autenticado

Retorna a OP completa: cabeçalho, custo total (soma de ValueCostTotal dos movimentos), array de itens consumidos (com SKU, quantidade, custo total e unitário, armazém) e array de etapas (com status, tempo gasto informado e tempo decorrido entre início e fim, além do usuário que finalizou). Inclui também TimeSpentTotal e TimeElapsedTotal agregados.

Resposta 200 — array com 1 item de ProductionDetail.

Erros

Status	Quando
500	Erro interno.

---

PUT /sku/production/{idstockkeepingunitproduction}

skuProductionPut · autenticado

Atualiza campos editáveis (DateEstimated, Comments, IDTypeStatusSkuProduction, IDOrder) — apenas os enviados são alterados. Bloqueado quando a OP está Finalizada com pedido vinculado ou Cancelada. Devolve o detalhe atualizado.

Request body — ProductionUpdate.

Erros

Status	Quando
400	[BadRequest] - Produção não existe; [BadRequest] - Produção esta finalizada; [BadRequest] - Produção esta cancelada; [BadRequest] - Status não existe.
500	Erro interno.

---

DELETE /sku/production/{idstockkeepingunitproduction}

skuProductionDelete · autenticado

Cancelamento lógico: marca a OP como IDTypeStatusSkuProduction = 4 e remove fisicamente os movimentos de consumo (StockKeepingUnitMovement.IDStockKeepingUnitProduction = ?) e as etapas (StockKeepingUnitProductionSteps). Reverte o saldo dos insumos no armazém. Bloqueado quando a OP já está Finalizada ou Cancelada. A resposta é o detalhe da OP cancelada.

Erros

Status	Quando
400	[BadRequest] - Produção não existe; [BadRequest] - Produção esta finalizada; [BadRequest] - Produção esta cancelada.
500	Erro interno.

---

POST /sku/production/{idstockkeepingunitproduction}/finish

skuProductionFinishPost · autenticado

Finaliza a OP marcando como IDTypeStatusSkuProduction = 1. Efeitos colaterais:

1. Cria um Recebimento (purchasePost) ou reaproveita o IDPurchase enviado no body. O fornecedor é o fornecedor padrão de recebimento da empresa (Suppliers.DefaultPurchase = 1).
2. Lança no recebimento o produto produzido (purchaseSkuPost com BypassValidation=1) na quantidade e custo total acumulados da OP.
3. Atualiza os movimentos de consumo (IDStatusSku = 1).
4. Vincula o IDPurchase no registro da OP.

Bloqueado quando a OP já está Finalizada/Cancelada. Devolve o detalhe do Recebimento gerado (mesmo formato de GET /purchase/{idpurchase}).

Request body — ProductionFinish (opcional; ambos os campos opcionais).

Erros

Status	Quando
400	[BadRequest] - Produção não existe; [BadRequest] - Produção esta finalizada; [BadRequest] - Produção esta cancelada; [BadRequest] - Não existe fornecedor padrão para recebimento cadastrado; [BadRequest] - Erro ao criar recebimento.
500	Erro interno.

---

POST /sku/production/{idstockkeepingunitproduction}/sku

skuProductionSkuPost · autenticado

Adiciona um insumo consumido extra à OP (além dos componentes copiados na criação). O SKU informado precisa ser tipo SKU (3), matéria-prima (6) ou variante (7), ter saldo disponível no armazém indicado (default = o armazém da OP). Custo segue UseCostFromCostSet. Bloqueado quando a OP está Finalizada/Cancelada. Devolve o detalhe da OP.

Request body — ProductionSkuAdd.

Erros

Status	Quando
400	[BadRequest] - Produção não existe; [BadRequest] - Item não é do tipo Sku ou matéria prima; [BadRequest] - Sku não existe; [BadRequest] - Sku não tem saldo disponível; [BadRequest] - Quantidade disponível (<x>) menor que quantidade solicitada (<y>).
500	Erro interno.

---

PUT /sku/production/{idstockkeepingunitproduction}/sku/{idskumovement}

skuProductionSkuPut · autenticado

Edita um item já consumido na OP: quantidade, armazém, custo total e observações. Quando aumenta a quantidade, valida saldo disponível no armazém para a diferença. Bloqueado quando OP está Finalizada/Cancelada.

Request body — ProductionSkuUpdate.

Erros

Status	Quando
400	[BadRequest] - Produção não existe; [BadRequest] - Produção esta finalizada; [BadRequest] - Produção esta cancelada; [BadRequest] - Armazém não existe; [BadRequest] - Quantidade disponível (<x>) menor que quantidade adicional solicitada (<y>); [BadRequest] - Sku não tem saldo disponível.
500	Erro interno.

---

DELETE /sku/production/{idstockkeepingunitproduction}/sku/{idskumovement}

skuProductionSkuDelete · autenticado

Remove uma linha de insumo consumido. Bloqueado quando OP está Finalizada/Cancelada.

Erros

Status	Quando
400	[BadRequest] - Produção não existe; [BadRequest] - Produção esta finalizada; [BadRequest] - Produção esta cancelada.
500	Erro interno.

---

PUT /sku/production/{idstockkeepingunitproduction}/steps/{idstockkeepingunitproductionsteps}

skuProductionStepsPut · autenticado

Marca o progresso de uma etapa específica da OP — muda o status e registra o tempo gasto. Regras:

• IDTypeStatusSkuProduction = 3 (Em andamento) → grava RecordTimestampStart = NOW().
• IDTypeStatusSkuProduction = 1 (Finalizado) → grava RecordTimestampEnd = NOW() e RecordUserCreatedEnd (usuário autenticado).
• Outros valores apenas atualizam o status.

Como efeito colateral, a OP-mãe passa para status 3 (Em andamento) — sai do Aberto. Devolve o detalhe da OP.

Request body — ProductionStepUpdate.

Erros

Status	Quando
400	[BadRequest] - Etapa produção não existe.
500	Erro interno.

---

GET /sku/production/line

skuProductionLineList · autenticado

Retorna as linhas de produção ativas da empresa, cada uma com a contagem de etapas (QtySteps) e o array de etapas (StockKeepingUnitProductionLineSteps) ordenado por ProductionLineStepOrder.

Query params

Nome	Tipo	Obrigatório	Descrição
IDStockKeepingUnitProductionLine	integer	não	Filtra por id da linha.
ProductionLineName	string	não	Filtra por nome exato.

Resposta 200 — array de ProductionLineListItem.

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno.

---

POST /sku/production/line

skuProductionLinePost · autenticado

Cria uma linha sem etapas (etapas são adicionadas depois com POST .../steps). Quando Default = 1, desmarca a linha que estava como padrão antes — apenas uma linha pode ser padrão por empresa. A resposta repete o formato da listagem.

Request body — ProductionLineCreate.

Erros

Status	Quando
400	[BadRequest] - Empresa não existe.
500	Erro interno.

---

PUT /sku/production/line/{idstockkeepingunitproductionline}

skuProductionLinePut · autenticado

Atualiza o nome e/ou a flag de padrão. Quando muda para Default = 1, desmarca a linha que estava como padrão. Quando muda para Default = 0, exige que outra linha já esteja marcada como padrão — não permite ficar sem padrão.

Request body — ProductionLineUpdate.

Erros

Status	Quando
400	[BadRequest] - Linha de produção não existe; [BadRequest] - É preciso ter uma linha de produção padrão.
500	Erro interno.

---

DELETE /sku/production/line/{idstockkeepingunitproductionline}

skuProductionLineDelete · autenticado

Remove fisicamente o registro. Bloqueado quando a linha ainda tem etapas cadastradas ou produtos vinculados. Devolve a string "Sucesso".

Erros

Status	Quando
400	[BadRequest] - Linha de produção não existe; [BadRequest] - Precisa excluir etapas de produção antes de excluir a linha; [BadRequest] - Há produtos com essa linha de produção, remover no cadastro do produto antes de excluir a linha; [BadRequest] - Erro ao excluir linha de produção.
500	Erro interno.

---

POST /sku/production/line/{idstockkeepingunitproductionline}/steps

skuProductionLineStepPost · autenticado

Adiciona uma etapa à linha. ProductionLineStepOrder é decimal (3,1) — permite inserir entre etapas existentes com 1.5. Devolve a lista atualizada de linhas.

Request body — ProductionLineStepCreate.

Erros

Status	Quando
400	[BadRequest] - Linha de produção não existe.
500	Erro interno.

---

PUT /sku/production/line/{idstockkeepingunitproductionline}/steps/{idstockkeepingunitproductionlinesteps}

skuProductionLineStepPut · autenticado

Atualiza nome e/ou ordem de uma etapa de linha. Devolve a lista atualizada.

Erros

Status	Quando
400	[BadRequest] - Etapa da linha de produção não existe.
500	Erro interno.

---

DELETE /sku/production/line/{idstockkeepingunitproductionline}/steps/{idstockkeepingunitproductionlinesteps}

skuProductionLineStepDelete · autenticado

Exclui fisicamente a etapa. Atenção: ordens de produção criadas antes mantêm as etapas que foram copiadas no momento da criação.

Erros

Status	Quando
400	[BadRequest] - Etapa da linha de produção não existe.
500	Erro interno.

---

GET /carrier/tracking-template

trackingTemplateList · autenticado

Retorna os templates de Mensagem Tracking da empresa, ordenados por EmailTitle. Cada item já vem com o status do tracking resolvido (StatusTracking), o tipo do template (TypeCarrierTrackingTemplate = e-mail ou WhatsApp), o nome da integração de mensagem (CompanyIntegration = IntegrationName - CompanyIntegrationName), além das listas de integração de origem (IDCompanyIntegrationOrderList) e tipo de pedido (IDTypeOrderList) devolvidas como arrays a partir do CSV armazenado no banco.

Query params

Nome	Tipo	Obrigatório	Descrição
IDCarrierTrackingTemplate	integer	não	Filtra por id específico do template.

Resposta 200 — array de TrackingTemplateListItem (até 1000 itens).

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno.

---

POST /carrier/tracking-template

trackingTemplatePost · autenticado

Cria um template para a empresa autenticada. Validações:

• CC e CCO (quando preenchidos) precisam ter e-mails válidos separados por vírgula.
• IDCompanyIntegration (integração de mensagem — e-mail/WhatsApp) precisa pertencer à empresa autenticada.
• IDCompanyIntegrationOrderList (integrações que originam pedidos) e IDTypeOrderList (tipos de pedido) precisam existir para a empresa e estar ativos.

Devolve o detalhe do template recém-criado (formato da listagem, array com 1 item).

Request body — TrackingTemplateCreate

Campo	Tipo	Obrigatório	Descrição
IDStatusTracking	integer (1-8)	sim	Macro status que dispara o template.
IDTypeCarrierTrackingTemplate	integer (1/2)	sim	1=e-mail, 2=WhatsApp/Webhook. Default 1.
HTML	string	sim	Corpo do template (HTML para e-mail). Aceita variáveis.
EmailTitle	string (≤150)	condicional	Assunto. Obrigatório para tipo e-mail.
CC / CCO	string (≤200)	não	E-mails em CC/CCO, separados por vírgula. Cada item validado.
IDCompanyIntegration	integer	condicional	Integração de entrega. Obrigatório para tipo WhatsApp/Webhook.
IDCompanyIntegrationOrderList	array/string	não	Restringe disparo às integrações de origem informadas.
IDTypeOrderList	array/string	não	Restringe disparo aos tipos de pedido informados.
CarrierTrackingTemplateName	string (≤100)	não	Nome amigável da regra.
CarrierTrackingTemplateStatus	integer (0/1)	não	1=ativo (default), 0=inativo.

Resposta 200 — array com 1 item de TrackingTemplateListItem.

Erros

Status	Quando
400	[BadRequest] - Empresa não existe; [BadRequest] - Email CCO não é válido <email>; [BadRequest] - Integração não existe; [BadRequest] - Integração(s) não localizada(s): <ids>; [BadRequest] - Tipo pedido(s) não localizado(s): <ids>.
500	Erro interno.

---

PUT /carrier/tracking-template/{idcarriertrackingtemplate}

trackingTemplatePut · autenticado

Atualização parcial — somente os campos enviados são alterados. Aplica as mesmas validações do POST para CC, CCO, IDCompanyIntegration, IDCompanyIntegrationOrderList e IDTypeOrderList. Devolve o detalhe atualizado.

Request body — TrackingTemplateUpdate (todos os campos opcionais).

Erros

Status	Quando
400	[BadRequest] - Tracking template não existe; [BadRequest] - Email CCO não é válido <email>; [BadRequest] - Integração tipo mensagem não existe; [BadRequest] - Integração(s) não localizada(s): <ids>; [BadRequest] - Tipo pedido(s) não localizado(s): <ids>.
500	Erro interno.

---

DELETE /carrier/tracking-template/{idcarriertrackingtemplate}

trackingTemplateDelete · autenticado

Remove fisicamente o template (DELETE FROM CarrierTrackingTemplate). Sem exclusão lógica nem regras de bloqueio. Devolve a string literal "Sucesso!".

Erros

Status	Quando
400	[BadRequest] - IDCarrierTrackingTemplate não existe.
500	Erro interno.

---

GET /carrier/quotation/rule

carrierQuotationRuleList · autenticado

Lista as regras de simulação de frete da empresa, ordenadas por Priority crescente (e por IDCarrierQuotationRule DESC no empate), até 1000 itens. Inclui regras Ativas (Status=1) e Inativas (Status=0) — as Excluídas (Status=2) ficam ocultas. Cada item já vem com:

• ConditionsRules: array de condições com ConditionValue quebrado em vetor pelo separador , (cada elemento é uma faixa/sigla — ver detalhe por tipo abaixo).
• ConditionNames: string concatenada com os nomes das condições da regra (usado para coluna da grid).
• CarrierQuotationRuleLog: histórico de alterações ordenado por IDCarrierQuotationRuleLog DESC. Cada entrada tem RecordTimestamp, Login do usuário e Data (JSON serializado com DE: <antes> PARA: <depois> por campo alterado, e <NomeCondicao>_Adicionado / <NomeCondicao>_Removido para mudanças de condições).

Resposta 200 — array de CarrierQuotationRuleListItem (até 1000).

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno.

---

POST /carrier/quotation/rule

carrierQuotationRulePost · autenticado

Cria uma regra com cabeçalho (nome, prioridade, vigência, ação) e condições. É obrigatório informar pelo menos uma condição. Cada condição é validada pelo seu tipo (IDTypeCarrierQuotationConditionRule):

Tipo	Nome	Formato de cada item	Validação
1	Estado/Região	UF ou UFCAPITAL/UFINTERIOR	UF precisa estar na lista oficial das 27 unidades federativas.
2	CEP Destino	`	<CEPAté>` (8 dígitos cada, sem hífen)
3	Transportadora	<IDSupplier>	Fornecedor precisa pertencer à empresa e ter IDTypeSupplier=2 (Transportadora). Obrigatório quando a ação é 9.
4	Valor do pedido	`	<Até>` (decimal em string)
6	Integração	<IDCompanyIntegration>	Integração precisa pertencer à empresa.
7	Peso (kg)	`	<Até>` (decimal)
8	SKUs iguais a	`	<descrição>`
9	SKUs diferentes de	`	<descrição>`
10	CEP Origem	`	<CEPAté>`

A ação (IDTypeCarrierQuotationActionRule) precisa estar ativa (TypeCarrierQuotationActionRuleStatus=1). Ações ativas:

ID	Nome	ActionValue esperado
1	Adicionar X dias no prazo	Inteiro (dias)
2	Alterar o preço R$	Decimal em reais
3	Alterar o preço X%	Percentual
5	Adicionar ao preço um % do valor da nota	Percentual
6	Fixar o preço em	Decimal em reais
7	Fixar o preço em uma % do valor da nota	Percentual
9	Excluir transportadoras selecionadas	(sem valor — exige cond. 3)
10	Fixar o preço unitário R$ X	Decimal em reais
13	Adicionar prazo de manuseio do CD	Inteiro (dias)

Após salvar, o backend regrava o Redis (CarrierQuotationRuleCondition:<accountname>) com todas as regras Ativas da empresa — o motor de simulação consulta o cache em vez de bater no banco.

Request body — CarrierQuotationRuleCreate

Campo	Tipo	Obrigatório	Descrição
CarrierQuotationRuleName	string	sim	Nome da regra.
Priority	integer ≥ 1	sim	Ordem de execução (menor → primeiro).
IDTypeCarrierQuotationActionRule	integer (enum)	sim	Tipo de ação (ver tabela).
ActionValue	string (decimal/inteiro)	condicional	Obrigatório para todas as ações exceto a 9.
Conditions	array de Condition	sim	Pelo menos 1 condição.
DateFrom / DateTo	date (YYYY-MM-DD)	não	1900-01-01 / 4000-01-01 quando o switch "Possui vigência" está desligado.
Status	integer (0/1)	não	1=Ativo (default), 0=Inativo.

Resposta 200 — array com 1 item de CarrierQuotationRuleDetail (mesmo formato da listagem, com ConditionsRules resolvido).

Erros

Status	Quando
400	[BadRequest] - Empresa não existe; [BadRequest] - Ação inativa ou não existe; [BadRequest] - Estado <UF> não encontrado; [BadRequest] - Faixa de cep <de>-<até> inválida; [BadRequest] - ID da transportadora <id> não encontrado; `[BadRequest] - Preço
500	Erro interno.

---

GET /carrier/quotation/rule/{idcarrierquotationrule}

carrierQuotationRuleGet · autenticado

Detalha uma regra. Mesmo formato da listagem (ConditionsRules quebrado em vetor, CarrierQuotationRuleLog ordenado DESC), porém limitado a 1 item. Retorna 400 quando o id não existe ou não pertence à empresa autenticada.

Erros

Status	Quando
400	[BadRequest] - Regra de cotação não encontrada; [BadRequest] - Parâmetros inválidos.
500	Erro interno.

---

PUT /carrier/quotation/rule/{idcarrierquotationrule}

carrierQuotationRulePut · autenticado

Atualiza a regra. Não é atualização parcial do cabeçalho — o handler executa um UPDATE com todos os campos do cabeçalho; campos ausentes viram NULL. As condições sim seguem diff:

1. Carrega as condições atuais (SELECT * FROM CarrierQuotationRuleCondition WHERE IDCarrierQuotationRule = ?).
2. Para cada item de Conditions no body, valida o ConditionValue pelo tipo (mesmas regras do POST, exceto que a validação de CEP aceita faixas com CEPDe == CEPAté — o POST exige <).
3. Insere os itens que não existiam antes (grava <NomeCondicao>_Adicionado no log).
4. Apaga os itens que existiam e não vieram no body (grava <NomeCondicao>_Removido no log).
5. Para cada campo do cabeçalho alterado, grava DE: <antes> PARA: <depois> no log (datas são comparadas truncadas para YYYY-MM-DD).
6. Regrava o Redis com todas as regras Ativas.

Quando Conditions vem como array vazio, todas as condições da regra são removidas em bloco (DELETE FROM CarrierQuotationRuleCondition WHERE IDCarrierQuotationRule = ?).

Request body — CarrierQuotationRuleUpdate

Erros

Status	Quando
400	[BadRequest] - Regra de cotação não existe; [BadRequest] - Estado <UF> não encontrado; [BadRequest] - Faixa de cep <de>-<até> inválida; [BadRequest] - ID da transportadora <id> não encontrado; `[BadRequest] - Preço
500	Erro interno.

---

DELETE /carrier/quotation/rule/{idcarrierquotationrule}

carrierQuotationRuleDelete · autenticado

Soft delete — UPDATE CarrierQuotationRule SET Status = 2 WHERE IDCarrierQuotationRule = ?. A regra deixa de aparecer na listagem (Status IN (0,1)) e sai do cache Redis (regravado só com regras Ativas). Devolve a string literal "Sucesso!".

Erros

Status	Quando
400	[BadRequest] - Regra de cotação não existe; [BadRequest] - Erro ao e executar ação.
500	Erro interno.

---

GET /carrier/quotation

carrierQuotationList · autenticado

Lista as simulações já rodadas pela empresa, ordenadas por IDCarrierQuotation DESC, até 5000 por página (use Page para paginar — offset = Page * 5000). Cada item traz cabeçalho + lista de transportadoras que responderam (CarriersName, concatenado por vírgula), sem expandir cada linha — para o detalhe use GET /carrier/quotation/{idcarrierquotation}.

Query params

Nome	Tipo	Obrigatório	Descrição
DateFrom	date	não	RecordTimestamp ≥ data.
DateTo	date	não	RecordTimestamp ≤ data 23:59:59.
ShippingPostalCode	string	não	CEP destino (apenas dígitos, comparação exata).
Description	string	não	Busca parcial (LIKE).
IDCarrierQuotation	integer	não	Id da simulação.
IDCompanyIntegration	integer	não	Filtra por integração origem (canal externo).
Page	integer	não	Página (offset = Page * 5000).

Resposta 200 — array de CarrierQuotationListItem.

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno.

---

POST /carrier/quotation

carrierQuotationPost · handler PHP · autenticado

Roda uma simulação de frete. Recebe CEP destino + array de volumes/produtos (Quotations) e devolve o resultado completo: cabeçalho

• uma linha por transportadora habilitada para leilão de frete (Suppliers.CarrierAuction = 1).

Configurações necessárias (sem elas, a simulação ou falha ou volta sem opções):

1. Empresa com endereço completo (CompanyAddressState, CompanyAddressPostalCode, CompanyAddressIbgeCityCode) — usado para calcular ICMS interestadual e cidade-mesma.
2. Transportadora cadastrada em Suppliers com:
   • IDTypeSupplier=2 (Transportadora).
   • CarrierAuction=1 (habilitada para leilão de frete).
   • CarrierCubageKmM (padrão 167) e, opcionalmente, CarrierCubageFreeWeight para cubagem.
   • CarrierShippingCutTime opcional (horário de corte; cotações rodadas depois marcam CutDaysTime=1).
   • CarrierAuctionPenalty opcional (ajuste percentual sobre o total).
   • CarrierICMSIncluded opcional (quando 1, ICMS é zerado).
   • CarrierAdditionalBusinessDays opcional (dias úteis fixos adicionados).
3. Faixa de CEP atendida em CarrierScope para cada transportadora (PostalCodeFrom, PostalCodeTo, Days, RateType, Gris, Advalorem, etc.).
4. Tabela de preço por peso em CarrierRate (por IDSupplier + RateType, com WeightFrom/WeightTo/RateValue). Para peso acima da maior faixa, cadastre uma linha com WeightTo=-1 (extrapolação linear).
5. Base de CEPs do idworks (sistema-padrão): o backend valida o CEP destino chamando GetStateByPostalCode — CEPs inexistentes geram CarrierQuotationError tipo 3.
6. Opcional: regras ativas em CarrierQuotationRule (ver tag Regras Simulação Frete) — modificam preço, prazo ou excluem transportadoras conforme condições atendidas.

Lógica do cálculo:

• Peso total = soma de Weight dos volumes.
• Largura total = soma de Width. Altura e comprimento totais = máximo.
• cubage = round(height * length * width * CarrierCubageKmM, 3) (em metros, cada dimensão dividida por 100).
• cubedWeight = peso bruto < CarrierCubageFreeWeight ? peso bruto : max(peso bruto, cubage).
• Procura CarrierRate na faixa do cubedWeight. Quando não acha mas existe WeightTo=-1, extrapola: rate = max_rate + (cubedWeight - max_weight) * rate_kg_extra.
• Soma componentes do preço (rate, gris, advalorem, pedágio, taxas) → SubtotalShippingValue.
• ICMS interestadual aplicado quando origem e destino têm UFs diferentes e CarrierICMSIncluded=0. Mesma cidade (ShippingSameCity=1) zera ICMS independente disso.
• AdjustedValue = round((subtotal + icms) * CarrierAuctionPenalty, 2).
• Aplica regras de simulação: RuleAdditionalValue, RuleAdditionalDays.
• ShippingShowValue = TotalShippingValue + AdjustedValue + RuleAdditionalValue (com arredondamento opcional via PriceRounding).

Request body — CarrierQuotationCreate

Campo	Tipo	Obrigatório	Descrição
ShippingPostalCode	string	sim	CEP destino (8 dígitos, com ou sem hífen).
Quotations	array de volumes	sim	Pelo menos 1 item com Weight > 0.
Description	string	não	Texto livre para identificar a simulação.
OriginPostalCode	string	não	Default = CompanyAddressPostalCode.
IDOrder	integer	não	Vínculo com pedido existente.
IDCompanyIntegration	integer	não	Preenchido quando vem de canal externo.
IDSkuHub	string	não	SKU enviado pelo canal.
IDSkuCompany	string	não	SKU local correspondente.

Cada item de Quotations:

Campo	Tipo	Obrigatório	Descrição
Weight	number	sim	Quilos. Soma vira peso total.
Height	number	sim	Centímetros. Backend pega o máximo.
Width	number	sim	Centímetros. Backend soma.
Length	number	sim	Centímetros. Backend pega o máximo.
ValueInvoice	number	não	Valor da nota em reais (alimenta Gris/Advalorem/Tde).
Quantity	number	não	Só relevante para simulação por Produto (o frontend já multiplica antes de chamar).

Resposta 200 — array com 1 item de CarrierQuotationDetail (cabeçalho + CarrierQuotations[] ordenado por Attended DESC, TotalDaysTime ASC, TotalShippingValue ASC).

Erros

Status	Quando
400	Precisa enviar o CEP destino; Peso precisa ser maior que zero; Dados para cotação não enviados; CEP destino <postalcode> não existe; Empresa não localizada (2). (Mensagens vêm via BusinessException PHP — sem prefixo [BadRequest].)
500	Erro interno.

---

GET /carrier/quotation/{idcarrierquotation}

carrierQuotationGet · autenticado

Retorna o detalhe da simulação. O cabeçalho traz os mesmos campos da listagem; CarrierQuotations[] é o array com uma linha por transportadora.

Cada linha (CarrierQuotationItemDetail) inclui:

• Identificação: IDCarrier, SupplierNameCorporateName, CarrierLogoUrl, CarrierModal.
• Estado: Attended (1=Atende, 0=Não atende, 3=Excluído por regra, 4=Fora da faixa de peso) + AttendedDescription pronto.
• Prazo: DaysTime, CarrierAdditionalBusinessDays, CutDaysTime, RuleAdditionalDays, TotalDaysTime, TotalShowDaysTime.
• Componentes do preço: ShipingValue, GrisValue, AdvaloremValue, TollValue, AccessDifficultyRateValue, DispatchFeeValue, DeliveryDifficultyRateValue, SECCATValue, TollFractionValue, TrafficRestrictionFeeValue, AdministrationFeeValue, CTEFeeValue, SUFRAMAFeeValue, FluvialInsuranceFee, OtherFee, OtherFeeValue, IcmsValue.
• Totais calculados pelo backend: SubtotalShippingValue, TotalShippingValue, IcmsValuePercent, ShippingShowValue (este último é o valor final, com ajustes de regra e arredondamento).
• Cubagem: WeightSelected, WeightCubed, CarrierCubageKmM, CarrierCubageFreeWeight.
• Regras aplicadas (quando houve): CarrierQuotationRuleValueName, CarrierQuotationRuleDaysName, RuleAdditionalValue, RuleAdditionalDays, IDCarrierQuotationRuleValue, IDCarrierQuotationRuleDays.

Linhas com Attended != 1 vêm com SubtotalShippingValue, TotalShippingValue, IcmsValuePercent e ShippingShowValue zerados (null) — só Attended=1 tem preço calculado.

Retorna [] quando o id não existe ou pertence a outra empresa.

Erros

Status	Quando
500	Erro interno.

---

GET /orders/tracking

orderTrackingList · autenticado

Lista pedidos em rastreamento da empresa, juntando dados do pedido, último status do pacote (Packages.TrackingIDStatus), último evento da transportadora (CarrierTracking) e dois indicadores derivados de pontualidade calculados em tempo real:

• IDStatusDeliveryConsumer: compara a data de entrega (OrderEvents.IDEvent=45) com ShippingEstimateDate.
• IDStatusDeliveryCarrier: compara a data de entrega com CarrierDeliveryDate (data prometida à transportadora).

Códigos do indicador:

Código	Significado
1	Entregue antes do prazo.
2	Entregue após o prazo.
3	Em curso, dentro do prazo (ainda não venceu).
4	Em curso, atrasado (venceu sem entrega).
6	Entregue no dia exato do prazo.

Os indicadores só são calculados quando há ShippingEstimateDate / CarrierDeliveryDate cadastrados no pedido. Quando o status do tracking é Finalizado (1), usa o diff entre DeliveredDate e a data esperada; caso contrário, usa o diff entre NOW() e a data esperada.

Limite 3000 itens por página (Page controla o offset = Page * 3000).

Quando TrackingEnabled=1 é informado, a query troca LEFT JOIN TypeCarrier por JOIN TypeCarrier ... AND TypeCarrier.TrackingEnabled=1, restringindo aos pedidos cuja transportadora tem integração de rastreio ativa.

Query params principais: DateFrom/DateTo (data do pedido), ShippingDateFrom/ShippingDateTo (data de postagem), ShippingEstimateDateFrom/ShippingEstimateDateTo (data estimada), Order, IDOrder, NfeNumber, OrderFrom, ConsumerNameCorporateName, ConsumerCpfCnpj, ConsumerEmail, IDCarrier, IDSalesChannel, IDCompanyIntegration, TrackingIDStatus, IDStatusDeliveryConsumer, IDStatusDeliveryCarrier, TrackingEnabled, Page.

Resposta 200 — array de OrderTrackingListItem.

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno.

---

GET /sku/location/group

skuLocationGroupList · autenticado

Lista grupos de endereços (StockKeepingUnitLocationGroup) da empresa, ordenados por StockKeepingUnitLocationGroupName. Aceita filtros por id e por nome exato.

Resposta 200 — array de SkuLocationGroupListItem.

---

POST /sku/location/group

skuLocationGroupPost · autenticado

Cria um grupo de endereços. O nome precisa ser único dentro da empresa (validado por SELECT ... WHERE StockKeepingUnitLocationGroupName = ? AND IDCompany = ?). Devolve o grupo recém-criado no formato da listagem.

Request body — SkuLocationGroupCreate (campo único: StockKeepingUnitLocationGroupName, máx. 100).

Erros

Status	Quando
400	[BadRequest] - Empresa não existe; [BadRequest] - Grupo já existente; [BadRequest] - Erro ao inserir a grupo.
500	Erro interno.

---

PUT /sku/location/group/{idstockkeepingunitlocationgroup}

skuLocationGroupPut · autenticado

Atualiza o nome do grupo. Valida unicidade dentro da empresa (excluindo o próprio registro).

Erros

Status	Quando
400	[BadRequest] - Preencha corretamente o nome do grupo; [BadRequest] - Grupo não encontrada; [BadRequest] - Grupo já existente; [BadRequest] - Grupo não atualizado.
500	Erro interno.

---

DELETE /sku/location/group/{idstockkeepingunitlocationgroup}

skuLocationGroupDelete · autenticado

Exclusão física. Verifica SELECT * FROM StockKeepingUnitLocation WHERE IDStockKeepingUnitLocationGroup = ? — se há endereços vinculados, devolve 200 com a string "Grupo esta vinculado a endereço. Editar endereço antes de excluir o grupo" (mensagem sem prefixo [BadRequest], mas tratada como erro pela UI).

Erros

Status	Quando
400	[BadRequest] - Grupo não existe.
500	Erro interno.

---

GET /sku/distribution-center

skuDistributionCenterList · autenticado

Lista os centros de distribuição da empresa, ordenados por DistributionCenterName. Respeita restrição de CDs permitidos ao usuário (cache UserCompanyDistributionCenter:<prefix>:<user> em Redis): quando o usuário tem CDs específicos atribuídos, o filtro limita à essa lista; senão devolve todos da empresa.

Aceita filtro CSV em IDStockKeepingUnitDistributionCenter.

Resposta 200 — array de DistributionCenterItem.

---

POST /sku/distribution-center

skuDistributionCenterPost · autenticado

Cria um CD. Validações: DistributionCenterName único na empresa. Marcar Default = 1 (default ausente) zera o Default dos demais CDs da empresa. Devolve a lista completa atualizada.

Erros: [BadRequest] - Já existe um centro de distribuição com este nome; [BadRequest] - Company não existe.

---

PUT /sku/distribution-center/{idstockkeepingunitdistributioncenter}

skuDistributionCenterPut · autenticado

Atualização parcial. Mesmas validações de unicidade.

---

DELETE /sku/distribution-center/{idstockkeepingunitdistributioncenter}

skuDistributionCenterDelete · autenticado

Exclusão física com 8 regras de bloqueio em cascata (cada uma verificada em sequência):

1. CD com armazéns vinculados → Existem armazéns vinculados a este centro de distribuição.
2. CD padrão → Precisa definir outro centro de distribuição padrão antes de deletar.
3. Histórico de recebimento de compra (StockKeepingUnitPurchase) → Centro de distribuição já teve recebimento e não pode ser excluído.
4. Histórico de pedidos (Orders) → ... já teve pedido e não pode ser excluído.
5. Histórico de pedido de compra (StockKeepingUnitBuyOrder) → ... já teve pedido de compra e não pode ser excluído.
6. Usuários com CD vinculado (UserCompanyDistributionCenter) → ... está vinculado a usuário e não pode ser excluído.
7. Ressuprimento (StockKeepingUnitResupplyList) → ... está vinculado a ressuprimento e não pode ser excluído.
8. Inventário (StockKeepingUnitInventorySummary) → ... está vinculado a inventário e não pode ser excluído.

Quando nenhuma bloqueia, executa DELETE FROM StockKeepingUnitDistributionCenter.

---

GET /sku/warehouse

skuWareHouseList · autenticado

Lista armazéns Ativos (Status = 1) da empresa, ordenados por WarehouseName. Inclui o nome do tipo (TypeStockKeepingUnitWarehouse: Saudável, Divergência, Quarentena, Recebimento, Falta, Vencido, Auditoria, Avaria, Devolução, Ressuprimento) e CD pai resolvido. Empresa faturadora (IDCompanyInvoice) vem como CompanyNameCorporateNameInvoice formatado AccountName - Razão Social.

Resposta 200 — array de WarehouseItem.

---

POST /sku/warehouse

skuWareHousePost · autenticado

Cria um armazém. Validações:

• IDStockKeepingUnitDistributionCenter precisa pertencer à empresa.
• IDCompanyInvoice (quando informado) precisa estar associada à conta autenticada via CompanyMain (operação multi-empresa).
• Default = 1 zera os demais armazéns da empresa.
• DefaultPurchase = 1 zera os demais como padrão de recebimento de compra.

Comportamento especial: o handler executa dois inserts em sequência:

1. INSERT INTO StockKeepingUnitWarehouse — cria o armazém.
2. INSERT INTO StockKeepingUnitLocation (Address, IDCompany, IDStockKeepingUnitWarehouse, Default) VALUES (?, ?, ?, 1) — cria simultaneamente um endereço padrão homônimo (Address = WarehouseName, Default = 1) dentro do armazém. Esse endereço serve como destino default quando nenhum endereço específico é informado em recebimento/transferência.

Erros: [BadRequest] - Company not found; [BadRequest] - Faturador não existe; [BadRequest] - Centro de distribuição não existe; [BadRequest] - Could not add warehouse; [BadRequest] - Could not add location.

---

PUT /sku/warehouse/{idstockkeepingunitwarehouse}

skuWareHousePut · autenticado

Atualização parcial. Mesmas validações do POST quando troca CD ou faturador.

Erros: [BadRequest] - Armazém não existe; [BadRequest] - Centro de distribuição não existe; [BadRequest] - Faturador não existe.

---

DELETE /sku/warehouse/{idstockkeepingunitwarehouse}

skuWareHouseDelete · autenticado

Soft delete — UPDATE StockKeepingUnitWarehouse SET Status = 0, SumQuantity = 0, Default = 0 WHERE IDStockKeepingUnitWarehouse = ?. Bloqueada quando:

1. Endereço vinculado (StockKeepingUnitLocation) → Armazém possui endereço cadastrado e não pode ser excluído.
2. De/para de armazém (HubWarehouse como destino) → Armazém tem de/para de armazém e não pode ser excluído.

---

GET /sku/location/category

skuLocationCategoryList · autenticado

Lista categorias Ativas (IsActive = 1) da empresa, ordenadas pelo nome. Devolve IDStockKeepingUnitLocationCategory, StockKeepingUnitLocationCategoryName, IsActive, AccountName.

---

POST /sku/location/category

skuLocationCategoryPost · autenticado

Cria uma categoria. Validações: nome único por empresa.

Erros: [BadRequest] - Categoria já existente; [BadRequest] - Empresa não existe; [BadRequest] - Erro ao inserir a categoria.

---

PUT /sku/location/category/{idstockkeepingunitlocationcategory}

skuLocationCategoryPut · autenticado

Atualiza o nome. Mesma validação de unicidade.

---

DELETE /sku/location/category/{idstockkeepingunitlocationcategory}

skuLocationCategoryDelete · autenticado

Soft delete — IsActive = 0 e prefixa o nome com o IDStockKeepingUnitLocationCategory (CONCAT(id, nome)) para liberar o nome para reuso em outra categoria. Bloqueada quando há:

1. Endereço (StockKeepingUnitLocation) com a categoria → Categoria esta vinculado a endereço. Editar endereço antes de excluir a categoria.
2. SKU (StockKeepingUnit) com a categoria → Categoria esta vinculado a SKU. Editar SKU antes de excluir a categoria.

---

GET /fulfillment/picking/basket

orderFulfillmentPickingBasketList · autenticado

Lista cestos Ativos (PickingListBasketStatus = 1) com dimensões, peso máximo, ExternalId, CD pai resolvido, IDOrder atualmente amarrado (com IDPickingList resolvido a partir do pedido) e PickingListBasketHistory (histórico de pedidos que passaram pelo cesto, em formato JSON-array já parseado).

Aceita filtros: IDPickingListBasket, IDStockKeepingUnitDistributionCenter, ExternalId, Page (offset = Page * 5000).

---

POST /fulfillment/picking/basket

orderFulfillmentPickingBasketPost · autenticado

Cria um cesto. ExternalId é único por CD. Quando o body não informa ExternalId, o backend faz UPDATE ... SET ExternalId = id após o insert (usa o próprio IDPickingListBasket como código externo).

Erros: [BadRequest] - Centro de distribuição não existe; [BadRequest] - Já existe um cesto para este centro de distribuição com o mesmo código.

---

PUT /fulfillment/picking/basket/{idpickinglisbasket}

orderFulfillmentPickingBasketPut · autenticado

Atualiza atributos do cesto. Uso especial: enviar IDOrder: null no body desvincula o pedido atualmente amarrado — a tela usa esse comportamento para limpar cestos em lote (botão "Remover pedidos").

Erros: [BadRequest] - Cesto picking não existe.

---

DELETE /fulfillment/picking/basket/{idpickinglisbasket}

orderFulfillmentPickingBasketDelete · autenticado

Soft delete — UPDATE PickingListBasket SET ExternalId = null, PickingListBasketStatus = 0. O ExternalId é liberado (NULL) para permitir reuso do mesmo código em um cesto novo (cadastros descontinuados frequentemente reaproveitam etiquetas).

---

GET /fulfillment/picking/basket/{idpickinglisbasket}/label

purchaseLabelGet (reaproveitado) · autenticado

Devolve o ZPL pronto para impressão da etiqueta do cesto, usando o template configurado em Etiquetas para o tipo de etiqueta de cesto.

---

GET /sku/batch

skuBatchList · autenticado

Lista lotes (StockKeepingUnitBatch) com:

• SKU resolvido: IDSku, IDSkuCompany, SkuName, BarCode, imagem principal (MainImageURL + MainImageThumbnailURL), curva ABC (AbcCurve), tipo (IDTypeSku).
• Endereço resolvido: IDStockKeepingUnitLocation, Address, IDStockKeepingUnitWarehouse + WarehouseName, CD + DistributionCenterName, categoria, grupo, tipo de endereço.
• Lote: IDBatchNumber, BestBeforeDate (validade), ManufacturingDate (fabricação), Comments (descrição), Default.
• Saldo calculado: BatchBalance (entradas − saídas com BalanceChange = 1), QtyHandling (saídas em movimento), QtyAvailable (saldo disponível do SKU no armazém).
• Derivados: IDBatchStatus/BatchStatus (Ativo se saldo > 0; Inativo se = 0), BatchDAgeInDays (idade do lote em dias).

Filtra SKUs ativos (IDStatusSku IN (1,2,3,4)) do tipo Produto / Variação / Kit (IDTypeSku IN (3,6,7)).

Filtros:

• IDSku, IDBatch, IDStockKeepingUnitLocation, IDStockKeepingUnitWarehouse, IDStockKeepingUnitDistributionCenter (CSV).
• SkuName, IDSkuCompany (LIKE), BarCode (busca em StockKeepingUnit, StockKeepingUnitBarCode e StockKeepingUnitBarCodePackage), Address (LIKE).
• DateFrom/DateTo (faixa de BestBeforeDate).
• Status (1 = só com saldo, 0 = só zerados, vazio = todos).
• Search — busca multi-campo (SKU/nome/endereço/código de barras); valor especial nulladdress filtra lotes sem endereço.
• Page — paginação (offset = Page * 5000).

Respeita restrição de CDs do usuário e operações multi-empresa via ShareSkuLocationWithRelatedCompanies.

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.

---

POST /sku/batch/{idsku}

skuBatchPost · autenticado · privilégio PrivilegeSkuBatch

Cria um lote no SKU em um endereço específico. Validações:

• SKU sem controle de lote (Batch != 1 no cadastro do SKU): se já existe lote desse SKU no endereço informado, devolve [BadRequest] - SKU já tem este endereço. SKUs com controle de lote (Batch = 1) permitem múltiplos lotes no mesmo endereço para rastreabilidade.
• Endereço precisa pertencer à empresa autenticada ou a uma empresa relacionada via CompanyMain + parâmetro ShareSkuLocationWithRelatedCompanies = 1.
• Quando Default = 1, zera o Default dos demais lotes do SKU antes de inserir.

Erros: [BadRequest] - SKU não existe; [BadRequest] - SKU já tem este endereço; [BadRequest] - Endereço SKU não existe.

---

PUT /sku/batch/{idsku}/{idbatch}

skuBatchPut · autenticado · privilégio PrivilegeSkuBatch

Atualiza validade (BestBeforeDate), fabricação (ManufacturingDate), endereço (transferência interna), descrição (Comments) e flag de padrão. Validações:

• ManufacturingDate ≤ BestBeforeDate e ManufacturingDate ≤ 2099-12-31 — caso contrário Data de fabricação não pode ser maior que data de validade nem 31/12/2099.
• IDStockKeepingUnitLocation = null é rejeitado — Endereço não pode ser removido (lote sempre tem endereço).
• Endereço novo precisa pertencer ao mesmo armazém do endereço atual (transferência entre armazéns usa a tela de Transferência entre Endereços, não esta).
• Default = 1 zera os demais lotes do SKU.

Existe também a variante PUT /sku/batch/{idsku} (sem idbatch na URL) que aceita o id do lote no body como IDBatch — comportamento idêntico.

Erros: [BadRequest] - Lote não existe; [BadRequest] - Data de fabricação não pode ser maior que data de validade nem 31/12/2099; [BadRequest] - Data de fabricação não pode ser maior que data de validade; [BadRequest] - Endereço não pode ser removido; [BadRequest] - Endereço SKU não existe ou pertence a outro armazém.

---

DELETE /sku/batch/{idsku}/{idbatch}

skuBatchDelete · autenticado · privilégio PrivilegeSkuDelete

Bloqueada quando o lote tem saldo (BatchBalance > 0) — Lote tem saldo, transferir quantidade para deletar. Lotes com saldo precisam ser transferidos primeiro para outro endereço (ou consumidos via venda/saída) antes da exclusão.

Erros: [BadRequest] - Lote não existe; [BadRequest] - Lote tem saldo, transferir quantidade para deletar.

---

GET /sku/movement

skuMovementList · autenticado · privilégio PrivilegeSkuMovementView (lista) / PrivilegeSkuKardexView (Kardex)

Retorna o histórico de movimentações de estoque (StockKeepingUnitMovement). O modo é controlado pelo parâmetro Type e troca o shape da resposta:

Type	Schema da resposta	Para quê serve
(ausente)	SkuMovementListItem[]	Listagem padrão da tela Movimentação Estoque com filtros amplos.
Kardex / kardex	SkuMovementKardexItem[]	Kardex cronológico por SKU + armazém (saldo e custo médio acumulados).
KardexLocation	SkuMovementKardexLocationItem[]	Kardex por endereço (em vez de armazém).
SkuInbound	SkuMovementInboundItem[]	Apenas entradas (recebimentos), com dados do XML da NF-e.
SkuOutbound	SkuMovementOutboundItem[]	Apenas saídas (vendas), com dados da NF-e de venda e do pedido.
SkuFiscalConciliation	SkuMovementFiscalConciliationItem[]	Árvore recursiva de lotes (CTE recursiva) partindo do recebimento original.

Origem da movimentação (TypeMovement) é derivada na listagem padrão e no Kardex pela primeira chave estrangeira preenchida: Transferência endereço (IDOriginIDSkuMovement > 0) → Ajuste saldo estoque (IDStockKeepingUnitInventory) → Inventário (IDStockKeepingUnitInventorySummary) → Recebimento (IDPurchase) → Venda (IDOrder) → Produção (IDStockKeepingUnitProduction).

Sentido (TypeSkuMovement) é Entrada quando IDTypeMovement = 0 e Saída quando IDTypeMovement = 1.

StatusInvoice e TypeFulfillmentNonconformity são resolvidos via cache (TypeStatusInvoice e TypeFulfillmentNonconformity no Redis).

Login é resolvido a partir do IDUser registrado em StockKeepingUnitMovementTransfer (transferências) ou StockKeepingUnitInventory (ajustes manuais).

Filtros disponíveis (listagem padrão):

• SKU: IDSku (aceita vários separados por vírgula/espaço), SkuName (LIKE), BarCode, IDSkuCompany (LIKE), IDSkuHub (resolve via HubOrderProduct + HubOrder), IDBrand, IDSupplier, SupplierCode (LIKE), Package.
• Movimentação: IDSkuMovement, BalanceChange (0/1), IDTypeMovement (0/1), IDTypeFulfillmentNonconformity, IDStockKeepingUnitWarehouse, BatchComments.
• Pedido: ConsumerNameCorporateName (LIKE), ConsumerCpfCnpj (LIKE), ConsumerEmail (LIKE), Order, IDOrder, IDConsumer, OrderFrom (subquery em OrderFrom), IDStatusOrder, IDStatusInvoice, IDCarrier, IDSalesChannel, IDCompanyIntegration, IDOrderType, IDCompanyInvoice, ShippingState, IncludeValueDashboard.
• NF-e: NfeNumber.
• Intervalos de data: DateFrom/DateTo (movimentação), InvoiceDateFrom/InvoiceDateTo (emissão NF), ShippingDateFrom/ShippingDateTo (envio — subquery em Packages), OrderDateFrom/OrderDateTo (criação do pedido), ValueOrderFrom/ValueOrderTo (valor do pedido).
• Sincronização incremental: SinceDateLastRecordModification (movimentações com DateLastRecordModification ≥ a data informada).

Quando há DateFrom + DateTo na listagem padrão, a query usa FORCE INDEX (RecordTimestampASC) para melhorar o plano de execução.

Paginação: Page (offset = Page * 1000 na listagem padrão, SkuInbound e SkuOutbound; Page * 8000 no Kardex e KardexLocation).

Ordenação: o parâmetro OrderBy aceita ASC (default) ou DESC e controla a ordem do RecordTimestamp no Kardex.

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa (conta não resolvida); [BadRequest] - Precisa informar o armazem e sku (Type=Kardex sem IDSku/IDStockKeepingUnitWarehouse); [BadRequest] - Precisa informar o endereço e sku (Type=KardexLocation sem IDSku/IDStockKeepingUnitLocation).

---

POST /sku/movement/transfer

skuMovementTransferPost · autenticado · privilégio PrivilegeSkuMovementTransfer

Move quantidade entre armazéns ou entre lotes/endereços. Gera duas movimentações vinculadas — saída na origem + entrada no destino — com IDOriginIDSkuMovement apontando da entrada para a saída.

Modos de transferência

Body enviado	Comportamento
IDStockKeepingUnitWarehouseFrom + IDStockKeepingUnitWarehouseTo	Transferência entre armazéns. Consome lotes em FIFO (mais antigo primeiro) até completar Quantity. Em SKU sem rastreabilidade (Batch = 0) usa o lote padrão.
IDBatchFrom + IDBatchTo	Transferência entre lotes específicos (mesmo SKU, lotes existentes).
IDBatchFrom + IDStockKeepingUnitLocationTo	Transferência por endereço: o sistema procura um lote compatível no destino (mesma validade/fabricação/comentário) e o reutiliza; se nenhum bate, cria um lote novo. Com KeepUniqueBatchForFiscalConciliation = 1, sempre cria um lote novo.

Validações em sequência

1. Quantity > 0 — caso contrário [BadRequest] - Quantidade precisa ser maior que zero.
2. SKU existe na empresa autenticada e está ativo (IDStatusSku <> 0) — [BadRequest] - SKU não existe.
3. Tipo do SKU em (3, 6, 7) (Produto/Variação, Matéria-prima, Insumo) — [BadRequest] - Item não é do tipo SKU, materia prima ou insumo.
4. Modo lote: lote origem existe e tem Show = 1. Endereço destino (quando informado) existe.
5. Modo lote rastreável (SKU Batch = 1) com AllowSameItemDifferentBatchSameLocation = 0: o endereço destino não pode ter o mesmo SKU em lote divergente — [BadRequest] - Item possui lotes divergentes no endereço de destino e não pode ser transferido.
6. CD: origem e destino no mesmo Centro de Distribuição — [BadRequest] - Centro de distribuição de origem diferente do destino.
7. Saldo: lote origem tem saldo suficiente, salvo se AllowNegativeBalanceTransfer = 1 ou IgnoreBalance = 1 — [BadRequest] - Quantidade total insuficiente para transferencia: Origem: X Transferência: Y.

Custo unitário das movimentações = custo médio do armazém de origem (InventoryValue / QtyAvailable em StockKeepingUnitBalance), ou CostSet do SKU se UseCostFromCostSet = 1.

Efeitos colaterais após sucesso

• Atualiza o cache de saldo StockKeepingUnitBalance do SKU no armazém de destino (helper updateCost).
• Lê pedidos no armazém de destino com IDStatusOrder IN (11, 12, 24) ("Falta produto" e equivalentes) que tenham IDTypeFulfillmentNonconformity IN (1, 2, 5, 6) para o SKU transferido. Para cada um, abate QuantityNonconformity à medida que a quantidade transferida cobre as faltas (UPDATE StockKeepingUnitMovement SET IDTypeFulfillmentNonconformity = NULL, QuantityNonconformity = NULL). Quando todos os itens em não conformidade do pedido são zerados, o pedido volta para IDStatusOrder = 1 (Fechado) com evento OrderEvents.IDEvent = 35 no histórico.
• Publica mensagem { Topic: "SkuBalanceTransfer", IDSku, ... } na fila SQS webhook.fifo para acionar os webhooks da empresa.

Parâmetros de query opcionais

• BatchResponse=1 — troca a resposta padrão (array de movimentações criadas) pela lista completa de lotes ativos do SKU (SkuMovementTransferBatchResponseItem[]). Útil para o frontend recarregar o painel de saldos sem nova chamada.
• IgnoreBalance=1 — ignora a validação de saldo apenas no fluxo IDBatchFrom + (IDBatchTo | IDStockKeepingUnitLocationTo) (mesma semântica de AllowNegativeBalanceTransfer, mas pontual).

Parametrizações relevantes (todas em Configurações → Parametrizações):

Key	Grupo	Efeito
AllowNegativeBalanceTransfer	Logística (WMS) → Endereço	Libera transferência mesmo com saldo insuficiente.
AllowSameItemDifferentBatchSameLocation	Logística (WMS) → Endereço	Aceita o mesmo SKU em lote divergente no mesmo endereço.
KeepUniqueBatchForFiscalConciliation	Produto	Cria sempre lote novo no destino.
UseCostFromCostSet	Produto	Usa CostSet no lugar do custo médio.
QuantityDecimalUnitGlobal	Configurações Gerais	Define as casas decimais usadas nas mensagens de saldo insuficiente.

---

POST /sku/{idsku}/cost/recalculate

skuCostRecalculatePost (handler PHP via asyncLambdaGateway) · autenticado · privilégio PrivilegeSkuKardexView

Despacha o reprocessamento do histórico de movimentações do SKU para refazer o cálculo de custo médio a partir do zero. A chamada é assíncrona — devolve imediatamente e o reprocessamento roda em segundo plano. O frontend mostra um aviso "Estamos realizando o processamento em segundo plano para garantir uma melhor experiência" e fecha automaticamente após 8 segundos.

Quando usar

• Importação de movimentações antigas resultou em custo médio inconsistente.
• Correção retroativa do custo de um recebimento já finalizado.
• Estorno de uma compra que afetou o histórico.
• Custo médio na tela de Saldo / Lotes não bate com o que o Kardex calcularia.

Atenção: o processo é irreversível e pode demorar minutos em SKUs com muito histórico.

---

GET /sku/resupply

skuResupplyList · autenticado

Lista ressuprimentos (StockKeepingUnitResupplyList) da empresa com totais agregados — QtyOrder (pedidos vinculados), QtyResupply (itens pendentes), QtyResupplyItems (unidades pendentes). Inclui CD, tipo, modalidade, status, prioridade, colaborador atribuído (UserStartLogin) e datas.

Aceita filtros amplos: status, modalidade, tipo, CD, colaborador atribuído, intervalo de datas (criação, início, finalização). Respeita restrição de CDs do usuário.

A tela mobile usa filtros próprios: IDResupplyStatus=1,2,3, RecordUserStart=<userid> (quando o parâmetro AllowRessuplyOnlyWorker está ativo), e DateFrom/DateTo cobrindo os últimos 30 dias.

---

POST /sku/resupply

skuResupplyPost · autenticado

Cria ressuprimento em dois modos:

Modo manual (sem IDOrder): valida tipo (1=Picking, 2=Pulmão, 3=Recebimento), modalidade (1=Individual, 2=Agrupado, 3=Indireto, default 1) e CD (usa o padrão da empresa se omitido).

Modo automático por pedido (com IDOrder): aciona o worker PHP sku/movement/resupply.php que analisa o pedido e gera as listas necessárias. Pode falhar com motivos específicos:

• Empresa não tem armazém configurado para ressuprimento — parâmetro ResupplyIDSkuWarehouse vazio.
• Não há itens marcados para ressuprimento neste pedido — nenhum SKU do pedido tem necessidade de ressuprimento.
• Itens deste pedido já estão em ressuprimento.
• Itens deste pedido já têm quantidade disponível no picking, ressuprimento não necessário.
• Não há saldo disponível em outros endereços para ressuprir este pedido.

---

GET /sku/resupply/{idstockkeepingunitresupplylist}

skuResupplyGet · autenticado

Detalhe completo do ressuprimento — cabeçalho + itens (StockKeepingUnitResupply) + eventos. Cada item traz IDSku, endereço origem, endereço destino, quantidade pendente, quantidade movimentada, recebimento vinculado (IDPurchase).

---

PUT /sku/resupply/{idstockkeepingunitresupplylist}

skuResupplyPut · autenticado

Atualização parcial. Usado para:

• Trocar status (Aberto → Iniciado → Finalizado / Cancelado).
• Atribuir colaborador (RecordUserStart). Privilégio PrivilegeCollaboratorsAssignmentResupply controla atribuição em massa pela tela.
• Alterar modalidade (IDTypeResupplyMode) — ação em massa via modal.
• Alterar prioridade (StockKeepingUnitResupplyListPriority, 0-10) — ação em massa via modal.

---

DELETE /sku/resupply/{idstockkeepingunitresupplylist}

skuResupplyDelete · autenticado

Bloqueada quando QtyResupply > 0 (há itens pendentes). A tela desabilita o botão e mostra tooltip explicando.

---

POST /sku/resupply/{idstockkeepingunitresupplylist}/merge

skuResupplyMergePost · autenticado · privilégio PrivilegeResupplyMerge

Move todos os itens de uma lista de ressuprimentos de origem (passada em IDStockKeepingUnitResupplyListSource[]) para o ressuprimento de destino (id na URL). Apenas ressuprimentos com status Aberto podem participar — a tela bloqueia seleção mista.

---

POST /sku/resupply/{idstockkeepingunitresupplylist}/sku

skuResupplySkuPost · autenticado · privilégio PrivilegeResuplySkuCreate

Adiciona item ao ressuprimento.

---

PUT /sku/resupply/{idstockkeepingunitresupplylist}/sku/{idstockkeepingunitresupply}

skuResupplySkuPut · autenticado · privilégio PrivilegeResuplySkuEdit

Atualiza item. Privilégios adicionais granulares:

• PrivilegeResupplyAllowEditQuantity — quem pode mudar a quantidade.
• PrivilegeResupplyAllowUserSetLocationTo — quem pode mudar o endereço de destino.

---

DELETE /sku/resupply/{idstockkeepingunitresupplylist}/sku/{idstockkeepingunitresupply}

skuResupplySkuDelete · autenticado · privilégio PrivilegeResuplySkuDelete

Remove item do ressuprimento.

---

GET /type/sku/resupply

typeSkuRessuply · autenticado

Devolve a lista fixa TypeResupply: 1=Picking, 2=Pulmão, 3=Recebimento.

---

GET /type/sku/resupply/status

typeSkuResuplyStatusList · autenticado

Devolve a lista fixa StatusResupply: 1=Aberto, 2=Iniciado, 3=Finalizado, 4=Cancelado.

---

GET /sku/inventory-summary

skuInventorySummaryList · autenticado

Lista inventários (StockKeepingUnitInventorySummary) da empresa, do mais recente para o mais antigo, paginada em blocos de 2000 (use Page). Devolve cabeçalho + colaboradores resolvidos (Login da 1ª, 2ª e 3ª conferência), CD, armazém, status (TypeStatusSkuInventory), tipo (TypeInventorySummary) e os totais agregados das filas (StockKeepingUnitInventorySummarySkuQueueCount e StockKeepingUnitInventorySummaryLocationQueueCount).

Aceita filtros por status (lista separada por vírgula), CD, armazém, intervalo de criação (DateFrom/DateTo), código do inventário e colaborador. O filtro de colaborador (RecordUserStart) considera o usuário em qualquer uma das três conferências.

---

POST /sku/inventory-summary

skuInventorySummaryPost · autenticado · privilégio PrivilegeInventorySummaryCreate

Cria o inventário no status 2 (Aberto). Valida em sequência:

• A empresa autenticada existe.
• O armazém (IDStockKeepingUnitWarehouse) é obrigatório, pertence à empresa (incluindo idcompanymainshare) e está ativo (Status = 1).
• O tipo de inventário (IDTypeInventorySummary) existe — 1 Endereço, 2 SKU, 3 Livre, 4 Auditoria. Default 1.
• O centro de distribuição, quando informado, pertence à empresa.
• A estratégia de quantidade (IDTypeQuantity) existe — 1 Não compensar negativos (default), 2 Somar quantidade reservada, 3 Compensar negativos. No frontend, "Compensar saldo negativo = Sim" envia 3.

Após o INSERT, invoca internamente skuInventorySummaryGet e devolve o inventário completo.

---

GET /sku/inventory-summary/{IDStockKeepingUnitInventorySummary}

skuInventorySummaryGet · autenticado · privilégio PrivilegeInventorySummaryView na tela

Detalhe completo do inventário. Inclui:

• Cabeçalho — campos do StockKeepingUnitInventorySummary mais o texto do status, tipo, estratégia de quantidade e Login dos três colaboradores.
• Items — uma linha por SKU + lote contado, com QuantityBatch (saldo esperado do lote no momento do lançamento), QuantityInventory / Second / Third (quantidades das três conferências) e QuantityInventoryDiff / Second / Third (diferença em relação ao esperado). Traz também BarCodeList, BarCodePackageList e MainImageThumbnailURL para suporte ao app de coletor. A data de validade vem como null quando o registro usa o sentinel 4000-01-01.
• StockKeepingUnitInventorySummarySkuQueue — fila de SKUs a inventariar (tipo SKU).
• StockKeepingUnitInventorySummaryLocationQueue — fila de endereços a inventariar (tipo Endereço). Quando todos os endereços têm coordenadas (Floor, Street, Module, Column, Level, LocationSide), a lista é ordenada por trajeto serpentino (Floor ASC, Street ASC, serpentina por rua, lado preferencial por direção, Column/Level) para otimizar o picking; sem coordenadas, ordena por Address natural-sort.

Query ?Draft=1 devolve o rascunho salvo em Redis em skuInventorySummarySku:<id> (TTL 4 dias).

---

PUT /sku/inventory-summary/{IDStockKeepingUnitInventorySummary}

skuInventorySummaryPut · autenticado · privilégio PrivilegeInventorySummaryEdit (status) ou PrivilegeCollaboratorsAssignmentInventory (atribuir colaborador)

Atualiza o cabeçalho:

• Encerrar conferência — IDTypeStatusSkuInventory aceita 6 (Fim 1ª), 7 (Fim 2ª) ou 8 (Fim 3ª). Cada transição grava o timestamp correspondente (InventoryFirstFinishTimestamp / InventorySecondFinishTimestamp / InventoryThirdFinishTimestamp).
• Atribuir colaborador — InventoryStartUser aceito quando o status < 6; InventorySecondUserStart quando status = 6; InventoryThirdUserStart quando status = 7. O usuário precisa estar ativo (UserCompany.Status = 1) na empresa.

Ao encerrar a 1ª conferência de um inventário de Auditoria (IDTypeInventorySummary = 4), o handler:

1. Lê a fila de SKUs do inventário.
2. Busca todos os lotes (StockKeepingUnitBatch.Show = 1) com saldo diferente de zero no armazém do inventário, filtrando pela fila de SKUs quando a fila tem itens.
3. Para cada lote que ainda não foi lançado em StockKeepingUnitInventoryItems, faz um INSERT com QuantityInventory = 0 e QuantityBatch = saldo apurado.
4. Quando IDTypeQuantity = 3 (Compensar negativos), prioriza esses lotes.

Bloqueios: Inventário já esta finalizado (status 1), Inventário esta cancelado (status 4), Inventário não pode ter a primeira /segunda/terceira conferência finalizada novamente (transição para 6 /7/8 a partir de um status já fechado).

Após a atualização, invoca skuInventorySummaryGet e devolve o inventário completo.

---

DELETE /sku/inventory-summary/{IDStockKeepingUnitInventorySummary}

skuInventorySummaryDelete · autenticado · privilégio PrivilegeInventorySummaryDelete

Cancela o inventário (IDTypeStatusSkuInventory = 4). Não dispara movimentação. Bloqueado quando o inventário já está Finalizado (status = 1).

---

POST /sku/inventory-summary/{IDStockKeepingUnitInventorySummary}/finish

skuInventorySummaryFinishPost · autenticado · privilégio PrivilegeInventorySummaryFinish

Finaliza o inventário e gera os ajustes de estoque. Passos:

1. Lê todos os itens contados ainda não movimentados (IDSkuMovement IS NULL) agrupados por IDSku + IDBatch.
2. Bloqueia se algum item tem o lote inativo (StockKeepingUnitBatch.Show = 0) — retorna Lote do item {IDSkuCompany} está inativo.
3. Para inventário tipo Endereço (IDTypeInventorySummary = 1), localiza endereços que estavam na fila mas não foram contados, busca os lotes com saldo nesses endereços, e cria linhas StockKeepingUnitInventoryItems com QuantityInventory = 0 e QuantityBatch = saldo apurado (compensar os endereços não inventariados).
4. Muda o status para 5 (Processando).
5. Para cada item, compara a última quantidade contada disponível (QuantityInventoryThird ?? QuantityInventorySecond ?? QuantityInventory) com QuantityBatch e cria uma movimentação em StockKeepingUnitMovement (IDTypeMovement = 0 para entrada, IDTypeMovement = 1 para saída) com Quantity = abs(diff), IDStatusSku = 1 e ValueCostTotal = Quantity × cost.
6. O custo aplicado é, nessa ordem: CostSet (custo manual do SKU, quando a parâmetro de empresa UseCostFromCostSet = 1 está ativo); caso contrário, CostAverage (StockKeepingUnitBalance.InventoryValue / QtyAvailable); quando o custo médio é zero, usa CostLastPurchase do SKU.
7. Para cada movimento, atualiza o item com IDSkuMovement = insertId e envia uma mensagem SkuBalanceInventoryFinish para a fila SQS webhook.fifo (com IDStockKeepingUnitInventorySummary, IDSku, IDStockKeepingUnitWarehouse, IDBatch, Quantity, IDTypeMovement, AccountName, ModificationTimestamp e atributo IDCompany).
8. Ao concluir, muda o status para 1 (Finalizado) e grava InventoryFinishTimestamp = NOW().

Bloqueios: inventário não localizado para finalizar, inventário não tem itens, Status inventário não permite finalizar (status fora de 2, 3, 6, 7, 8).

---

POST /sku/inventory-summary/{IDStockKeepingUnitInventorySummary}/sku

skuInventorySummarySkuPost · autenticado · privilégio PrivilegeInventorySummaryItemCreate

Endpoint multi-uso, controlado pela query string:

Modo A — fila de endereços (IDTypeQueue=1). Adiciona endereços em StockKeepingUnitInventorySummaryLocationQueue. Com AddAllLocations=1, inclui automaticamente todos os endereços do armazém do inventário com saldo de lote diferente de zero. Sem essa flag, espera body { IDStockKeepingUnitLocation } (objeto ou array); valida que o endereço pertence a um armazém do CD do inventário.

Modo B — fila de SKUs (IDTypeQueue=2). Adiciona SKUs em StockKeepingUnitInventorySummarySkuQueue. Com AddAllSkus=1, inclui todos os SKUs ativos (StockKeepingUnit.IDStatusSku <> 0) dos tipos Produto/Kit/Insumo (IDTypeSku IN (3, 6, 7)) da empresa com saldo de lote no CD do inventário. Sem a flag, valida que o SKU é Produto/Kit/Insumo e pertence à empresa.

Modo C — lançamento de contagem (sem IDTypeQueue). Insere em StockKeepingUnitInventoryItems o que foi contado. Espera { IDSku, IDStockKeepingUnitWarehouse, QuantityInventory, IDBatchNumber?, BestBeforeDate?, ManufacturingDate?, BatchComments? }. Quando o body não traz IDBatchNumber, o sistema distribui a quantidade entre os lotes existentes do SKU no armazém (ordenando por saldo positivo primeiro, depois por validade e número do lote), aplicando o delta contra o saldo de cada lote (consome saldo positivo se a contagem é menor, soma se é maior) — quando não há saldo em lote algum, cria um lote no endereço padrão. Quando o SKU não tem nenhum lote no armazém, cria um endereço "Principal" (se necessário) e um lote vazio antes de inserir o item.

Quando o request envia o IDStockKeepingUnitLocation (query) sem IDTypeQueue, o sistema assume contagem por endereço: para qualquer SKU que tinha saldo no endereço e não veio no body, cria automaticamente uma linha com QuantityInventory = 0 (zera os ausentes da contagem).

IDTypeQuantity (query) sobrescreve a estratégia de quantidade do cadastro e altera o cálculo de saldo de referência:

• 2 (Somar quantidade reservada) — antes de gravar, soma a Quantity de pedidos em manuseio (Orders com IDStatusOrder NOT IN (0, 1, 9) e movimentação IDStatusSku = 0).
• 3 (Compensar negativos) — antes de gravar, soma |QtyAvailable| quando o saldo do SKU está negativo.

O parâmetro de empresa ConsiderBatchBalanceAfterShipped reduz o cálculo do QuantityBatch ao considerar apenas pedidos já expedidos (IDStatusSku = 1 nas movimentações de saída).

Quando recebe o primeiro item lançado com QuantityInventory, o sistema atribui o usuário autenticado como InventoryStartUser e (quando o inventário está no status 2) muda para 3 (Em andamento) e grava InventoryStartTimestamp = NOW(). Para QuantityInventorySecond ou QuantityInventoryThird, atribui InventorySecondUserStart / InventoryThirdUserStart e muda o status para 9 / 10.

Draft=1 salva o body em Redis (skuInventorySummarySku:<id>, TTL 4 dias) sem persistir no banco — usado pelo app de coletor para guardar contagem parcial.

Quando o body é array, erros parciais são acumulados em uma lista de objetos ({ IDSku|Armazem|Lote, Description, Status: 0 }) que vira o retorno em caso de qualquer falha; quando o body é objeto e há erro, devolve via [BadRequest].

Bloqueios: Inventário já esta finalizado / Inventário esta cancelado / Inventário não existe / Sku não existe / Armazém não existe / Endereço não existe para armazém / Lote não existe.

---

DELETE /sku/inventory-summary/{IDStockKeepingUnitInventorySummary}/sku

skuInventorySummaryQueueDelete · autenticado · privilégio PrivilegeInventorySummaryItemDelete

Remove SKU ou endereço da fila de contagem. Exige exatamente uma das query strings:

• IDStockKeepingUnitInventorySummarySkuQueue — remove de StockKeepingUnitInventorySummarySkuQueue.
• IDStockKeepingUnitInventorySummaryLocationQueue — remove de StockKeepingUnitInventorySummaryLocationQueue.

Bloqueado quando o inventário está Finalizado ou Cancelado.

---

PUT /sku/inventory-summary/{IDStockKeepingUnitInventorySummary}/sku/{IDStockKeepingUnitInventoryItems}

skuInventorySummarySkuPut · autenticado · privilégio PrivilegeInventorySummaryItemEdit (ou PrivilegeInventorySummaryAllowEditQuantity quando configurado)

Atualiza a quantidade contada de um item já existente. O handler escolhe a conferência ativa pelo status do inventário e descarta os campos das demais:

• Status 3 (Em andamento) → grava QuantityInventory.
• Status 6 ou 9 (Fim 1ª / Processando 2ª) → grava QuantityInventorySecond.
• Status 7 ou 10 (Fim 2ª / Processando 3ª) → grava QuantityInventoryThird.

Quando QuantityInventorySecond ou Third é enviado e a conferência correspondente ainda não foi iniciada (InventorySecondStartTimestamp ou InventoryThirdStartTimestamp IS NULL), o handler atribui o usuário autenticado como colaborador da rodada e muda o status para 9 ou 10.

O body é um array (o backend lê body[0]). Aceita também BestBeforeDate, ManufacturingDate e BatchComments para SKUs com rastreabilidade obrigatória. Bloqueios: Sku inventário não encontrado, Inventário já esta finalizado, Inventário esta cancelado.

---

DELETE /sku/inventory-summary/{IDStockKeepingUnitInventorySummary}/sku/{IDStockKeepingUnitInventoryItems}

skuInventorySummarySkuDelete · autenticado · privilégio PrivilegeInventorySummaryItemDelete

Remove uma linha de item já lançada (StockKeepingUnitInventoryItems). Bloqueado quando o inventário está Finalizado (1) ou Cancelado (4).

---

GET /purchase/schedule

purchaseScheduleList · autenticado

Lista os agendamentos de recebimento (StockKeepingUnitPurchaseSchedule) da empresa, ordenados por StartTime ascendente. Inclui dados do recebimento amarrado quando há:

• Fornecedor: IDSupplier, SupplierCpfCnpj, SupplierNameCorporateName.
• Nota fiscal: serie, nNF, dhEmi, qVol (volumes), Weight (peso bruto).
• Recebimento: CheckinTimestamp, IDStatusPurchase, StatusPurchase.
• Agregados: ItemsQuantity (soma de quantidades), SkuQuantity (SKUs distintos).

Status calculado (StockKeepingUnitPurchaseScheduleStatus):

Código	Nome	Cor	Condição
1	Recebido	Verde	CheckinTimestamp preenchido.
2	Agendado	Azul	EndTime > NOW() e sem check-in.
3	Atrasado	Vermelho	EndTime < NOW() e sem check-in.
4	Não agendado	Cinza	Sem IDPurchase (agendamento avulso).

Aceita filtros: IDStockKeepingUnitPurchaseSchedule, IDPurchase, StartTime (≥ data), EndTime (≤ data 23:59:59).

---

POST /purchase/schedule

purchaseSchedulePost · autenticado

Cria agendamento. Validações:

• StartTime ≤ EndTime (caso contrário Data de início precisa ser menor que data de término).
• IDPurchase (quando informado): recebimento precisa existir na empresa e ainda não ter agendamento ativo (Recebimento já esta agendado para <data>).
• Sem IDPurchase → cria agendamento avulso (bloqueio de horário sem amarrar recebimento — útil para manutenção, almoço, etc.).

Erros: [BadRequest] - Data de início precisa ser menor que data de término; [BadRequest] - Recebimento já esta agendado para <data>; [BadRequest] - Recebimento não existe; [BadRequest] - Empresa não existe.

---

PUT /purchase/schedule/{idstockkeepingunitpurchaseschedule}

purchaseSchedulePut · autenticado

Atualização parcial. Mesmas validações do POST. Trocar IDPurchase exige que o novo recebimento não esteja agendado.

Erros: [BadRequest] - Agendamento não existe; demais idem POST.

---

DELETE /purchase/schedule/{idstockkeepingunitpurchaseschedule}

purchaseScheduleDelete · autenticado

Exclusão física. Sem regra de bloqueio. Devolve "sucesso".

Erros: [BadRequest] - Agendamento não existe.

---

GET /purchase/schedule/config

purchaseScheduleConfigList · autenticado

Lista as configurações de agenda de recebimento da empresa (StockKeepingUnitPurchaseScheduleConfig). Cada item junta:

• Cabeçalho da configuração — duração da janela, limites diários (MaxItemsPerDay, MaxSchedulePerDay), antecedência mínima (ScheduleMinimumAdvanceTimeHour), janela máxima de antecipação (ScheduleMaximumTimeAheadDay), tolerância de check-in (HourDifferenceAllowed).
• Nome do CD resolvido (DistributionCenterName).
• Array StockKeepingUnitPurchaseScheduleConfigTimetable com as faixas por dia da semana, ordenadas por WeekDay ASC, StartTime ASC.

Aceita IDStockKeepingUnitPurchaseScheduleConfig para detalhar uma configuração específica.

Resposta 200 — array de PurchaseScheduleConfigItem.

---

POST /purchase/schedule/config

purchaseScheduleConfigPost · autenticado

Cria a configuração de agenda para um CD. Regra de unicidade: 1 CD = 1 configuração. Segunda tentativa devolve [BadRequest] - Já existe uma agenda para esse centro de distribuição.

Quando o body inclui StockKeepingUnitPurchaseScheduleConfigTimetable (array de { WeekDay, StartTime, EndTime }), o backend insere as faixas em bloco em StockKeepingUnitPurchaseScheduleConfigTimetable. Sem o array, a configuração é criada sem horários e o agendamento fica indisponível até alguém editar.

Erros: [BadRequest] - Centro de distribuição precisa ser informado; [BadRequest] - Centro de distribuição não existe; [BadRequest] - Já existe uma agenda para esse centro de distribuição; [BadRequest] - Empresa não existe.

---

PUT /purchase/schedule/config/{idstockkeepingunitpurchasescheduleconfig}

purchaseScheduleConfigPut · autenticado

Atualização parcial do cabeçalho. Comportamento do StockKeepingUnitPurchaseScheduleConfigTimetable:

Body	Efeito
Não envia o campo	Timetable atual fica intacta.
Envia [] (array vazio)	Apaga todas as faixas — agendamento fica indisponível.
Envia array preenchido	DELETE + INSERT em bloco — substitui todas as faixas.

Trocar IDStockKeepingUnitDistributionCenter exige que o novo CD não tenha outra configuração existente.

Erros: [BadRequest] - Configuração agendamento não existe; [BadRequest] - Centro de distribuição não existe; [BadRequest] - Já existe uma agenda para esse centro de distribuição.

---

DELETE /purchase/schedule/config/{idstockkeepingunitpurchasescheduleconfig}

purchaseScheduleConfigDelete · autenticado

Exclusão física. A tabela StockKeepingUnitPurchaseScheduleConfigTimetable tem ON DELETE CASCADE, então as faixas de horário são apagadas automaticamente. Devolve a string literal sucesso.

Erros: [BadRequest] - Configuração agendamento não existe.

---

GET /fulfillment/picking/configuration

orderFulfillmentPickingConfigurationList · autenticado

Lista as configurações da empresa. Retorna o nome resolvido do CD (DistributionCenterName) e do tipo de picking (TypePickingList). As listas CSV são entregues como arrays depois do split por vírgula: IDCompanyIntegrationList, IDOrderTypeList, IDCarrierList, WeekIntervalAutoGenerate.

Aceita filtro IDPickingListConfiguration para detalhar uma única configuração.

Resposta 200 — array de PickingListConfigurationItem.

---

POST /fulfillment/picking/configuration

orderFulfillmentPickingConfigurationPost · autenticado

Cria uma configuração. Validações em cascata:

1. PickingListConfigurationName obrigatório e único na empresa.
2. StartAutoGenerateTime e FinishAutoGenerateTime obrigatórios; o início precisa ser ≤ fim.
3. ItemsQtyLimit, OrderQtyLimit, SkuQtyLimit numéricos quando informados.
4. OrderPriority entre 0 e 10.
5. WeekIntervalAutoGenerate é um array de inteiros 0-6 (0=Domingo, 6=Sábado). Vazio = todos os dias.
6. Cada IDCompanyIntegration na lista precisa existir na empresa e ter Show = 1.
7. Cada IDTypeOrder precisa existir na empresa e ter Status = 1.
8. Cada IDCarrier precisa ser fornecedor da empresa com IDTypeSupplier = 2 (Transportadora).
9. IDStockKeepingUnitDistributionCenter precisa pertencer à empresa.
10. IDTypePickingList precisa existir (1, 2, 3 ou 4).

Tipos de picking (TypePickingList):

ID	Nome	O que faz
1	Picking	Somente separação. Faturamento vem em outra etapa.
2	Picking & Packing	Separação + emissão da nota fiscal no mesmo passo.
3	Monopedido	Cada picking list contém um único pedido.
4	Colméia	Cadastrado na tabela mas hoje não exposto no formulário da tela.

Request body — PickingListConfigurationCreate. Devolve o item via list após o insert.

Erros: ver lista completa em OpenAPI. Principais: [BadRequest] - Preencha corretamente o nome da configuração; [BadRequest] - Nome de configuração já existente; [BadRequest] - Preencha corretamente horário de início e fim de geração de picking-list; [BadRequest] - Horário de início precisa ser menor que horário final; [BadRequest] - Prioridade pedido precisa ser entre 0 e 10; [BadRequest] - Preencha corretamente os dias de geração de picking-list; [BadRequest] - Integração(s) não localizada(s): <ids>; [BadRequest] - Tipo pedido(s) não localizada(s): <ids>; [BadRequest] - Transportadora(s) não localizada(s): <ids>; [BadRequest] - Centro de distribuição não existe; [BadRequest] - Tipo de picking list não existe.

---

PUT /fulfillment/picking/configuration/{idpickinglistconfiguration}

orderFulfillmentPickingConfigurationPut · autenticado

Atualização parcial. Aplica as mesmas validações do POST exceto a unicidade do nome (mantém o nome original quando não enviado). Listas CSV podem ser limpas enviando "" ou [] no body.

Erros: idem POST + [BadRequest] - Configuração picking list não encontrada.

---

DELETE /fulfillment/picking/configuration/{idpickinglistconfiguration}

orderFulfillmentPickingConfigurationDelete · autenticado

Exclusão física. Sem regras de bloqueio — picking lists já geradas no histórico continuam intactas. Devolve a string literal Configuração de picking-list excluída com sucesso.

Erros: [BadRequest] - Informe corretamente a configuração de picking-list; [BadRequest] - Empresa não existe (também usado quando a configuração não pertence à empresa autenticada).

---

GET /sku/location

skuLocationList · autenticado

Lista endereços (StockKeepingUnitLocation) da empresa, com dois modos controlados pelo query OnlyLocation:

• OnlyLocation=1 — modo cadastro. Retorna 1 linha por endereço. Inclui dimensões, tipo, categoria, grupo, armazém e CD. Filtra por L.Status quando informado. Aplica restrição de CDs permitidos ao usuário (UserCompanyDistributionCenter:<prefix>:<user>).
• OnlyLocation ausente — modo legado. LEFT JOIN StockKeepingUnitBatch + StockKeepingUnit devolve 1 linha por lote vinculado ao endereço, com QtyAddress (saldo calculado por soma de StockKeepingUnitMovement). Sempre filtra L.Status = 1. Aceita filtro Empty (HAVING QtyAddress = 0/<> 0).

Quando a empresa tem ShareSkuLocationWithRelatedCompanies = 1 em uma integração tipo 16, a query também inclui endereços da empresa-mãe (CompanyMain.IDCompanyMain).

Paginação por Page * 5000.

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno.

---

POST /sku/location

skuLocationPost · autenticado

Cria endereço(s). O comportamento depende do parâmetro NewAddressParameter (Configurações → Logística (WMS) → Endereço → "Utiliza endereço completo?"):

Modo WMS (NewAddressParameter = 1):

Obrigatórios: IDStockKeepingUnitWarehouse, IDTypeAddress, IDStockKeepingUnitLocationCategory, dimensões (Height, Width, Length, MaxWeight — todos > 0).

• Individual: enviar Floor, Street, Module (numérico), Column (alfanumérico, letras viram maiúsculas), Level (numérico). Backend monta Address = Floor-Street-Module-Column-Level. O separador padrão é -; pode ser customizado via Concatenator (-, . ou |). Falha quando já existe esse Floor/Street/Module/Column/Level no CD.
• Em massa (BulkLocation = 1): enviar Floor, Street, StartModule/EndModule, StartColumn/EndColumn, StartLevel/EndLevel. Backend gera o produto cartesiano. Falha se qualquer endereço gerado já existe no CD.

Validações: armazém ativo da empresa; categoria ativa da empresa; grupo opcional da empresa; tipo de endereço válido (1/2/3). Para cadastro em massa, EndModule ≥ StartModule, EndColumn ≥ StartColumn (quando letras, dentro do alfabeto), EndLevel ≥ StartLevel, e Módulo e Nível precisam ser numéricos.

Modo legado (NewAddressParameter = 0):

Obrigatório: Address (string livre). IDStockKeepingUnitWarehouse opcional — quando informado, valida que o armazém pertence à empresa e que não existe outro endereço com mesmo nome no CD. Default = 1 zera o Default dos outros endereços do armazém antes de inserir.

Resposta 200 — modo individual: array com 1 item de SkuLocationListItem. Modo em massa: string Endereços cadastrados com sucesso.

Erros — ver lista completa no schema OpenAPI. Principais: [BadRequest] - As dimensões do endereço não podem ser negativas ou vazias; [BadRequest] - Preencha corretamente o armazém, tipo e categoria de armazenamento; [BadRequest] - Já existe este endereço para o mesmo centro de distribuição; [BadRequest] - Endereços repitidos, consulte seus endereços (modo em massa).

---

PUT /sku/location/{idstockkeepingunitlocation}

skuLocationPut · autenticado

Atualização parcial. No modo WMS, dimensões precisam ser positivas (quando enviadas); módulo e nível precisam ser numéricos (quando alterados); se o nome (Address) não vier no body, é recalculado como Floor-Street-Module-Column-Level usando o separador detectado no endereço original.

Bloqueio importante: quando o endereço já tem movimento (StockKeepingUnitMovement via lote vinculado), não pode mudar o armazém — devolve Endereço não pode ter armazém alterado, pois já possui venda. Isso preserva histórico de origem/destino dos lotes.

Ao marcar Default = 1, zera o Default dos demais endereços do mesmo armazém antes de aplicar a alteração.

Erros: [BadRequest] - Localização não existe; [BadRequest] - As dimensões do endereço não podem ser negativas; [BadRequest] - Preencha módulo e nível com números; [BadRequest] - Endereço não pode ter armazém alterado, pois já possui venda; [BadRequest] - Armazém não localizado; [BadRequest] - Preencha corretamente a categoria de armazenamento; [BadRequest] - Preencha corretamente o tipo de endereço; [BadRequest] - Grupo endereço não encontrado; [BadRequest] - Já existe este endereço para o centro de distribuição.

---

DELETE /sku/location/{idstockkeepingunitlocation}

skuLocationDelete · autenticado

Exclusão física. Verifica SELECT * FROM StockKeepingUnitBatch WHERE IDStockKeepingUnitLocation = ? — se há lote vinculado, devolve [BadRequest] - Endereço possui lote/sku vinculado e não pode ser removido.

Sem vínculos: executa DELETE FROM StockKeepingUnitLocation WHERE IDStockKeepingUnitLocation = ? e devolve a string literal sucesso.

Erros: [BadRequest] - Endereço não existe.

---

GET /sku/location/{idstockkeepingunitlocation}/label

purchaseLabelGet · autenticado

Devolve o ZPL pronto para impressão da etiqueta do endereço. Reaproveita o handler de etiqueta usado em outros módulos — o conteúdo é controlado pelo template de etiqueta de endereço configurado para a empresa.

---

GET /user/workingday

userWorkingDayList · autenticado

Lista colaboradores (UserWorkingDay) da empresa, juntando escala (UserWorkScale), turnos (UserWorkShift), funções permitidas (UserJobPosition), função atual, categorias de endereço (StockKeepingUnitLocationCategory), grupos de endereço (StockKeepingUnitLocationGroup) e supervisor.

Aceita filtros: IDUserWorkingDay, IDUser, IDStockKeepingUnitLocationCategoryList (string CSV — comparação exata), IDUserJobPositionList (id único — FIND_IN_SET), Status, IDWorkScale, IDUserUpper.

Em modo multi-empresa com accountname=all, o handler agrupa todas as empresas do contexto; caso idcompanymainshare esteja preenchido, adiciona essa empresa-mãe à lista.

Resposta 200 — array de UserWorkingDayListItem (com WorkShift, JobPositions, Categories, LocationsGroup resolvidos como arrays).

---

POST /user/workingday

userWorkingDayPost · autenticado

Cria um colaborador para um IDUser existente. Cada usuário só pode ter 1 registro UserWorkingDay por empresa — tentativa de duplicar devolve Colaborador já existe para esse usuário.

Validações em cascata:

1. IDUser + IDUserJobPositionList + IDUserWorkScale obrigatórios.
2. Usuário precisa ter vínculo com a empresa (UserCompany).
3. Para cada IDUserJobPosition informado, valida que existe.
4. IDUserJobPositionCurrent (quando informado) precisa estar dentro da lista IDUserJobPositionList.
5. Cada IDStockKeepingUnitLocationCategory informada precisa pertencer à empresa e estar ativa (IsActive = 1).
6. Cada IDStockKeepingUnitLocationGroup precisa pertencer à empresa.
7. IDUserWorkScale precisa pertencer à empresa.
8. IDUserUpper (quando informado) precisa ser um IDUserWorkingDay existente.

Request body — UserWorkingDayCreate. Listas CSV vão como string ("1,2,3").

Erros — ver tabela em POST /user/workingday.

---

PUT /user/workingday/{idworkingday}

userWorkingDayPut · autenticado

Atualização parcial. Diferenças relevantes em relação ao POST:

• Para limpar IDStockKeepingUnitLocationCategoryList, IDStockKeepingUnitLocationGroupList ou IDUserUpper, envie string vazia "" no body — o handler trata como NULL.
• Bloqueia colaborador ser próprio supervisor (IDUserUpper === IDUserWorkingDay).
• Validações de função/categoria/grupo só rodam quando o valor mudou em relação ao registro atual.

---

DELETE /user/workingday/{idworkingday}

userWorkingDayDelete · autenticado

Exclusão física. Verifica SELECT * FROM UserWorkingDay WHERE IDUserUpper = ? — se o colaborador é supervisor de outro colaborador, devolve [BadRequest] - Colaborador é supervisor de outros colaboradores e não pode ser excluído.

Devolve a string literal Colaborador excluído com sucesso em caso de sucesso.

---

GET /carrier/quotation/error

carrierQuotationErrorList · autenticado

Lista read-only dos 3000 erros mais recentes (CarrierQuotationError) gerados pelo endpoint público de cotação de frete (carrierQuotationPost, handler PHP) da empresa autenticada, ordenados por IDCarrierQuotationError DESC.

Cada item traz:

• IDCarrierQuotationError, RecordTimestamp, RecordUserCreated.
• IDTypeCarrierQuotationError + TypeCarrierQuotationError (texto amigável do tipo).
• ShippingPostalCode (8 dígitos, com padding de zeros à esquerda).
• IDSkuHub (SKU enviado pelo canal; preenchido em erros tipo 1, 4, 5).
• IDCompanyIntegration + CompanyIntegrationName (formato IntegrationName - CompanyIntegrationName).
• AccountName.

Tipos de erro (IDTypeCarrierQuotationError):

ID	Nome	Causa
1	Variação canal não localizada	SKU do canal sem mapeamento na integração.
2	Sku não localizado	SKU não cadastrado.
3	Cep não localizado	CEP destino fora da base ou em formato inválido.
4	Sku sem peso cadastrado	SKU encontrado mas SkuWeight vazio.
5	Sku sem dimensões cadastradas	SKU encontrado mas falta SkuWidth, SkuHeight ou SkuLength.
6	Tipo integração de venda não localizada	IDTypeCompanyIntegration não suportado pelo endpoint.

Fluxo de gravação: o handler PHP grava cada erro primeiro em Redis (CarrierQuotationError:<uuid>) com RecordTimestamp, ShippingPostalCode, IDCompany, RecordUserCreated, IDTypeCarrierQuotationError, IDSkuHub, IDCompanyIntegration. O worker cachetodb.php consome essa chave do Redis e materializa o registro na tabela CarrierQuotationError.

Query params

Nome	Tipo	Obrigatório	Descrição
DateFrom	date (YYYY-MM-DD)	não	Filtra RecordTimestamp ≥ data.
DateTo	date (YYYY-MM-DD)	não	Filtra RecordTimestamp ≤ data 23:59:59.

Resposta 200 — array de CarrierQuotationErrorListItem (até 3000).

Erros

Status	Quando
400	[BadRequest] - Erro na configuração da empresa.
500	Erro interno.

---

NF Serviço Tomado

Feed de NFSe recebidas dos fornecedores (frontend pages/feeds/nfs, /app/invoiceservice, módulo 91). Caixa de entrada das notas fiscais de serviço emitidas para o CNPJ da empresa — capturadas automaticamente da prefeitura por cron PHP (não pela API REST). Distinta da tela Nota Fiscal de Serviço (/app/nfeinvoiceservice, módulo 105) que cobre NFSe emitidas pela empresa.

Método	Rota	Função	Descrição
GET	/invoice-service/feed	invoiceServiceFeedList	Lista (paginação 500/página) das NFSe recebidas. Filtros: fornecedor, número, data, tags. WHERE fixo E.Show = 1. JOIN INNER em NfsServiceCode — notas com código fora da base são descartadas silenciosamente. Quirk: filtro SupplierCpfCnpj referencia coluna inexistente, nunca casa.
GET	/invoice-service/feed/invoice-xml	nfseFeedXmlGet (PHP)	Baixa o XML original (Type=XML) ou a DANFSE em PDF (Type=PDF) de uma nota. Autoriza pela cadeia NfsEvents → CompanyMain → Company.AccountName. PDF do ADN é pré-gerado no S3; outras prefeituras renderizam sob demanda.

Ingestão (não exposta via API):

1. lambdaphp/opt/nfe/feed/feedschedule.php itera empresas com NfseFeedStatus=1 AND CertificadoBestBeforeDate>NOW().
2. nfsefeed.php carrega certificado A1 e consulta cada município com IBGECityCode.NfseFeed=1. CityCode 0 → ADN; outros → SOAP da prefeitura.
3. ServiceFeedNfse->FeedNfseUpdateOnDuplicate grava em NfsEvents (XML em S3 InvoiceServiceFeed/<id>.xml).
4. Eventos de cancelamento marcam IDTypeStatusInvoiceService=2 e NfsCancelDate.

Configuração (vive no Company, não em TypeCompanyParameters):

• Company.NfseFeedStatus = 1.
• Company.CertificadoBestBeforeDate > NOW() (certificado A1 vigente).
• IBGECityCode.NfseFeed = 1 no município (lista interna).

Privilégio (módulo 91): PrivilegeNFsFeedView (id 467) — apenas visualização (sem CRUD; o feed é read-only por natureza).

---

Notas para a próxima geração (escala)

Anotações internas para o time de documentação. Não fazem parte do contrato da API e podem ficar fora da versão publicada.

• O retorno do DELETE /accounts/payable/{idaccountpayable} pode incluir a representação completa de um pedido ou ordem de serviço — esses dois schemas precisam ser documentados em seguida (operações OrderGet e invoiceServiceGet).
• GET de conta a pagar não retorna erro quando o id não existe (devolve []). Vale conferir se esse comportamento se repete em outros endpoints da API.
• Alguns campos aparecem como nullable mesmo sendo obrigatórios no banco — isso acontece quando o vínculo com outra entidade é opcional e o registro relacionado pode não existir. A documentação reflete o que a API efetivamente devolve, não o esquema bruto do banco.