{ "openapi": "3.0.1", "info": { "title": "idworks API", "version": "2026-05-29", "description": "Documentação da API idworks (sa-east-1). Cobre Contas a Pagar (`/accounts/payable`), Contas a Receber (`/accounts/receivable`) — incluindo conciliação de adquirentes e marketplace — Contas Bancárias (`/accounts/bank-account`), Conciliação Bancária (`/accounts/bank-statement`, incluindo transferências e regras), Fluxo de Caixa (`/accounts/cash-flow`), Plano de Contas (`/type/account/type`), Tipo Pedido (`/type/order/type`), Marcas, Fornecedores, Categorias de Fornecedores, Tipo Documento, DE-PARA CFOP recebimento, Webhook, Perfil de Acesso, Ações em Massa e Integrações.\n\nConvenção de erro: as mensagens de erro vêm prefixadas, e cada prefixo corresponde a um status HTTP — `[BadRequest] ...` → 400 e `Error: ...` → 500. Respostas sem prefixo são tratadas como 200, e Produção (Linha de Produção e Ordens de Produção). Inclui também a configuração de Mensagem Tracking (templates de e-mail e webhook disparados nas transições de status de rastreio).", "license": { "name": "Proprietary", "url": "https://idworks.com.br" } }, "servers": [ { "url": "https://{AccountName}.api-idworks.com.br/{basePath}", "description": "Produção (substitua AccountName pelo nome da sua conta)", "variables": { "AccountName": { "default": "teste", "description": "Nome da conta idworks do cliente (use \"teste\" para a conta de demonstração)." }, "basePath": { "default": "1.0", "description": "Versão da API" } } } ], "security": [ { "JWT": [] } ], "tags": [ { "name": "Agendamento de Recebimento" }, { "name": "Armazéns" }, { "name": "Arquivos" }, { "name": "Autenticação" }, { "name": "Boleto Bancário" }, { "name": "CT-e" }, { "name": "Cadastro de Clientes" }, { "name": "Cadastro de Fornecedores" }, { "name": "Cadastro de Usuários" }, { "name": "Categorias Similares" }, { "name": "Categorias de Fornecedor" }, { "name": "Categorias de Produto" }, { "name": "Centros de Distribuição" }, { "name": "Cobrança" }, { "name": "Coleções" }, { "name": "Conciliação Bancária" }, { "name": "Contas Bancárias" }, { "name": "Contas a Pagar" }, { "name": "Contas a Receber" }, { "name": "Correios — PI" }, { "name": "Cotação de Frete" }, { "name": "Códigos Similares" }, { "name": "Códigos de Barras" }, { "name": "Códigos de Barras (Embalagem)" }, { "name": "DE-PARA CFOP Recebimento" }, { "name": "Dashboards" }, { "name": "Departamentos Tributários" }, { "name": "Endereços de Estoque" }, { "name": "Especificações de SKU" }, { "name": "Especificações por Categoria" }, { "name": "Etiquetas (Empresa)" }, { "name": "Faixa de Etiquetas Correios" }, { "name": "Feed de NF-e" }, { "name": "Fluxo de Caixa" }, { "name": "Fornecedores ↔ SKUs" }, { "name": "Frente de Caixa" }, { "name": "Grupos de SKU" }, { "name": "Hub — Anúncios" }, { "name": "Hub — Categorias" }, { "name": "Hub — DE-PARA Adquirentes" }, { "name": "Hub — DE-PARA Transportadora" }, { "name": "Hub — DE-PARA Variações" }, { "name": "Hub — Estoque" }, { "name": "Hub — Marcas" }, { "name": "Hub — Notificações" }, { "name": "Hub — Pagamento" }, { "name": "Hub — Pedidos" }, { "name": "Hub — Política Comercial" }, { "name": "Hub — Recursos" }, { "name": "Hub — Tipos de Referência" }, { "name": "Imagens de SKU" }, { "name": "Integrações" }, { "name": "Inventário" }, { "name": "Inventário (Legacy)" }, { "name": "Jobs e Tarefas" }, { "name": "Jornada de Trabalho" }, { "name": "Kits" }, { "name": "Log de SKU" }, { "name": "Logs de Webhook" }, { "name": "Logística Reversa Correios" }, { "name": "Lotes" }, { "name": "Marcas" }, { "name": "Metas" }, { "name": "Minha Empresa" }, { "name": "Modalidades de Transporte" }, { "name": "Movimentação de Estoque" }, { "name": "Módulos Contratados" }, { "name": "NF-e / NFC-e" }, { "name": "NFS-e" }, { "name": "Notificações de Versão" }, { "name": "Números de Série" }, { "name": "Packing" }, { "name": "Pagamento PDV" }, { "name": "Pedido de Compra" }, { "name": "Pedidos" }, { "name": "Perfis de Acesso" }, { "name": "Picking" }, { "name": "Políticas Comerciais" }, { "name": "Preços" }, { "name": "Produtos e SKUs" }, { "name": "Produção" }, { "name": "Promoção PDV" }, { "name": "Recebimento" }, { "name": "Recálculo de Custo" }, { "name": "Relatórios Customizados" }, { "name": "Ressuprimento" }, { "name": "SKU — Etiqueta" }, { "name": "Saldo de Estoque" }, { "name": "Tags de SKU" }, { "name": "Templates de Importação" }, { "name": "Templates de Rastreamento" }, { "name": "Tipos de Embalagem" }, { "name": "Tipos — CT-e" }, { "name": "Tipos — Canal de Venda" }, { "name": "Tipos — Cliente" }, { "name": "Tipos — Compras" }, { "name": "Tipos — Contas e Pagamento" }, { "name": "Tipos — Cotação" }, { "name": "Tipos — Empresa" }, { "name": "Tipos — Etiquetas" }, { "name": "Tipos — Fornecedor" }, { "name": "Tipos — Fulfillment" }, { "name": "Tipos — Impostos" }, { "name": "Tipos — Jobs" }, { "name": "Tipos — Metas" }, { "name": "Tipos — Nota Fiscal" }, { "name": "Tipos — PDV" }, { "name": "Tipos — Pedido" }, { "name": "Tipos — Relatórios" }, { "name": "Tipos — SKU" }, { "name": "Tipos — Usuário" }, { "name": "Transições de Status" }, { "name": "Variações (Grade)" } ], "paths": { "/accounts/bank-account": { "get": { "operationId": "bankAccountList", "tags": [ "Contas Bancárias" ], "summary": "Lista contas bancárias da empresa", "description": "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.", "parameters": [ { "name": "DateForecast", "in": "query", "required": false, "description": "Data limite (inclusive) para o cálculo de `BalanceForecast`. Default: data atual (não calcula saldo futuro além de hoje).", "schema": { "type": "string", "format": "date" } }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "description": "Filtra apenas contas cujo faturador corresponde a este id de empresa.", "schema": { "type": "integer" } }, { "name": "BankNumber", "in": "query", "required": false, "description": "Filtra pelo código Febraban do banco. Aceita string de até 3 caracteres.", "schema": { "type": "string", "maxLength": 3 } } ], "responses": { "200": { "description": "Lista de contas bancárias (vazia se não houver match).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccountListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "bankAccountPost", "tags": [ "Contas Bancárias" ], "summary": "Cadastra uma conta bancária", "description": "Cria uma conta bancária para a empresa. Quando a conta é marcada como **principal de recebimento** ou **principal de pagamento**, qualquer outra conta da mesma combinação de empresa e faturador é automaticamente desmarcada (só uma pode ser principal por vez).\n\nO faturador, a integração bancária e o tipo de pedido (quando informados) são validados contra os cadastros da empresa.\n\nA resposta é a lista atualizada de contas bancárias, no mesmo formato do `GET /accounts/bank-account`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCreate" } } }, "description": "Dados da conta bancária a cadastrar. `Bank` e `BankNumber` são obrigatórios; demais campos são opcionais. Marcar `MainIncome=1` ou `MainPayment=1` desmarca automaticamente a conta principal anterior do mesmo faturador." }, "responses": { "200": { "description": "Conta criada. Retorna a lista atualizada de contas bancárias.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccountListItem" } } } } }, "400": { "description": "Validação falhou (prefixo `[BadRequest]`). Mensagens possíveis: `Empresa não existe`, `Faturador não existe`, `Integração não existe`, `Integração Pix 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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/bank-account/{idbankaccount}": { "parameters": [ { "name": "idbankaccount", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da conta bancária." } ], "put": { "operationId": "bankAccountPut", "tags": [ "Contas Bancárias" ], "summary": "Atualiza uma conta bancária", "description": "Atualiza a conta bancária de forma parcial — apenas os campos enviados são alterados.\n\nA operação tem **dois modos**, decididos pelo corpo da requisição:\n\n- **Atualização de cadastro** (modo padrão): altera dados como `Bank`, `BankNumber`, `BankRouting`, `AccountNumber`, integração, faturador, terminal TEF, tipo de pedido. Vale a mesma regra do POST: marcar uma conta como principal de recebimento ou pagamento desmarca as demais. Tentar mudar `BankNumber` quando a conta atual é interna (`000`) e existe caixa aberto vinculado é bloqueado.\n- **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 bancário. Quando a diferença é zero, responde com erro.\n\nA resposta (no modo cadastro ou quando há ajuste de saldo aplicado) é a lista atualizada de contas bancárias.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountUpdate" } } }, "description": "Campos da conta bancária a atualizar (atualização parcial — só os enviados são aplicados). Para ativar o **modo de ajuste de saldo inicial**, envie `InitialBalance` junto com `InitialBalanceDate`; nesse modo os demais campos são ignorados e um lançamento de ajuste é gravado no extrato." }, "responses": { "200": { "description": "Conta atualizada. Retorna a lista atualizada de contas bancárias.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccountListItem" } } } } }, "400": { "description": "Validação falhou (prefixo `[BadRequest]`). Possíveis mensagens: `Empresa não existe`, `Faturador não existe`, `Integração não existe`, `Integração Pix 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` (quando o ajuste de saldo resulta em diferença zero).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "bankAccountDelete", "tags": [ "Contas Bancárias" ], "summary": "Exclui (inativa) uma conta bancária", "description": "Inativa a conta bancária (`Status = 0`). Não exclui fisicamente o registro.\n\n**Regras impeditivas**:\n- A conta não pode ter lançamentos de pagamento ou recebimento.\n- A conta não pode estar vinculada como conta prevista em algum título a pagar ou receber.\n- A conta não pode ter sido usada em abertura de caixa do PDV.\n\nA resposta é a lista atualizada de contas bancárias.", "responses": { "200": { "description": "Conta inativada. Retorna a lista atualizada de contas bancárias.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccountListItem" } } } } }, "400": { "description": "Regras impeditivas (prefixo `[BadRequest]`): `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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/bank-statement": { "get": { "operationId": "bankStatementList", "tags": [ "Conciliação Bancária" ], "summary": "Extrato bancário ou conciliação bancária", "description": "Retorna lançamentos do extrato bancário. O comportamento muda conforme o valor de `Source`:\n\n- **`Source=1` (extrato interno)**: lista os lançamentos do extrato do idworks (entradas e saídas conciliadas com títulos a pagar/receber), com saldo corrente calculado linha a linha (`Balance`), saldo do período anterior (`PreviousBalance`), totais de recebimentos/pagamentos e saldo final. A resposta é um objeto único agregado.\n- **`Source=2` (extrato bancário)**: lista os lançamentos importados do banco (conciliação), agrupados por `IDBankStatementConciliation`, com a lista de contas internas (`InternalAccounts[]`) que casam com cada lançamento bancário, totais por tipo e diferença entre o valor lançado no banco e a soma das contas internas. A resposta é um array.\n- **`Source=1` com `IDBankStatementConciliation`** (modo especial): retorna apenas as contas internas vinculadas a uma conciliação bancária específica, como array.\n\nQuando `Source` não é `1` nem `2`, devolve erro. Aceita filtros de data (`DateFrom`/`DateTo`), conta bancária, tipo de transação, status de conciliação, e suporta paginação por `Page`.", "parameters": [ { "name": "Source", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 1, 2 ] }, "description": "`1` extrato interno (idworks), `2` extrato bancário (importado)." }, { "name": "IDBankAccount", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por conta bancária." }, { "name": "IDCompany", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por empresa (quando o usuário tem acesso a múltiplas)." }, { "name": "IDTypeAccount", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Tipo do lançamento: 0=entrada, 1=saída." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial. No modo `Source=2`, default é `2025-01-01` quando omitida." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final. Default: hoje quando `DateFrom` for informada." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Página (5000 itens por página)." }, { "name": "IDBankStatement", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por lançamento interno específico." }, { "name": "IDBankStatementConciliation", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Em `Source=1`, ativa o modo especial que retorna apenas contas internas dessa conciliação. Em `Source=2`, restringe ao grupo." }, { "name": "IDTypeStatusConciliation", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "description": "(Source=2) Filtra por status da conciliação." }, { "name": "OnlyTransfer", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1 ] }, "description": "(Source=1) Quando `1`, traz apenas transferências (lançamentos sem título associado)." }, { "name": "Ignore", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Reservado (lido do query mas sem efeito documentado no caminho atual)." } ], "responses": { "200": { "description": "Resultado depende de `Source` e dos filtros.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BankStatementInternalResponse" }, { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementConciliationEntry" }, "description": "Resposta no modo `Source=2`." }, { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementConciliationInternal" }, "description": "Resposta no modo `Source=1` com `IDBankStatementConciliation`." } ] } } } }, "400": { "description": "Erro de validação dos filtros enviados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "bankStatementPost", "tags": [ "Conciliação Bancária" ], "summary": "Concilia títulos ou transferências com um lançamento bancário ou de adquirente", "description": "Vincula um conjunto de títulos a pagar/receber **ou** de transferências entre contas a um único lançamento — bancário ou de adquirente. O corpo deve identificar **exatamente uma** das duas conciliações em `IDBankStatementConciliation` (conciliação bancária) ou `IDAccountsPayableReceivableConciliation` (conciliação de adquirente), e também **exatamente uma** das listas: `Accounts[]` para títulos a pagar/receber, ou `Transfers[]` para transferências entre contas já lançadas.\n\nFluxo:\n\n- **Conciliação de adquirente** com `Accounts[]`: cria os lançamentos no extrato interno (`AccountsPayableReceivableBankStatement`) para cada título, vincula via `AccountsPayableReceivableConciliationMatch` e marca a conciliação de adquirente como `ConciliationStatus=3` (Manual).\n- **Conciliação bancária** com `Accounts[]`: o status final depende dos valores — `3` quando o total dos títulos bate com o valor bancário, `4` (parcial) quando ainda falta reconciliar.\n- **Quando o título já tem lançamento** com a mesma data da conciliação, o lançamento existente é reaproveitado em vez de criar novo. Lançamentos já vinculados a outra conciliação bloqueiam a operação.\n- **`Transfers[]`** liga transferências entre contas pré-lançadas (sem título associado) à conciliação. Transferências já conciliadas são rejeitadas.\n\nO valor total das contas não pode ultrapassar o valor do lançamento de conciliação (comparação em módulo, para suportar estornos).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementConciliationCreate" } } }, "description": "Identifique **exatamente uma** conciliação (`IDBankStatementConciliation` ou `IDAccountsPayableReceivableConciliation`) e **exatamente uma** das listas (`Accounts` para vincular títulos a pagar/receber, `Transfers` para vincular transferências). `IDBankAccount` é obrigatório." }, "responses": { "200": { "description": "Conciliação efetuada. Retorna um array com 1 item — a conciliação resultante com os lançamentos vinculados e o status final.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementConciliationCreateResponse" }, "maxItems": 1 } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Lançamento de conciliação não selecionado`\n- `Informe apenas uma conciliação: bancária ou de adquirente`\n- `Conta bancária não selecionada`\n- `Contas a receber/pagar é obrigatório e deve ser um array com pelo menos um item`\n- `Transferência é obrigatória e deve ser um array com pelo menos um item`\n- `Accounts[]. Conta a pagar/receber não informada ou inválida`\n- `Transfers[]. Transferência não informada ou inválida`\n- `Empresa não encontrada`\n- `Lançamento de conciliação de adquirente não encontrado`\n- `Lançamento conciliação bancária não encontrado`\n- `Conta bancária não encontrada`\n- `Contas não encontradas: `\n- `O valor total dos lançamentos () é maior que o valor do título (). Código do título: . Lançamentos: `\n- `Divergência na data dos pagamentos realizados e a data do `\n- `Título já esta conciliado na conciliação bancária código: `\n- `O valor total das contas () é maior que o valor do (). Não é possível conciliar.`\n- `Transferência(s) não encontradas ou já conciliadas: `\n- `Falha ao processar conciliação`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/bank-statement/transfer": { "post": { "operationId": "bankStatementTransferPost", "tags": [ "Conciliação Bancária" ], "summary": "Cria uma transferência entre contas bancárias", "description": "Registra uma transferência de valor entre duas contas bancárias da empresa. Gera dois lançamentos no extrato interno (`AccountsPayableReceivableBankStatement`): um de débito (saída) na conta de origem e um de crédito (entrada) na conta de destino. Os dois lançamentos ficam ligados por uma referência única (`AccountsPayableReceivableBankStatementTransfer`), o que permite tratá-los como o mesmo movimento ao reconciliar.\n\nAs descrições dos lançamentos são geradas automaticamente concatenando a descrição informada (ou o texto padrão `Transferência entre contas`) com o banco e o número da conta do outro lado da operação. A origem e o destino não podem ser a mesma conta.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementTransferCreate" } } }, "description": "Dados da transferência entre contas. `IDBankFrom`, `IDBankTo` e `Value` são obrigatórios; `IDBankTo` precisa ser diferente de `IDBankFrom` e `Value` precisa ser maior que zero. A descrição informada é concatenada com o banco e a conta do outro lado nos dois lançamentos gerados." }, "responses": { "200": { "description": "Transferência registrada. Retorna detalhes da transferência e os dois lançamentos criados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementTransferCreateResponse" } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Conta bancária de origem não informada`\n- `Conta bancária de destino não informada`\n- `A conta de origem e destino não podem ser a mesma`\n- `Valor deve ser maior que zero`\n- `Empresa não encontrada`\n- `Uma ou ambas as contas bancárias não foram encontradas ou não pertencem a esta empresa`\n- `Conta bancária de origem não encontrada`\n- `Conta bancária de destino não encontrada`\n- `Falha ao inserir transação de débito`\n- `Falha ao inserir transação de crédito`\n- `Falha ao processar transferência`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/bank-statement/transfer/{idbankstatement}": { "parameters": [ { "name": "idbankstatement", "in": "path", "required": true, "description": "Identificador de **um** dos dois lançamentos da transferência (débito ou crédito). O outro lado é resolvido automaticamente pelo sistema.", "schema": { "type": "integer", "format": "int32" } } ], "delete": { "operationId": "bankStatementTransferDelete", "tags": [ "Conciliação Bancária" ], "summary": "Exclui uma transferência entre contas bancárias", "description": "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 autenticada e remove **a referência da transferência e os dois lançamentos** do extrato.\n\nFalha quando o lançamento informado não é parte de uma transferência ou quando um dos lados pertence a outra empresa.", "responses": { "200": { "description": "Transferência excluída. Retorna a referência removida e os dados resumidos dos dois lançamentos apagados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementTransferDeleteResponse" } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Empresa não encontrada`\n- `Lançamento não é uma transferência ou não foi encontrado`\n- `Uma ou ambas as transações não pertencem a esta empresa`\n- `Falha ao excluir as transações`\n- `Falha ao excluir transferência`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/bank-statement/conciliation-rule": { "get": { "operationId": "bankStatementConciliationRuleList", "tags": [ "Conciliação Bancária" ], "summary": "Lista regras de conciliação automática", "description": "Retorna as regras de conciliação automática cadastradas. Quando o 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).\n\nCada regra é restrita a uma **conta bancária** e a um **tipo de transação** (débito ou crédito). Tem um **tipo de regra**: `1` (contas a pagar/receber) — onde os campos opcionais funcionam como filtros adicionais (plano de contas, tipo documento, tipo pagamento, fornecedor, cliente) — ou `2` (transferência), que requer a **conta bancária de destino** (`IDBankAccountTo`).", "parameters": [ { "name": "IDBankAccount", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por conta bancária." }, { "name": "IDBankStatementConciliationRule", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Retorna apenas a regra com o identificador informado." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Página (5000 itens por página)." } ], "responses": { "200": { "description": "Lista de regras (ou array vazio quando não há resultados).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementConciliationRuleListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "bankStatementConciliationRulePost", "tags": [ "Conciliação Bancária" ], "summary": "Cria uma regra de conciliação automática", "description": "Cadastra uma nova regra para conciliação automática. Conforme `IDTypeRule`:\n\n- **`IDTypeRule=1` (contas a pagar/receber)** — o campo `IDBankAccountTo` é descartado. Os campos `IDTypeAccountPayableReceivable`, `IDTypeDocument`, `IDTypePayment`, `IDSupplier` e `IDConsumer` são opcionais e funcionam como filtros adicionais para o casamento automático.\n- **`IDTypeRule=2` (transferência)** — o campo `IDBankAccountTo` é **obrigatório** e os filtros de título (plano de contas, tipo documento, tipo pagamento, fornecedor, cliente) são descartados.\n\nNão é permitido repetir uma descrição (`Description`) para a mesma conta bancária. A conta bancária de origem (`IDBankAccount`) e a de destino (`IDBankAccountTo`) não podem ser iguais.\n\nA resposta é a representação completa da regra recém-criada, no mesmo formato de `GET /accounts/bank-statement/conciliation-rule`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementConciliationRuleCreate" } } }, "description": "Dados da regra de conciliação. `IDBankAccount` e `IDTypeRule` são obrigatórios. Para `IDTypeRule=1` (contas a pagar/receber), os campos de filtro são opcionais; para `IDTypeRule=2` (transferência), `IDBankAccountTo` passa a ser obrigatório e os filtros são ignorados." }, "responses": { "200": { "description": "Regra criada. Retorna o item completo (mesmo formato do `GET`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementConciliationRuleListItem" }, "maxItems": 1 } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Empresa não existe`\n- `Já existe uma regra com a mesma descrição para essa conta bancária`\n- `Conta bancária obrigatória` / `Conta bancária não existe`\n- `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`\n- `Tipo regra obrigatório` / `Tipo regra não existe`\n- `Tipo pagamento não existe` / `Tipo documento não existe`\n- `Fornecedor não existe` / `Cliente não existe`\n- `Erro ao criar regra`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/bank-statement/conciliation-rule/{idbankstatementconciliationrule}": { "parameters": [ { "name": "idbankstatementconciliationrule", "in": "path", "required": true, "description": "Identificador da regra de conciliação.", "schema": { "type": "integer", "format": "int32" } } ], "put": { "operationId": "bankStatementConciliationRulePut", "tags": [ "Conciliação Bancária" ], "summary": "Atualiza uma regra de conciliação automática", "description": "Atualiza uma regra de conciliação existente. As mesmas regras de criação valem: `IDTypeRule=1` descarta `IDBankAccountTo`; `IDTypeRule=2` exige `IDBankAccountTo` e descarta os filtros de título. Apenas os campos enviados no corpo são considerados; a unicidade da descrição por conta bancária também é validada.\n\nA resposta é a representação completa da regra atualizada, no mesmo formato de `GET /accounts/bank-statement/conciliation-rule`.", "requestBody": { "required": true, "description": "Estrutura idêntica ao corpo de criação. Campos ausentes são tratados como `null` e descartados da atualização.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankStatementConciliationRuleCreate" } } } }, "responses": { "200": { "description": "Regra atualizada (mesmo formato do `GET`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementConciliationRuleListItem" }, "maxItems": 1 } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Regra não existe`\n- `Já existe uma regra com a mesma descrição para essa conta bancária`\n- `Conta bancária obrigatória` / `Conta bancária não existe`\n- `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`\n- `Tipo regra obrigatório` / `Tipo regra não existe`\n- `Tipo pagamento não existe` / `Tipo documento não existe`\n- `Fornecedor não existe` / `Cliente não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "bankStatementConciliationRuleDelete", "tags": [ "Conciliação Bancária" ], "summary": "Exclui uma regra de conciliação automática", "description": "Remove a regra. Falha quando a regra não pertence a uma conta bancária da empresa autenticada.", "responses": { "200": { "description": "Exclusão bem-sucedida. O corpo é a string `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "enum": [ "sucesso" ] } } } }, "400": { "description": "Validação falhou (prefixo `[BadRequest]`). Mensagem: `Regra não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/carrier/modal": { "get": { "operationId": "carrierModalList", "tags": [ "Modalidades de Transporte" ], "summary": "Lista modalidades de transportadora", "description": "Retorna as modalidades de transportadora cadastradas pela empresa, ordenadas por nome. Cada modalidade descreve a forma como uma transportadora opera (Rodoviário, Aéreo, Marítimo, Fluvial, Próprio, Motoboy, Drone, etc.) e fica disponível para seleção no cadastro do fornecedor que opera como transportadora.", "parameters": [ { "name": "IDCarrierModal", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por identificador único da modalidade." } ], "responses": { "200": { "description": "Lista de modalidades da empresa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierModalListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "carrierModalPost", "tags": [ "Modalidades de Transporte" ], "summary": "Cadastra uma modalidade", "description": "Cria uma modalidade de transportadora na empresa autenticada. O nome (`CarrierModal`) precisa ser único dentro da empresa — o sistema bloqueia o cadastro de outra modalidade com o mesmo nome. A resposta é a lista atualizada de modalidades.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierModalCreate" } } }, "description": "Cria uma nova modalidade de transportadora (ex.: `Rodoviário`, `Aéreo`, `Motoboy`). O nome precisa ser único dentro da empresa." }, "responses": { "200": { "description": "Modalidade criada. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierModalListItem" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Já existe uma Modalidade com essa conta`\n- `Empresa não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/carrier/modal/{idcarriermodal}": { "parameters": [ { "name": "idcarriermodal", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da modalidade de transportadora." } ], "put": { "operationId": "carrierModalPut", "tags": [ "Modalidades de Transporte" ], "summary": "Atualiza uma modalidade", "description": "Atualiza o nome da modalidade. Mesma regra de unicidade do `POST` — o novo nome não pode bater com outra modalidade já cadastrada na mesma empresa.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierModalCreate" } } }, "description": "Atualiza o nome da modalidade. Mesma estrutura do `POST` — o nome precisa continuar único na empresa." }, "responses": { "200": { "description": "Modalidade atualizada. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierModalListItem" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Modalidade não existe`\n- `Já existe uma Modalidade com essa conta`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "carrierModalDelete", "tags": [ "Modalidades de Transporte" ], "summary": "Exclui uma modalidade", "description": "**Exclusão física** — a modalidade é apagada do banco. O sistema bloqueia a exclusão em duas situações: (1) **existe alguma transportadora** (fornecedor com `IDCarrierModal` apontando para esta) — é preciso remover/trocar a modalidade no cadastro da transportadora; (2) **existe configuração no de/para de transportadora** em `HubCarrier` apontando para esta.\n\nA resposta em sucesso é a lista atualizada de modalidades.", "responses": { "200": { "description": "Modalidade excluída. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierModalListItem" } } } } }, "400": { "description": "Bloqueios (prefixo `[BadRequest]`):\n- `Modalidade não existe`\n- `Há transportadora com essa modalidade, remover no cadastro da transportadora`\n- `Modalidade esta configurada no de/para de transportadora`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/brand": { "get": { "operationId": "brandList", "tags": [ "Marcas" ], "summary": "Lista marcas", "description": "Retorna as marcas ativas da empresa. Aceita uma busca textual por `Search` que casa contra o id e o nome. Limite máximo de 5000 resultados.", "parameters": [ { "name": "Search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca textual contra identificador `IDBrand` e nome `Name`. Cada espaço vira um curinga `%` interno." } ], "responses": { "200": { "description": "Lista de marcas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrandListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "brandPost", "tags": [ "Marcas" ], "summary": "Cadastra uma marca", "description": "Cria uma marca para a empresa. Os campos `Description`, `Keywords` e `Title` herdam o valor de `Name` quando ausentes ou vazios. `IsActive` assume `1` por padrão, `MenuHome` assume `0`, e `Score` fica nulo.\n\nA resposta é o detalhe da marca recém-criada (mesmo formato do `GET /brand/{idbrand}`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandCreate" } } }, "description": "Dados da marca a cadastrar. Apenas `Name` é obrigatório; `Description`, `Keywords` e `Title` herdam o valor de `Name` quando ausentes ou vazios, `IsActive` assume 1 e `MenuHome` assume 0." }, "responses": { "200": { "description": "Marca criada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" }, "maxItems": 1 } } } }, "400": { "description": "Empresa não localizada. Mensagem: `[BadRequest] - Company não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/brand/{idbrand}": { "parameters": [ { "name": "idbrand", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da marca." } ], "get": { "operationId": "brandGet", "tags": [ "Marcas" ], "summary": "Detalha uma marca", "description": "Retorna o cadastro completo de uma marca.", "responses": { "200": { "description": "Marca encontrada (array com 1 item) ou array vazio quando o id não pertence à empresa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "brandPut", "tags": [ "Marcas" ], "summary": "Atualiza uma marca", "description": "Atualiza a marca de forma parcial — apenas os campos enviados são alterados. A resposta é o detalhe da marca atualizada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandUpdate" } } }, "description": "Campos da marca a atualizar. Todos os campos são opcionais — apenas os enviados são aplicados; os demais permanecem com o valor atual." }, "responses": { "200": { "description": "Marca atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" }, "maxItems": 1 } } } }, "400": { "description": "Marca não encontrada. Mensagem: `[BadRequest] - Brand não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "brandDelete", "tags": [ "Marcas" ], "summary": "Exclui (inativa) uma marca", "description": "Inativa a marca (`Status = 0`). Não exclui fisicamente o registro. A exclusão é bloqueada quando há produtos ativos vinculados à marca.", "responses": { "200": { "description": "Marca inativada. Devolve a string `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "enum": [ "sucesso" ] } } } }, "400": { "description": "Regras impeditivas (prefixo `[BadRequest]`): `marca não existe`, `Marca possui produto ativos. Alterar a marca no cadastro do item antes de excluir a marca`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/movement": { "get": { "summary": "Lista movimentações de estoque", "description": "Substituir o parágrafo de derivação do `TypeMovement` por: \"O campo `TypeMovement` é derivado das vinculações da movimentação: `Transferência endereço` quando há movimentação de origem (`IDOriginIDSkuMovement > 0`); `Ajuste saldo estoque` quando há ajuste de saldo (`IDStockKeepingUnitInventory`); `Inventário` quando há apuração de inventário (`IDStockKeepingUnitInventorySummary`); `Recebimento` quando há recebimento (`IDPurchase`); quando há pedido (`IDOrder`), `Transferência CD` se o tipo do pedido é de transferência entre centros de distribuição (`IsTransfer=1`) ou `Venda` caso contrário; `Produção` quando há produção (`IDStockKeepingUnitProduction`). O campo `IsTransfer` (flag do tipo do pedido) passou a ser retornado. `TypeSkuMovement` é `Saída` para `IDTypeMovement=1` e `Entrada` para `IDTypeMovement=0`.\"", "tags": [ "Movimentação de Estoque" ], "parameters": [ { "name": "Type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Kardex", "kardex", "KardexLocation", "KardexBatch", "SkuInbound", "SkuOutbound", "SkuFiscalConciliation" ] }, "description": "Modo de operacao. Quando ausente, retorna a listagem padrao. Valores aceitos: `Kardex` (ou `kardex`), `KardexLocation`, `KardexBatch`, `SkuInbound`, `SkuOutbound`, `SkuFiscalConciliation`. O shape da resposta muda conforme o `Type`." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Numero da pagina (offset = `Page * 1000` na listagem padrao, `Page * 8000` em `Kardex`/`KardexLocation`/`KardexBatch`, `Page * 1000` em `SkuInbound`/`SkuOutbound`)." }, { "name": "OrderBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "description": "Ordenação do `RecordTimestamp` no Kardex. `ASC` (mais antigos primeiro) ou `DESC` (mais recentes primeiro). Padrão `ASC`." }, { "name": "IDSku", "in": "query", "required": false, "schema": { "type": "string" }, "description": "SKU. Aceita um ou vários códigos separados por vírgula ou espaço (ex.: `33895,398` ou `33895 398`). Obrigatório quando `Type` é `Kardex`, `KardexLocation`, `SkuInbound`, `SkuOutbound` ou `SkuFiscalConciliation`." }, { "name": "IDStockKeepingUnitWarehouse", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Armazém da movimentação. Obrigatório quando `Type=Kardex` (ou `kardex`)." }, { "name": "IDStockKeepingUnitLocation", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Endereço físico. Obrigatório quando `Type=KardexLocation`." }, { "name": "IDCompany", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Conta a filtrar (em multi-empresa). Quando ausente, usa a conta autenticada." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Início do intervalo de data da movimentação (`YYYY-MM-DD`)." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo de data da movimentação (`YYYY-MM-DD`). O sistema acrescenta automaticamente `23:59:59` ao final." }, { "name": "SkuName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome do produto (busca parcial — `LIKE`)." }, { "name": "BarCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código de barras do SKU." }, { "name": "IDBrand", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Marca do produto." }, { "name": "SupplierCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código do SKU usado pelo fornecedor (busca parcial — `LIKE`)." }, { "name": "IDSupplier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Fornecedor (quando origem é recebimento)." }, { "name": "Package", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Embalagem cadastrada no SKU." }, { "name": "IDSkuCompany", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código de referência do SKU (busca parcial — `LIKE`)." }, { "name": "IDSkuHub", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código do SKU no canal de venda (`IDSkuHub`)." }, { "name": "IDSkuMovement", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador específico de uma movimentação." }, { "name": "BalanceChange", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra apenas movimentações que alteram o saldo (`1`) ou que não alteram (`0`)." }, { "name": "IDTypeMovement", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Sentido da movimentação. `0` = entrada, `1` = saída." }, { "name": "IDTypeFulfillmentNonconformity", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 4, 5, 6 ] }, "description": "Tipo de não conformidade no fulfillment." }, { "name": "ConsumerNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome ou razão social do cliente do pedido (busca parcial)." }, { "name": "ConsumerCpfCnpj", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CPF/CNPJ do cliente (busca parcial)." }, { "name": "ConsumerEmail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "E-mail do cliente (busca parcial)." }, { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Número/identificador do pedido (busca exata)." }, { "name": "OrderFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Origem do pedido (`OrderFrom`)." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Pedido específico." }, { "name": "IDConsumer", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Cliente específico." }, { "name": "NfeNumber", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Número da NF-e vinculada." }, { "name": "IDSalesChannel", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Canal de venda (`IDSalesChannel`)." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Integração de venda (`CompanyIntegration`)." }, { "name": "IDStatusOrder", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Status do pedido." }, { "name": "IDStatusInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Status da NF-e." }, { "name": "IDCarrier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Transportadora do pedido." }, { "name": "IDOrderType", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Tipo do pedido." }, { "name": "ShippingState", "in": "query", "required": false, "schema": { "type": "string" }, "description": "UF de entrega do pedido." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Empresa faturadora do pedido." }, { "name": "InvoiceDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Início do intervalo da data de emissão da NF-e." }, { "name": "InvoiceDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo da data de emissão da NF-e (acrescenta `23:59:59`)." }, { "name": "ShippingDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Início do intervalo da data de envio." }, { "name": "ShippingDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo da data de envio." }, { "name": "ValueOrderFrom", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Valor mínimo do pedido." }, { "name": "ValueOrderTo", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Valor máximo do pedido." }, { "name": "OrderDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Início do intervalo da data de criação do pedido." }, { "name": "OrderDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo da data de criação do pedido (acrescenta `23:59:59`)." }, { "name": "IncludeValueDashboard", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra por tipo de pedido marcado como `Incluir valor dashboard`." }, { "name": "BatchComments", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Descrição/Comentários do lote (busca exata)." }, { "name": "SinceDateLastRecordModification", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Retorna apenas movimentações com `DateLastRecordModification >=` a data informada (`YYYY-MM-DD HH:MM:SS`). Útil para sincronização incremental." }, { "name": "IDBatch", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Lote (`IDBatch`). Obrigatorio quando `Type=KardexBatch`. Nos demais modos, quando informado, restringe a movimentacao ao lote." } ], "responses": { "200": { "description": "Lista de movimentações conforme o `Type` requisitado.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SkuMovementListItem" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SkuMovementKardexItem" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SkuMovementKardexLocationItem" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SkuMovementInboundItem" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SkuMovementOutboundItem" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SkuMovementFiscalConciliationItem" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SkuMovementKardexBatchItem" } } ] } } } }, "400": { "description": "Falha de validação. Possíveis mensagens:\n- `[BadRequest] - Precisa informar o armazem e sku` — `Type=Kardex` sem `IDSku`/`IDStockKeepingUnitWarehouse`.\n- `[BadRequest] - Precisa informar o endereço e sku` — `Type=KardexLocation` sem `IDSku`/`IDStockKeepingUnitLocation`.\n- `[BadRequest] - Precisa informar o lote` — `Type=KardexBatch` sem `IDBatch`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } }, "operationId": "skuMovementList" } }, "/sku/movement/transfer": { "post": { "summary": "Transfere quantidade entre armazéns/endereços", "description": "Move quantidade de um SKU entre dois armazéns ou dois endereços/lotes, gerando **duas movimentações vinculadas** (saída na origem, entrada no destino). O custo unitário usado em ambas é o custo médio do armazém de origem — ou o valor de `CostSet` quando a parametrização `UseCostFromCostSet` está ativa.\n\nOrigem e destino precisam estar no **mesmo Centro de Distribuição** (`IDStockKeepingUnitDistributionCenter`). O SKU precisa ser do tipo Produto/Variação, Matéria-prima ou Insumo.\n\n**Modos de transferência:**\n- **Entre armazéns** — envie `IDStockKeepingUnitWarehouseFrom` + `IDStockKeepingUnitWarehouseTo`. O sistema consome lotes na ordem FIFO (mais antigo primeiro) até completar `Quantity`. Para SKU sem rastreabilidade (`Batch = 0`) usa o lote padrão.\n- **Entre lotes/endereços** — envie `IDBatchFrom` + (`IDBatchTo` **ou** `IDStockKeepingUnitLocationTo`). Quando vier só `IDStockKeepingUnitLocationTo`, o sistema procura um lote compatível no destino (mesma validade/fabricação/comentário) e o reutiliza; se não existir, cria um novo lote. Com a parametrização `KeepUniqueBatchForFiscalConciliation` ativa, **sempre cria um novo lote no destino**.\n\n**Validações:**\n- Se a quantidade total do lote origem for menor que `Quantity`, devolve `[BadRequest] - Quantidade total insuficiente para transferencia`. Pode ser contornado com `IgnoreBalance=1` (query) ou ativando `AllowNegativeBalanceTransfer`.\n- Em transferência entre endereços com SKU rastreável (`Batch = 1`), se o endereço destino já tem o mesmo SKU em lote divergente (validade/fabricação/comentário diferentes) e a parametrização `AllowSameItemDifferentBatchSameLocation` está inativa, devolve `[BadRequest] - Item possui lotes divergentes no endereço de destino`.\n\n**Efeitos colaterais:**\n- Atualiza `StockKeepingUnitBalance` (saldo agregado) do SKU no armazém de destino.\n- Reprocessa pedidos no armazém de destino com status \"Falta produto\" (e equivalentes — `IDStatusOrder IN (11, 12, 24)`), limpando `QuantityNonconformity` à medida que a quantidade transferida cobre as faltas, e devolvendo o pedido a `IDStatusOrder = 1` (Fechado) quando todos os itens voltam a ter saldo. Cada alteração gera evento de pedido (`IDEvent = 35`).\n- Publica a notificação `SkuBalanceTransfer` para o webhook da empresa.\n\n**Resposta:** por padrão devolve as duas movimentações criadas (`SkuMovementTransferResponseItem`). Quando `BatchResponse=1` é enviado na query, devolve a lista completa de lotes ativos do SKU (`SkuMovementTransferBatchResponseItem`) — útil para o frontend recarregar o painel de saldos sem nova chamada.", "tags": [ "Movimentação de Estoque" ], "parameters": [ { "name": "BatchResponse", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, a resposta troca de array de movimentações para a lista completa de lotes ativos do SKU. Padrão `0`." }, { "name": "IgnoreBalance", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, ignora a validação de saldo na transferência por lote (mesma semântica de `AllowNegativeBalanceTransfer`, mas pontual). Vale apenas no fluxo `IDBatchFrom + (IDBatchTo | IDStockKeepingUnitLocationTo)`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuMovementTransferBody" } } }, "description": "Transferência de estoque de um SKU entre dois depósitos. Informe `IDSku`, `Quantity`, `IDStockKeepingUnitWarehouseFrom` (origem), `IDStockKeepingUnitWarehouseTo` (destino) e — quando o SKU é controlado por lote — `IDBatchFrom` e `IDBatchTo`. `IDStockKeepingUnitLocationTo` direciona o endereço de destino." }, "responses": { "200": { "description": "Transferência criada com sucesso. Quando `BatchResponse=1`, retorna a lista de lotes ativos do SKU; caso contrário, retorna as duas movimentações criadas.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SkuMovementTransferResponseItem" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SkuMovementTransferBatchResponseItem" } } ] } } } }, "400": { "description": "Falha de validação. Possíveis mensagens:\n- `[BadRequest] - Quantidade precisa ser maior que zero` — `Quantity` ausente ou zero.\n- `[BadRequest] - SKU não existe` — `IDSku` inválido ou não pertence à conta.\n- `[BadRequest] - Item não é do tipo SKU, materia prima ou insumo` — `IDTypeSku` fora de `(3, 6, 7)`.\n- `[BadRequest] - Lote origem não existe` — `IDBatchFrom` inválido.\n- `[BadRequest] - Lote destino não existe` — `IDBatchTo` inválido.\n- `[BadRequest] - Endereço destino não existe` — `IDStockKeepingUnitLocationTo` inválido.\n- `[BadRequest] - Armazém origem não existe` / `[BadRequest] - Armazém destino não existe` — armazém inválido ou de outra empresa.\n- `[BadRequest] - Centro de distribuição de origem diferente do destino` — armazéns/endereços em CDs diferentes.\n- `[BadRequest] - Item possui lotes divergentes no endereço de destino e não pode ser transferido` — bloqueio quando `AllowSameItemDifferentBatchSameLocation` está inativo.\n- `[BadRequest] - Quantidade total insuficiente para transferencia: Origem: X Transferência: Y` — saldo insuficiente (libere com `AllowNegativeBalanceTransfer` ou `IgnoreBalance=1`).\n- `[BadRequest] - Quantidade insuficiente para transferência` — não há lote disponível para consumir no armazém de origem.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } }, "operationId": "skuMovementTransferPost" } }, "/sku/{idsku}/cost/recalculate": { "post": { "summary": "Recalcula o custo médio do SKU (assíncrono)", "description": "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 — a API devolve imediatamente e o reprocessamento roda em segundo plano. Use quando o custo médio na tela de Saldo / Lotes ficar inconsistente com o que o Kardex calcularia (importação de movimentações antigas, correção retroativa do custo de um recebimento, estorno de compra etc.).\n\nAtenção: a operação é **irreversível** e pode demorar minutos em SKUs com muito histórico.", "tags": [ "Recálculo de Custo" ], "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "SKU a ter o custo recalculado." } ], "responses": { "200": { "description": "Recálculo aceito e despachado para processamento em segundo plano.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuCostRecalculateAcceptedResponse" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } }, "operationId": "skuCostRecalculatePost" } }, "/supplier": { "get": { "operationId": "supplierList", "tags": [ "Cadastro de Fornecedores" ], "summary": "Lista fornecedores e transportadoras", "description": "Retorna o catálogo de fornecedores (e transportadoras — compartilham o mesmo cadastro) da empresa autenticada. Apenas cadastros ativos (`SupplierStatus=1`) entram na resposta. Aceita filtros por categoria, tipo de fornecedor, CPF/CNPJ, sinal de leilão de frete e nome; aceita ainda uma busca textual genérica (`Search`) que cruza nome, e-mail, CPF/CNPJ e id.\n\nQuando o usuário tem categorias de fornecedor vinculadas em **Configurações → Usuários** **e** a parametrização **Permitir visualizar registros apenas fornecedores vinculados ao usuário** está ativada, o resultado é automaticamente restrito a essas categorias. Paginação por `Page` com 2000 itens por página.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Página (2000 itens por página)." }, { "name": "Search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca textual genérica. O texto é separado em letras (nome/e-mail) e dígitos (CPF/CNPJ/id) e cruzado contra `SupplierNameCorporateName`, `SupplierEmail`, `SupplierCpfCnpj` e `IDSupplier`." }, { "name": "SupplierNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome ou razão social (LIKE)." }, { "name": "SupplierCpfCnpj", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo CPF ou CNPJ (LIKE, somente dígitos)." }, { "name": "IDSupplierCategory", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por uma ou mais categorias de fornecedor. Lista separada por vírgula." }, { "name": "IDTypeSupplier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo tipo de fornecedor (vinculado à categoria)." }, { "name": "CarrierAuction", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra transportadoras que participam (1) ou não (0) do leilão de frete." } ], "responses": { "200": { "description": "Lista de fornecedores ativos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "supplierPost", "tags": [ "Cadastro de Fornecedores" ], "summary": "Cadastra um fornecedor", "description": "Cria um novo fornecedor (ou transportadora — depende da categoria informada). Quando `SupplierCpfCnpj` é informado, o sistema tenta consultar `publica.cnpj.ws/cnpj/` com timeout de 5 s. Se a consulta retornar com sucesso (típico para CNPJ válido), os campos de endereço, telefone, e-mail, razão social, nome fantasia, inscrição estadual e data de início de atividade são **sobrescritos** com os dados da Receita — qualquer valor enviado no corpo para esses campos é ignorado. Em caso de falha (CPF, CNPJ inexistente, timeout, indisponibilidade do serviço externo), o sistema cai de volta para os valores do corpo.\n\nQuando a parametrização **Bloquear cadastro duplicado de fornecedor** (`BlockDuplicateSupplier`, grupo *Fornecedor*) está ativada, o sistema bloqueia o cadastro se já existir outro fornecedor ativo com o mesmo CPF/CNPJ.\n\nA resposta é o detalhe completo do fornecedor recém-criado (mesmo formato de `GET /supplier/{idsupplier}`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreate" } } }, "description": "Cadastro de um novo fornecedor (produto, transportadora, serviço, etc.). Quando `SupplierCpfCnpj` é informado e a parametrização **Não Permitir Cadastros Duplicados Para Fornecedor** está ativa, o sistema rejeita CPF/CNPJ já cadastrado e ativo na empresa. Para CNPJ, os campos de identificação (`SupplierNameCorporateName`, `SupplierTradeName`, `SupplierStateInscription`), contato (`SupplierTelephone`, `SupplierEmail`), endereço (`ShippingStreet`, `ShippingNumber`, `ShippingComplement`, `ShippingNeighborhood`, `ShippingCity`, `ShippingState`, `ShippingPostalCode`) e `SupplierBirthDate` são sobrescritos com os dados retornados pela Receita (consulta a `publica.cnpj.ws`); se a consulta falhar, valem os valores enviados no corpo." }, "responses": { "200": { "description": "Fornecedor criado. Retorna o cadastro completo.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Já existe um fornecedor com esse CPF/CNPJ` (quando `BlockDuplicateSupplier=1`)\n- `Categoria fornecedor não existe`\n- `Empresa não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/supplier/{idsupplier}": { "parameters": [ { "name": "idsupplier", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do fornecedor (ou transportadora — compartilham o mesmo cadastro)." } ], "get": { "operationId": "supplierGet", "tags": [ "Cadastro de Fornecedores" ], "summary": "Detalha um fornecedor ou transportadora", "description": "Retorna o cadastro completo de um fornecedor. O mesmo cadastro também é usado para transportadoras — os campos com prefixo `Carrier*` ficam preenchidos apenas quando o fornecedor opera como transportadora.\n\nA resposta inclui descrições resolvidas dos relacionamentos (categoria, tipo de fornecedor, integração, banco, estado civil, plano de contas), uma lista de contatos, faixas de SRO dos Correios (transportadoras), uploads de tabela de frete (transportadoras), centros de custo padrão para os títulos gerados e um campo textual com o status do último upload de tabela de frete.\n\nNão retorna erro quando o id não existe ou não pertence à empresa — a resposta é `200 []`.", "responses": { "200": { "description": "Fornecedor encontrado (array com 1 item) ou array vazio quando o id não pertence à empresa autenticada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierDetail" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "supplierPut", "tags": [ "Cadastro de Fornecedores" ], "summary": "Atualiza um fornecedor", "description": "Atualiza parcialmente o cadastro do fornecedor — apenas os campos enviados no corpo são alterados. As validações disparam quando os campos correspondentes vêm preenchidos:\n\n- Se `SupplierCpfCnpj` mudar **e** a parametrização **Bloquear cadastro duplicado de fornecedor** estiver ativa, o sistema bloqueia o salvamento quando já existe outro fornecedor ativo com o mesmo documento.\n- Se `IDSupplierCategory` for informado, a categoria precisa pertencer à empresa autenticada.\n- Se `IDTypeAccountPayableReceivable` for informado, o plano de contas precisa existir na empresa.\n- Se `IDCompanyLabel` mudar, o template de etiqueta precisa pertencer à empresa autenticada ou à empresa-padrão de etiquetas (id 54) e ser do tipo etiqueta de transportadora.\n- Se `CarrierAuction=1` e o fornecedor ainda não tinha `CarrierQuotationExternalId`, o sistema atribui um id sequencial dentro da empresa.\n\nSempre que o cadastro muda para/de transportadora, a lista de transportadoras de leilão de frete é regravado.\n\nA resposta é o detalhe completo do fornecedor atualizado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierUpdate" } } }, "description": "Atualização parcial: envie apenas os campos que precisa alterar — o sistema só atualiza chaves presentes no corpo. Quando `SupplierCpfCnpj` muda e a parametrização **Não Permitir Cadastros Duplicados Para Fornecedor** está ativa, valida duplicidade contra outros fornecedores ativos da empresa. Quando `CarrierAuction` passa para 1 e o fornecedor ainda não tem `CarrierQuotationExternalId`, o sistema atribui automaticamente o próximo identificador sequencial e, ao mudar o tipo do fornecedor para/de transportadora, atualiza a lista de transportadoras de leilão da empresa. `IDTypeAccountPayableReceivable` e `IDCompanyLabel` são validados contra os respectivos cadastros da empresa." }, "responses": { "200": { "description": "Fornecedor atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Fornecedor não existe`\n- `Categoria fornecedor não existe`\n- `Já existe um fornecedor com esse CPF/CNPJ`\n- `Plano de contas não existe`\n- `Etiqueta não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "supplierDelete", "tags": [ "Cadastro de Fornecedores" ], "summary": "Exclui (inativa) um fornecedor", "description": "Marca o fornecedor como inativo e limpa os vínculos com integração (`IDCompanyIntegration`) e leilão de frete (`CarrierAuction`). Não há exclusão física do registro: o `SupplierStatus` passa para **0** quando o fornecedor nunca teve título a pagar/receber, ou para **2** quando já existe pelo menos um título vinculado — isso preserva o histórico financeiro mas remove o fornecedor das listas ativas.\n\nA resposta é a lista atualizada de fornecedores (mesmo formato de `GET /supplier`).", "responses": { "200": { "description": "Fornecedor inativado. Retorna a lista de fornecedores ativos atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierListItem" } } } } }, "400": { "description": "Fornecedor não localizado. Mensagem: `[BadRequest] - Supplier não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/supplier/{idsupplier}/contact": { "parameters": [ { "name": "idsupplier", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do fornecedor." } ], "post": { "operationId": "supplierContactPost", "tags": [ "Cadastro de Fornecedores" ], "summary": "Adiciona um contato ao fornecedor", "description": "Cria um contato (pessoa física) vinculado ao fornecedor. A resposta é o detalhe completo do fornecedor atualizado, com a nova entrada já visível em `Contacts[]`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierContactCreate" } } }, "description": "Dados do contato a ser adicionado ao fornecedor." }, "responses": { "200": { "description": "Contato criado. Retorna o detalhe atualizado do fornecedor.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierDetail" }, "maxItems": 1 } } } }, "400": { "description": "Fornecedor não localizado. Mensagem: `[BadRequest] - Fornecedor não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/supplier/{idsupplier}/contact/{idsupplierscontact}": { "parameters": [ { "name": "idsupplier", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do fornecedor." }, { "name": "idsupplierscontact", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do contato." } ], "put": { "operationId": "supplierContactPut", "tags": [ "Cadastro de Fornecedores" ], "summary": "Atualiza um contato do fornecedor", "description": "Atualiza parcialmente um contato — apenas os campos enviados no corpo são alterados. A resposta é o detalhe completo do fornecedor atualizado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierContactUpdate" } } }, "description": "Atualização parcial dos campos do contato: somente as chaves presentes no corpo são alteradas." }, "responses": { "200": { "description": "Contato atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierDetail" }, "maxItems": 1 } } } }, "400": { "description": "Fornecedor ou contato não encontrados. Mensagem: `[BadRequest] - Fornecedor não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "supplierContactDelete", "tags": [ "Cadastro de Fornecedores" ], "summary": "Remove um contato do fornecedor", "description": "Apaga fisicamente o contato. A resposta é o detalhe completo do fornecedor atualizado, já sem o contato removido.", "responses": { "200": { "description": "Contato removido. Retorna o detalhe atualizado do fornecedor.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierDetail" }, "maxItems": 1 } } } }, "400": { "description": "Fornecedor não localizado. Mensagem: `[BadRequest] - Fornecedor não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/supplier/{idsupplier}/cost-center": { "parameters": [ { "name": "idsupplier", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do fornecedor." } ], "post": { "operationId": "supplierCostCenterPost", "tags": [ "Cadastro de Fornecedores" ], "summary": "Define o rateio padrão de centros de custo do fornecedor", "description": "Substitui (apaga e regrava) o rateio padrão de centros de custo aplicado nos títulos gerados a partir deste fornecedor. O corpo é um **array** de pares `IDTypeCostCenter` + `ValueRatio`, onde a soma de `ValueRatio` precisa fechar em **1** (100%). Quando o array é vazio (`[]`), o rateio padrão é removido. Todos os centros de custo precisam existir na empresa.\n\nO comportamento é atômico: o sistema valida primeiro a soma e os centros, depois apaga o rateio anterior e insere o novo de uma vez. A resposta é a string `\"sucesso\"` quando o array é vazio, ou o detalhe completo do fornecedor atualizado quando há centros a gravar.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierCostCenterRatio" } } } }, "description": "Array com o rateio completo de centros de custo do fornecedor. Cada item tem `IDTypeCostCenter` (centro de custo da empresa) e `ValueRatio` (proporção decimal entre 0 e 1). A soma de `ValueRatio` precisa fechar em 1 (100%). O sistema **substitui** o rateio existente: apaga todos os vínculos atuais e insere os enviados. Enviar array vazio remove todo o rateio." }, "responses": { "200": { "description": "Rateio aplicado. Retorna o detalhe atualizado do fornecedor, ou a string `\"sucesso\"` quando o rateio foi removido (array vazio).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SupplierDetail" } }, { "type": "string", "enum": [ "sucesso" ] } ] } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Fornecedor não existe`\n- `Rateio precisa somar 100%`\n- `Precisa enviar ao menos um centro de custo`\n- `Centro de custo(s) não localizado(s): `", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/supplier/{idsupplier}/logo": { "parameters": [ { "name": "idsupplier", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do fornecedor." } ], "post": { "operationId": "supplierLogoPost", "tags": [ "Cadastro de Fornecedores" ], "summary": "Sobe ou troca o logotipo do fornecedor", "description": "Aceita duas formas de envio do logotipo:\n\n- **Upload multipart** (`multipart/form-data` com campo `file`) — sobe o arquivo direto do cliente.\n- **URL externa** (`application/json` com `{ \"Url\": \"...\" }`) — o sistema baixa a imagem da URL informada e grava no S3.\n\nNos dois casos a imagem é salva no bucket público do idworks (`https://public.idworks.com.br/Image/Suppliers/...`) com um nome único, e o campo `SupplierLogoUrl` do fornecedor é atualizada. A resposta é um corpo vazio com status HTTP — `200` em sucesso, `404` se o fornecedor não existe, `400` se a URL informada não retorna a imagem.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Arquivo de imagem (PNG/JPG)." } } } }, "application/json": { "schema": { "type": "object", "required": [ "Url" ], "properties": { "Url": { "type": "string", "format": "uri", "description": "URL pública de onde o sistema deve baixar a imagem." } } } } }, "description": "Envio do logotipo do fornecedor. Aceita duas formas: (1) `multipart/form-data` com o campo `file` contendo o arquivo de imagem; ou (2) JSON com `{ \"Url\": \"...\" }` para que o sistema baixe a imagem da URL informada. O arquivo é armazenado em `https://public.idworks.com.br/Image/Suppliers/` e o `SupplierLogoUrl` do fornecedor é atualizado." }, "responses": { "200": { "description": "Logotipo aplicado (corpo vazio).", "content": {} }, "400": { "description": "Falha ao baixar imagem da URL informada. Mensagem: `[BadRequest] - erro ao baixar imagem`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "404": { "description": "Fornecedor não encontrado (corpo vazio)." }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/supplier/category": { "get": { "operationId": "supplierCategoryList", "tags": [ "Categorias de Fornecedor" ], "summary": "Lista categorias de fornecedor", "description": "Retorna as categorias ativas da empresa, ordenadas pela descrição. Cada item já vem com o tipo de fornecedor resolvido (`TypeSupplier`). Aceita filtro opcional por `IDSupplierCategory` para retornar uma única categoria. Quando a empresa autenticada é a `all` (multi-conta), retorna as categorias de todas as empresas vinculadas.", "parameters": [ { "name": "IDSupplierCategory", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "description": "Filtra por identificador de categoria. Quando omitido, devolve todas as categorias ativas da empresa." } ], "responses": { "200": { "description": "Lista de categorias.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierCategoryListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "supplierCategoryPost", "tags": [ "Categorias de Fornecedor" ], "summary": "Cadastra uma categoria de fornecedor", "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCategoryCreate" } } }, "description": "Dados da categoria a ser cadastrada. `CategoryDescription` é o nome exibido na lista de categorias; `IDTypeSupplier` define o tipo (Produto, Transportadora, Serviço, etc.)." }, "responses": { "200": { "description": "Categoria criada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierCategoryListItem" }, "maxItems": 1 } } } }, "400": { "description": "Empresa não localizada. Mensagem: `[BadRequest] - Empresa não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/supplier/category/{idsuppliercategory}": { "parameters": [ { "name": "idsuppliercategory", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da categoria de fornecedor." } ], "put": { "operationId": "supplierCategoryPut", "tags": [ "Categorias de Fornecedor" ], "summary": "Atualiza uma categoria de fornecedor", "description": "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. A resposta repete o formato da listagem.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCategoryUpdate" } } }, "description": "Novos valores da categoria. Os dois campos são gravados via `UPDATE` direto, então envie-os mesmo quando só um precisa mudar." }, "responses": { "200": { "description": "Categoria atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierCategoryListItem" }, "maxItems": 1 } } } }, "400": { "description": "Categoria não encontrada para a empresa. Mensagem: `[BadRequest] - Categoria fornecedor não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "supplierCategoryDelete", "tags": [ "Categorias de Fornecedor" ], "summary": "Exclui (inativa) uma categoria de fornecedor", "description": "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.", "responses": { "200": { "description": "Categoria inativada. Devolve a lista atualizada das categorias ativas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierCategoryListItem" } } } } }, "400": { "description": "Categoria não encontrada ou possui fornecedores ativos. Mensagens: `[BadRequest] - Categoria fornecedor não existe`; `[BadRequest] - Existem fornecedores nessa categoria, alterar a categoria dentro do cadastro do fornecedor antes de excluir`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/cash-flow": { "get": { "operationId": "cashFlowList", "tags": [ "Fluxo de Caixa" ], "summary": "Lista o fluxo de caixa", "description": "Retorna o fluxo de caixa da empresa em dois modos, controlados pelo parâmetro `Type`:\n\n- **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`. Considera o ano inteiro definido em `Year` (ou o ano corrente quando omitido) e ignora contas com status **Não lançado**.\n- **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**).\n\nValores são assinados pelo tipo de lançamento: contas a pagar (`IDTypeAccount=1`) entram negativas; contas a receber (`IDTypeAccount=0`) entram positivas.", "parameters": [ { "name": "Year", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Ano de referência (default: ano corrente). O resumo cobre de 01/jan a 31/dez deste ano." }, { "name": "GroupBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "month", "day" ], "default": "month" }, "description": "Granularidade do agrupamento no modo Resumo: `month` consolida por mês, `day` consolida por dia. Ignorado no modo Detalhe." }, { "name": "Type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Detail" ] }, "description": "Quando `Detail`, lista os títulos individuais (modo de detalhamento, usado pelo drill-through). Omitido: modo Resumo." }, { "name": "Date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "**Modo Detalhe**. Primeiro dia do mês a detalhar (`YYYY-MM-DD`); o sistema deriva o último dia do mesmo mês como limite superior." }, { "name": "DateType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "DateDue", "DatePayment" ] }, "description": "**Modo Detalhe**. Define a coluna do `Date`: `DateDue` filtra pelo vencimento (lançamentos previstos do mês); `DatePayment` filtra pela data do pagamento lançado (lançamentos realizados do mês)." }, { "name": "IDTypeAccountPayableReceivable", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "**Modo Detalhe**. Restringe ao plano de contas selecionado." }, { "name": "IDBankAccountForecast", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela conta bancária prevista do lançamento." }, { "name": "IDBankAccount", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por lançamentos que tenham pelo menos um pagamento (entrada do extrato) na conta bancária informada." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela empresa faturadora (filial) do lançamento." } ], "responses": { "200": { "description": "Fluxo de caixa retornado. O formato depende de `Type`: array de itens consolidados (modo Resumo) ou array de títulos individuais (modo Detalhe). Quando não há registros no Resumo, retorna `[]`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CashFlowSummaryItem" } }, { "type": "array", "items": { "$ref": "#/components/schemas/CashFlowDetailItem" } } ] } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/payable": { "get": { "operationId": "accountsPayableList", "tags": [ "Contas a Pagar" ], "summary": "Lista contas a pagar", "description": "Retorna as contas a pagar da empresa, com totais já calculados — valor total `ValueTotal`, valor pago `ValuePaid`, saldo devedor `ValuePaymentPending`. Aceita filtros por data (vencimento, documento, competência, último pagamento, registro), valor, status, fornecedor, cliente, tipo de documento, tipo de pagamento, plano de contas, centro de custo, conta bancária, pedido associado e mais. Paginação por `Page` (5000 itens por página).\n\nQuando 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.\n\nUse `IDTypeEntity=1` para trazer apenas títulos com cliente e `IDTypeEntity=2` para apenas títulos com fornecedor.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Página (cada página tem 5000 itens)." }, { "name": "IDAccountPayableReceivable", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por um ou mais ids (lista separada por vírgula). Útil para retornar lotes recém-criados." }, { "name": "IDStatusAccountPayableReceivable", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6 ] }, "default": [ 0, 1, 2, 3, 5 ] }, "description": "Filtro de status (lista 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` (não traz Pago, Não lançado nem Vence hoje).", "style": "form", "explode": false }, { "name": "IDSupplier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por fornecedor." }, { "name": "IDConsumer", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por cliente." }, { "name": "IDTypeEntity", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2 ] }, "description": "Restringe ao tipo: `1` apenas com cliente, `2` apenas com fornecedor." }, { "name": "DocumentNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo número do documento." }, { "name": "IDTypeAccountPayableReceivable", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por plano de contas." }, { "name": "IDTypePayment", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por tipo de pagamento." }, { "name": "IDTypeDocument", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por tipo de documento." }, { "name": "Scheduled", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Apenas títulos agendados (`1`) ou não (`0`)." }, { "name": "Forecast", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Apenas previsões (`1`) ou apenas reais (`0`)." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por pedido associado." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por empresa faturadora." }, { "name": "IDBankAccountForecast", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela conta bancária prevista para pagamento." }, { "name": "IDBankAccount", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela conta bancária do pagamento já lançado." }, { "name": "ValueFrom", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Valor mínimo." }, { "name": "ValueTo", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Valor máximo." }, { "name": "DateDueFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Vencimento a partir de." }, { "name": "DateDueTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Vencimento até." }, { "name": "DateDocumentFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data do documento a partir de." }, { "name": "DateDocumentTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data do documento até." }, { "name": "DateCompetenceFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Competência a partir de." }, { "name": "DateCompetenceTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Competência até." }, { "name": "DateLastPaymentFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Último pagamento a partir de." }, { "name": "DateLastPaymentTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Último pagamento até (inclusivo até 23:59)." }, { "name": "DateRecordTimestampFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de criação do registro a partir de." }, { "name": "DateRecordTimestampTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de criação do registro até (inclusivo até 23:59)." }, { "name": "IDTypeCostCenter", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por centro de custo. Traz apenas os títulos vinculados ao centro de custo informado." } ], "responses": { "200": { "description": "Lista de contas a pagar com totais calculados (vazia quando o usuário não tem acesso pela parametrização de governança).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsPayableListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "accountsPayablePost", "tags": [ "Contas a Pagar" ], "summary": "Cria contas a pagar (com suporte a recorrência e retenção de impostos)", "description": "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.\n\n**Regras de negócio**:\n- `IDConsumer` e `IDSupplier` não podem ser enviados juntos.\n- Quando `IDBankAccountForecast` é omitido e a empresa tem **exatamente uma** conta bancária cadastrada, ela é usada automaticamente.\n- Para recorrência mensal, `PeriodTypeValue` deve estar entre 1 e 31 (dia do mês).\n- Para recorrência semanal, `PeriodTypeValue` deve estar entre 0 e 6 (dia da semana).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsPayableCreate" } } }, "description": "Dados do título a pagar. `DateDue`, `Value`, `IDTypeDocument` e `IDTypeAccountPayableReceivable` são obrigatórios. Para criar uma **série recorrente**, envie `PeriodType`, `QuantityRepeat` e `PeriodTypeValue` — o sistema gera as próximas ocorrências ajustando feriados/finais de semana conforme `Holiday`." }, "responses": { "200": { "description": "Conta(s) criada(s). Retorna a lista das contas recém-criadas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsPayableListItem" } } } } }, "400": { "description": "Validação falhou (prefixo `[BadRequest]`). Possíveis mensagens:\n- `Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)`\n- `Fornecedor não existe` / `Cliente não existe`\n- `Faturador não existe` / `Empresa não existe`\n- `Type Payment não existe` / `Tipo documento não existe` / `Plano de contas não existe`\n- `Pedido não existe` / `Conta bancária não existe`\n- `Fornecedor retenção é obrigatório` / `Valor retenção é obrigatório` / `Data vencimento retenção é obrigatória`\n- `Valor retenção superior ao valor do título`\n- `Fornecedores(s) retenção imposto não localizado(s): ...`\n- `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`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/payable/{idaccountpayable}": { "parameters": [ { "name": "idaccountpayable", "in": "path", "required": true, "description": "Identificador da conta a pagar.", "schema": { "type": "integer", "format": "int32" } } ], "get": { "operationId": "accountsPayableGet", "tags": [ "Contas a Pagar" ], "summary": "Detalha uma conta a pagar", "description": "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.\n\nAtenção: quando o id não existe ou a conta pertence a outra empresa, a resposta é `200` com `[]` (array vazio) — este endpoint não retorna erro para \"não encontrado\".", "responses": { "200": { "description": "Conta encontrada (objeto único em array) ou array vazio quando não encontrada.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AccountsPayableDetail" }, "minItems": 1, "maxItems": 1 }, { "type": "array", "maxItems": 0 } ] } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "accountsPayablePut", "tags": [ "Contas a Pagar" ], "summary": "Atualiza uma conta a pagar", "description": "Atualiza a conta a pagar de forma parcial — apenas os campos enviados são alterados (o `PUT` se comporta como `PATCH`). Quando `ChangeNextRepeat=1`, a alteração é propagada para todas as ocorrências futuras da mesma série de recorrência.\n\nA diferença campo a campo é registrada no histórico de alterações. A resposta é a representação completa da conta atualizada, no mesmo formato de `GET /accounts/payable/{idaccountpayable}`.", "parameters": [ { "name": "ChangeNextRepeat", "in": "query", "required": false, "description": "Quando `1`, propaga a atualização para as próximas ocorrências da mesma recorrência (com `DateDue` posterior).", "schema": { "type": "integer", "enum": [ 1 ] } } ], "requestBody": { "required": true, "description": "Todos os campos são opcionais; só os enviados são atualizados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsPayableUpdate" } } } }, "responses": { "200": { "description": "Conta atualizada. Retorna o mesmo formato do `GET /accounts/payable/{idaccountpayable}`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsPayableDetail" } } } } }, "400": { "description": "Validação falhou (prefixo `[BadRequest]`). Mensagens possíveis:\n- `Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)`\n- `Contas a pagar não existe`\n- `Fornecedor não existe` / `Cliente não existe` / `Faturador não existe`\n- `Tipo pagamento não existe` (×2 — também acionado quando `TypeDocument` não é encontrado)\n- `Conta bancária não existe`\n- `Plano de contas não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "accountsPayableDelete", "tags": [ "Contas a Pagar" ], "summary": "Exclui uma conta a pagar", "description": "Remove a conta a pagar e desvincula as GNREs associadas.\n\n**Regras**:\n- Não é possível excluir quando a conta está agendada.\n- Não é possível excluir quando já existem pagamentos lançados.\n- 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.\n- Quando `ChangeNextRepeat=1`, também remove as ocorrências futuras da mesma série de recorrência.\n- 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\"`.", "parameters": [ { "name": "ChangeNextRepeat", "in": "query", "required": false, "description": "Quando `1`, também exclui as próximas ocorrências da mesma recorrência.", "schema": { "type": "integer", "enum": [ 1 ] } } ], "responses": { "200": { "description": "Exclusão bem-sucedida. O corpo varia: `\"sucesso\"` quando não há pedido nem ordem de serviço associada; objeto representando o pedido/ordem de serviço atualizada quando houver.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "string", "enum": [ "sucesso" ] }, { "type": "object", "description": "Representação do pedido ou da ordem de serviço — schema não documentado neste piloto." } ] } } } }, "400": { "description": "Regras impeditivas (prefixo `[BadRequest]`):\n- `Pagamento não existe`\n- `Título esta agendado e não pode ser excluído`\n- `Não é possível excluir um contas a pagar atrelado a um recebimento`\n- `Contas a pagar já tem pagamento`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/payable/file": { "post": { "operationId": "accountsPayableFileDownload", "tags": [ "Contas a Pagar" ], "summary": "Gera ZIP com arquivos de contas a pagar e envia por e-mail", "description": "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**.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "type": "integer" }, "description": "Array direto de IDs." }, { "type": "object", "required": [ "IDAccountPayableReceivable" ], "properties": { "IDAccountPayableReceivable": { "type": "array", "items": { "type": "integer" }, "description": "Lista de ids de contas a pagar." } } } ] } } }, "description": "Lista de identificadores de contas a pagar cujos arquivos serão compactados. Aceita um array direto de inteiros ou um objeto com a chave `IDAccountPayableReceivable` contendo o array." }, "responses": { "200": { "description": "URL assinada do ZIP gerado no S3 (válida por 48 horas). O arquivo também é enviado para o e-mail do usuário.", "content": { "application/json": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `IDs inválidos`\n- `Nenhum arquivo encontrado`\n- `Usuário não encontrado`\n- `Empresa inválida`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/payable/{idaccountpayable}/payment": { "parameters": [ { "name": "idaccountpayable", "in": "path", "required": true, "description": "Identificador da conta a pagar.", "schema": { "type": "integer", "format": "int32" } } ], "post": { "operationId": "accountsPayablePaymentPost", "tags": [ "Contas a Pagar" ], "summary": "Lança um pagamento na conta a pagar", "description": "Registra um pagamento na conta a pagar, atualizando 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.", "parameters": [ { "name": "FinishIfPossible", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1 ] }, "description": "Quando `1`, tenta finalizar o pedido vinculado se todos os seus títulos estiverem pagos após este lançamento." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsPayablePaymentCreate" } } }, "description": "Dados do pagamento a lançar. `IDBankAccount` e `DateTransactionTimestamp` são obrigatórios. Quando `Value` é omitido, o sistema assume o saldo devedor total (`ValueTotal - ValuePaid`)." }, "responses": { "200": { "description": "Pagamento lançado. Retorna a conta a pagar atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsPayableDetail" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Conta a receber/pagar não existe`\n- `Conta bancária não existe`\n- `Caixinha esta aberto e não pode ter pagamentos efetuados`\n- `Valor a conciliar divergente de valor do título e não há outro lançamento relacionado`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/payable/{idaccountpayable}/payment/{idaccountpayment}": { "parameters": [ { "name": "idaccountpayable", "in": "path", "required": true, "description": "Identificador da conta a pagar.", "schema": { "type": "integer", "format": "int32" } }, { "name": "idaccountpayment", "in": "path", "required": true, "description": "Identificador do lançamento de pagamento (`IDBankStatement`).", "schema": { "type": "integer", "format": "int32" } } ], "delete": { "operationId": "accountsPayablePaymentDelete", "tags": [ "Contas a Pagar" ], "summary": "Cancela um pagamento lançado", "description": "Remove o lançamento de pagamento e reverte o status da conta a pagar. Quando o pagamento está 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 da conta.", "parameters": [ { "name": "IDBankStatementConciliation", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Quando informado, garante que o pagamento só seja excluído se pertencer a esta conciliação. Pagamentos vinculados a outra conciliação são bloqueados." } ], "responses": { "200": { "description": "Pagamento cancelado. Retorna a conta a pagar atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsPayableDetail" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Pagamento não existe`\n- `Pagamento foi realizado em um caixa e não pode ser excluído`\n- `Caixinha esta aberto e não pode ter pagamentos efetuados`\n- `Não é possível excluir um pagamento vinculado a outra conciliação bancária`\n- `Problema ao deletar pagamento`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/payable/{idaccountpayable}/cost-center": { "parameters": [ { "name": "idaccountpayable", "in": "path", "required": true, "description": "Identificador da conta a pagar.", "schema": { "type": "integer", "format": "int32" } } ], "post": { "operationId": "accountsPayableReceivableCostCenterPost", "tags": [ "Contas a Pagar" ], "summary": "Define o rateio de centros de custo", "description": "Substitui completamente o rateio de centros de custo da conta a pagar. Enviar array vazio remove todos os centros. A soma de `ValueRatio` de todos os itens deve ser exatamente `1` (100%).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsPayableCostCenterSetItem" }, "description": "Lista de centros de custo com suas proporções. Array vazio limpa todos os centros." } } }, "description": "Array com os centros de custo e suas proporções (`ValueRatio`). A soma dos `ValueRatio` precisa ser exatamente `1` (100%). Array vazio remove todos os centros de custo da conta." }, "responses": { "200": { "description": "Rateio atualizado. Retorna a conta a pagar atualizada ou `\"sucesso\"` quando o array foi vazio.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AccountsPayableDetail" } }, { "type": "string", "enum": [ "sucesso" ] } ] } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Conta a receber/pagar não existe`\n- `Rateio precisa somar 100%`\n- `Centro de custo(s) não localizado(s): {ids}`\n- `Precisa enviar ao menos um centro de custo`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/payable/{idaccountpayable}/bank-integration": { "parameters": [ { "name": "idaccountpayable", "in": "path", "required": true, "description": "Identificador da conta a pagar.", "schema": { "type": "integer", "format": "int32" } } ], "post": { "operationId": "accountsPayableBankPaymentPost", "tags": [ "Contas a Pagar" ], "summary": "Envia a conta a pagar para pagamento bancário integrado", "description": "Processa o pagamento via integração bancária. Após o envio, retorna a conta atualizada, salvo quando `NoInvoke=1`.", "parameters": [ { "name": "NoInvoke", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1 ] }, "description": "Quando `1`, não consulta `accountsPayableGet` após o envio e devolve apenas `\"Sucesso\"`." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Corpo não utilizado; pode ser omitido." } } }, "description": "Corpo não utilizado; pode ser omitido. O envio é sempre referente ao título identificado no path." }, "responses": { "200": { "description": "Envio bem-sucedido. Retorna a conta a pagar atualizada ou `\"Sucesso\"` quando `NoInvoke=1`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AccountsPayableDetail" } }, { "type": "string", "enum": [ "Sucesso" ] } ] } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Título precisa ser enviado`\n- Mensagens de erro retornadas pelo processo bancário.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/payable/{idaccountpayable}/file": { "parameters": [ { "name": "idaccountpayable", "in": "path", "required": true, "description": "Identificador da conta a pagar.", "schema": { "type": "integer", "format": "int32" } } ], "post": { "operationId": "accountsFilePost", "tags": [ "Contas a Pagar" ], "summary": "Anexa um arquivo à conta a pagar", "description": "Faz upload de um arquivo via `multipart/form-data` (campo `file`) e o vincula à conta a pagar. O tipo do arquivo é definido pelo parâmetro `IDTypeFile`. Ao anexar um boleto, o sistema tenta ler automaticamente o código de barras ou o PIX copia-e-cola do arquivo; quando a conta ainda não tem `BankSlipBarCode` preenchido, o valor lido é gravado. Retorna o detalhe atualizado da conta a pagar.", "parameters": [ { "name": "IDTypeFile", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "description": "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." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Arquivo a ser anexado." } } } } }, "description": "Upload `multipart/form-data` com o campo `file` contendo o binário do arquivo. O tipo é controlado pelo parâmetro de query `IDTypeFile`." }, "responses": { "200": { "description": "Arquivo anexado. Retorna a conta a pagar atualizada com o novo arquivo listado em `Files`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsPayableDetail" } } } } }, "404": { "description": "Conta a pagar não encontrada para a empresa. Corpo vazio." } } } }, "/accounts/payable/{idaccountpayable}/file/{idfile}": { "parameters": [ { "name": "idaccountpayable", "in": "path", "required": true, "description": "Identificador da conta a pagar.", "schema": { "type": "integer", "format": "int32" } }, { "name": "idfile", "in": "path", "required": true, "description": "Identificador do arquivo.", "schema": { "type": "integer", "format": "int32" } } ], "get": { "operationId": "accountsFileGet", "tags": [ "Contas a Pagar" ], "summary": "Baixa um arquivo anexado à conta a pagar", "description": "Serve o arquivo diretamente do S3. A implementação não foi localizada localmente — comportamento inferido a partir das URLs geradas em `accountsPayableGet`. Aceita `View=1` e `token` como query params conforme o link gerado.\n\n⚠️ *Sistema não confirmado em código.*", "parameters": [ { "name": "View", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1 ] }, "description": "Quando `1`, serve o arquivo para visualização no browser." }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Token de autenticação (alternativa ao header `Authorization` para uso em links diretos)." }, { "name": "File", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Parâmetro de roteamento interno gerado pelo sistema." } ], "responses": { "200": { "description": "Conteúdo binário do arquivo." } } }, "delete": { "operationId": "accountsFileDelete", "tags": [ "Contas a Pagar" ], "summary": "Remove um arquivo anexado à conta a pagar", "description": "Exclui o arquivo do banco e retorna a conta a pagar atualizada.", "responses": { "200": { "description": "Arquivo removido. Retorna a conta a pagar atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsPayableDetail" } } } } }, "400": { "description": "Arquivo não encontrado para esta conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/receivable": { "get": { "operationId": "accountsReceivableList", "tags": [ "Contas a Receber" ], "summary": "Lista contas a receber", "description": "Retorna as contas a receber da empresa, com totais calculados — valor total `ValueTotal`, valor pago `ValuePaid`, saldo pendente `ValuePaymentPending`. Cada item traz também dados resolvidos do pedido associado, da nota fiscal de origem (quando há) e da integração. Aceita filtros por data, valor, status, cliente, fornecedor, plano de contas, tipo de documento, tipo de pagamento, conta bancária, pedido, adquirente (`TID`/`NSU`) e mais. Paginação por `Page` (4000 itens por página).\n\nQuando 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.\n\nUse `IDTypeEntity=1` para trazer apenas títulos com cliente (cobrança) e `IDTypeEntity=2` para apenas títulos com fornecedor (devolução ou estorno).", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Página (cada página tem 4000 itens)." }, { "name": "IDAccountPayableReceivable", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por um ou mais ids da conta a receber (lista separada por vírgula)." }, { "name": "IDStatusAccountPayableReceivable", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6 ] }, "default": [ 0, 1, 2, 3, 5 ] }, "description": "Filtro de status (lista 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` (omite Pago, Não lançado e Vence hoje).", "style": "form", "explode": false }, { "name": "IDConsumer", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por cliente." }, { "name": "IDSupplier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por fornecedor (caso de devolução/estorno em contas a receber)." }, { "name": "ConsumerNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome ou razão social do cliente (ou do fornecedor, quando o título é de fornecedor)." }, { "name": "IDTypeEntity", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2 ] }, "description": "Restringe ao tipo: `1` apenas com cliente, `2` apenas com fornecedor." }, { "name": "DocumentNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo número do documento." }, { "name": "NfeNumber", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo número da nota fiscal de origem." }, { "name": "IDTypeAccountPayableReceivable", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por plano de contas." }, { "name": "IDTypePayment", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por tipo de pagamento." }, { "name": "IDTypeDocument", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por tipo de documento." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador interno do pedido associado." }, { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo número externo do pedido (ex.: `OT-1234`, `ML-5678`)." }, { "name": "OrderFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por pedido de origem (lista de canais de venda associados ao pedido)." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela empresa faturadora." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela integração originadora do título (marketplace, adquirente, ERP)." }, { "name": "IDBankAccountForecast", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela conta bancária prevista para recebimento." }, { "name": "IDBankAccount", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela conta bancária onde o pagamento já foi lançado." }, { "name": "TID", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo TID (identificador da transação do adquirente)." }, { "name": "NSU", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo NSU (identificador sequencial único do adquirente)." }, { "name": "TIDorNSU", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Procura o mesmo valor em `TID` **ou** `NSU` (cláusula `OR`). Use quando o usuário não sabe a origem do identificador." }, { "name": "NSUorTID", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Alias adicional ao filtro `TIDorNSU` — combinado a ele, expande o `OR` para um segundo par de valores." }, { "name": "ValueFrom", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Valor total mínimo (`Value + ValuePenalty + ValueInterest - ValueDiscount`)." }, { "name": "ValueTo", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Valor total máximo." }, { "name": "DateDueFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Vencimento a partir de." }, { "name": "DateDueTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Vencimento até." }, { "name": "DateDocumentFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data do documento a partir de." }, { "name": "DateDocumentTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data do documento até." }, { "name": "DateCompetenceFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Competência a partir de." }, { "name": "DateCompetenceTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Competência até." }, { "name": "DateLastPaymentFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data do último pagamento a partir de." }, { "name": "DateLastPaymentTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data do último pagamento até (inclusivo até 23:59)." }, { "name": "DateRecordTimestampFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de cadastro do registro a partir de." }, { "name": "DateRecordTimestampTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de cadastro do registro até (inclusivo até 23:59)." }, { "name": "InvoiceDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de emissão da nota fiscal de origem a partir de." }, { "name": "InvoiceDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de emissão da nota fiscal de origem até (inclusivo até 23:59:59)." } ], "responses": { "200": { "description": "Lista de contas a receber com totais calculados (vazia quando o usuário não tem acesso pela parametrização de governança ou não há matches).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsReceivableListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "accountsReceivablePost", "tags": [ "Contas a Receber" ], "summary": "Cria uma conta a receber", "description": "Cria uma nova conta a receber. A resposta é a representação completa da conta recém-criada, no mesmo formato de `GET /accounts/receivable/{idaccountreceivable}` (objeto único dentro de array).\n\n**Regras de negócio**:\n- `IDConsumer` e `IDSupplier` não podem ser enviados juntos — apenas um dos dois.\n- Quando `IDCompanyInvoice` é omitido, assume a empresa autenticada.\n- Strings vazias são tratadas como nulas — equivalentes a omitir o campo.\n- Cria sempre como conta de **entrada** (`IDTypeAccount=0`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsReceivableCreate" } } }, "description": "Dados do título a receber. `DateDue`, `Value`, `IDTypeDocument` e `IDTypeAccountPayableReceivable` são obrigatórios. `IDTypePayment` é opcional — quando informado é validado contra a tabela de tipos de pagamento. `IDConsumer` e `IDSupplier` são mutuamente exclusivos." }, "responses": { "200": { "description": "Conta criada. Retorna a representação completa da conta no formato detalhado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsReceivableDetail" }, "minItems": 1, "maxItems": 1 } } } }, "400": { "description": "Validação falhou (prefixo `[BadRequest]`). Possíveis mensagens:\n- `Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)`\n- `Empresa não existe`\n- `Cliente não existe` / `Fornecedor não existe`\n- `Faturador não existe`\n- `Type Payment não existe`\n- `Tipo documento não existe` / `Plano de contas não existe`\n- `IDBankAccountForecast não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/receivable/conciliation": { "get": { "operationId": "accountsReceivableConciliationList", "tags": [ "Contas a Receber" ], "summary": "Lista conciliações de adquirentes (auditoria de taxas)", "description": "Retorna as conciliações de adquirentes recebidas. Há dois modos de operação:\n\n- **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.\n- **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/OK, 2=azul/com prejuízo, 3=amarelo/sem configuração, 4=laranja/taxa configurada não aplicada, 5=vermelho/diferença grande). Use `IDAuditStatus` para filtrar apenas conciliações com determinado resultado de auditoria.\n\nPaginação por `Page` (5000 itens por página).", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Página (cada página tem 5000 itens)." }, { "name": "AuditRate", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, ativa o modo de auditoria de taxas — a resposta usa `AccountsReceivableConciliationAuditItem`." }, { "name": "IDAuditStatus", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por resultado de auditoria (apenas quando `AuditRate=1`). Lista separada por vírgula. Valores: 1=verde, 2=azul, 3=amarelo, 4=laranja, 5=vermelho." }, { "name": "IDAccountsPayableReceivableConciliation", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por identificador único da conciliação." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela integração adquirente." }, { "name": "IDTypePaymentFrom", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo tipo de pagamento do adquirente (`TypeAcquirerPayment`)." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo pedido vinculado a alguma conta a receber conciliada (não aplicável quando `AuditRate=1`)." }, { "name": "TID", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo TID da conciliação." }, { "name": "NSU", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo NSU da conciliação." }, { "name": "ExternalIDOrderReference", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela referência externa do pedido enviada pelo adquirente." }, { "name": "Status", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo status retornado pelo adquirente (`IDTypeAcquirerStatus`). Ex.: 1=Pagamento, 3=Devolução, 4=Chargeback." }, { "name": "ConciliationStatus", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "description": "Status de conciliação interno: 1=Não conciliado, 2=Conciliação automática, 3=Conciliação manual, 4=Conciliação parcial (não aplicável quando `AuditRate=1`)." }, { "name": "ReceivableIDBank", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo banco em que o adquirente liberou o valor." }, { "name": "IDTypeAcquirerReleaseType", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo tipo de liberação do adquirente." }, { "name": "SaleDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data da venda a partir de." }, { "name": "SaleDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data da venda até. Default `4000-01-01` (sem limite superior)." }, { "name": "ReceivedDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de recebimento a partir de." }, { "name": "ReceivedDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de recebimento até. Default `4000-01-01` (sem limite superior)." }, { "name": "RecordTimestampFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de cadastro do registro a partir de." }, { "name": "RecordTimestampTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de cadastro do registro até (inclusivo até 23:59:59)." } ], "responses": { "200": { "description": "Lista de conciliações. O schema do item depende de `AuditRate`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AccountsReceivableConciliationListItem" }, "description": "Resposta default (`AuditRate=0`)." }, { "type": "array", "items": { "$ref": "#/components/schemas/AccountsReceivableConciliationAuditItem" }, "description": "Resposta com auditoria de taxas (`AuditRate=1`)." } ] } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/receivable/conciliation/{idaccountspayablereceivableconciliation}": { "parameters": [ { "name": "idaccountspayablereceivableconciliation", "in": "path", "required": true, "description": "Identificador da conciliação de adquirente.", "schema": { "type": "integer", "format": "int32" } } ], "put": { "operationId": "accountsReceivableConciliationPut", "tags": [ "Contas a Receber" ], "summary": "Atualiza observações de uma conciliação", "description": "Atualiza apenas o campo `Comments` da conciliação. Demais campos da conciliação não podem ser alterados por esta rota. A resposta é a conciliação atualizada no mesmo formato da listagem default.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsReceivableConciliationUpdate" } } }, "description": "Apenas `Comments` é alterável; demais campos da conciliação são ignorados." }, "responses": { "200": { "description": "Conciliação atualizada. Retorna a conciliação no mesmo formato de `GET /accounts/receivable/conciliation`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsReceivableConciliationListItem" } } } } }, "400": { "description": "Conciliação não existe. Mensagem: `[BadRequest] - Conciliação não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/receivable/marketplace-conciliation": { "get": { "operationId": "accountsReceivableMarketplaceConciliationList", "tags": [ "Contas a Receber" ], "summary": "Lista conciliações de marketplace", "description": "Retorna as conciliações de marketplace, ou seja, os valores liberados por integrações de marketplace para cada pedido — já decompostos em comissão (`MarketplaceFeeValue`), antecipação (`MarketplaceFinancingFeeValue`), frete (`MarketplaceShippingFeeValue`), cupom (`MarketplaceCouponValue`), impostos (`MarketplaceTaxesValue`) e outras taxas (`MarketplaceOtherFeeValue`).\n\nCada item agrupa as contas a receber internas vinculadas (`InternalAccounts`) e soma os valores líquidos em `ERPValueTotal`, permitindo bater o que entrou no banco com o que o marketplace declara.\n\nPaginação por `Page` (5000 itens por página).", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Página (cada página tem 5000 itens)." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela integração de marketplace." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo pedido interno vinculado (via `HubOrder`)." }, { "name": "OrderID", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo identificador externo do pedido no marketplace." }, { "name": "TID", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo TID da conciliação." }, { "name": "IDTypeAcquirerStatus", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo status do marketplace (`IDTypeAcquirerStatus`)." }, { "name": "IDTypeStatusConciliation", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "description": "Status de conciliação: `1` Não conciliado, `2` Conciliado automaticamente, `3` Conciliado manualmente, `4` Conciliado parcialmente." }, { "name": "Installment", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo número da parcela." }, { "name": "InstallmentTotal", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo total de parcelas." }, { "name": "SaleDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data da venda a partir de." }, { "name": "SaleDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data da venda até. Default `4000-01-01`." }, { "name": "ReceivedDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de recebimento a partir de." }, { "name": "ReceivedDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de recebimento até. Default `4000-01-01`." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Página dos resultados (cada página tem 5000 itens)." } ], "responses": { "200": { "description": "Lista de conciliações de marketplace agrupadas, cada uma com suas contas internas vinculadas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsReceivableMarketplaceConciliationItem" } } } } } } } }, "/accounts/receivable/{idaccountreceivable}": { "parameters": [ { "name": "idaccountreceivable", "in": "path", "required": true, "description": "Identificador da conta a receber.", "schema": { "type": "integer", "format": "int32" } } ], "get": { "operationId": "accountsReceivableGet", "tags": [ "Contas a Receber" ], "summary": "Detalha uma conta a receber", "description": "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.).\n\nAtenção: quando o id não existe ou a conta pertence a outra empresa, a resposta é `200` com `[]` (array vazio) — este endpoint não retorna erro para \"não encontrado\".", "responses": { "200": { "description": "Conta encontrada (objeto único em array) ou array vazio quando não encontrada.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AccountsReceivableDetail" }, "minItems": 1, "maxItems": 1 }, { "type": "array", "maxItems": 0 } ] } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "accountsReceivablePut", "tags": [ "Contas a Receber" ], "summary": "Atualiza uma conta a receber", "description": "Atualiza a conta a receber de forma parcial — apenas os campos enviados são alterados (o `PUT` se comporta como `PATCH`). A diferença campo a campo é registrada no histórico de alterações da conta.\n\nQuando o título tem um boleto ou link de pagamento (`ConsumerBankSlip`) associado:\n- Se o boleto está pago, **a alteração de valor ou vencimento é bloqueada**.\n- Se o boleto está aberto ou cancelado, a alteração é propagada para o gateway de pagamento.\n\nQuando `IDSupplier` é enviado, `IDConsumer` é zerado (e vice-versa) — não é possível ter os dois ao mesmo tempo. A resposta é a representação completa da conta atualizada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsReceivableUpdate" } } }, "description": "Campos do título a atualizar (atualização parcial — só os enviados são aplicados). Quando o título tem boleto/link de pagamento associado, alterações de `Value` ou `DateDue` podem ser bloqueadas (boleto já pago) ou propagadas ao gateway (boleto em aberto)." }, "responses": { "200": { "description": "Conta atualizada. Retorna o mesmo formato de `GET /accounts/receivable/{idaccountreceivable}`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsReceivableDetail" } } } } }, "400": { "description": "Validação falhou (prefixo `[BadRequest]`). Possíveis mensagens:\n- `Conta a receber não existe`\n- `Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)`\n- `Cliente não existe` / `Fornecedor não existe`\n- `Faturador não existe`\n- `Pagamento não existe` / `Banco não existe`\n- `Tipo documento não existe` / `Plano de contas não existe`\n- `Integração não existe`\n- `Boleto / link pagamento já esta pago e não pode ser alterado`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "accountsReceivableDelete", "tags": [ "Contas a Receber" ], "summary": "Exclui uma conta a receber", "description": "Exclui a conta a receber. Bloqueado quando: (a) o título está agendado para pagamento automático (`Scheduled=1`); (b) já existe pelo menos um pagamento lançado; (c) o título está vinculado a um recebimento de mercadoria (`IDPurchase`) e a parametrização **Não permitir excluir contas pagar com recebimento** está ativa.\n\nA exclusão também limpa o vínculo de eventuais GNREs (`IDAccountsPayable`). Quando o título foi originado de pedido ou ordem de serviço, registra um evento no histórico do pedido/OS.", "parameters": [ { "name": "ChangeNextRepeat", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1 ] }, "description": "Quando `1`, exclui também as próximas ocorrências da mesma série de recorrência (vinculadas pelo `IDAccountPayableReceivableMain`, com `DateDue` posterior à do título atual)." } ], "responses": { "200": { "description": "Conta excluída. Retorna a string `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "enum": [ "sucesso" ] } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Pagamento não existe`\n- `Título esta agendado e não pode ser excluído`\n- `Não é possível excluir um contas a pagar atrelado a um recebimento`\n- `Contas a pagar já tem pagamento`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/receivable/{idaccountreceivable}/cost-center": { "parameters": [ { "name": "idaccountreceivable", "in": "path", "required": true, "description": "Identificador da conta a receber.", "schema": { "type": "integer", "format": "int32" } } ], "post": { "operationId": "accountsReceivableCostCenterPost", "tags": [ "Contas a Receber" ], "summary": "Define o rateio de centros de custo", "description": "Substitui completamente o rateio de centros de custo da conta a receber. Enviar array vazio remove todos os centros. A soma de `ValueRatio` de todos os itens deve ser exatamente `1` (100%). Os centros enviados precisam estar ativos e pertencer à empresa da conta.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsPayableCostCenterSetItem" }, "description": "Lista de centros de custo com suas proporções. Array vazio limpa todos os centros." } } }, "description": "Array com os centros de custo e suas proporções (`ValueRatio`). A soma dos `ValueRatio` precisa ser exatamente `1` (100%). Array vazio remove todos os centros de custo da conta." }, "responses": { "200": { "description": "Rateio atualizado. Retorna a conta a receber atualizada ou `\"sucesso\"` quando o array foi vazio.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AccountsReceivableDetail" } }, { "type": "string", "enum": [ "sucesso" ] } ] } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Conta a receber/pagar não existe`\n- `Rateio precisa somar 100%`\n- `Centro de custo(s) não localizado(s): {ids}`\n- `Precisa enviar ao menos um centro de custo`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/receivable/{idaccountreceivable}/payment": { "parameters": [ { "name": "idaccountreceivable", "in": "path", "required": true, "description": "Identificador da conta a receber.", "schema": { "type": "integer", "format": "int32" } } ], "post": { "operationId": "accountsReceivablePaymentPost", "tags": [ "Contas a Receber" ], "summary": "Lança um pagamento na conta a receber", "description": "Registra um pagamento na conta a receber, atualizando o status conforme o saldo pendente. Regras:\n\n- Quando a conta tinha **previsão** (`Forecast=1`), a flag é zerada após o lançamento.\n- Quando a conta não tinha banco previsto (`IDBankAccountForecast`), assume o banco do pagamento como previsão.\n- 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.\n- Quando `IDAccountsPayableReceivableConciliationMarketplace` é informado, gera automaticamente as contas filhas para comissão, antecipação, frete, cupom e impostos do marketplace conforme parametrização da integração.\n- Pagamentos em conta de **caixinha** (`BankNumber=000`) só são aceitos com a caixinha fechada.\n- Quando `FinishIfPossible=1` e há pedido vinculado, tenta finalizar o pedido se todos os títulos estiverem pagos após este lançamento.", "parameters": [ { "name": "FinishIfPossible", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1 ] }, "description": "Quando `1`, tenta finalizar o pedido vinculado se todos os seus títulos estiverem pagos após este lançamento." }, { "name": "query", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1 ] }, "description": "Quando `1`, retorna apenas a string `\"sucesso\"` (não invoca a recuperação completa da conta). Usado em fluxos em massa para evitar latência." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsReceivablePaymentCreate" } } }, "description": "Dados do recebimento a lançar. `IDBankAccount` e `DateTransactionTimestamp` são obrigatórios. Quando `IDAccountsPayableReceivableConciliation` é informado e o valor difere do título, o sistema procura outro lançamento relacionado para redistribuir a diferença e gera o lançamento automático da taxa do adquirente. Quando `IDAccountsPayableReceivableConciliationMarketplace` é informado, gera as contas filhas (comissão, antecipação, frete, cupom, impostos) conforme a parametrização da integração." }, "responses": { "200": { "description": "Pagamento lançado. Retorna a conta a receber atualizada (ou a string `\"sucesso\"` quando `query=1`).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AccountsReceivableDetail" } }, { "type": "string", "enum": [ "sucesso" ] } ] } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Conta a receber/pagar não existe`\n- `Conta bancária não existe`\n- `Caixinha esta aberto e não pode ter pagamentos efetuados`\n- `Valor a conciliar divergente de valor do título e não há outro lançamento relacionado`\n- `Conciliação marketplace inexistente`\n- `Erro ao criar lançamento de taxa adquirente`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/accounts/receivable/{idaccountreceivable}/payment/{idaccountpayment}": { "parameters": [ { "name": "idaccountreceivable", "in": "path", "required": true, "description": "Identificador da conta a receber.", "schema": { "type": "integer", "format": "int32" } }, { "name": "idaccountpayment", "in": "path", "required": true, "description": "Identificador do lançamento de pagamento (`IDBankStatement`).", "schema": { "type": "integer", "format": "int32" } } ], "delete": { "operationId": "accountsReceivablePaymentDelete", "tags": [ "Contas a Receber" ], "summary": "Cancela um pagamento lançado", "description": "Remove o lançamento de pagamento e reverte o status da conta a receber. Regras:\n\n- Pagamentos lançados em **caixa** (`IDStoreFrontCashier` preenchido) não podem ser excluídos por esta rota.\n- Pagamentos em conta de **caixinha** (`BankNumber=000`) só podem ser excluídos com a caixinha fechada.\n- Quando o pagamento está vinculado a uma **conciliação bancária** (`BankStatementConciliationReference`), desvincula e recalcula o status da conciliação para parcial ou não conciliado conforme o resto das referências.\n- Quando o pagamento está vinculado a uma **conciliação adquirente** ou **marketplace** (`AccountsPayableReceivableConciliationMatch` / `AccountsPayableReceivableConciliationMarketplaceReference`), desvincula e reabre a conciliação correspondente.\n- A exclusão é registrada no histórico da conta.", "parameters": [ { "name": "IDBankStatementConciliation", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Quando informado, garante que o pagamento só seja excluído se pertencer a esta conciliação bancária. Pagamentos vinculados a outra conciliação são bloqueados." } ], "responses": { "200": { "description": "Pagamento cancelado. Retorna a conta a receber atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountsReceivableDetail" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Pagamento não existe`\n- `Pagamento foi realizado em um caixa e não pode ser excluído`\n- `Caixinha esta aberto e não pode ter pagamentos efetuados`\n- `Não é possível excluir um pagamento vinculado a outra conciliação bancária`\n- `Erro ao atualizar conciliação bancária`\n- `Erro ao verificar vínculos de conciliação`\n- `Problema ao deletar pagamento`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/type": { "get": { "operationId": "typeAccountTypeList", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Lista o plano de contas", "description": "Retorna os planos de contas **ativos** (`Status=1`) da empresa em dois formatos, controlados por `Type`:\n\n- **Árvore** (`Type=Tree`): cada item raiz traz seus descendentes recursivamente em `Children[]`, ordenado por descrição. Quando o item tem `ExternalCode`, a descrição é prefixada (`-`). Inclui categoria do plano (`IDTypeCategoryAccountPayble` / `TypeCategoryAccountPaybleDescription`) já propagada do pai para os filhos.\n- **Lista plana** (default, sem `Type`): array com todos os planos no escopo (raiz e filhos), cada item traz o caminho hierárquico completo em `CategoryTree` (texto separado por ` -> `, do nível mais alto até a folha) e a mesma categoria já propagada.\n\nAceita filtros opcionais por tipo (`IDTypeAccount`), categoria (`IDTypeCategoryAccountPayble`) e identificador (`IDTypeAccountPayble`) — este último só é considerado no modo Árvore.", "parameters": [ { "name": "Type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Tree" ] }, "description": "Quando `Tree`, devolve estrutura aninhada com `Children[]`. Sem o parâmetro, devolve lista plana com `CategoryTree`." }, { "name": "IDTypeAccount", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra pelo tipo do lançamento: `0` entrada (a receber), `1` saída (a pagar)." }, { "name": "IDTypeCategoryAccountPayble", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela categoria do plano (ver `GET /type/account/type/category`)." }, { "name": "IDTypeAccountPayble", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "(Apenas no modo Árvore) Restringe ao plano com o id informado. Ignorado na lista plana." } ], "responses": { "200": { "description": "Plano de contas retornado. O formato depende de `Type`. Quando a lista plana não tem resultados, retorna `[]`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TypeAccountTreeNode" }, "description": "Modo Árvore." }, { "type": "array", "items": { "$ref": "#/components/schemas/TypeAccountFlatItem" }, "description": "Modo Lista plana (default)." } ] } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "typeAccountTypePost", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Cadastra um plano de contas", "description": "Cria um plano de contas. Quando `IDTypeAccountPaybleFather` é informado, o plano nasce como **filho** do pai indicado e a categoria informada (`IDTypeCategoryAccountPayble`) é descartada — a categoria do filho é sempre a do pai. Quando o pai é omitido, a categoria informada é gravada (opcional).\n\nMarcar **`DefaultOrder=1`** ou **`DefaultPurchase=1`** transforma este plano no padrão da empresa — qualquer outro plano marcado é automaticamente desmarcado. Se `ExternalCode` ou `InternalCode` forem informados, precisam ser únicos entre os planos ativos da empresa.\n\nA resposta retorna o plano recém-criado no formato controlado pelo query `Type` (mesmo do `GET`).", "parameters": [ { "name": "Type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Tree" ], "default": "Tree" }, "description": "Formato do plano retornado na resposta. Default `Tree`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeAccountCreate" } } }, "description": "Dados do plano de contas a cadastrar. `TypeAccountPaybleDescription` obrigatório. Quando `IDTypeAccountPaybleFather` é informado, o plano nasce como filho do pai indicado e a `IDTypeCategoryAccountPayble` enviada é descartada (filho herda do pai). `ExternalCode` e `InternalCode`, quando informados, precisam ser únicos entre os planos ativos da empresa. Marcar `DefaultOrder=1` ou `DefaultPurchase=1` desmarca automaticamente o anterior." }, "responses": { "200": { "description": "Plano criado. Retorna o item recém-criado no formato indicado por `Type`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TypeAccountTreeNode" } }, { "type": "array", "items": { "$ref": "#/components/schemas/TypeAccountFlatItem" } } ] } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Empresa não existe`\n- `Plano de contas superior não existe`\n- `Já existe um plano com o mesmo cód. referência externo`\n- `Já existe um plano com o mesmo cód. referência interno`\n- `IDTypeCategoryAccountPayble não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/type/{idtypeaccount}": { "parameters": [ { "name": "idtypeaccount", "in": "path", "required": true, "description": "Identificador do plano de contas (`IDTypeAccountPayble`).", "schema": { "type": "integer", "format": "int32" } } ], "put": { "operationId": "typeAccountTypePut", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Atualiza um plano de contas", "description": "Atualiza o plano de contas com o id informado. As mesmas regras do POST valem: pai descarta categoria, `ExternalCode`/`InternalCode` precisam ser únicos entre os planos ativos da empresa, e marcar `DefaultOrder=1` ou `DefaultPurchase=1` desmarca o anterior.\n\n**Diferença importante em relação ao POST**: quando o cliente envia `DefaultOrder=0` (ou omite) e **não existe outro plano** marcado como padrão de pedido na empresa (excluindo este), a operação **falha** — sempre é preciso ter exatamente um padrão de pedido. A mesma regra vale para `DefaultPurchase=0`.\n\nA resposta retorna toda a lista atual do plano de contas no formato Árvore (chama internamente o `GET`).", "parameters": [ { "name": "Type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Tree" ], "default": "Tree" }, "description": "Formato da lista retornada na resposta. Default `Tree`." } ], "requestBody": { "required": true, "description": "Mesmos campos do POST.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeAccountCreate" } } } }, "responses": { "200": { "description": "Plano atualizado. Retorna a lista completa do plano de contas (mesmo formato do `GET`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeAccountTreeNode" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Plano de contas não existe`\n- `Plano de contas superior não existe`\n- `Já existe um plano com o mesmo cód. referência externo`\n- `Já existe um plano com o mesmo cód. referência interno`\n- `IDTypeCategoryAccountPayble não existe`\n- `É preciso ter um plano de contas padrão para pedido`\n- `É preciso ter um plano de contas padrão para compras`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "typeAccountTypeDelete", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Inativa um plano de contas", "description": "Inativa o plano de contas (soft delete — define `Status=0` e zera `IDTypeAccountPaybleFather`).\n\n**Bloqueios**:\n- O plano não pode ter filhos ativos — é preciso remover os filhos primeiro.\n- O plano não pode estar referenciado em alguma parametrização da empresa do tipo **GNRE** (`GnreIDTypeAccountPayableReceivable`) — a parametrização precisa ser removida antes.\n\nA resposta retorna a lista atual do plano de contas (chama internamente o `GET` no formato lista plana).", "responses": { "200": { "description": "Exclusão bem-sucedida. Retorna a lista atual do plano de contas (formato lista plana, sem `Type`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeAccountFlatItem" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Plano de contas a receber/pagar não existe`\n- `Plano de contas esta na parametrização da empresa. Remover a parametrização antes de excluir o documento`\n- `Remover o plano de conta filho antes de excluir o pai`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/type/category": { "get": { "operationId": "typeAccountCategoryList", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Lista as categorias do plano de contas", "description": "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. Cada plano de contas raiz pode ser classificado em uma categoria; planos filhos herdam a categoria do pai.\n\nO identificador é devolvido como **string** para preservar zeros à esquerda em integrações.", "responses": { "200": { "description": "Lista de categorias, ordenada pela descrição.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeAccountCategoryListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/document": { "get": { "operationId": "typeAccountDocumentList", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Lista tipos de documento", "description": "Retorna os tipos de documento ativos da empresa, ordenados pela descrição. Quando a empresa autenticada é a `all` (multi-conta), retorna os tipos de todas as empresas vinculadas.", "responses": { "200": { "description": "Lista de tipos de documento.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeDocumentListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "typeAccountDocumentPost", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Cadastra um tipo de documento", "description": "Cria um tipo de documento para a empresa autenticada. Após gravar, o a listagem para `/type/account/document` é invalidado. A resposta é a lista completa atualizada (formato de `GET /type/account/document`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeDocumentCreate" } } }, "description": "Dados do tipo de documento a cadastrar. `TypeDocument` é a descrição (ex.: `Nota Fiscal`, `Boleto`). `DefaultOrder` e `DefaultPurchase` marcam o tipo como padrão de pedido de venda e de compra, respectivamente." }, "responses": { "200": { "description": "Tipo de documento criado. Devolve a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeDocumentListItem" } } } } }, "400": { "description": "Empresa não localizada. Mensagem: `[BadRequest] - Empresa não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/document/{idtypedocument}": { "parameters": [ { "name": "idtypedocument", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do tipo de documento." } ], "put": { "operationId": "typeAccountDocumentPut", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Atualiza um tipo de documento", "description": "Atualiza descrição e flags de padrão (`DefaultOrder`, `DefaultPurchase`) 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 a listagem para `/type/account/document` é invalidado. A resposta é a lista completa atualizada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeDocumentUpdate" } } }, "description": "Atualiza os mesmos campos do POST (`TypeDocument`, `DefaultOrder`, `DefaultPurchase`)." }, "responses": { "200": { "description": "Tipo de documento atualizado. Devolve a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeDocumentListItem" } } } } }, "400": { "description": "Tipo de documento não encontrado para a empresa. Mensagem: `[BadRequest] - Tipo Documento não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "typeAccountDocumentDelete", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Exclui (inativa) um tipo de documento", "description": "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 a listagem é invalidado e a resposta é a lista completa atualizada.", "responses": { "200": { "description": "Tipo de documento inativado. Devolve a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeDocumentListItem" } } } } }, "400": { "description": "Tipo de documento não encontrado ou referenciado por parametrização. Mensagens: `[BadRequest] - Tipo documento não existe`; `[BadRequest] - Tipo documento esta na parametrização da empresa. Remover a parametrização antes de excluir o documento`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/status": { "get": { "operationId": "typeOrderStatusList", "tags": [ "Tipos — Pedido" ], "summary": "Lista os status de pedido da empresa", "description": "Retorna a lista de **status de pedido** configurados para a empresa autenticada, com o nome editado (`StatusOrder`), a cor (`StatusColorCode`) e a descrição padrão do sistema (`StatusOrderDescription`). A lista de status é fixa no sistema (até 58 valores diferentes, abrangendo todo o ciclo do pedido — Aberto, Fechado, Picking, Packing, Enviado, Entregue, Cancelado, OS, Orçamento, etc.), e cada empresa pode renomear/colorir esses status mas não pode adicionar novos.\n\nA resposta vem ordenada por `Order` (posição do status no fluxo). O campo `IDStatusOrder` é devolvido como string (`CAST AS CHAR`).", "parameters": [ { "name": "ChangeOnCreate", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra apenas os status que podem ser usados como **status inicial** ao criar um pedido (`ChangeOnCreate=1`). Esses são, por exemplo: Aberto, Fechado, Enviado, Entregue, Em espera, A faturar, Nota Fiscal, Cancelado, Em devolução, Fulfillment e os status de OS." } ], "responses": { "200": { "description": "Lista de status do pedido configurados para a empresa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeOrderStatusListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/status/{idstatusorder}": { "parameters": [ { "name": "idstatusorder", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do status de pedido (fixo no sistema). Valores comuns: 0=Aberto, 1=Fechado, 2=Iniciado picking, 3=Pré picking-list, 4=Finalizado picking, 5=Segurar pedido, 6=Aguardando expedição, 7=Enviado, 8=Entregue com sucesso, 9=Em espera, 21=A faturar, 90=Cancelado, 100=Deletado, etc." } ], "put": { "operationId": "typeOrderStatusPut", "tags": [ "Tipos — Pedido" ], "summary": "Atualiza o nome e a cor de um status de pedido", "description": "Atualiza o **nome local** (`StatusOrder`) e a **cor** (`StatusColorCode`) que a empresa autenticada usa para o status. **Não é possível** criar status novos nem excluir os existentes — a tabela de status do sistema é fixa. A resposta é a lista atualizada de status (mesmo formato de `GET /type/order/status`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeOrderStatusUpdate" } } }, "description": "Atualiza a descrição e a cor do status do pedido para a empresa autenticada. `StatusOrder` é o nome amigável exibido na tela; `StatusColorCode` é a cor de destaque (formato hexadecimal `#RRGGBB`)." }, "responses": { "200": { "description": "Status atualizado. Retorna a lista de status atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeOrderStatusListItem" } } } } }, "400": { "description": "Status não localizado na empresa. Mensagem: `[BadRequest] - Status pedido não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/type": { "get": { "operationId": "typeOrderTypeList", "tags": [ "Tipos — Pedido" ], "summary": "Lista tipos de pedido", "description": "Retorna os tipos de pedido **ativos** (`Status=1`) da empresa autenticada, com a descrição amigável da política comercial, do faturador, do armazém padrão, do armazém de devolução, do tipo de retorno simbólico de armazenagem, do tipo de devolução, do plano de contas, do centro de custo e da finalidade da NFe. Ordenado por nome.\n\nAceita filtros opcionais por: `EnableFrenteCaixa` (apenas tipos visíveis no PDV), `IDCompanyInvoice` (filtra pelo faturador), `ServiceRequest` (apenas tipos marcados como ordem de serviço) e `IsTransfer` (apenas tipos de transferência entre filiais).", "parameters": [ { "name": "EnableFrenteCaixa", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, traz apenas tipos com **Ativo frente de caixa = Sim**." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo faturador (filial) configurado no tipo de pedido." }, { "name": "ServiceRequest", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, traz apenas tipos marcados como **Ordem de Serviço**." }, { "name": "IsTransfer", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, traz apenas tipos de **transferência** entre filiais." } ], "responses": { "200": { "description": "Lista de tipos de pedido.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeOrderListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "orderTypeOrderPost", "tags": [ "Tipos — Pedido" ], "summary": "Cadastra um tipo de pedido", "description": "Cria um novo tipo de pedido. **Regras de unicidade**: cada empresa pode ter no máximo **um** tipo marcado como `Default=1`, `Resend=1`, `Return=1` e `SymbolicReturn=1` — ao salvar com qualquer um desses flags em `1`, o tipo anterior é automaticamente desmarcado.\n\n**Validações**: faturador (se diferente da própria conta) precisa ser uma filial; armazém (padrão e de devolução) precisa estar ativo na mesma empresa; tipo de pedido para retorno simbólico e tipo de pedido para devolução precisam existir na mesma empresa; plano de contas e centro de custo precisam pertencer à empresa; `TypeOrderOrderPriority` aceita `0`–`10`.\n\nA resposta retorna **a lista completa** de tipos de pedido da empresa (mesmo formato de `GET /type/order/type`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeOrderCreate" } } }, "description": "Dados do tipo de pedido a cadastrar. Cobre uma grande área de configuração: flags de uso (`Default`, `Resend`, `Return`, `SymbolicReturn` — cada uma, quando `1`, desmarca o tipo anteriormente marcado da empresa), prefixo do número do pedido (`OrderPrefix`), política comercial (`IDCompanySalesPolicy`), faturador padrão (`IDCompanyInvoice`), armazém padrão e de devolução (`IDStockKeepingUnitWarehouse`/`IDStockKeepingUnitWarehouseReturn`), comportamento de NF (`CreateBankSlipAfterInvoice`, `RecalculateAccountsDueDateAfterInvoice`, `BlockInvoiceToCompanySameDocument`, `IssueNFCe`, `TypeOrderNfeindFinal`, `TypeOrderNfeComments`, `InvoiceIntermedCNPJ`, `IncludeInboundInvoiceReferenceKey`, `CfopConsiderSymbolicStorageReturn`), regras de movimentação (`BalanceChange`, `IsTransfer`, `ServiceRequest`), regras comerciais (`MinimumMarkup`, `MaximumDiscountPerItem`, `BlockSkuZeroValue`, `SafetyStockPercent`, `AutomaticCancelOpenOrderAfterHour`, `OrderFinishConfirmation`, `ConsumerVoucherDefault`), cotação de frete (`CarrierQuotation`), prioridade WMS (`TypeOrderOrderPriority`, 0–10), e financeiro (`IDTypeAccountPayableReceivable`, `IDTypeCostCenter`). Existências de armazém, faturador, política comercial, tipo de pedido de devolução, plano de contas e centro de custo são validadas contra a empresa autenticada." }, "responses": { "200": { "description": "Tipo criado. Retorna a lista completa atual de tipos de pedido.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeOrderListItem" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Empresa não existe`\n- `Politica comercial não existe`\n- `Faturador não existe`\n- `Armazém não existe` / `Armazém devolução não existe`\n- `Tipo de pedido para retorno simbólico de armazenagem não localizado`\n- `Tipo de pedido de devolução não localizado`\n- `Plano de contas não existe`\n- `Centro de custo não existe`\n- `Prioridade pedido precisa ser entre 0 e 10`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/type/{idordertype}": { "parameters": [ { "name": "idordertype", "in": "path", "required": true, "description": "Identificador do tipo de pedido (`IDTypeOrder`).", "schema": { "type": "integer", "format": "int32" } } ], "get": { "operationId": "orderTypeOrderGet", "tags": [ "Tipos — Pedido" ], "summary": "Detalha um tipo de pedido", "description": "Retorna o detalhe do tipo de pedido informado, **acrescido das regras fiscais** (`TypeOrderTax[]`) — uma entrada por departamento fiscal cadastrado para SKUs na empresa, com o vínculo opcional `IDTax` da regra fiscal aplicada ao tipo de pedido.\n\nQuando o id não existe ou pertence a outra empresa, devolve `[]` em status `200`.", "responses": { "200": { "description": "Tipo encontrado (array com 1 item) ou `[]` quando não encontrado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeOrderDetail" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "orderTypeOrderPut", "tags": [ "Tipos — Pedido" ], "summary": "Atualiza um tipo de pedido", "description": "Atualiza o tipo de pedido. As mesmas regras de unicidade e validação do POST valem.\n\nA resposta retorna **a lista completa** de tipos de pedido da empresa (mesmo formato de `GET /type/order/type`).", "requestBody": { "required": true, "description": "Mesmo formato do POST.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeOrderCreate" } } } }, "responses": { "200": { "description": "Tipo atualizado. Retorna a lista completa atual de tipos de pedido.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeOrderListItem" } } } } }, "400": { "description": "Mesmas validações do POST. Mensagens possíveis:\n- `Tipo pedido não existe`\n- `Politica comercial não existe`\n- `Faturador não existe`\n- `Armazém não existe` / `Armazém devolução não existe`\n- `Tipo de pedido para retorno simbólico de armazenagem não localizado`\n- `Tipo de pedido de devolução não localizado`\n- `Plano de contas não existe`\n- `Centro de custo não existe`\n- `Prioridade pedido precisa ser entre 0 e 10`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "orderTypeOrderDelete", "tags": [ "Tipos — Pedido" ], "summary": "Inativa um tipo de pedido", "description": "Inativa o tipo de pedido (soft delete — `Status=0`). Antes de inativar, remove **todas** as regras fiscais (`TypeOrderTax`) vinculadas a este tipo.\n\n**Bloqueios**:\n- Tipo já usado em pedidos (`Orders`).\n- Tipo configurado como **de/para de armazém** em `HubWarehouse`.\n- Tipo configurado como **de/para de política comercial** em `HubSalesPolicy`.\n- Tipo atrelado a uma **conta bancária** (`IDTypeOrder`).\n- Tipo referenciado por outro tipo como **retorno simbólico de armazenagem** (`IDTypeOrderSymbolicStorageReturn`).\n- Tipo referenciado por outro tipo como **devolução padrão** (`IDTypeOrderDefaultReturn`) — apenas se o outro tipo ainda está ativo.\n\nA resposta retorna a lista completa atual (chama internamente o `GET`).", "responses": { "200": { "description": "Tipo inativado. Retorna a lista completa atual de tipos de pedido.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeOrderListItem" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Tipo pedido não existe`\n- `Tipo de pedido já tem pedido criado e não pode ser excluído`\n- `Tipo de pedido tem de/para de armazém e não pode ser excluído`\n- `Tipo de pedido tem de/para de política comercial e não pode ser excluído`\n- `Tipo de pedido esta atrelado a conta bancária e não pode ser excluído`\n- `Tipo de pedido esta atrelado a tipo de pedido retorno simbólico armazenagem no tipo de pedido `\n- `Tipo de pedido esta atrelado como tipo de pedido de devolução padrão no tipo de pedido `", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/payment": { "get": { "operationId": "typeOrderPaymentList", "tags": [ "Tipos — Pedido" ], "summary": "Lista tipos de pagamento", "description": "Retorna os tipos de pagamento ativos da empresa, ordenados por descrição. Cada item traz a categoria (cartão de crédito, débito, Pix, boleto, dinheiro, vale, etc.) e a bandeira (`NfTBand`) quando a categoria exige uma — categorias `1` (cartão de crédito) e `6` (cartão de débito) sempre vêm com bandeira.", "parameters": [ { "name": "EnableFrenteCaixa", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra apenas tipos habilitados (1) ou não habilitados (0) para frente de caixa." } ], "responses": { "200": { "description": "Lista de tipos de pagamento ativos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypePaymentListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "typeOrderPaymentPost", "tags": [ "Tipos — Pedido" ], "summary": "Cadastra um tipo de pagamento", "description": "Cria um tipo de pagamento na empresa autenticada. Quando `Category` for `1` (cartão de crédito) ou `6` (cartão de débito), o campo `NfTBand` é obrigatório e precisa existir na tabela de bandeiras suportadas. A resposta é a lista atualizada de tipos de pagamento.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypePaymentCreate" } } }, "description": "Dados do tipo de pagamento a cadastrar. `TypePaymentDescription` é o nome amigável. `Category` agrupa pagamentos para apuração. `DaysDue` é o prazo padrão (em dias) usado para gerar a data de vencimento das contas. `DefaultOrder`/`DefaultPurchase` marcam o tipo como padrão de pedido de venda/compra. `NfTBand`, quando informada, define a bandeira reportada na NFe e é validada contra `NfTBand`. `EnableFrenteCaixa=1` habilita o tipo no PDV. `IncludeComission=1` (default) inclui o pagamento no cálculo de comissão." }, "responses": { "200": { "description": "Tipo criado. Retorna a lista atualizada (mesmo formato de `GET /type/order/payment`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypePaymentListItem" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Company não existe`\n- `Bandeira não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/payment/{idtypepayment}": { "parameters": [ { "name": "idtypepayment", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do tipo de pagamento." } ], "put": { "operationId": "typeOrderPaymentPut", "tags": [ "Tipos — Pedido" ], "summary": "Atualiza um tipo de pagamento", "description": "Substitui o cadastro do tipo de pagamento. **Atualização total** — todos os campos do corpo são gravados (campos omitidos viram `null` ou recebem o default do endpoint). A resposta é a lista atualizada de tipos de pagamento. Mesma regra de `NfTBand` obrigatório quando `Category` é `1` ou `6`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypePaymentCreate" } } }, "description": "Atualiza o tipo de pagamento. Mesmos campos do POST: `TypePaymentDescription`, `Category`, `DaysDue`, `DefaultOrder`, `DefaultPurchase`, `NfTBand`, `EnableFrenteCaixa`, `IncludeComission`. Quando `NfTBand` muda, é validada contra `NfTBand`." }, "responses": { "200": { "description": "Tipo atualizado. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypePaymentListItem" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Tipo pagamento não existe`\n- `Bandeira não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "typeOrderPaymentDelete", "tags": [ "Tipos — Pedido" ], "summary": "Exclui (inativa) um tipo de pagamento", "description": "Marca o tipo de pagamento como inativo (`Status=0`); o registro não é apagado fisicamente. A resposta é a lista de tipos ativos atualizada.", "responses": { "200": { "description": "Tipo inativado. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypePaymentListItem" } } } } }, "400": { "description": "Tipo não localizado. Mensagem: `[BadRequest] - Tipo Pagamento não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/payment/{idtypepayment}/rate": { "parameters": [ { "name": "idtypepayment", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do tipo de pagamento." } ], "get": { "operationId": "typeOrderPaymentRateGet", "tags": [ "Tipos — Pedido" ], "summary": "Lista as taxas adquirentes do tipo de pagamento", "description": "Retorna a lista de taxas (MDR + AR ou taxa fixa) vinculadas ao tipo de pagamento, com os identificadores e descrições resolvidas da integração e do método de pagamento do adquirente (`TypePayment`). Cada item descreve uma combinação de **integração adquirente** + **método de pagamento (bandeira/modalidade)** + **faixa de parcelas** + **vigência**, com a taxa correspondente.", "responses": { "200": { "description": "Lista de taxas adquirentes.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypePaymentRateItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "typeOrderPaymentRatePost", "tags": [ "Tipos — Pedido" ], "summary": "Cadastra uma taxa adquirente para o tipo de pagamento", "description": "Cria uma combinação de integração + método de pagamento + faixa de parcelas + vigência, com a taxa correspondente. O sistema bloqueia o salvamento quando já existe outra taxa cobrindo a mesma faixa de parcelas em um período sobreposto com a mesma integração — a mensagem indica em qual tipo de pagamento a colisão acontece. Taxas negativas (`FixedRate`, `MerchantDiscountRate` ou `AnticipationRate < 0`) também são rejeitadas. A resposta é a lista atualizada de taxas do tipo de pagamento.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypePaymentRateCreate" } } }, "description": "Combinação adquirente + método + faixa de parcelas + vigência com a taxa cobrada nesse cenário. Pode ser **MDR + AR** (deixe `FixedRate=0`) ou **taxa fixa** (deixe `MerchantDiscountRate=0` e `AnticipationRate=0`). Taxas negativas são rejeitadas. `MinInstallment` ≤ `MaxInstallment`. `IDCompanyIntegration` e `IDTypePaymentFrom` (combinação bandeira + modalidade do adquirente) são obrigatórios e validados contra `TypeAcquirerPayment` + `CompanyIntegration` da empresa (categoria adquirente). A combinação (faixa de parcelas + vigência) não pode sobrepor com outra taxa já cadastrada." }, "responses": { "200": { "description": "Taxa criada. Retorna a lista atualizada (mesmo formato de `GET /type/order/payment/{idtypepayment}/rate`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypePaymentRateItem" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Taxas não podem ter valor negativo`\n- `Empresa não existe`\n- `Integração obrigatório`\n- `Integração não existe`\n- `Método de pagamento obrigatório`\n- `O mínimo de parcelas não pode ser maior que o máximo de parcelas`\n- `Já existe uma taxa com a mesma quantidade de parcela e data de vigência`\n- `Já existe uma taxa com a mesma quantidade de parcela e data de vigência para o tipo de pagamento código: `", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/payment/{idtypepayment}/rate/{idtypepaymentrate}": { "parameters": [ { "name": "idtypepayment", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do tipo de pagamento." }, { "name": "idtypepaymentrate", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da taxa adquirente." } ], "put": { "operationId": "typeOrderPaymentRatePut", "tags": [ "Tipos — Pedido" ], "summary": "Atualiza uma taxa adquirente", "description": "Atualização **parcial** — apenas os campos enviados no corpo são alterados. Mesmas regras de sobreposição e taxas negativas do `POST`. A resposta é a lista atualizada de taxas do tipo de pagamento.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypePaymentRateUpdate" } } }, "description": "Atualização parcial da taxa — apenas os campos enviados são alterados. Mantém as regras do POST: taxas não negativas, faixa de parcelas válida, vigência sem sobreposição com outras taxas da mesma integração." }, "responses": { "200": { "description": "Taxa atualizada. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypePaymentRateItem" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Taxas não podem ter valor negativo`\n- `Tipo taxa pagamento não existe`\n- `Integração obrigatório`\n- `Integração não existe`\n- `Método de pagamento obrigatório`\n- `O mínimo de parcelas não pode ser maior que o máximo de parcelas`\n- `Já existe uma taxa com a mesma quantidade de parcela e data de vigência`\n- `Já existe uma taxa com a mesma quantidade de parcela e data de vigência para o tipo de pagamento código: `", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "typeOrderPaymentRateDelete", "tags": [ "Tipos — Pedido" ], "summary": "Exclui uma taxa adquirente", "description": "Apaga fisicamente a taxa (não é exclusão lógica). A resposta é a string `\"sucesso\"`.", "responses": { "200": { "description": "Taxa excluída. Retorna a string `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "enum": [ "sucesso" ] } } } }, "400": { "description": "Taxa ou tipo de pagamento não encontrados. Mensagem: `[BadRequest] - Tipo taxa de pagamento não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/cost-center": { "get": { "operationId": "typeAccountCostCenterList", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Lista centros de custo", "description": "Retorna os centros de custo ativos da empresa, ordenados por descrição. Cada item traz a descrição, o código externo opcional (usado para casar com sistemas terceiros — ERP contábil, integração de governança) e o subdomínio da empresa.", "responses": { "200": { "description": "Lista de centros de custo ativos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeCostCenterListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "typeAccountCostCenterPost", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Cadastra um centro de custo", "description": "Cria um centro de custo na empresa autenticada. Quando `ExternalCode` for informado, o sistema bloqueia o cadastro se já existir outro centro de custo ativo na mesma empresa com o mesmo código externo. A resposta é a lista atualizada de centros de custo.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeCostCenterCreate" } } }, "description": "Dados do centro de custo a cadastrar. `TypeCostCenter` (descrição) obrigatório. `ExternalCode`, quando informado, precisa ser único na empresa entre os centros ativos." }, "responses": { "200": { "description": "Centro criado. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeCostCenterListItem" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Empresa não existe`\n- `Já existe um centro de custo com este código externo`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/cost-center/{idtypecostcenter}": { "parameters": [ { "name": "idtypecostcenter", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do centro de custo." } ], "put": { "operationId": "typeAccountCostCenterPut", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Atualiza um centro de custo", "description": "Atualiza a descrição e o código externo do centro de custo. Quando `ExternalCode` mudar, o sistema aplica a mesma checagem de duplicidade do `POST`. A resposta é a lista atualizada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeCostCenterCreate" } } }, "description": "Atualiza descrição e/ou `ExternalCode` do centro de custo. `ExternalCode` mantém a regra de unicidade na empresa." }, "responses": { "200": { "description": "Centro atualizado. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeCostCenterListItem" } } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Centro de custo não existe`\n- `Já existe um centro de custo com este código externo`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "typeAccountCostCenterDelete", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Exclui (inativa) um centro de custo", "description": "Marca o centro de custo como inativo (`Status=0`). O registro não é apagado fisicamente — rateios e títulos antigos continuam apontando para ele, mas o centro não aparece mais nas listas e seletores. A resposta é a lista atualizada de centros ativos.", "responses": { "200": { "description": "Centro inativado. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeCostCenterListItem" } } } } }, "400": { "description": "Centro não localizado. Mensagem: `[BadRequest] - Centro de custo não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase/cfop-inbound": { "get": { "operationId": "purchaseCfopInboundList", "tags": [ "DE-PARA CFOP Recebimento" ], "summary": "Lista regras DE-PARA de CFOP de recebimento", "description": "Retorna todos os pares CFOP origem → CFOP destino cadastrados para a empresa, ordenados pelo CFOP de origem. Cada item já vem com a descrição de cada CFOP. Quando a empresa autenticada é a `all` (multi-conta), retorna as regras de todas as empresas vinculadas.", "responses": { "200": { "description": "Lista de regras DE-PARA.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseCfopInboundListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "purchaseCfopInboundPost", "tags": [ "DE-PARA CFOP Recebimento" ], "summary": "Cadastra uma regra DE-PARA de CFOP", "description": "Cria uma regra para a empresa autenticada. Valida que `CfopFrom` e `CfopTo` existem no catálogo nacional de CFOPs e que o par ainda não foi cadastrado para a empresa (a tabela tem chave única em `CfopFrom + CfopTo + IDCompany`). A resposta é a **lista completa atualizada** das regras da empresa.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseCfopInboundCreate" } } }, "description": "Dados da regra de conversão de CFOP no recebimento. Obrigatorio enviar `CfopFrom` (CFOP de origem) e `CfopTo` (CFOP de destino); ambos precisam existir na tabela de CFOPs e a combinação não pode estar duplicada para a empresa." }, "responses": { "200": { "description": "Regra criada. Devolve a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseCfopInboundListItem" } } } } }, "400": { "description": "Erros de validação. Mensagens possíveis: `[BadRequest] - Esta regra já existe e não será adicionada novamente`; `[BadRequest] - CFOP de origem não existe`; `[BadRequest] - CFOP de destino não existe`; `[BadRequest] - Empresa não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase/cfop-inbound/{idstockkeepingunitpurchasecfopinbound}": { "parameters": [ { "name": "idstockkeepingunitpurchasecfopinbound", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da regra DE-PARA." } ], "put": { "operationId": "purchaseCfopInboundPut", "tags": [ "DE-PARA CFOP Recebimento" ], "summary": "Atualiza uma regra DE-PARA", "description": "Atualiza o par `CfopFrom`/`CfopTo` de uma regra existente. Ambos os campos são considerados em toda chamada (não é atualização parcial). Aplica as mesmas validações do POST: os CFOPs precisam existir no catálogo nacional e o novo par não pode colidir com outra regra da empresa. A resposta é a lista completa atualizada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseCfopInboundUpdate" } } }, "description": "Novos valores da regra de conversão de CFOP. Enviar `CfopFrom` e `CfopTo`; ambos precisam existir e a combinação não pode coincidir com outra regra já cadastrada na empresa." }, "responses": { "200": { "description": "Regra atualizada. Devolve a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseCfopInboundListItem" } } } } }, "400": { "description": "Erros de validação. Mensagens possíveis: `[BadRequest] - De/Para de CFOP não existe`; `[BadRequest] - Esta regra já existe e não será adicionada novamente`; `[BadRequest] - CFOP de origem não existe`; `[BadRequest] - CFOP de destino não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "purchaseCfopInboundDelete", "tags": [ "DE-PARA CFOP Recebimento" ], "summary": "Exclui uma regra DE-PARA", "description": "**Remove fisicamente** o registro (não é exclusão lógica). Não há regra de bloqueio: a exclusão é sempre permitida quando a regra pertence à empresa. A resposta é a lista completa atualizada.", "responses": { "200": { "description": "Regra excluída. Devolve a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseCfopInboundListItem" } } } } }, "400": { "description": "Regra não encontrada. Mensagem: `[BadRequest] - De/Para de CFOP não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/sales-policy": { "get": { "operationId": "companySalesPolicyGet", "tags": [ "Políticas Comerciais" ], "summary": "Lista políticas comerciais", "description": "Retorna as políticas comerciais (tabelas de preço) cadastradas pela empresa, ordenadas por nome. Cada item traz o tipo da política (`TypeCompanySalesPolicy` — Normal / Custo médio / Relativa), o nome da política base (`CompanySalesPolicyFrom`, quando é uma política relativa), o tipo de operação (`TypeCompanySalesPolicyOperation` — Multiplicação ou Soma), o valor da operação e o markup configurado.", "parameters": [ { "name": "IDCompanySalesPolicy", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por identificador único da política comercial." }, { "name": "IDTypeCompanySalesPolicy", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3 ] }, "description": "Filtra por tipo de política: 1=Normal, 2=Custo médio, 3=Relativa à outra política." } ], "responses": { "200": { "description": "Lista de políticas comerciais da empresa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySalesPolicyListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "companySalesPolicyPost", "tags": [ "Políticas Comerciais" ], "summary": "Cadastra uma política comercial", "description": "Cria uma política comercial na empresa autenticada. Regras:\n\n- Quando `IDTypeCompanySalesPolicy=3` (Relativa), `IDCompanySalesPolicyFrom`, `IDTypeCompanySalesPolicyOperation` e `OperationValue` são **obrigatórios**.\n- A política base (`IDCompanySalesPolicyFrom`) **não pode** ser do tipo Relativa (3) — só Normal ou Custo médio podem servir de base. Isso evita cadeias de políticas relativas.\n- Quando `Default=1`, o sistema **desmarca** automaticamente a política padrão anterior, garantindo que sempre haja exatamente uma política padrão por empresa.\n- `IDTypeCompanySalesPolicy` default = `1` (Normal) quando omitido.\n\nA resposta é o detalhe da política recém-criada (mesmo formato de `GET /company/sales-policy?IDCompanySalesPolicy=`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySalesPolicyCreate" } } }, "description": "Dados da política comercial a cadastrar. Obrigatório `CompanySalesPolicy` (nome). Campos opcionais: `Default` (1 marca como padrão e desmarca a anterior), `CostAverage`, `Markup`, `IDTypeCompanySalesPolicy` (1 = comum, 2 = atacado, 3 = relativa — quando 3, exige `IDCompanySalesPolicyFrom`, `IDTypeCompanySalesPolicyOperation` e `OperationValue`), `IDCompanySalesPolicyFrom`, `PriceRounding`, `IDTypeCompanySalesPolicyOperation` e `OperationValue`." }, "responses": { "200": { "description": "Política criada. Retorna o detalhe da política recém-cadastrada (array com 1 item).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySalesPolicyListItem" }, "maxItems": 1 } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Para política do tipo relativa, obrigatório o preenchimento do tipo operação, política comercial base e valor da operação`\n- `Empresa não existe`\n- `Tipo política comercial não existe`\n- `Política comercial base não existe`\n- `Tipo operação não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/sales-policy/{idcompanysalespolicy}": { "parameters": [ { "name": "idcompanysalespolicy", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da política comercial." } ], "put": { "operationId": "companySalesPolicyPut", "tags": [ "Políticas Comerciais" ], "summary": "Atualiza uma política comercial", "description": "Atualiza uma política comercial. Atenção: apenas o nome `CompanySalesPolicy` e a marca padrão `Default` são aplicados parcialmente (só mudam quando enviados); os demais campos são sempre regravados e, quando omitidos, voltam ao padrão (`IDTypeCompanySalesPolicy`→1 Normal, `CostAverage`→0, `Markup`/`IDCompanySalesPolicyFrom`/`IDTypeCompanySalesPolicyOperation`/`OperationValue`/`PriceRounding`→nulo), o que reverte o tipo para Normal e zera a configuração de política Relativa — por isso, envie a configuração completa a cada atualização. Regras:\n\n- Quando `IDTypeCompanySalesPolicy=3` (Relativa), `IDCompanySalesPolicyFrom`, `IDTypeCompanySalesPolicyOperation` e `OperationValue` são **obrigatórios**.\n- A política base não pode ser do tipo Relativa.\n- Quando `Default=1`, o sistema desmarca a política padrão anterior. Quando `Default=0`, o sistema **bloqueia** o salvamento se essa for a única política padrão da empresa — com a mensagem `É preciso ter uma politica comercial padrão`.\n- **Recálculo de preços**: quando o tipo final da política for Relativa, os preços de venda vigentes vinculados a ela (com vigência que inclui a data atual) são recalculados de forma assíncrona com base na nova política base e operação; a API responde imediatamente.\n\nA resposta é o detalhe atualizado da política (array com 1 item).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySalesPolicyUpdate" } } }, "description": "Campos da política comercial a atualizar — apenas os enviados são aplicados. Aceita `CompanySalesPolicy`, `Default`, `CostAverage`, `Markup`, `IDTypeCompanySalesPolicy`, `IDCompanySalesPolicyFrom`, `PriceRounding`, `IDTypeCompanySalesPolicyOperation` e `OperationValue`. Para `IDTypeCompanySalesPolicy = 3` (relativa) os campos de operação e política base são obrigatórios; tirar a marca padrão exige que outra política já esteja como padrão." }, "responses": { "200": { "description": "Política atualizada. Retorna o detalhe atualizado (array com 1 item).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySalesPolicyListItem" }, "maxItems": 1 } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Politica comercial não existe`\n- `Para política do tipo relativa, obrigatório o preenchimento do tipo operação, política comercial base e valor da operação`\n- `É preciso ter uma politica comercial padrão`\n- `Tipo política comercial não existe`\n- `Política comercial base não existe`\n- `Tipo operação não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "companySalesPolicyDelete", "tags": [ "Políticas Comerciais" ], "summary": "Exclui uma política comercial", "description": "**Exclusão física** — a política é apagada definitivamente do banco. O sistema bloqueia a exclusão em cinco situações:\n\n1. A política é a **padrão** (`Default=1`) — defina outra como padrão antes.\n2. Existem **preços vinculados** a ela em `StockKeepingUnitPricing`.\n3. Existem **de/para de canal de venda** em `HubSalesPolicy` apontando para ela como destino.\n4. Existem **tipos de pedido** em `TypeOrder` configurados para usar essa política como padrão.\n5. Existem **promoções de PDV** em `StockKeepingUnitPromotionSalesPolicies` vinculadas.\n\nA resposta em sucesso é a lista atualizada de políticas (mesmo formato de `GET /company/sales-policy`).", "responses": { "200": { "description": "Política excluída. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySalesPolicyListItem" } } } } }, "400": { "description": "Bloqueios de exclusão (prefixo `[BadRequest]`):\n- `Politica comercial não existe`\n- `Precisa definir outra política comercial padrão antes de deletar`\n- `Existem preços vinculados a essa politica comercial`\n- `Existem de/para vinculados a essa politica comercial`\n- `Existem tipos de pedido vinculados a essa politica comercial`\n- `Existem promoções PDV vinculadas a essa politica comercial`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company": { "get": { "operationId": "companyGet", "tags": [ "Minha Empresa" ], "summary": "Detalha a empresa autenticada", "description": "Retorna o cadastro completo da empresa identificada pelo subdomínio (`AccountName`) usado na chamada — todos os campos do cadastro da empresa mais os dados agregados: descrição do regime tributário (CRT), URL do logotipo (com sufixo `-thumbnail`), id da integração NFe/NFSe principal (`IDCompanyIntegration` com `IDTypeCompanyIntegration=16`), array de inscrições estaduais em `StateInscription` e array de créditos do Simples Nacional em `CompanySimplesCred`.\n\nO campo `CertificadoPassword` é sempre retornado como `null` (a senha do certificado nunca é exposta pela API).", "responses": { "200": { "description": "Cadastro da empresa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDetail" }, "maxItems": 1 } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "companyPut", "tags": [ "Minha Empresa" ], "summary": "Atualiza a empresa autenticada", "description": "Atualização parcial — apenas os campos enviados são alterados. Regras de validação:\n\n- `NfeSerie` e `NfceSerie` não podem ser maiores que 999.\n- Quando `NfeSerie` muda, todas as notas pendentes (`IDStatusInvoice IN (0,1)`) da série anterior, modelo 55, têm o flag `Main` zerado.\n- Quando `NfceSerie` muda, mesma regra para modelo 65.\n- Quando `CompanyAddressPostalCode` muda, o sistema consulta o CEP novo e atualiza o `CompanyAddressIbgeCityCode` automaticamente (a menos que tenha sido informado no body).\n- Quando `CteFeedStatus=1`, o sistema bloqueia se já existe outra empresa com o **mesmo CNPJ** e CTe ativo (a feature de CTe não suporta duas empresas com mesmo CNPJ).\n\nA cada alteração, o sistema gera um log em `CompanyLog` com os campos alterados (DE → PARA) e devolve o cadastro completo atualizado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUpdate" } } }, "description": "Campos da empresa autenticada a atualizar. Atualização parcial — apenas os campos enviados são alterados; os demais permanecem com o valor atual. Quando `CompanyAddressPostalCode` muda, o sistema recalcula `CompanyAddressIbgeCityCode`." }, "responses": { "200": { "description": "Cadastro atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Serie NFe não pode ser maior que 999`\n- `Serie NFCe não pode ser maior que 999`\n- `Empresa não existe`\n- `CNPJ já tem recurso de CTe ativo e não pode estar em duas empresas com mesmo CNPJ`\n- `erro consultar cep` (quando o CEP novo é inválido)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/branch": { "get": { "operationId": "companyBranchGet", "tags": [ "Minha Empresa" ], "summary": "Lista a empresa-matriz e suas filiais", "description": "Retorna a empresa-matriz autenticada e a lista de **filiais** vinculadas a ela via `CompanyMain` (que aponta para a matriz). A resposta traz os campos principais da matriz e um array `Branch[]` com os dados das filiais (id, subdomínio, CNPJ, razão social, nome fantasia, logo, certificado, série NFe/NFCe, regime tributário).", "responses": { "200": { "description": "Dados da matriz + lista de filiais.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyBranchResponse" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/company-logo": { "post": { "operationId": "companyLogoPost", "tags": [ "Minha Empresa" ], "summary": "Sobe ou troca o logotipo da empresa", "description": "Aceita duas formas de envio do logotipo:\n\n- **Upload multipart** (`multipart/form-data` com campo `file`) — sobe o arquivo direto do cliente.\n- **URL externa** (`application/json` com `{ \"Url\": \"...\" }`) — o sistema baixa a imagem da URL informada e grava no S3.\n\nA imagem é salva no bucket público do idworks (`https://public.idworks.com.br/Image/_.`) e o campo `CompanyLogoUrl` é atualizado. Resposta é um status HTTP — `200` em sucesso (corpo vazio), `404` se a empresa não existe, `400` quando a URL externa não retorna a imagem.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Arquivo de imagem (PNG/JPG)." } } } }, "application/json": { "schema": { "type": "object", "required": [ "Url" ], "properties": { "Url": { "type": "string", "format": "uri", "description": "URL pública de onde o sistema deve baixar a imagem." } } } } }, "description": "Logotipo da empresa. Aceita duas formas: (a) upload `multipart/form-data` com o arquivo no campo padrão do formulário; (b) corpo JSON com `{ \"url\": \"https://...\" }` — o sistema baixa a imagem da URL informada. O arquivo é gravado no bucket público da empresa e o `CompanyLogoUrl` (mais o `CompanyLogoUrlThumbnail`) é atualizado no cadastro." }, "responses": { "200": { "description": "Logotipo aplicado (corpo vazio).", "content": {} }, "400": { "description": "Falha ao baixar imagem da URL informada. Mensagem: `[BadRequest] - erro ao baixar imagem`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "404": { "description": "Empresa não encontrada (corpo vazio)." }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/state-inscription": { "post": { "operationId": "companyStateInscriptionPost", "tags": [ "Minha Empresa" ], "summary": "Adiciona uma inscrição estadual", "description": "Cria uma inscrição estadual (IE) vinculada à empresa. Regras:\n\n- A inscrição é validada com o algoritmo oficial por UF (pacote `ie`). Quando inválida, o salvamento é bloqueado.\n- Para Minas Gerais (`State=MG`), o sistema faz padding com zeros à esquerda até 13 dígitos.\n- A inscrição não pode duplicar entre estados na mesma empresa.\n- A empresa só pode ter **uma** inscrição por estado.\n\nA resposta é o detalhe atualizado da empresa (mesmo formato de `GET /company`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyStateInscriptionCreate" } } }, "description": "Dados da inscrição estadual a cadastrar para a empresa. Apenas `State` e `StateInscription` são obrigatórios. A inscrição é validada com o algoritmo oficial da UF e cada empresa pode ter no máximo uma inscrição por UF." }, "responses": { "200": { "description": "Inscrição adicionada. Retorna o detalhe atualizado da empresa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Empresa não existe`\n- `Inscrição estadual não é válida`\n- `Inscrição estadual já adicionada no estado `\n- `Estado já tem configuração`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/state-inscription/{idstateinscription}": { "parameters": [ { "name": "idstateinscription", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da inscrição estadual (`IDCompanyStateInscription`)." } ], "put": { "operationId": "companyStateInscriptionPut", "tags": [ "Minha Empresa" ], "summary": "Atualiza uma inscrição estadual", "description": "Atualização total — todos os campos do corpo são gravados. Mesmas regras de validação do `POST` (algoritmo oficial por UF, padding MG, unicidade por estado).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyStateInscriptionCreate" } } }, "description": "Atualização total da inscrição estadual — todos os campos do corpo são gravados (sobrescreve o cadastro). Mantém as mesmas validações do `POST`." }, "responses": { "200": { "description": "Inscrição atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Inscrição estadual não existe`\n- `Inscrição estadual não é válida`\n- `Inscrição estadual já adicionada no estado `", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "companyStateInscriptionDelete", "tags": [ "Minha Empresa" ], "summary": "Remove uma inscrição estadual", "description": "Apaga fisicamente a inscrição estadual. A resposta é o detalhe atualizado da empresa.", "responses": { "200": { "description": "Inscrição removida.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDetail" }, "maxItems": 1 } } } }, "400": { "description": "Inscrição não localizada. Mensagem: `[BadRequest] - State Inscription não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/simples-cred": { "post": { "operationId": "companySimplesCredPost", "tags": [ "Minha Empresa" ], "summary": "Cadastra créditos do Simples Nacional para um período", "description": "Cria um registro de crédito do Simples Nacional para um mês/ano (`MonthYear`). O sistema converte a data para o primeiro dia do mês (`MonthYear`) e último dia do mês (`MonthYearTo`) automaticamente. Um período só pode ter um registro — duplicidade é bloqueada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySimplesCredCreate" } } }, "description": "Dados do crédito do Simples Nacional a registrar para um período (mês/ano)." }, "responses": { "200": { "description": "Crédito cadastrado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Company não existe`\n- `Já existe configuração para este periodo`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/simples-cred/{idcompanysimplescred}": { "parameters": [ { "name": "idcompanysimplescred", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do crédito do Simples." } ], "put": { "operationId": "companySimplesCredPut", "tags": [ "Minha Empresa" ], "summary": "Atualiza créditos do Simples Nacional", "description": "Atualização total — todos os campos do corpo são gravados. Mesma regra de unicidade por período do `POST`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySimplesCredCreate" } } }, "description": "Atualização total do crédito do Simples Nacional — todos os campos do corpo são gravados." }, "responses": { "200": { "description": "Crédito atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `IDCompanySimplesCred não existe`\n- `Já existe configuração para este periodo`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "companySimplesCredDelete", "tags": [ "Minha Empresa" ], "summary": "Remove um crédito do Simples Nacional", "description": "Apaga fisicamente o registro de crédito. A resposta é o detalhe atualizado da empresa.", "responses": { "200": { "description": "Crédito removido.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDetail" }, "maxItems": 1 } } } }, "400": { "description": "Crédito não localizado. Mensagem: `[BadRequest] - IDCompanySimplesCred não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/certificate": { "post": { "operationId": "companyCertificatePost", "tags": [ "Minha Empresa" ], "summary": "Importa o certificado digital da empresa", "description": "Importa um arquivo de certificado digital A1 (`.pfx`) com a senha informada. O arquivo é enviado como `multipart/form-data` no campo `certificado` e a senha vai na query `Password`. O sistema valida o certificado, confere que o CNPJ do certificado bate com o da empresa (8 primeiros dígitos), extrai a data de validade (`CertificadoBestBeforeDate`) e o emissor (`CertificadoIssuer1`/`CertificadoIssuer2`) e o armazena de forma segura para uso na assinatura de notas fiscais (NFe/NFCe/NFSe/CTe).\n\n**Erros possíveis:** `O arquivo não esta no formato .pfx`; `Não foi possivel ler o certificado, verificar senha`; `Certificado inválido: não foi possível extrair o CNPJ do certificado`; `CNPJ do certificado () diferente do CNPJ da empresa ()`.", "responses": { "200": { "description": "Certificado importado." }, "400": { "description": "Erros de validação do certificado (prefixo `[BadRequest]`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/report": { "get": { "operationId": "companyReportList", "tags": [ "Relatórios Customizados" ], "summary": "Lista o catálogo de relatórios disponíveis para a empresa", "description": "Retorna o **catálogo de relatórios** que a empresa autenticada tem habilitados — agrupados por categoria (`TypeCompanyReportGroup`: Vendas, Financeiro, Fiscal, Estoque, WMS, TMS, Anúncios, Integração, Customizado, etc.) e detalhando para cada relatório os **filtros aceitos** (`TypeCompanyReportQuery`).\n\nCada filtro tem um `Type` (RangerPicker para intervalo de datas, InputGroup para par de campos, Select para lista, Input para texto livre), um `Label` (legenda exibida) e um `Param` (lista de nomes de query string que o front envia ao gerar o relatório). Para o relatório de id `85` (Estoque por integração), o sistema injeta dinamicamente os parâmetros `IDTypeCompanyIntegration` e `ListSalesChannel` no filtro de Integração.", "responses": { "200": { "description": "Catálogo de relatórios (array de grupos, cada um com `TypeCompanyReport[]` e seus `TypeCompanyReportQuery[]`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyReportGroup" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/report": { "get": { "operationId": "userReportList", "tags": [ "Cadastro de Usuários" ], "summary": "Lista os relatórios já gerados pelo usuário", "description": "Retorna o histórico de relatórios que **o usuário autenticado** gerou — ordenado pela data de criação descendente. Cada item traz o tipo de relatório (`TypeCompanyReport`), os filtros usados (`Query`), o status (`Status`: pendente, processando, concluído, erro), comentários, link de download (`Link`, preenchido quando o processamento termina) e a data/hora da geração.", "responses": { "200": { "description": "Histórico de relatórios do usuário.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserReportListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "userReportPost", "tags": [ "Cadastro de Usuários" ], "summary": "Enfileira a geração de um relatório", "description": "Cria um pedido de geração de relatório para o tipo (`IDTypeCompanyReport`) e filtros (`Query`) informados. O processamento é **assíncrono**: o sistema insere o registro em `UserReport` com status pendente, envia a mensagem para a fila assíncrona `reports.fifo` (com `MessageGroupId` igual ao subdomínio da empresa, garantindo serialização por empresa) e devolve a lista atualizada de relatórios do usuário. O processo consome a fila, executa a query, gera o arquivo, sobe para o storage e atualiza `Link` no registro.\n\n**Duplicidade**: o sistema bloqueia se já existe um relatório do **mesmo tipo**, com a **mesma query**, do **mesmo usuário**, ainda **sem `Link`** e com `IDTypeStatusUserReport=1` (pendente), criado nas **últimas 3 horas** — para evitar gerar o mesmo relatório duas vezes em paralelo. Mensagem: `Relatório já esta em processamento, favor aguardar`.\n\nQuando `SendEmail=1`, o processo envia o link do arquivo para o e-mail do usuário ao terminar a geração.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserReportCreate" } } }, "description": "Pedido de geração de relatório. `IDTypeCompanyReport` e `Query` (string `chave1=valor1&chave2=valor2` com os filtros do relatório) são obrigatórios. `SendEmail=1` faz o processo enviar o link por email ao usuário quando terminar. Bloqueado por duplicidade: se já existe um relatório do mesmo tipo, mesma `Query`, mesmo usuário, sem `Link` e criado nas últimas 3 horas." }, "responses": { "200": { "description": "Relatório enfileirado. Retorna o histórico atualizado de relatórios do usuário (mesmo formato de `GET /user/report`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserReportListItem" } } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Empresa não existe`\n- `Relatório já esta em processamento, favor aguardar`\n- `Problema ao gerar relatório`\n- `Query deve ser uma querystring (ex: DateFrom=2026-06-23&DateTo=2026-06-23), recebido JSON: `", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/{iduser}/comission": { "parameters": [ { "name": "iduser", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do usuário (vendedor) ao qual a comissão será vinculada." } ], "post": { "operationId": "userComissionPost", "tags": [ "Cadastro de Usuários" ], "summary": "Adiciona uma regra de comissão para o vendedor", "description": "Cria uma regra de comissão (`SalesmanComission`) vinculada ao usuário. A regra define a vigência (`DateFrom`/`DateTo`), o percentual de comissão (`ComissionPercent`) e o limite máximo de desconto (`DiscountPercentLimit`) — vendas com desconto **acima do limite** não pagam essa comissão. Quando `IDCategory` é informado, a regra **só vale** para vendas de SKUs daquela categoria (permite ter percentuais diferentes por categoria de produto).\n\nA cada criação, o sistema também grava um log da operação em `UserLog`. A resposta é o detalhe completo do usuário atualizado, com a nova regra já em `SalesmanComission[]`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserComissionCreate" } } }, "description": "Regra de comissão a cadastrar para o vendedor. `DateFrom`, `DateTo` e `ComissionPercent` são obrigatórios. `DiscountPercentLimit` limita o desconto da venda que ainda paga essa regra. `IDCategory` (opcional) restringe a regra a vendas de SKUs da categoria informada." }, "responses": { "200": { "description": "Regra de comissão criada. Retorna o detalhe do usuário com a lista atualizada de regras.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserComissionDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Usuário não encontrado`\n- `Categoria não existe` (quando `IDCategory` aponta para categoria de outra empresa ou inexistente)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/{iduser}/comission/{idsalesmancomission}": { "parameters": [ { "name": "iduser", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do usuário (vendedor)." }, { "name": "idsalesmancomission", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da regra de comissão." } ], "put": { "operationId": "userComissionPut", "tags": [ "Cadastro de Usuários" ], "summary": "Atualiza uma regra de comissão", "description": "Atualização total da regra — todos os campos do corpo são gravados. Quando `IDCategory` é informado, é validado contra `StockKeepingUnitCategory` da empresa autenticada. A operação também grava um log em `UserLog` e devolve o detalhe atualizado do usuário.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserComissionCreate" } } }, "description": "Atualização total da regra de comissão — todos os campos do corpo substituem o valor anterior. Mesmos campos do POST." }, "responses": { "200": { "description": "Regra atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserComissionDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Comissão vendedor não encontrada`\n- `Categoria não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "userComissionDelete", "tags": [ "Cadastro de Usuários" ], "summary": "Remove uma regra de comissão", "description": "Apaga fisicamente a regra de comissão. Grava log em `UserLog` com o id da regra removida. A resposta é o detalhe atualizado do usuário.", "responses": { "200": { "description": "Regra removida.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserComissionDetail" }, "maxItems": 1 } } } }, "400": { "description": "Regra não encontrada para o usuário/empresa. Mensagem: `[BadRequest] - Comissão vendedor não encontrada`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/store-front/cashier/history": { "get": { "operationId": "storeFrontCashierHistoryList", "tags": [ "Frente de Caixa" ], "summary": "Lista sessões de caixa do PDV", "description": "Lista as sessões de caixa (`StoreFrontCashier`) — cada item é uma abertura/fechamento de caixa de uma das contas bancárias do tipo \"caixa do PDV\" da empresa. A listagem traz o operador (`Login`/`UserName`), o caixa (`Bank` da conta), as datas e os comentários de abertura/fechamento.\n\nO escopo é multi-empresa: respeita o contexto `accountname`/`idcompanylist` do token. Quando `accountname=[\"all\"]`, lista de todas as empresas do grupo; caso contrário, filtra pelas empresas habilitadas no token.\n\nOrdenação: data de abertura **decrescente**.", "parameters": [ { "name": "IDBankAccount", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por conta bancária (caixa) específica." }, { "name": "RecordUserCreated", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo usuário que abriu o caixa." }, { "name": "IDStoreFrontCashier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por identificador único da sessão de caixa." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra apenas sessões cujo banco usa este faturador." }, { "name": "DateFromOpen", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial (inclusive) da abertura do caixa." }, { "name": "DateToOpen", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final (inclusive — fim do dia) da abertura do caixa." } ], "responses": { "200": { "description": "Lista de sessões de caixa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreFrontCashierHistoryListItem" } } } } }, "400": { "description": "Configuração de empresa inválida (prefixo `[BadRequest]`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/store-front/cashier/history/{idstorefrontcashier}": { "parameters": [ { "name": "idstorefrontcashier", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da sessão de caixa do PDV." } ], "get": { "operationId": "storeFrontCashierHistoryGet", "tags": [ "Frente de Caixa" ], "summary": "Detalhe (extrato) de uma sessão de caixa", "description": "Retorna o **extrato completo** de uma sessão de caixa, com 3 listas agregadas:\n\n- **`OrderList[]`** — pedidos atendidos no caixa, **uma linha por recebimento** (`AccountsPayableReceivable`), com o tipo de pagamento, NSU, TID, parcelas, vendedor, cliente e o status do pedido (`IDStatusOrder` = `90` indica venda cancelada). Vem do join de `StoreFrontCashierOrder` × `AccountsPayableReceivable`.\n- **`TransactionList[]`** — lançamentos bancários (`AccountsPayableReceivableBankStatement`) gerados na sessão: sangrias, suprimentos, recebimentos baixados etc. `IDTypeAccount = 1` é débito (a tela inverte o sinal do valor) e demais valores são crédito.\n- **`PaymentSummary[]`** — soma dos recebimentos **válidos** (pedidos não cancelados) por tipo de pagamento. A lista começa com os tipos de pagamento habilitados no PDV (`EnableFrenteCaixa=1`) zerados e é incrementada conforme `OrderList` é processada.\n\nAlém disso, traz os totais agregados `TotalOrderValue` (soma de `OrderList`) e `TotalTransactionValue` (soma de `TransactionList`).", "responses": { "200": { "description": "Extrato da sessão (array com 1 item).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreFrontCashierHistoryDetail" }, "maxItems": 1 } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/store-front/cashier/history/{idstorefrontcashier}/adjust/{idaccountpayablereceivable}": { "parameters": [ { "name": "idstorefrontcashier", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da sessão de caixa do PDV." }, { "name": "idaccountpayablereceivable", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do recebimento (`AccountsPayableReceivable`) a ajustar." } ], "put": { "operationId": "storeFrontCashierHistoryPut", "tags": [ "Frente de Caixa" ], "summary": "Ajusta um recebimento da sessão de caixa", "description": "Corrige os dados de um recebimento gerado dentro de uma sessão de caixa do PDV. Permite trocar o **tipo de pagamento** (`IDTypePayment`), informar/atualizar **TID** e **NSU** da maquininha e alterar a **quantidade de parcelas** (`InstallmentTotal`).\n\nRegras importantes:\n\n- O recebimento precisa estar com status conciliação **ainda aberto** — só são aceitos `IDStatusAccountPayableReceivable` ∈ `{0, 1, 6}`. Recebimentos já conciliados/baixados retornam `[BadRequest] - Recebimento já foi conciliado e não pode ser editado`.\n- `IDTypePayment` precisa pertencer à mesma empresa do recebimento (`IDCompany`).\n- O update afeta **todas as parcelas** do mesmo agrupamento `(IDOrder, IDTypePayment, IDTypeAccount, NSU, TID)` — quando há parcelamento, todas as linhas relacionadas recebem a mesma alteração.\n- Quando `InstallmentTotal` muda, o sistema **recria o parcelamento** com a nova quantidade de parcelas (apaga os recebimentos antigos e gera os novos com o valor recalculado). Quando `InstallmentTotal` permanece igual, apenas os campos enviados são gravados.\n- Cada alteração de campo (`IDTypePayment`/`TID`/`NSU`) é registrada em `AccountsPayableReceivableLog` no formato `DE: PARA: `.\n\nNa frente, o botão de edição exige a privilégio `PrivilegePointOfSaleEditTransaction` — quem não tem precisa autorizar via senha de gerente (`POST /user/{iduser}/verify`).\n\nA resposta é o extrato atualizado da sessão (mesma forma do `GET /store-front/cashier/history/{idstorefrontcashier}`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFrontCashierHistoryAdjust" } } }, "description": "Edita os campos do recebimento (`AccountsPayableReceivable`) feito no caixa: pode trocar a forma de pagamento, TID, NSU e a quantidade de parcelas. Quando `InstallmentTotal` é diferente do atual, o sistema apaga o agrupamento `(IDOrder, IDTypePayment, NSU, TID)` e recria o parcelamento com o valor total dividido nas novas parcelas. Cada alteração efetiva é registrada em `AccountsPayableReceivableLog`. A operação só é aceita enquanto nenhuma das parcelas tiver sido conciliada (`IDStatusAccountPayableReceivable` em `0`, `1` ou `6`)." }, "responses": { "200": { "description": "Recebimento ajustado. Retorna o extrato atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreFrontCashierHistoryDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Conta a receber não existe`\n- `Conta a receber não existe (parcelamentos)`\n- `Recebimento já foi conciliado e não pode ser editado`\n- `Tipo pagamento não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`). Inclui falha do processo de retaguarda durante o recálculo do parcelamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/promotion": { "get": { "operationId": "skuPromotionList", "tags": [ "Promoção PDV" ], "summary": "Lista promoções do PDV", "description": "Lista as promoções (`StockKeepingUnitPromotion`) cadastradas para a(s) empresa(s) do contexto. Aceita filtros por **tipo** (`IDTypeSkuPromotion` = 1 Regular, 2 Compre e Ganhe, 3 Desconto Progressivo, 4 Compre Junto), **status** (`IDTypeSkuPromotionStatus` = 0 Excluída, 1 Ativo, 2 Programada, 3 Finalizada, 4 Inativa — default `1,2,3,4`, ou seja, esconde excluídas), **nome** (`StockKeepingUnitPromotionName`, busca parcial) e dois intervalos de datas independentes (sobre `DateFrom` e sobre `DateTo`).\n\nO escopo é multi-empresa: respeita o contexto `accountname`/`idcompanylist` do token. Quando `accountname=[\"all\"]`, lista de todas as empresas do grupo.", "parameters": [ { "name": "IDTypeSkuPromotion", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "description": "Filtra por tipo de promoção." }, { "name": "IDTypeSkuPromotionStatus", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ] }, "default": [ 1, 2, 3, 4 ] }, "description": "Lista CSV de status. Default `1,2,3,4` (oculta `0`=Excluída). Pode ser usado para mostrar só ativas (`1`), só programadas (`2`) etc.", "style": "form", "explode": false }, { "name": "StockKeepingUnitPromotionName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome (busca parcial, case-insensitive)." }, { "name": "DateFromDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Início do intervalo a aplicar sobre o campo `DateFrom` da promoção." }, { "name": "DateFromDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo a aplicar sobre o campo `DateFrom` da promoção (inclusive — fim do dia)." }, { "name": "DateToDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Início do intervalo a aplicar sobre o campo `DateTo` da promoção." }, { "name": "DateToDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo a aplicar sobre o campo `DateTo` da promoção (inclusive — fim do dia)." } ], "responses": { "200": { "description": "Lista de promoções (cabeçalho apenas — sem itens vinculados).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionListItem" } } } } }, "400": { "description": "Configuração de empresa inválida (prefixo `[BadRequest]`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuPromotionPost", "tags": [ "Promoção PDV" ], "summary": "Cria uma promoção", "description": "Cria uma promoção do tipo informado em `IDTypeSkuPromotion`. Os campos exigidos e ignorados variam **por tipo** — o body abaixo descreve o conjunto completo, mas o sistema só usa o que faz sentido para o tipo escolhido e zera o resto.\n\n## Regras por tipo\n\n### Tipo 1 — Regular\nDesconto em **% ou R$** aplicado a todos os produtos ou apenas aos que casam com as **restrições** (`StockKeepingUnitPromotionCategories`, `StockKeepingUnitPromotionBrands`, `StockKeepingUnitPromotionProducts`, `StockKeepingUnitPromotionSkus`).\n- Use **um** entre `PercentualDiscountValue` (fração `0–1`, ex.: `0.10` = 10%) **ou** `NominalDiscountValue` (R$).\n- `MinOrderValue` / `MaxOrderValue` (opcionais): só vale quando o total do pedido cai nesse intervalo.\n- Para cada restrição há um flag de **inclusão/exclusão** (`BrandsIncluded`, `CategoriesIncluded`, `ProductsIncluded`, `SkusIncluded` — default `1` = iguais a; `0` = diferentes de). Quando a lista correspondente é vazia, a restrição **não filtra**.\n\n### Tipo 2 — Compre e Ganhe\nCliente compra `MinimumQuantityBuyTogether` unidades dos itens em `StockKeepingUnitPromotionSkus` e ganha (grátis, valor zero) os itens listados em `StockKeepingUnitPromotionSkusBuyTogether`.\n- `StockKeepingUnitPromotionSkus` **obrigatório** (itens que devem ser comprados).\n- `StockKeepingUnitPromotionSkusBuyTogether` **obrigatório** (itens de brinde).\n- `MinimumQuantityBuyTogether` **obrigatório** e > 0.\n- Campos de desconto/range/restrição são ignorados.\n\n### Tipo 3 — Desconto Progressivo\nQuanto mais unidades, maior o desconto. Cada faixa em `StockKeepingUnitPromotionProgressive` tem `Quantity` (a partir de quantas unidades vale) e `DiscountPercent` **OU** `FixedPrice` (preço unitário fixo).\n- Itens elegíveis: `StockKeepingUnitPromotionSkus` (SKUs) **OU** `StockKeepingUnitPromotionProducts` (produtos pai).\n- `Quantity` precisa ser **único** entre as faixas (não pode ter duas faixas com mesma quantidade).\n- Combine com `ExactlyQuantity=1` (no cabeçalho) para aplicar a faixa apenas quando a quantidade for **múltipla exata** (4, 8, 12... para faixa de 4).\n\n### Tipo 4 — Compre Junto\nDuas listas com descontos separados. Compre `MinimumQuantityBuyTogether` unidades da **lista principal** (`StockKeepingUnitPromotionSkus`) com desconto `PercentualDiscountValue`; ao adicionar itens da **lista complementar** (`StockKeepingUnitPromotionSkusBuyTogether`), eles recebem `PercentualDiscountValueBuyTogether`.\n- Todos os 4 campos são obrigatórios.\n- `PercentualDiscountValue` e `PercentualDiscountValueBuyTogether` em fração `0–1`.\n\n## Flags do cabeçalho (todos os tipos)\n\n- **`Cumulative`** — quando `1`, pode acumular com **outras promoções de tipos diferentes** no mesmo item (regra de prioridade depois do desempate por maior desconto).\n- **`CumulativeManualPrice`** — quando `1`, aplica o desconto mesmo se o item já tem um **preço manual** (preço de venda diferente do preço de lista). Quando `0`, a promoção é descartada se houver desconto manual.\n- **`AllowDifferentItemQuantitySum`** — quando `1`, a `MinimumQuantityBuyTogether` (Compre e Ganhe / Compre Junto) ou a `Quantity` da faixa (Progressivo) considera a **soma de quantidades de SKUs diferentes** que entram na promoção. Quando `0`, só conta o mesmo SKU.\n- **`ExactlyQuantity`** — quando `1` (Progressivo), aplica a faixa só quando a quantidade for múltiplo exato; quando `0`, aplica assim que a quantidade atinge a faixa (com lógica greedy decrescente).\n- **`OnlyRegisteredConsumer`** — quando `1`, a promoção só é aplicada se o pedido tem `IDConsumer` informado (cliente cadastrado).\n- **`DateFrom`/`DateTo`** — vigência. Para promoção **\"para sempre\"**, envie `DateFrom = \"1900-01-01\"` e `DateTo = \"4000-01-01\"`.\n\n## Vínculos opcionais\n\n- **`StockKeepingUnitPromotionTypeOrders`** — lista de tipos de pedido (`Status=1`) em que a promoção vale. Vazio = vale para todos.\n- **`StockKeepingUnitPromotionSalesPolicies`** — lista de políticas comerciais aceitas. Vazio = vale para todas.\n\n## Detalhes\n\n- A nova promoção passa a valer imediatamente para a empresa (ordem de aplicação: tipo → maior % → maior R$).\n- O nome (`StockKeepingUnitPromotionName`) é gravado **sem acentos** (normalização NFD).\n\nA resposta é o detalhe completo da promoção criada (mesmo formato de `GET /sku/promotion/{id}`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuPromotionCreate" } } }, "description": "Dados da promoção a cadastrar. `IDTypeSkuPromotion` define o tipo: `1` Regular (desconto direto), `2` Compre e ganhe, `3` Desconto progressivo, `4` Compre junto. Para tipo `1` informe as listas de marcas, categorias, produtos ou SKUs participantes; para tipo `4` use `StockKeepingUnitPromotionSkusBuyTogether[]` com os SKUs do grupo. `DateFrom` precisa ser menor que `DateTo`." }, "responses": { "200": { "description": "Promoção criada. Retorna o detalhe (array com 1 item).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Empresa não existe`\n- `Tipo de promoção não existe`\n- `Promoção sem regra de cadastro` (tipo diferente de 1/2/3/4)\n- `Data de precisa ser maior que data até`\n- `Tipo pedido(s) não localizada(s): `\n- `Politica(s) comercial não localizada(s): `\n- `Marca(s)/Categoria(s)/Produtos(s)/Sku(s) não localizada(s): ` (valida que pertencem à empresa e estão com status ativo)\n- `Quantidade mínima é obrigatória na promoção compre e ganhe`\n- `Quantidade mínima é obrigatória na promoção compre junto`\n- `Percentual desconto lista um é obrigatória` (Compre Junto)\n- `Percentual desconto lista dois é obrigatória` (Compre Junto)\n- `Obrigatório informar itens` / `Obrigatório informar itens brinde` / `Obrigatório informar itens lista dois`\n- `Obrigatório informar quantidade e % desconto` (Progressivo sem faixas)\n- `Campo quantidade precisa ser único` (Progressivo com faixas duplicadas)\n- `Erro ao criar promoção`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/promotion/{idstockkeepingunitpromotion}": { "parameters": [ { "name": "idstockkeepingunitpromotion", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da promoção." } ], "get": { "operationId": "skuPromotionGet", "tags": [ "Promoção PDV" ], "summary": "Detalhe completo de uma promoção", "description": "Retorna a promoção com **todas as listas vinculadas** resolvidas: marcas (`StockKeepingUnitPromotionBrands`), categorias (`StockKeepingUnitPromotionCategories`), produtos (`StockKeepingUnitPromotionProducts`), SKUs (`StockKeepingUnitPromotionSkus`), tipos de pedido (`StockKeepingUnitPromotionTypeOrders`), políticas comerciais (`StockKeepingUnitPromotionSalesPolicies`), faixas progressivas (`StockKeepingUnitPromotionProgressive`) e SKUs de brinde/lista complementar (`StockKeepingUnitPromotionSkusBuyTogether` — com URL da imagem principal). Esse é o corpo usado pelo modal de edição da tela.", "responses": { "200": { "description": "Detalhe da promoção (array com 1 item ou vazio se não existe).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionDetail" }, "maxItems": 1 } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "skuPromotionPut", "tags": [ "Promoção PDV" ], "summary": "Atualiza uma promoção", "description": "Atualiza parcialmente o cabeçalho da promoção e **substitui** as listas vinculadas. O **tipo (`IDTypeSkuPromotion`) não pode ser alterado** — vem da promoção existente; o sistema respeita as regras do tipo original e zera campos que não fazem sentido (ex.: para tipo 1 zera `MinimumQuantityBuyTogether` e `PercentualDiscountValueBuyTogether`).\n\nValida o mesmo conjunto de regras do `POST` (vigência, existência de marcas/categorias/produtos/SKUs na empresa, faixas únicas no Progressivo, etc.).\n\n**Sincronização das listas** (diff inteligente): quando você envia uma lista (qualquer um dos campos `StockKeepingUnitPromotionBrands`, `Categories`, `Products`, `Skus`, `TypeOrders`, `SalesPolicies`, `SkusBuyTogether`, `Progressive`), o sistema:\n1. Lê os vínculos atuais.\n2. **Insere** os itens da lista enviada que ainda não existem.\n3. **Apaga** os itens existentes que não estão na lista enviada.\n4. Mantém o resto inalterado.\n\nEnviar uma **lista vazia** (`[]`) apaga todos os vínculos daquele tipo. Para **não tocar** numa lista, **omita** o campo do body.\n\nAs alterações passam a valer imediatamente. Trava `PercentualDiscountValue > 1` com `[BadRequest] - Desconto percentual não pode ser maior que 100%`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuPromotionUpdate" } } }, "description": "Atualização parcial da promoção. Todos os campos são opcionais; apenas os enviados são aplicados." }, "responses": { "200": { "description": "Promoção atualizada. Retorna o detalhe (mesmo formato do GET).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Promoção não localizada`\n- `Desconto percentual não pode ser maior que 100%`\n- `Data de precisa ser maior que data até`\n- demais erros do POST (faixas duplicadas, vínculos inexistentes, obrigatórios faltando para o tipo)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuPromotionDelete", "tags": [ "Promoção PDV" ], "summary": "Exclui uma promoção", "description": "Exclusão **híbrida** — depende de a promoção já ter sido usada em pedidos:\n\n- Se **não há** promoções vinculadas a pedidos vinculados → **exclusão física** do registro.\n- Se já foi usada → **exclusão lógica** (`IDTypeSkuPromotionStatus = 0`, status \"Excluída\"). Isso preserva o histórico nos pedidos antigos.\n\nDispara a regravação interno (excluídas e inativas ficam de fora ).", "responses": { "200": { "description": "Promoção excluída (resposta: string `sucesso`).", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Promoção não localizada`\n- `Erro ao excluir promoção`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/promotion/sku/{idsku}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do SKU (`IDSku`)." } ], "get": { "operationId": "skuPromotionSkuGet", "tags": [ "Promoção PDV" ], "summary": "Lista promoções aplicáveis a um SKU", "description": "Retorna **todas as promoções vigentes** que se aplicam ao SKU informado — usado pela tela do produto para mostrar o selo de promoção. Avalia: vigência (data atual ∈ `[DateFrom, DateTo]`), restrição por marca, categoria, produto e SKU (respeitando as flags `*Included` = `1` para igualdade ou `0` para diferença). Itens listados em `StockKeepingUnitPromotionSkusBuyTogether` (lista de brindes) também entram (`IncludeSkuTogether=1`).\n\nSem token de empresa válido, retorna `[NotFound] - Sku não existe`.", "responses": { "200": { "description": "Promoções aplicáveis ao SKU.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionSkuItem" } } } } }, "404": { "description": "Sku não encontrado: `[NotFound] - Sku não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/promotion/order/validate": { "post": { "operationId": "skuPromotionOrderValidateGet", "tags": [ "Promoção PDV" ], "summary": "Aplica promoções ao carrinho do PDV", "description": "Recebe a lista de itens em montagem no PDV e **aplica todas as promoções vigentes** retornando o carrinho com os preços recalculados (`PriceSelling`, `PriceSellingTotal`, `ValueDiscount`, `ValueDiscountTotal`, `OriginalPriceSelling`, `PromotionDiscountPercent`) e a lista de promoções usadas (`IDStockKeepingUnitPromotion`/`StockKeepingUnitPromotionName`) por item.\n\n## Regras de elegibilidade (por promoção × item)\n\nUma promoção é aplicada quando passa em **todos** os testes:\n\n1. **Vigência** — data/hora atual ∈ `[DateFrom, DateTo]`.\n2. **Restrição de marca** — quando `BrandsIncluded=1`, a marca do SKU está na lista; quando `BrandsIncluded=0`, **não** está.\n3. **Restrição de categoria** — mesma lógica de `CategoriesIncluded`.\n4. **Restrição de produto** — mesma lógica de `ProductsIncluded` (compara `IDProduct` da variação).\n5. **Restrição de SKU** — mesma lógica de `SkusIncluded`.\n6. **Tipo de pedido** — quando `StockKeepingUnitPromotionTypeOrders` não vazio, `IDOrderType` precisa estar na lista.\n7. **Política comercial** — quando `StockKeepingUnitPromotionSalesPolicies` não vazio, `IDCompanySalesPolicy` do item precisa estar na lista.\n8. **Acúmulo com preço manual** — quando `CumulativeManualPrice=0` e `PriceListTotal ≠ PriceSellingTotal` (preço foi alterado manualmente), descarta.\n9. **Cliente cadastrado** — quando `OnlyRegisteredConsumer=1`, `IDConsumer` precisa estar informado.\n10. **Faixa de valor do pedido** (Regular) — `totalvalue ∈ [MinOrderValue, MaxOrderValue]`.\n\n## Cálculo do preço\n\n- **Regular**: aplica `PercentualDiscountValue` (multiplica `PriceSellingTotal × (1 - %)`) ou `NominalDiscountValue × Quantity` (com piso em 0).\n- **Compre e Ganhe**: se `Quantity ≥ MinimumQuantityBuyTogether`, cada item em `SkusBuyTogether` é adicionado/atualizado no carrinho com `PriceSellingTotal=0` (brinde).\n- **Desconto Progressivo (ExactlyQuantity=0)**: percorre as faixas (ordenadas desc por `Quantity`) e aplica a primeira em que `progressive.Quantity ≤ Quantity` ou `≤ GroupedQuantity` (com `AllowDifferentItemQuantitySum=1`).\n- **Desconto Progressivo (ExactlyQuantity=1)**: lógica **greedy** — para cada faixa (desc por `Quantity`), encaixa múltiplos exatos (`floor(remaining / Quantity)`), gera um objeto de carrinho por faixa aplicada, e o resíduo vira um objeto **sem desconto**.\n- **Compre Junto**: se `Quantity ≥ MinimumQuantityBuyTogether` da lista principal e existe item da lista complementar no carrinho, aplica `PercentualDiscountValue` no principal e `PercentualDiscountValueBuyTogether` no complementar.\n\n## Desempate entre promoções\n\nQuando o mesmo item bate em **várias promoções**:\n1. Ordena por **maior desconto** (`PreValueDiscountTotal`).\n2. Mantém a primeira; mantém também subsequentes desde que **mesmo tipo + Cumulative=1** (acumula promoções do mesmo tipo cumulativas) **ou tipo diferente** (deixa o resto da lógica decidir).\n\n## `StoreFrontCashierOrderTemp`\n\nO endpoint também **persiste** o estado do carrinho em `StoreFrontCashierOrderTemp` (vinculado ao caixa aberto via `IDStoreFrontCashier`/`IDBankAccount`). Se você passar `IDStoreFrontCashierOrderTemp`, atualiza esse registro; senão insere um novo e devolve o `IDStoreFrontCashierOrderTemp` gerado no corpo da resposta. Isso é o que permite o PDV retomar o pedido em outro terminal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuPromotionOrderValidateBody" } } }, "description": "Pedido a validar contra as promoções vigentes da empresa. Informe a lista de itens (`Items[]`) com SKU, quantidade e preço, o tipo de pedido (`IDOrderType`), opcionalmente o consumidor (`IDConsumer`, exigido por promoções `OnlyRegisteredConsumer=1`) e o caixa (`IDStoreFrontCashier`). O retorno traz os descontos e ajustes calculados para cada item." }, "responses": { "200": { "description": "Carrinho com os preços e promoções recalculados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuPromotionOrderValidateResponse" } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Pedido não tem itens` (lista vazia)\n- `Item não encontrado` (SKU informado não existe ou não é da empresa)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/promotion/type": { "get": { "operationId": "typeSkuPromotionList", "tags": [ "Tipos — SKU" ], "summary": "Lista os tipos de promoção do PDV", "description": "Lista de valores fixos do sistema (`TypeSkuPromotion`) usados no seletor de tipo do modal: `1`=Regular, `2`=Compre e ganhe, `3`=Desconto progressivo, `4`=Compre junto.", "responses": { "200": { "description": "Tipos de promoção.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeSkuPromotion": { "type": "string", "description": "Identificador do tipo de promoção." }, "TypeSkuPromotion": { "type": "string", "description": "Nome do tipo de promoção (`Regular`, `Compre e Ganhe`, `Desconto Progressivo`, `Compre Junto`)." } } } } } } } } } }, "/type/sku/promotion/status": { "get": { "operationId": "typeSkuPromotionStatusList", "tags": [ "Tipos — SKU" ], "summary": "Lista os status possíveis de promoção do PDV", "description": "Lista de valores fixos (`TypeSkuPromotionStatus`): `0`=Excluída, `1`=Ativo, `2`=Programada, `3`=Finalizada, `4`=Inativa.", "responses": { "200": { "description": "Status possíveis.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeSkuPromotionStatus": { "type": "string", "description": "Identificador do status da promoção." }, "TypeSkuPromotionStatus": { "type": "string", "description": "Descrição do status (ex.: `Ativa`, `Inativa`, `Excluída`)." } } } } } } } } } }, "/store-front/payment": { "get": { "operationId": "storeFrontPaymentList", "tags": [ "Pagamento PDV" ], "summary": "Lista transações TEF/Pix do PDV", "description": "Lista as transações de pagamento feitas no PDV — tanto via maquininha (PayGo/ControlPay) quanto via Pix (Stark Bank, Pagar.me). Cada item traz o valor, o status, o tipo de pagamento, o adquirente, o último número do cartão (4 dígitos), TID, código de autorização, e o ZPL dos comprovantes (`Receipt` para via estabelecimento, `ReceiptBuyer` para via cliente — ambos vêm com `\\r\\n VA` apendado para impressão direta).\n\nA listagem é multi-empresa: respeita `accountname`/`idcompanylist` do token. Quando `accountname=[\"all\"]`, lista de todas as empresas do grupo. Limite de **2000 itens por página** — use `Page` (zero-indexed) para paginar (o deslocamento é `Page × 2000`).\n\n**Janela padrão de 30 dias:** quando a chamada não traz nenhum filtro seletivo — identificador da transação `IDStoreFrontCashierPayment`, `TID`, código de autorização `AuthId`, terminal `TefTerminal`, início do período de criação `DateFrom` ou início do período de cancelamento `DateCancelFrom` — a listagem devolve apenas as transações dos últimos 30 dias, contadas pela data de criação `RecordTimestamp`. Filtrar somente por status `IDTypeStatusStoreFrontCashierPayment`, por caixa `IDBankAccount`, por faturador `IDCompanyInvoice`, por `DateTo` ou por `DateCancelTo` **não** amplia essa janela; para varrer o histórico completo, informe `DateFrom` (ou outro dos filtros seletivos).\n\nCada item já vem com o `IDOrder` do pedido associado resolvido (ligação feita pelo `IDOrderIntention`, o UUID que conecta a tentativa de pagamento ao pedido fechado).\n\nOrdenação: `IDStoreFrontCashierPayment` decrescente (mais recentes primeiro).", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Página zero-indexed. Offset = `Page × 2000`." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra apenas transações cuja conta bancária tem este faturador." }, { "name": "IDBankAccount", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por caixa/maquininha (conta bancária do PDV)." }, { "name": "TefTerminal", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código do terminal TEF (ID PayGo)." }, { "name": "TID", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo TID retornado pela maquininha." }, { "name": "AuthId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código de autorização do adquirente." }, { "name": "IDTypeStatusStoreFrontCashierPayment", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "description": "Filtra por status (1=Pendente, 2=Em pagamento, 3=Creditado, 4=Expirado, 5=Cancelamento iniciado, 6=Em cancelamento, 7=Cancelado, 8=Pagamento recusado)." }, { "name": "IDStoreFrontCashierPayment", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por identificador único da transação." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Início do intervalo da data de criação da transação." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo da data de criação da transação (inclusive — fim do dia)." }, { "name": "DateCancelFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Início do intervalo da data de cancelamento." }, { "name": "DateCancelTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo da data de cancelamento (inclusive — fim do dia)." } ], "responses": { "200": { "description": "Lista de transações.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreFrontPaymentListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/store-front/cashier/{idbankaccount}/payment": { "parameters": [ { "name": "idbankaccount", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Conta bancária do caixa do PDV (`IDBankAccount`) — define qual integração (PayGo/StarkBank/Pagar.me) será usada e em que terminal a venda é direcionada." } ], "post": { "operationId": "storeFrontPaymentPost", "tags": [ "Frente de Caixa" ], "summary": "Inicia uma cobrança TEF ou Pix", "description": "Cria o registro `StoreFrontCashierPayment` (status inicial **Pendente**) e dispara a cobrança no provedor configurado pela integração da conta bancária (`IDCompanyIntegration` → `IDTypeCompanyIntegration`).\n\n## Direcionamento por integração\n\n- **PayGo / ControlPay** (`IDTypeCompanyIntegration = 17`): manda a venda para a maquininha (TEF) com `formaPagamentoId` derivado da categoria do tipo de pagamento (`22`=crédito → `21`, `23`=débito → `22`, `24`=Pix → `24`). Exige `TefTerminal` preenchido e `Token` da integração configurado. Em sucesso de conexão, status vira **Em pagamento** (`2`). Erro de conexão em 15s vira status **Expirado** (`4`) com mensagem `Erro ao conectar ao terminal TEF...`.\n- **StarkBank** (`131`): gera um QR Code Pix dinâmico (`CreateDynamicBrcode`) com 3600s de expiração. Retorna `PixCopiaCola` (string copia-cola) e `QrCodeImageUrl`. Status vira **Em pagamento**.\n- **Pagar.me** (`13`): só suporta **Pix** (`Category = 24`). Outras categorias dão `Integração Pagarme no PDV suporta apenas Pix`. Retorna `PixCopiaCola`, `QrCodeImageUrl` e o `TID`.\n\n## Categorias de tipo de pagamento aceitas\n\nApenas tipos de pagamento com `Category` ∈ `{22 crédito, 23 débito, 24 Pix}`. Outros valores retornam `Tipo de pagamento inválido (categoria recebida: ), permitido apenas crédito, débito e Pix`.\n\n## IDOrderIntention\n\nQuando o cliente envia `IDOrderIntention` (UUID), o sistema usa esse valor para ligar a tentativa ao pedido. Quando omite, o sistema gera um UUID novo e devolve no body. Esse UUID é o que casa com `IDOrderIntention` (ligação tentativa → pedido fechado).\n\nA partir daí, o cliente deve fazer **polling** via `GET /store-front/cashier/{idbankaccount}/payment/{idstorefrontcashierpayment}` até obter `Success=1` ou um status final.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFrontPaymentPostBody" } } }, "description": "Inicia uma cobrança no PDV. `IDTypePayment` precisa pertencer à empresa e ter `Category` em `22` (crédito), `23` (débito) ou `24` (Pix). A integração da cobrança é resolvida automaticamente a partir da conta bancária: Pix usa `IDCompanyIntegrationPix`; crédito e débito usam `IDCompanyIntegration`. O comportamento varia por integração — **PayGo (TEF)**: dispara venda no terminal físico via API ControlPay (`/Venda/Vender`), exige `TefTerminal` e o token da integração; **StarkBank**: gera BR Code Pix dinâmico (default 1h de expiração); **Pagar.me**: gera cobrança Pix (suporta apenas Pix neste fluxo). `IDOrderIntention` é o UUID que liga a cobrança ao pedido fechado pelo PDV; quando omitido o sistema gera um novo." }, "responses": { "200": { "description": "Cobrança iniciada (status retornado = `2` Em pagamento). PayGo (TEF) retorna `IDStoreFrontCashierPayment`, `IDOrderIntention`, `IDTypeStatusStoreFrontCashierPayment` e `ExternalId`. Pix (StarkBank/Pagar.me) retorna ainda `PixCopiaCola`, `QrCodeImageUrl` e `QrcodeExpirationTimeInSeconds`; Pagar.me inclui também o `TID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFrontPaymentPostResponse" } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Necessário enviar dados para cobrança`\n- `Precisa enviar o valor, conta bancária e código do tipo de pagamento`\n- `Conta bancária não localizada`\n- `Conta bancária não tem integração selecionada`\n- `Conta bancária não tem integração configurada`\n- `Tipo pagamento não encontrado`\n- `Tipo de pagamento inválido (categoria recebida: ), permitido apenas crédito, débito e Pix`\n- `Conta bancária não tem terminal TEF preenchido` (PayGo)\n- `Token integração TEF não esta preenchido` (PayGo)\n- `Erro ao conectar ao terminal TEF. Verificar conexão da máquininha (PIN PAD) com computador, internet e aplicativo paygo` (PayGo, status 15)\n- `Integração Pagarme no PDV suporta apenas Pix` (Pagar.me, categoria ≠ 24)\n- `Integração não suportada para este fluxo de pagamento`\n- `` (quando o provedor recusa a cobrança)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno inesperado (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/store-front/cashier/{idbankaccount}/payment/{idstorefrontcashierpayment}": { "parameters": [ { "name": "idbankaccount", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Conta bancária do caixa do PDV." }, { "name": "idstorefrontcashierpayment", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da transação criada em `POST /store-front/cashier/{idbankaccount}/payment`." } ], "get": { "operationId": "storeFrontPaymentGet", "tags": [ "Frente de Caixa" ], "summary": "Consulta status de uma transação TEF/Pix (polling)", "description": "Faz **polling síncrono no adquirente** dentro de um loop limitado a **60 tentativas** (1s entre elas) — quando esgota, retorna **HTTP 504** sem corpo. Por isso a chamada deve ser feita com **timeout client-side ≥ 60s** (a frente usa 180s).\n\n## Por integração\n\n- **PayGo / ControlPay**: consulta `IntencaoVenda/GetByFiltros` a cada segundo. Extrai do retorno o último `pagamentosExternos` (sempre o mais recente) e popula:\n - `IDTypeStatusStoreFrontCashierPayment` ← mapeamento de `intencaoVendaStatus.id` via `ExternalId`.\n - `TID` ← `nsuTid`, `AuthId` ← `autorizacao`, `Acquirer` ← `adquirente`, `PaymentSystemName` ← `bandeira` (Visa, Master etc.).\n - `ReturnCode` ← `codigoRespostaAdquirente`, `ReturnMessage` ← `mensagemRespostaAdquirente`.\n - `Receipt` (via estabelecimento) e `ReceiptBuyer` (via cliente) ← extraídos do `respostaAdquirente` (texto ZPL bruto entre `PWINFO_RCPTMERCH =` e `PWINFO_RCPTCHOLDER`/etc).\n - `CardLastDigits` ← últimos 4 dígitos do PAN extraído da string `CARTAO:` ou `PWINFO_CARDPARCPAN`.\n- **StarkBank**: chama `CheckPaymentByTag(ExternalId)` a cada segundo. Quando `paid === true`, status vira **Creditado** (`3`) com `Success=1`. Retorno inclui `PixCopiaCola`, `QrCodeImageUrl`, `QrcodeExpirationTimeInSeconds`.\n- **Pagar.me**: chama `GetPix(IDCompanyIntegration, ExternalId)` a cada segundo. `IDStatusBankSlip=2` → **Creditado**; `IDStatusBankSlip=4` → **Cancelado**; demais → continua **Em pagamento**.\n\n## Sucesso vs. falha\n\nO endpoint retorna **`Success`** no corpo para o cliente decidir o que fazer:\n\n- `Success=1` → transação finalizada com sucesso (Creditado ou Cancelado bem sucedido).\n- `Success=0` → falha (Expirado, Pagamento recusado, ou caso especial PayGo `codigoRespostaExecTransac=-2596` ou `idPagamento` vazio com status `15`).\n\nAo final do polling (sucesso ou falha definitiva), o sistema grava a atualização final em `StoreFrontCashierPayment` via `StoreFrontPaymentUpdate`. Se o loop esgotar sem decisão, retorna HTTP 504 e o cliente deve fazer nova chamada.", "responses": { "200": { "description": "Status retornado. Sempre inclui o status (`IDTypeStatusStoreFrontCashierPayment` + `TypeStatusStoreFrontCashierPayment`) e `Success` (0/1).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFrontPaymentGetResponse" } } } }, "400": { "description": "Erros de validação:\n- `Transação não localizada idw`\n- `Transação não localizada controlpay` (PayGo)\n- `Transação divergente (referência controlpay: , esperado: )`\n- `Integração não suportada para este fluxo de pagamento`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "504": { "description": "Timeout do polling — 60 tentativas esgotadas sem resultado final. Cliente deve repetir a chamada." } } }, "delete": { "operationId": "storeFrontPaymentDelete", "tags": [ "Frente de Caixa" ], "summary": "Cancela uma transação TEF/Pix", "description": "Cancela uma transação **autorizada** (status `3` Creditado) ou **em cancelamento** (status `6`). Outros status retornam `Transação não esta aprovada. O cancelamento é permitido apenas em transações autorizadas`.\n\n## Por integração\n\n- **PayGo / ControlPay**: chama `Venda/CancelarVenda` com `senhaTecnica` (senha técnica do TEF, passada via query `TEFPassword`). **Obrigatória** — se omitida, retorna `Precisa informar a senha do TEF para cancelamento (TEFPassword)`. Em sucesso de conexão, status vira **Em cancelamento** (`6`); cliente deve fazer polling via `GET` até o status final virar **Cancelado** (`7`). Erro de conexão → mensagem `Erro ao conectar ao terminal TEF...`.\n- **StarkBank**: retorna direto `Não é possível cancelar uma cobrança Pix. O QR Code apenas expira após o tempo configurado.` — Pix Stark Bank **não é cancelável** (só expira).\n- **Pagar.me**: chama `CancelPix(IDCompanyIntegration, ExternalId)`. Status vira **Cancelado** (`7`) com `RecordTimestampCancel` e `IDUserCancel` preenchidos.\n\nEm todos os casos com sucesso de conexão, grava `RecordTimestampCancel` (data/hora atual) e `IDUserCancel` (usuário que iniciou o cancelamento, vindo do token via `LAMBDA_REQUEST_CONTEXT.authorizer.User`).\n\nA frente de cancelamento da tela faz polling do `GET` por até 180 segundos com intervalo de 2s entre tentativas, mostrando \"Aguarde ou digite o número do cartão...\" enquanto espera o cliente operar a maquininha.", "parameters": [ { "name": "TEFPassword", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Senha técnica do TEF (PayGo). Obrigatória para integração ControlPay; ignorada para StarkBank (não suporta) e opcional para Pagar.me." } ], "responses": { "200": { "description": "Cancelamento solicitado. Para PayGo retorna o `StoreFrontCashierPayment` com status atualizado para Em cancelamento (`6`) — cliente deve fazer polling via `GET`. Para Pagar.me retorna com status Cancelado (`7`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFrontPaymentListItem" } } } }, "400": { "description": "Erros:\n- `Transação não localizada`\n- `Transação não esta aprovada. O cancelamento é permitido apenas em transações autorizadas`\n- `Conta bancária não tem integração selecionada`\n- `Precisa informar a senha do TEF para cancelamento (TEFPassword)` (PayGo)\n- `Token integração TEF não está preenchido` (PayGo)\n- `Erro ao conectar ao terminal TEF...` (PayGo, status 15)\n- `Não é possível cancelar uma cobrança Pix. O QR Code apenas expira após o tempo configurado.` (StarkBank)\n- `Transação Pagarme sem ExternalId, não é possível cancelar`\n- `Integração da conta bancária não suportada para cancelamento`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/store-front/payment/status": { "get": { "operationId": "typeStoreFrontPaymentStatus", "tags": [ "Tipos — PDV" ], "summary": "Lista os status possíveis de transação TEF/Pix", "description": "Lista de valores fixos (`TypeStatusStoreFrontCashierPayment`):\n\n| Id | Descrição | ExternalId (PayGo) |\n|---|---|---|\n| 1 | Pendente | 5 |\n| 2 | Em pagamento | 6 |\n| 3 | Creditado | 10 |\n| 4 | Expirado | 15 |\n| 5 | Cancelamento iniciado | 18 |\n| 6 | Em cancelamento | 19 |\n| 7 | Cancelado | 20 |\n| 8 | Pagamento recusado | 25 |\n\nO `ExternalId` é usado pelo sistema `GET` para mapear o status retornado pelo PayGo/ControlPay para o status interno.", "responses": { "200": { "description": "Status possíveis.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeStatusStoreFrontCashierPayment": { "type": "string", "description": "Identificador do status da transação do PDV." }, "TypeStatusStoreFrontCashierPayment": { "type": "string", "description": "Descrição do status (`Pendente`, `Em processamento`, `Creditado`, `Cancelado`, etc.)." } } } } } } } } } }, "/store-front/cashier": { "get": { "operationId": "storeFrontCashierList", "tags": [ "Frente de Caixa" ], "summary": "Lista os caixas (caixinhas) do PDV", "description": "Lista todos os **caixas do PDV** (`BankAccount` com `BankNumber = '000'`, status ativo) da(s) empresa(s) do contexto. Cada item traz o **status** derivado (Aberto/Fechado), o **operador** logado (quando aberto), o **saldo** corrente do caixa (`Balance` = soma de todos os lançamentos em `AccountsPayableReceivableBankStatement` até agora) e o faturador (`IDCompanyInvoice`) que será usado na NFC-e.\n\nO escopo é multi-empresa: respeita `accountname`/`idcompanylist` do token. Quando `accountname=[\"all\"]`, lista todos os caixas do grupo.\n\nO front da Frente de Caixa filtra ainda na própria tela: mostra primeiro os caixas **abertos pelo usuário corrente** (oferecendo \"Retomar Caixa\"), em seguida os caixas **fechados** disponíveis, e bloqueia os caixas **abertos por outro usuário**.", "parameters": [ { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra caixas cujo faturador é esta empresa. Usado pela tela de abertura para mostrar só os caixas da empresa selecionada." }, { "name": "StoreFrontCashierStatus", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2 ] }, "description": "Filtra pelo status: `1`=Fechado (sem sessão aberta), `2`=Aberto (com sessão ativa)." } ], "responses": { "200": { "description": "Lista de caixas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreFrontCashierListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/store-front/cashier/{idbankaccount}": { "parameters": [ { "name": "idbankaccount", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Conta bancária do caixa do PDV." } ], "get": { "operationId": "storeFrontCashierGet", "tags": [ "Frente de Caixa" ], "summary": "Snapshot do caixa aberto (resumo financeiro + ZPL)", "description": "Retorna o **caixa aberto** com cálculos financeiros completos da sessão atual + **dois recibos ZPL** prontos para impressão (usados no fechamento e na conferência diária).\n\n## Campos calculados\n\n- **`Balance`** — saldo atual do caixa (soma de todos os créditos menos débitos em `AccountsPayableReceivableBankStatement` até agora).\n- **`Income`** — soma de **créditos** desde a abertura do caixa (`IDTypeAccount=0`) **menos** o que foi pago em dinheiro nos pedidos (porque o dinheiro do cliente já entrou pela venda; evita contagem dupla).\n- **`Outcome`** — soma de **débitos** desde a abertura.\n- **`AdjustIn`** — reforços (créditos sem `IDAccountPayableReceivable` vinculado).\n- **`AdjustOut`** — sangrias (débitos sem `IDAccountPayableReceivable` vinculado).\n- **`TotalValueCancelled`** — diferença entre `Income` original e a soma dos pagamentos em dinheiro (usada para conciliar quando há vendas canceladas).\n- **`PaymentSummary`** — vendas da sessão agrupadas por **tipo de pagamento** (com descrição), incluindo os tipos zerados habilitados para PDV (`EnableFrenteCaixa=1`).\n- **`PaymentCategorySummary`** — vendas agrupadas por **categoria** de pagamento (Crédito, Débito, Dinheiro, Pix etc.).\n- **`InvoiceSummary`** — vendas agrupadas por modelo de NF emitida (`NfeModelo` = 55 NFe, 65 NFCe, ou null para pendentes).\n\n## Recibos ZPL\n\n- **`ReceiptBase64Encode`** — \"Fechamento de caixa\" para conferência (Saldo Anterior + Total Vendas por tipo + Reforço + Sangria + Saldo Final).\n- **`ReceiptFiscalBase64Encode`** — \"Resumo Fiscal\" (Total NFCe, Total NFe, Pendentes + quantidade de cada).\n\nAmbos os ZPL vêm codificados em **base64 + cp850** (encoding necessário para a maioria das impressoras térmicas Bematech/Daruma/Epson). Use o `PrintService` (com QzTray) para enviá-los para a impressora padrão (`LabelReceiptDefaultPrinter`).\n\n## Quando o caixa está fechado\n\nMesmo com o caixa fechado, o endpoint retorna o `BankAccount` com `Balance` corrente — apenas os campos da sessão (`RecordTimestampOpen`, `Income`, `Outcome`, etc.) vêm vazios.\n\n## Tipo de pedido padrão\n\nQuando a `IDTypeOrder` está nula, o sistema busca o **tipo de pedido marcado como padrão para Frente de Caixa** (`DefaultFrenteCaixa=1`). Se também não houver, retorna `[BadRequest] - Não existe tipo de pedido padrão para frente de caixa`.", "responses": { "200": { "description": "Snapshot do caixa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreFrontCashierDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Caixa não existe`\n- `Não existe tipo de pedido padrão para frente de caixa`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/store-front/cashier/{idbankaccount}/open": { "parameters": [ { "name": "idbankaccount", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Conta bancária do caixa do PDV a abrir." } ], "post": { "operationId": "storeFrontCashierOpenPost", "tags": [ "Frente de Caixa" ], "summary": "Abre o caixa do PDV", "description": "Abre uma **nova sessão** de caixa (`StoreFrontCashier`) ou **retoma** a sessão atual quando o caixa já está aberto pelo mesmo usuário.\n\n## Pré-condições\n\n1. **Controle de concorrência** (TTL 10s) chaveado por `IDBankAccount` — evita abertura concorrente do mesmo caixa.\n2. **Conta precisa ser caixinha do PDV** — `BankNumber = '000'`. Se não for, retorna `Banco informado não é do tipo Caixinha`.\n3. **Tipo de pedido padrão** — `IDTypeOrder` precisa estar preenchido (configurado no cadastro da conta).\n4. **Caixa não pode estar aberto por outro usuário** — se está, retorna `Caixa já esta aberto e precisa fechar antes de abrir novamente`. Se for o **mesmo usuário**, a chamada é **idempotente** — retoma a sessão existente sem criar nova.\n5. **Usuário não pode ter outro caixa aberto** — se tem, retorna `Usuário já possui outro caixa aberto`.\n6. **Senha** — validada com `bcrypt.compare` contra a senha cadastrada do usuário. Senha errada → `Senha incorreta`. Usuário sem senha → `Usuário não tem senha cadastrada`.\n\n## Validações condicionais (parâmetro CompanyParameter)\n\nQuando `CheckConfigCashierOpen = 1`, o sistema **valida configurações fiscais** antes de abrir:\n\n- `NfceUltima`, `NfceSerie`, `NfceCSC`, `NfceCSCid` preenchidos (campos para emissão de NFCe).\n- Existe pelo menos uma `TypeTax` com `IssueNFCe=1` para a empresa.\n- Essa `TypeTax` tem pelo menos uma configuração `StockKeepingUnitIcmsTaxInterstate` (ICMS para consumidor final).\n- Existe pelo menos um `TypePayment` ativo com `EnableFrenteCaixa=1`.\n\nFalha em qualquer um → mensagem específica (`Precisa preencher o número da última NFCe...`, `Não existe nenhuma regra fiscal para emissão de NFCe...`, etc.).\n\n## Side-effects\n\n- Cria registro em `StoreFrontCashier` (ou reutiliza o existente em retomada).\n- Se `InitialBalance` difere do `Balance` atual em mais de R$ 0,01, gera lançamento `AccountsPayableReceivableBankStatement` com descrição **\"Ajuste abertura de caixa\"** (crédito se positivo, débito se negativo) — registra a divergência declarada pelo operador (\"o caixa tinha mais/menos do que o sistema dizia\").\n- Grava `CommentsOpen` quando preenchido.\n\n## Resposta\n\nRetorna o caixa aberto com o **contexto operacional** (`IDStoreFrontCashier`, `RecordTimestampOpen`, `Login`, tipo de pedido, política comercial, armazém, faturador, flag `IssueNFCe`) — tudo que o front precisa para inicializar a tela do PDV.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFrontCashierOpenBody" } } }, "description": "Abre a sessão de caixa do operador autenticado. Faz validação prévia da configuração quando a parametrização **Validar configurações na abertura do caixa** está ativa: checa série/numeração/CSC da NFCe no cadastro da empresa, regra fiscal ativa para emissão de NFCe (`IssueNFCe=1`), configuração de ICMS para consumidor final na regra fiscal e ao menos um tipo de pagamento habilitado no PDV (`EnableFrenteCaixa=1`). Em seguida valida a senha do operador via bcrypt contra a senha cadastrada do usuário. Quando o mesmo operador já tem a sessão aberta, a chamada é idempotente e devolve a sessão atual. Diferenças entre `InitialBalance` e o saldo calculado da `BankAccount` geram lançamento `Ajuste abertura de caixa` no extrato bancário. Bloqueios comuns: caixa de outro operador já aberto, banco que não é caixinha (`BankNumber != '000'`), banco sem tipo de pedido padrão, usuário sem senha cadastrada. Controle de concorrência (TTL 10s, chaveado por `IDBankAccount`) evita aberturas simultâneas do mesmo caixa." }, "responses": { "200": { "description": "Caixa aberto (ou retomado). Resposta inclui o contexto operacional para inicializar o PDV.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreFrontCashierOpenResponse" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Caixa já esta em processo de abertura` (controle de concorrência)\n- `Caixa não existe`\n- `Banco informado não é do tipo Caixinha`\n- `Banco informado não tem tipo de pedido padrão cadastrado`\n- `Caixa já esta aberto e precisa fechar antes de abrir novamente`\n- `Usuário não localizado`\n- `Usuário não tem senha cadastrada`\n- `Senha incorreta`\n- `Usuário já possui outro caixa aberto`\n- `Erro ao abrir caixa. Verificar se o mesmo já esta aberto`\n- `Não existe tipo de pedido padrão para frente de caixa`\n- Validações fiscais (com `CheckConfigCashierOpen=1`): `Precisa preencher o número da última NFCe...`, `Precisa preencher a séria da NFCe...`, `Precisa preencher ID CSC...`, `Precisa preencher código de contribuinte...`, `Não existe nenhuma regra fiscal para emissão de NFCe...`, `Não existe nenhuma configração de ICMS na regra fiscal para consumidor final`, `Não existe tipo de pagamento configurado para frente de caixa`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/store-front/cashier/{idbankaccount}/close": { "parameters": [ { "name": "idbankaccount", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Conta bancária do caixa a fechar." } ], "post": { "operationId": "storeFrontCashierClosePost", "tags": [ "Frente de Caixa" ], "summary": "Fecha o caixa do PDV", "description": "Fecha a sessão atual do caixa, gravando `RecordTimestampClose` com o momento do fechamento.\n\n## Validações\n\n- Caixa precisa estar **aberto** — se não, retorna `Caixa não esta aberto e precisa abrir antes de fechar`.\n- **Senha** validada com bcrypt — `Senha incorreta` se errada, `Usuário não tem senha cadastrada` se vazia.\n- Usuário precisa existir (`Usuário não localizado` se não bate com a empresa).\n\n## Side-effects\n\n- Se `FinalBalance` difere do `Balance` atual em mais de R$ 0,01, gera lançamento `AccountsPayableReceivableBankStatement` com descrição **\"Ajuste fechamento de caixa\"** (crédito ou débito conforme o sinal) — registra a divergência apurada pelo operador na conferência física (\"contei R$ 850 mas o sistema dizia R$ 870\").\n- Grava `CommentsClose` quando preenchido.\n- A frente normalmente exige **obrigatório** o campo `Comments` quando há divergência (`FinalBalance != Balance`).\n\nO caixa não permite ser fechado se ainda há **pedido em montagem** ou **transação TEF em aberto** — o front bloqueia o botão de fechamento quando `listItems.length > 0`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFrontCashierCloseBody" } } }, "description": "Encerra a sessão de caixa atual (gravando `RecordTimestampClose`). A senha do operador autenticado é validada via bcrypt. Quando `FinalBalance` difere em mais de R$ 0,01 do saldo calculado, gera um lançamento `Ajuste fechamento de caixa` no extrato bancário (entrada se sobrou, saída se faltou). Falha quando a sessão não está aberta." }, "responses": { "200": { "description": "Caixa fechado. Resposta: string `Sucesso`.", "content": { "application/json": { "schema": { "type": "string", "example": "Sucesso" } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Caixa não existe`\n- `Caixa não esta aberto e precisa abrir antes de fechar`\n- `Usuário não localizado`\n- `Usuário não tem senha cadastrada`\n- `Senha incorreta`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/store-front/cashier/{idbankaccount}/adjust": { "parameters": [ { "name": "idbankaccount", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Conta bancária do caixa." } ], "post": { "operationId": "storeFrontCashierAdjustPost", "tags": [ "Frente de Caixa" ], "summary": "Sangria ou reforço de caixa", "description": "Registra uma **sangria** (saída de dinheiro do caixa para o cofre/banco, `Type=2`) ou **reforço** (entrada de dinheiro no caixa, geralmente troco, `Type=1`).\n\n## Validações\n\n- Caixa precisa estar **aberto** — `Caixa não esta aberto e não pode ter sangria/reforço` caso contrário.\n- Senha do usuário validada via bcrypt.\n- **Sangria não pode ultrapassar o saldo** — se `Balance - Value < 0`, retorna `Sangria não pode ser realizada, pois valor é maior que disponível`.\n- Campo `Type` é **obrigatório** — se omitido, retorna `Precisa informar o Type (1 - reforço, 2 - sangria)`.\n\n## Side-effects\n\n- Cria lançamento em `AccountsPayableReceivableBankStatement` com:\n - `IDTypeAccount = 0` (crédito) para reforço, `1` (débito) para sangria.\n - `TransactionDescription = \"Reforço: \"` ou `\"Sangria: \"`.\n - `IDStoreFrontCashier` vinculado à sessão atual.\n\n## Recibo ZPL\n\nA resposta inclui um **recibo ZPL** (`ReceiptBase64Encode`, base64 + cp850) com cabeçalho da empresa, operador, tipo (REFORÇO/SANGRIA), valor formatado em R$, data/hora, caixa e observações. O recibo tem espaço para assinatura do responsável e é impresso automaticamente pelo PDV (geralmente em 2 vias — uma fica com o operador, outra com quem recebeu o dinheiro retirado).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFrontCashierAdjustBody" } } }, "description": "Registra reforço (`Type=1`, entrada de dinheiro) ou sangria (`Type=2`, retirada de dinheiro) no caixa aberto, gravando um lançamento em `AccountsPayableReceivableBankStatement` com a descrição `Reforço: ` ou `Sangria: `. A senha do operador é validada via bcrypt. Sangria que excede o saldo disponível é rejeitada. A resposta inclui o recibo do operador em `ReceiptBase64Encode` (texto cp850 + base64) pronto para a impressora." }, "responses": { "200": { "description": "Sangria/reforço registrado. Retorna o ZPL do recibo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ReceiptBase64Encode": { "type": "string", "format": "byte", "description": "ZPL do recibo (base64 + cp850)." } } } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Precisa informar o Type (1 - reforço, 2 - sangria)`\n- `Caixa não existe`\n- `Caixa não esta aberto e não pode ter sangria/reforço`\n- `Sangria não pode ser realizada, pois valor é maior que disponível`\n- `Usuário não localizado`\n- `Usuário não tem senha cadastrada`\n- `Senha incorreta`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/store-front/cashier/{idbankaccount}/order-temp": { "parameters": [ { "name": "idbankaccount", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Conta bancária do caixa." } ], "get": { "operationId": "storeFrontCashierOrderTempGet", "tags": [ "Frente de Caixa" ], "summary": "Lista rascunhos de pedido do caixa", "description": "Lista os **rascunhos de pedido** (`StoreFrontCashierOrderTemp`) salvos no caixa. Esses rascunhos são **gerados automaticamente** pelo motor de promoções `POST /sku/promotion/order/validate` a cada alteração do carrinho — funcionam como um \"backup\" do estado do PDV para permitir **retomar uma venda interrompida** em outro terminal.\n\nCada item tem o `OrderData` (JSON parseado) com a estrutura completa do carrinho: itens, cliente, pagamentos, tipo de pedido, política comercial, vendedor, etc.\n\nA tela usa esses rascunhos no menu **Rascunho de Pedido** — o operador pode escolher um rascunho e o sistema **restaura todo o estado** da venda (chama internamente `startOrderByTemp`).", "responses": { "200": { "description": "Lista de rascunhos com `OrderData` em JSON parseado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreFrontCashierOrderTempItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/store-front/cashier/{idbankaccount}/order-temp/{idstorefrontcashierordertemp}": { "parameters": [ { "name": "idbankaccount", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Conta bancária do caixa." }, { "name": "idstorefrontcashierordertemp", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do rascunho." } ], "delete": { "operationId": "storeFrontCashierOrderTempDelete", "tags": [ "Frente de Caixa" ], "summary": "Apaga um rascunho de pedido", "description": "Remove fisicamente o rascunho de venda. Usado pelo PDV quando o operador descarta uma venda ou quando o pedido é efetivamente finalizado (`POST /orders`).", "responses": { "200": { "description": "Rascunho removido. Resposta: string `sucesso`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Rascunho não encontrado. Mensagem: `[BadRequest] - Rascunho pedido não encontrado`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/label": { "get": { "operationId": "typeCompanyLabelList", "tags": [ "Etiquetas (Empresa)" ], "summary": "Lista modelos de etiqueta", "description": "Retorna os modelos de etiqueta cadastrados pela empresa, ordenados pelo nome (`LabelName`), limitados a **3000 itens** por chamada. Aceita filtros por categoria (`IDTypeLabelCategory`) e por identificador único (`IDCompanyLabel`). Cada item traz as dimensões, o código ZPL bruto (quando o modelo foi escrito em modo ZPL) e o nome da categoria já resolvido.", "parameters": [ { "name": "IDTypeLabelCategory", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por categoria da etiqueta (`TypeLabelCategory`). Valores conhecidos: 1=Embarque (adicional transportadora), 2=Itens (recebimento), 3=Endereços, 4=Itens (cadastro), 5=Transportadora (embarque), 6=Cesto Picking, 7=Transportadora (cadastro), 8=Ressuprimento pendente, 9=Inconformidade picking/packing." }, { "name": "IDCompanyLabel", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por identificador único da etiqueta." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Reservado (lido do query mas sem efeito no caminho atual — todos os itens já vêm na mesma chamada, até 3000)." } ], "responses": { "200": { "description": "Lista de modelos de etiqueta.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyLabelListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "typeCompanyLabelPost", "tags": [ "Etiquetas (Empresa)" ], "summary": "Cadastra um modelo de etiqueta", "description": "Cria um modelo de etiqueta na empresa autenticada. `IDTypeLabelCategory` precisa existir na tabela de categorias do sistema. `EditorMode` controla a forma como o modelo é desenhado: `1` (default) é o modo **Canvas** — interface visual com variáveis e elementos drag-and-drop; `2` é o modo **ZPL** — código bruto colado no editor. A resposta é a lista de etiquetas filtrada pelo id recém-criado (mesmo formato de `GET /company/label?IDCompanyLabel=`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyLabelCreate" } } }, "description": "Dados do modelo de etiqueta. Obrigatórios: `LabelName`, `IDTypeLabelCategory`, `HeightCm`, `WidthCm`. Quando `EditorMode=2` (ZPL), o campo `LabelZpl` é obrigatório; no modo Canvas (1, default) o ZPL é gerado pelo front a partir do layout visual." }, "responses": { "200": { "description": "Modelo criado. Retorna a etiqueta recém-cadastrada (array com 1 item, mesmo formato da listagem).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyLabelListItem" }, "maxItems": 1 } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Empresa não existe`\n- `Tipo etiqueta não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/label/{idcompanylabel}": { "parameters": [ { "name": "idcompanylabel", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do modelo de etiqueta." } ], "put": { "operationId": "typeCompanyLabelPut", "tags": [ "Etiquetas (Empresa)" ], "summary": "Atualiza um modelo de etiqueta", "description": "Atualiza parcialmente o modelo — apenas os campos enviados são alterados. Quando `IDTypeLabelCategory` for informado, precisa existir na tabela de categorias. A resposta é a etiqueta atualizada no mesmo formato da listagem.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyLabelUpdate" } } }, "description": "Campos do modelo de etiqueta a atualizar. Atualização parcial — apenas os campos enviados são alterados." }, "responses": { "200": { "description": "Modelo atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyLabelListItem" }, "maxItems": 1 } } } }, "400": { "description": "Erros de validação (prefixo `[BadRequest]`):\n- `Etiqueta não existe`\n- `Tipo etiqueta não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "typeCompanyLabelDelete", "tags": [ "Etiquetas (Empresa)" ], "summary": "Exclui um modelo de etiqueta", "description": "**Exclusão física** — diferente de outros cadastros do idworks, o modelo é apagado definitivamente do banco. Transportadoras e fornecedores que apontavam para essa etiqueta via `IDCompanyLabel` passam a ter o vínculo quebrado (o id deixa de existir). A resposta é a string `\"Sucesso\"` (com S maiúsculo).", "responses": { "200": { "description": "Modelo excluído. Retorna a string `\"Sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "enum": [ "Sucesso" ] } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Etiqueta não existe`\n- `Erro ao deletar etiqueta`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/webhook": { "get": { "operationId": "webhookList", "tags": [ "Logs de Webhook" ], "summary": "Lista logs de envio de webhook", "description": "Retorna o histórico de tentativas de envio de webhook da empresa, do mais recente para o mais antigo. Cada item representa **uma tentativa** de envio identificada pelo `UUID` da mensagem SQS — o campo `Attempts` indica quantas vezes a tentativa foi retentada. Aceita filtros opcionais por `Topic`, `Status`, faixa de data e paginação (2000 registros por página).\n\nFluxo de origem dos registros: quando uma ação habilitada no idworks ocorre (criar SKU, emitir NF, atualizar tracking, etc.), o sistema enfileira a notificação para envio ao webhook. O consumidor (`webhookPost`) lê a fila, consulta o endpoint e as credenciais configuradas para a empresa na integração `Webhook` (`IDTypeCompanyIntegration=52`), faz `POST` no endpoint do cliente com timeout de 10s e grava o resultado nesta tabela (`Status = 1` em sucesso, `Status = 0` em erro). Falhas voltam para a fila e incrementam `Attempts` na próxima tentativa.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Página (zero-based). Cada página devolve no máximo 2000 itens. Default: 0." }, { "name": "Topic", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome técnico do tópico (`SkuPost`, `InvoiceIssue`, `OrderStatus`, etc.). Match exato." }, { "name": "Status", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra pelo status do envio: `1` = sucesso (o destino respondeu 2xx), `0` = erro." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial (inclusive) do `RecordTimestamp`. Combina com `DateTo`." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final do `RecordTimestamp`, inclusivo até `23:59:59`. Combina com `DateFrom`." } ], "responses": { "200": { "description": "Lista de tentativas (até 2000 por página).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookLogListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/privilege-group": { "get": { "operationId": "userPrivilegeGroupList", "tags": [ "Perfis de Acesso" ], "summary": "Lista perfis de acesso", "description": "Retorna os perfis de acesso (grupos de privilégios) ativos da empresa, ordenados pelo nome. Quando a empresa autenticada é a `all` (multi-conta), retorna os perfis de todas as empresas vinculadas.", "responses": { "200": { "description": "Lista de perfis.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserPrivilegeGroupListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "userPrivilegeGroupPost", "tags": [ "Perfis de Acesso" ], "summary": "Cadastra um perfil de acesso", "description": "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, no formato de `GET /user/privilege-group/{idprivilegegroup}`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPrivilegeGroupCreate" } } }, "description": "Perfil de acesso a cadastrar. Apenas `PrivilegeGroupName` é obrigatório. O perfil nasce sem privilégios — use `POST /user/privilege-group/{idprivilegegroup}/resource` para atribuir a lista de privilégios depois." }, "responses": { "200": { "description": "Perfil criado. Devolve o detalhe (lista de módulos/privilégios atribuídos — vazia logo após o POST).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserPrivilegeGroupDetail" } } } } }, "400": { "description": "Empresa não localizada. Mensagem: `[BadRequest] - Company não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/privilege-group/{idprivilegegroup}": { "parameters": [ { "name": "idprivilegegroup", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do perfil de acesso." } ], "get": { "operationId": "userPrivilegeGroupGet", "tags": [ "Perfis de Acesso" ], "summary": "Detalha um perfil com os privilégios atribuídos", "description": "Retorna os **privilégios atribuídos** ao perfil, agrupados por área do menu (`ModuleGroupDescription`) e, dentro de cada área, por módulo (`ModuleDescription`). **Não devolve** privilégios disponíveis que não foram atribuídos — a tela do frontend cruza este resultado com `GET /company/module` (catálogo completo) para mostrar os checkboxes marcados e desmarcados.\n\nQuando o perfil ainda está vazio (logo após o `POST`), a resposta é `[]`.", "responses": { "200": { "description": "Detalhe do perfil. Array de áreas, cada uma com a lista de módulos do perfil e seus privilégios.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserPrivilegeGroupDetail" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "userPrivilegeGroupPut", "tags": [ "Perfis de Acesso" ], "summary": "Renomeia um perfil de acesso", "description": "Atualiza **apenas o nome** do perfil (`PrivilegeGroupName`). Para alterar os privilégios atribuídos, use `POST /user/privilege-group/{idprivilegegroup}/resource`. A resposta é o detalhe do perfil atualizado (mesmo formato do `GET`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPrivilegeGroupUpdate" } } }, "description": "Atualiza apenas o nome do perfil (`PrivilegeGroupName`)." }, "responses": { "200": { "description": "Perfil renomeado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserPrivilegeGroupDetail" } } } } }, "400": { "description": "Perfil não encontrado para a empresa. Mensagem: `[BadRequest] - Privelege Group não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "userPrivilegeGroupDelete", "tags": [ "Perfis de Acesso" ], "summary": "Exclui (inativa) um perfil de acesso", "description": "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`) — nesse caso é preciso primeiro desvincular o perfil de cada usuário em **Configurações → Usuários**.\n\nA resposta é a lista atualizada dos perfis ativos (mesmo formato do `GET /user/privilege-group`).", "responses": { "200": { "description": "Perfil inativado. Devolve a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserPrivilegeGroupListItem" } } } } }, "400": { "description": "Perfil não encontrado ou ainda vinculado a usuários. Mensagens: `[BadRequest] - Grupo privilégio não existe`; `[BadRequest] - Perfil de acesso esta vinculado a usuários e não pode ser excluído`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/privilege-group/{idprivilegegroup}/resource": { "parameters": [ { "name": "idprivilegegroup", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do perfil de acesso." } ], "post": { "operationId": "userPrivilegeGroupResourcePost", "tags": [ "Perfis de Acesso" ], "summary": "Substitui a lista de privilégios do perfil", "description": "Sobrescreve a lista de privilégios atribuídos ao perfil — **não é incremento**. O body é um array com os identificadores (`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.\n\nA cada chamada o sistema:\n1. Grava um registro de auditoria em `UserPrivilegeGroupLog` com o usuário, o `Data` enviado e o id do perfil.\n2. Apaga todas as linhas de `UserPrivilegeGroupResource` do perfil e insere a nova lista.\n3. Devolve o detalhe do perfil atualizado.\n\n> A alteração só passa a valer para o usuário **depois que ele faz logout e login de novo** no sistema — a sessão ativa ainda guarda os privilégios anteriores.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Array de `IDUserPrivilege` que devem ficar atribuídos ao perfil. Pode ser vazio para deixar o perfil sem nenhum privilégio." } } }, "description": "Array de `IDUserPrivilege` que devem ficar atribuídos ao perfil. Sobrescreve a lista existente — não é incremento. Aceita array vazio para deixar o perfil sem nenhum privilégio. A alteração só vale para o usuário no próximo login (a sessão atual ainda mantém os privilégios anteriores)." }, "responses": { "200": { "description": "Privilégios atualizados. Devolve o detalhe do perfil.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserPrivilegeGroupDetail" } } } } }, "400": { "description": "Perfil não encontrado. Mensagem: `[BadRequest] - Privilegio não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/job": { "get": { "operationId": "jobsResultList", "tags": [ "Jobs e Tarefas" ], "summary": "Lista jobs de ação em massa", "description": "Retorna os jobs disparados pela empresa, do mais recente para o mais antigo. Cada item traz o tipo da ação (`TypeJob`) e o login do usuário que criou. Aceita filtro opcional por `IDTypeJob`. Quando a empresa autenticada é a `all` (multi-conta), retorna jobs de todas as empresas vinculadas.", "parameters": [ { "name": "IDTypeJob", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo tipo da ação (`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." } ], "responses": { "200": { "description": "Lista de jobs.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "jobsResultPost", "tags": [ "Jobs e Tarefas" ], "summary": "Dispara um job de ação em massa (upload de planilha)", "description": "Cria um job para processar em lote a ação indicada por `IDTypeJob`. O sistema:\n\n1. Valida o `IDTypeJob` contra o catálogo de `TypeJob` (cada tipo sabe processar um formato de planilha — importação de SKU, de pedidos, etc.).\n2. Faz upload do arquivo enviado (multipart `file`, até 5 MB no frontend) para o armazenamento temporário e calcula o **hash SHA-256** do conteúdo.\n3. Se já existe um job da mesma empresa com o **mesmo hash** ainda em processamento, **reaproveita** o job existente e retorna o `IDJob` atual sem disparar de novo — bloqueio anti-duplicação.\n4. Caso contrário, registra um novo job e dispara o processamento de forma **assíncrona**.\n5. Devolve `IDJob` ao cliente. O resultado real é gravado linha-a-linha e o usuário recebe a confirmação por e-mail. Acompanhe via `GET /job/{idjob}`.", "parameters": [ { "name": "IDTypeJob", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Identificador do tipo de ação. Define qual rotina processa o arquivo. Lista completa em `TypeJob` — 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." }, { "name": "IDBankAccount", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "**Obrigatório quando `IDTypeJob = 38`** (Importar extrato OFX). Identificador da conta bancária de destino. Vai como `Metadata` do job." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "**Obrigatório quando `IDTypeJob = 41`** (Importar conciliação adquirente). Identificador da integração de adquirente. Vai como `Metadata` do job." }, { "name": "IDSupplier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Usado por algumas ações de tabela de frete (`IDTypeJob` 4, 5, 10). Vai como `Metadata` do job junto com o nome do arquivo." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Planilha `.xlsx` ou `.xls` com os dados a importar. Até 5 MB. O modelo da planilha de cada tipo é baixado em `TemplateUrl` (quando preenchido)." } } } } }, "description": "Upload `multipart/form-data` com o campo `file` contendo a planilha (XLSX/CSV, até 5 MB). O tipo da ação é definido por `IDTypeJob` na query. O sistema grava o arquivo em armazenamento temporário, calcula um hash SHA-256 do conteúdo e, se já existe um job em processamento com o mesmo hash para a empresa, reaproveita o `IDJob` existente — bloqueio anti-duplicação. Caso contrário, dispara o processamento associado de forma assíncrona." }, "responses": { "200": { "description": "Job criado (ou reaproveitado). Devolve `IDJob` para acompanhamento. O processamento é assíncrono — o resultado vem por e-mail e pode ser acompanhado em `GET /job/{idjob}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPostResponse" } } } }, "400": { "description": "Falha de validação. Mensagens possíveis: `[BadRequest] - Ação não encontrada` (IDTypeJob inválido); `[BadRequest] - Erro ao processar ação em massa` (combinação rota/tipo não mapeada); `[BadRequest] - IDBankAccount é obrigatório`; `[BadRequest] - IDCompanyIntegration é obrigatório`. Também devolve **400 sem corpo** quando o `file` está ausente para uma ação que exige arquivo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "404": { "description": "Empresa do `accountname` não localizada (404 sem corpo)." }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/job/{idjob}": { "parameters": [ { "name": "idjob", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do job." } ], "get": { "operationId": "jobsResultGet", "tags": [ "Jobs e Tarefas" ], "summary": "Detalha um job com os resultados linha-a-linha", "description": "Retorna o cabeçalho do job (datas, usuário, tipo, etc.) e o array `Result` com **uma entrada por linha** processada — cada uma com a aba (`Sheet`), o número da linha (`Line`), o status (`1` = sucesso, `0` = erro), a descrição da ação ou do erro, e o id e nome do recurso afetado. A resposta também traz uma **URL pré-assinada** (`UrlFile`) para baixar o arquivo enviado (válida por 2 dias).\n\nPaginação por `Page` (5000 linhas de resultado por página). Quando o id não pertence à empresa autenticada, devolve `[]`.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Página zero-based para a lista de resultados (`Result`). Cada página devolve no máximo 5000 linhas. Default: 0." } ], "responses": { "200": { "description": "Detalhe do job (array com 1 item) ou `[]` quando o id não pertence à empresa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobDetail" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/integration": { "get": { "operationId": "companyParameterList", "tags": [ "Integrações" ], "summary": "Lista as integrações da empresa", "description": "Retorna as integrações configuradas pela empresa (`CompanyIntegration`) com o tipo já resolvido (logo, nome, categoria) e o nível de reputação consolidado a partir das parametrizações. Aceita filtros opcionais por categoria, tipo, identificador, status e flag de gift card. Quando a empresa autenticada é a `all` (multi-conta), retorna integrações de todas as empresas vinculadas.", "parameters": [ { "name": "IDTypeCompanyIntegrationCategory", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por categoria do tipo de integração. Aceita um id único ou uma lista separada por vírgula (ex.: `1,4`). Categorias usuais: 1=Canal de Venda, 2=Gateway, 3=Transportadora, 4=Adquirente, 9=Banco. Outras: 7=ERP, 8=WMS, 10=Hub, 14=Plataformas de e-commerce." }, { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por tipo de integração (`IDTypeCompanyIntegration`). Ex.: 10=Mercado Livre, 16=idworks, 50=Correios, 131=Stark Bank." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por identificador específico da integração da empresa." }, { "name": "Status", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1, 2, 3 ] }, "description": "Filtra pelo status da integração: `1`=Ativo, `2`=Erro de autenticação, `3`=Não autenticado, `0`=Inativo." }, { "name": "GiftCard", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra pela flag `GiftCard` (tipos voltados a vale-presente)." } ], "responses": { "200": { "description": "Lista de integrações.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyIntegrationListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "companyParameterPost", "tags": [ "Integrações" ], "summary": "Cria uma integração da empresa", "description": "Cadastra uma nova `CompanyIntegration` para a empresa autenticada, partindo de um tipo (`IDTypeCompanyIntegration`).\n\nO **status inicial** depende do tipo:\n- Se o tipo tem parametrização com `Key = \"Validate\"` no catálogo, a integração nasce com `Status = 3` (**Não Autenticado**). É preciso passar pelo fluxo de autenticação para virar `Ativo`.\n- Caso contrário, nasce com `Status = 1` (**Ativo**) direto.\n\nDevolve o detalhe da integração recém-criada (formato de `GET /company/integration/{idcompanyintegration}`), pronto para preencher as parametrizações.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIntegrationCreate" } } }, "description": "Dados da integração a cadastrar. `IDTypeCompanyIntegration` aponta para o catálogo de tipos disponíveis (canais de venda como Mercado Livre, Shopee, VTEX; adquirentes como Cielo, Rede; transportadoras; bancos; etc.). Após criar, as credenciais e demais opções devem ser informadas via `PUT /company/integration/{idcompanyintegration}/parameter`." }, "responses": { "200": { "description": "Integração criada. Devolve o detalhe (array de parametrizações, vazio até preencher).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyIntegrationParameter" } } } } }, "400": { "description": "Erros de validação. Mensagens: `[BadRequest] - Tipo integração não existe`; `[BadRequest] - Empresa não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/integration/{idcompanyintegration}": { "parameters": [ { "name": "idcompanyintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da integração." } ], "put": { "operationId": "companyIntegrationPut", "tags": [ "Integrações" ], "summary": "Atualiza nome e status de uma integração", "description": "Atualiza o **nome** (`CompanyIntegrationName`) e o **status** (`Status`) da integração. Os outros dados (tipo, parametrizações) ficam intocados.\n\nA resposta repete o detalhe da integração (mesmo formato do `GET`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIntegrationUpdate" } } }, "description": "Atualiza os atributos administrativos da integração (nome amigável e status). Para alterar credenciais/configurações use `PUT /company/integration/{idcompanyintegration}/parameter`." }, "responses": { "200": { "description": "Integração atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyIntegrationParameter" } } } } }, "400": { "description": "Integração não encontrada. Mensagem: `[BadRequest] - Integração não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "companyIntegrationDelete", "tags": [ "Integrações" ], "summary": "Exclui (inativa) uma integração", "description": "Inativa a integração (`Status = 0`, `Show = 0`) e **remove fisicamente**:\n- Todas as parametrizações (`CompanyParameters`).\n- Todos os mapas de Hub (`HubCategory`, `HubBrand`, `HubCarrier`, `HubPayment`, `HubSalesPolicy`, `HubVariation`, `HubWarehouse`).\n\nExclusão é **bloqueada** por categoria:\n- **Transportadora** (categoria 3): bloqueia quando há fornecedor ativo com esta integração — fornecedores inativos são desvinculados (limpa `IDCompanyIntegration`).\n- **Gateway / Adquirente / Banco** (categorias 2, 4, 9 — respectivamente Gateway, Adquirente, Banco): bloqueia quando há conta bancária ativa vinculada — contas inativas são desvinculadas.\n- **Anúncios**: bloqueia quando há `HubProduct` apontando para esta integração — é preciso excluir os anúncios antes.\n\nA resposta é a lista atualizada das integrações (mesmo formato do `GET /company/integration`).", "responses": { "200": { "description": "Integração inativada. Devolve a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyIntegrationListItem" } } } } }, "400": { "description": "Integração não encontrada ou bloqueada por vínculo. Mensagens: `[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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/integration/{idcompanyintegration}/check": { "parameters": [ { "name": "idcompanyintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da integração." } ], "get": { "operationId": "companyIntegrationCheckGet", "tags": [ "Integrações" ], "summary": "Verifica credenciais de uma integração", "description": "Faz uma checagem síncrona das credenciais configuradas para a integração no sistema externo. A verificação é roteada conforme o tipo da integração — Correios (tipo 50), E-mail (tipo 51) e os demais canais de venda, cada um pelo seu conector próprio.\n\nA resposta é o que o serviço de integração devolver — geralmente um JSON com `Status`, `Message` e detalhes do diagnóstico. Use para confirmar, antes de salvar parametrizações, que as credenciais respondem ao canal externo.", "responses": { "200": { "description": "Resultado da checagem retornado pelo serviço de integração (formato varia por integração).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Conteúdo bruto da resposta do serviço de integração. Tipicamente inclui status e mensagem do diagnóstico." } } } }, "400": { "description": "Falha de roteamento ou integração inválida. Mensagens: `[BadRequest] - Integração não encontrada`; `[BadRequest] - Integracão não tem consulta de status` (tipo não suporta check ou serviço de integração devolveu 404); mensagem do serviço de integração em outros casos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/integration/{idcompanyintegration}/parameter": { "parameters": [ { "name": "idcompanyintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da integração." } ], "get": { "operationId": "companyParameterGet", "tags": [ "Integrações" ], "summary": "Lista as parametrizações da integração", "description": "Devolve o catálogo de parametrizações do tipo da integração cruzado com os valores já gravados pela empresa — é o que a tela usa para montar o formulário de configuração, agrupado por `TypeCompanyParametersGroup`.\n\nDetalhes do retorno:\n\n- Só vêm parametrizações com `Type` diferente de `hidden`, ordenadas por `ParameterOrder`.\n- Para `Type` `list`/`multi_list`, o campo `List` traz as opções disponíveis (itens de tabelas-tipo, planos de contas, contas bancárias, status, etc., conforme a `Key`).\n- Para `Type` `string_copy`/`url_get`, o campo `Value` pode ser **calculado** (ex.: URL de webhook/leilão de frete personalizada para a empresa, com tokens embutidos), em vez do valor cru gravado.\n\n**Modo alternativo** — quando `Type=ImportOffer`, o endpoint não retorna parametrizações: devolve o último job de importação de anúncios da integração com o progresso (`QuantityProcessed`, `QuantityPending`, `QuantityTotal`).", "parameters": [ { "name": "Type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Modo de consulta. Em branco (padrão) retorna as parametrizações. Com `ImportOffer`, retorna o progresso do último job de importação de anúncios da integração." } ], "responses": { "200": { "description": "Lista de parametrizações da integração (ou, quando `Type=ImportOffer`, o progresso do último job de importação). Array vazio quando não há registros.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyIntegrationParameter" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "companyParameterPut", "tags": [ "Integrações" ], "summary": "Atualiza as parametrizações da integração", "description": "Sobrescreve (upsert) os valores das parametrizações da integração. O body é um **array** de `{Key, Value}`. Para cada item:\n\n1. 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`).\n2. Faz upsert em `CompanyParameters` (chave única `IDCompanyIntegration + Key`).\n3. Grava o evento em `CompanyParametersLog` com o usuário autenticado e o body inteiro como `Data`.\n\nNão é necessário enviar todas as parametrizações — só as que mudaram. A resposta é o detalhe atualizado (mesmo formato do `GET`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyParameterValue" }, "description": "Lista de pares chave/valor a gravar/atualizar." } } }, "description": "Mapa de parametrizações da integração no formato `{ \"\": , ... }`, onde cada `` corresponde ao campo `Key` retornado por `GET /company/integration/{idcompanyintegration}/parameter` (ex.: `EndPoint`, `HeaderKeyAuth`, `TagBusiness`, `GnreIDTypeDocument`, `IDCompanyInvoice`). Tipos: `string`/`password`/`string_copy` → string; `boolean`/`checkbox` → `0` ou `1`; `list` → o `Value` da opção escolhida; `multi_list` → array de `Value`. Faz upsert: chaves enviadas substituem o valor atual; chaves omitidas permanecem inalteradas." }, "responses": { "200": { "description": "Parametrizações atualizadas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyIntegrationParameter" } } } } }, "400": { "description": "Integração não encontrada. Mensagem: `[BadRequest] - Integração não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/company/integration/{idcompanyintegration}/parameter/import": { "parameters": [ { "name": "idcompanyintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da integração." } ], "post": { "operationId": "companyParameterImportPost", "tags": [ "Integrações" ], "summary": "Dispara importação automática de anúncios", "description": "Dispara a importação automática de anúncios do canal de venda configurado (`idcompanyintegration`), repassando os demais parâmetros recebidos na query. Usado pela tela de importação direto do canal para popular a área temporária de produtos importados da integração.\n\nA resposta é o que o serviço de integração devolver (geralmente confirmação de enfileiramento).", "responses": { "200": { "description": "Resposta do serviço de integração (formato varia).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Resposta da importação de parâmetros — o formato varia por canal (geralmente confirmação de enfileiramento)." } } } }, "400": { "description": "Falha do serviço de integração. Devolve o `errorMessage` recebido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/production": { "get": { "operationId": "skuProductionList", "tags": [ "Produção" ], "summary": "Lista ordens de produção", "description": "Retorna as ordens de produção da empresa, com SKU produzido, armazém, status, pedido vinculado (quando há) e dados do usuário criador. Aceita filtros por id, SKU, status e faixa de data de cadastro.", "parameters": [ { "name": "IDStockKeepingUnitProduction", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por id específico da OP." }, { "name": "IDSku", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo SKU produzido." }, { "name": "IDSkuCompany", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código externo do SKU (`IDSkuCompany`)." }, { "name": "IDTypeStatusSkuProduction", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "description": "Filtra pelo status: 1=Finalizado, 2=Aberto, 3=Em andamento, 4=Cancelado." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Faixa inicial de `RecordTimestamp` (cadastro)." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Faixa final de `RecordTimestamp`, inclusivo até `23:59:59`." } ], "responses": { "200": { "description": "Lista de ordens de produção.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuProductionPost", "tags": [ "Produção" ], "summary": "Cria uma ordem de produção", "description": "Cria uma OP para um SKU configurado como `OwnProduction = 1`. Efeitos no momento da criação:\n\n1. Gera lançamentos em `StockKeepingUnitMovement` (tipo 1 = consumo) para **cada componente** do kit (`StockKeepingUnitKitItems`), na quantidade necessária × `Quantity`, debitando o saldo do armazém indicado.\n2. Valida que cada componente tem saldo disponível no armazém — falha se não tiver.\n3. Custos do consumo seguem `UseCostFromCostSet` da empresa: quando ativo, usa `CostSet` do SKU; senão, calcula pelo saldo (`InventoryValue / QtyAvailable`).\n4. Copia as etapas da `StockKeepingUnitProductionLine` vinculada ao SKU (ou da linha padrão da empresa) para `StockKeepingUnitProductionSteps`.\n5. Status inicial = 2 (Aberto). A resposta é o detalhe da OP recém-criada (formato de `GET /sku/production/{idstockkeepingunitproduction}`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionCreate" } } }, "description": "Dados de cadastro da ordem de produção (cabeçalho). Os itens (SKUs a produzir) são enviados depois via `POST /sku/production/{idstockkeepingunitproduction}/sku`." }, "responses": { "200": { "description": "Ordem de produção criada (detalhe).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionDetail" } } } } }, "400": { "description": "`[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: Quantidade disponível () menor que quantidade solicitada ()`; `[BadRequest] - Sku não tem saldo disponível`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/production/{idstockkeepingunitproduction}": { "parameters": [ { "name": "idstockkeepingunitproduction", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da ordem de produção." } ], "get": { "operationId": "skuProductionGet", "tags": [ "Produção" ], "summary": "Detalha uma ordem de produção", "description": "Retorna a OP completa com: cabeçalho, lista de **itens consumidos** (`Items` — array de `StockKeepingUnitMovement` de cada insumo com SKU, quantidade, custo total e unitário, armazém), lista de **etapas** (`StockKeepingUnitProductionLineSteps` — array com status, tempo gasto, tempo decorrido, usuário que finalizou cada uma) e somatórios de tempo (`TimeSpentTotal`, `TimeElapsedTotal`) e custo (`ValueCostTotal`).", "responses": { "200": { "description": "Detalhe da OP (array com 1 item).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionDetail" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "skuProductionPut", "tags": [ "Produção" ], "summary": "Atualiza uma ordem de produção", "description": "Atualiza campos editáveis (`DateEstimated`, `Comments`, `IDTypeStatusSkuProduction`, `IDOrder`) — apenas os campos enviados são alterados. Bloqueia atualização quando a OP está **Finalizada** com pedido vinculado ou **Cancelada**. Quando `IDTypeStatusSkuProduction` é enviado, valida que existe no catálogo. A resposta é o detalhe atualizado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionUpdate" } } }, "description": "Atualização parcial da ordem de produção. Apenas os campos enviados são aplicados." }, "responses": { "200": { "description": "OP atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionDetail" } } } } }, "400": { "description": "`[BadRequest] - Produção não existe`; `[BadRequest] - Produção esta finalizada`; `[BadRequest] - Produção esta cancelada`; `[BadRequest] - Status não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuProductionDelete", "tags": [ "Produção" ], "summary": "Cancela uma ordem de produção", "description": "**Cancelamento lógico**: marca a OP como `IDTypeStatusSkuProduction = 4` (Cancelado) e remove fisicamente os movimentos de insumos consumidos (`StockKeepingUnitMovement`) e as etapas (`StockKeepingUnitProductionSteps`). Reverte automaticamente o saldo dos insumos no armazém. Bloqueado quando a OP já está **Finalizada** ou **Cancelada**. A resposta é o detalhe da OP cancelada.", "responses": { "200": { "description": "OP cancelada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionDetail" } } } } }, "400": { "description": "`[BadRequest] - Produção não existe`; `[BadRequest] - Produção esta finalizada`; `[BadRequest] - Produção esta cancelada`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/production/{idstockkeepingunitproduction}/finish": { "parameters": [ { "name": "idstockkeepingunitproduction", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da OP." } ], "post": { "operationId": "skuProductionFinishPost", "tags": [ "Produção" ], "summary": "Finaliza a ordem de produção (gera Recebimento)", "description": "Conclui a OP marcando como `IDTypeStatusSkuProduction = 1` (Finalizado). Efeitos colaterais:\n\n1. Cria um **Recebimento** (`purchasePost`) ou reaproveita o `IDPurchase` enviado no body. O fornecedor é o **fornecedor padrão de recebimento** da empresa.\n2. Lança no recebimento o **produto produzido** (`purchaseSkuPost` com `BypassValidation=1`), na quantidade e custo total acumulados da OP.\n3. Atualiza os movimentos de consumo (`IDStatusSku = 1`).\n4. Vincula o `IDPurchase` ao registro da OP.\n\nBloqueado quando a OP já está Finalizada/Cancelada. Devolve o detalhe do Recebimento gerado (mesmo formato de `GET /purchase/{idpurchase}`).", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionFinish" } } }, "description": "Finalização da ordem de produção — efetiva a entrada dos SKUs produzidos no depósito de destino e consome os componentes (no caso de produção de kits). O corpo geralmente é vazio; o sistema usa o estado da ordem para concluir a movimentação." }, "responses": { "200": { "description": "Detalhe do recebimento gerado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionFinishResponse" } } } } }, "400": { "description": "`[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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/production/{idstockkeepingunitproduction}/sku": { "parameters": [ { "name": "idstockkeepingunitproduction", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da OP." } ], "post": { "operationId": "skuProductionSkuPost", "tags": [ "Produção" ], "summary": "Adiciona um insumo extra à OP", "description": "Adiciona um item consumido (insumo/matéria-prima) à OP além dos componentes copiados na criação. O SKU informado precisa ser do tipo SKU (3), matéria-prima (6) ou variante (7), ter saldo disponível no armazém indicado (ou no armazém da OP), e o custo é calculado conforme o flag `UseCostFromCostSet` da empresa. Bloqueado quando a OP está Finalizada/Cancelada. Devolve o detalhe da OP atualizada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionSkuAdd" } } }, "description": "Adiciona um SKU à ordem de produção. Informe `Quantity` (quantidade a produzir) e opcionalmente `Comments`." }, "responses": { "200": { "description": "Insumo adicionado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionDetail" } } } } }, "400": { "description": "`[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 () menor que quantidade solicitada ()`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/production/{idstockkeepingunitproduction}/sku/{idskumovement}": { "parameters": [ { "name": "idstockkeepingunitproduction", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da OP." }, { "name": "idskumovement", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do movimento de consumo (linha de insumo na OP)." } ], "put": { "operationId": "skuProductionSkuPut", "tags": [ "Produção" ], "summary": "Atualiza um insumo da OP", "description": "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. Devolve o detalhe da OP.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionSkuUpdate" } } }, "description": "Atualiza a quantidade ou o depósito de destino de um item da ordem de produção." }, "responses": { "200": { "description": "Insumo atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionDetail" } } } } }, "400": { "description": "`[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 () menor que quantidade adicional solicitada ()`; `[BadRequest] - Sku não tem saldo disponível`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuProductionSkuDelete", "tags": [ "Produção" ], "summary": "Remove um insumo da OP", "description": "Remove uma linha de insumo consumido na OP. Bloqueado quando OP está Finalizada/Cancelada. Devolve o detalhe da OP atualizada.", "responses": { "200": { "description": "Insumo removido.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionDetail" } } } } }, "400": { "description": "`[BadRequest] - Produção não existe`; `[BadRequest] - Produção esta finalizada`; `[BadRequest] - Produção esta cancelada`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/production/{idstockkeepingunitproduction}/steps/{idstockkeepingunitproductionsteps}": { "parameters": [ { "name": "idstockkeepingunitproduction", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da OP." }, { "name": "idstockkeepingunitproductionsteps", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da etapa dentro da OP." } ], "put": { "operationId": "skuProductionStepsPut", "tags": [ "Produção" ], "summary": "Atualiza uma etapa da OP (status e tempo gasto)", "description": "Marca o progresso de uma etapa específica da OP: muda o status (`IDTypeStatusSkuProduction`) e registra o tempo gasto (`TimeSpent`, formato `HH:MM:SS`). Quando muda para `3` (Em andamento), grava `RecordTimestampStart` com o momento atual. Quando muda para `1` (Finalizado), grava `RecordTimestampEnd` com o momento atual e `RecordUserCreatedEnd` com o usuário autenticado. Como efeito colateral, a OP-mãe passa para status `3` (Em andamento) — sai do Aberto. Devolve o detalhe da OP.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionStepUpdate" } } }, "description": "Atualiza o status da etapa da ordem de produção (avanço no fluxo de etapas configurado na linha de produção)." }, "responses": { "200": { "description": "Etapa atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionDetail" } } } } }, "400": { "description": "`[BadRequest] - Etapa produção não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/production/line": { "get": { "operationId": "skuProductionLineList", "tags": [ "Produção" ], "summary": "Lista linhas de produção", "description": "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`. Aceita filtros por id e por nome.", "parameters": [ { "name": "IDStockKeepingUnitProductionLine", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por id da linha." }, { "name": "ProductionLineName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por nome exato da linha." } ], "responses": { "200": { "description": "Lista de linhas de produção.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionLineListItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuProductionLinePost", "tags": [ "Produção" ], "summary": "Cria uma linha de produção", "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionLineCreate" } } }, "description": "Dados da linha de produção a cadastrar." }, "responses": { "200": { "description": "Linha criada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionLineListItem" } } } } }, "400": { "description": "`[BadRequest] - Empresa não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/production/line/{idstockkeepingunitproductionline}": { "parameters": [ { "name": "idstockkeepingunitproductionline", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da linha de produção." } ], "put": { "operationId": "skuProductionLinePut", "tags": [ "Produção" ], "summary": "Atualiza uma linha de produção", "description": "Atualiza o nome (`ProductionLineName`) e/ou a flag de padrão (`Default`). 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. Devolve a lista atualizada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionLineUpdate" } } }, "description": "Atualiza a linha de produção." }, "responses": { "200": { "description": "Linha atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionLineListItem" } } } } }, "400": { "description": "`[BadRequest] - Linha de produção não existe`; `[BadRequest] - É preciso ter uma linha de produção padrão`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuProductionLineDelete", "tags": [ "Produção" ], "summary": "Exclui uma linha de produção", "description": "**Remove fisicamente** o registro. Bloqueado quando a linha **ainda tem etapas** cadastradas (precisa excluir etapas antes) ou **produtos vinculados** (precisa desvincular no cadastro do produto antes). Devolve a string `\"Sucesso\"` no caso de sucesso.", "responses": { "200": { "description": "Linha excluída.", "content": { "application/json": { "schema": { "type": "string", "enum": [ "Sucesso" ] } } } }, "400": { "description": "`[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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/production/line/{idstockkeepingunitproductionline}/steps": { "parameters": [ { "name": "idstockkeepingunitproductionline", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da linha de produção." } ], "post": { "operationId": "skuProductionLineStepPost", "tags": [ "Produção" ], "summary": "Cria uma etapa em uma linha de produção", "description": "Adiciona uma etapa à linha. Etapas são ordenadas por `ProductionLineStepOrder` (decimal — permite inserir entre etapas existentes com `1.5`). Devolve a lista atualizada de linhas.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionLineStepCreate" } } }, "description": "Adiciona uma etapa à linha de produção (ex.: Corte, Costura)." }, "responses": { "200": { "description": "Etapa criada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionLineListItem" } } } } }, "400": { "description": "`[BadRequest] - Linha de produção não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/production/line/{idstockkeepingunitproductionline}/steps/{idstockkeepingunitproductionlinesteps}": { "parameters": [ { "name": "idstockkeepingunitproductionline", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da linha." }, { "name": "idstockkeepingunitproductionlinesteps", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da etapa." } ], "put": { "operationId": "skuProductionLineStepPut", "tags": [ "Produção" ], "summary": "Atualiza uma etapa de uma linha", "description": "Atualiza nome e/ou ordem da etapa. Devolve a lista atualizada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionLineStepCreate" } } }, "description": "Atualiza o nome da etapa da linha de produção." }, "responses": { "200": { "description": "Etapa atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionLineListItem" } } } } }, "400": { "description": "`[BadRequest] - Etapa da linha de produção não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuProductionLineStepDelete", "tags": [ "Produção" ], "summary": "Remove uma etapa de uma linha", "description": "Exclui fisicamente a etapa. Atenção: ordens de produção criadas antes mantêm as etapas que foram copiadas no momento da criação. Devolve a lista atualizada.", "responses": { "200": { "description": "Etapa removida.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductionLineListItem" } } } } }, "400": { "description": "`[BadRequest] - Etapa da linha de produção não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/carrier/tracking-template": { "get": { "operationId": "trackingTemplateList", "tags": [ "Templates de Rastreamento" ], "summary": "Lista templates de Mensagem Tracking", "description": "Retorna os templates de mensagem tracking ativos 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 do pedido (`IDCompanyIntegrationOrderList`) e tipo de pedido (`IDTypeOrderList`) devolvidas como arrays a partir do CSV armazenado no banco.", "parameters": [ { "name": "IDCarrierTrackingTemplate", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por id específico do template." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Página dos resultados, começando em `0`. Cada página retorna até 1000 templates: `Page=0` traz os primeiros 1000, `Page=1` os 1000 seguintes, e assim por diante. Se omitido ou vazio, assume `0`." } ], "responses": { "200": { "description": "Uma página de templates, com até 1000 itens.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingTemplateListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "trackingTemplatePost", "tags": [ "Templates de Rastreamento" ], "summary": "Cria um template de Mensagem Tracking", "description": "Cria um template para a empresa autenticada. Validações:\n- `CC` e `CCO` (quando preenchidos) precisam ter e-mails válidos separados por vírgula.\n- `IDCompanyIntegration` (integração de mensagem — e-mail/WhatsApp) precisa pertencer à empresa autenticada.\n- `IDCompanyIntegrationOrderList` (integrações que originam pedidos) e `IDTypeOrderList` (tipos de pedido) precisam existir para a empresa e estar ativos.\n\nDepois de salvar, devolve o detalhe do template recém-criado (formato da listagem). Não há `Lista de status de tracking` no body — o sistema aceita qualquer valor numérico em `IDStatusTracking`, mas a UI usa `TypeStatusTracking` (1=Finalizado, 2=Em andamento, 3=Atenção, 4=Não iniciado, 5=Saiu para entrega, 6=Extraviado, 7=Devolvido, 8=Postado).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingTemplateCreate" } } }, "description": "Cria um template de rastreio (regra de disparo de mensagem amarrada a um macro status de tracking). Validações executadas: cada e-mail em `CC` e `CCO` é validado por regex; quando `IDCompanyIntegration` for enviado precisa pertencer à empresa; `IDCompanyIntegrationOrderList` aceita lista de integrações de origem (validadas com `Show = 1`); `IDTypeOrderList` aceita lista de tipos de pedido (validados com `Status = 1`). Ambas as listas aceitam array ou string separada por vírgula — o sistema normaliza para CSV antes de gravar. Quando vazias, o template dispara para todas as integrações/tipos de pedido." }, "responses": { "200": { "description": "Template criado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingTemplateListItem" }, "maxItems": 1 } } } }, "400": { "description": "Validações: `[BadRequest] - Email CCO não é válido `; `[BadRequest] - Empresa não existe`; `[BadRequest] - Integração não existe`; `[BadRequest] - Integração(s) não localizada(s): `; `[BadRequest] - Tipo pedido(s) não localizado(s): `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/carrier/tracking-template/{idcarriertrackingtemplate}": { "parameters": [ { "name": "idcarriertrackingtemplate", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do template." } ], "put": { "operationId": "trackingTemplatePut", "tags": [ "Templates de Rastreamento" ], "summary": "Atualiza um template de Mensagem Tracking", "description": "Atualiza um template existente. **Atualização parcial** — somente os campos enviados são alterados. Aplica as mesmas validações do POST para `CC`, `CCO`, `IDCompanyIntegration`, `IDCompanyIntegrationOrderList` e `IDTypeOrderList`. A resposta repete o formato da listagem com o detalhe atualizado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingTemplateUpdate" } } }, "description": "Atualização parcial — apenas campos enviados são alterados. Mesmas validações do `POST` (regex de e-mail em `CC`/`CCO`, existência de `IDCompanyIntegration`, integrações de origem com `Show=1`, tipos de pedido com `Status=1`)." }, "responses": { "200": { "description": "Template atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingTemplateListItem" }, "maxItems": 1 } } } }, "400": { "description": "Validações: `[BadRequest] - Tracking template não existe`; `[BadRequest] - Email CCO não é válido `; `[BadRequest] - Integração tipo mensagem não existe`; `[BadRequest] - Integração(s) não localizada(s): `; `[BadRequest] - Tipo pedido(s) não localizado(s): `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "trackingTemplateDelete", "tags": [ "Templates de Rastreamento" ], "summary": "Exclui um template de Mensagem Tracking", "description": "**Remove fisicamente** o template (exclusão definitiva, sem soft delete nem histórico). Não há regras de bloqueio. Devolve a string literal `\"Sucesso!\"`.", "responses": { "200": { "description": "Template excluído.", "content": { "application/json": { "schema": { "type": "string", "enum": [ "Sucesso!" ] } } } }, "400": { "description": "`[BadRequest] - IDCarrierTrackingTemplate não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/carrier/quotation/rule": { "get": { "operationId": "carrierQuotationRuleList", "tags": [ "Cotação de Frete" ], "summary": "Lista regras de simulação de frete", "description": "Retorna as regras da empresa **ordenadas por `Priority` crescente** e, em empate, por `IDCarrierQuotationRule` DESC (até 1000 itens). Inclui regras Ativas (`Status=1`) e Inativas (`Status=0`), mas oculta as Excluídas (`Status=2`). Cada item já vem com `ConditionsRules` (array de condições com `ConditionValue` quebrado em vetor pelo separador `,`), `ConditionNames` (string concatenada com nomes das condições, usada na grid) e `CarrierQuotationRuleLog` (histórico de alterações em formato `DE: PARA: `).", "responses": { "200": { "description": "Lista das regras (até 1000).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotationRuleListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } }, "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Índice da página para paginação, começando em `0`. Cada página retorna até 1000 regras; informe `1` para as próximas 1000, e assim por diante. Quando omitido, assume `0` (primeira página)." } ] }, "post": { "operationId": "carrierQuotationRulePost", "tags": [ "Cotação de Frete" ], "summary": "Cria uma regra de simulação de frete", "description": "Cria uma regra para a empresa autenticada, com 1+ condições e 1 ação. O sistema valida cada condição pelo `IDTypeCarrierQuotationConditionRule` informado:\n\n- **1 — Estado/Região**: cada item é a sigla UF (2 letras) opcionalmente concatenada com `CAPITAL` ou `INTERIOR` (ex.: `SP`, `SPCAPITAL`, `RJINTERIOR`). UFs aceitas: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO.\n- **2 — CEP Destino** e **10 — CEP Origem**: cada item é a faixa `|`, sem hífens, 8 dígitos cada. `CEPDe` precisa ser **menor** que `CEPAté`.\n- **3 — Transportadora**: cada item é o `IDSupplier` de um fornecedor da empresa com `IDTypeSupplier=2` (Transportadora). Quando a ação é `9` (Excluir transportadoras), a condição 3 é **obrigatória** e a UI marca automaticamente.\n- **4 — Valor do pedido**: cada item é a faixa `|` em reais. `ValorDe` precisa ser **menor** que `ValorAté`, ambos ≥ 0.\n- **6 — Integração**: cada item é o `IDCompanyIntegration` de uma integração configurada pela empresa.\n- **7 — Peso (kg)**: cada item é a faixa `|` em kg.\n- **8 — SKUs iguais a** e **9 — SKUs diferentes de**: cada item tem o formato `|`. Não há validação de existência do SKU no sistema.\n\nA regra passa a valer imediatamente para a próxima cotação. Devolve o detalhe da regra recém-criada (formato do GET por id).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierQuotationRuleCreate" } } }, "description": "Cria uma regra de simulação de frete. Toda regra precisa de pelo menos uma condição. O `ConditionValue` é validado de acordo com o tipo da condição: estados pelo cadastro oficial; faixas de CEP exigem 8 dígitos e `cepInicial < cepFinal`; transportadoras precisam existir como `Suppliers` da empresa com `IDTypeSupplier=2`; faixas de valor exigem `de < até` ambos positivos; integrações precisam pertencer à empresa. A regra passa a valer imediatamente para a próxima cotação (`POST /carrier/quotation`)." }, "responses": { "200": { "description": "Regra criada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotationRuleDetail" }, "maxItems": 1 } } } }, "400": { "description": "Validações: `[BadRequest] - Empresa não existe`; `[BadRequest] - Ação inativa ou não existe`; `[BadRequest] - Estado não encontrado`; `[BadRequest] - Faixa de cep - inválida`; `[BadRequest] - ID da transportadora não encontrado`; `[BadRequest] - Preço | inválido, preço De precisa ser menor que preço Para`; `[BadRequest] - ID da integração não encontrado`; `[BadRequest] - Falha ao adicionar regra de cotação`; `[BadRequest] - Falha ao adicionar condições da regra de cotação`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/carrier/quotation/rule/{idcarrierquotationrule}": { "parameters": [ { "name": "idcarrierquotationrule", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da regra." } ], "get": { "operationId": "carrierQuotationRuleGet", "tags": [ "Cotação de Frete" ], "summary": "Detalha uma regra de simulação de frete", "description": "Retorna a regra completa: cabeçalho (`CarrierQuotationRuleName`, `Priority`, `Status`, `DateFrom`, `DateTo`, ação e valor), `ConditionsRules` com cada condição quebrada em vetor pelo separador `,`, e `CarrierQuotationRuleLog` ordenado por `IDCarrierQuotationRuleLog` DESC (histórico de alterações em formato `DE: PARA: ` e `_Adicionado` / `_Removido`).", "responses": { "200": { "description": "Detalhe da regra.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotationRuleDetail" }, "maxItems": 1 } } } }, "400": { "description": "`[BadRequest] - Regra de cotação não encontrada`; `[BadRequest] - Parâmetros inválidos`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "carrierQuotationRulePut", "tags": [ "Cotação de Frete" ], "summary": "Atualiza uma regra de simulação de frete", "description": "**Atualização total** do cabeçalho (`CarrierQuotationRuleName`, `Priority`, `Status`, `DateFrom`, `DateTo`, `IDTypeCarrierQuotationActionRule`, `ActionValue`) — campos que não vêm no body são gravados como NULL. As **condições** seguem a lógica de diff: o sistema compara `Conditions` com o que já está em `CarrierQuotationRuleCondition` e:\n\n- Insere o que está no body e não existe (grava `_Adicionado` no log).\n- Apaga o que existe e não veio no body (grava `_Removido` no log).\n- Mantém o que já estava igual.\n\nQualquer mudança de campo do cabeçalho gera linha no log no formato `DE: PARA: `. Datas são comparadas truncadas para `YYYY-MM-DD`. As alterações passam a valer imediatamente. Devolve o detalhe da regra atualizada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierQuotationRuleUpdate" } } }, "description": "Atualiza a regra. **Não é atualização parcial** — campos do cabeçalho ausentes são gravados como `NULL`. Para `Conditions`, é feito diff: condições novas são inseridas e ausentes são removidas. As mudanças passam a valer imediatamente." }, "responses": { "200": { "description": "Regra atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotationRuleDetail" }, "maxItems": 1 } } } }, "400": { "description": "Validações: `[BadRequest] - Regra de cotação não existe`; `[BadRequest] - Estado não encontrado`; `[BadRequest] - Faixa de cep - inválida`; `[BadRequest] - ID da transportadora não encontrado`; `[BadRequest] - Preço | inválido, preço De precisa ser menor que preço Até`; `[BadRequest] - ID da integração não encontrado`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "carrierQuotationRuleDelete", "tags": [ "Cotação de Frete" ], "summary": "Exclui uma regra de simulação de frete", "description": "**Soft delete** — marca a regra com `Status = 2` (Excluída). A regra deixa de aparecer na listagem (que só traz `Status IN (0,1)`) e deixa de ser usada nas próximas cotações. Devolve a string literal `\"Sucesso!\"`.", "responses": { "200": { "description": "Regra excluída.", "content": { "application/json": { "schema": { "type": "string", "enum": [ "Sucesso!" ] } } } }, "400": { "description": "`[BadRequest] - Regra de cotação não existe`; `[BadRequest] - Erro ao e executar ação`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/carrier/quotation": { "get": { "operationId": "carrierQuotationList", "tags": [ "Cotação de Frete" ], "summary": "Lista simulações de frete", "description": "Lista as simulações de frete já feitas pela empresa, ordenadas por `IDCarrierQuotation` DESC (até 5000 por página). Cada item traz cabeçalho da simulação (CEP destino, peso, dimensões totais, valor da nota, usuário que rodou, integração de origem quando veio de canal externo) e o resumo das transportadoras que responderam (`CarriersName` — lista de razões sociais separadas por vírgula).\n\nNão devolve as linhas detalhadas de cada transportadora — para isso use `GET /carrier/quotation/{idcarrierquotation}`.", "parameters": [ { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra `RecordTimestamp` ≥ esta data." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra `RecordTimestamp` ≤ esta data 23:59:59." }, { "name": "ShippingPostalCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por CEP destino (apenas dígitos; pontuação é ignorada na comparação)." }, { "name": "Description", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca parcial (`LIKE`) por descrição." }, { "name": "IDCarrierQuotation", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por id da simulação." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra simulações originadas de uma integração específica." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Página de paginação (offset = `Page * 5000`)." } ], "responses": { "200": { "description": "Lista das simulações (até 5000 por página).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotationListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "carrierQuotationPost", "tags": [ "Cotação de Frete" ], "summary": "Roda uma simulação de frete", "description": "Roda uma cotação para o CEP destino + lista de volumes/produtos.\n\nValidações iniciais (retornam 400):\n- `ShippingPostalCode` precisa estar preenchido.\n- Pelo menos 1 item em `Quotations` com `Weight > 0`.\n- CEP precisa existir na base de CEPs (caso contrário grava erro tipo `3` em `CarrierQuotationError`).\n\nLógica:\n- Peso total = soma dos `Weight` de cada item.\n- Largura total = soma dos `Width`.\n- Altura e comprimento totais = **máximo** entre os itens.\n- Para cada transportadora ativa de leilão de frete (`CarrierAuction = 1`):\n - Calcula cubagem usando `CarrierCubageKmM` (padrão 167) e compara com `CarrierCubageFreeWeight` para definir `WeightSelected` (peso real ou cubado).\n - Busca a faixa de CEP em `CarrierScope`; se não atende, marca `Attended=0`.\n - Busca preço em `CarrierRate` por `RateType` + `WeightFrom/WeightTo`; quando o peso excede a maior faixa e existe entrada com `WeightTo=-1`, extrapola linearmente.\n - Soma componentes do frete (rate, gris, advalorem, pedágio, taxas de difícil acesso, despacho, etc.) → subtotal.\n - Aplica ICMS interestadual (se origem e destino diferem de estado **e** transportadora não tem `CarrierICMSIncluded`).\n - Aplica `CarrierAuctionPenalty` da transportadora e regras de **Regras Simulação Frete** (adição de dias e/ou valor).\n- Persiste cabeçalho em `CarrierQuotation` e linhas em `CarrierQuotationRate`.\n\nDevolve um array com 1 item: o detalhe da simulação criada (mesmo formato do GET por id).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierQuotationCreate" } } }, "description": "Simula frete para um destino. Mínimo: `ShippingPostalCode` (CEP destino) e `Quotations[]` com `Weight`, `Height`, `Width` e `Length` por volume. O sistema padroniza o CEP em 8 dígitos com zero à esquerda, agrega medidas (soma peso/largura/valor da nota, pega maior altura/comprimento, conta volumes) e percorre todas as transportadoras ativas da empresa com gateway interno (`IDCarrierGateway=1`). Para cada transportadora aplica regras de cubagem, tabela de preços por faixa de peso, Gris, Advalorem, TDE, pedágio, ICMS interestadual e demais taxas. Depois aplica as regras de simulação cadastradas (`POST /carrier/quotation/rule`) na ordem da `Priority`. A resposta vem ordenada por atendimento e prazo crescente. Quando `IDOrder` é enviado e já existe uma simulação para esse pedido, o registro existente é reaproveitado. Quando chamado por integração de marketplace (Mercado Livre, Tray, Convertize etc.), o sistema adapta o corpo de resposta ao formato do canal. CEP destino inexistente gera entrada em `GET /carrier/quotation/error` (tipo `3` Cep não localizado)." }, "responses": { "200": { "description": "Simulação criada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotationDetail" }, "maxItems": 1 } } } }, "400": { "description": "`Precisa enviar o CEP destino`; `Peso precisa ser maior que zero`; `Dados para cotação não enviados`; `CEP destino não existe`; `Empresa não localizada (2)`. (Mensagens sem o prefixo `[BadRequest]`.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/carrier/quotation/{idcarrierquotation}": { "parameters": [ { "name": "idcarrierquotation", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da simulação." } ], "get": { "operationId": "carrierQuotationGet", "tags": [ "Cotação de Frete" ], "summary": "Detalha uma simulação de frete", "description": "Retorna a simulação com **todas** as linhas por transportadora. Cada linha (`CarrierQuotations[]`) traz:\n\n- `IDCarrier` + `SupplierNameCorporateName` + `CarrierLogoUrl` + `CarrierModal` (modalidade da transportadora).\n- `Attended` (1=Atende, 0=Não atende, 3=Excluído por regra, 4=Fora da faixa) e `AttendedDescription` (texto pronto para exibição).\n- Componentes do preço: `ShipingValue`, `GrisValue`, `AdvaloremValue`, `TollValue`, `AccessDifficultyRateValue`, `DispatchFeeValue`, `DeliveryDifficultyRateValue`, `SECCATValue`, `TollFractionValue`, `TrafficRestrictionFeeValue`, `AdministrationFeeValue`, `CTEFeeValue`, `SUFRAMAFeeValue`, `FluvialInsuranceFee`, `OtherFee`, `OtherFeeValue`, `IcmsValue`.\n- Totais calculados pelo sistema: `SubtotalShippingValue` (soma dos componentes), `TotalShippingValue` (subtotal + ICMS), `IcmsValuePercent`, `ShippingShowValue` (total + ajustes de regra + `PriceRounding`).\n- Prazo: `DaysTime` (transportadora) + `CarrierAdditionalBusinessDays` (transportadora) + `CutDaysTime` (1 quando saiu fora do horário de corte) + `RuleAdditionalDays` (regra) → `TotalDaysTime` / `TotalShowDaysTime`.\n- Cubagem: `WeightCubed`, `WeightSelected`, `CarrierCubageKmM`, `CarrierCubageFreeWeight`.\n- Quando regras de simulação foram aplicadas: `CarrierQuotationRuleValueName`, `CarrierQuotationRuleDaysName`, `RuleAdditionalValue`, `RuleAdditionalDays`.\n\nOrdenação: `Attended DESC` (quem atende primeiro), `TotalDaysTime ASC` (prazo curto primeiro), `TotalShippingValue ASC` (preço baixo).", "responses": { "200": { "description": "Detalhe da simulação. `[]` quando o id não existe ou pertence a outra empresa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotationDetail" }, "maxItems": 1 } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/orders": { "get": { "operationId": "ordersList", "tags": [ "Pedidos" ], "summary": "Lista pedidos", "description": "Lista os pedidos da empresa autenticada — endpoint compartilhado entre **Outbound** (default `IDStatusOrder=1` + `OrderBy=ASC`), **Pedidos**, **Retirada em Mãos** (`IDStatusOrder=17&Budget=0&SkuView=0`) e demais telas que listam pedidos. Paginação fixa em **2000 registros por página** (`Page=N` → offset `N*2000`).\n\n**Etapas internas** (`OrdersGet`):\n\n1. Resolve `IDCompany` a partir do prefix da conta + `accountname` do header. Quando o usuário tem mais de uma conta vinculada, busca a posição correspondente em `IDCompanyList` (CSV indexado por `accountnamelist`).\n2. Se o usuário tem **centros de distribuição vinculados**, restringe à lista dele. Querystring `IDStockKeepingUnitDistributionCenter` é validada contra essa lista — se não pertence, retorna `[]` imediatamente.\n3. Quando `Search` é informado, limita `IDOrder` aos últimos 3 meses (busca rápida só varre essa janela).\n4. Quando o usuário é vendedor (`Salesman=1`) com `restrictaccesssalesman=1`, restringe aos pedidos cujos consumidores estão vinculados ao usuário em `ConsumerSalesman`.\n5. Em duas etapas: primeiro resolve os `IDOrder` paginados (2000 por página); depois carrega cada pedido completo com todos os dados resolvidos (status, integração, nota fiscal, transportadora, faturador, CD).\n6. `SkuView=1` muda o segundo passo para retornar `Items` agregados (array JSON de SKUs do pedido com nome, quantidade, valor unitário, kit, inconformidade e imagem principal) em vez das colunas planas. Frontend usa para preview de linha expandida.\n\n**Busca rápida (`Search`)** — quando informada, casa contra qualquer um dos campos:\n- `Order`.\n- `ConsumerNameCorporateName` / `ShippingReceiverName` (exige ≥4 caracteres alfabéticos).\n- `ConsumerEmail`.\n- `ConsumerCpfCnpj` (apenas dígitos, comprimento entre 11 e 14).\n- `NfeNumber` (apenas dígitos, ≤9).\n- `IDOrder` (apenas dígitos, ≤11).\n- `OrderFrom` (qualquer marketplace).\n- `PackId` (apenas dígitos com comprimento > 15).\n\n**Endpoint compartilhado por várias telas** — esta documentação cobre o conjunto **completo** de querystrings; cada tela usa um subconjunto.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Página (0-indexada). Offset aplicado = `Page * 2000`." }, { "name": "OrderBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" }, "description": "Direção de ordenação por `IDOrder`. O Outbound passa `OrderBy=ASC` por padrão para mostrar os pedidos mais antigos primeiro." }, { "name": "OrderByRule", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "SkuNameAsc", "SkuNameDesc", "IDSkuCompanyAsc", "IDSkuCompanyDesc" ] }, "description": "`1` adiciona à resposta o campo `OrderByRule` com os 2 primeiros nomes/códigos de SKU do pedido (em ordem ascendente). Frontend usa para ordenar a tela pela coluna escolhida." }, { "name": "Search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca rápida unificada. Pesquisa simultaneamente em `Order`, `ConsumerNameCorporateName`, `ShippingReceiverName`, `ConsumerEmail`, `ConsumerCpfCnpj`, `NfeNumber`, `IDOrder`, `OrderFrom` e `PackId`. Limita a varredura aos últimos 3 meses (`IDOrder ≥ IDOrderThreeMonthsAgo`)." }, { "name": "SkuView", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "`1` faz a resposta incluir o agregado `Items` (array de SKUs do pedido com nome, quantidade, valor, kit, inconformidade e imagem principal). Frontend usa para expandir linha. Sem esta flag, a resposta vem com colunas planas." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra pedidos com `RecordTimestamp` a partir desta data (inclusive) — data de criação do pedido." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra pedidos com `RecordTimestamp` até o final desta data (inclusive) — data de criação do pedido." }, { "name": "InvoiceDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra pedidos com `NfedhEmi` (data de emissão da NF principal) a partir desta data (inclusive)." }, { "name": "InvoiceDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra pedidos com `NfedhEmi` (data de emissão da NF principal) até o final desta data (inclusive)." }, { "name": "ShippingDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Existe pelo menos um `ShippingDate` ≥ data para o pedido." }, { "name": "ShippingDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Existe pelo menos um `ShippingDate` ≤ data + ` 23:59:59`." }, { "name": "ShippingHandlingLimitDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`ShippingEstimateHandlingLimitDate` ≥ data. Aplicável apenas a pedidos integrados (data estimada de expedição vinda do canal — usado principalmente pelo Mercado Livre)." }, { "name": "ShippingHandlingLimitDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`ShippingEstimateHandlingLimitDate` ≤ data." }, { "name": "ShippingEstimateDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`ShippingEstimateDate` ≥ data (data prevista de entrega ao cliente)." }, { "name": "ShippingEstimateDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`ShippingEstimateDate` ≤ data + ` 23:59:59`." }, { "name": "SinceRecordTimestamp", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "`RecordTimestamp` ≥ timestamp. Útil para sincronizações incrementais (consumidores externos)." }, { "name": "SinceDateLastRecordModification", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "`DateLastRecordModification` ≥ timestamp. Pega pedidos modificados depois do timestamp." }, { "name": "IDStatusOrder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Status do pedido. Aceita CSV (`IDStatusOrder=1,4,21`). Valores em `TypeStatusOrder` — ver tabela completa em `support data/TypeStatusOrder.csv`." }, { "name": "IDStatusInvoice", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Status da nota fiscal principal (`IDStatusInvoice`). CSV. Quando contém o valor `0`, expande para incluir também pedidos **sem NF** (`NOT EXISTS` em `NfCompany`)." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código interno do pedido. CSV aceito (`IDOrder=1234,5678`)." }, { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Número do pedido (`Order`). Aceita múltiplos valores separados por vírgula ou espaço (ex.: `OT-1234,ML-5648`)." }, { "name": "OrderFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Número do pedido no canal de origem (`OrderFrom`). CSV aceito." }, { "name": "Budget", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`Budget`. `0` = pedido firme, `1` = orçamento. Tela de Pedidos passa `Budget=0`." }, { "name": "BalanceChange", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Tipo: `1` = pedido que movimenta estoque, `0` = nota fiscal sem movimento de estoque." }, { "name": "NfeNoPayment", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`NfeNoPayment=1` filtra pedidos cuja NF foi emitida sem pagamento associado." }, { "name": "IDCarrier", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Transportadora (`IDCarrier` → `IDSupplier`). CSV aceito." }, { "name": "IDOrderType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tipo de pedido (`IDOrderType` → `TypeOrder`). CSV aceito." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Conta de integração vinculada ao pedido (`IDCompanyIntegration`). CSV aceito." }, { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tipo de integração / canal de vendas (`IDTypeCompanyIntegration`). CSV aceito." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Empresa faturadora do pedido (`IDCompanyInvoice`)." }, { "name": "IDSalesman", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Vendedor responsável pelo pedido (`IDSalesman` → `IDUser`)." }, { "name": "IDConsumer", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Cliente do pedido (`IDConsumer`)." }, { "name": "IDTypeOrderReturn", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Motivo de devolução. CSV aceito (`IDTypeOrderReturn`)." }, { "name": "IDPickingList", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pedidos vinculados a esta(s) picking-list(s). CSV aceito." }, { "name": "IDOrdersCarrierCollectionList", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pedidos vinculados a este(s) romaneio(s). CSV aceito." }, { "name": "nullCollection", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` filtra apenas pedidos sem romaneio (`IDOrdersCarrierCollectionList IS NULL`)." }, { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Centro de distribuição. CSV aceito. Validado contra a lista de CDs vinculados ao usuário; se o usuário tem restrição e o valor não pertence, a resposta volta vazia." }, { "name": "IDStockKeepingUnitWarehouse", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Armazém. Filtra pedidos que têm pelo menos um item vinculado ao armazém (via `StockKeepingUnitMovement`)." }, { "name": "IDSku", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Pedidos que contêm o SKU informado (verificado em `StockKeepingUnitMovement`)." }, { "name": "IDSkuCompany", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pedidos que contêm um SKU com o código de referência informado (`IDSkuCompany`)." }, { "name": "ConsumerNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome / razão social do cliente (LIKE em `ConsumerNameCorporateName`)." }, { "name": "ConsumerCpfCnpj", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CPF ou CNPJ do cliente. Aceita formato com pontuação — o sistema normaliza para apenas dígitos antes de comparar." }, { "name": "ConsumerEmail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "E-mail do cliente (LIKE em `ConsumerEmail`)." }, { "name": "ConsumerTelephone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Telefone do cliente. O sistema normaliza para apenas dígitos antes de comparar." }, { "name": "NfeNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Número da nota fiscal principal (`NfeNumber`). CSV aceito (`NfeNumber=1234,5678`)." }, { "name": "NfeSerie", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Série da nota fiscal principal (`NfeSerie`)." }, { "name": "NfeChaveAcesso", "in": "query", "required": false, "schema": { "type": "string", "minLength": 44, "maxLength": 44 }, "description": "Chave de acesso da NF-e (44 dígitos). Busca exata em `NfeChaveAcesso`." }, { "name": "ShippingId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código de rastreio. Filtra pedidos que têm um `ShippingId` correspondente." }, { "name": "ShippingPostalCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CEP do destinatário (`ShippingPostalCode`)." }, { "name": "ShippingState", "in": "query", "required": false, "schema": { "type": "string" }, "description": "UF do destinatário (`ShippingState`). CSV aceito." }, { "name": "ValueOrderFrom", "in": "query", "required": false, "schema": { "type": "number", "format": "double" }, "description": "Valor mínimo do pedido (soma dos itens + frete + acessórios)." }, { "name": "ValueOrderTo", "in": "query", "required": false, "schema": { "type": "number", "format": "double" }, "description": "Valor máximo do pedido." }, { "name": "OrderPriority", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Prioridade do pedido (`OrderPriority`)." }, { "name": "OrdersSalesChannelLabelStatus", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Status da etiqueta no canal de venda (`Header`)." }, { "name": "Tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pedidos que têm a tag informada em `Tag`." }, { "name": "IncludeValueDashboard", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra pelo flag `IncludeValueDashboard` do tipo de pedido." }, { "name": "ServiceRequest", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra pelo flag `ServiceRequest` do tipo de pedido (pedidos de serviço)." }, { "name": "PickingListBasketExternalId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cesto da picking-list (`ExternalId`). Usado quando a tela mostra pedidos amarrados a um cesto físico bipado." }, { "name": "IDStoreFrontCashier", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Caixa do PDV (`IDStoreFrontCashier`). Filtra pedidos lançados em um caixa específico." }, { "name": "LastID", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Cursor de paginacao por chave. Quando informado, a listagem ignora o deslocamento de Page e retorna os 2000 pedidos seguintes com IDOrder maior que este valor (quando OrderBy=ASC) ou menor (quando OrderBy=DESC). Use o IDOrder do ultimo item da pagina anterior para percorrer grandes volumes de forma incremental." } ], "responses": { "200": { "description": "Array de pedidos. Retorna até 2000 itens por página. Cada item traz o pedido + status + integração + NF principal + transportadora + faturador + CD. Quando `SkuView=1`, traz também o array `Items` com os SKUs do pedido. Quando nenhum pedido casa com os filtros, retorna `[]` (com `200`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrdersListItem" } } } } } } }, "post": { "operationId": "ordersCreate", "tags": [ "Pedidos" ], "summary": "Cria pedido", "description": "Cria um pedido da empresa autenticada — endpoint **compartilhado** por todas as telas que criam pedidos (**Pedidos**, **PDV/Store Front**, **Ordem de serviço**, devolução/Reversa, importação). A tela de **Ordem de serviço** usa este mesmo endpoint enviando o tipo de pedido marcado como ordem de serviço; o subconjunto de campos enviado por cada tela varia.\n\n**O que o endpoint faz:**\n\n1. Resolve a empresa a partir do token e, quando `ShareDataWithRelatedCompanies=1`, o grupo de empresas relacionadas.\n2. Valida tipo de pedido, vendedor, centro de distribuição, integração, cliente e endereços; monta itens, pagamentos e dados fiscais e grava o pedido.\n3. Quando o tipo de pedido emite NFCe (PDV), o pedido já nasce como `StoreFrontOrder=1`.\n4. Retorna a ficha completa do pedido recém-criado, acrescentando `Danfe65Base64Encode` (PDF da DANFE NFCe em base64, quando houver).\n\n**Campos obrigatórios** dependem do tipo de pedido e das parametrizações da empresa: há fallbacks para tipo de pedido padrão, centro de distribuição padrão e vendedor automático (`AutomaticSetSalesmanNewOrder`). O `required` abaixo reflete o conjunto exigido pelo fluxo de criação padrão do frontend.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDOrderType", "IDSalesman", "IDStockKeepingUnitDistributionCenter", "IDConsumer", "IDAddress", "ShippingEstimateDate" ], "properties": { "IDOrderType": { "type": "integer", "format": "int64", "description": "Tipo de pedido. Na criacao de ordem de servico, apenas os tipos marcados como ordem de servico. Sem valor, usa o tipo de pedido padrao da empresa; se nao houver padrao, retorna 400." }, "IDSalesman": { "type": "integer", "format": "int64", "description": "Vendedor responsavel (na ordem de servico, o tecnico responsavel). Quando ausente e a empresa usa atribuicao automatica de vendedor, e preenchido pelo sistema." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "format": "int64", "description": "Centro de distribuicao de onde o pedido sera atendido. Sem valor, usa o centro de distribuicao padrao da empresa; se nao houver padrao, retorna 400." }, "IDConsumer": { "type": "integer", "format": "int64", "description": "Cliente do pedido. Deve estar cadastrado para a empresa." }, "IDAddress": { "type": "integer", "format": "int64", "description": "Endereco de cobranca do cliente (IDConsumer)." }, "IDAddressDelivery": { "type": "integer", "format": "int64", "description": "Endereco de entrega, quando diferente do endereco de cobranca." }, "ShippingEstimateDate": { "type": "string", "format": "date-time", "description": "Data/hora prevista para entrega/atendimento (na ordem de servico, a data de previsao do atendimento)." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integracao de origem do pedido. Quando o tipo de pedido exige integracao e o valor nao e informado, retorna 400." }, "IDCompanyInvoice": { "type": "integer", "format": "int64", "description": "Empresa faturadora, quando diferente da empresa do pedido." }, "Order": { "type": "string", "description": "Numero/identificador externo do pedido. Quando ausente, o sistema gera a numeracao." }, "OrderComments": { "type": "string", "description": "Observacao do pedido (texto livre)." }, "OrderFrom": { "type": "string", "description": "Origem do pedido (canal/marketplace de procedencia), quando aplicavel." }, "OrderGift": { "type": "integer", "description": "1 marca o pedido como presente." }, "Budget": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "1 cria o registro como orcamento (nao movimenta estoque ate a conversao)." }, "BalanceChange": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo do registro: 1 Pedido (movimenta estoque) x 0 Nota Fiscal (sem movimentacao)." }, "IDStatusOrder": { "type": "integer", "format": "int64", "description": "Status inicial do pedido. Sem valor, o pedido nasce em 0 (Aberto). Status invalido retorna 400." }, "IDServiceOrder": { "type": "integer", "format": "int64", "description": "Ordem de servico vinculada, quando o pedido e gerado a partir de uma OS existente." }, "ValueShipping": { "type": "number", "format": "double", "default": 0, "description": "Valor do frete do pedido." }, "IDCarrier": { "type": "integer", "format": "int64", "description": "Transportadora do pedido. Quando informada, deve estar cadastrada e ativa." }, "Consumer": { "type": "object", "description": "Dados do cliente para cadastro/atualizacao no ato da criacao (alternativa a informar um IDConsumer ja existente). Campos aceitos incluem ConsumerCpfCnpj, ConsumerNameCorporateName, ConsumerTradeName, ConsumerEmail, ConsumerTelephone, ConsumerType, Address e DeliveryAddress.", "additionalProperties": true }, "Invoice": { "type": "object", "description": "Dados da nota fiscal a emitir/vincular junto com o pedido. Campos aceitos incluem NfeNumber, NfeSerie, NfeChaveAcesso, NfeModelo, NfeTotalValue, NfedhEmi, NfecStat, NfenProt, NfetpEmis.", "additionalProperties": true }, "Tags": { "type": "array", "description": "Etiquetas/marcadores a vincular ao pedido.", "items": { "type": "object", "additionalProperties": true } }, "InvoiceType": { "type": "integer", "enum": [ 1, 2 ], "description": "Tipo de comprovante: 1 documento fiscal, 2 recibo." }, "IssueInvoice": { "type": "integer", "enum": [ 0, 1 ], "description": "1 solicita a emissao da nota fiscal ja na criacao do pedido." }, "NFCe": { "type": "integer", "enum": [ 0, 1 ], "description": "1 indica pedido com NFCe (PDV); forca StoreFrontOrder=1." }, "StoreFrontOrder": { "type": "integer", "enum": [ 0, 1 ], "description": "1 marca o pedido como originado no PDV/Store Front." }, "IDStoreFrontCashier": { "type": "integer", "format": "int64", "description": "Caixa do PDV em que o pedido foi lancado." }, "IDStoreFrontCashierOrderTemp": { "type": "integer", "format": "int64", "description": "Identificador temporario do pedido em aberto no caixa do PDV, usado para consolidar o lancamento." }, "IDOrderIntention": { "type": "integer", "format": "int64", "description": "Intencao de pedido (pre-pedido) a partir da qual este pedido e materializado." }, "IDTypeOrderReturn": { "type": "integer", "format": "int64", "description": "Motivo de devolucao. Obrigatorio quando o pedido e uma devolucao (Reversa)." }, "IDTypeOrderReturnCategory": { "type": "integer", "format": "int64", "enum": [ 1, 2, 3 ], "description": "Categoria de devolucao. Obrigatoria quando o pedido e uma devolucao (Reversa): 1=Troca/Vale, 2=Reembolso, 3=Insucesso de entrega." }, "IDOrderOriginReturn": { "type": "integer", "format": "int64", "description": "Pedido original que esta sendo devolvido (quando este pedido e a devolucao)." }, "IDStockKeepingUnitWarehouseReturn": { "type": "integer", "format": "int64", "description": "Armazem de retorno dos itens na devolucao." }, "ConsumerVoucher": { "type": "number", "format": "double", "description": "Valor de vale-compras do cliente aplicado ao pedido. Nao pode exceder o disponivel para a loja." }, "CreateInbound": { "type": "integer", "enum": [ 0, 1 ], "description": "1 gera tambem o recebimento (inbound) associado ao pedido." }, "SendEmail": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "1 dispara o e-mail de confirmacao ao cliente." }, "NFeFin": { "type": "string", "description": "Finalidade da NF-e (normal, complementar, ajuste, devolucao)." }, "NFeType": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo da NF-e: 0 entrada, 1 saida." }, "NfeindFinal": { "type": "integer", "description": "Indicador de consumidor final da NF-e." }, "NfeModFrete": { "type": "string", "description": "Modalidade de frete da NF-e." }, "NfeNatureOperation": { "type": "string", "description": "Natureza da operacao da NF-e." }, "NfeCfopPriority": { "type": "string", "description": "CFOP prioritario a aplicar na NF-e." }, "NfeComments": { "type": "string", "description": "Informacoes complementares da NF-e." }, "NfeAccessoryExpenses": { "type": "number", "format": "double", "default": 0, "description": "Despesas acessorias da NF-e." }, "NfeFactorPercent": { "type": "number", "format": "double", "description": "Percentual de fator aplicado no calculo da NF-e." }, "NfeNoPayment": { "type": "integer", "enum": [ 0, 1 ], "description": "1 permite faturar sem pagamento cadastrado (depende de privilegio); tambem ignora o array Payments." }, "NfeChaveAcessoDevolucao": { "type": "string", "description": "Chave de acesso da NF-e referenciada em devolucao." }, "ShippingEstimateHandlingLimitDate": { "type": "string", "format": "date-time", "description": "Data/hora limite estimada de expedicao (prazo de manuseio). Usada principalmente em pedidos integrados de canais de venda. Campo novo (adicionado em 2026-06-22)." }, "Items": { "type": "array", "description": "Itens do pedido. Podem ser enviados aqui na criacao ou pelos endpoints filhos de item.", "items": { "type": "object", "required": [ "IDSku", "Quantity" ], "properties": { "IDSku": { "type": "integer", "format": "int64", "description": "SKU do item. Deve estar cadastrado para a loja; item do tipo Produto (pai) nao pode ser adicionado ao pedido." }, "Quantity": { "type": "number", "format": "double", "description": "Quantidade do item." }, "PriceSelling": { "type": "number", "format": "double", "description": "Preco de venda unitario praticado no item." }, "OriginalPriceSelling": { "type": "number", "format": "double", "description": "Preco de venda unitario antes de desconto manual, usado no calculo do limite de desconto." }, "ValueDiscount": { "type": "number", "format": "double", "description": "Valor de desconto aplicado ao item." }, "ValueCost": { "type": "number", "format": "double", "description": "Custo unitario do item." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "format": "int64", "description": "Armazem de onde o item sai. Quando omitido, usa o armazem do tipo de pedido ou o armazem padrao da empresa. Deve pertencer ao centro de distribuicao do pedido." }, "IDCompanySalesPolicy": { "type": "integer", "format": "int64", "description": "Politica comercial usada para buscar o preco de lista/tabela do item." }, "IDUserDiscount": { "type": "integer", "format": "int64", "description": "Usuario que concede o desconto; usado para validar o limite de desconto permitido." }, "IDStockKeepingUnitPromotion": { "type": "integer", "format": "int64", "description": "Promocao aplicada ao item (dispensa a validacao de limite de desconto manual)." }, "IDTypeOrderReturn": { "type": "integer", "format": "int64", "description": "Motivo de devolucao especifico do item (em pedidos de devolucao)." }, "IDPurchase": { "type": "integer", "format": "int64", "description": "Compra vinculada ao item, quando aplicavel." }, "BalanceChange": { "type": "integer", "enum": [ 0, 1 ], "description": "1 movimenta estoque para o item; 0 nao movimenta." } } } }, "Payments": { "type": "array", "description": "Pagamentos do pedido. Ignorados quando NfeNoPayment=1. A soma dos Value compoe o total de pagamento do pedido.", "items": { "type": "object", "required": [ "Value" ], "properties": { "IDTypePayment": { "type": "integer", "format": "int64", "description": "Tipo de pagamento. Deve estar cadastrado para a empresa; quando omitido, usa o tipo de pagamento padrao de pedido da empresa." }, "Value": { "type": "number", "format": "double", "description": "Valor do pagamento." }, "IDBankAccount": { "type": "integer", "format": "int64", "description": "Conta bancaria do pagamento. Quando informada, deve estar cadastrada." }, "IDBankAccountForecast": { "type": "integer", "format": "int64", "description": "Conta bancaria de previsao do pagamento. Quando informada, deve estar cadastrada." }, "NoSplit": { "type": "integer", "enum": [ 0, 1 ], "description": "1 impede o split/parcelamento automatico do pagamento." } } } } } } } }, "description": "Dados do pedido a criar. Cabeçalho (cliente, endereço, vendedor, CD, tipo de pedido) é obrigatório; itens, pagamento, pacotes e arquivos podem ser enviados aqui ou nos endpoints filhos. Quando `IDOrderType`, `IDStockKeepingUnitDistributionCenter`, `IDSalesman` ou `ShippingEstimateDate` são omitidos, o sistema tenta resolver pelo padrão da empresa — sem padrão configurado retorna `400`." }, "responses": { "200": { "description": "Pedido criado. Retorna um array com a ficha completa do pedido recém-criado (mesma estrutura do registro de pedido), acrescido de `Danfe65Base64Encode` (PDF da DANFE NFCe em base64, `null` quando não aplicável).", "content": { "application/json": { "schema": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/OrdersListItem" }, { "type": "object", "properties": { "Danfe65Base64Encode": { "type": "string", "nullable": true, "description": "PDF da DANFE da NFCe em base64, quando o pedido emitiu NFCe; caso contrário, `null`." } } } ] } } } } }, "400": { "description": "Dados inválidos ou cadastro ausente. Mensagens emitidas (sem o prefixo): `Precisa enviar a conta para criar o pedido`, `Empresa não encontrada`, `Tipo pedido informado não cadastrado ou empresa não possui tipo pedido padrão`, `Status pedido não cadastrado ou inválido ao criar pedido`, `Vendedor não existe`, `Centro de distribuição não existe`, `Empresa não possui centro de distribuição padrão`, `Integração não cadastrada`, `Obrigatório informar a integração`, `Empresa faturadora não encontrada`, `Consumidor não cadastrado`, `Endereço não cadastrado`, `Endereço entrega não cadastrado`, `Transportadora não cadastrada ou inativa`, `SKU(s) não cadastrados: …`, `Itens são tipo produto e não pode ser adicionado ao pedido`, `Armazém(s) não cadastrado: …`, `Tipo documento padrão não cadastrado`, `Plano de contas padrão não cadastrado`, `Não tem motivo de devolução cadastrado`, `Não tem categoria de devolução cadastrada`, `Pedido com emissão de NFCe, mas não tem tipo de pedido para NFCe`, `Tipo pedido emite NFCe e nota fiscal é devolução. Não é permitido emitir NFCe de devolução`, `Valor do vale compras é acima do disponível para a loja: …`, `Problema adicionar pagamento: …`, `Erro ao criar pedido`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/orders/{idorder}/status": { "put": { "operationId": "orderStatusPut", "tags": [ "Pedidos" ], "summary": "Altera status do pedido", "description": "Move o pedido de um status para outro, respeitando as transições configuradas em `TypeStatusOrderRule` para a empresa. Usado pelo botão **Cancelar** da tela **Outbound** com `IDOrderStatusTo=90`, mas serve a **todas as transições** disparadas pelas telas de operação (Pedidos, Picking-List, Romaneio, Tracking, etc.).\n\n**Fluxo do sistema:**\n\n1. Localiza o pedido pelo `IDOrder` da rota + `AccountName` do contexto (`AccountName = prefix`).\n2. Lê `IDStatusOrder` atual + `IDCarrierType`, `IDStatusInvoice` da NF principal, `IDOrdersCarrierCollectionList`, `IDPickingList`.\n3. Consulta `TypeStatusOrderRule` (transições permitidas saindo do status atual) e valida que `IDOrderStatusTo` está na lista. Se não estiver, retorna `[BadRequest] - Status não permite alteração`.\n4. Aplica validações específicas do **status destino** (cada `IDOrderStatusTo` tem o seu `case`). Os casos mais relevantes:\n - **`0` Aberto** — reverte para Aberto. Quando a NF principal está em status `IN (2, 3, 4, 5, 7, 8)` (Enviada/Emitida/Processando/Pendente conciliação EPEC/Cancelada/Denegada) e a parametrização `AllowOpenOrderInvoiced != 1`, bloqueia com `[BadRequest] - Desvincular nota fiscal antes de alterar status`. Reseta `BalanceChange` em movimentos e `Budget=0` quando o status origem está em margem/crédito.\n - **`1` Fechado** — só permitido a partir de `11` (Falta produto) ou `93` (Em produção).\n - **`90` Cancelado** (botão da tela Outbound) — bloqueia quando `IDOrdersCarrierCollectionList > 0` (`[BadRequest] - Pedido esta em romaneio X, retirar antes de mudar status`) ou `IDPickingList > 0` (`[BadRequest] - Pedido esta na Picking List X, retirar antes de mudar status`). Caso liberado: zera `BalanceChange` dos movimentos, deleta `Packages`, ajusta `AccountsPayableReceivable` (status `4` Cancelado quando ainda em aberto; mantém status quando pago; cria contra-lançamento em `AccountsPayableReceivableBankStatement` quando pagamento foi em dinheiro / `Category=7`), zera `PickingBasket`/`IDOrdersCarrierCollectionList`/`IDPickingList` no pedido e atualiza `IDStatusOrder=90`.\n - **`91` Extraviado**, **`92` Extraviado parcialmente**, **`94` Devolvido**, **`95` Em devolução**, **`97` Reversa finalizada** — disponíveis para transições típicas do pós-envio. Bloqueio depende da regra cadastrada em `TypeStatusOrderRule`.\n5. Grava um evento em `OrderEvents` (`IDEvent=35` para Aberto, `19` para Cancelado, etc.) com `RecordUserCreated` e `StatusDate`.\n\n**Validações de body comuns**:\n\n- `IDOrderStatusTo` precisa estar na lista de transições permitidas a partir do status atual.\n- Quando o `CommentsRequired=1` para o destino e `StatusComment` está vazio, retorna `[BadRequest] - Comentário precisa ser preenchido`.\n- `StatusDate` não pode ser mais de 5 min no futuro (`[BadRequest] - Data Evento não pode ser superior a data atual`).", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Código interno do pedido (`IDOrder`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusPutPayload" } } }, "description": "Movimento de status do pedido. `IDOrderStatusTo` indica o status destino (ver `support data/TypeStatusOrder.csv`); `StatusComment` é a justificativa registrada no histórico (obrigatória para alguns status — ex.: cancelamento). O motor de status valida transições proibidas (pedidos faturados, picking iniciado, etc.) e dispara recálculos/cancelamentos de NF quando o destino é cancelamento." }, "responses": { "200": { "description": "Transição aplicada. Body de resposta é a string literal `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Validação falhou. Mensagens emitidas:\n- `[BadRequest] - não localizado` (path `idorder` ausente/inválido).\n- `[BadRequest] - Status não permite alteração` (transição não cadastrada em `TypeStatusOrderRule` para a empresa).\n- `[BadRequest] - Comentário precisa ser preenchido` (quando o destino exige comentário e `StatusComment` veio vazio).\n- `[BadRequest] - Data Evento não pode ser superior a data atual` (`StatusDate` > agora + 5 min).\n- `[BadRequest] - Desvincular nota fiscal antes de alterar status` (transição → `0` Aberto com NF em status conflitante).\n- `[BadRequest] - Pedido esta em romaneio X, retirar antes de mudar status` (transição → `90` Cancelado com pedido amarrado em romaneio).\n- `[BadRequest] - Pedido esta na Picking List X, retirar antes de mudar status` (transição → `90` com pedido em picking-list ativa).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "404": { "description": "Pedido não encontrado. Mensagens emitidas pela operação começam com `[NotFound]`." }, "500": { "description": "Erro inesperado. Mensagens começam com `Error:`." } } } }, "/orders/log": { "get": { "operationId": "ordersLogList", "tags": [ "Pedidos" ], "summary": "Lista eventos do pedido (Log Pedidos)", "description": "Lista o histórico de ações realizadas em pedidos (`OrderEvents`), com `EventDescription`, executor (`User`), `Order` e conta já resolvidos. Paginação fixa em **5000 registros por página** (`Page=N` → offset `N*5000`), ordenado por `IDOrderEvents` decrescente (mais recentes primeiro). Em contexto multi-conta (`accountname = all`), traz todas as contas acessíveis ao usuário.\n\nNenhum filtro é obrigatório. Todos os filtros são combinados com AND. A faixa de data filtra eventos com `RecordTimestamp` entre `DateFrom` e o final de `DateTo` (inclusive).", "parameters": [ { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código interno do pedido (mostrado como **Código pedido** na tela)." }, { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo número do pedido visível ao cliente (`Order`)." }, { "name": "IDEvent", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo tipo da ação (`IDEvent`). Ex.: `0` Pedido criado, `2` Finalizar pedido, `19` Cancelar pedido, `35` Alteração status. Lista completa em `support data/TypeOrderEvents.csv`." }, { "name": "Header", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1, 2 ] }, "description": "Resultado da ação: `0` Erro (Problema), `1` Sucesso, `2` Inativo. O select da tela só oferece Erro e Sucesso — `2` (Inativo) aparece na lista mas não é selecionável no filtro." }, { "name": "RecordUserCreated", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo usuário que disparou a ação (`IDUser`)." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial da janela: traz eventos com `RecordTimestamp` a partir desta data (inclusive). Quando informada sem `DateTo`, o limite superior fica aberto." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final da janela. O sistema concatena ` 23:59:59` para incluir o dia inteiro." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (offset = `Page * 5000`)." } ], "responses": { "200": { "description": "Lista de eventos de pedido.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrderEventLogItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/orders/gnre": { "get": { "operationId": "orderGnreList", "tags": [ "Pedidos" ], "summary": "Lista GNRE (ou apuração DIFAL com Summary=1)", "description": "Endpoint compartilhado pelas telas **GNRE** e **Apuração DIFAL**. O comportamento depende da querystring `Summary`:\n\n- **`Summary` omitido ou `0`** — tela **GNRE**. Devolve uma linha por guia (`Gnre`) com `IDGnre`, `BarCode`, `DueDate`, `RevenueCode` (com `Description` resolvido), `ReceiptNumber`, `StatusProcessCode` (`StatusDescription`), `GnreValue`/`GnreInterest`/`GnreRestatement`/`GnrePenalty` (computa `GnreTotalValue = soma dos quatro`), `IDOrder`, `Order`, `NfeNumber/Serie/dhEmi/StatusInvoice`, `SupplierNameCorporateName` (da transportadora), `AccountName` da conta e da NF, `OrderFrom` (canais concatenados).\n- **`Summary=1`** — tela **Apuração DIFAL**. Devolve uma linha por pedido com NF principal de modelo `55` (`NfeModelo = 55`), trazendo `NfedhEmi`, `NfeChaveAcesso`, `NfeNumber/Serie`, `IDStatusInvoice`+`StatusInvoice`, `GnreStatusDescription` (descrição do último status de processamento da guia do pedido), `CompanyIntegrationName`, `StatusOrder`, `TypeOrder`, `ShippingDate` (max de Packages), `ValueOrder` (soma de `PriceSellingTotal` + `ValueShipping` + `NfeAccessoryExpenses`), `NfeValueIcmsUfDest` e `NfeValueFcpUfDest` (soma do movimento). O sinal dos valores é positivo quando `NfeType=1` (saída) e negativo quando `NfeType=0` (entrada).\n\nPaginação fixa em **5000 registros por página** (`Page=N` → offset `N*5000`). Em contexto multi-conta (`accountname = all`), traz todas as contas acessíveis.", "parameters": [ { "name": "Summary", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` ativa o modo apuração DIFAL; omitido ou `0` lista as guias GNRE." }, { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo número do pedido (`Order`)." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código interno do pedido (`IDOrder`)." }, { "name": "NfeNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo número da NF principal (`NfeNumber`)." }, { "name": "NfeSerie", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela série da NF principal." }, { "name": "OrderFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo canal de origem do pedido (busca em `OrderFrom`)." }, { "name": "IDStatusOrder", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo status do pedido." }, { "name": "IDStatusInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo status da NF principal." }, { "name": "IDCarrier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela transportadora (`IDCarrier`)." }, { "name": "ShippingState", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela UF de destino (`ShippingState`)." }, { "name": "ReceiptNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo número de protocolo da guia (`ReceiptNumber`)." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo faturador (`IDCompanyInvoice`)." }, { "name": "IDOrderType", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo tipo do pedido." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela integração de origem do pedido." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de criação da guia (`Recordtimestamp ≥`). Aplicado apenas no modo guias (`Summary=0`)." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de criação da guia (concatenada com ` 23:59:59`)." }, { "name": "InvoiceDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de emissão da NF (`NfedhEmi`)." }, { "name": "InvoiceDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de emissão da NF." }, { "name": "ShippingDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de envio (`ShippingDate`)." }, { "name": "ShippingDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de envio. **Observação**: por bug no sistema, o limite superior usa `InvoiceDateTo` em vez de `ShippingDateTo`." }, { "name": "DueDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Vencimento mínimo da guia (`DueDate ≥`)." }, { "name": "DueDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Vencimento máximo da guia." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (offset = `Page * 5000`)." } ], "responses": { "200": { "description": "Lista de guias GNRE (default) ou de linhas de apuração DIFAL (`Summary=1`). `[]` quando nada bate com os filtros.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/GnreListItem" } }, { "type": "array", "items": { "$ref": "#/components/schemas/DifalSummaryItem" } } ] } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "orderGnrePost", "tags": [ "Pedidos" ], "summary": "Gera GNRE em massa para os pedidos selecionados", "description": "Aciona a geração de GNRE para uma lista de pedidos. Para cada pedido valida que existe NF principal (`Main=1`) com status emitido (`IDStatusInvoice=3`). Os pedidos válidos são agrupados por `AccountNameInvoice` (faturador) e processados em paralelo: para cada grupo, o sistema gera a GNRE e envia o lote à SEFAZ. Devolve `\"sucesso\"` quando todos os lotes são gerados com OK; o primeiro erro aborta com a mensagem propagada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer" }, "description": "Array de `IDOrder`." } } }, "description": "Array de `IDOrder` para emitir GNRE em lote. Todos os pedidos precisam ter nota fiscal emitida (`IDStatusInvoice=3`) — caso contrário retorna `400`. Os pedidos são agrupados pela empresa faturadora e enviados ao processo fiscal." }, "responses": { "200": { "description": "Sucesso. Corpo: string `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "`[BadRequest] - Nota fiscal não emitida` (NF do primeiro pedido ainda não está em `IDStatusInvoice=3`); `[BadRequest] - Pedido não localizado` (nenhum pedido válido encontrado para o `AccountName` do contexto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro propagado pela geração da GNRE — mensagem retornada pelo serviço de emissão à SEFAZ.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/orders/gnre/file": { "post": { "operationId": "gnreFileDownload", "tags": [ "Pedidos" ], "summary": "Baixa ZIP com os PDFs das guias selecionadas", "description": "Recebe um array de `IDGnre` e gera um arquivo ZIP contendo `.pdf` para cada guia válida da empresa. O ZIP é gravado em `Temp/.zip` no bucket S3 e retornado por meio de **URL assinada válida por 2 dias**. Em paralelo, dispara um e-mail (SES, modelo `Html/exportar-XML.html`) para o usuário solicitante com o mesmo link. O corpo da resposta é a URL assinada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer" }, "description": "Array de `IDGnre`." } } }, "description": "Array de `IDGnre` cujos PDFs serão zipados e disponibilizados por e-mail ao usuário solicitante." }, "responses": { "200": { "description": "URL assinada do arquivo ZIP (válida por 2 dias).", "content": { "application/json": { "schema": { "type": "string", "format": "uri", "example": "https://idworks-bucket.s3.amazonaws.com/Temp/abc123-def456.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600" } } } }, "500": { "description": "Erro interno (falha de upload S3, falha SES).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/orders/gnre/{idgnre}": { "get": { "operationId": "gnreFileGet", "tags": [ "Pedidos" ], "summary": "Devolve o PDF de uma guia individual", "description": "Usado pela ação **Visualizar arquivo** na tela GNRE para abrir o PDF da guia em um modal. Resposta: stream/URL do PDF correspondente ao `IDGnre` informado.", "parameters": [ { "name": "idgnre", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da guia GNRE." } ], "responses": { "200": { "description": "Conteúdo/URL do PDF da guia." }, "404": { "description": "Guia não encontrada." }, "500": { "description": "Erro interno." } } } }, "/orders/tracking": { "get": { "operationId": "orderTrackingList", "tags": [ "Pedidos" ], "summary": "Lista pedidos em rastreamento", "description": "Lista pedidos com informação de rastreio agregada. Retorna até 3000 itens por página (`Page` controla o offset = `Page * 3000`). Inclui dados do pedido, último evento de tracking da transportadora, status calculados de entrega e indicadores de pontualidade.\n\nQuando `TrackingEnabled=1` é informado, a listagem restringe aos pedidos cuja transportadora tem `TrackingEnabled = 1` (integração de rastreio ativa); pedidos sem transportadora vinculada deixam de aparecer nesse modo.", "parameters": [ { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`RecordTimestamp` ≥ data." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`RecordTimestamp` ≤ data 23:59:59." }, { "name": "ShippingDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de postagem ≥ (filtra `ShippingDate`)." }, { "name": "ShippingDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de postagem ≤ 23:59:59." }, { "name": "ShippingEstimateDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data estimada de entrega ≥ (`ShippingEstimateDate`)." }, { "name": "ShippingEstimateDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data estimada de entrega ≤ 23:59:59." }, { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca parcial pelo número do pedido (`LIKE`)." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do pedido." }, { "name": "NfeNumber", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo número da NF-e." }, { "name": "OrderFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Origem externa do pedido (chave-código no `OrderFrom`)." }, { "name": "ConsumerNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome ou razão social do cliente (busca parcial)." }, { "name": "ConsumerCpfCnpj", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo CPF ou CNPJ do cliente." }, { "name": "ConsumerEmail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo e-mail do cliente." }, { "name": "IDCarrier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador da transportadora." }, { "name": "IDSalesChannel", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do canal de venda." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador da integração da empresa." }, { "name": "TrackingIDStatus", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo último status do tracking do pacote." }, { "name": "IDStatusDeliveryConsumer", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo indicador de pontualidade consumidor (calculado: 1=Antes do prazo, 2=Após o prazo, 3=Em curso, 4=Atrasado, 6=No prazo). Aplicado como HAVING." }, { "name": "IDStatusDeliveryCarrier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo indicador de pontualidade transportadora (mesmos códigos). Aplicado como HAVING." }, { "name": "TrackingEnabled", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` força filtro pelos pedidos cuja transportadora tem integração de rastreio ativa." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (offset = `Page * 3000`)." } ], "responses": { "200": { "description": "Lista de pedidos em rastreamento (até 3000).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrderTrackingListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/location/group": { "get": { "operationId": "skuLocationGroupList", "tags": [ "Endereços de Estoque" ], "summary": "Lista grupos de endereços", "description": "Lista grupos de endereços (`StockKeepingUnitLocationGroup`) da empresa, ordenados pelo nome.", "parameters": [ { "name": "IDStockKeepingUnitLocationGroup", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do grupo de localização do SKU." }, { "name": "StockKeepingUnitLocationGroupName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome exato do grupo." } ], "responses": { "200": { "description": "Lista de grupos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuLocationGroupListItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuLocationGroupPost", "tags": [ "Endereços de Estoque" ], "summary": "Cria um grupo de endereços", "description": "Cria um grupo de endereços para a empresa autenticada. Nome precisa ser **único** dentro da empresa.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuLocationGroupCreate" } } }, "description": "Dados do grupo de endereços a cadastrar (agrupamento de endereços que compartilham configuração)." }, "responses": { "200": { "description": "Grupo criado (retorna o detalhe via list).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuLocationGroupListItem" }, "maxItems": 1 } } } }, "400": { "description": "`[BadRequest] - Empresa não existe`; `[BadRequest] - Grupo já existente`; `[BadRequest] - Erro ao inserir a grupo`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/location/group/{idstockkeepingunitlocationgroup}": { "parameters": [ { "name": "idstockkeepingunitlocationgroup", "in": "path", "required": true, "schema": { "type": "integer" } } ], "put": { "operationId": "skuLocationGroupPut", "tags": [ "Endereços de Estoque" ], "summary": "Atualiza um grupo de endereços", "description": "Atualiza o nome do grupo. Valida unicidade do nome dentro da empresa (excluindo o próprio registro).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuLocationGroupCreate" } } }, "description": "Atualiza o grupo de endereços. Mesmo schema do POST." }, "responses": { "200": { "description": "Grupo atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuLocationGroupListItem" }, "maxItems": 1 } } } }, "400": { "description": "`[BadRequest] - Preencha corretamente o nome do grupo`; `[BadRequest] - Grupo não encontrada`; `[BadRequest] - Grupo já existente`; `[BadRequest] - Grupo não atualizado`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuLocationGroupDelete", "tags": [ "Endereços de Estoque" ], "summary": "Exclui um grupo de endereços", "description": "**Exclusão física** do grupo de endereços. Bloqueada quando existe pelo menos um endereço (`StockKeepingUnitLocation`) vinculado ao grupo — neste caso devolve `200` com mensagem texto `Grupo esta vinculado a endereço. Editar endereço antes de excluir o grupo` (sem prefixo `[BadRequest]`).", "responses": { "200": { "description": "Grupo excluído (string literal `\"sucesso\"`) ou mensagem de bloqueio.", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "`[BadRequest] - Grupo não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/batch": { "get": { "operationId": "skuBatchList", "tags": [ "Lotes" ], "summary": "Lista lotes e endereços de SKU", "description": "Lista os lotes de SKU da empresa com dados do produto, do endereço de armazenagem (armazém, centro de distribuição, grupo, categoria e tipo de endereço), validade, data de fabricação, comentários e saldos calculados: saldo do lote `BatchBalance`, quantidade em movimentação `QtyHandling` e saldo disponível do SKU no armazém `QtyAvailable`. Retorna também preço de venda `PriceSell` e preço de tabela `PriceList`; ao informar uma política comercial em `IDCompanySalesPolicy`, os preços seguem essa política e, havendo promoção ativa, o desconto percentual `PercentualDiscountValue` é aplicado ao `PriceSell`. Considera apenas SKUs não deletados dos tipos Sku, Matéria-prima e Uso e consumo. Respeita a restrição de centros de distribuição do usuário e o compartilhamento de estoque entre empresas relacionadas.", "parameters": [ { "name": "IDSku", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do produto/SKU." }, { "name": "IDBatch", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do lote." }, { "name": "IDStockKeepingUnitLocation", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador da localização do SKU." }, { "name": "IDStockKeepingUnitWarehouse", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do depósito do SKU." }, { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Aceita CSV." }, { "name": "SkuName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome do produto (busca parcial)." }, { "name": "IDSkuCompany", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código de referência do SKU (`LIKE`)." }, { "name": "BarCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código de barras do produto." }, { "name": "Address", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo logradouro do endereço (busca parcial)." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`BestBeforeDate` ≥ data." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`BestBeforeDate` ≤ data." }, { "name": "Status", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` lotes Ativos (com saldo), `0` Inativos (sem saldo)." }, { "name": "Search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca multi-campo (SKU, nome, endereço, código de barras). `nulladdress` filtra lotes sem endereço." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Número da página da listagem (1-based). Padrão `1`." }, { "name": "IDCompanySalesPolicy", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador da política comercial usada para calcular os preços `PriceSell` e `PriceList` de cada lote. Quando informada e diferente da política padrão, promoções ativas do SKU também são aplicadas (desconto retornado em `PercentualDiscountValue`). Quando omitida, usa a política comercial padrão da empresa." } ], "responses": { "200": { "description": "Lista de lotes.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuBatchItem" } } } } }, "400": { "description": "Validação falhou. Prefixo `[BadRequest]`. Mensagem: `Política comercial não existe` — quando `IDCompanySalesPolicy` é informado mas não corresponde a nenhuma política comercial da empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/batch/{idsku}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "skuBatchPost", "tags": [ "Lotes" ], "summary": "Cria lote para um SKU", "description": "Cria um lote no SKU em um endereço específico. Validações:\n\n- **SKU sem controle de lote** (`Batch != 1`): se já existe lote desse SKU no endereço, devolve `[BadRequest] - SKU já tem este endereço`.\n- **Endereço** precisa pertencer à empresa (ou empresa relacionada com `ShareSkuLocationWithRelatedCompanies = 1`).\n- Quando `Default = 1`, zera o `Default` dos demais lotes do SKU antes de inserir.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuBatchCreate" } } }, "description": "Dados do lote a cadastrar para o SKU. `BestBeforeDate` (validade) e `ManufacturingDate` (fabricação) são obrigatórios; `IDStockKeepingUnitLocation` define o endereço de alocação. `Default=1` marca este lote como o de saída prioritária nas vendas." }, "responses": { "200": { "description": "Lote criado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuBatchItem" }, "maxItems": 1 } } } }, "400": { "description": "`[BadRequest] - SKU não existe`; `[BadRequest] - SKU já tem este endereço`; `[BadRequest] - Endereço SKU não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "skuBatchPutByBody", "tags": [ "Lotes" ], "summary": "Atualiza lote (id no body)", "description": "Versão do PUT em que o `IDBatch` vem no corpo. Mesmas validações do PUT por path.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuBatchUpdate" } } }, "description": "Atualização parcial do lote (sem mudança do identificador do lote — para alterar um lote específico use `PUT /sku/batch/{idsku}/{idbatch}`)." }, "responses": { "200": { "description": "Atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuBatchItem" } } } } } } } }, "/sku/batch/{idsku}/{idbatch}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idbatch", "in": "path", "required": true, "schema": { "type": "integer" } } ], "put": { "operationId": "skuBatchPut", "tags": [ "Lotes" ], "summary": "Atualiza lote", "description": "Atualiza validade (`BestBeforeDate`), fabricação (`ManufacturingDate`), endereço, descrição (`Comments`) e flag de padrão. Validações:\n\n- `ManufacturingDate ≤ BestBeforeDate` e `ManufacturingDate ≤ 2099-12-31`.\n- `IDStockKeepingUnitLocation = null` é rejeitado (`Endereço não pode ser removido`).\n- Endereço novo precisa pertencer ao **mesmo armazém** do endereço atual (ou empresa relacionada).\n- Quando seta `Default = 1`, zera os demais lotes do SKU.\n\nRequer privilégio `PrivilegeSkuBatch` (Editar Validade Lote Sku).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuBatchUpdate" } } }, "description": "Atualização parcial do lote identificado por `{idbatch}`." }, "responses": { "200": { "description": "Lote atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuBatchItem" }, "maxItems": 1 } } } }, "400": { "description": "`[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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuBatchDelete", "tags": [ "Lotes" ], "summary": "Remove lote", "description": "Remove um lote de SKU. A exclusão é bloqueada quando o lote ainda tem saldo em estoque (saldo diferente de zero); nesse caso, transfira a quantidade para outro endereço ou consuma-a via venda/saída antes de excluir.", "responses": { "200": { "description": "Lote removido.", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "`[BadRequest] - Lote não existe`; `[BadRequest] - Lote tem saldo, transferir quantidade para deletar`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/resupply": { "get": { "operationId": "skuResupplyList", "tags": [ "Ressuprimento" ], "summary": "Lista ressuprimentos", "description": "Lista ressuprimentos da empresa com totais agregados (`QtyOrder`, `QtyResupply`, `QtyResupplyItems`). Aceita filtros por status, modalidade, tipo, CD, colaborador, datas. Respeita restrição de CDs do usuário.", "responses": { "200": { "description": "Lista de ressuprimentos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResupplyItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuResupplyPost", "tags": [ "Ressuprimento" ], "summary": "Cria ressuprimento", "description": "Cria um ressuprimento manualmente ou a partir de um pedido (`IDOrder`).\n\n**Modo manual** (sem `IDOrder`): valida tipo de ressuprimento (1=Picking, 2=Pulmão, 3=Recebimento), modalidade (1=Individual, 2=Agrupado, 3=Indireto) e CD (usa o CD padrão da empresa se omitido).\n\n**Modo automático por pedido** (com `IDOrder`): o sistema analisa o pedido e gera as listas de ressuprimento necessárias. Pode falhar com `Empresa não tem armazém configurado para ressuprimento`, `Não há itens marcados para ressuprimento neste pedido`, `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`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResupplyCreate" } } }, "description": "Dados do ressuprimento a abrir. `IDTypeResupply` define o fluxo (`1` Picking — do pulmão para o picking; `2` Pulmão — chegada nova ao pulmão; `3` Recebimento — do recebimento para o estoque). `IDTypeResupplyMode` define a forma de execução (Individual, Agrupado, Indireto)." }, "responses": { "200": { "description": "Ressuprimento criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResupplyItem" } } } }, "400": { "description": "Validações conforme sistema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/resupply/{idstockkeepingunitresupplylist}": { "parameters": [ { "name": "idstockkeepingunitresupplylist", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "skuResupplyGet", "tags": [ "Ressuprimento" ], "summary": "Detalha ressuprimento", "description": "Detalhe completo do ressuprimento, com itens, eventos e colaborador atribuído.", "responses": { "200": { "description": "Detalhe.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResupplyItem" }, "maxItems": 1 } } } } } }, "put": { "operationId": "skuResupplyPut", "tags": [ "Ressuprimento" ], "summary": "Atualiza ressuprimento (status, atribuição, modalidade, prioridade, finalização)", "description": "Atualização parcial. Usado para: mudar status (Aberto → Iniciado → Finalizado / Cancelado), atribuir colaborador, alterar modalidade, alterar prioridade. As ações em massa da tela (modalidade, prioridade, atribuir colaborador) iteram esse endpoint.", "requestBody": { "description": "Atualização parcial da lista de ressuprimento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "Comments": { "type": "string", "description": "Observações da lista de ressuprimento." }, "RecordUserStart": { "type": "string", "description": "Login do colaborador que iniciou o ressuprimento." }, "IDResupplyStatus": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Status do ressuprimento: `1` Aberto, `2` Iniciado, `3` Finalizado, `4` Cancelado." }, "IDTypeResupplyMode": { "type": "integer", "description": "Modo de ressuprimento." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Centro de distribuição." }, "StockKeepingUnitResupplyListPriority": { "type": "integer", "description": "Prioridade da lista na fila de ressuprimento." } } } } } }, "responses": { "200": { "description": "Atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResupplyItem" }, "maxItems": 1 } } } } } }, "delete": { "operationId": "skuResupplyDelete", "tags": [ "Ressuprimento" ], "summary": "Exclui ressuprimento", "description": "Bloqueada quando há itens pendentes de abastecimento (`QtyResupply > 0`).", "responses": { "200": { "description": "Excluído.", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "Bloqueios de exclusão.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/resupply/{idstockkeepingunitresupplylist}/merge": { "parameters": [ { "name": "idstockkeepingunitresupplylist", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "skuResupplyMergePost", "tags": [ "Ressuprimento" ], "summary": "Consolida ressuprimentos", "description": "Move todos os itens de uma lista de ressuprimentos de origem (informada no body) para o ressuprimento de destino (id na URL). Apenas ressuprimentos com status Aberto podem ser consolidados.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "IDStockKeepingUnitResupplyList": { "type": "array", "items": { "type": "integer" }, "description": "Identificador da lista de ressuprimento de **origem**, que será mesclada na lista de destino (path param)." } } } } }, "description": "Mescla este ressuprimento com outros pendentes do mesmo centro de distribuição. O corpo geralmente é vazio; o sistema usa o identificador da URL para identificar o destino da mesclagem." }, "responses": { "200": { "description": "Consolidado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ResupplyItem" } } } } } } } }, "/sku/resupply/{idstockkeepingunitresupplylist}/sku": { "parameters": [ { "name": "idstockkeepingunitresupplylist", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "skuResupplySkuPost", "tags": [ "Ressuprimento" ], "summary": "Adiciona item ao ressuprimento", "description": "Adiciona um SKU/lote ao ressuprimento (endereço origem, endereço destino, quantidade).", "responses": { "200": { "description": "Item adicionado.", "content": { "application/json": { "schema": { "type": "array" } } } } }, "requestBody": { "description": "Adiciona um item à lista de ressuprimento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "IDSku": { "type": "integer", "description": "SKU a ressuprir." }, "IDBatchFrom": { "type": "integer", "description": "Lote de origem (de onde o estoque sai). Opcional." }, "IDBatchTo": { "type": "integer", "description": "Lote de destino. Opcional." }, "IDStockKeepingUnitLocationTo": { "type": "integer", "description": "Endereço de destino do ressuprimento." }, "QtyTransferRecommendation": { "type": "number", "format": "double", "description": "Quantidade recomendada de transferência. Opcional." } } } } } } } }, "/sku/resupply/{idstockkeepingunitresupplylist}/sku/{idstockkeepingunitresupply}": { "parameters": [ { "name": "idstockkeepingunitresupplylist", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idstockkeepingunitresupply", "in": "path", "required": true, "schema": { "type": "integer" } } ], "put": { "operationId": "skuResupplySkuPut", "tags": [ "Ressuprimento" ], "summary": "Atualiza item de ressuprimento", "description": "Altera quantidade, endereço destino ou conclui a movimentação do item. Privilégio `PrivilegeResupplyAllowUserSetLocationTo` controla quem pode mudar o endereço destino. Privilégio `PrivilegeResupplyAllowEditQuantity` controla quem pode mudar a quantidade.", "responses": { "200": { "description": "Item atualizado.", "content": { "application/json": { "schema": { "type": "array" } } } } }, "requestBody": { "description": "Atualiza um item da lista de ressuprimento (quantidade, endereço, não-conformidade).", "content": { "application/json": { "schema": { "type": "object", "properties": { "IDSku": { "type": "integer", "description": "SKU do item de ressuprimento." }, "IDBatchFrom": { "type": "integer", "description": "Lote de origem. Opcional." }, "IDBatchTo": { "type": "integer", "description": "Lote de destino. Opcional." }, "IDStockKeepingUnitLocationTo": { "type": "integer", "description": "Endereço de destino." }, "QtyTransferRecommendation": { "type": "number", "format": "double", "description": "Quantidade recomendada de transferência." }, "IDSkuMovement": { "type": "integer", "description": "Movimentação de estoque vinculada. Opcional." }, "QuantityNonconformity": { "type": "number", "format": "double", "description": "Quantidade em não-conformidade. Opcional." }, "IDTypeFulfillmentNonconformity": { "type": "integer", "enum": [ 1, 2, 4, 5, 6 ], "description": "Tipo de não-conformidade: `1` Avariado, `2` Vencido, `4` Em Produção, `5` Falta, `6` Ressuprimento." } } } } } } }, "delete": { "operationId": "skuResupplySkuDelete", "tags": [ "Ressuprimento" ], "summary": "Remove item do ressuprimento", "responses": { "200": { "description": "Item removido.", "content": { "application/json": { "schema": { "type": "string" } } } } }, "description": "Remove um item específico da lista de ressuprimento. Devolve a lista de ressuprimento atualizada." } }, "/type/sku/resupply": { "get": { "operationId": "typeSkuRessuply", "tags": [ "Tipos — SKU" ], "summary": "Lista tipos de ressuprimento", "description": "Devolve a lista de `TypeResupply` (`1` Picking, `2` Pulmão, `3` Recebimento).", "responses": { "200": { "description": "Lista.", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/type/sku/resupply/status": { "get": { "operationId": "typeSkuResuplyStatusList", "tags": [ "Tipos — SKU" ], "summary": "Lista status do ressuprimento", "description": "Devolve a lista de `StatusResupply` (`1` Aberto, `2` Iniciado, `3` Finalizado, `4` Cancelado).", "responses": { "200": { "description": "Lista.", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/charge/bank-slip": { "get": { "operationId": "chargeBankSlipList", "tags": [ "Boleto Bancário" ], "summary": "Lista boletos bancários", "description": "Lista os boletos da empresa autenticada com dados do cliente, valor, vencimento, status (`TypeStatusBankSlip`), URL e código de barras gerados pelo banco. Cada linha traz também os flags `BankSlipUpdate` e `BankSlipCancel` (booleans calculados pelo sistema de acordo com o estado atual e o banco) — são eles que governam quais ações ficam habilitadas no frontend.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Número da página da listagem (1-based). Padrão `1`." }, { "name": "IDStatusBankSlip", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6 ] } }, "description": "Status do boleto: `1` Aguardando pagamento, `2` Pago, `3` Pendente, `4` Cancelado, `5` Baixa manual, `6` Protesto.", "style": "form", "explode": false }, { "name": "DateDueFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de vencimento ≥ data." }, { "name": "DateDueTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de vencimento ≤ data." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de criação ≥ data." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de criação ≤ data." }, { "name": "ConsumerNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome / razão social do cliente (LIKE)." }, { "name": "ConsumerCpfCnpj", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CPF/CNPJ do cliente." }, { "name": "ConsumerEmail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "E-mail do cliente (LIKE)." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Pedido vinculado." }, { "name": "TID", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador da transação no banco." } ], "responses": { "200": { "description": "Array de boletos.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDBankSlip": { "type": "integer", "format": "int64", "description": "Identificador único do boleto." }, "IDConsumer": { "type": "integer", "format": "int64", "description": "Identificador do cliente sacado." }, "ConsumerNameCorporateName": { "type": "string", "description": "Nome (PF) ou razão social (PJ) do sacado." }, "ConsumerCpfCnpj": { "type": "string", "description": "CPF/CNPJ do sacado, apenas dígitos." }, "ConsumerEmail": { "type": "string", "nullable": true, "description": "E-mail do sacado. `null` quando não informado." }, "IDOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do pedido vinculado ao boleto, quando aplicável." }, "Order": { "type": "string", "nullable": true, "description": "Número/identificador externo do pedido vinculado, quando aplicável." }, "IDServiceOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador da NF de serviço vinculada, quando aplicável." }, "Value": { "type": "number", "format": "double", "description": "Valor original do boleto em R$." }, "ValuePaid": { "type": "number", "format": "double", "nullable": true, "description": "Valor efetivamente pago em R$. `null` quando o boleto ainda não foi liquidado." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento do boleto (`YYYY-MM-DD`)." }, "DatePaid": { "type": "string", "format": "date", "nullable": true, "description": "Data de pagamento (`YYYY-MM-DD`). `null` enquanto não houver liquidação." }, "IDStatusBankSlip": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6 ], "description": "Status do boleto: `1` Aguardando pagamento, `2` Pago, `3` Pendente, `4` Cancelado, `5` Baixa manual, `6` Protesto." }, "StatusBankSlip": { "type": "string", "description": "Descrição amigável do status do boleto." }, "BankSlipUrl": { "type": "string", "format": "uri", "nullable": true, "description": "URL do PDF do boleto (S3 público, pode expirar). `null` quando ainda não emitido." }, "BankSlipBarCode": { "type": "string", "nullable": true, "description": "Linha digitável / código de barras do boleto. `null` quando ainda não emitido." }, "BankSlipUpdate": { "type": "boolean", "description": "Indica se o boleto pode ser editado neste estado." }, "BankSlipCancel": { "type": "boolean", "description": "Indica se o boleto pode ser cancelado neste estado." }, "TID": { "type": "string", "nullable": true, "description": "Identificador único da transação no gateway/adquirente, quando o boleto é gerado por integração." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração que emitiu o boleto (Stark Bank, Bradesco, Itaú, etc.)." }, "CompanyIntegration": { "type": "string", "description": "Nome amigável da integração emissora do boleto." }, "RecordUserCreated": { "type": "string", "description": "Login do usuário que criou o boleto." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do boleto." } } } } } } } } }, "post": { "operationId": "chargeBankSlipPost", "tags": [ "Boleto Bancário" ], "summary": "Gera um novo boleto", "description": "Cria um boleto via API do banco configurado em `IDCompanyIntegration`. Pode ser avulso, vinculado a pedido (`IDOrder`) ou a NFSe (`IDServiceOrder`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDConsumer", "Value", "DateDue", "IDCompanyIntegration" ], "properties": { "IDConsumer": { "type": "integer", "format": "int64", "description": "Cliente a ser cobrado." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração bancária que emitirá o boleto." }, "Value": { "type": "number", "format": "double", "description": "Valor do boleto." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento." }, "Comments": { "type": "string", "description": "Observações que aparecem no boleto." }, "IDOrder": { "type": "integer", "format": "int64", "description": "(Opcional) Vincula a um pedido — o banco cria o boleto referenciando o pedido." }, "IDServiceOrder": { "type": "integer", "format": "int64", "description": "(Opcional) Vincula a uma NFSe." } } } } }, "description": "Dados do boleto a emitir. `IDConsumer`, `IDCompanyIntegration`, `Value` e `DateDue` são obrigatórios; `IDOrder` ou `IDServiceOrder` vinculam opcionalmente o boleto a um pedido ou a uma NFSe. O sistema dispara a emissão do boleto na API do banco." }, "responses": { "200": { "description": "Boleto criado. Retorna `{ response: [] }` com `BankSlipUrl` e `BankSlipBarCode` preenchidos." }, "400": { "description": "Erros conhecidos: cliente sem endereço, integração indisponível, banco rejeitou os dados." } } } }, "/charge/bank-slip/{idbankslip}": { "get": { "operationId": "chargeBankSlipGet", "tags": [ "Boleto Bancário" ], "summary": "Consulta status no banco e atualiza", "description": "Consulta a API do banco para buscar o status atualizado do boleto e atualiza no idworks. Chamado pelo ícone **Atualizar** da linha. Bloqueado pelo frontend quando o boleto já está pago (`IDStatusBankSlip=2`).", "parameters": [ { "name": "idbankslip", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do boleto." } ], "responses": { "200": { "description": "Status atualizado. Retorna a linha do boleto com os campos refrescados." }, "400": { "description": "Falha na consulta ao banco." } } }, "put": { "operationId": "chargeBankSlipPut", "tags": [ "Boleto Bancário" ], "summary": "Atualiza o boleto", "description": "Atualiza valor, vencimento ou observações do boleto. Quais campos são editáveis depende do banco — o frontend bloqueia o botão Editar quando `BankSlipUpdate=false`.", "parameters": [ { "name": "idbankslip", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do boleto." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Value": { "type": "number", "format": "double", "description": "Novo valor do boleto em R$." }, "DateDue": { "type": "string", "format": "date", "description": "Nova data de vencimento (`YYYY-MM-DD`)." }, "Comments": { "type": "string", "description": "Observações do boleto." } } } } }, "description": "Campos do boleto a atualizar (`Value`, `DateDue`, `Comments`). Quais campos são editáveis depende do banco — o frontend só libera o botão Editar quando o boleto traz `BankSlipUpdate=true`. Campos omitidos preservam o valor atual." }, "responses": { "200": { "description": "Boleto atualizado." }, "400": { "description": "Banco recusou alteração ou campos inválidos." } } }, "delete": { "operationId": "chargeBankSlipDelete", "tags": [ "Boleto Bancário" ], "summary": "Cancela o boleto (com ou sem dar baixa)", "description": "Cancela o boleto via API do banco. Dois modos:\n\n- **Sem querystring** (Somente Cancelar) — apenas cancela. A conta a receber vinculada (se houver) **fica em aberto**.\n- **Com `ValuePaid` e `DatePaid`** (Dar Baixa e Cancelar) — cria um lançamento de pagamento na conta bancária (`AccountsPayableReceivableBankStatement`) com a data e o valor informados, dá baixa na conta a receber, e em seguida cancela o boleto. Usado quando o cliente já pagou por outro meio (PIX, transferência) e o boleto continua aberto.\n\nBloqueado pelo frontend quando `BankSlipCancel=false` ou quando `IDStatusBankSlip ∉ {1, 3}`.", "parameters": [ { "name": "idbankslip", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do boleto." }, { "name": "ValuePaid", "in": "query", "required": false, "schema": { "type": "number", "format": "double" }, "description": "Valor pago — quando informado junto com `DatePaid`, ativa o modo Dar Baixa e Cancelar." }, { "name": "DatePaid", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data do pagamento — obrigatória junto com `ValuePaid`." } ], "responses": { "200": { "description": "Boleto cancelado (e pagamento registrado quando aplicável)." }, "400": { "description": "Boleto já cancelado, já pago, ou banco recusou cancelamento." } } } }, "/consumer": { "get": { "operationId": "consumerList", "tags": [ "Cadastro de Clientes" ], "summary": "Lista clientes", "description": "Lista os clientes da empresa autenticada, com métricas agregadas: receita total (soma dos valores das contas a receber vinculadas), quantidade total de pedidos do cliente, receita de NFs de serviço emitidas (`ServiceOrder` em status `IDStatusInvoice=3`) e vendedores vinculados (lista de `UserName` via `ConsumerSalesman`). Paginação fixa em **3000 por página** (`Page=N` → offset `N*3000`). Por padrão, o sistema filtra por `StatusConsumer IN (1,2,3)` — clientes Deletados (`StatusConsumer=0`) não aparecem.\n\n**Restrição de vendedor**: quando `Salesman=1` e `RestrictAccessSalesman=1`, o sistema restringe a listagem aos clientes vinculados ao usuário logado em `ConsumerSalesman`.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Página 0-indexada. Offset = `Page * 3000`." }, { "name": "Search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca rápida unificada — testa o termo contra `ConsumerNameCorporateName` (LIKE), `ConsumerCpfCnpj` (apenas dígitos, ≥10 caracteres), `ConsumerEmail` (LIKE) e `IDConsumer` (apenas dígitos)." }, { "name": "ConsumerNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca textual no nome / razão social (LIKE)." }, { "name": "ConsumerCpfCnpj", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CPF/CNPJ. O sistema normaliza para apenas dígitos antes da consulta (aceita formato com pontuação)." }, { "name": "ConsumerEmail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "E-mail (LIKE)." }, { "name": "ConsumerTelephone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Telefone. O sistema normaliza para apenas dígitos." }, { "name": "IDTypeStatusConsumer", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer", "enum": [ 0, 1, 2, 3 ] }, "default": [ 1, 2, 3 ] }, "description": "Status do cliente. Aceita CSV (ex.: `1,2,3`). Valores: `0` Deletado, `1` Ativo, `2` Inativo, `3` Inadimplente. Default `1,2,3` (não traz Deletados).", "style": "form", "explode": false }, { "name": "ConsumerPriority", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Prioridade interna (`ConsumerPriority`)." }, { "name": "IDSalesman", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Vendedor vinculado. CSV aceito. Filtra apenas clientes com o vendedor informado em `ConsumerSalesman`." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra clientes com `RecordTimestamp` a partir desta data (inclusive)." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra clientes com `RecordTimestamp` até o final desta data (inclusive)." }, { "name": "SinceDateLastRecordModification", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Pega apenas clientes modificados após o timestamp informado. Útil para sincronizações incrementais." } ], "responses": { "200": { "description": "Array de clientes.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDConsumer": { "type": "integer", "format": "int64", "description": "Identificador único do cliente." }, "AccountName": { "type": "string", "description": "Conta (prefixo) à qual o cliente pertence — útil em contexto multi-conta." }, "ConsumerType": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Tipo do cliente: `1` Pessoa Física, `2` Pessoa Jurídica, `3` Estrangeiro." }, "ConsumerNameCorporateName": { "type": "string", "description": "Nome (PF) ou razão social (PJ) do cliente." }, "ConsumerCpfCnpj": { "type": "string", "description": "CPF (PF) ou CNPJ (PJ) do cliente, apenas dígitos." }, "ConsumerEmail": { "type": "string", "nullable": true, "description": "E-mail principal do cliente. `null` quando não informado." }, "ConsumerTelephone": { "type": "string", "nullable": true, "description": "Telefone principal do cliente, apenas dígitos. `null` quando não informado." }, "IDTypeStatusConsumer": { "type": "integer", "enum": [ 0, 1, 2, 3 ], "description": "Status do cliente: `0` Deletado, `1` Ativo, `2` Inativo, `3` Inadimplente. Por padrão a listagem traz apenas `1,2,3` (Deletados ficam de fora)." }, "TypeStatusConsumer": { "type": "string", "description": "Descrição amigável do status (corresponde ao `IDTypeStatusConsumer`)." }, "ConsumerPriority": { "type": "integer", "nullable": true, "description": "Prioridade interna do cliente (valor numérico definido pela empresa). `null` quando não definida." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que o cliente foi cadastrado." }, "DateLastRecordModification": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora da última modificação do cadastro. `null` quando nunca foi alterado depois do cadastro inicial." }, "OrderQuantity": { "type": "integer", "description": "Quantidade total de pedidos do cliente." }, "OrderRevenueValueTotal": { "type": "number", "format": "double", "description": "Soma dos valores das contas vinculadas ao cliente." }, "ServiceOrderRevenueValueTotal": { "type": "number", "format": "double", "description": "Receita total das NFs de serviço emitidas (`IDStatusInvoice=3`) para o cliente — soma de quantidade × valor unitário de cada item da NFSe." }, "Salesman": { "type": "string", "nullable": true, "description": "Lista (separada por vírgula) dos vendedores vinculados ao cliente." } } } } } } } } }, "post": { "operationId": "consumerPost", "tags": [ "Cadastro de Clientes" ], "summary": "Cria um cliente", "description": "Cria um cliente (PF ou PJ) no cadastro central. Usado pelo modal **Novo Cliente** e pela importação em massa via planilha (uma chamada por linha).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ConsumerType", "ConsumerNameCorporateName", "ConsumerCpfCnpj" ], "properties": { "ConsumerType": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Tipo do cliente: `1` Pessoa Física, `2` Pessoa Jurídica, `3` Estrangeiro." }, "ConsumerNameCorporateName": { "type": "string", "description": "Nome (PF) ou Razão Social (PJ)." }, "ConsumerCpfCnpj": { "type": "string", "description": "CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita apenas dígitos; é completado com zeros à esquerda até 11 ou 14." }, "ConsumerEmail": { "type": "string", "format": "email", "description": "E-mail do cliente. Aceita múltiplos e-mails separados por vírgula; cada um é validado individualmente." }, "ConsumerTelephone": { "type": "string", "description": "Telefone principal do cliente." }, "ConsumerTradeName": { "type": "string", "description": "Nome fantasia (PJ). Quando `ConsumerType=2` e o CNPJ é consultado automaticamente, é preenchido a partir da base pública." }, "ConsumerBirthDate": { "type": "string", "format": "date", "description": "Data de nascimento (PF) ou início de atividade (PJ), formato `YYYY-MM-DD`." }, "Comments": { "type": "string", "description": "Observações livres sobre o cliente." }, "IDTypeConsumerClassification": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "description": "Classificação do cliente: `1` Consumidor Final, `2` Empresa Simples (revenda), `3` Empresa Normal (revenda), `4` Empresa Normal (uso e consumo), `5` Indústria (compra para industrialização), `6` Empresa com Regime Especial, `7` Produtor Rural, `8` Empresa Simples (uso e consumo)." }, "ConsumerPriority": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Prioridade interna do cliente, de 0 a 10." }, "IDCarrier": { "type": "integer", "description": "Transportadora padrão do cliente (`IDSupplier` de uma transportadora cadastrada)." } } } } }, "description": "Dados do cliente a cadastrar. `ConsumerType`, `ConsumerNameCorporateName` e `ConsumerCpfCnpj` são obrigatórios; os demais são opcionais. Quando `ConsumerType=2` (PJ) com CNPJ válido, o sistema completa automaticamente endereço, nome fantasia e demais dados a partir da base pública de CNPJ. CPF/CNPJ é validado e não pode duplicar dentro da empresa." }, "responses": { "200": { "description": "Cliente criado. Retorna um array com o detalhe completo do cliente recém-criado (mesmo formato do `GET /consumer/{idconsumer}`), com o `IDConsumer` atribuído." }, "400": { "description": "Erros de validação (CPF/CNPJ duplicado, formato inválido, etc.)." } } } }, "/consumer/{idconsumer}": { "get": { "operationId": "consumerGet", "tags": [ "Cadastro de Clientes" ], "summary": "Detalhe do cliente", "description": "Retorna o cadastro completo do cliente (dados básicos + dados fiscais + métricas agregadas). Endpoints separados servem cada bloco do detalhe (`/consumer/{idconsumer}/address`, `/consumer/{idconsumer}/salesman`, `/consumer/{idconsumer}/credit`, `/consumer/{idconsumer}/voucher`).", "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do cliente." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "description": "Restringe o saldo de vale retornado (`ConsumerVoucherValue`) a um faturador específico. Só é considerado quando a empresa está configurada para restringir vale por faturador; caso contrário é ignorado." } ], "responses": { "200": { "description": "Detalhe do cliente." }, "404": { "description": "`[NotFound] - Cliente não encontrado`." } } }, "put": { "operationId": "consumerPut", "tags": [ "Cadastro de Clientes" ], "summary": "Atualiza dados do cliente", "description": "Atualiza dados básicos do cliente. Os blocos do detalhe (endereços, vendedores, créditos) têm endpoints próprios.", "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do cliente." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Atualização parcial do cliente — apenas os campos enviados são alterados.", "properties": { "ConsumerType": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Tipo do cliente: `1` Pessoa Física, `2` Pessoa Jurídica, `3` Estrangeiro." }, "ConsumerNameCorporateName": { "type": "string", "description": "Nome (PF) ou Razão Social (PJ)." }, "ConsumerCpfCnpj": { "type": "string", "description": "CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita apenas dígitos." }, "ConsumerEmail": { "type": "string", "format": "email", "description": "E-mail do cliente. Aceita múltiplos e-mails separados por vírgula; cada um é validado individualmente." }, "ConsumerTelephone": { "type": "string", "description": "Telefone principal do cliente." }, "ConsumerTradeName": { "type": "string", "description": "Nome fantasia (PJ)." }, "ConsumerBirthDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de nascimento (PF) ou início de atividade (PJ), `YYYY-MM-DD`. Enviar string vazia limpa o campo." }, "Comments": { "type": "string", "description": "Observações livres sobre o cliente." }, "StatusConsumer": { "type": "integer", "enum": [ 0, 1, 2, 3 ], "description": "Status do cliente: `0` Deletado, `1` Ativo, `2` Inativo, `3` Inadimplente." }, "IDTypeConsumerClassification": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "description": "Classificação do cliente: `1` Consumidor Final, `2` Empresa Simples (revenda), `3` Empresa Normal (revenda), `4` Empresa Normal (uso e consumo), `5` Indústria (compra para industrialização), `6` Empresa com Regime Especial, `7` Produtor Rural, `8` Empresa Simples (uso e consumo)." }, "ConsumerPriority": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Prioridade interna do cliente, de 0 a 10." }, "IDCarrier": { "type": "integer", "description": "Transportadora padrão (`IDSupplier` de uma transportadora cadastrada para a empresa)." }, "IDCompanySalesPolicy": { "type": "integer", "description": "Política comercial padrão vinculada ao cliente (`IDCompanySalesPolicy` de uma política cadastrada para a empresa)." } } } } }, "description": "Atualização do cadastro do cliente (parcial). Aceita os mesmos campos do POST mais `StatusConsumer`." }, "responses": { "200": { "description": "Cliente atualizado." }, "400": { "description": "Erro de validação." }, "404": { "description": "Cliente não encontrado." } } }, "delete": { "operationId": "consumerDelete", "tags": [ "Cadastro de Clientes" ], "summary": "Remove cliente (soft delete)", "description": "Marca o cliente como **Deletado** (`StatusConsumer=0`). **Não apaga fisicamente** — preserva histórico de pedidos, contas a receber e NFs emitidas. O cliente deixa de aparecer na listagem padrão (que filtra `StatusConsumer IN (1,2,3)`).", "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do cliente." } ], "responses": { "200": { "description": "Cliente marcado como deletado." }, "400": { "description": "Cliente tem vínculos ativos que impedem a remoção." }, "404": { "description": "Cliente não encontrado." } } } }, "/cte": { "get": { "operationId": "cteFeedGet", "tags": [ "CT-e" ], "summary": "Lista o feed de CT-e", "description": "Lista os CT-e emitidos contra o CNPJ da empresa, baixados automaticamente da SEFAZ. Para cada CT-e, traz: dados do documento (`CarrierInvoice`), descrição do tipo (`CtTpCte`), situação SEFAZ (`CtCSit`), tomador (`CtToma`), serviço prestado (`CttpServ`), pedido vinculado (`Orders` resolvido pela chave da NF-e citada), eventual conta a pagar associada (`AccountsPayableReceivable` resolvida por fornecedor + `CTeNumber`), peso do pedido vs. peso cobrado e diferenças, valores de frete e impostos, e URLs assinadas para XML/DANFE (servidor `Cte/.xml|pdf`).\n\nQuando o filtro `FreightConciliation=1` é informado, o sistema retorna uma listagem alternativa que cruza com `CarrierQuotation` + `CarrierQuotationRate` (leilão de frete) e expõe o campo calculado `IDStatusShippingAuctionDif` (`1` = simulado < cobrado, `2` = simulado > cobrado, `3` = empate), filtrável pelo parâmetro de mesmo nome. Útil para análise de divergência de frete.\n\nPaginação: **1000 por página** (`Page=N` → offset `N*1000`). Ordenação: registros agrupados por `IDCarrierInvoice` (uma linha por CT-e, sem ordenação explícita).", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Página 0-indexada. Offset = `Page * 1000`." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Empresa faturadora destinatária do CT-e (`IDCompanyInvoice`)." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`CTeDate` ≥ data." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`CTeDate` ≤ data + ` 23:59:59`." }, { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Número do pedido vinculado (`Order`)." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Código interno do pedido vinculado (`IDOrder`)." }, { "name": "InvoiceNumber", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Número da NF-e de produto citada no CT-e. Extraído das posições 26 a 34 da chave de acesso (`InvoiceAccessKey`)." }, { "name": "InvoiceAccessKey", "in": "query", "required": false, "schema": { "type": "string", "minLength": 44, "maxLength": 44 }, "description": "Chave de acesso da NF-e de produto citada (44 dígitos)." }, { "name": "SupplierNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome/razão social da transportadora emissora do CT-e (LIKE)." }, { "name": "IDCarrier", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Transportadora cadastrada com integração ativa (`IDSupplier` com `TypeCarrier`)." }, { "name": "CTeSit", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 3 ] }, "description": "Situação SEFAZ: `1` Uso autorizado, `3` CT-e Cancelada (`SitCte`)." }, { "name": "CTeType", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ] }, "description": "Tipo: `0` Normal, `1` Complementar, `2` Anulação, `3` Substituição, `4` Fatura (`CtTpCte`)." }, { "name": "CTeToma", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ] }, "description": "Tipo de tomador do frete: `0` Remetente, `1` Expedidor, `2` Recebedor, `3` Destinatário, `4` Outros (`CtToma`)." }, { "name": "FreightConciliation", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` ativa modo de conciliação de frete (compara o `R$ frete total` cobrado com o `ShipingValue` da `CarrierQuotationRate`). Habilita o filtro `IDStatusShippingAuctionDif`." }, { "name": "IDStatusShippingAuctionDif", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3 ] }, "description": "Aplicável apenas com `FreightConciliation=1`. Filtra pelo resultado da comparação: `1` simulado < cobrado, `2` simulado > cobrado, `3` empate." } ], "responses": { "200": { "description": "Array de CT-e. Quando nenhum casa com os filtros, retorna `[]`. Cada item segue o schema `CarrierInvoiceFeedItem`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierInvoiceFeedItem" } } } } } } } }, "/cte/invoice-xml": { "get": { "operationId": "cteFeedXmlGet", "tags": [ "CT-e" ], "summary": "Serve XML/PDF individual de um CT-e", "description": "Serve o XML (`Type=XML`) ou o PDF da DANFE (`Type=PDF`) de um CT-e individual. Não é chamado diretamente pelo frontend — as URLs já vêm prontas no corpo de `GET /cte` nos campos `XmlFile` (XML) e `XmlDanfe` (PDF), assinadas com o `token` do contexto do usuário.", "parameters": [ { "name": "Folder", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "Cte" ] }, "description": "Pasta no S3 — sempre `Cte`." }, { "name": "Type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "XML", "PDF" ] }, "description": "`XML` devolve o arquivo XML do CT-e; `PDF` devolve o PDF da DANFE." }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Token de autenticação do usuário (já incluído nas URLs geradas por `GET /cte`)." }, { "name": "File", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Nome do arquivo no S3 — `.xml`." } ], "responses": { "200": { "description": "Conteúdo binário (XML ou PDF)." } } }, "post": { "operationId": "cteFeedXmlDownload", "tags": [ "CT-e" ], "summary": "Baixa XML de vários CT-e em lote", "description": "Empacota em um único `.zip` os XMLs dos CT-e informados e gera uma URL pré-assinada do S3 para download.\n\nBody: **array de inteiros** com os `IDCarrierInvoice` das linhas selecionadas. O sistema localiza os CT-e correspondentes no bucket (`Cte/.xml`), compacta e devolve a URL.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64", "description": "Código interno (`IDCarrierInvoice`) da linha do CT-e." } } } }, "description": "Array de `IDCarrierInvoice` (inteiros) — as linhas selecionadas na listagem de CT-e a incluir no pacote `.zip`. O sistema localiza o XML de cada CT-e em `Cte/.xml` no S3, compacta e envia uma URL pré-assinada (válida por 2 dias) pelo e-mail do usuário; a resposta da chamada também devolve a URL." }, "responses": { "200": { "description": "URL pré-assinada para download do zip.", "content": { "application/json": { "schema": { "type": "string", "format": "uri" } } } } } } }, "/purchase/buy-order": { "get": { "operationId": "buyOrderList", "tags": [ "Pedido de Compra" ], "summary": "Lista pedidos de compra", "description": "Lista os pedidos de compra da empresa autenticada com dados do fornecedor, status, comprador, data prevista de entrega, totais e flags relevantes. Sem filtro de status na querystring, a tela aplica filtro default `0,3,1,6` (Aberto, Pedido Confirmado, Aguardando Recebimento, Recebido Parcialmente) — para incluir Finalizado/Cancelado/Mesclado, o consumidor precisa informar `IDStatusBuyOrder` explicitamente.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Número da página da listagem (1-based). Padrão `1`." }, { "name": "IDStatusBuyOrder", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer", "enum": [ 0, 1, 2, 3, 5, 6, 7 ] } }, "description": "Status. CSV aceito. Valores: `0` Aberto, `1` Aguardando Recebimento, `2` Cancelado, `3` Pedido Confirmado, `5` Finalizado, `6` Recebido Parcialmente, `7` Mesclado.", "style": "form", "explode": false }, { "name": "IDBuyOrder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código interno do pedido. CSV aceito." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de criação ≥ data." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de criação ≤ data." }, { "name": "DateDueFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data prevista de entrega ≥ data. Combinado com `IDStatusBuyOrder=1,6` e data menor que hoje, identifica pedidos atrasados." }, { "name": "DateDueTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data prevista de entrega ≤ data." }, { "name": "IDSupplier", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Fornecedor (`IDSupplier`)." }, { "name": "SupplierNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Razão social do fornecedor (LIKE)." }, { "name": "RecordUserCreated", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Comprador (usuário) que criou o pedido." }, { "name": "IDSku", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pedidos que contêm o SKU informado." }, { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Centro de distribuição destino." } ], "responses": { "200": { "description": "Array de pedidos de compra com dados do fornecedor, status, totais (`ValueProductsTotal`, `SkuQuantity`, `ItemsQuantity`) e flags." } } }, "post": { "operationId": "buyOrderPost", "tags": [ "Pedido de Compra" ], "summary": "Cria pedido de compra", "description": "Cria um pedido novo. Quando a parametrização `BuyOrderComments` está preenchida, o sistema injeta o texto no campo `Comments`. Quando `ShowAllSuppliersBuyOrder=0` (default), o sistema valida que o fornecedor tenha categoria Produto.", "requestBody": { "description": "Cria o cabeçalho do pedido de compra. Os itens são adicionados depois via `POST /purchase/buy-order/{idbuyorder}/sku`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "IDSupplier": { "type": "integer", "description": "Fornecedor do pedido de compra." }, "IDOrder": { "type": "integer", "description": "Pedido de venda vinculado, quando o pedido de compra nasce de uma venda. Opcional." }, "Comments": { "type": "string", "description": "Observações do pedido de compra." }, "IDCompanyInvoice": { "type": "integer", "description": "Faturador (empresa do grupo) do pedido de compra." }, "EstimatedReceiptDate": { "type": "string", "format": "date", "description": "Data estimada de recebimento (`YYYY-MM-DD`)." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Centro de distribuição de destino." } }, "required": [ "IDSupplier" ] } } } }, "responses": { "200": { "description": "Pedido criado. Retorna `{ response: [{IDBuyOrder, SupplierNameCorporateName, ...}] }`." }, "400": { "description": "Erros: fornecedor de categoria inválida, item sem SKU, etc." } } } }, "/purchase/buy-order/{idbuyorder}": { "get": { "operationId": "buyOrderGet", "tags": [ "Pedido de Compra" ], "summary": "Detalhe do pedido de compra", "parameters": [ { "name": "idbuyorder", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do pedido de compra." } ], "responses": { "200": { "description": "Detalhe completo do pedido." }, "404": { "description": "Pedido não encontrado." } }, "description": "Retorna o detalhe completo de um pedido de compra: fornecedor, itens (SKU, quantidade, preço unitário), centro de distribuição de destino e situação. Use para conferência e acompanhamento do pedido antes do recebimento." }, "put": { "operationId": "buyOrderPut", "tags": [ "Pedido de Compra" ], "summary": "Atualiza pedido de compra", "description": "Atualiza dados básicos, itens, valores ou status. Quais alterações são permitidas depende do `IDStatusBuyOrder` atual — pedidos `Aberto` aceitam tudo; `Pedido Confirmado` em diante restringe alterações de itens/valores. Mudança para status `Finalizado` exige `PrivilegeBuyOrderFinish` e é irreversível.", "parameters": [ { "name": "idbuyorder", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do pedido de compra." } ], "requestBody": { "description": "Atualização parcial do cabeçalho do pedido de compra.", "content": { "application/json": { "schema": { "type": "object", "properties": { "IDSupplier": { "type": "integer", "description": "Fornecedor do pedido de compra." }, "IDOrder": { "type": "integer", "description": "Pedido de venda vinculado. Opcional." }, "Comments": { "type": "string", "description": "Observações." }, "IDStatusBuyOrder": { "type": "integer", "enum": [ 0, 1, 2, 3, 5, 6, 7 ], "description": "Status do pedido de compra: `0` Aberto, `1` Aguardando Recebimento, `2` Cancelado, `3` Pedido Confirmado, `5` Finalizado, `6` Recebido Parcialmente, `7` Mesclado." }, "IDCompanyInvoice": { "type": "integer", "description": "Faturador do pedido de compra." }, "EstimatedReceiptDate": { "type": "string", "format": "date", "description": "Data estimada de recebimento (`YYYY-MM-DD`)." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Centro de distribuição de destino." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém de destino." } } } } } }, "responses": { "200": { "description": "Pedido atualizado." }, "400": { "description": "Transição de status inválida ou alteração não permitida no status atual." } } }, "delete": { "operationId": "buyOrderDelete", "tags": [ "Pedido de Compra" ], "summary": "Remove pedido de compra", "description": "Remove o pedido. Bloqueado quando o status é `Finalizado` (5), `Cancelado` (2), `Recebido Parcialmente` (6) ou `Mesclado` (7) — nesses casos, retorna `[BadRequest]` com mensagem específica.", "parameters": [ { "name": "idbuyorder", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do pedido de compra." } ], "responses": { "200": { "description": "Pedido removido." }, "400": { "description": "Pedido em status que bloqueia remoção." } } } }, "/purchase/feed": { "get": { "operationId": "purchaseFeed", "tags": [ "Feed de NF-e" ], "summary": "Lista o feed de NF-e recebidas", "description": "Lista as NF-e emitidas contra o CNPJ da empresa, baixadas automaticamente da SEFAZ. Cada linha vem com dados da nota (número, série, chave de acesso, fornecedor, valor, datas), descrição do tipo (Entrada/Saída via `NfTpNf`), descrição do último evento (`NfTpEvent`), situação SEFAZ (`NfCSit`), tags internas, eventual recebimento criado (`IDPurchase`), eventual conta a pagar associada (`IDAccountPayableReceivable`, resolvida por fornecedor + número de documento) e URLs assinadas para o **XML** e a **DANFE** (servidor `/invoice/danfe?Folder=Inbound&Type=XML|PDF&Origin=Feed&token=...&File=`).\n\nPaginação: **500 por página** (`Page=N` → offset `N*500`). Ordenação: `ORDER BY IDNfEvents DESC`.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Página 0-indexada. Offset = `Page * 500`." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Empresa faturadora (`IDCompanyInvoice` → `IDCompany`). Usado em ambientes multi-empresa." }, { "name": "SupplierNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome/razão social do fornecedor (LIKE em `SupplierNameCorporateName`)." }, { "name": "NfeNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Número da NF-e (`NFeNumber`). Aceita com pontuação — apenas os dígitos são considerados." }, { "name": "SupplierCpfCnpj", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CPF/CNPJ do fornecedor (LIKE). Pontuação é removida pelo sistema antes da consulta." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`NFeDate` ≥ data (data de emissão)." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "`NFeDate` ≤ data + ` 23:59:59`." }, { "name": "IDNfEvents", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Código interno da linha do feed. Útil para buscar uma linha específica." }, { "name": "Tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra apenas linhas que têm a tag informada em `Tag`." } ], "responses": { "200": { "description": "Lista de NF-e do feed. Quando nenhum registro casa com os filtros, retorna `[]`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseFeedItem" } } } } } } } }, "/purchase/feed/{idnfevents}": { "put": { "operationId": "purchaseFeedPut", "tags": [ "Feed de NF-e" ], "summary": "Atualiza tags da NF do feed", "description": "Sincroniza as tags internas da linha (`NfEventsTag`) com o array `Tags` enviado no body. Fluxo:\n\n1. Localiza a nota por `IDNfEvents` + `AccountName = prefix`. Falha com `[BadRequest] - Nota fiscal não existe` se não encontrar.\n2. Compara as tags atuais com o array enviado.\n3. Tags presentes no array enviado que ainda não existem são adicionadas.\n4. Tags atuais que não estão no array enviado são removidas.\n5. Quando o array vier vazio, todas as tags da linha são removidas.\n6. Devolve a linha atualizada.\n\nO array `Tags` é livre — qualquer string de até 255 caracteres pode ser usada como tag. A tela usa o componente Select com modo `tags` para criar/reutilizar.", "parameters": [ { "name": "idnfevents", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Código interno da linha do feed." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Tags" ], "properties": { "Tags": { "type": "array", "items": { "type": "string" }, "description": "Estado desejado das tags. Para limpar, envie `[]`." } } } } }, "description": "Estado desejado das tags da nota fiscal. O array é a verdade — tags atuais que não estão no array são removidas, e tags do array que ainda não existem são criadas. Enviar `[]` apaga todas as tags da nota." }, "responses": { "200": { "description": "Linha do feed atualizada (array com 1 item, mesmo schema de `GET /purchase/feed`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseFeedItem" } } } } }, "400": { "description": "Mensagens emitidas: `[BadRequest] - Nota fiscal não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase/feed/{idnfevents}/manifest": { "post": { "operationId": "purchaseFeedManifestPut", "tags": [ "Feed de NF-e" ], "summary": "Manifesta a NF perante a SEFAZ", "description": "Envia um evento de manifestação do destinatário à SEFAZ para a nota informada. O evento fica registrado no histórico oficial da nota e não pode ser desfeito. Eventos aceitos: `210200` Confirmação da Operação, `210210` Ciência da Emissão, `210220` Desconhecimento da Operação e `210240` Operação não Realizada — este último exige `Comments` com pelo menos 15 caracteres. O frontend usa o mesmo endpoint na ação em lote, iterando uma chamada por nota selecionada.", "parameters": [ { "name": "idnfevents", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Código interno da linha do feed." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Event" ], "properties": { "Event": { "type": "integer", "enum": [ 210200, 210210, 210220, 210240 ], "description": "Código do evento de manifestação do destinatário enviado à SEFAZ: `210200` Confirmação da Operação, `210210` Ciência da Emissão, `210220` Desconhecimento da Operação, `210240` Operação não Realizada. Outro valor é rejeitado com `Evento não permitido`." }, "Comments": { "type": "string", "minLength": 15, "description": "Motivo da manifestação. Obrigatório apenas quando `Event=210240` (Operação não Realizada), com no mínimo 15 caracteres — abaixo disso a operação é recusada. Para os demais eventos é opcional e ignorado." } } } } } }, "responses": { "200": { "description": "Manifestação aceita pela SEFAZ. O evento fica registrado no histórico da nota e passa a aparecer na coluna `Evento` do feed." }, "400": { "description": "Validação ou erro retornado pela SEFAZ. Mensagens possíveis: `Evento não permitido` (quando `Event` está fora dos valores aceitos), `Motivo do evento precisa ser maior que 15 caracteres` (`Event=210240` com `Comments` abaixo de 15 caracteres), `Nota não encontrada`, `Empresa não localizada`, `Certificado digital não encontrado`, além do motivo (`xMotivo`) devolvido pela própria SEFAZ quando a manifestação é rejeitada." } } } }, "/purchase/feed/invoice-xml": { "post": { "operationId": "purchaseFeedXmlGet", "tags": [ "Feed de NF-e" ], "summary": "Baixa XML de várias NFs em lote", "description": "Empacota em um único `.zip` os XMLs das notas informadas e gera uma **URL pré-assinada do S3** (TTL 2 dias) para download. Em paralelo, envia o link **por e-mail** ao usuário logado (template `Inbound`).\n\nFonte dos arquivos: bucket `idworks`, prefixo `Inbound/.xml`. Os XMLs são copiados/arquivados via `s3-zip` (sem preservar hierarquia de pastas) e o zip resultante é gravado em `Temp/.zip`.\n\nO body é um **array de strings** no formato `.xml` (cada string corresponde a uma nota). O frontend filtra antes de enviar — exclui linhas sem `NFeNumber` e linhas com situação diferente de `Uso autorizado`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "description": "Nome do arquivo XML no S3 — `.xml`.", "minLength": 48, "maxLength": 48 } } } }, "description": "Array com os nomes dos arquivos XML a empacotar, no formato `.xml`. O frontend exclui antes de enviar as linhas sem `NFeNumber` e as com situação SEFAZ diferente de `Uso autorizado`." }, "responses": { "200": { "description": "URL pré-assinada para download do zip. Resposta é a URL pura (string). Em paralelo, um e-mail com o mesmo link é enviado ao usuário logado.", "content": { "application/json": { "schema": { "type": "string", "format": "uri", "example": "https://idworks.s3.amazonaws.com/Temp/abc.zip?X-Amz-Algorithm=..." } } } }, "500": { "description": "Falha ao compactar ou subir o zip. Mensagens começam com `zipFile.upload error` ou `catched error:`." } } } }, "/purchase/feed/invoice-danfe": { "post": { "operationId": "purchaseFeedDanfeBulkPost", "tags": [ "Feed de NF-e" ], "summary": "Baixa DANFE de várias NFs em lote", "description": "Empacota em um único `.zip` os PDFs de DANFE das notas informadas e gera uma URL para download (mesmo fluxo do `invoice-xml`, mas para PDFs).\n\nO body é um **array de inteiros** com os `IDNfEvents` das notas a baixar.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64", "description": "Código interno (`IDNfEvents`) da linha do feed." } } } }, "description": "Array de `IDNfEvents` (códigos internos das linhas do feed) cujas DANFEs PDF serão empacotadas em um único `.zip`." }, "responses": { "200": { "description": "URL pré-assinada para download do zip de PDFs.", "content": { "application/json": { "schema": { "type": "string", "format": "uri" } } } } } } }, "/purchase/feed/tag": { "get": { "operationId": "purchaseFeedTagList", "tags": [ "Feed de NF-e" ], "summary": "Lista tags do feed", "description": "Lista todas as tags já cadastradas em notas do feed da empresa autenticada (`Tag` agrupado). Usado pelo seletor de Tags do modal **Adicionar Tag** e pelo filtro **Tags** do painel de filtros.", "responses": { "200": { "description": "Array com as tags distintas.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "Tag": { "type": "string", "description": "Texto da tag." } } } } } } } } } }, "/purchase/xml": { "post": { "operationId": "purchaseInvoiceXmlPost", "tags": [ "Recebimento" ], "summary": "Cria recebimento a partir de NF do Feed, pedido próprio ou XML cru", "description": "Wrapper para criar e popular o recebimento em um único chamado. Resolve o XML de 3 fontes:\n1. `?IDNfEvents=` — usa o XML do Feed NF (NFEvents).\n2. `?IDOrder=` — usa o XML de um pedido próprio (devolução de cliente).\n3. Body — XML cru no body da requisição.\n\nFluxo:\n- Resolve fornecedor por CNPJ (cria novo `Suppliers` quando não existe, vinculando à categoria padrão de produto).\n- Cria `StockKeepingUnitPurchase` em status 0.\n- Processa o XML completo (impostos, SKUs, lotes, duplicatas).\n- Se a importação falha, deleta o recebimento criado.\n\n**`?OnlyPayment=1`** pula a criação do recebimento e cria apenas as contas a pagar do XML.", "parameters": [ { "name": "IDNfEvents", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "ID da NF do Feed NF (`NfEvents`)." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Pedido de venda própria (para criar recebimento de devolução)." }, { "name": "OnlyPayment", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` cria apenas contas a pagar do XML." }, { "name": "IDStockKeepingUnitWarehouse", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador do depósito do SKU." }, { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador do centro de distribuição do SKU." }, { "name": "ImportType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Critério de matching de SKU (CSV). `1`=código fornecedor, `2`=código de barras, `3`=código de referência, `5`=código integração/hub." } ], "requestBody": { "required": false, "content": { "application/xml": { "schema": { "type": "string", "format": "binary", "description": "XML da NF-e cru (alternativa a `IDNfEvents`/`IDOrder`)." } } }, "description": "Corpo do `POST /purchase/xml`: conteúdo bruto do XML da NF-e a importar (texto, geralmente enviado como `text/xml` e podendo vir em base64 que o sistema decodifica). Só é exigido quando a importação não é feita por `IDOrder` ou `IDNfEvents` na query string." }, "responses": { "200": { "description": "Recebimento criado." }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Precisa ser enviado o IDOrder ou IDNfEvents ou XML`\n- `Nota fiscal não encontrada`\n- `Nota fiscal de saída não permite criar recebimento. Gerar pedido de devolução para criar recebimento`\n- `Armazém não encontrado`\n- `Já existe contas a pagar cadastrada` (OnlyPayment)\nMais erros propagados do processamento do XML (XML inválido, SKU não encontrado, etc.).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase/schedule": { "get": { "operationId": "purchaseScheduleList", "tags": [ "Agendamento de Recebimento" ], "summary": "Lista agendamentos de recebimento", "description": "Lista os agendamentos da empresa, ordenados por `StartTime` ascendente. Cada item traz cabeçalho (`StartTime`, `EndTime`, `ScheduleTitle`, `Comments`, `IDPurchase`) **e** dados resolvidos do recebimento amarrado (quando houver):\n\n- Fornecedor: `SupplierCpfCnpj`, `SupplierNameCorporateName`.\n- Nota fiscal: `serie`, `nNF`, `dhEmi` (emissão), `qVol` (volumes), `pesoB` (peso bruto, exposto como `Weight`).\n- Recebimento: `CheckinTimestamp`, `StatusPurchase`, `IDStatusPurchase`.\n- Agregados calculados: `ItemsQuantity` (soma de quantidades em `StockKeepingUnitMovement`) e `SkuQuantity` (SKUs distintos no recebimento).\n- `StockKeepingUnitPurchaseScheduleStatus` (`1`-`4`) + `StockKeepingUnitPurchaseScheduleStatusDescription` (`Recebido`, `Agendado`, `Atrasado`, `Não agendado`) — derivado de `CheckinTimestamp` e `EndTime` em relação ao momento atual: `Recebido` quando há check-in, `Agendado` quando o `EndTime` ainda não passou, `Atrasado` quando passou sem check-in, `Não agendado` quando não há recebimento amarrado.", "parameters": [ { "name": "IDStockKeepingUnitPurchaseSchedule", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do agendamento de compra do SKU." }, { "name": "IDPurchase", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador da compra." }, { "name": "StartTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra agendamentos com `StartTime` a partir desta data (inclusive)." }, { "name": "EndTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra agendamentos com `EndTime` até o final desta data (inclusive)." } ], "responses": { "200": { "description": "Lista de agendamentos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseScheduleItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "purchaseSchedulePost", "tags": [ "Agendamento de Recebimento" ], "summary": "Cria agendamento", "description": "Cria um agendamento. Validações:\n\n- `StartTime ≤ EndTime` — caso contrário `Data de início precisa ser menor que data de término`.\n- Quando `IDPurchase` é informado: o recebimento precisa existir na empresa **e** ainda não ter agendamento ativo. Se já tem, devolve `Recebimento já esta agendado para `.\n- `IDPurchase` ausente cria **agendamento avulso** (bloqueio na agenda sem amarrar recebimento).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseScheduleCreate" } } }, "description": "Dados do agendamento de recebimento a cadastrar. Obrigatórios `StartTime` e `EndTime` (com `StartTime` <= `EndTime`). Opcionais: `Comments`, `ScheduleTitle` e `IDPurchase` (recebimento associado — quando informado, precisa existir e não pode já estar agendado)." }, "responses": { "200": { "description": "Agendamento criado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseScheduleItem" }, "maxItems": 1 } } } }, "400": { "description": "`[BadRequest] - Data de início precisa ser menor que data de término`; `[BadRequest] - Recebimento já esta agendado para `; `[BadRequest] - Recebimento não existe`; `[BadRequest] - Empresa não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase/schedule/{idstockkeepingunitpurchaseschedule}": { "parameters": [ { "name": "idstockkeepingunitpurchaseschedule", "in": "path", "required": true, "schema": { "type": "integer" } } ], "put": { "operationId": "purchaseSchedulePut", "tags": [ "Agendamento de Recebimento" ], "summary": "Atualiza agendamento", "description": "Atualização parcial. Mesmas validações do POST (data início ≤ fim; recebimento único). Trocar `IDPurchase` exige que o novo recebimento não esteja agendado ainda.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseScheduleCreate" } } }, "description": "Campos do agendamento de recebimento a atualizar — apenas os enviados são aplicados. Aceita `StartTime`, `EndTime`, `Comments`, `ScheduleTitle` e `IDPurchase`; quando ambas as datas são enviadas, `StartTime` precisa ser menor ou igual a `EndTime` e o recebimento informado não pode já estar agendado em outro registro." }, "responses": { "200": { "description": "Agendamento atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseScheduleItem" }, "maxItems": 1 } } } }, "400": { "description": "`[BadRequest] - Agendamento não existe`; demais idem POST.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "purchaseScheduleDelete", "tags": [ "Agendamento de Recebimento" ], "summary": "Exclui agendamento", "description": "Exclusão física. Sem regra de bloqueio — agendamento amarrado a recebimento já recebido pode ser apagado (mas geralmente se mantém para histórico).", "responses": { "200": { "description": "Agendamento excluído.", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "`[BadRequest] - Agendamento não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase/schedule/config": { "get": { "operationId": "purchaseScheduleConfigList", "tags": [ "Agendamento de Recebimento" ], "summary": "Lista configurações de agendamento de recebimento", "description": "Lista as configurações de agendamento da empresa. Cada item traz o cabeçalho da configuração (duração, limites, antecedência, tolerância) **e** o array `StockKeepingUnitPurchaseScheduleConfigTimetable` com todas as faixas de horário por dia da semana já resolvidas (ordenadas por `WeekDay ASC, StartTime ASC`).", "parameters": [ { "name": "IDStockKeepingUnitPurchaseScheduleConfig", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por id específico." } ], "responses": { "200": { "description": "Lista de configurações.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseScheduleConfigItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "purchaseScheduleConfigPost", "tags": [ "Agendamento de Recebimento" ], "summary": "Cria configuração de agendamento", "description": "Cria a configuração para um CD. Validações:\n- `IDStockKeepingUnitDistributionCenter` obrigatório e precisa pertencer à empresa.\n- **Um CD pode ter apenas 1 configuração** — segunda tentativa devolve `[BadRequest] - Já existe uma agenda para esse centro de distribuição`.\n- `StockKeepingUnitPurchaseScheduleConfigTimetable` (quando enviado) é um array de faixas de horário, cada uma com `WeekDay` (0-6), `StartTime` e `EndTime`. Quando omitido, a configuração é criada sem horários e o agendamento fica indisponível até o operador editar.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseScheduleConfigCreate" } } }, "description": "Configurações da agenda de recebimento de um centro de distribuição. Obrigatório `IDStockKeepingUnitDistributionCenter` (precisa existir e não pode já ter agenda cadastrada). Campos: `ScheduleDurationMinutes`, `ScheduleMaximumTimeAheadDay`, `ScheduleMinimumAdvanceTimeHour`, `MaxSchedulePerDay`, `MaxItemsPerDay`, `HourDifferenceAllowed` e `StockKeepingUnitPurchaseScheduleConfigTimetable` (array com a janela semanal — cada item tem `WeekDay`, `StartTime` e `EndTime`)." }, "responses": { "200": { "description": "Configuração criada (formato da listagem).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseScheduleConfigItem" }, "maxItems": 1 } } } }, "400": { "description": "`[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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase/schedule/config/{idstockkeepingunitpurchasescheduleconfig}": { "parameters": [ { "name": "idstockkeepingunitpurchasescheduleconfig", "in": "path", "required": true, "schema": { "type": "integer" } } ], "put": { "operationId": "purchaseScheduleConfigPut", "tags": [ "Agendamento de Recebimento" ], "summary": "Atualiza configuração de agendamento", "description": "Atualização parcial. Comportamento do `StockKeepingUnitPurchaseScheduleConfigTimetable`:\n- **Não enviado**: timetable atual fica intacta.\n- **Array vazio** (`[]`): **apaga** todas as faixas atuais — agendamento fica indisponível.\n- **Array preenchido**: **substitui** as faixas atuais (DELETE + INSERT em bloco).\n\nValidações: troca de `IDStockKeepingUnitDistributionCenter` exige que o novo CD não tenha outra configuração existente.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseScheduleConfigUpdate" } } }, "description": "Campos da configuração da agenda a atualizar — apenas os enviados são aplicados. Aceita `ScheduleDurationMinutes`, `ScheduleMaximumTimeAheadDay`, `ScheduleMinimumAdvanceTimeHour`, `MaxSchedulePerDay`, `MaxItemsPerDay`, `IDStockKeepingUnitDistributionCenter`, `HourDifferenceAllowed` e `StockKeepingUnitPurchaseScheduleConfigTimetable` (substitui a janela semanal — array vazio remove todos os horários; cada item tem `WeekDay`, `StartTime` e `EndTime`)." }, "responses": { "200": { "description": "Configuração atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseScheduleConfigItem" }, "maxItems": 1 } } } }, "400": { "description": "`[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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "purchaseScheduleConfigDelete", "tags": [ "Agendamento de Recebimento" ], "summary": "Exclui configuração de agendamento", "description": "**Exclusão física**. As faixas de horário vinculadas são removidas automaticamente em cascata. Devolve a string literal `sucesso`.", "responses": { "200": { "description": "Configuração excluída.", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "`[BadRequest] - Configuração agendamento não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/picking/configuration": { "get": { "operationId": "orderFulfillmentPickingConfigurationList", "tags": [ "Picking" ], "summary": "Lista configurações de geração de picking list", "description": "Lista as configurações da empresa. Retorna o nome resolvido do CD (`DistributionCenterName`) e do tipo de picking (`TypePickingList`). As listas CSV (`IDCompanyIntegrationList`, `IDOrderTypeList`, `IDCarrierList`, `WeekIntervalAutoGenerate`) são devolvidas como **arrays** depois do `split(',')`.", "parameters": [ { "name": "IDPickingListConfiguration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador da configuração de lista de separação." } ], "responses": { "200": { "description": "Lista das configurações.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PickingListConfigurationItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "orderFulfillmentPickingConfigurationPost", "tags": [ "Picking" ], "summary": "Cria uma configuração de picking list", "description": "Cria uma configuração. Validações:\n\n- `PickingListConfigurationName` obrigatório e **único** dentro da empresa.\n- `StartAutoGenerateTime` e `FinishAutoGenerateTime` obrigatórios e `Start ≤ Finish`.\n- `ItemsQtyLimit`, `OrderQtyLimit`, `SkuQtyLimit` precisam ser numéricos (quando informados).\n- `OrderPriority` entre 0 e 10 (quando informado).\n- `WeekIntervalAutoGenerate` é um array de inteiros 0-6 (0=Domingo, 6=Sábado).\n- Cada `IDCompanyIntegration` precisa pertencer à empresa e ter `Show = 1`.\n- Cada `IDTypeOrder` precisa pertencer à empresa e ter `Status = 1`.\n- Cada `IDCarrier` precisa ser um fornecedor da empresa com `IDTypeSupplier = 2` (Transportadora).\n- `IDStockKeepingUnitDistributionCenter` precisa pertencer à empresa.\n- `IDTypePickingList` precisa existir (1=Picking, 2=Picking & Packing, 3=Monopedido, 4=Colméia).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickingListConfigurationCreate" } } }, "description": "Cria uma configuração de geração automática de picking-list. Define o CD, o tipo de coleta gerado, a janela diária (início/fim/dias da semana), os filtros de pedido (integração, tipo, transportadora) e os limites (itens, pedidos, SKUs, cestos). Veja `PickingListConfigurationCreate`." }, "responses": { "200": { "description": "Configuração criada (formato da listagem).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PickingListConfigurationItem" }, "maxItems": 1 } } } }, "400": { "description": "`[BadRequest] - Preencha corretamente o nome da configuração`; `[BadRequest] - Nome de configuração já existente`; `[BadRequest] - Preencha corretamente quantidade de itens, pedidos e skus`; `[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): `; `[BadRequest] - Tipo pedido(s) não localizada(s): `; `[BadRequest] - Transportadora(s) não localizada(s): `; `[BadRequest] - Centro de distribuição não existe`; `[BadRequest] - Tipo de picking list não existe`; `[BadRequest] - Empresa não existe`; `[BadRequest] - Erro ao cadastrar configuração`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/picking/configuration/{idpickinglistconfiguration}": { "parameters": [ { "name": "idpickinglistconfiguration", "in": "path", "required": true, "schema": { "type": "integer" } } ], "put": { "operationId": "orderFulfillmentPickingConfigurationPut", "tags": [ "Picking" ], "summary": "Atualiza uma configuração de picking list", "description": "Atualização parcial. Aplica as mesmas validações do POST (exceto que `PickingListConfigurationName` não é validado por unicidade — pode manter o nome original). Aceita listas vazias para limpar campos CSV (`IDCompanyIntegrationList`, `IDOrderTypeList`, `IDCarrierList`, `WeekIntervalAutoGenerate`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickingListConfigurationUpdate" } } }, "description": "Atualização parcial da configuração. Aceita qualquer subconjunto dos campos de `PickingListConfigurationCreate`; campos omitidos preservam o valor atual." }, "responses": { "200": { "description": "Configuração atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PickingListConfigurationItem" }, "maxItems": 1 } } } }, "400": { "description": "Validações idem POST + `[BadRequest] - Configuração picking list não encontrada`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "orderFulfillmentPickingConfigurationDelete", "tags": [ "Picking" ], "summary": "Exclui uma configuração de picking list", "description": "**Exclusão física**. Sem regras de bloqueio — picking lists geradas continuam no histórico mesmo após excluir a configuração que as gerou. Devolve a string literal `Configuração de picking-list excluída com sucesso`.", "responses": { "200": { "description": "Configuração excluída.", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "`[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).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/distribution-center": { "get": { "operationId": "skuDistributionCenterList", "tags": [ "Centros de Distribuição" ], "summary": "Lista centros de distribuição", "description": "Lista os CDs da empresa, ordenados por `DistributionCenterName`. Respeita restrição de CDs permitidos ao usuário.", "parameters": [ { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por id; aceita lista CSV." } ], "responses": { "200": { "description": "Lista de CDs.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DistributionCenterItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuDistributionCenterPost", "tags": [ "Centros de Distribuição" ], "summary": "Cria centro de distribuição", "description": "Cria um CD. Nome único por empresa. Quando `Default = 1` (default ausente), o sistema zera o `Default` dos demais CDs da empresa antes de inserir. Devolve a lista completa atualizada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistributionCenterCreate" } } }, "description": "Dados do centro de distribuição a cadastrar." }, "responses": { "200": { "description": "CD criado (devolve lista completa).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DistributionCenterItem" } } } } }, "400": { "description": "`[BadRequest] - Já existe um centro de distribuição com este nome`; `[BadRequest] - Company não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/distribution-center/{idstockkeepingunitdistributioncenter}": { "parameters": [ { "name": "idstockkeepingunitdistributioncenter", "in": "path", "required": true, "schema": { "type": "integer" } } ], "put": { "operationId": "skuDistributionCenterPut", "tags": [ "Centros de Distribuição" ], "summary": "Atualiza centro de distribuição", "description": "Atualização parcial. Valida unicidade do nome dentro da empresa. Marcar `Default = 1` zera o `Default` dos demais CDs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistributionCenterCreate" } } }, "description": "Atualiza o centro de distribuição. Mesmo schema do POST." }, "responses": { "200": { "description": "CD atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DistributionCenterItem" } } } } }, "400": { "description": "`[BadRequest] - Centro de distribuição não existe`; `[BadRequest] - Já existe um centro de distribuição com este nome`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuDistributionCenterDelete", "tags": [ "Centros de Distribuição" ], "summary": "Exclui centro de distribuição", "description": "**Exclusão física** com várias regras de bloqueio em cascata:\n\n1. Armazéns vinculados → bloqueia.\n2. CD padrão → exige definir outro antes.\n3. Histórico de recebimento (`StockKeepingUnitPurchase`) → bloqueia.\n4. Histórico de pedidos (`Orders`) → bloqueia.\n5. Histórico de pedido de compra (`StockKeepingUnitBuyOrder`) → bloqueia.\n6. Usuários com vínculo (`UserCompanyDistributionCenter`) → bloqueia.\n7. Ressuprimento (`StockKeepingUnitResupplyList`) → bloqueia.\n8. Inventário (`StockKeepingUnitInventorySummary`) → bloqueia.", "responses": { "200": { "description": "CD excluído.", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "`[BadRequest] - Existem armazéns vinculados a este centro de distribuição`; `[BadRequest] - Precisa definir outro centro de distribuição padrão antes de deletar`; `[BadRequest] - Centro de distribuição já teve recebimento e não pode ser excluído`; `[BadRequest] - Centro de distribuição já teve pedido e não pode ser excluído`; `[BadRequest] - Centro de distribuição já teve pedido de compra e não pode ser excluído`; `[BadRequest] - Centro de distribuição está vinculado a usuário e não pode ser excluído`; `[BadRequest] - Centro de distribuição está vinculado a ressuprimento e não pode ser excluído`; `[BadRequest] - Centro de distribuição está vinculado a inventário e não pode ser excluído`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/warehouse": { "get": { "operationId": "skuWareHouseList", "tags": [ "Armazéns" ], "summary": "Lista armazéns", "description": "Lista armazéns Ativos (`Status = 1`) da empresa, ordenados por `WarehouseName`. Inclui o nome resolvido do tipo (`TypeStockKeepingUnitWarehouse`), CD pai e empresa faturadora (`IDCompanyInvoice`). Respeita restrição de CDs do usuário.", "parameters": [ { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo identificador do centro de distribuição do SKU." } ], "responses": { "200": { "description": "Lista de armazéns.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WarehouseItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuWareHousePost", "tags": [ "Armazéns" ], "summary": "Cria armazém", "description": "Cria um armazém dentro de um CD. Validações:\n- `IDStockKeepingUnitDistributionCenter` precisa pertencer à empresa.\n- `IDCompanyInvoice` (quando informado) precisa ser uma empresa associada à conta autenticada via `CompanyMain`.\n- Quando `Default = 1`, zera o `Default` dos demais armazéns da empresa.\n- Quando `DefaultPurchase = 1`, zera o `DefaultPurchase` dos demais armazéns.\n\nComportamento especial: o POST cria **simultaneamente** o armazém **e** um endereço padrão dentro dele em `StockKeepingUnitLocation` (Address = WarehouseName, Default = 1).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseCreate" } } }, "description": "Dados do depósito a cadastrar. `IDTypeStockKeepingUnitWarehouse` define a natureza (saudável, divergência, quarentena, etc.); `Default=1` define como padrão de venda; `DefaultPurchase=1` define como padrão de compra; `SumQuantity=1` faz o saldo deste depósito entrar no estoque disponível total." }, "responses": { "200": { "description": "Armazém criado (lista completa).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WarehouseItem" } } } } }, "400": { "description": "`[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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/warehouse/{idstockkeepingunitwarehouse}": { "parameters": [ { "name": "idstockkeepingunitwarehouse", "in": "path", "required": true, "schema": { "type": "integer" } } ], "put": { "operationId": "skuWareHousePut", "tags": [ "Armazéns" ], "summary": "Atualiza armazém", "description": "Atualização parcial. Mesmas validações do POST quando trocar CD ou faturador. Quando seta `Default=1` zera os demais armazéns.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseCreate" } } }, "description": "Atualiza o depósito. Mesmo schema do POST." }, "responses": { "200": { "description": "Armazém atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WarehouseItem" } } } } }, "400": { "description": "`[BadRequest] - Armazém não existe`; `[BadRequest] - Centro de distribuição não existe`; `[BadRequest] - Faturador não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuWareHouseDelete", "tags": [ "Armazéns" ], "summary": "Inativa armazém", "description": "**Soft delete** (`Status=0`, `SumQuantity=0`, `Default=0`). Bloqueada quando o armazém tem endereço cadastrado (`StockKeepingUnitLocation`) ou aparece como destino em de/para de armazém (`HubWarehouse`).", "responses": { "200": { "description": "Armazém inativado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WarehouseItem" } } } } }, "400": { "description": "`[BadRequest] - Armazém não existe`; `[BadRequest] - Armazém possui endereço cadastrado e não pode ser excluído`; `[BadRequest] - Armazém tem de/para de armazém e não pode ser excluído`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/location/category": { "get": { "operationId": "skuLocationCategoryList", "tags": [ "Endereços de Estoque" ], "summary": "Lista categorias de endereço", "description": "Lista categorias **Ativas** (`IsActive=1`) da empresa, ordenadas pelo nome.", "parameters": [ { "name": "IDStockKeepingUnitLocationCategory", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador da categoria de localização do SKU." } ], "responses": { "200": { "description": "Lista de categorias.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuLocationCategoryItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuLocationCategoryPost", "tags": [ "Endereços de Estoque" ], "summary": "Cria categoria de endereço", "description": "Cria uma categoria. Nome único por empresa.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuLocationCategoryCreate" } } }, "description": "Dados da categoria de endereço a cadastrar." }, "responses": { "200": { "description": "Categoria criada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuLocationCategoryItem" }, "maxItems": 1 } } } }, "400": { "description": "`[BadRequest] - Categoria já existente`; `[BadRequest] - Empresa não existe`; `[BadRequest] - Erro ao inserir a categoria`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/location/category/{idstockkeepingunitlocationcategory}": { "parameters": [ { "name": "idstockkeepingunitlocationcategory", "in": "path", "required": true, "schema": { "type": "integer" } } ], "put": { "operationId": "skuLocationCategoryPut", "tags": [ "Endereços de Estoque" ], "summary": "Atualiza categoria de endereço", "description": "Atualização parcial. Valida unicidade do nome.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuLocationCategoryCreate" } } }, "description": "Atualiza a categoria de endereço. Mesmo schema do POST." }, "responses": { "200": { "description": "Categoria atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuLocationCategoryItem" }, "maxItems": 1 } } } }, "400": { "description": "`[BadRequest] - Categoria não existe`; `[BadRequest] - Categoria já existente`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuLocationCategoryDelete", "tags": [ "Endereços de Estoque" ], "summary": "Inativa categoria de endereço", "description": "**Soft delete** — `IsActive=0` e prefixa o nome com o id (``) para liberar o nome para reuso. Bloqueada quando há endereço (`StockKeepingUnitLocation`) ou SKU (`StockKeepingUnit`) vinculado à categoria.", "responses": { "200": { "description": "Categoria inativada (string `sucesso`).", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "`[BadRequest] - Categoria não existe`; `[BadRequest] - Categoria esta vinculado a endereço. Editar endereço antes de excluir a categoria`; `[BadRequest] - Categoria esta vinculado a SKU. Editar SKU antes de excluir a categoria`; `[BadRequest] - Erro ao apagar a categoria`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/picking/basket": { "get": { "operationId": "orderFulfillmentPickingBasketList", "tags": [ "Picking" ], "summary": "Lista cestos picking", "description": "Lista cestos Ativos (`PickingListBasketStatus = 1`) com pedido atualmente amarrado (`IDOrder`), CD, dimensões e histórico (`PickingListBasketHistory`).", "parameters": [ { "name": "IDPickingListBasket", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do cesto da lista de separação." }, { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do centro de distribuição do SKU." }, { "name": "ExternalId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo identificador externo (definido pelo cliente da API)." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Número da página da listagem (1-based). Padrão `1`." } ], "responses": { "200": { "description": "Lista de cestos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PickingListBasketItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "orderFulfillmentPickingBasketPost", "tags": [ "Picking" ], "summary": "Cria cesto picking", "description": "Cria um cesto vinculado a um CD. `ExternalId` é único por CD; quando não informado, o sistema usa o próprio `IDPickingListBasket` como ExternalId.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickingListBasketCreate" } } }, "description": "Cadastra um cesto físico de coleta para um CD. `IDStockKeepingUnitDistributionCenter` é obrigatório; `ExternalId` (etiqueta/código de barras impresso no cesto) é opcional — quando ausente o sistema usa o próprio `IDPickingListBasket` como `ExternalId`. Dimensões e peso máximo alimentam a sugestão automática de embalagem." }, "responses": { "200": { "description": "Cesto criado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PickingListBasketItem" }, "maxItems": 1 } } } }, "400": { "description": "`[BadRequest] - Centro de distribuição não existe`; `[BadRequest] - Já existe um cesto para este centro de distribuição com o mesmo código`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/picking/basket/{idpickinglisbasket}": { "parameters": [ { "name": "idpickinglisbasket", "in": "path", "required": true, "schema": { "type": "integer" } } ], "put": { "operationId": "orderFulfillmentPickingBasketPut", "tags": [ "Picking" ], "summary": "Atualiza cesto picking", "description": "O cesto também pode ser vinculado a uma picking-list via IDPickingList (fluxo colméia), além do vínculo por pedido via IDOrder; IDOrder e IDPickingList são mutuamente exclusivos e não podem ser enviados se o cesto já tiver o outro tipo de vínculo. Enviar IDOrder=null desvincula o pedido atualmente amarrado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickingListBasketCreate" } } }, "description": "Atualiza cadastro do cesto. Aceita os mesmos campos do POST. Enviar `IDOrder = null` desvincula o pedido atualmente atrelado ao cesto." }, "responses": { "200": { "description": "Cesto atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PickingListBasketItem" }, "maxItems": 1 } } } }, "400": { "description": "`[BadRequest] - Cesto picking não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "orderFulfillmentPickingBasketDelete", "tags": [ "Picking" ], "summary": "Inativa cesto picking", "description": "**Soft delete** — `PickingListBasketStatus = 0` e libera o `ExternalId` (define como `NULL`) para permitir reuso do mesmo código em um novo cesto.", "responses": { "200": { "description": "Cesto inativado (string `sucesso`).", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "`[BadRequest] - Cesto picking não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/picking/basket/{idpickinglisbasket}/label": { "parameters": [ { "name": "idpickinglisbasket", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "pickingBasketLabelGet", "tags": [ "Picking" ], "summary": "Gera etiqueta ZPL do cesto", "description": "Devolve o ZPL pronto para impressão da etiqueta do cesto (reaproveita o sistema `purchaseLabelGet`).", "responses": { "200": { "description": "Etiqueta ZPL.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/location": { "get": { "operationId": "skuLocationList", "tags": [ "Endereços de Estoque" ], "summary": "Lista endereços do armazém", "description": "Lista endereços (`StockKeepingUnitLocation`) da empresa. **Dois modos de listagem** controlados pelo query param `OnlyLocation`:\n\n- `OnlyLocation=1` (modo padrão da tela): traz **somente** o cadastro do endereço (sem expandir lotes/SKUs). Inclui dimensões, tipo, categoria, grupo, armazém e centro de distribuição. Filtra por `Status` do endereço (quando informado) e respeita restrição de Centros de Distribuição do usuário (`UserCompanyDistributionCenter::`).\n- `OnlyLocation` ausente (modo legado): devolve uma linha por **lote** vinculado ao endereço, com saldo em estoque (`QtyAddress`). Útil para visualizar o que tem em cada endereço. Sempre considera apenas endereços com `Status = 1`.\n\nSuporta filtro `Empty` (`QtyAddress = 0` ou `<> 0`) só no modo legado. Paginação por `Page * 5000`.\n\nQuando a empresa tem parametrização `ShareSkuLocationWithRelatedCompanies = 1` em uma integração tipo `16`, a listagem inclui também os endereços da empresa-mãe (`IDCompanyMain`).", "parameters": [ { "name": "OnlyLocation", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` = só cadastro de endereço; ausente = endereço × lote (com saldo)." }, { "name": "IDStockKeepingUnitLocation", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador da localização do SKU." }, { "name": "IDStockKeepingUnitWarehouse", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do depósito do SKU." }, { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Lista CSV de centros de distribuição. Sistema valida contra a lista permitida ao usuário." }, { "name": "IDStockKeepingUnitLocationGroup", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do grupo de localização do SKU." }, { "name": "IDStockKeepingUnitLocationCategory", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador da categoria de localização do SKU." }, { "name": "IDTypeAddress", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3 ] }, "description": "1=Picking, 2=Pulmão, 3=Blocado." }, { "name": "Address", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca parcial (`LIKE`) pelo nome do endereço." }, { "name": "Floor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo andar do endereço." }, { "name": "Street", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome da rua do endereço (busca parcial)." }, { "name": "Module", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome do módulo do sistema (semântica específica do endpoint)." }, { "name": "Column", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome da coluna usada na operação (semântica específica do endpoint)." }, { "name": "Level", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nível." }, { "name": "IDSku", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtro só no modo legado (com lote)." }, { "name": "IDSkuCompany", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca parcial pelo código de referência do SKU (modo legado)." }, { "name": "SkuName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome do produto (busca parcial)." }, { "name": "BarCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código de barras do produto." }, { "name": "Status", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Aplicado só com `OnlyLocation=1`." }, { "name": "Empty", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Modo legado: `0`=só endereços vazios, `1`=só endereços com saldo." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Número da página da listagem (1-based). Padrão `1`." } ], "responses": { "200": { "description": "Lista (até 5000). Modo `OnlyLocation=1` devolve `SkuLocationListItem`; modo legado devolve `SkuLocationBatchItem`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SkuLocationListItem" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SkuLocationBatchItem" } } ] } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuLocationPost", "tags": [ "Endereços de Estoque" ], "summary": "Cria um ou mais endereços", "description": "Cria endereço(s). O comportamento depende da parametrização da empresa:\n\n**Modo WMS** (`NewAddressParameter = 1`):\n- Campos obrigatórios: `IDStockKeepingUnitWarehouse`, `IDTypeAddress`, `IDStockKeepingUnitLocationCategory`, dimensões (`Height`, `Width`, `Length`, `MaxWeight` — todos `> 0`).\n- Cadastro individual: enviar `Floor`, `Street`, `Module` (numérico), `Column` (alfanumérico), `Level` (numérico). O sistema monta `Address = Floor-Street-Module-Column-Level` (separador padrão `-`, customizável via `Concatenator`: `-`, `.` ou `|`). Falha se já existe esse mesmo conjunto Floor/Street/Module/Column/Level + CD.\n- **Cadastro em massa** (`BulkLocation = 1`): enviar `Floor`, `Street`, `StartModule`/`EndModule`, `StartColumn`/`EndColumn`, `StartLevel`/`EndLevel`. O sistema gera o **produto cartesiano** das faixas (ex.: `StartModule=1`, `EndModule=3`, `StartColumn=A`, `EndColumn=C`, `StartLevel=1`, `EndLevel=2` → 18 endereços). Falha se qualquer endereço gerado já existe no CD.\n- Validações: armazém ativo da empresa, categoria ativa da empresa, grupo da empresa (se informado), tipo de endereço válido. Módulo e nível precisam ser **numéricos**; coluna pode ser alfanumérica (letras viram maiúsculas).\n\n**Modo legado** (`NewAddressParameter = 0`):\n- Campo obrigatório: `Address` (string livre).\n- `IDStockKeepingUnitWarehouse` opcional; quando informado, valida que o armazém pertence à empresa e que não existe outro endereço com mesmo nome no CD. Quando `Default = 1`, zera o `Default` dos demais endereços do armazém antes de inserir.\n\nDevolve o detalhe via list (`OnlyLocation=1`) ou — em cadastro em massa WMS — a string `Endereços cadastrados com sucesso`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuLocationCreate" } } }, "description": "Dados do endereço físico (posição) a cadastrar. O endereço completo é montado a partir de `Floor`, `Street`, `Module`, `Column`, `Level`. `IDTypeAddress` define o uso (Picking, Pulmão, Recebimento)." }, "responses": { "200": { "description": "Endereço criado (array com 1 item no modo individual) ou string de sucesso (modo em massa).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SkuLocationListItem" }, "maxItems": 1 }, { "type": "string", "example": "Endereços cadastrados com sucesso" } ] } } } }, "400": { "description": "Validações WMS: `[BadRequest] - As dimensões do endereço não podem ser negativas ou vazias`; `[BadRequest] - As faixas de módulo, coluna e nível iniciais não podem ser nulas, maiores que as finais e módulo e nível possuir letras`; `[BadRequest] - Preencha corretamente o armazém, tipo e categoria de armazenamento`; `[BadRequest] - Armazém não foi encontrado`; `[BadRequest] - Categoria de armazenamento não encontrada`; `[BadRequest] - Grupo endereço não encontrado`; `[BadRequest] - Tipo de endereço não encontrado`; `[BadRequest] - Preencha todos os campos do endereço (Andar, Rua, Modulo, Coluna e Nivel)`; `[BadRequest] - Preencha módulo e nível com números`; `[BadRequest] - Já existe este endereço para o mesmo centro de distribuição`; `[BadRequest] - Endereços repitidos, consulte seus endereços`; `[BadRequest] - Erro ao gerar endereços em massa`; `[BadRequest] - Erro ao inserir endereços`. Validações legado: `[BadRequest] - Endereço precisa ser informado`; `[BadRequest] - Armazém não localizado`; `[BadRequest] - Já existe este endereço para o centro de distribuição`. Gerais: `[BadRequest] - Empresa não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/location/{idstockkeepingunitlocation}": { "parameters": [ { "name": "idstockkeepingunitlocation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "put": { "operationId": "skuLocationPut", "tags": [ "Endereços de Estoque" ], "summary": "Atualiza um endereço", "description": "Atualização parcial. Quando `NewAddressParameter = 1`, aceita todos os campos WMS (dimensões precisam ser positivas; módulo e nível precisam ser numéricos quando alterados). Quando o endereço já tem **movimento** (`StockKeepingUnitMovement` via lote vinculado), **não pode mudar o armazém** — bloqueio para preservar histórico.\n\nNo modo WMS, se o nome do endereço (`Address`) não vier no body, é recalculado automaticamente como `Floor-Street-Module-Column-Level` usando o separador detectado no `Address` original (`-`, `.` ou `|`).\n\nAo marcar `Default = 1`, zera o `Default` dos demais endereços do mesmo armazém antes de aplicar a alteração.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuLocationUpdate" } } }, "description": "Atualiza o endereço físico." }, "responses": { "200": { "description": "Endereço atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuLocationListItem" }, "maxItems": 1 } } } }, "400": { "description": "`[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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuLocationDelete", "tags": [ "Endereços de Estoque" ], "summary": "Exclui um endereço", "description": "**Exclusão física**. Bloqueada quando existe pelo menos um lote (`StockKeepingUnitBatch`) vinculado ao endereço — neste caso devolve `Endereço possui lote/sku vinculado e não pode ser removido`. Para excluir, primeiro transfira o estoque para outro endereço.\n\nQuando o endereço não tem lote vinculado, remove o registro definitivamente e devolve a string `sucesso`.", "responses": { "200": { "description": "Endereço excluído (string `sucesso`).", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "`[BadRequest] - Endereço não existe`; `[BadRequest] - Endereço possui lote/sku vinculado e não pode ser removido`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/location/{idstockkeepingunitlocation}/label": { "parameters": [ { "name": "idstockkeepingunitlocation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "skuLocationLabelGet", "tags": [ "Endereços de Estoque" ], "summary": "Gera a etiqueta ZPL do endereço", "description": "Devolve o conteúdo ZPL pronto para impressão da etiqueta do endereço. Reaproveita o sistema `purchaseLabelGet` — o conteúdo é definido pelo template de etiqueta de endereço configurado para a empresa.", "responses": { "200": { "description": "Etiqueta ZPL como string.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/workingday": { "get": { "operationId": "userWorkingDayList", "tags": [ "Jornada de Trabalho" ], "summary": "Lista colaboradores", "description": "Lista colaboradores (`UserWorkingDay`) com escala, função atual, funções permitidas, grupos de endereços, categorias de endereço, supervisor e última atividade do usuário (`LastActivityTimestamp`).", "parameters": [ { "name": "IDUserWorkingDay", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do dia de trabalho do usuário." }, { "name": "IDUser", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador do usuário." }, { "name": "IDStockKeepingUnitLocationCategoryList", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Lista CSV de ids; filtra coincidência exata da string CSV." }, { "name": "IDUserJobPositionList", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra colaboradores que tenham essa função no CSV `IDUserJobPositionList` (`FIND_IN_SET`)." }, { "name": "Status", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2 ] }, "description": "Filtra por status. A semântica e os valores aceitos dependem do endpoint — consulte o `description` da operação." }, { "name": "IDWorkScale", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador da escala de trabalho." }, { "name": "IDUserUpper", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra subordinados de um supervisor." } ], "responses": { "200": { "description": "Lista de colaboradores.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserWorkingDayListItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "userWorkingDayPost", "tags": [ "Jornada de Trabalho" ], "summary": "Cadastra um colaborador", "description": "Cria o registro de colaborador para um `IDUser` existente. Valida em cascata: usuário pertence à empresa, escala existe na empresa, cada função informada existe, função atual está dentro da lista de funções, cada categoria/grupo de endereço informado pertence à empresa, supervisor (quando informado) existe.\n\n**Restrição**: cada usuário tem **apenas 1** registro `UserWorkingDay` por empresa — tentativa duplicada devolve `[BadRequest] - Colaborador já existe para esse usuário`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWorkingDayCreate" } } }, "description": "Colaborador a cadastrar. `IDUser`, `IDUserJobPositionList` (CSV de funções) e `IDUserWorkScale` (escala) são obrigatórios. Cada usuário só pode ter um cadastro de colaborador por empresa. Categorias/grupos de endereço e supervisor são opcionais; todos os ids informados são validados contra a empresa autenticada." }, "responses": { "200": { "description": "Colaborador criado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserWorkingDayListItem" }, "maxItems": 1 } } } }, "400": { "description": "Validações: `[BadRequest] - Preencha os campos corretamente`; `[BadRequest] - Usuário não existe, preencha corretamente`; `[BadRequest] - Colaborador já existe para esse usuário`; `[BadRequest] - Função atual não atríbuida ao colaborador`; `[BadRequest] - Função não existente, preencha corretamente`; `[BadRequest] - Categoria de armazenamento não existe`; `[BadRequest] - Escala não existe, preencha corretamente`; `[BadRequest] - Grupo de armazenamento não existe`; `[BadRequest] - Colaborador superior não existe, preencha corretamente`; `[BadRequest] - Empresa não existe`; `[BadRequest] - Erro ao cadastrar colaborador`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/workingday/{idworkingday}": { "parameters": [ { "name": "idworkingday", "in": "path", "required": true, "schema": { "type": "integer" } } ], "put": { "operationId": "userWorkingDayPut", "tags": [ "Jornada de Trabalho" ], "summary": "Atualiza um colaborador", "description": "**Atualização parcial** — só os campos enviados são alterados (passar string vazia em `IDStockKeepingUnitLocationCategoryList`, `IDStockKeepingUnitLocationGroupList` ou `IDUserUpper` limpa o campo para NULL). Valida unicidade da escala/função/grupo dentro da empresa e proíbe colaborador ser próprio supervisor.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWorkingDayUpdate" } } }, "description": "Atualização parcial do colaborador — só os campos enviados são alterados. String vazia em `IDStockKeepingUnitLocationCategoryList`, `IDStockKeepingUnitLocationGroupList` ou `IDUserUpper` limpa o campo. Colaborador não pode ser seu próprio supervisor." }, "responses": { "200": { "description": "Colaborador atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserWorkingDayListItem" }, "maxItems": 1 } } } }, "400": { "description": "Validações do POST + `[BadRequest] - Colaborador não existe`; `[BadRequest] - Colaborador não pode ser seu próprio supervisor`; `[BadRequest] - Preencha corretamente o status`; `[BadRequest] - Categoria armazém não existe ()`; `[BadRequest] - Grupo endereços não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "userWorkingDayDelete", "tags": [ "Jornada de Trabalho" ], "summary": "Exclui um colaborador", "description": "**Exclusão física**. Bloqueada quando o colaborador é supervisor de outro colaborador (verifica `IDUserUpper = ?`).", "responses": { "200": { "description": "Colaborador excluído (string literal `Colaborador excluído com sucesso`).", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "`[BadRequest] - Informe corretamente o colaborador`; `[BadRequest] - Colaborador não existe`; `[BadRequest] - Colaborador é supervisor de outros colaboradores e não pode ser excluído`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/carrier/quotation/error": { "get": { "operationId": "carrierQuotationErrorList", "tags": [ "Cotação de Frete" ], "summary": "Lista erros de simulação de frete", "description": "Lista os erros de simulação de frete da empresa em páginas de até 3000 registros (avance com `Page`), ordenados por `IDCarrierQuotationError` decrescente.", "parameters": [ { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra erros com `RecordTimestamp` ≥ esta data." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra erros com `RecordTimestamp` ≤ esta data 23:59:59." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Índice da página para paginação, começando em `0`. Cada página retorna até 3000 erros; informe `1` para os próximos 3000, e assim por diante. Quando omitido, assume `0` (primeira página)." } ], "responses": { "200": { "description": "Lista dos erros (até 3000).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotationErrorListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/orders/package": { "get": { "operationId": "packageList", "tags": [ "Pedidos" ], "summary": "Lista pacotes (fila do Pré-Romaneio)", "description": "Lista pacotes (`Packages`) com dados do pedido, transportadora, código de rastreio (`ShippingId`), status do pedido (`IDStatusOrder` / `StatusOrder`), status do pacote (`IDStatusPackage` / `StatusPackage`), CD (`DistributionCenterName`), conta (`AccountName`) e romaneio atual (`IDOrdersCarrierCollectionList`). Restrito automaticamente pelos CDs habilitados ao usuário logado. Paginado em blocos de 5000 (`Page` = número; offset = `Page * 5000`).", "parameters": [ { "name": "IDStatusOrder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Status do pedido (CSV — múltiplos valores aceitos). Útil para listar só `6,22` (aguardando expedição/romaneio)." }, { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Número do pedido (`Order`). Aceita CSV ou separado por espaço." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código numérico do pedido (`IDOrder`). Aceita CSV ou separado por espaço." }, { "name": "ShippingId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código de rastreio do pacote." }, { "name": "IDPackage", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador interno do pacote." }, { "name": "IDOrdersCarrierCollectionList", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "description": "Filtra pacotes já amarrados a um romaneio específico." }, { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por CD (validado contra os CDs habilitados ao usuário; valores fora da lista retornam vazio)." }, { "name": "nullCollection", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` filtra apenas pacotes ainda **sem romaneio** (sem `IDOrdersCarrierCollectionList`)." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Página (blocos de 5000)." } ], "responses": { "200": { "description": "Lista de pacotes (até 5000 por página).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PreCollectionPackageListItem" } } } } } } } }, "/fulfillment/packing/collection-list/order": { "post": { "operationId": "orderFulfillmentCarrierCollectionListOrderPost", "tags": [ "Packing" ], "summary": "Amarra pacote (ou pedido) ao romaneio por bipagem", "description": "Recebe o código de rastreio (`ShippingId`) **ou** a chave de acesso da NF-e (44 dígitos) em `Search`, junto com `IDCarrier` (transportadora bipada). Localiza o pacote ou o pedido, valida regras e amarra o item a um romaneio em aberto (status `1`) da combinação transportadora + CD (+ operador, conforme parametrização). Se não houver romaneio aberto compatível, cria um novo registro em `OrdersCarrierCollectionList`.\n\n**Modos** controlados por parâmetros de empresa:\n- `PackagesOnOrdersCarrierCollectionList=1` → modo **por pacote** (cada pacote individual é amarrado). Quando `Search` é uma chave NF-e (44 dígitos), todos os pacotes do pedido vão para o mesmo romaneio. Suporta `AllowMultipleOrdersCarrierCollectionListPerOrder=1` para permitir pacotes do mesmo pedido em romaneios distintos.\n- `PackagesOnOrdersCarrierCollectionList=0` → modo **por pedido** (`IDOrdersCarrierCollectionList` é atualizado e o pedido inteiro é vinculado).\n- `OneCollectionListPerWorker=1` → romaneio aberto separado por operador.\n\n**Efeitos** em qualquer modo:\n- Atualiza `IDOrdersCarrierCollectionList` (ou `IDOrdersCarrierCollectionList`).\n- Atualiza `IDStatusOrder = 6` (Aguardando expedição) quando vinha de `22` (Aguardando romaneio).\n- Grava `OrderEvent` com `IDEvent=27` (`Inserido romaneio: `) no histórico do pedido.\n- Retorna o pedido atualizado, exceto quando `NoInvoke=1` (resposta passa a ser literal `\"Sucesso\"`).", "parameters": [ { "name": "NoInvoke", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` (default no fluxo de bipagem comum) retorna `\"Sucesso\"` sem invocar `OrderGet`. `0` (fluxo do modal de edição) invoca `OrderGet` e retorna o pedido completo." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreCollectionPostPayload" } } }, "description": "Bipa um pacote para amarrar ao romaneio em formação. `Search` aceita o **código de rastreio do pacote** ou a **chave de acesso da NF-e** (44 dígitos — o sistema detecta o formato via regex). `IDCarrier` precisa coincidir com a transportadora do pedido bipado, caso contrário retorna `[BadRequest]`." }, "responses": { "200": { "description": "Sucesso. Quando `NoInvoke=1` retorna o literal `\"Sucesso\"`; caso contrário retorna o pedido vindo do `OrderGet`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "string", "example": "Sucesso" }, { "type": "object", "description": "Resposta do `OrderGet` (pedido completo)." } ] } } } }, "400": { "description": "Mensagens `[BadRequest]` típicas:\n- `Por favor informar o código do pacote`\n- `Por favor informar o código da transportadora`\n- `Pedido não encontrado` / `Pacote não encontrado`\n- `Pedido não possui transportadora`\n- `Transportadora informada divergente do pedido`\n- `Pedido já inserido em romaneio` / `Pacote já inserido em romaneio`\n- `Nota fiscal divergente`\n- `Romaneio divergente, esse pedido já possui pacotes em outros romaneios`\n- `Status do pedido não permite inserir no romaneio, precisa estar aguardando romaneio ou aguardando expedição`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/packing/collection-list": { "get": { "operationId": "orderFulfillmentCarrierCollectionListList", "tags": [ "Packing" ], "summary": "Lista romaneios com filtros", "description": "Lista os romaneios (`OrdersCarrierCollectionList`) da empresa, opcionalmente filtrados por status, transportadora, CD, operador, código do romaneio e intervalo de datas. Limite fixo de 500 registros. Quando o usuário tem restrição de CD e o `IDStockKeepingUnitDistributionCenter` solicitado não está na lista permitida, retorna array vazio.\n\nOs campos `FileName1..FileName5` são retornados como URLs pré-assinadas do S3 (validade de 48 h) ou `null` quando o anexo correspondente não foi enviado.", "parameters": [ { "name": "IDOrdersCarrierCollectionListStatus", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Lista de status separados por vírgula (ex.: `1,2`). Valores possíveis: `1`=Aberto, `2`=Fechado, `3`=Finalizado. Sem este filtro, retorna todos os status." }, { "name": "RecordTimestamp", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial do intervalo (formato `YYYY-MM-DD`). Filtra contra `RecordTimestampEnd` (data de finalização) — não contra a data de criação." }, { "name": "RecordTimestampEnd", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final do intervalo (formato `YYYY-MM-DD`). `23:59:59` é apendado automaticamente para incluir o dia inteiro." }, { "name": "IDOrdersCarrierCollectionList", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro por identificador(es) do romaneio. Aceita vários separados por vírgula (ex.: `33895,398`)." }, { "name": "IDCarrier", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtro por transportadora (`IDSupplier`)." }, { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtro por centro de distribuição. Submetido à ACL do usuário — quando o usuário tem restrição de CDs e o CD solicitado não está na lista, retorna vazio." }, { "name": "RecordUserCreated", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtro por usuário criador (`IDUser`)." } ], "responses": { "200": { "description": "Lista de romaneios (no máximo 500).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionListListItem" } } } } } } }, "post": { "operationId": "orderFulfillmentCarrierCollectionListPost", "tags": [ "Packing" ], "summary": "Cria romaneio vazio para uma transportadora", "description": "Cria um romaneio novo (`OrdersCarrierCollectionList`) em status `1` (Aberto), sem pacotes vinculados. O `IDCarrier` precisa pertencer a um fornecedor (`Suppliers`) da empresa autenticada.\n\nNa prática a maioria dos romaneios é criada **automaticamente** pelo endpoint `POST /fulfillment/packing/collection-list/order` (Pré-Romaneio) ao amarrar o primeiro pacote — este endpoint cobre o caso raro de criação manual antecipada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionListPostPayload" } } }, "description": "Cria um romaneio vazio para uma transportadora. Após criado, pacotes são amarrados via `POST /fulfillment/packing/collection-list/order` (bipagem) e o romaneio segue o fluxo Aberto → Fechado → Finalizado." }, "responses": { "200": { "description": "Sucesso. O sistema executa o `INSERT` mas não invoca callback — a resposta é vazia/`null`." }, "400": { "description": "Mensagens `[BadRequest]` típicas:\n- `Company não existe` — prefixo do token não resolveu para empresa.\n- `Transportadora não existe` — `IDCarrier` não está em `Suppliers` para esta empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/packing/collection-list/{idorderscarriercollectionlist}": { "get": { "operationId": "orderFulfillmentCarrierCollectionListGet", "tags": [ "Packing" ], "summary": "Detalhe do romaneio (com pedidos e pendências)", "description": "Detalhe completo do romaneio. Além dos campos do `List`, inclui `Orders` (todos os pedidos/volumes do romaneio com dados do destinatário, NF, rastreio e peso) e `PedingPackages` (volumes do pedido que estão em **outros** romaneios — usado para avisar sobre split ao fechar).\n\nQuando a parametrização **Exibir dados faturador folha romaneio** (`ShowCompanyInvoiceCarrierCollection=1`) está habilitada, os campos `CompanyNameCorporateName`/`CompanyCpfCnpj`/`CompanyLogoUrl` no cabeçalho do romaneio são substituídos pelos dados do faturador do **primeiro** pedido (quando há múltiplos faturadores).", "parameters": [ { "name": "idorderscarriercollectionlist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do romaneio (`IDOrdersCarrierCollectionList`)." } ], "responses": { "200": { "description": "Detalhe do romaneio em array (com 0 ou 1 elemento).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionListDetail" } } } } } } }, "put": { "operationId": "orderFulfillmentCarrierCollectionListPut", "tags": [ "Packing" ], "summary": "Altera a transportadora do romaneio inteiro", "description": "Substitui a transportadora de **todos os pedidos** do romaneio pela informada em `IDCarrier`. Só permitido enquanto o romaneio **ainda não foi assinado** (`FileName1 IS NULL`).\n\n**Efeitos:**\n- Em cada pedido do romaneio, atualiza `IDCarrier` para a nova transportadora e zera `IntegrationEdiCarrier` (reseta integração EDI da transportadora).\n- Grava `OrderEvent` (`IDEvent=31`, `Header=1`) em cada pedido com comentário `\"Transportadora alterada de: {antiga} para: {nova}\"`.\n- Atualiza o `IDCarrier` do próprio romaneio.\n- Retorna o detalhe atualizado (invoca `Get` internamente).\n\nPara remover apenas alguns pacotes (e não o romaneio inteiro), use `PUT /fulfillment/packing/collection-list/{id}/order`.", "parameters": [ { "name": "idorderscarriercollectionlist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do romaneio (`IDOrdersCarrierCollectionList`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionListPutPayload" } } }, "description": "Troca a transportadora do romaneio. A nova transportadora precisa estar ativa, pertencer à empresa e ser diferente da atual." }, "responses": { "200": { "description": "Detalhe do romaneio com a nova transportadora.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionListDetail" } } } } }, "400": { "description": "Mensagens `[BadRequest]` típicas:\n- `Precisa enviar nova transportadora` — `IDCarrier` ausente.\n- `Romaneio já possui assinatura e não pode ser alterado` — `FileName1` preenchido.\n- `Nova transportadora precisa ser diferente da anterior`.\n- `Romaneio não existe`.\n- `Transportadora não existe` — fornecedor inativo (`SupplierStatus != 1`) ou de outra empresa.\n- `Pacotes para romaneio não localizados` — romaneio sem pedidos/pacotes amarrados.\n- `Erro ao atualizar romaneio`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/packing/collection-list/{idorderscarriercollectionlist}/close": { "post": { "operationId": "orderFulfillmentCarrierCollectionListClosePost", "tags": [ "Packing" ], "summary": "Fecha o romaneio (status 1 → 2)", "description": "Move o romaneio de Aberto (1) para Fechado (2). A partir daí o romaneio aceita conferência por bipagem mas não recebe pacotes novos.\n\nQuando as parametrizações **Considerar pacotes ao inserir no romaneio** (`PackagesOnOrdersCarrierCollectionList=1`) **e** **Permitir pacotes do mesmo pedido em diferentes romaneios** (`AllowMultipleOrdersCarrierCollectionListPerOrder=0`) estão na combinação restritiva, o endpoint valida que **todos os pacotes** dos pedidos do romaneio estão neste romaneio. Se houver pacotes do mesmo pedido em outros lugares, retorna 400 e o frontend mostra a tabela de pendências.\n\nRetorna a **lista** atualizada filtrada por `IDOrdersCarrierCollectionListStatus=1,2` (operação ainda em andamento).", "parameters": [ { "name": "idorderscarriercollectionlist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do romaneio (`IDOrdersCarrierCollectionList`)." } ], "responses": { "200": { "description": "Lista de romaneios Aberto + Fechado (resposta padrão para refresh do listing).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionListListItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]` típicas:\n- `Romaneio não existe`.\n- `Pedidos X,Y,Z possuem pacotes que não estão nesse romaneio` — split detectado no modo restritivo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/packing/collection-list/{idorderscarriercollectionlist}/open": { "post": { "operationId": "orderFulfillmentCarrierCollectionListOpenPost", "tags": [ "Packing" ], "summary": "Reabre o romaneio (status 2 → 1)", "description": "Move o romaneio de Fechado (2) de volta para Aberto (1), permitindo amarração de pacotes novos. **Romaneios Finalizados (3) não podem ser reabertos** — uma vez despachado o romaneio é definitivo (os pedidos já estão como Enviado e os pacotes com data de embarque).", "parameters": [ { "name": "idorderscarriercollectionlist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do romaneio (`IDOrdersCarrierCollectionList`)." } ], "responses": { "200": { "description": "Lista de romaneios Aberto + Fechado atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionListListItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]` típicas:\n- `Romaneio finalizado não pode ser alterado para aberto` — status atual é `3`.\n- `Romaneio não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/packing/collection-list/{idorderscarriercollectionlist}/finish": { "post": { "operationId": "orderFulfillmentCarrierCollectionListFinishPost", "tags": [ "Packing" ], "summary": "Finaliza o romaneio e despacha os pedidos", "description": "Despacha o romaneio. Move o status para `3` (Finalizado), grava `RecordTimestampEnd` com o momento atual e aplica em paralelo:\n\n- **Pedidos com `IDCarrierType IN (30, 32)`** (retirada / canal-marketplace) → `IDStatusOrder = 17` (Retirada) + `OrderEvent` `IDEvent=46`.\n- **Demais pedidos** → `IDStatusOrder = 7` (Enviado) + `OrderEvent` `IDEvent=4`.\n- **Volumes** → `IDStatusPackage = 1` e `ShippingDate` com o momento do despacho.\n- **Movimentos de estoque** → `IDStatusSku = 1`, `QuantityNonconformity = NULL`, `IDTypeFulfillmentNonconformity = NULL`.\n\nRetorna o detalhe atualizado (invoca `Get` internamente).", "parameters": [ { "name": "idorderscarriercollectionlist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do romaneio (`IDOrdersCarrierCollectionList`)." } ], "responses": { "200": { "description": "Detalhe do romaneio finalizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionListDetail" } } } } }, "400": { "description": "Mensagens `[BadRequest]` típicas:\n- `Romaneio não existe`.\n- `Romaneio não existe (pedidos)` — UNION de pedidos/pacotes vazia.\n- `Erro ao finalizar romaneio`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/packing/collection-list/{idorderscarriercollectionlist}/file": { "post": { "operationId": "orderFulfillmentCarrierCollectionListFilePost", "tags": [ "Packing" ], "summary": "Salva assinatura do motorista e PDF final", "description": "Registra a retirada do romaneio pela transportadora: salva os dados do motorista, a imagem da assinatura digital, anexos opcionais e o PDF do romaneio. Bloqueia toda edição posterior do romaneio (alterar transportadora, remover pacote, merge).\n\n**Restrições:**\n- Romaneio precisa estar em status `3` (Finalizado).\n- Romaneio não pode estar já assinado (`FileName1 IS NULL`).\n\n**Efeitos:**\n- Upload no S3 (bucket `OrdersCarrierCollectionListFiles/`): `{id}_Signature.{ext}` (assinatura), `{id}_1_DocumentImage.{ext}` / `{id}_2_DocumentImage.{ext}` / `{id}_3_DocumentImage.{ext}` (anexos), `{id}_Signaturepdf.pdf` (PDF).\n- No romaneio, grava nome/documento/placa/comentário, os paths dos arquivos enviados e `SigningRecordTimestamp` com o momento da assinatura (horário de Brasília).\n- Se **Enviar email automaticamente para transportadora** (`AutoSendEmailToCarrier=1`) estiver habilitado e `CarrierCollectionListEmail` estiver preenchido, dispara e-mail (SES ou SMTP configurado em `CompanyIntegration IDTypeCompanyIntegration=51`) com assunto `\"Romaneio {id} - {empresa}\"` e PDF anexado. CC: lista em `CCEmailsAutoSendEmailToCarrier`.", "parameters": [ { "name": "idorderscarriercollectionlist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do romaneio (`IDOrdersCarrierCollectionList`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionListFilePayload" } } }, "description": "Registra a assinatura do motorista no momento da retirada: documento, nome, placa, comentário e até 5 arquivos (`FileName1`..`FileName5`) enviados como **data URIs base64**. `FileName1` (assinatura) e `FileName5` são obrigatórios. Após gravada a assinatura, o romaneio fica imutável (não permite reabrir, mesclar nem trocar pedidos)." }, "responses": { "200": { "description": "Lista contendo o romaneio recém-assinado (`GET /fulfillment/packing/collection-list?IDOrdersCarrierCollectionList=`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionListListItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]` típicas:\n- `Preencha corretamente o código do Romaneio`.\n- `Preencha corretamente os campos do motorista e assinatura` — algum dos campos obrigatórios (`CarrierDriverDocument`, `CarrierDriverNameCorporateName`, `CarLicensePlate`, `FileName1`, `FileName5`) vazio.\n- `Romaneio não encontrado`.\n- `Romaneio já assinado` — `FileName1` já preenchido.\n- `Status não permite assinar romaneio` — status != 3.\n- `erro ao subir assinatura` / `erro ao subir arquivos` / `erro ao subir pdf do romaneio` — falha no S3.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/packing/collection-list/{idorderscarriercollectionlist}/order": { "put": { "operationId": "orderFulfillmentCarrierCollectionListOrderPut", "tags": [ "Packing" ], "summary": "Remove pacotes do romaneio e reatribui transportadora", "description": "Remove um subconjunto de pacotes do romaneio e atribui uma nova transportadora aos pedidos afetados. Operação típica de correção: pacote foi para o romaneio errado e precisa ir em outra transportadora ou ficar para outro dia.\n\n**Restrições:**\n- Romaneio não pode estar assinado (`FileName1 IS NULL`).\n- Nova transportadora precisa estar ativa e ser diferente da atual.\n- Cada `IDPackage` em `IDPackageArray` precisa pertencer a este romaneio.\n\n**Efeitos:**\n- Nos pacotes informados, define `IDOrdersCarrierCollectionList = NULL` (desvincula do romaneio).\n- Nos pedidos dos pacotes removidos, define `IDStatusOrder = 22` (Aguardando expedição), `IDCarrier` para o novo, `IDOrdersCarrierCollectionList = NULL` e `IntegrationEdiCarrier = NULL`.\n- Grava `OrderEvent` (`IDEvent=31`, `Header=1`) com comentário `\"Transportadora alterada de: {antiga} para: {nova}, removido do romaneio: {id}\"`.\n- Retorna o detalhe do romaneio atualizado (invoca `Get`).\n\nO romaneio em si **não** é alterado — apenas os pedidos/pacotes saem dele. Para trocar a transportadora do romaneio inteiro, use `PUT /fulfillment/packing/collection-list/{id}`.", "parameters": [ { "name": "idorderscarriercollectionlist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do romaneio (`IDOrdersCarrierCollectionList`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionListOrderPutPayload" } } }, "description": "Remove pacotes do romaneio e atribui uma nova transportadora aos pedidos correspondentes. Cada `IDPackage` precisa pertencer a este romaneio; os pedidos voltam para o status **Aguardando expedição** com a `IDCarrier` informada." }, "responses": { "200": { "description": "Detalhe do romaneio sem os pacotes removidos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionListDetail" } } } } }, "400": { "description": "Mensagens `[BadRequest]` típicas:\n- `Precisa enviar nova transportadora`.\n- `Precisa enviar pacotes para alteração de transportadora`.\n- `Romaneio já possui assinatura e não pode ser alterado`.\n- `Nova transportadora precisa ser diferente da anterior`.\n- `Romaneio não existe`.\n- `Transportadora não existe`.\n- `Pacotes para romaneio não localizados`.\n- `Pacotes não localizados para o romaneio` — algum `IDPackage` não pertence a este romaneio.\n- `Erro ao atualizar romaneio`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/packing/order/{idorder}": { "post": { "operationId": "orderFulfillmentPackingIDOrderPost", "tags": [ "Packing" ], "summary": "Finaliza (ou rascunha) o packing de um pedido", "description": "Coração do fluxo de packing. Dois modos:\n\n**Modo Rascunho** (`Draft=1`): apenas grava o `body` como rascunho temporário sob a chave `PickingList:` (TTL 4 dias). Não toca em banco. Retorna `\"sucesso\"`. É chamado **a cada bipagem** pelo frontend para preservar o progresso do operador.\n\n**Modo Final** (sem `Draft`): processa o packing completo:\n\n1. **Conferência**: compara `Items` enviados com `StockKeepingUnitMovement` do pedido. Em caso de divergência, falha com mensagem detalhada (itens não enviados / a maior / a menor). Aceita divergência apenas quando `PartialInvoice=1` (com privilégio + parametrização habilitada).\n2. **Faturamento parcial**: quando há `differenceSentLessQty`, ajusta `StockKeepingUnitMovement` proporcionalmente, recalcula `PriceSellingTotal` e reescala `Value`. Se `AutomaticTransferPartialInvoiceWarehousePacking` configurado, transfere itens removidos para o endereço de Quarentena.\n3. **Validação de série**: para SKUs com `SerialNumber=1`, valida e amarra cada serial via `StockKeepingUnitSerialNumber`.\n4. **Reconciliação de volumes**: cria/apaga linhas em `Packages` para bater com `QuantityPackages`; salva dimensões dos volumes vindas em `Volumes[]`.\n5. **Embalagens**: para cada item em `Packages[]`, insere a linha de embalagem no pedido (com `PriceSelling=0`).\n6. **NF-e**: dispara a emissão da nota fiscal, a menos que `NoInvoke=1`.\n7. **Transição de status**: com transportadora + romaneio habilitado → status `6` + adiciona ao romaneio aberto. Com `SetShippedAfterPacking=1` ou `IDOrderStatusTo`, dispara a mudança de status do pedido (geralmente para `7` Enviado). Caso contrário → status `22` (Aguardando romaneio).\n8. **Picking-list status**: marca como `5` (Concluído) quando todos os pedidos terminaram, ou `4` (Em packing) caso contrário.\n\nAplica debounce de 3s (MD5 do body) para evitar disparo duplicado pelo operador.\n\nRetorna o detalhe atualizado do pedido.\n\nQuando a parametrização Ignorar itens de serviço no faturamento (IgnoreServiceItemsOnInvoice) está habilitada, os itens cujo SKU é do tipo Serviço são desconsiderados da conferência — não precisam ser enviados em Items.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do pedido (`IDOrder`)." }, { "name": "Draft", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` apenas grava o body como rascunho temporário (TTL 4 dias) sem efeitos colaterais. Usado pelo frontend para autosave entre bipagens." }, { "name": "PartialInvoice", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` autoriza faturamento parcial (fecha o packing mesmo com itens conferidos a menos). Só tem efeito quando a parametrização **Permitir faturamento parcial no packing** está habilitada e o body inclui `TempAuthToken` (obtido via `POST /user/{id}/verify` com `PrivilegeAllowPartialInvoice`)." }, { "name": "NoInvoice", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` pula a emissão de NF-e (não invoca o processo). Também ignora o gate de status fiscal no final. Usado em fluxos sem nota." }, { "name": "IDOrderStatusTo", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Status final desejado para o pedido (override). Quando informado, invoca `orderStatusPut` em vez da lógica padrão de romaneio. Tipicamente `7` (Enviado)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackingOrderPostPayload" } } }, "description": "Finaliza (ou salva rascunho com query `?Draft=1`) o packing de um pedido. Cada bipagem na tela vira uma entrada em `Items`; `Volumes` traz peso/dimensões de cada volume. Quando os itens conferidos batem com o esperado da picking-list, o sistema cria os pacotes, dispara a emissão da NF-e e avança o status do pedido." }, "responses": { "200": { "description": "Em modo Rascunho: literal `\"sucesso\"`. Em modo Final: detalhe do pedido (resultado de `OrderGet`).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "string", "example": "sucesso" }, { "type": "object", "description": "Resposta do `OrderGet`." } ] } } } }, "400": { "description": "Mensagens `[BadRequest]` típicas:\n- `Processo de faturamento em dupliciade` — disparo duplicado em menos de 3 s.\n- `Pedido esta no status aberto e não pode seguir o processo de packing`.\n- `Pedido esta com nota fiscal emitida e não pode alterar as quantidades dos itens` — `PartialInvoice` com NF já emitida.\n- ` | | ` — divergência sem `PartialInvoice=1`.\n- `Item X controla serial mas não foi enviado no faturamento`.\n- `Item X controla serial e tem quantidade maior que um. Precisa ser enviado de forma individual o serial`.\n- `Serial informado para o item X não existe` / `não está disponível`.\n- `Erro ao selecionar serial IDSku:X` / `Erro ao alterar quantidade IDSku:X`.\n- `Nota Fiscal não emitida` — gate final quando NF não saiu e o estado não está na lista de declaração de transporte.\nAlém disso, propaga erros do processo de retaguarda de NF-e e do `skuMovementTransferPost`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "404": { "description": "`[NotFound] - Pedido não encontrado`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "orderFulfillmentPackingIDOrderDelete", "tags": [ "Packing" ], "summary": "Cancela o pedido durante o packing", "description": "Cancela o pedido (define `IDStatusOrder = 90`). Apesar do nome do endpoint, não é um \"undo\" do packing — é cancelamento real:\n\n- Libera reserva de estoque: nas movimentações do pedido, zera `BalanceChange` e `IDBatch`.\n- Cancela contas a receber do pedido: define `IDStatusAccountPayableReceivable = 4` (Cancelada) nos lançamentos vinculados.\n- Apaga fisicamente todos os volumes (`Packages`) do pedido.\n- Limpa vínculos: `PickingBasket = NULL`, `IDOrdersCarrierCollectionList = NULL`, `IDPickingList = NULL`.\n- Registra evento `IDEvent=19` (cancelamento) com o motivo em `Comments`.\n- Quando a parametrização **Endereço transferência cancelamento pedido packing** está configurada, dispara `skuMovementTransferPost` para mover cada item de estoque ao endereço de Devolução.\n\nO frontend faz autenticação dupla antes de chamar: primeiro `POST /user/{IDUser}/verify` (com `PrivilegeAllowOrderCancelPacking`) para obter o `TempAuthToken`, depois envia o motivo no body.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do pedido (`IDOrder`)." }, { "name": "Comments", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Motivo do cancelamento (registrado no histórico). Pode também vir no body como `Comments`." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "TempAuthToken": { "type": "string", "description": "Token temporário (obrigatório) obtido via `POST /user/{id}/verify` com `PrivilegeAllowOrderCancelPacking`." }, "Comments": { "type": "string", "description": "Motivo do cancelamento. Mínimo 15 caracteres (validado pelo frontend)." } } } } }, "description": "Sem corpo. Reverte o packing do pedido: apaga os volumes criados, descarta o rascunho do packing salvo e retorna o pedido para o status anterior dentro da picking-list." }, "responses": { "200": { "description": "Sucesso. Retorna o literal `\"sucesso\"`." }, "400": { "description": "Mensagens `[BadRequest]` típicas:\n- `Pedido não encontrado`.\n- `Desvincular nota fiscal antes de alterar status` — `IDStatusInvoice IN (2,3,4,5,7,8)` (Enviada, Emitida, Processando, Pendente Conciliação EPEC, Cancelada, Denegada).\n- `Pedido esta em romaneio X, retirar antes de mudar status`.\n- `Pedido já esta cancelado` — `IDStatusOrder IN (90, 100)`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/packing/picking-list/{idpickinglist}": { "get": { "operationId": "orderFulfillmentPackingListGet", "tags": [ "Packing" ], "summary": "Detalhe da picking-list pronto para packing", "description": "Retorna os pedidos + itens da picking-list, com os SKUs detalhados (código de barras, endereço, peso, série, kit, imagem) para o operador conferir item a item. Cada pedido vem com o `Draft` salvo (último rascunho do packing daquele pedido) para o frontend restaurar o progresso.\n\nFiltra apenas pedidos da empresa corrente e exclui itens cujo SKU é embalagem (`Package = 1`).\n\nQuando a parametrização Ignorar itens de serviço no picking (IgnoreServiceItemsOnPicking) está habilitada, os itens de SKU do tipo Serviço são omitidos da lista de itens a conferir.", "parameters": [ { "name": "idpickinglist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da picking-list (`IDPickingList`)." } ], "responses": { "200": { "description": "Array de pedidos da picking-list (vazio quando nada encontrado).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PackingPickingListOrder" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Precisa enviar o código da picking list` — `idpickinglist` ausente ou literal `\"null\"`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/packing/picking-list/{idpickinglist}/merge": { "post": { "operationId": "orderFulfillmentPickingListMerge", "tags": [ "Packing" ], "summary": "Mescla picking-lists Pendentes (origem → destino)", "description": "Move todos os pedidos da picking-list **origem** (path param) para a **destino** (`IDPickingList` no body) e remove a origem.\n\n⚠️ **Atenção ao URL**: a rota começa com `/fulfillment/packing/` (não `/picking/`) — mantido por compatibilidade histórica. É o mesmo endpoint da tag **Packing** (`orderFulfillmentPickingListMerge`).\n\n**Restrições** (ambas validadas):\n- Origem em status `1` (Pendente).\n- Destino em status `1` (Pendente).\n- Origem e destino na mesma empresa.\n\n**Efeitos**:\n- Reatribui todos os pedidos da origem para o destino (o `IDPickingList` de cada pedido passa a apontar para o destino).\n- Reatribui também os movimentos de estoque desses pedidos ao destino, de modo que os agregados do destino (`QtyOrder`, `ItemsQuantity`, `SkuQuantity`) passem a refletir o conteúdo combinado das duas listas.\n- Remove a picking-list de origem.\n- Não recalcula a prioridade (`PickingListPriority`) do destino.\n\nRetorna o item de lista do destino (mesma estrutura de `GET /fulfillment/picking/picking-list`).", "parameters": [ { "name": "idpickinglist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da picking-list (`IDPickingList`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickingListMergePayload" } } }, "description": "Mescla a picking-list origem (path) em uma picking-list destino (`IDPickingList`). Ambas precisam estar **pendentes** (status 1). Pedidos da origem são reatribuídos ao destino e a origem é apagada." }, "responses": { "200": { "description": "Item de lista da picking-list destino atualizada, com os agregados (`QtyOrder`, `ItemsQuantity`, `SkuQuantity`) já consolidados com os pedidos e movimentos migrados da origem.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PickingListListItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Picking List não existe` — origem.\n- `Status picking list não permite mesclar` — origem fora de status `1`.\n- `Picking list destino não existe`.\n- `Status picking list destino não permite mesclar` — destino fora de status `1`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/picking": { "post": { "operationId": "orderFulfillmentPickingPost", "tags": [ "Picking" ], "summary": "Gera picking-list(s) a partir de pedidos", "description": "Corrigir o rótulo do status 20 no bloco de validação (IDStatusOrder ∈ {1, 4, 20, 93} = Fechado, Finalizado picking, Em separação [não 'Em tratativa interna'], Em Produção) e acrescentar que, para listas colméia (IDTypePickingList=4) com itens em mais de um grupo de endereço, o sistema cria uma lista pai e uma lista filha por grupo de endereço (os movimentos de estoque são atribuídos às filhas).", "parameters": [ { "name": "IDTypePickingList", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "description": "Tipo de picking-list: `1` Picking, `2` Picking & Packing, `3` Monopedido, `4` Colméia." }, { "name": "RecordUserCreatedStartPicking", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Colaborador a ser atribuído como separador." }, { "name": "PickingListPriority", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10 }, "description": "Prioridade fixa. Quando ausente, o sistema aplica a lógica baseada em `PickingListConfiguration`." }, { "name": "IDPickingListConfiguration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Configuração que disparou a geração — usada com `OrderQtyLimit` para reuso de listas pendentes." }, { "name": "OrderQtyLimit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Limite máximo de pedidos por picking-list. Combinado com `IDPickingListConfiguration` + `PickingListPriority` para tentar reusar uma lista pendente do mesmo `LocationGroup`." }, { "name": "bypasssvalidation", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` pula a validação de status do pedido e a unicidade de CD. Use apenas em fluxos automatizados confiáveis." }, { "name": "OnlyValidate", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` retorna `{HasBalance, AvailableResupply}` sem criar a picking-list. Usado pelo frontend para preview." }, { "name": "debug", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` ecoa respostas internas para troubleshooting." }, { "name": "OriginalPickingListPriority", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Prioridade original registrada junto da picking-list; usada também no cálculo de prioridade de ressuprimento." }, { "name": "IgnorePickingPreferenceByAllowResupplyLocation", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "1 ignora a preferência de coletar em endereços que permitem ressuprimento ao alocar o saldo. Quando ausente, herda o valor da configuração de picking aplicável." }, { "name": "PreferLocationMoreQuantity", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "1 prefere o endereço com maior quantidade disponível ao alocar o saldo. Quando ausente, herda o valor da configuração de picking aplicável." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickingPostPayload" } } }, "description": "Array de `IDOrder` a serem agrupados em uma ou mais picking-lists. Pedidos são agrupados pela **combinação de endereços de coleta** (`IDStockKeepingUnitLocationGroup`); cada combinação distinta vira uma picking-list. Apoie-se em querystrings (`OnlyValidate=1`, `IDPickingListConfiguration`, `IDTypePickingList`, etc.) para controlar o comportamento — detalhes na descrição da operação." }, "responses": { "200": { "description": "Sucesso. Sem `OnlyValidate=1`, retorna `{ \"IDPickingList\": <último id>, \"Message\": \"Lista de picking gerada com sucesso\" }` ou, em caso de pedidos sem estoque, `\"Lista de picking gerada incompleta. N pedido(s) sem estoque\"`. Com `OnlyValidate=1`, retorna `{ \"HasBalance\": 0|1, \"AvailableResupply\": 0|1 }`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "IDPickingList": { "type": "integer", "format": "int64", "description": "Identificador da picking-list gerada. `0` quando o disparo foi modo `OnlyValidate=1` (validação) ou quando nenhuma lista foi criada." }, "Message": { "type": "string", "description": "Mensagem descrevendo o resultado da operação." }, "HasBalance": { "type": "integer", "description": "`1` quando há saldo suficiente para gerar a picking-list dos pedidos enviados; `0` quando há falta total ou parcial." }, "AvailableResupply": { "type": "integer", "description": "`1` quando há saldo em pulmão/blocado capaz de cobrir a falta via ressuprimento; `0` quando não há." } } } } } }, "400": { "description": "Mensagens típicas:\n- `Necessário selecionar pedidos para gerar lista picking` — body vazio.\n- `Processo já esta rodando, favor aguardar` — duplicidade detectada.\n- `Tipo picking list não existe`.\n- `Pedido X não localizado`.\n- `Pedido X esta em status que não permite iniciar picking`.\n- `Pedidos selecionados estão em mais de um CD. A lista de separação só pode conter pedidos de um único CD.`\n- `Problema ao gerar picking list` — nenhum lista criada (ex.: todos sem batch alocável).\n- Propaga erros da integração com produção própria quando ela falha.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/picking/picking-list": { "get": { "operationId": "orderFulfillmentPickingListList", "tags": [ "Picking" ], "summary": "Lista picking-lists com filtros", "description": "Lista as picking-lists da empresa (limite fixo de 5 000 por página), ordenadas por PickingListPriority e depois IDPickingList; quando nenhum filtro seletivo é enviado (IDPickingList, IDPickingListStatus, cesto, colaborador ou qualquer intervalo de datas/ShippingEstimateDate), o sistema restringe automaticamente aos últimos 30 dias por RecordTimestamp, e restrições de CD do usuário continuam sendo aplicadas.", "parameters": [ { "name": "IDPickingListStatus", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Lista CSV de status. Ex.: `1,2,6,7`. Valores: `1` Pendente, `2` Iniciado, `3` Coletado, `4` Packing Processando, `5` Packing Concluído, `6` Fim 1ª Conf., `7` Iniciado 2ª Conf." }, { "name": "IDPickingList", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por identificador da picking-list. Aceita CSV." }, { "name": "RecordUserCreatedStartPicking", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo colaborador atribuído." }, { "name": "PickingListBasketExternalId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código externo do cesto (basket) associado." }, { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CDs (CSV). Submetido à ACL de CD do usuário." }, { "name": "RecordTimestampFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial do intervalo de criação." }, { "name": "RecordTimestampTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final do intervalo de criação (apenda `23:59:59`)." }, { "name": "RecordTimestampStartPickingFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Intervalo de início do picking." }, { "name": "RecordTimestampStartPickingTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo de data/hora de início da separação no filtro." }, { "name": "RecordTimestampFinishedPickingFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Intervalo de fim do picking." }, { "name": "RecordTimestampFinishedPickingTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo de data/hora de conclusão da separação no filtro." }, { "name": "RecordTimestampStartPackingFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Intervalo de início do packing." }, { "name": "RecordTimestampStartPackingTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo de data/hora de início da embalagem no filtro." }, { "name": "RecordTimestampEndFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Intervalo de fim do packing." }, { "name": "RecordTimestampEndTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo de data/hora de término no filtro (formato `YYYY-MM-DDTHH:MM:SS`)." }, { "name": "ShippingEstimateDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Intervalo de data prevista de entrega (mín. dos pedidos da lista)." }, { "name": "ShippingEstimateDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo da data de previsão de envio no filtro (formato `YYYY-MM-DD`)." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página da listagem; o deslocamento aplicado é Page × 5000. Ausente = primeira página (deslocamento 0)." } ], "responses": { "200": { "description": "Array de picking-lists (no máximo 5 000).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PickingListListItem" } } } } } } } }, "/fulfillment/picking/picking-list/{idpickinglist}": { "get": { "operationId": "orderFulfillmentPickingListGet", "tags": [ "Picking" ], "summary": "Detalhe da picking-list com rota de coleta otimizada", "description": "Retorna as linhas de coleta da picking-list. Cada linha agrupa `IDSku × IDOrder × IDBatch` (modo padrão) ou `IDSku × Address` (modo agrupado, `?Grouped=1`).\n\n**Ordenação serpentina**: quando todas as linhas têm `Floor`, o sistema aplica uma rota otimizada:\n- `Floor` decrescente (andares superiores primeiro).\n- `Street` ascendente.\n- `Module` ascendente em ruas ímpares; descendente em ruas pares (a menos que `ConsiderEndOfStreetBeginningOfAnother=1`).\n- `LocationSide`: rua ímpar começa pelo lado direito; rua par pelo lado esquerdo.\n- `Column` monotônico com a direção; `Level` ascendente.\nQuando alguma linha não tem `Floor`, cai num sort alfabético natural por `Address`.\n\n**Modo Rascunho** (`?Draft=1`): devolve o rascunho salvo (TTL 4 dias) em vez de consultar o banco. Usado pelo aplicativo WMS para recuperar progresso interrompido.\n\nQuando a parametrização Ignorar itens de serviço no picking (IgnoreServiceItemsOnPicking) está habilitada, as linhas de SKU do tipo Serviço são omitidas da folha de coleta.", "parameters": [ { "name": "idpickinglist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da picking-list (`IDPickingList`)." }, { "name": "Grouped", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` agrupa por `IDSku × Address` (folha consolidada). Sem agrupamento (default), agrupa por `IDSku × IDOrder × IDBatch`." }, { "name": "Draft", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` retorna o rascunho salvo em vez de consultar o banco. Sem efeito quando não há rascunho." } ], "responses": { "200": { "description": "Array de linhas de coleta.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PickingListMovementItem" } } } } } } }, "put": { "operationId": "orderFulfillmentPickingListPut", "tags": [ "Picking" ], "summary": "Atualiza colaborador, tipo, prioridade ou move status (4/6/7)", "description": "Incluir Checked entre os campos aceitos: pelo menos um de RecordUserCreatedStartPicking, IDTypePickingList, PickingListPriority, IDPickingListStatus ou Checked precisa ser informado. Checked marca a conferência da picking-list.", "parameters": [ { "name": "idpickinglist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da picking-list (`IDPickingList`)." }, { "name": "Draft", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` apenas grava o body como rascunho temporário (TTL 4 dias), sem persistir." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickingListPutPayload" } } }, "description": "Atualização parcial da picking-list. Pelo menos um dos campos (`RecordUserCreatedStartPicking`, `IDTypePickingList`, `PickingListPriority`, `IDPickingListStatus`) precisa ser enviado. `IDPickingListStatus` só aceita 4, 6 ou 7 — para iniciar (`1→2`) ou coletar (`2→3`) use os endpoints `/start` e `/finish`. Com `?Draft=1` o body é gravado como rascunho temporário (TTL 4 dias) sem tocar o banco." }, "responses": { "200": { "description": "Sucesso. Sem `Draft`: retorna o item de lista atualizado (single-element array via `orderFulfillmentPickingListList`). Com `Draft`: literal `\"sucesso\"`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/PickingListListItem" } }, { "type": "string", "example": "sucesso" } ] } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Picking-list não existe`.\n- `Status da Picking-list não permite atribuir colaborador` — status atual fora de `{1, 2, 3, 4, 6, 7}`.\n- `Colaborador não existe`.\n- `Colaborador não possui função de separador de pedido`.\n- `Tipo de picking list não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/picking/picking-list/{idpickinglist}/start": { "post": { "operationId": "orderFulfillmentPickingListStart", "tags": [ "Picking" ], "summary": "Inicia a coleta (status 1 → 2)", "description": "Acrescentar que, em listas do tipo colméia (IDTypePickingList=4 com lista pai), os pedidos podem estar em IDStatusOrder 2, 3 ou 4 (não apenas 3 Pré picking-list) para iniciar a coleta.", "parameters": [ { "name": "idpickinglist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da picking-list (`IDPickingList`)." }, { "name": "NoInvoke", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` retorna apenas `\"sucesso\"` sem invocar `orderFulfillmentPickingListGet`. Reduz overhead em fluxos automatizados." } ], "responses": { "200": { "description": "Detalhe da picking-list iniciada (linhas de coleta) ou literal `\"sucesso\"`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/PickingListMovementItem" } }, { "type": "string", "example": "sucesso" } ] } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Picking List não existe`.\n- `Essa lista esta vinculada a outro colaborador` — atribuída a outro usuário.\n- `Você precisa finalizar a lista X antes de iniciar uma nova` — regra de uma lista iniciada por colaborador.\n- `Pedido (s) X, Y, Z com status errado` — algum pedido fora de status `3` (Pré-picking).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/picking/picking-list/{idpickinglist}/finish": { "post": { "operationId": "orderFulfillmentPickingListFinish", "tags": [ "Picking" ], "summary": "Finaliza a coleta (status 2/6/7 → 3)", "description": "Acrescentar que, em listas do tipo colméia (IDTypePickingList=4 com lista pai), o status 3 (Pré picking-list) também é aceito na entrada — conjunto {2, 3, 4, 10, 24} — além do conjunto {2, 4, 10, 24} das listas comuns.", "parameters": [ { "name": "idpickinglist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da picking-list (`IDPickingList`)." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickingListFinishPayload" } } }, "description": "Finaliza a coleta da picking-list. Body é opcional: quando enviado como array, cada entrada informa, para um pedido da lista, os códigos externos (`PickingListBasketExternalIdList`) dos cestos usados — o sistema registra essas vinculações em `PickingListBasket`. Quando vazio ou omitido, só atualiza status e timestamps da picking-list." }, "responses": { "200": { "description": "Detalhe da picking-list finalizada (linhas de coleta atualizadas).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PickingListMovementItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Picking list não localizada`.\n- `Pedido (s) X, Y, Z com status errado` — algum pedido fora de `{2, 4, 10, 24}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/picking/picking-list/{idpickinglist}/order/{idorder}": { "delete": { "operationId": "orderFulfillmentPickingListOrderDelete", "tags": [ "Picking" ], "summary": "Remove pedido da picking-list", "description": "Remove o pedido da picking-list, do cesto e do romaneio simultaneamente. **O `{idpickinglist}` no path é ignorado** — o sistema resolve a picking-list via `IDPickingList`.\n\n**Validação**: `IDStatusOrder ≤ 5` (Aberto, Fechado, Iniciado picking, Pré-picking, Finalizado picking ou Segurar pedido). Status fora desse range falham com mensagem misleading `\"Pedido não esta no status Segurar Pedido\"`.\n\n**Transição automática de status** conforme estado atual + presença de não conformidade no pedido:\n\n| Status atual | Tem NC? | Novo status | `IDEvent` |\n|---|---|---|---|\n| `1` (Fechado) | sim | `10` (Picking NC) | `29` |\n| `2` (Iniciado picking) | sim | `10` (Picking NC) | `29` |\n| `3` (Pré-picking) | sim | `10` (Picking NC) | `29` |\n| `4` (Finalizado picking) | sim | `14` (Packing NC) | `29` |\n| `5` (Segurar pedido) | — | `13` (Tratativa) | `30` |\n| `1–4` | não | `1` (Fechado) | `30` |\n\n**Efeitos colaterais**:\n- No pedido: novo `IDStatusOrder` conforme tabela, `IDPickingList = NULL`, `PickingBasket = NULL`, `IDOrdersCarrierCollectionList = NULL`.\n- Se a picking-list ficar sem pedidos, é removida.\n- Se o romaneio do pedido ficar sem pedidos, é removido.\n- Insere `OrderEvents` com `IDEvent` conforme tabela acima.", "parameters": [ { "name": "idpickinglist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da picking-list (`IDPickingList`)." }, { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do pedido (`IDOrder`)." } ], "responses": { "200": { "description": "Sucesso. Retorna o literal `\"sucesso\"`." }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Pedido não existe`.\n- `Pedido não esta no status Segurar Pedido` — mensagem na verdade significa que `IDStatusOrder > 5`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/fulfillment/picking/picking-list/{idpickinglist}/order/{idorder}/sku/{idskumovement}": { "put": { "operationId": "orderFulfillmentSkuNonconformityPut", "tags": [ "Picking" ], "summary": "Registra inconformidade no item da picking", "description": "Marca um movimento de estoque como em inconformidade (falta, vencido ou avariado). Acionado pelo aplicativo WMS quando o operador, no chão do CD, encontra um problema no item.\n\n⚠️ **`{idpickinglist}` no path é ignorado** — o sistema resolve via `IDSkuMovement`.\n\n**Validação**: `IDStatusOrder` do pedido não pode ser `7` (Expedido) nem `8` (Entregue).\n\n**Sem transferência automática** (`TransferIfPossible != 1` ou sem parâmetro de armazém): apenas marca o movimento com `IDTypeFulfillmentNonconformity` e `QuantityNonconformity`. Insere `OrderEvents` `IDEvent=28`. Sem mudança de status nem de batch.\n\n**Com transferência automática** (`TransferIfPossible=1` + parâmetro `AutomaticTransferNonConformityInPicking{Missing|BestBefore|Damage}Warehouse` setado para o tipo):\n1. Se `QuantityNonconformity < Quantity` do movimento, **divide o movimento em dois** — um com a quantidade ok, outro com a quantidade inconforme; todos os totais fiscais são escalonados proporcionalmente.\n2. Marca o movimento NC com `IDBatch = NULL` e os campos NC.\n3. Transfere a quantidade NC para o armazém configurado.\n4. Tenta realocar batch para o pedido.\n5. Conforme o resultado:\n - Tem saldo em pulmão/blocado ≥ `QuantityNonconformity` → pedido vai para `IDStatusOrder = 10` (Picking NC); movimento marca `IDTypeFulfillmentNonconformity = 6` (Ressuprimento).\n - Não tem saldo lugar nenhum → pedido vai para `IDStatusOrder = 10`; movimento mantém o batch novo se houver.\n - Realocação bem-sucedida → limpa `QuantityNonconformity` e `IDTypeFulfillmentNonconformity` (divergência \"resolvida\").\n\n**Parâmetros consultados**: `AutomaticTransferNonConformityInPickingMissingWarehouse` (tipo 5 Falta), `AutomaticTransferNonConformityInPickingBestBeforeWarehouse` (tipo 2 Vencido), `AutomaticTransferNonConformityInPickingDamageWarehouse` (tipo 1 Avariado).\n\n**Resposta**: por padrão retorna o pedido. Com `?ReturnPickingList=1`, retorna a picking-list.", "parameters": [ { "name": "idpickinglist", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da picking-list (`IDPickingList`)." }, { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do pedido (`IDOrder`)." }, { "name": "idskumovement", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do movimento de estoque (`IDSkuMovement`) que será marcado em inconformidade." }, { "name": "TransferIfPossible", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` habilita a transferência automática do item NC para o armazém parametrizado. Requer parâmetro do tipo correspondente preenchido." }, { "name": "ReturnPickingList", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` retorna o detalhe da picking-list. Sem este flag, retorna o detalhe do pedido (via `OrderGet`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickingNonconformityPayload" } } }, "description": "Aponta inconformidade num movimento de coleta (item faltou, está vencido ou avariado). `IDTypeFulfillmentNonconformity` define a natureza do problema (`1` Avariado, `2` Vencido, `5` Falta, `6` Ressuprimento — atribuído pelo próprio sistema quando há saldo no pulmão). Quando `QuantityNonconformity` é menor que a quantidade total e o cliente envia `TransferIfPossible=1` na query, o movimento é dividido em dois (um ok, um inconforme)." }, "responses": { "200": { "description": "Detalhe do pedido ou da picking-list (conforme `ReturnPickingList`).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "Resposta do `OrderGet`." }, { "type": "array", "items": { "$ref": "#/components/schemas/PickingListMovementItem" } } ] } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Pedido não existe`.\n- `O status atual não permite atualizar` — pedido em status `7` ou `8`.\nAlém disso, propaga erros da transferência de estoque e da realocação de batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/invoice": { "get": { "operationId": "companyInvoiceList", "tags": [ "NF-e / NFC-e" ], "summary": "Lista NFs (NF-e modelos 55/65)", "description": "Lista as NFs (`NfCompany`) emitidas pelas empresas do grupo da conta autenticada (`IDCompany = company`), com pedido (`Orders`), faturador (`Company`), status (`TypeStatusInvoice`), tipo de operação (`NfTpNf`), tipo de emissão (`NfTpEmis`), finalidade (`NfFin`), modelo (`NfModNf`) e processo SEFAZ (`NfProcessCode`) já resolvidos. Paginação fixa em **5000 registros por página** (`Page=N` → offset `N*5000`).\n\n**Modo \"com pedidos pendentes\"** — quando `IDStatusInvoice` contém `0` (Pendente), o resultado inclui também os pedidos que ainda **não têm NF emitida** como entradas adicionais com `IDNfCompany=NULL`, `NfeNumber=NULL`, `NfeSerie=NULL` e `StatusInvoice=\"Pendente\"`. Permite que a tela mostre tanto NFs já emitidas quanto pedidos aguardando emissão.\n\n**Busca rápida `Search`** — casa contra `NfeNumber`, `IDOrder` (apenas valores ≥ `IDOrderThreeMonthsAgo` ), `Order` e `NfeChaveAcesso` (apenas quando a chave tem mais de 40 dígitos).", "parameters": [ { "name": "IDNfCompany", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo id da NF." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo id interno do pedido." }, { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo número do pedido." }, { "name": "NfeNumber", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo número exato da NF." }, { "name": "NfeNumberFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Início da faixa de número de NF (apenas dígitos)." }, { "name": "NfeNumberTo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fim da faixa de número de NF." }, { "name": "NfeSerie", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Série da NF." }, { "name": "IDStatusInvoice", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Status da NF (`IDStatusInvoice`). Aceita CSV. **`0` (Pendente) na lista ativa o modo \"pedidos pendentes\"** descrito na descrição do endpoint." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo faturador (id da empresa)." }, { "name": "CompanyCpfCnpjInvoice", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo CNPJ do faturador (apenas dígitos)." }, { "name": "NfeChaveAcesso", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Chave de acesso da NF (44 dígitos)." }, { "name": "NfetpEmis", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Tipo de emissão (`NfetpEmis` — normal, contingência, etc.)." }, { "name": "FinNFe", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Finalidade da NFe (`FinNFe` — normal, complementar, ajuste, devolução)." }, { "name": "NfTpNf", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Tipo da NF (entrada/saída, `NfTpNf`)." }, { "name": "NfedhEmiFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de emissão da NF." }, { "name": "NfedhEmiTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de emissão da NF (concatenada com ` 23:59:59`)." }, { "name": "ConsumerNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome/razão social do cliente do pedido." }, { "name": "ConsumerCpfCnpj", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo CPF/CNPJ do cliente." }, { "name": "ShippingState", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela UF de destino." }, { "name": "NoOrder", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` filtra apenas NFs sem pedido vinculado (numerações reservadas via `POST /invoice`)." }, { "name": "Search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca rápida — aplica `OR` em `NfeNumber`, `IDOrder`, `Order` e `NfeChaveAcesso` (esta última só quando ≥ 40 dígitos). Limita pedidos a `IDOrder ≥ IDOrderThreeMonthsAgo`." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (offset = `Page * 5000`)." } ], "responses": { "200": { "description": "Lista combinada de NFs e (quando `IDStatusInvoice` inclui `0`) pedidos sem NF.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyInvoiceListItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "companyInvoicePost", "tags": [ "NF-e / NFC-e" ], "summary": "Reserva/registra numeração de NF sem pedido", "description": "Cria um registro `NfCompany` apenas com `IDCompanyInvoice`, `NfeSerie`, `NfeNumber` e `NfeModelo` (sem `IDOrder`). Usado pelo botão **Gerar Numeração NF** da tela — quando a empresa precisa **registrar** um número manualmente (ex.: número emitido fora do sistema que precisa entrar para manter a sequência) ou **reservar** um número futuro. Valida que o `IDCompanyInvoice` pertence ao grupo da empresa (`CompanyMain`) e que a tupla (`IDCompanyInvoice`, `NfeSerie`, `NfeNumber`, `NfeModelo`) ainda não existe.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyInvoiceCreate" } } }, "description": "Dados da numeração de NF a registrar. `IDCompanyInvoice`, `NfeSerie` e `NfeNumber` são obrigatórios; `NfeModelo` default `55` (use `65` para NFCe). A tupla (`IDCompanyInvoice`, `NfeSerie`, `NfeNumber`, `NfeModelo`) precisa ser inédita — não há reaproveitamento de número/série/modelo na mesma empresa emissora." }, "responses": { "200": { "description": "Numeração registrada. Corpo: string `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "`[BadRequest] - Já existe essa NF e Serie para a empresa emissora`; `[BadRequest] - Erro ao adicionar numeração`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/invoice/{idnfcompany}/disable": { "post": { "operationId": "invoiceDisablePost", "tags": [ "NF-e / NFC-e" ], "summary": "Inutiliza NF", "description": "Inutiliza na SEFAZ uma NF que **não chegou a ser emitida** (número \"queimado\" / sequência sem uso), marcando-a como `Inutilizada` no status fiscal. Usado pelo modal **Inutilizar NF** da tela. Body coleta justificativa (mínimo 15 caracteres pela regra da SEFAZ).", "parameters": [ { "name": "idnfcompany", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da NF (`IDNfCompany`) a inutilizar." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Comments": { "type": "string", "minLength": 15, "description": "Justificativa/observação da inutilização da NF." } } } } }, "description": "Justificativa da inutilização. O sistema lê `Comments` (não `Justification`) e o envia como `xJust` ao serviço de inutilização da SEFAZ — a regra da SEFAZ exige texto entre 15 e 255 caracteres." }, "responses": { "200": { "description": "NF inutilizada." }, "400": { "description": "Erros propagados pela SEFAZ ou validação interna do processo de retaguarda. Shape não confirmado." }, "500": { "description": "Erro interno." } } } }, "/invoice-service": { "get": { "operationId": "invoiceServiceList", "tags": [ "NFS-e" ], "summary": "Lista NFS-e (ServiceOrder)", "description": "Lista as NFS-e (`ServiceOrder`) cadastradas pela empresa autenticada, com `StatusInvoice` (de `TypeStatusInvoice`), `CityName`/`State` (de `IBGECityCode`), `ServiceDescription` (de `NfsServiceCode` quando cadastrado para o município), faturador (`IDCompanyInvoice` + `AccountNameInvoice` + `CompanyNameCorporateNameInvoice`), `NfsValue` computado como `NfsServiceQuantity * NfsServiceUnitValue` e `ValuePaid` (soma de `Value` em `AccountsPayableReceivable` vinculadas). Paginação fixa em **1000 registros por página** (`Page=N` → offset `N*1000`).\n\nFiltros são opcionais e combinados com `AND`. Janelas de data usam `BETWEEN` com `' 23:59:59'` apendado ao limite superior.", "parameters": [ { "name": "IDServiceOrder", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Id interno da NFS-e." }, { "name": "IDConsumer", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Id do cliente vinculado (`IDConsumer`)." }, { "name": "ConsumerNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca parcial (`LIKE`) por nome/razão social do cliente." }, { "name": "ConsumerCpfCnpj", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca parcial (`LIKE`) por CPF/CNPJ do cliente. Apenas dígitos." }, { "name": "NfsNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Número da NFS-e (apenas dígitos)." }, { "name": "IDStatusInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo status da NF (`IDStatusInvoice`)." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo faturador (id da empresa)." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de criação (`RecordTimestamp ≥`)." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de criação (com `' 23:59:59'` apendado)." }, { "name": "NfsDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de emissão (`NfsDate`)." }, { "name": "NfsDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de emissão." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (offset = `Page * 1000`)." } ], "responses": { "200": { "description": "Lista de NFS-e.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceInvoiceListItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "invoiceServicePost", "tags": [ "NFS-e" ], "summary": "Cria NFS-e (modal Nova NF de Serviço)", "description": "Cria uma NFS-e em status **Pendente** (`IDStatusInvoice=0`). Pré-condições verificadas pelo sistema: empresa precisa ter `Inscrição Municipal` cadastrada (`CompanyCityInscription`); endereço completo cadastrado (`CompanyAddressIbgeCityCode`); o município emite NFS-e (`NfseIssue = 1`). Quando `IDCompanyInvoice` informado, valida que pertence à empresa principal (`CompanyMain`).\n\nApós criar a NFS-e, **não emite** automaticamente — a emissão é uma ação subsequente (`POST /invoice-service/{idserviceorder}/invoice`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceInvoiceCreate" } } }, "description": "Dados da NFS-e a cadastrar (status nasce **Pendente**, `IDStatusInvoice=0`). `IDConsumer`, `NfsServiceCode`, `NfsServiceQuantity` e `NfsServiceUnitValue` são obrigatórios. `IDCompanyInvoice` (faturador) precisa pertencer ao grupo (`CompanyMain`) da empresa autenticada; quando omitido, usa a própria empresa. As retenções (`NfsIRRFRetentionValue`, `NfsPISRetentionValue`, `NfsCOFINSRetentionValue`, `NfsCSLLRetentionValue`) ficam `null` quando não informadas e os percentuais cadastrados na empresa zeram para o valor total — caso contrário, o sistema calcula automaticamente a partir do percentual configurado, gravando `0` quando o cálculo resulta em valor abaixo de R$ 10,00." }, "responses": { "200": { "description": "NFS-e criada. Devolve o detalhe (formato similar ao GET).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceInvoiceListItem" } } } }, "400": { "description": "`[BadRequest] - Faturador não existe`; `[BadRequest] - Obrigatório preencher a inscrição municipal no cadastro da empresa`; `[BadRequest] - Obrigatório preencher o endereço completo no cadastro da empresa`; `[BadRequest] - Cliente não existe`; `[BadRequest] - Município não emite NFS-e`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/invoice-service/{idserviceorder}": { "delete": { "operationId": "invoiceServiceDelete", "tags": [ "NFS-e" ], "summary": "Exclui NFS-e (ação Deletar da linha)", "description": "Exclui fisicamente uma NFS-e. **Bloqueado** quando o status da NF é diferente de **Pendente** ou **Erro** (`IDStatusInvoice > 1` — Enviada/Emitida/Cancelada não podem ser excluídas) ou quando há contas a receber **Pagas** ou **Parcialmente Pagas** vinculadas (`IDStatusAccountPayableReceivable IN (2,3)`). Quando liberada, remove em cascata `ServiceOrderLog` e `AccountsPayableReceivable` vinculadas, desvincula `ConsumerBankSlip` (`IDServiceOrder = NULL`) e deleta o `ServiceOrder`.", "parameters": [ { "name": "idserviceorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da NFS-e." } ], "responses": { "200": { "description": "NFS-e excluída. Corpo: string `\"Sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "Sucesso" } } } }, "400": { "description": "`[BadRequest] - Status nota fiscal não excluir NFSe`; `[BadRequest] - Nota fiscal já tem pagamento baixado e não pode ser excluido`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "404": { "description": "`[NotFound] - NFSe não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "get": { "operationId": "invoiceServiceGet", "summary": "Detalha uma NFS-e", "description": "Retorna os dados completos de uma NFS-e (cabeçalho fiscal, cliente, endereço, retenções, serviço, status), com o histórico de eventos (`Events`), as contas a receber vinculadas (`Payments`) e URLs assinadas para baixar o XML e a DANFSE em PDF.", "tags": [ "NFS-e" ], "parameters": [ { "name": "idserviceorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da NFS-e." } ], "responses": { "200": { "description": "NFS-e encontrada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceServiceDetail" } } } } } } }, "put": { "operationId": "invoiceServicePut", "summary": "Atualiza uma NFS-e", "description": "Atualiza os dados de uma NFS-e antes da emissão. A operação só é permitida enquanto o status estiver em Pendente ou Erro (`IDStatusInvoice <= 1`). Calcula automaticamente as retenções (IRRF, CSLL, PIS, COFINS) quando o valor da retenção é enviado como `null` e a empresa tem percentual configurado, copia dados do cliente e do endereço escolhidos para a nota, e registra o histórico de alterações. Exige inscrição municipal e endereço completo cadastrados na empresa, e que o município emita NFS-e.", "tags": [ "NFS-e" ], "parameters": [ { "name": "idserviceorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da NFS-e." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceServiceUpdateBody" } } }, "description": "Atualização parcial da NFS-e enquanto o status estiver em **Pendente** ou **Erro** (`IDStatusInvoice ≤ 1`). Apenas os campos enviados são alterados. `IDConsumer` e `IDAddress` aceitam `null` explícito para limpar os dados gravados na nota; quando preenchidos, o cliente/endereço é validado e os dados do cadastro são copiados para a nota. `IDCompanyInvoice` segue a regra de pertencer ao grupo. `NfsNBS` aceita CNPJ formatado (`.` removido automaticamente). `NfsCIndOp` e `NfsCClassTrib`, quando informados, são validados contra `NfsCIndOp` e `NfsCstIbsCbs` (campo `NFSe=1`)." }, "responses": { "200": { "description": "NFS-e atualizada. Retorna o detalhe completo (mesmo schema do `GET`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceServiceDetail" } } } } }, "400": { "description": "Validação falhou. Mensagens reais: `[BadRequest] - Status nota fiscal não permite edição`, `[BadRequest] - Obrigatório preencher a inscrição municipal no cadastro da empresa`, `[BadRequest] - Obrigatório preencher o endereço completo no cadastro da empresa`, `[BadRequest] - Município não possui integração de emissão de NFSe`, `[BadRequest] - Cliente não existe`, `[BadRequest] - Endereço não existe`, `[BadRequest] - Faturador não existe`, `[BadRequest] - Código serviço não existe`, `[BadRequest] - NBS não existe`, `[BadRequest] - Código Indicador de Operação não existe`, `[BadRequest] - Código de Classificação tributária não existe`." }, "404": { "description": "NFS-e não encontrada: `[NotFound] - NFSe não existe`." } } } }, "/invoice-service/{idserviceorder}/invoice": { "post": { "operationId": "invoiceServiceInvoicePost", "tags": [ "NFS-e" ], "summary": "Emite a NFS-e na prefeitura (Mais Ações)", "description": "Dispara a emissão da NFS-e identificada por `idserviceorder`: conecta ao webservice da prefeitura, valida e devolve o número/protocolo da nota emitida. Mensagens de erro (validação local ou rejeição da prefeitura) são prefixadas com `[BadRequest]`.\n\nValida que a NFS-e existe e pertence à empresa autenticada antes de emitir.", "parameters": [ { "name": "idserviceorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da NFS-e a emitir." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "array", "items": {}, "description": "Body ignorado — o sistema envia `[]` ao processo." } } }, "description": "Sem corpo de entrada significativo — o sistema valida que a NFS-e existe e pertence à empresa autenticada e dispara a emissão, conectando ao webservice da prefeitura. Aceita `application/json` vazio." }, "responses": { "200": { "description": "Retorno do processo de retaguarda (geralmente o objeto da NFS-e atualizado com `NfsNumber`, `NfsVerificationCode`, `IDStatusInvoice`).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Resposta da emissão da NF de serviço. O formato varia por provedor municipal." } } } }, "400": { "description": "`[BadRequest] - ` (validação ou rejeição da prefeitura).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "404": { "description": "`[NotFound] - NFSe não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno / falha de comunicação com o processo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "invoiceServiceInvoiceDelete", "summary": "Cancela uma NFS-e emitida", "description": "Solicita o cancelamento de uma NFS-e já emitida junto à prefeitura. Grava o motivo do cancelamento (`NfsCancelDescription`) e consulta o canal fiscal que dispara o evento de cancelamento na prefeitura. Quando `RemovePayment=1`, as contas a receber vinculadas à nota também são removidas.", "tags": [ "NFS-e" ], "parameters": [ { "name": "idserviceorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da NFS-e." }, { "name": "RemovePayment", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "Quando `1`, remove também as contas a receber vinculadas à NFS-e." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "Comments": { "type": "string", "description": "Motivo do cancelamento. Default: `Cancelamento de nota fiscal`." } } } } }, "description": "Opcional. Apenas `Comments` é lido — vira o motivo do cancelamento enviado no evento de cancelamento à prefeitura. Quando ausente, o sistema usa o texto default `\"Cancelamento de nota fiscal\"`." }, "responses": { "200": { "description": "Cancelamento enviado à prefeitura.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Erro retornado pelo processo fiscal ou pela prefeitura. Prefixo `[BadRequest]`." }, "404": { "description": "NFS-e não encontrada: `[NotFound] - NFSe não existe`." } } } }, "/invoice-service/feed": { "get": { "operationId": "invoiceServiceFeedList", "tags": [ "NFS-e" ], "summary": "Lista NFSe recebidas dos fornecedores", "description": "Lista paginada (500/página, offset `Page * 500`) das NFSe que a empresa recebeu de seus fornecedores. As notas são capturadas automaticamente — este endpoint apenas **lê** o feed já populado.\n\n**Multi-tenant**: token com `accountname[0] == \"all\"` dispensa filtro; caso contrário resolve pela `idcompanylist` do contexto.\n\n**Filtro fixo `Show = 1`**: notas soft-hidden não aparecem. Notas com `(CityCode, NfsServiceCode)` sem cadastro no catálogo de códigos de serviço (`NfsServiceCode`) são descartadas silenciosamente.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Página da paginação. `OFFSET = Page * 500`." }, { "name": "IDNfsEvents", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra por identificador da nota." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo faturador (filial)." }, { "name": "NfeNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo número da NFSe. Apenas dígitos. Match exato contra `NfsNumber`." }, { "name": "SupplierNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`LIKE %valor%` contra `NfsSupplierNameCorporateName`." }, { "name": "SupplierCpfCnpj", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo CPF/CNPJ do fornecedor. ⚠️ **Quirk conhecido**: o filtro referencia internamente um campo (`SupplierCpfCnpj`) que não existe na origem dos dados (`NfsEvents` — o correto seria `NfsSupplierCpfCnpj`), então atualmente este parâmetro nunca retorna resultado." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de emissão (`NfsDate ≥ DateFrom`)." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de emissão (`NfsDate ≤ DateTo 23:59:59`)." }, { "name": "Tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra notas que tenham essa tag em `Tag`." } ], "responses": { "200": { "description": "Array de NFSe ordenado por `NfsDate DESC` (máx. 500).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceServiceFeedItem" } } } } } } } }, "/invoice-service/feed/invoice-xml": { "get": { "operationId": "nfseFeedXmlGet", "tags": [ "NFS-e" ], "summary": "Download XML ou DANFSE PDF de uma NFSe do feed", "description": "Baixa o arquivo da NFSe (XML ou PDF).\n\n**Autorização**: a empresa do token precisa coincidir com `AccountName` da nota (cadeia `NfsEvents → CompanyMain → Company`). Notas de outras empresas retornam erro.\n\n**Type=XML**: serve o `.xml` original com `Content-Disposition: attachment`. Conteúdo é desescapado (entities HTML substituídas).\n\n**Type=PDF**: renderiza a DANFSE. ADN tem PDF pré-gerado; outras prefeituras renderizam sob demanda.", "parameters": [ { "name": "File", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da NFSe (`IDNfsEvents`). Apenas dígitos." }, { "name": "Type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "XML", "PDF" ] }, "description": "`XML` baixa o XML original. `PDF` retorna a DANFSE renderizada." }, { "name": "account", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Prefixo da conta. Fallback quando o contexto não resolve." }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Token de autenticação adicional gerado pelo `invoiceServiceFeedList`." } ], "responses": { "200": { "description": "Arquivo binário do XML (`application/xml`) ou PDF (`application/pdf`).", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Erros:\n- `Arquivo não encontrado (1)` — `IDNfsEvents` não pertence à empresa do token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase": { "get": { "operationId": "purchaseList", "tags": [ "Recebimento" ], "summary": "Lista recebimentos com filtros", "description": "Lista paginada (1 000/página) dos recebimentos da empresa. Aplica restrição por CDs vinculados ao usuário e — quando `AllowOnlyUserSupplierCategorySet=1` — restringe por categorias de fornecedor do usuário.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Página da paginação. OFFSET = Page * 1000." }, { "name": "IDStatusPurchase", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo status do recebimento `IDStatusPurchase`. Aceita CSV (ex.: `0,3,4`). Valores: `0` Aberto, `1` Finalizado, `2` Cancelada, `3` Em conferência, `4` Conferência realizada, `5` Aguardando validação comercial, `6` Aguardando validação operacional, `7` Recebimento autorizado, `8` Recebimento recusado, `9` Finalização recebimento autorizada, `10` Aguardando finalização comercial, `11` Finalização recebimento recusada, `12` Aguardando finalização operacional." }, { "name": "IDPurchase", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da compra." }, { "name": "InvoiceNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Número da NF. Aceita CSV." }, { "name": "chNFe", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Chave de acesso da NF-e (44 dígitos)." }, { "name": "SupplierNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome ou razão social do fornecedor (busca parcial)." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de criação (RecordTimestamp)." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo de datas no filtro (formato `YYYY-MM-DD`)." }, { "name": "InvoiceDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de emissão da NF (dhEmi)." }, { "name": "InvoiceDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo da data da nota fiscal no filtro (formato `YYYY-MM-DD`)." }, { "name": "InvoiceFinishTimestampDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data de finalização do recebimento." }, { "name": "InvoiceFinishTimestampDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo da data/hora de conclusão da nota fiscal no filtro." }, { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador do centro de distribuição do SKU." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da nota fiscal da empresa." }, { "name": "Search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca livre por nome do fornecedor, número da NF, chave de acesso ou IDPurchase." }, { "name": "ReturnOrder", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` = só recebimentos de devolução (Reversa); `0` = só de fornecedor." }, { "name": "SkuView", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` = expande os itens (modo card no frontend)." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador do pedido `IDOrder` vinculado ao recebimento." }, { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo número do pedido `Order` vinculado ao recebimento." }, { "name": "ConsumerNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome ou razão social do consumidor do pedido vinculado (busca parcial)." }, { "name": "chNFeFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Em recebimentos de devolução, filtra pela chave de acesso `chNFeFrom` da nota fiscal de origem (a venda que gerou a devolução)." }, { "name": "NfeNumberFrom", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Em recebimentos de devolução, filtra pelo número `NfeNumberFrom` da nota fiscal de origem." }, { "name": "OrderFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo pedido de origem `OrderFrom` associado ao pedido do recebimento." }, { "name": "StockKeepingUnitPurchaseScheduleStatus", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "description": "Filtra pela situação do agendamento de recebimento: `1` Recebido (há check-in e janela definida), `2` Agendado (janela ainda não passou e sem check-in), `3` Atrasado (janela passou sem check-in), `4` Não agendado (sem agendamento amarrado)." }, { "name": "StartTimeFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Início do intervalo do horário de agendamento `StartTime` (formato `YYYY-MM-DD`)." }, { "name": "StartTimeTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo do horário de agendamento `StartTime` (formato `YYYY-MM-DD`; o dia inteiro é considerado)." }, { "name": "SinceRecordTimestamp", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Retorna apenas recebimentos criados a partir desta data/hora `RecordTimestamp` (inclusive). Útil para sincronização incremental." }, { "name": "SinceDateLastRecordModification", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Retorna apenas recebimentos com última modificação `DateLastRecordModification` a partir desta data/hora (inclusive). Útil para sincronização incremental." } ], "responses": { "200": { "description": "Array de recebimentos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseListItem" } } } } } } }, "post": { "operationId": "purchasePost", "tags": [ "Recebimento" ], "summary": "Cria novo recebimento", "description": "Cria um recebimento em status `0` (Aberto). Quando `IDBuyOrder` é informado, vincula o pedido de compra e ajusta seu status para `1` (Recebimento iniciado), além de marcar as contas a pagar do pedido com este `IDPurchase`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasePostPayload" } } }, "description": "Dados do recebimento (compra) a cadastrar. Obrigatório `IDSupplier`. Opcionais: `IDOrder`, `Comments`, `IDBuyOrder` (pedido de compra associado), `IDCompanyInvoice` (faturador — quando diferente da empresa, precisa estar vinculado a ela) e `IDStockKeepingUnitDistributionCenter` (centro de distribuição que recebe a mercadoria)." }, "responses": { "200": { "description": "Detalhe do recebimento criado (resultado de `purchaseGet`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseDetail" } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Empresa não existe`\n- `Fornecedor não existe`\n- `Faturador não existe`\n- `IDOrder não existe`\n- `Pedido de compra não existe`\n- `Centro de distribuição não existe`\n- `Empresa não tem centro de distribuição padrão`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase/{idpurchase}": { "get": { "operationId": "purchaseGet", "tags": [ "Recebimento" ], "summary": "Detalhe do recebimento (com itens e pagamentos)", "description": "Detalhe completo. Sem `?ItemsInvoice=1`, retorna o objeto com `Items`, `Payments` e — quando há pedido de compra vinculado — `ItemsBuyOrder` para conciliação. Com `?ItemsInvoice=1`, retorna apenas os produtos do XML importado (`StockKeepingUnitPurchaseXmlProduct`) com descrições de CST/CFOP já resolvidas.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "ItemsInvoice", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` retorna só os produtos do XML, não o detalhe do recebimento." } ], "responses": { "200": { "description": "Detalhe do recebimento ou itens do XML (conforme `ItemsInvoice`). Retorna `[]` quando não encontra.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseDetail" } } } } } }, "put": { "operationId": "purchasePut", "tags": [ "Recebimento" ], "summary": "Atualiza recebimento (incluindo aprovações)", "description": "Atualiza campos do recebimento. Campos do XML (`dhEmi`/`nNF`/`chNFe`/`natOp`/`NFeType`/`NFeFin`) só editáveis quando o XML não tem protocolo SEFAZ.\n\n**Aprovações** (`PurchaseCheckinApproved` / `PurchaseReceiptApproved`): transitionam status. Exigem privilégio Authorize correspondente.\n\n**Reabertura** (`IDStatusPurchase=0` de recebimento finalizado): só permitida se nenhum produto foi vendido OU `InvoiceFinishTimestamp` foi há menos de 8 dias (`TotalDays < 8`). Reverte movimentos de estoque para status pendente.\n\n**Frete** (`ValueShipping`): valor é rateado proporcionalmente ao `ValueCostTotal` em todos os movimentos do recebimento.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasePutPayload" } } }, "description": "Campos do recebimento a atualizar — apenas os enviados são aplicados. Aceita `IDSupplier`, `IDOrder`, `Comments`, `IDStatusPurchase`, `ValueShipping`, `IDBuyOrder`, `CheckinTimestamp` (não pode ser maior que a data atual), `IDCompanyInvoice`, `PurchaseCheckinApproved`, `PurchaseReceiptApproved`, `IDStockKeepingUnitDistributionCenter` e os dados fiscais da nota (`dhEmi`, `nNF`, `chNFe`, `natOp`, `NFeType`, `NFeFin`)." }, "responses": { "200": { "description": "Detalhe atualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseDetail" } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Recebimento não existe`\n- `Status não existe`\n- `Usuário não tem permissão para aprovar recebimento`\n- `Fornecedor não existe`\n- `Pedido não existe` / `Pedido de compra não existe`\n- `Faturador não existe`\n- `Já existe o mesmo documento para este fornecedor no recebimento: ` (duplicidade de NF)\n- `Já existe a mesma chave de acesso no recebimento: `\n- `Data de Recebimento não pode ser maior que data atual`\n- `Já houve venda de produtos desse recebimento e não pode ser aberto`\n- `Centro de distribuição do item é diferente do CD do recebimento`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "purchaseDelete", "tags": [ "Recebimento" ], "summary": "Cancela o recebimento (status → 2)", "description": "Soft-delete: marca o recebimento como **Cancelada** (status 2). Apaga movimentos de estoque, contas a pagar e XML importado. Só permitido em status `0` (Aberto). Bloqueado se existe conta a pagar com extrato bancário vinculado.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." } ], "responses": { "200": { "description": "Sucesso." }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Recebimento não existe`\n- `Status não permite atualização`\n- `Contas a pagar já foi quitado. Favor remover o pagamento`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase/{idpurchase}/check/start": { "post": { "operationId": "purchaseStartCheckPost", "tags": [ "Recebimento" ], "summary": "Inicia a conferência (status → 3)", "description": "Inicia a conferência do recebimento. Status atual precisa ser `0` (Aberto) ou `7` (Recebimento autorizado). Quando `PurchaseScheduleRequired=1` e não está aprovado, valida o agendamento (existência, data, janela de tolerância) e move o status para `StatusChangePurchase*` caso falhe.\n\nSucesso: status → `3` (Em conferência), `CheckinTimestamp` registrado.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "CheckinTimestamp" ], "properties": { "CheckinTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que a mercadoria chegou no CD." } } } } }, "description": "Início da conferência: `CheckinTimestamp` (obrigatório) é a data/hora em que a mercadoria chegou no CD. Precisa ser ≤ agora; quando o CD exige agendamento (`PurchaseScheduleRequired=1`), é comparada com a janela do agendamento + tolerância." }, "responses": { "200": { "description": "Detalhe atualizado." }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Obrigatório enviar a data de checkin`\n- `Data de Recebimento não pode ser maior que data atual`\n- `Recebimento esta no status X e não pode ser conferido`\n- `Agendamento obrigatório e recebimento não possui agendamento`\n- `Agendamento está para o dia X`\n- `Agendamento esta para ser iniciado X com tolerância de NH`\n- `Agendamento esta para ser finalizado X`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase/{idpurchase}/check": { "get": { "operationId": "purchaseCheckGet", "tags": [ "Recebimento" ], "summary": "Retorna a conferência (comparativa com NF)", "description": "Retorna o que foi conferido vs o que deveria ter (agrupado por SKU), com `Status` 1 (conferido OK) ou 0 (faltando/divergente). Inclui URLs das fotos no S3 público (`Image/Inbound/`).\n\n**`?Draft=1`** retorna o rascunho de conferência salvo em `StockKeepingUnitPurchaseItemsCheckTemp` (usado pelo mobile para retomar).", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "IDStockKeepingUnitPurchaseItemsCheck", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra um item específico." }, { "name": "Draft", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` retorna draft (mobile)." } ], "responses": { "200": { "description": "Array de itens conferidos com status e diff." } } }, "post": { "operationId": "purchaseCheckPost", "tags": [ "Recebimento" ], "summary": "Salva a conferência (draft ou final)", "description": "Salva os itens conferidos. **Controle de idempotência** por MD5 do body com janela de 60s — chamadas duplicadas dentro dessa janela são ignoradas.\n\nQuerystrings:\n- `?Draft=1` salva em `StockKeepingUnitPurchaseItemsCheckTemp` (rascunho).\n- `?Draft=0` (default): apaga o draft e grava em `StockKeepingUnitPurchaseItemsCheck` (definitivo).\n- `?ChangeStatus=1`: ao final, muda status do recebimento para `4` (Conferência realizada).\n- `?NoInvoke=1`: pula o re-invoke de `purchaseCheckGet` (otimização do mobile).", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "Draft", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, restringe à versão de rascunho/draft." }, { "name": "ChangeStatus", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra por mudança de status." }, { "name": "NoInvoke", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, não dispara o efeito colateral assíncrono normalmente associado à chamada." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseCheckItem" } } } }, "description": "Lista de itens conferidos fisicamente — um objeto por linha de SKU + lote. Quando `?Draft=1`, é gravada em rascunho (`StockKeepingUnitPurchaseItemsCheckTemp`); caso contrário, apaga o rascunho e grava como conferência definitiva." }, "responses": { "200": { "description": "Sucesso." }, "400": { "description": "`[BadRequest] - Processo de conferência em dupliciade` (operação já em andamento) / `Recebimento não existe` / `Erro ao conferir recebimento`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase/{idpurchase}/check/{idstockkeepingunitpurchaseitemscheck}": { "put": { "operationId": "purchaseCheckPut", "tags": [ "Recebimento" ], "summary": "Edita um item da conferência", "description": "Atualiza Quantidade, Lote, Validade, Fabricação ou Comentários de uma linha de conferência. Status do recebimento precisa ser `0`, `3` ou `4`.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "idstockkeepingunitpurchaseitemscheck", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do registro de conferência." } ], "requestBody": { "description": "Atualiza um item conferido do recebimento (quantidade, lote e datas).", "content": { "application/json": { "schema": { "type": "object", "properties": { "Quantity": { "type": "number", "format": "double", "description": "Quantidade conferida do item." }, "BestBeforeDate": { "type": "string", "format": "date", "description": "Data de validade do lote (`YYYY-MM-DD`)." }, "ManufacturingDate": { "type": "string", "format": "date", "description": "Data de fabricação do lote (`YYYY-MM-DD`)." }, "BatchComments": { "type": "string", "description": "Observações do lote." }, "Comments": { "type": "string", "description": "Observações da conferência do item." } } } } } }, "responses": { "200": { "description": "Sucesso." }, "400": { "description": "`[BadRequest] - Status do recebimento não permite editar conferência` / `Item conferência não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "purchaseCheckDelete", "tags": [ "Recebimento" ], "summary": "Remove um item da conferência", "description": "Mesmo gate de status (0, 3 ou 4).", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "idstockkeepingunitpurchaseitemscheck", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do registro de conferência." } ], "responses": { "200": { "description": "Sucesso." } } } }, "/purchase/{idpurchase}/check/image": { "post": { "operationId": "purchaseCheckImagePost", "tags": [ "Recebimento" ], "summary": "Upload de foto da etiqueta (com IA opcional)", "description": "Upload multipart de imagem da etiqueta. Salva em S3 `Image/Inbound/.` (jpg/jpeg/png/pdf) e cria registro em `StockKeepingUnitPurchaseItemsCheckFile`.\n\n**`?MainImg=1`**: envia a imagem para o **Google Document AI** (processor configurado por parametrização da empresa). O OCR extrai automaticamente `Batch`, `BestBeforeDate` e `ManufacturingDate` da etiqueta — útil para conferência no celular sem digitação manual.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "MainImg", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` aciona OCR via Google Document AI." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Arquivo de imagem da etiqueta (jpg/jpeg/png/pdf), enviado como multipart." } } } } }, "description": "Upload multipart de imagem da etiqueta/produto. Formatos aceitos: `jpg`, `jpeg`, `png`, `pdf`. Quando enviado com `?MainImg=1`, a imagem passa por OCR (Google Document AI) e o sistema devolve os campos extraídos (`Batch`, `BestBeforeDate`, `ManufacturingDate`)." }, "responses": { "200": { "description": "Sucesso. Retorna `IDStockKeepingUnitPurchaseItemsCheckFile` e, quando `MainImg=1`, `BestBeforeDate`/`Batch`/`ManufacturingDate` extraídos." }, "400": { "description": "`Erro ao subir arquivo`." }, "404": { "description": "`Recebimento não encontrado`." } } } }, "/purchase/{idpurchase}/receipt": { "post": { "operationId": "purchaseReceipt", "tags": [ "Recebimento" ], "summary": "Finaliza o recebimento (entra estoque + side effects)", "description": "Divergências para maior (quantidade acima da prevista ou SKU fora do recebimento) são roteadas ao armazém de divergência do CD; com `CreateNewPurchaseSentMore=1`, o excedente é destacado para um novo recebimento criado automaticamente para o mesmo fornecedor e centro de distribuição, em vez de compor a lista de divergências.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "PartialBuyOrder", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` finaliza apenas o recebimento mantendo o pedido de compra em status Parcial." }, { "name": "CreateReturnOrder", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` cria automaticamente um pedido de devolução para itens conferidos a menor." }, { "name": "CreateNewPurchaseSentMore", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` separa as quantidades recebidas a maior (itens acima do previsto, ou SKUs que não constam do recebimento) e as lança em um novo recebimento criado automaticamente para o mesmo fornecedor e centro de distribuição do recebimento atual; o recebimento atual é finalizado apenas com as quantidades previstas. Sem a flag (ou `0`), o excedente entra no cálculo de divergência normal." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseReceiptPayload" } } }, "description": "Opcional. Lista dos itens efetivamente recebidos — um objeto por SKU + lote. Quando o body é omitido, o sistema monta a lista a partir da conferência salva (`StockKeepingUnitPurchaseItemsCheck`). Divergências para maior vão ao armazém de divergência do CD; divergências para menor reduzem ou apagam os movimentos previstos (e, se `?CreateReturnOrder=1`, geram pedido de devolução)." }, "responses": { "200": { "description": "Detalhe do recebimento finalizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseDetail" } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Centro de distribuição não possui armazém de divergência cadastrado`\n- `Nenhum SKU pode ter quantidade menor ou igual a zero, verifique antes de finalizar`\n- `` com itens não enviados / a menor / a maior / não existe no recebimento\n- `Armazém (IDStockKeepingUnitWarehouse) X não encontrado`\n- `Endereço SKU X não encontrado`\n- `Lote (IDBatchNumber) X não encontrado para o sku: Y`\n- `Datas de fabricação e validade precisam ser preenchidas para o SKU: X`\n- `Preencha a data de validade, obrigatória para o SKU X`\n- `Preencha o lote, obrigatório para o SKU X`\n- `SKU X vence em N dias e mínimo dias necessários são M dias` (com `MinimumDaysBestBeforePurchase`)\n- `Data de fabricação maior que data de validade para o SKU X`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "404": { "description": "`[NotFound] - Recebimento não encontrado`." } } } }, "/purchase/{idpurchase}/sku": { "post": { "operationId": "purchaseSkuPost", "tags": [ "Recebimento" ], "summary": "Adiciona item ao recebimento", "description": "Adiciona um movimento de entrada (`StockKeepingUnitMovement IDTypeMovement=0`). Recebimento precisa estar em status `0` (Aberto). Valida obrigatoriedade de lote/validade/fabricação conforme flags do SKU (`RastroControl`, `BestBeforeRequired`, `BatchRequired`). Quando o SKU tem `Batch=1` e o endereço já tem lote/validade divergente, bloqueia (a menos que `AllowSameItemDifferentBatchSameLocation=1`).", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "BypassValidation", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` pula validações de obrigatoriedade de rastreabilidade." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSkuPostPayload" } } }, "description": "Dados do item a adicionar ao recebimento (SKU, armazém, quantidade, custo, lote, validade, CFOP). O recebimento precisa estar em status `0` (Aberto). Quando o SKU exige rastreabilidade, lote, fabricação e validade são obrigatórios. `?BypassValidation=1` pula essas validações." }, "responses": { "200": { "description": "Detalhe atualizado." }, "400": { "description": "Várias mensagens (`Quantidade > 0`, `Data fab > validade`, `Status não permite`, `Sku não existe`, `Armazém não existe`, `Lote SKU não existe`, `Endereço SKU não existe`, `CFOP X não existe`, `Item possui lotes divergentes`, etc.)." } } } }, "/purchase/{idpurchase}/sku/{idskumovement}": { "put": { "operationId": "purchaseSkuPut", "tags": [ "Recebimento" ], "summary": "Edita item do recebimento", "description": "Atualiza quantidade, custo, lote, validade, armazém ou endereço do item. Recebimento precisa estar em status `0`. **Exceção**: quando o recebimento já está finalizado e a alteração é apenas em `ValueCostTotal`, o sistema permite e registra log explícito — útil para corrigir custo sem reverter estoque.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "idskumovement", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do movimento de estoque (`IDSkuMovement`) do item no recebimento." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseSkuPostPayload" } } }, "description": "Campos editáveis do item do recebimento (mesmo schema do `POST`). Atualização parcial. Recebimento precisa estar em status `0` (Aberto), exceto quando a alteração é apenas em `ValueCostTotal` — nesse caso, o sistema permite ajuste mesmo com recebimento finalizado e registra log explícito." }, "responses": { "200": { "description": "Sucesso." } } }, "delete": { "operationId": "purchaseSkuDelete", "tags": [ "Recebimento" ], "summary": "Remove item do recebimento", "description": "Recebimento em status `0`. Também apaga o lote (`StockKeepingUnitBatch`) se ele não tem mais movimentos vinculados.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "idskumovement", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do movimento de estoque (`IDSkuMovement`) do item no recebimento." } ], "responses": { "200": { "description": "Sucesso." } } } }, "/purchase/{idpurchase}/payment": { "post": { "operationId": "purchasePaymentPost", "tags": [ "Recebimento" ], "summary": "Adiciona pagamento (com retenções)", "description": "Cria um título a pagar (`AccountsPayableReceivable IDTypeAccount=1`) vinculado ao recebimento. Quando `Taxes` é informado, cria também um título por retenção com `IDAccountPayableReceivableFather` apontando para o título principal — útil para PIS/COFINS/IR/CSLL retidos.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasePaymentPostPayload" } } }, "description": "Dados do título a pagar a lançar no recebimento. `Taxes[]` (opcional) gera um título a pagar separado por retenção fiscal, vinculado ao título principal via `IDAccountPayableReceivableFather` (útil para PIS/COFINS/IR/CSLL retidos)." }, "responses": { "200": { "description": "Detalhe atualizado." }, "400": { "description": "`Recebimento não existe` / `Fornecedor não existe` / `Type Payment não existe` / `Tipo documento não existe` / `Plano de contas não existe` / `Conta bancária não existe` / `Fornecedor retenção é obrigatório` / `Valor retenção é obrigatório` / `Data vencimento retenção é obrigatória` / `Fornecedores(s) retenção imposto não localizado(s): X`." } } } }, "/purchase/{idpurchase}/payment/{idaccountpayablereceivable}": { "put": { "operationId": "purchasePaymentPut", "tags": [ "Recebimento" ], "summary": "Edita pagamento", "description": "Edita campos do título a pagar. ⚠️ **Quirk**: o sistema sobrescreve `DateDocument` e `DocumentNumber` com os valores do XML do recebimento (quando há XML) — campos passados no body podem ser ignorados.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "idaccountpayablereceivable", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do título a pagar (`IDAccountPayableReceivable`)." } ], "requestBody": { "description": "Atualização parcial dos dados de pagamento de uma parcela do recebimento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "IDAccountPayableReceivable": { "type": "integer", "description": "Conta a pagar a atualizar. Quando omitido, usa o id do path." }, "Comments": { "type": "string", "description": "Observações do pagamento." }, "DateCompetence": { "type": "string", "format": "date", "description": "Data de competência (`YYYY-MM-DD`)." }, "DateDocument": { "type": "string", "format": "date", "description": "Data do documento (`YYYY-MM-DD`)." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento (`YYYY-MM-DD`)." }, "DocumentNumber": { "type": "string", "description": "Número do documento." }, "IDTypePayment": { "type": "integer", "description": "Tipo de pagamento." }, "IDTypeDocument": { "type": "integer", "description": "Tipo de documento." }, "IDTypeAccountPayble": { "type": "integer", "description": "Plano de contas (categoria) da conta a pagar." }, "Value": { "type": "number", "format": "double", "description": "Valor da parcela em R$." }, "BankSlipBarCode": { "type": "string", "description": "Linha digitável / código de barras do boleto." }, "IDBankAccountForecast": { "type": "integer", "description": "Conta bancária de previsão." }, "ValueDiscount": { "type": "number", "format": "double", "description": "Valor de desconto em R$." }, "ValueInterest": { "type": "number", "format": "double", "description": "Valor de juros em R$." }, "ValuePenalty": { "type": "number", "format": "double", "description": "Valor de multa em R$." } } } } } }, "responses": { "200": { "description": "Sucesso." } } }, "delete": { "operationId": "purchasePaymentDelete", "tags": [ "Recebimento" ], "summary": "Remove pagamento", "description": "Recebimento precisa estar em status `0`.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "idaccountpayablereceivable", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do título a pagar (`IDAccountPayableReceivable`)." } ], "responses": { "200": { "description": "Sucesso." } } } }, "/purchase/{idpurchase}/invoice": { "post": { "operationId": "purchaseInvoicePost", "tags": [ "Recebimento" ], "summary": "Processa XML da NF-e no recebimento", "description": "Recebe XML cru de NF-e (`` + ``) e gera o recebimento de compra completo: cabeçalho e itens do XML, movimentos de estoque, batches, alocações e o contas a pagar (~50 validações).\n\n**Matching de SKU**: `ImportType` define a ordem (`1`=código fornecedor, `2`=código de barras, `3`=código de referência, `5`=código integração). Sem `ImportType`, tenta em sequência. Quando `PurchaseCreateSkuIfNotExists=1`, cria SKU automaticamente para produtos não encontrados.\n\n**Cálculo de custo**: `vProd + vICMSST + vFCPST + vIPI - vDesc + vFrete + vOutro` menos os impostos configurados para subtrair (`PurchaseSubtractPis/Cofins/Icms`). CFOPs em `CFOPCostZero` zeram o custo.\n\n**Controle de concorrência**: registro em `LogScript` chave `PurchaseInvoicePost__` TTL 900 s — `Processo já esta rodando, aguardar!`.\n\n**Devolução** (NF com `tpNF=0 + refNFe`): usa custo da NF original (proporcional).", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "IDStockKeepingUnitWarehouse", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador do depósito do SKU." }, { "name": "ImportType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Critério de matching (CSV)." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Para matching por código do canal de venda." } ], "requestBody": { "required": true, "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } }, "description": "XML cru da NF-e a importar (`` + ``). O sistema processa: matching de SKU, cálculo de impostos e custo, criação de lotes, contas a pagar e movimentos de estoque." }, "responses": { "200": { "description": "XML processado." }, "400": { "description": "Mensagens de erro:\n- `XML não é válido` / `XML não esta assinado` / `O arquivo não é um XML de Nota Fiscal válido`\n- `Recebimento não encontrado` / `O status atual não permite inserir XML`\n- `Tipo documento padrão não cadastrado` / `Plano de contas padrão para compras não cadastrado`\n- `XML já importado` / `Recebimento já tem XML importado`\n- `Armazém informado não cadastrado` / `Armazém informado não pertence ao centro de distribuição`\n- `Processo já esta rodando, aguardar!` (operação já em andamento)\n- `SKU(s) não cadastrados: produto código:X EAN:Y` (sem `PurchaseCreateSkuIfNotExists`)\n- `SKU(s) sem alíquota de entrada de PIS/COFINS cadastrada` (com `RequirePisCofinsInboundAliquot=1`)\n- `Certificado digital não encontrado` / `Erro validação SEFAZ: X` (com `ValidadeInboundInvoice=1`)\n- `Erro salvar Xml`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/purchase/{idpurchase}/label": { "get": { "operationId": "purchaseLabelGet", "tags": [ "Recebimento" ], "summary": "Gera etiqueta do recebimento (ZPL ou PDF)", "description": "Gera etiquetas dos itens via Labelary API (PDF) ou retorna ZPL puro. Modelo da etiqueta vem de `IDCompanyLabel`.", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." }, { "name": "IDCompanyLabel", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da etiqueta da empresa." }, { "name": "Download", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` baixa o arquivo `.zpl`." }, { "name": "Zpl", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` retorna o ZPL bruto." }, { "name": "IDSkuMovement", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra 1 movimento." }, { "name": "IDCompanySalesPolicy", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pela política de venda da empresa." } ], "responses": { "200": { "description": "PDF ou ZPL conforme parâmetros.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string", "description": "ZPL." } } } }, "400": { "description": "`Parâmetros inválidos, obrigatório informar account e IDCompanyLabel` / `Recebimento não encontrado` / `Problema ao gerar etiqueta`." } } } }, "/purchase/{idpurchase}/log": { "get": { "operationId": "purchaseLogGet", "tags": [ "Recebimento" ], "summary": "Histórico de alterações do recebimento", "description": "Retorna o log auditoria (`StockKeepingUnitPurchaseLog`) ordenado decrescente — quem fez, quando, o que mudou (diff).", "parameters": [ { "name": "idpurchase", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recebimento (`IDPurchase`)." } ], "responses": { "200": { "description": "Array de eventos." } } } }, "/hub/sales-policy": { "get": { "operationId": "hubSalesPolicyList", "tags": [ "Hub — Política Comercial" ], "summary": "Lista mapeamentos DE-PARA", "description": "Lista todos os mapeamentos da empresa autenticada. Sem paginação. Ordenação por `IntegrationName, CompanyIntegrationName`.", "parameters": [ { "name": "IDSalesPolicyTo", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra por política comercial interna." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra por canal de venda." } ], "responses": { "200": { "description": "Array de mapeamentos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubSalesPolicyItem" } } } } } } }, "post": { "operationId": "hubSalesPolicyPost", "tags": [ "Hub — Política Comercial" ], "summary": "Cria mapeamento DE-PARA", "description": "Cria um novo mapeamento. **Sem checagem de unicidade** — duplicatas com mesma combinação podem coexistir. Validações:\n\n- Integração precisa existir e pertencer à empresa autenticada.\n- Política comercial interna precisa existir e pertencer à empresa.\n- Tipo de pedido (se informado) precisa existir e pertencer à empresa.\n- Vtex (`IDTypeCompanyIntegration = 23`): `IDSalesPolicyFrom` obrigatório.\n- Mercado Livre (`IDTypeCompanyIntegration = 10`): `ShippingFree` é aceito e armazenado.\n- Outras integrações: `ShippingFree` é **forçado a `null`** pelo servidor (mesmo se enviado no body).\n\nResposta: a lista completa atualizada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubSalesPolicyPayload" } } }, "description": "Mapeamento de política comercial a cadastrar. `IDCompanyIntegration` e `IDSalesPolicyTo` são obrigatórios. `IDSalesPolicyFrom` é obrigatório quando a integração é Vtex (`IDTypeCompanyIntegration = 23`). `ShippingFree` só é considerado para Mercado Livre (`IDTypeCompanyIntegration = 10`) — em outras integrações é forçado a `null`." }, "responses": { "200": { "description": "Lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubSalesPolicyItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Integração não cadastrada`\n- `Campo política integração é obrigatório para integração Vtex`\n- `Politica comercial não cadastrada`\n- `Tipo pedido não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/sales-policy/{idhubsalespolicy}": { "put": { "operationId": "hubSalesPolicyPut", "tags": [ "Hub — Política Comercial" ], "summary": "Edita mapeamento DE-PARA", "description": "Edita um mapeamento existente. Mesmas validações do Post:\n\n- Registro precisa existir e pertencer à empresa (referência em `CompanyIntegration`).\n- Regras de obrigatoriedade por integração (Vtex exige `IDSalesPolicyFrom`).\n- `ShippingFree` forçado a `null` quando não-Meli.\n- Quando `ShippingFree` não vem no body, mantém o valor anterior.\n\nResposta: lista completa atualizada (`hubSalesPolicyList` re-invocado).", "parameters": [ { "name": "idhubsalespolicy", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do mapeamento (`IDHubSalesPolicy`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubSalesPolicyPayload" } } }, "description": "Mesma estrutura do POST. Mantém as mesmas regras por integração; campos não enviados preservam o valor atual." }, "responses": { "200": { "description": "Lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubSalesPolicyItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]` (Post +):\n- `Hub Politica Comercial não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubSalesPolicyDelete", "tags": [ "Hub — Política Comercial" ], "summary": "Remove mapeamento DE-PARA", "description": "Apaga o mapeamento. Sem restrições — qualquer mapeamento pode ser removido a qualquer momento. As validações reversas vivem em outras telas (`OrderTypeOrderDelete`, `companySalesPolicyDelete`).", "parameters": [ { "name": "idhubsalespolicy", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do mapeamento (`IDHubSalesPolicy`)." } ], "responses": { "200": { "description": "Lista atualizada após remoção.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubSalesPolicyItem" } } } } }, "400": { "description": "`[BadRequest] - Hub Politica Comercial não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/payment": { "get": { "operationId": "hubPaymentList", "tags": [ "Hub — Pagamento" ], "summary": "Lista mapeamentos — Hub Pagamento", "description": "Lista os mapeamentos da empresa autenticada. Sem paginação.", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da integração da empresa." } ], "responses": { "200": { "description": "Array de mapeamentos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentHubItem" } } } } } } }, "post": { "operationId": "hubPaymentPost", "tags": [ "Hub — Pagamento" ], "summary": "Cria mapeamento — Hub Pagamento", "description": "Cria um novo mapeamento. Retorna a lista completa atualizada (re-invoca o List).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentHubPayload" } } }, "description": "Mapeamento de forma de pagamento a cadastrar. `IDCompanyIntegration` e `IDPaymentTo` são obrigatórios. `IDPaymentFrom` é o código da forma de pagamento usado pelo canal." }, "responses": { "200": { "description": "Lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentHubItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `De/para pagamento já existe`\n- `Pagamento não cadastrado`\n- `Integração não cadastrada`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/payment/{idhubpayment}": { "put": { "operationId": "hubPaymentPut", "tags": [ "Hub — Pagamento" ], "summary": "Edita mapeamento — Hub Pagamento", "description": "Edita o mapeamento. Retorna a lista atualizada.", "parameters": [ { "name": "idhubpayment", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da forma de pagamento no hub." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentHubPayload" } } }, "description": "Mesma estrutura do POST. Em integrações cujo tipo NÃO é `23`, `24`, `34`, `45` ou `53`, quando `IDPaymentFrom` é enviado vazio o sistema o preenche automaticamente com o `IDSalesChannel` da integração." }, "responses": { "200": { "description": "Lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentHubItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `De/para pagamento já existe`\n- `Pagamento não cadastrada`\n- `Integração não cadastrada`\n- `Pagamento Hub não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubPaymentDelete", "tags": [ "Hub — Pagamento" ], "summary": "Remove mapeamento — Hub Pagamento", "description": "Apaga o mapeamento.", "parameters": [ { "name": "idhubpayment", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da forma de pagamento no hub." } ], "responses": { "200": { "description": "Lista atualizada após remoção.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentHubItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Pagamento Hub não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/brand": { "get": { "operationId": "hubBrandList", "tags": [ "Hub — Marcas" ], "summary": "Lista mapeamentos — Hub Marcas", "description": "Lista os mapeamentos da empresa autenticada. Sem paginação.", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da integração da empresa." } ], "responses": { "200": { "description": "Array de mapeamentos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrandHubItem" } } } } } } }, "post": { "operationId": "hubBrandPost", "tags": [ "Hub — Marcas" ], "summary": "Cria mapeamento — Hub Marcas", "description": "Cria um novo mapeamento. Retorna a lista completa atualizada (re-invoca o List).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandHubPayload" } } }, "description": "Mapeamento de marca a cadastrar. `IDCompanyIntegration` e `IDBrandTo` são obrigatórios; `IDBrandFrom` é o código da marca no canal (texto livre)." }, "responses": { "200": { "description": "Lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrandHubItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Marca não cadastrada`\n- `Integração não cadastrada`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/brand/{idhubbrand}": { "put": { "operationId": "hubBrandPut", "tags": [ "Hub — Marcas" ], "summary": "Edita mapeamento — Hub Marcas", "description": "Edita o mapeamento. Retorna a lista atualizada.", "parameters": [ { "name": "idhubbrand", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da marca no hub." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandHubPayload" } } }, "description": "Mesma estrutura do POST. Campos não enviados preservam o valor atual." }, "responses": { "200": { "description": "Lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrandHubItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Marca não cadastrada`\n- `Integração não cadastrada`\n- `De/Para marca não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubBrandDelete", "tags": [ "Hub — Marcas" ], "summary": "Remove mapeamento — Hub Marcas", "description": "Apaga o mapeamento.", "parameters": [ { "name": "idhubbrand", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da marca no hub." } ], "responses": { "200": { "description": "Lista atualizada após remoção.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrandHubItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `IDHubBrand não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/brand/{idhubbrand}/update": { "post": { "operationId": "hubBrandUpdatePost", "tags": [ "Hub — Marcas" ], "summary": "Reprocessa mapeamento (sincroniza com o canal)", "description": "Reconsulta os dados do mapeamento direto no canal em segundo plano externo. Depende de `TypeSalesChannelResource` com `ResourceType=Brand` cadastrado para o tipo da integração — caso contrário falha com a mensagem de recurso indisponível.", "parameters": [ { "name": "idhubbrand", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da marca no hub." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da integração da empresa." } ], "responses": { "200": { "description": "Reprocessamento disparado." }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Integracão não tem recurso`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/category": { "get": { "operationId": "hubCategoryList", "tags": [ "Hub — Categorias" ], "summary": "Lista mapeamentos — Hub Categorias", "description": "Lista os mapeamentos da empresa autenticada. Sem paginação.", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da integração da empresa." } ], "responses": { "200": { "description": "Array de mapeamentos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryHubItem" } } } } } } }, "post": { "operationId": "hubCategoryPost", "tags": [ "Hub — Categorias" ], "summary": "Cria mapeamento — Hub Categorias", "description": "Cria um novo mapeamento. Retorna a lista completa atualizada (re-invoca o List).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryHubPayload" } } }, "description": "Mapeamento de categoria a cadastrar. `IDCompanyIntegration` e `IDCategoryTo` são obrigatórios; `IDCategoryFrom` é o código da categoria no canal e `CategoryFromTree` carrega a árvore completa (`Eletrônicos > TV > Smart TV`) para facilitar a navegação na tela." }, "responses": { "200": { "description": "Lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryHubItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Categoria não cadastrada`\n- `Integração não cadastrada`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/category/{idhubcategory}": { "put": { "operationId": "hubCategoryPut", "tags": [ "Hub — Categorias" ], "summary": "Edita mapeamento — Hub Categorias", "description": "Edita o mapeamento. Retorna a lista atualizada.", "parameters": [ { "name": "idhubcategory", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da categoria no hub." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryHubPayload" } } }, "description": "Mesma estrutura do POST. Campos não enviados preservam o valor atual." }, "responses": { "200": { "description": "Lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryHubItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Categoria não cadastrada`\n- `Integração não cadastrada`\n- `Categoria hub não existe`\n- `Já existe de/para de categoria para mesma categoria e integração`\n- `Erro ao inserir de/para de categoria`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubCategoryDelete", "tags": [ "Hub — Categorias" ], "summary": "Remove mapeamento — Hub Categorias", "description": "Apaga o mapeamento.", "parameters": [ { "name": "idhubcategory", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da categoria no hub." } ], "responses": { "200": { "description": "Lista atualizada após remoção.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryHubItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `IDHubCategory não existe`\n- `Existe de/para de variação para essa categoria e a mesma não pode ser excluida`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/category/{idhubcategory}/update": { "post": { "operationId": "hubCategoryUpdatePost", "tags": [ "Hub — Categorias" ], "summary": "Reprocessa mapeamento (sincroniza com o canal)", "description": "Reconsulta os dados do mapeamento direto no canal em segundo plano externo. Depende de `TypeSalesChannelResource` com `ResourceType=Category` cadastrado para o tipo da integração — caso contrário falha com a mensagem de recurso indisponível.", "parameters": [ { "name": "idhubcategory", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da categoria no hub." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da integração da empresa." } ], "responses": { "200": { "description": "Reprocessamento disparado." }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Integracão não tem recurso`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/warehouse": { "get": { "operationId": "hubWarehouseList", "tags": [ "Hub — Estoque" ], "summary": "Lista mapeamentos — Hub Estoque", "description": "Lista os mapeamentos da empresa autenticada. Sem paginação.", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da integração da empresa." } ], "responses": { "200": { "description": "Array de mapeamentos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WarehouseHubItem" } } } } } } }, "post": { "operationId": "hubWarehousePost", "tags": [ "Hub — Estoque" ], "summary": "Cria mapeamento — Hub Estoque", "description": "Cria um novo mapeamento. Retorna a lista completa atualizada (re-invoca o List).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseHubPayload" } } }, "description": "Mapeamento de armazém a cadastrar. `IDCompanyIntegration`, `IDStockKeepingUnitWarehouseFrom`, `IDStockKeepingUnitWarehouseTo` e `IDOrderType` são obrigatórios. `IDStatusOrder` é opcional e só aceita status com `ChangeOnCreate = 1`." }, "responses": { "200": { "description": "Lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WarehouseHubItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `DE/PARA de armazém já existe`\n- `Tipo Pedido não cadastrado`\n- `Armazem não cadastrada`\n- `Integração não cadastrada`\n- `Status pedido não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/warehouse/{idhubwarehouse}": { "put": { "operationId": "hubWarehousePut", "tags": [ "Hub — Estoque" ], "summary": "Edita mapeamento — Hub Estoque", "description": "Edita o mapeamento. Retorna a lista atualizada.", "parameters": [ { "name": "idhubwarehouse", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do depósito no hub." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarehouseHubPayload" } } }, "description": "Mesma estrutura do POST. Campos não enviados preservam o valor atual." }, "responses": { "200": { "description": "Lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WarehouseHubItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Tipo Pedido não cadastrado`\n- `Armazém não cadastrada`\n- `Integração não cadastrada`\n- `De/para armazém não cadastrado`\n- `Status pedido não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubWarehouseDelete", "tags": [ "Hub — Estoque" ], "summary": "Remove mapeamento — Hub Estoque", "description": "Apaga o mapeamento. A lista da integração é atualizada.", "parameters": [ { "name": "idhubwarehouse", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do depósito no hub." } ], "responses": { "200": { "description": "Lista atualizada após remoção.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WarehouseHubItem" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `IDHubWarehouse não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/question-answer-template": { "get": { "operationId": "hubQuestionAnswerTemplateList", "tags": [ "Hub — Anúncios" ], "summary": "Lista templates de mensagem", "description": "Lista os templates de mensagem da empresa. Filtros via querystring por `AnswerType` (`1` Resposta pré-cadastrada, `2` Mensagem automática).", "parameters": [ { "name": "AnswerType", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2 ] }, "description": "Filtra pelo tipo de resposta." } ], "responses": { "200": { "description": "Array de templates.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubMessageItem" } } } } } } }, "post": { "operationId": "hubQuestionAnswerTemplatePost", "tags": [ "Hub — Anúncios" ], "summary": "Cria template de mensagem", "description": "Cria um novo template. `Title` é obrigatório quando `AnswerType=2` (Mensagem automática). Texto pode conter variáveis dinâmicas `{{Variável}}` substituídas no momento do uso.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubMessagePayload" } } }, "description": "Modelo de mensagem a cadastrar. `AnswerType` define se é resposta pré-cadastrada (`1`) ou mensagem automática (`2`); `Answer` é o texto e aceita variáveis dinâmicas como `{{Nickname}}`. `Title` é obrigatório para `AnswerType=2`." }, "responses": { "200": { "description": "Template criado." } } } }, "/hub/product/question-answer-template/{idhubproductquestionanswertemplate}": { "put": { "operationId": "hubQuestionAnswerTemplatePut", "tags": [ "Hub — Anúncios" ], "summary": "Edita template de mensagem", "parameters": [ { "name": "idhubproductquestionanswertemplate", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do modelo de pergunta/resposta de produto no hub." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubMessagePayload" } } }, "description": "Mesma estrutura do POST. Campos não enviados preservam o valor atual." }, "responses": { "200": { "description": "Sucesso." } }, "description": "Edita um template de mensagem usado para responder perguntas de compradores no canal de venda. Devolve o template atualizado." }, "delete": { "operationId": "hubQuestionAnswerTemplateDelete", "tags": [ "Hub — Anúncios" ], "summary": "Remove template de mensagem", "parameters": [ { "name": "idhubproductquestionanswertemplate", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do modelo de pergunta/resposta de produto no hub." } ], "responses": { "200": { "description": "Sucesso." } }, "description": "Remove um template de mensagem de perguntas/respostas do canal de venda." } }, "/hub/product/question-answer": { "get": { "operationId": "hubQuestionAnswerList", "tags": [ "Hub — Anúncios" ], "summary": "Lista perguntas dos compradores", "description": "Lista as perguntas feitas pelos compradores nos anúncios. Filtros opcionais: `IDTypeHubProductQuestionAnswerStatus` (`1` Não Respondida, `2` Respondida), `Nickname` (histórico do comprador), `IDHubProduct` (anúncio específico).", "parameters": [ { "name": "IDTypeHubProductQuestionAnswerStatus", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2 ] }, "description": "Filtra pelo status da pergunta/resposta de produto no hub." }, { "name": "Nickname", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo apelido." }, { "name": "IDHubProduct", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador do produto no hub." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da integração da empresa." } ], "responses": { "200": { "description": "Array de perguntas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubQuestionAnswerItem" } } } } } } } }, "/hub/product/question-answer/{idhubproductquestionanswer}": { "put": { "operationId": "hubQuestionAnswerPut", "tags": [ "Hub — Anúncios" ], "summary": "Responde uma pergunta", "description": "Envia a resposta para o canal e marca a pergunta como Respondida (status `2`). Limite de **2000 caracteres** imposto pelo canal.", "parameters": [ { "name": "idhubproductquestionanswer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da pergunta/resposta de produto no hub." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Answer" ], "properties": { "Answer": { "type": "string", "maxLength": 2000, "description": "Texto da resposta à pergunta do comprador no canal de venda." } } } } }, "description": "Texto da resposta a ser enviada ao comprador no canal. Único campo aceito é `Answer` (até 2000 caracteres). O envio sincroniza a resposta no canal e marca a pergunta como Respondida." }, "responses": { "200": { "description": "Resposta enviada." } } }, "delete": { "operationId": "hubQuestionAnswerDelete", "tags": [ "Hub — Anúncios" ], "summary": "Remove uma pergunta", "description": "Permitido apenas em perguntas **Não Respondidas** (`IDTypeHubProductQuestionAnswerStatus=1`).", "parameters": [ { "name": "idhubproductquestionanswer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da pergunta/resposta de produto no hub." } ], "responses": { "200": { "description": "Sucesso." } } } }, "/hub/order/claim": { "get": { "operationId": "hubOrderClaimList", "tags": [ "Hub — Pedidos" ], "summary": "Lista reclamações abertas pelos compradores", "description": "Lista as reclamações sincronizadas dos canais. Cada linha tem estágio, tipo e motivo (vindos do canal — listas auxiliares em `/type/hub/order/claim/{reason,stage,type,resolution-reason}`).", "responses": { "200": { "description": "Array de reclamações." } } } }, "/hub/order/claim/{idhuborderclaim}": { "get": { "operationId": "hubOrderClaimGet", "tags": [ "Hub — Pedidos" ], "summary": "Detalhe da reclamação (chat + ações disponíveis)", "description": "Detalhe completo: mensagens trocadas, anexos, dados do pedido, comprador, e — crucialmente — `AvailableActions` que o canal indica para o estágio atual (`refund`, `open_dispute`, `allow_return`, `return_review_ok`, `return_review_fail`, `send_potential_shipping`, `allow_partial_refund`, `send_message_to_complainant`, `send_message_to_mediator`, etc.). Quando `ClaimStatus=1` (Fechado), nenhuma ação é mais possível.", "parameters": [ { "name": "idhuborderclaim", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da reclamação de pedido no hub." } ], "responses": { "200": { "description": "Detalhe da reclamação." } } } }, "/hub/order/claim/{idhuborderclaim}/action": { "post": { "operationId": "hubOrderClaimAction", "tags": [ "Hub — Pedidos" ], "summary": "Executa uma ação na reclamação", "description": "Dispara uma das `AvailableActions` (ver acima). Body varia por tipo de ação:\n- `refund` / `open_dispute` / `allow_return` / `return_review_ok` — sem body adicional.\n- `send_potential_shipping` — `{DateShipping}`.\n- `allow_partial_refund` — `{Percentage}` ou `{Amount}`.\n- `return_review_fail` — `{Reason, Message, FileUUIDs}` (anexo obrigatório para motivos SRF2/SRF4).\n- `send_message_to_complainant` / `send_message_to_mediator` — `{Message}`.\n- `send_only_attachments` / `send_attachments` — `{Message, FileUUIDs}`.", "parameters": [ { "name": "idhuborderclaim", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da reclamação de pedido no hub." }, { "name": "Type", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Tipo da ação (ver `AvailableActions[].Type` retornado por `GET /hub/order/claim/{id}`)." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Corpo varia conforme a ação (`Type` na query). Estruturas observadas: ações sem body (`refund`, `open_dispute`, `allow_return`, `return_review_ok`); `{DateShipping}` para `send_potential_shipping`; `{Percentage}` ou `{Amount}` para `allow_partial_refund`; `{Reason, Message, FileUUIDs}` para `return_review_fail` (anexo obrigatório para motivos SRF2/SRF4); `{Message}` para `send_message_to_complainant` e `send_message_to_mediator`; `{Message, FileUUIDs}` para `send_only_attachments` e `send_attachments`. Os `FileUUIDs` vêm das chamadas anteriores ao endpoint de upload." }, "responses": { "200": { "description": "Ação executada — `GET claim` é re-invocado e novo estado retornado." } } } }, "/hub/order/claim/{idhuborderclaim}/action/file": { "post": { "operationId": "hubOrderClaimActionFile", "tags": [ "Hub — Pedidos" ], "summary": "Faz upload de arquivo para anexar a uma ação", "description": "Sobe um arquivo (foto, PDF, vídeo curto) e devolve um `FileUUID` para usar em uma ação subsequente (`return_review_fail`, `send_attachments`, etc.). Quando o motivo da recusa é SRF2/SRF4 (return_review_fail), o anexo é obrigatório — sistema aceita query `?Return=1`.", "parameters": [ { "name": "idhuborderclaim", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da reclamação de pedido no hub." }, { "name": "Return", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, restringe a registros de devolução." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Arquivo anexado à ação da reclamação (imagem ou documento), enviado como multipart." } } } } }, "description": "Upload multipart de um arquivo (foto, PDF ou vídeo curto). Resposta inclui o `FileUUID` que deve ser referenciado posteriormente no corpo da ação correspondente." }, "responses": { "200": { "description": "Retorna `FileUUID` para o anexo." } } } }, "/orders/hub": { "get": { "operationId": "orderHubList", "tags": [ "Pedidos" ], "summary": "Lista o staging de pedidos integrados", "description": "Lista o staging de pedidos integrados dos canais de venda, com os filtros de canal/cliente/UTM/data, busca textual `Search`, modo `OrdersNotCreated=1` (so registros que ainda nao geraram pedido) e paginacao em blocos de 1000 (`Page` -> deslocamento `Page * 1000`).", "responses": { "200": { "description": "Array de linhas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubOrderItem" } } } } } }, "parameters": [ { "name": "ConsumerNameCorporateName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo primeiro nome do cliente (busca parcial)." }, { "name": "ConsumerCpfCnpj", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo documento do cliente (CPF/CNPJ, busca parcial)." }, { "name": "ConsumerEmail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo e-mail do cliente (busca parcial)." }, { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo numero do pedido ja criado (`Order`)." }, { "name": "OrderFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo identificador do pedido na origem (`OrderId` do canal)." }, { "name": "IDStatusOrder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo status do pedido no canal de venda (`Status`)." }, { "name": "IDSalesChannel", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo canal de venda." }, { "name": "ShippingId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo codigo de rastreio/etiqueta do envio." }, { "name": "PackId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo identificador de agrupamento de pacotes do canal." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de registro do staging (`RecordTimestamp >=`)." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de registro (concatenada com ` 23:59:59`)." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pela integracao de origem do pedido." }, { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo tipo de integracao/canal." }, { "name": "IDIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo identificador interno do registro de staging." }, { "name": "Coupon", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo cupom aplicado no pedido." }, { "name": "UtmCampaign", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela campanha de origem (UTM)." }, { "name": "UtmMedium", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo meio de origem (UTM)." }, { "name": "UtmSource", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela fonte de origem (UTM)." }, { "name": "UtmiCampaign", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela campanha interna (UTMi)." }, { "name": "UtmiPage", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela pagina interna (UTMi)." }, { "name": "UtmiPart", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela parte/secao interna (UTMi)." }, { "name": "OrdersNotCreated", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, lista apenas registros do staging que ainda nao geraram pedido (`IDOrder` vazio), cujo status do canal nao esta cancelado e que estao marcados para criar pedido." }, { "name": "Search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca textual generica. Casa contra `PackId`, identificador interno `IDIntegration`, codigo de rastreio `ShippingId`, identificador do pedido na origem `OrderId`, codigo interno `IDOrder`, numero do pedido `Order`, primeiro nome do cliente `ConsumerFirstName`, nome do recebedor `ShippingReceiverName`, documento `ConsumerDocument` e e-mail `ConsumerEmail`. Espacos viram curinga interno." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Pagina; o deslocamento e `Page * 1000` (blocos de 1000 registros)." }, { "name": "CreationTimestampFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de criacao do pedido no canal de origem (CreationTimestamp >=). Diferente de DateFrom, que filtra a data de registro do staging." }, { "name": "CreationTimestampTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de criacao do pedido no canal de origem (concatenada com 23:59:59)." } ] }, "post": { "operationId": "orderHubPost", "tags": [ "Pedidos" ], "summary": "Cria pedido manualmente (puxa do canal pelo código origem)", "description": "Quando o canal não enviou o pedido automaticamente, este endpoint faz um **pull explícito** usando o código origem informado. Útil para 'puxar' pedidos pontuais. `ShippingId` é obrigatório apenas para Mercado Livre OnSite (`IDTypeCompanyIntegration=1`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubOrderPostPayload" } } }, "description": "Solicita ao canal de venda a importação imediata de um pedido específico (atalho para evitar esperar o coletor agendado). `IDCompanyIntegration` define a integração e `OrderFrom` é o código do pedido no canal." }, "responses": { "200": { "description": "Linha criada (e pedido idworks também, se a integração está configurada para criação automática)." } } } }, "/hub/order/{idintegration}": { "get": { "operationId": "orderHubGet", "tags": [ "Hub — Pedidos" ], "summary": "Detalhe de uma linha de staging", "description": "Detalhe completo com todos os campos do canal + status idworks (quando há pedido criado).", "parameters": [ { "name": "idintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador único da linha de staging." } ], "responses": { "200": { "description": "Detalhe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubOrderItem" } } } } } }, "delete": { "operationId": "orderHubDelete", "tags": [ "Hub — Pedidos" ], "summary": "Remove uma linha de staging", "description": "Permitido apenas quando `IDOrder` está vazio (linha ainda não virou pedido idworks). Linhas com `IDOrder` preenchido devem ser canceladas pela tela de Pedidos (que reverte estoque, contas a receber, etc.).", "parameters": [ { "name": "idintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador único da linha de staging." } ], "responses": { "200": { "description": "Removido." } } } }, "/hub/order/create/{idintegration}": { "post": { "operationId": "orderHubCreatePost", "tags": [ "Hub — Pedidos" ], "summary": "Cria pedido idworks a partir de linha de staging", "description": "serviço de integração que transforma a linha de staging em pedido efetivo no idworks: cria cliente, endereço, itens (SKUs vinculados), pagamentos (tipo via Hub Pagamento), frete (transportadora via Hub Carriers), aplica armazém + tipo de pedido (via Hub Estoque) e UTM tracking. Após sucesso, o campo `IDOrder` da linha fica preenchido.", "parameters": [ { "name": "idintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador único da linha de staging." } ], "responses": { "200": { "description": "Pedido idworks criado." } } } }, "/hub/order/update/{idintegration}": { "post": { "operationId": "orderHubUpdatePost", "tags": [ "Hub — Pedidos" ], "summary": "Reprocessar — re-pull do canal", "description": "Faz pull novamente do canal usando o código origem e atualiza a linha de staging com os dados frescos. Não recria o pedido idworks (se já existir, mantém).", "parameters": [ { "name": "idintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador único da linha de staging." } ], "responses": { "200": { "description": "Reprocessamento disparado." } } }, "put": { "operationId": "orderHubUpdatePut", "tags": [ "Hub — Pedidos" ], "summary": "Atualiza SKU vinculado a item da linha", "description": "Edita o vínculo SKU local ↔ produto do canal em um item da linha de staging. Usado pela expansão da linha quando um item está sem SKU mapeado.", "parameters": [ { "name": "idintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador único da linha de staging." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "IDSku": { "type": "integer", "format": "int64", "description": "Identificador do SKU no idworks a vincular ao produto do canal." }, "IDIntegrationProducts": { "type": "integer", "format": "int64", "description": "Identificador do produto na integração (canal de venda)." } } } } }, "description": "Vincula um SKU local a um item específico da linha de staging que veio sem mapeamento. `IDIntegrationProducts` identifica o item dentro do pedido integrado (`IDIntegrationProducts`) e `IDSku` é o SKU interno a ser associado (não pode ser kit, tipo `4`)." }, "responses": { "200": { "description": "Atualizado." } } } }, "/hub/order/status/{idorder}": { "get": { "operationId": "orderHubStatusGet", "tags": [ "Hub — Pedidos" ], "summary": "Consulta status atualizado do pedido no canal", "description": "Força consulta de status no canal para um pedido idworks específico — útil para sincronizar estado quando o pull periódico não atualizou.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Status do canal." } } } }, "/hub/order/invoice/{idorder}": { "post": { "operationId": "orderHubInvoicePost", "tags": [ "Hub — Pedidos" ], "summary": "Envia NF do pedido para o canal", "description": "Quando o pedido idworks foi faturado, este endpoint envia o XML da NF para o canal (alguns canais exigem para que o pedido siga para o status Enviado).", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "NF enviada." } } } }, "/hub/order/{idintegration}/action": { "post": { "operationId": "orderHubMessagePost", "tags": [ "Hub — Pedidos" ], "summary": "Envia mensagem ao comprador pelo canal", "description": "Dispara uma mensagem ao comprador no canal. Type indica o tipo de mensagem (`send_message`, etc.). Privilégio `PrivilegeHubOrderMessageSend`.", "parameters": [ { "name": "idintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador único da linha de staging." }, { "name": "Type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por tipo. A semântica depende do endpoint." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Mensagem ao comprador. Corpo padrão `{Message}`; o `Type` na query indica o tipo de envio (`send_message` por padrão). O conteúdo aceito depende do canal — o sistema proxia o corpo para o processo do canal." }, "responses": { "200": { "description": "Mensagem enviada." } } } }, "/hub/order/{idintegration}/action/file": { "post": { "operationId": "orderHubMessageAttachmentPost", "tags": [ "Hub — Pedidos" ], "summary": "Anexo de arquivo em mensagem do pedido", "description": "Faz upload de arquivo para anexar a uma mensagem do pedido.", "parameters": [ { "name": "idintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador único da linha de staging." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Arquivo anexado à ação do pedido no canal (imagem ou documento), enviado como multipart." } } } } }, "description": "Upload multipart de arquivo para anexar a uma mensagem do pedido. Aceita query `Return=1` quando o anexo se refere a uma devolução." }, "responses": { "200": { "description": "Arquivo anexado." } } } }, "/hub/product/size-chart": { "get": { "operationId": "hubProductSizeChartList", "tags": [ "Hub — Anúncios" ], "summary": "Lista grades — Hub Grade de Tamanho", "description": "Lista as grades de tamanho cadastradas. Retorna apenas grades com `SizeChartStatus` 1 ou 2.", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra por integração." }, { "name": "ExternalId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo identificador da grade no canal." }, { "name": "CatalogDomain", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo domínio de catálogo (ex.: `MLB-FOOTWEAR`)." } ], "responses": { "200": { "description": "Lista de grades.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSizeChartItem" } } } } } } }, "post": { "operationId": "hubProductSizeChartPost", "tags": [ "Hub — Anúncios" ], "summary": "Cria grade de tamanho — Hub Grade de Tamanho", "description": "Cria uma nova grade de tamanho com suas linhas (tamanhos) e atributos de medida. A grade nasce em status pendente de sincronização — um processo assíncrono envia ao canal. `RowId` precisa ser único dentro da grade.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductSizeChartCreate" } } }, "description": "Grade de tamanho a cadastrar com suas linhas iniciais. `IDCompanyIntegration`, `SizeChartName` e `TypeMeasure` são obrigatórios. Cada linha em `HubProductSizeChartRow[]` representa um tamanho com seu `RowId` único e a lista de atributos de medida (`FieldId` + `FieldValue`)." }, "responses": { "200": { "description": "Grade criada (mesma estrutura do GET por ID).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSizeChartDetail" } } } } }, "400": { "description": "`[BadRequest] - Empresa não existe` · `[BadRequest] - Linha {RowId} duplicada`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/size-chart/{idhubproductsizechart}": { "get": { "operationId": "hubProductSizeChartGet", "tags": [ "Hub — Anúncios" ], "summary": "Detalha grade — Hub Grade de Tamanho", "description": "Retorna a grade com todas as linhas (tamanhos) e atributos de medida.", "parameters": [ { "name": "idhubproductsizechart", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da tabela de medidas de produto no hub." } ], "responses": { "200": { "description": "Grade detalhada. Retorna array vazio quando não existe ou pertence a outra empresa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSizeChartDetail" } } } } } } }, "put": { "operationId": "hubProductSizeChartPut", "tags": [ "Hub — Anúncios" ], "summary": "Atualiza grade — Hub Grade de Tamanho", "description": "Atualiza nome e tipo de medida da grade. Tipo de medida **não pode** ser alterado depois que a grade foi sincronizada com o canal (já tem `ExternalId`).", "parameters": [ { "name": "idhubproductsizechart", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da tabela de medidas de produto no hub." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductSizeChartUpdate" } } }, "description": "Apenas `SizeChartName` e `TypeMeasure` podem ser alterados após a criação. `TypeMeasure` não pode mudar se a grade já foi sincronizada com o canal (existe `ExternalId`)." }, "responses": { "200": { "description": "Grade atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSizeChartDetail" } } } } }, "400": { "description": "`[BadRequest] - Grade de tamanho não existe` · `[BadRequest] - Grade de tamanho já foi sincronizada com canal e não pode ser alterada`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "hubProductSizeChartRowPost", "tags": [ "Hub — Anúncios" ], "summary": "Adiciona linha à grade — Hub Grade de Tamanho", "description": "Adiciona uma nova linha (tamanho) à grade existente. O `RowId` precisa ser único na grade. Cada combinação `FieldId`+`FieldValue` precisa ser única — o sistema rejeita atributos duplicados.", "parameters": [ { "name": "idhubproductsizechart", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da tabela de medidas de produto no hub." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductSizeChartRowPayload" } } }, "description": "Adiciona uma nova linha (tamanho) à grade. `RowId` deve ser único dentro da grade. Atributos com combinação `FieldId`+`FieldValue` já existentes na grade são rejeitados." }, "responses": { "200": { "description": "Linha adicionada (retorna a grade completa).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSizeChartDetail" } } } } }, "400": { "description": "`[BadRequest] - Empresa não existe` · `[BadRequest] - Já existe um tamanho com mesmo código (rowid)` · `[BadRequest] - Já existe o atributo {FieldName} com o mesmo valor {FieldValue}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubProductSizeChartDelete", "tags": [ "Hub — Anúncios" ], "summary": "Exclui grade — Hub Grade de Tamanho", "description": "Exclui a grade. Quando a grade ainda não foi sincronizada com o canal (sem `ExternalId`) a exclusão é imediata. Quando já foi sincronizada, dispara um pedido assíncrono ao canal — o status só será atualizado depois de até 24h.", "parameters": [ { "name": "idhubproductsizechart", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da tabela de medidas de produto no hub." } ], "responses": { "200": { "description": "Mensagem `Sucesso` (quando excluída localmente) ou `Solicitação de exclusão realizada com sucesso. Se houver algum problema, a tabela retornará a lista em 24h` (quando dispara processo no canal).", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "`[BadRequest] - Grade de tamanho não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/size-chart/{idhubproductsizechart}/{rowid}": { "put": { "operationId": "hubProductSizeChartRowPut", "tags": [ "Hub — Anúncios" ], "summary": "Atualiza atributos da linha — Hub Grade de Tamanho", "description": "Atualiza (upsert) os atributos de medida de uma linha existente. Combinações `FieldId` já presentes têm `FieldName`, `FieldValue` e `Unit` atualizados; novas combinações são inseridas.", "parameters": [ { "name": "idhubproductsizechart", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da tabela de medidas de produto no hub." }, { "name": "rowid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Código do tamanho dentro da grade." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductSizeChartRowUpdatePayload" } } }, "description": "Atributos de medida a inserir ou atualizar na linha. Combinações `FieldId` já existentes na linha são atualizadas; novas são adicionadas." }, "responses": { "200": { "description": "Linha atualizada (retorna a grade completa).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSizeChartDetail" } } } } }, "400": { "description": "`[BadRequest] - Linha grade de tamanho não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/promotion": { "get": { "operationId": "hubProductPromotionList", "tags": [ "Hub — Anúncios" ], "summary": "Lista promoções — Hub Promoções", "description": "Lista as promoções do hub. Use `IDProductHub` para verificar se um anúncio específico está em alguma promoção — quando informado, cada promoção retornada inclui o objeto `HubProductPromotionItem` com os campos do anúncio dentro daquela promoção. Página de até 2000 registros.", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da integração da empresa." }, { "name": "IDTypeHubProductPromotionStatus", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "description": "Filtra por status (`1`-`8`)." }, { "name": "IDTypeHubProductPromotion", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por tipo. Consulte `/type/hub/product/promotion/type`." }, { "name": "IDProductHub", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra promoções que contenham o anúncio informado (ex.: `MLB123456789`)." }, { "name": "IDHubProductPromotion", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da promoção de produto no hub." }, { "name": "DateFromDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra promoções com `DateFrom` >= esta data." }, { "name": "DateFromDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Filtra promoções com `DateFrom` <= esta data (23:59:59)." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (cada página = 2000 registros)." } ], "responses": { "200": { "description": "Promoções.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductPromotionItem" } } } } } } }, "post": { "operationId": "hubProductPromotionPost", "tags": [ "Hub — Anúncios" ], "summary": "Cria promoção — Hub Promoções", "description": "Cria promoção localmente e dispara sincronização assíncrona com o canal. Só funciona para tipos com `SellerCreate = 1`. Os demais tipos são gerados no canal e apenas recebidos no idworks. Para `Campanha vendedor` (tipo 8) o nome é único entre promoções ativas/programadas da mesma integração.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductPromotionCreate" } } }, "description": "Promoção a cadastrar. **Só funciona** para tipos com `SellerCreate = 1` no catálogo (atualmente `Desconto individual` e `Campanha vendedor`). Para `Campanha vendedor`, `PromotionName`, `DateFrom` e `DateTo` são obrigatórios; `SellerPercent` precisa ficar entre `0.10` e `0.70`; janela máxima de 31 dias." }, "responses": { "200": { "description": "Promoção criada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductPromotionDetail" } } } } }, "400": { "description": "`[BadRequest] - Empresa não existe` · `[BadRequest] - Tipo de promoção não pode ser criada` · `[BadRequest] - Obrigatório data de neste tipo de promoção` · `[BadRequest] - Obrigatório data até neste tipo de promoção` · `[BadRequest] - Nome da promoção não pode ser maior que 25 caracteres` · `[BadRequest] - Intervalo de data tem que ser inferior a 31 dias` · `[BadRequest] - Data até precisa ser maior que hoje` · `[BadRequest] - Desconto precisa ser maior que 10%` · `[BadRequest] - Desconto precisa ser menor que 70%` · `[BadRequest] - Já existe uma promoção ativa/programada com o mesmo nome`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/promotion/{idhubproductpromotion}": { "get": { "operationId": "hubProductPromotionGet", "tags": [ "Hub — Anúncios" ], "summary": "Detalha promoção — Hub Promoções", "description": "Retorna a promoção com seus anúncios. A lista de anúncios é paginada em blocos de 5000 — use `Page` para navegar. `HasNextPageItems = 1` indica que há mais itens.", "parameters": [ { "name": "idhubproductpromotion", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da promoção de produto no hub." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página de anúncios (cada página = 5000 anúncios)." } ], "responses": { "200": { "description": "Promoção detalhada. Array vazio quando não existe ou pertence a outra empresa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductPromotionDetail" } } } } } } }, "put": { "operationId": "hubProductPromotionPut", "tags": [ "Hub — Anúncios" ], "summary": "Atualiza promoção — Hub Promoções", "description": "Atualiza dados da promoção e dispara nova sincronização. Para `Campanha vendedor` em status `Iniciado` a `DateFrom` não pode ser alterada. Mesmas validações de datas/percentual da criação.", "parameters": [ { "name": "idhubproductpromotion", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da promoção de produto no hub." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductPromotionUpdate" } } }, "description": "Atualização da promoção. Mesmas regras de criação por tipo. Em `Campanha vendedor` já `Iniciado` (`IDTypeHubProductPromotionStatus = 2`), `DateFrom` não pode mais ser alterado." }, "responses": { "200": { "description": "Promoção atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductPromotionDetail" } } } } }, "400": { "description": "`[BadRequest] - Promoção não existe` · `[BadRequest] - Data inicio não pode ser alterada em promoção com status iniciada` · `[BadRequest] - Data inicio precisa ser maior ou igual a hoje` · `[BadRequest] - Já existe uma promoção ativa/programada com o mesmo nome`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubProductPromotionDelete", "tags": [ "Hub — Anúncios" ], "summary": "Exclui promoção — Hub Promoções", "description": "Solicita exclusão da promoção no canal (assíncrono). Só funciona para `Campanha vendedor` (tipo 8) — demais tipos não permitem exclusão pela API.", "parameters": [ { "name": "idhubproductpromotion", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da promoção de produto no hub." } ], "responses": { "200": { "description": "Pedido de exclusão registrado. Promoção retorna em status `Exclusão pendente` enquanto o canal processa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductPromotionDetail" } } } } }, "400": { "description": "`[BadRequest] - Promoção não existe` · `[BadRequest] - Tipo de promoção não permite excluir`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/promotion/{idhubproductpromotion}/item": { "post": { "operationId": "hubProductPromotionItemPost", "tags": [ "Hub — Anúncios" ], "summary": "Adiciona anúncio à promoção — Hub Promoções", "description": "Adiciona um anúncio à promoção e dispara sincronização. Só funciona quando a promoção é `SellerCreate = 1`. Para `Desconto individual` (tipo 3) o sistema consulta o anúncio no canal — preço promocional precisa ficar entre 20% e 95% do preço anunciado e o anúncio não pode estar em revisão.", "parameters": [ { "name": "idhubproductpromotion", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da promoção de produto no hub." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductPromotionItemCreate" } } }, "description": "Inclui um anúncio na promoção. Só permitido em promoções com `SellerCreate = 1`. Para `Desconto individual` o sistema valida que o desconto fica entre 5% e 80% do preço anunciado; `DateFrom` e `DateTo` são obrigatórios e o intervalo máximo é de 31 dias." }, "responses": { "200": { "description": "Anúncio adicionado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductPromotionAdvertisement" } } } } }, "400": { "description": "`[BadRequest] - Promoção não localizada` · `[BadRequest] - Promoção não permite adicionar itens` · `[BadRequest] - Este anúncio já esta na promoção e não pode ser adicionado novamente. Editar o mesmo` · `[BadRequest] - Anúncio não encontrado` · `[BadRequest] - Anúncio não localizado no canal` · `[BadRequest] - Item esta em revisão e não pode ser incluído promoção` · `[BadRequest] - Desconto precisa ser superior a 5%. Preço anúnciado do item no canal é {preço}` · `[BadRequest] - Desconto não pode ser maior que 80%. Preço anúnciado do item no canal é {preço}` · `[BadRequest] - Problema ao baixar anúncio no canal. Tentar novamente em instantes`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/promotion/{idhubproductpromotion}/item/{idhubproductpromotionitem}": { "put": { "operationId": "hubProductPromotionItemPut", "tags": [ "Hub — Anúncios" ], "summary": "Atualiza anúncio na promoção — Hub Promoções", "description": "Atualiza um anúncio dentro da promoção e dispara nova sincronização. **Disponível apenas** para integrações de promoção (`IDTypeCompanyIntegration = 10`). Os campos aceitos e as validações dependem do tipo da promoção: `Tradicional` valida preço acima de 0 e abaixo do original e do mínimo do canal; `Oferta relâmpago` valida preço e quantidade dentro dos limites do canal; `Oferta do dia` valida apenas preço; `Desconto individual` valida intervalo de datas (máx 31 dias); `Campanha vendedor` aceita só `SellingPrice` quando não há percentual fixo na promoção. Quando há `DateDeadline` na promoção, ela precisa estar no futuro.", "parameters": [ { "name": "idhubproductpromotion", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da promoção de produto no hub." }, { "name": "idhubproductpromotionitem", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do item da promoção de produto no hub." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductPromotionItemUpdate" } } }, "description": "Atualização do anúncio na promoção. Os campos aceitos e as validações variam por tipo: preço, datas, quantidade. Valores fora dos limites mínimos/máximos retornados pelo canal são rejeitados." }, "responses": { "200": { "description": "Anúncio atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductPromotionAdvertisement" } } } } }, "400": { "description": "`[BadRequest] - Item promoção não existe` · `[BadRequest] - Integração não tem recurso de promoção` · `[BadRequest] - Data limite para participar da promoção já terminou` · `[BadRequest] - Tipo de promoção não pertence a integração` · `[BadRequest] - Valor da oferta precisa ser maior que 0` · `[BadRequest] - Valor promocional precisa ser menor que preço base do item` · `[BadRequest] - Valor promocional não pode ser inferior ao valor mínimo do item em campanha, {valor}` · `[BadRequest] - Quantidade disponível precisa ser maior que 0` · `[BadRequest] - Valor da oferta não pode ser menor que valor mínimo de {valor}` · `[BadRequest] - Valor da oferta não pode ser maior que valor maximo de {valor}` · `[BadRequest] - Quantidade de estoque precisa ser maior que {qty}` · `[BadRequest] - Quantidade de estoque precisa ser menor que {qty}` · `[BadRequest] - Intervalo de data tem que ser inferior a 31 dias`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubProductPromotionItemDelete", "tags": [ "Hub — Anúncios" ], "summary": "Remove anúncio da promoção — Hub Promoções", "description": "Remove o anúncio da promoção e dispara sincronização para retirar do canal. Disponível apenas para integrações de promoção (`IDTypeCompanyIntegration = 10`). O item entra em status `Pendente` até o canal confirmar.", "parameters": [ { "name": "idhubproductpromotion", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da promoção de produto no hub." }, { "name": "idhubproductpromotionitem", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do item da promoção de produto no hub." } ], "responses": { "200": { "description": "Anúncio em remoção.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductPromotionAdvertisement" } } } } }, "400": { "description": "`[BadRequest] - Item promoção não existe` · `[BadRequest] - Integração não tem recurso de promoção`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/hub/product/promotion/status": { "get": { "operationId": "typeHubProductPromotionStatusList", "tags": [ "Hub — Tipos de Referência" ], "summary": "Lista status de promoção — Hub Promoções", "description": "Lista os status possíveis de promoção do hub: `1` Ativo · `2` Iniciado · `3` Programada · `4` Candidato · `5` Finalizada · `6` Ativação pendente · `7` Exclusão pendente · `8` Excluido.", "parameters": [ { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por integração (atualmente todos os status valem para todas as integrações)." } ], "responses": { "200": { "description": "Status.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeHubProductPromotionStatusItem" } } } } } } } }, "/type/hub/product/promotion/type": { "get": { "operationId": "typeHubProductPromotionList", "tags": [ "Hub — Tipos de Referência" ], "summary": "Lista tipos de promoção — Hub Promoções", "description": "Lista os tipos de promoção do hub (`Tradicional`, `Campanha vendedor`, `Oferta relâmpago`, `Oferta do dia`, `Desconto individual`, etc.). Use `SellerCreate=1` para listar apenas tipos que o vendedor pode criar diretamente pela API.", "parameters": [ { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por integração (ex.: `10` para Mercado Livre)." }, { "name": "SellerCreate", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra tipos que o vendedor pode criar localmente. `1` apenas criáveis · `0` apenas recebidos." } ], "responses": { "200": { "description": "Tipos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeHubProductPromotionItem" } } } } } } } }, "/sku/collection": { "get": { "operationId": "skuCollectionList", "tags": [ "Coleções" ], "summary": "Lista coleções", "description": "Lista as coleções da empresa, ordenadas por nome (`StockKeepingUnitCollectionName ASC`). Em contexto multi-conta (`accountname = all`), traz todas as contas acessíveis.", "parameters": [ { "name": "StockKeepingUnitCollectionName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome da coleção." }, { "name": "IDStockKeepingUnitCollection", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo id da coleção." } ], "responses": { "200": { "description": "Lista de coleções.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuCollectionItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuCollectionPost", "tags": [ "Coleções" ], "summary": "Cria coleção", "description": "Cria uma coleção para a empresa autenticada. Após inserir, reinvoca `skuCollectionList` e devolve a coleção criada (em formato de lista).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuCollectionCreate" } } }, "description": "Dados da coleção (grupo de SKUs com finalidade de exibição/agrupamento) a cadastrar." }, "responses": { "200": { "description": "Coleção criada (devolve a coleção em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuCollectionItem" } } } } }, "400": { "description": "`[BadRequest] - Empresa não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/collection/{idstockkeepingunitcollection}": { "put": { "operationId": "skuCollectionPut", "tags": [ "Coleções" ], "summary": "Atualiza coleção", "description": "Renomeia uma coleção da empresa autenticada. Após atualizar, reinvoca `skuCollectionList` e devolve a coleção atualizada (em formato de lista).", "parameters": [ { "name": "idstockkeepingunitcollection", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da coleção." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuCollectionCreate" } } }, "description": "Atualiza a coleção. Mesmo schema do POST." }, "responses": { "200": { "description": "Coleção atualizada (devolve a coleção em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuCollectionItem" } } } } }, "400": { "description": "`[BadRequest] - Coleção não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuCollectionDelete", "tags": [ "Coleções" ], "summary": "Exclui coleção", "description": "Exclui uma coleção da empresa autenticada. **Bloqueado** quando a coleção tem SKUs associados — é preciso remover os vínculos antes (endpoints `/sku/{idsku}/collection`).", "parameters": [ { "name": "idstockkeepingunitcollection", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da coleção." } ], "responses": { "200": { "description": "Coleção excluída. Corpo: string `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "`[BadRequest] - Coleção não existe`; `[BadRequest] - Coleção esta associada a SKUs, remover o vínculo antes de excluir a coleção`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/group": { "get": { "operationId": "skuGroupList", "tags": [ "Grupos de SKU" ], "summary": "Lista grupos SKU", "description": "Lista os grupos da empresa, ordenados por nome (`SkuGroupName ASC`), paginados em blocos de 10000. Em contexto multi-conta (`accountname = all`), traz todas as contas acessíveis.", "parameters": [ { "name": "SkuGroupName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome do grupo (igualdade)." }, { "name": "Search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca parcial (`LIKE`) no nome do grupo." }, { "name": "IDStockKeepingUnitGroup", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo id do grupo." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (offset = `Page * 10000`)." } ], "responses": { "200": { "description": "Lista de grupos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuGroupItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuGroupPost", "tags": [ "Grupos de SKU" ], "summary": "Cria grupo SKU", "description": "Cria um grupo para a empresa autenticada. Após inserir, reinvoca `skuGroupList` e devolve o grupo criado (em formato de lista).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuGroupCreate" } } }, "description": "Dados do grupo de SKUs (agrupamento operacional, distinto da coleção) a cadastrar." }, "responses": { "200": { "description": "Grupo criado (devolve o grupo em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuGroupItem" } } } } }, "400": { "description": "`[BadRequest] - Empresa não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/group/{idstockkeepingunitgroup}": { "put": { "operationId": "skuGroupPut", "tags": [ "Grupos de SKU" ], "summary": "Atualiza grupo SKU", "description": "Renomeia um grupo da empresa autenticada. Após atualizar, reinvoca `skuGroupList` e devolve o grupo atualizado (em formato de lista).", "parameters": [ { "name": "idstockkeepingunitgroup", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id do grupo." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuGroupCreate" } } }, "description": "Atualiza o grupo. Mesmo schema do POST." }, "responses": { "200": { "description": "Grupo atualizado (em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuGroupItem" } } } } }, "400": { "description": "`[BadRequest] - Grupo não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuGroupDelete", "tags": [ "Grupos de SKU" ], "summary": "Exclui grupo SKU", "description": "Exclui um grupo da empresa autenticada. **Bloqueado** quando o grupo tem SKUs associados ou códigos similares vinculados.", "parameters": [ { "name": "idstockkeepingunitgroup", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id do grupo." } ], "responses": { "200": { "description": "Grupo excluído. Corpo: string `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "`[BadRequest] - Grupo não existe`; `[BadRequest] - Grupo esta associado a SKUs, remover o vínculo antes de excluir o grupo`; `[BadRequest] - Grupo esta associado a códigos similares, remover o vínculo antes de excluir o grupo`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/similar-code": { "get": { "operationId": "skuSimilarCodeList", "tags": [ "Códigos Similares" ], "summary": "Lista códigos similares", "description": "Lista os códigos similares da empresa autenticada com o grupo (`SkuGroupName`) e a conta (`AccountName`) já resolvidos. Em contexto multi-conta (`accountname = all`), traz todas as contas acessíveis. Ordenado por `SkuGroupName ASC`, paginado em blocos de 10000.", "parameters": [ { "name": "SkuGroupName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome exato do grupo SKU (igualdade)." }, { "name": "IDStockKeepingUnitGroup", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo id do grupo SKU." }, { "name": "SkuSimilarCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código similar (igualdade)." }, { "name": "SkuSimilarCodeTag", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela tag do código similar (igualdade)." }, { "name": "IDStockKeepingUnitSimilarCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo id do código similar." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (offset = `Page * 10000`)." } ], "responses": { "200": { "description": "Lista de códigos similares.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSimilarCodeItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuSimilarCodePost", "tags": [ "Códigos Similares" ], "summary": "Cria código similar", "description": "Cria um código similar vinculado a um grupo SKU da empresa autenticada. Valida que o grupo existe e pertence à empresa, e que `SkuSimilarCode` ainda não existe no grupo. Após inserir, reinvoca `skuSimilarCodeList` e devolve o código criado (em formato de lista).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuSimilarCodeCreate" } } }, "description": "Cadastro de código similar — código de referência alternativo que permite localizar o SKU por código de fornecedor ou marketplace externo." }, "responses": { "200": { "description": "Código criado (devolve o código em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSimilarCodeItem" } } } } }, "400": { "description": "`[BadRequest] - Grupo não existe`; `[BadRequest] - Já existe esse código cadastrado para o grupo`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/similar-code/tag": { "get": { "operationId": "skuSimilarCodeTagList", "tags": [ "Códigos Similares" ], "summary": "Lista tags de códigos similares", "description": "Lista as tags (`SkuSimilarCodeTag`) já em uso pelos códigos similares da empresa autenticada, em ordem alfabética. Ignora valores nulos e vazios. Usada para popular o autocomplete do campo `SkuSimilarCodeTag` na tela.", "responses": { "200": { "description": "Lista de tags distintas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSimilarCodeTagItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/similar-code/{idstockkeepingunitsimilarcode}": { "put": { "operationId": "skuSimilarCodePut", "tags": [ "Códigos Similares" ], "summary": "Atualiza código similar", "description": "Atualiza grupo, código e/ou tag de um código similar da empresa autenticada. Quando `SkuSimilarCode` muda, valida que o novo código ainda não existe no grupo. Quando `IDStockKeepingUnitGroup` muda, valida que o novo grupo pertence à empresa. Após atualizar, reinvoca `skuSimilarCodeList` e devolve o registro (em formato de lista).", "parameters": [ { "name": "idstockkeepingunitsimilarcode", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id do código similar." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuSimilarCodeCreate" } } }, "description": "Atualiza o código similar. Mesmo schema do POST." }, "responses": { "200": { "description": "Código atualizado (em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSimilarCodeItem" } } } } }, "400": { "description": "`[BadRequest] - Código similar não existe`; `[BadRequest] - Grupo não existe`; `[BadRequest] - Já existe esse código cadastrado para o grupo`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuSimilarCodeDelete", "tags": [ "Códigos Similares" ], "summary": "Exclui código similar", "description": "Exclui fisicamente o código similar da empresa autenticada. Sem regras de bloqueio — o vínculo é apenas com o grupo SKU, que não trava a exclusão.", "parameters": [ { "name": "idstockkeepingunitsimilarcode", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id do código similar." } ], "responses": { "200": { "description": "Código excluído. Corpo: string `\"Sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "Sucesso" } } } }, "400": { "description": "`[BadRequest] - Código similar não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/variation": { "get": { "operationId": "typeSkuVariationList", "tags": [ "Tipos — SKU" ], "summary": "Lista variações", "description": "Lista as variações Ativas da empresa, ordenadas por `ProductVariationOrder` e `ProductVariation`. Cada item já traz a grade de valores no campo `TypeProductVariation`.", "responses": { "200": { "description": "Lista de variações.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeSkuVariationItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "typeSkuVariationPost", "tags": [ "Tipos — SKU" ], "summary": "Cria variação", "description": "Cria uma variação para a empresa autenticada. Após inserir, reinvoca `typeSkuVariationList` e devolve a lista atualizada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeSkuVariationCreate" } } }, "description": "Dados da variação a cadastrar. `ProductVariation` (nome) e `IDTypeProductVariationType` (tipo padrão — Cor, Tamanho, Voltagem…) obrigatórios. `ProductVariationOrder` é a ordem de exibição (única por empresa); quando omitida, recebe o próximo número após o maior `ProductVariationOrder` já cadastrado." }, "responses": { "200": { "description": "Variação criada (devolve a lista de variações).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeSkuVariationItem" } } } } }, "400": { "description": "`[BadRequest] - Empresa não existe`; `[BadRequest] - Variação padrão não existe`; `[BadRequest] - Já existe variação com essa ordem `; `[BadRequest] - Problema ao adicionar variação, validar se todos os dados obrigatórios foram informados (tipo, nome e ordem)`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/variation/type": { "get": { "operationId": "typeProductVariationType", "tags": [ "Tipos — SKU" ], "summary": "Lista tipos padrão de variação", "description": "Lista os **tipos padrão** de variação do sistema (Cor, Tamanho, Voltagem, Material, Sabor…), ordenados por nome. Lista fixa, igual para todas as empresas — usada para preencher o campo `IDTypeProductVariationType` ao criar/editar uma variação.", "responses": { "200": { "description": "Lista de tipos padrão.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeProductVariationTypeItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/variation/{idtypeskuvariation}": { "get": { "operationId": "typeSkuVariationGet", "tags": [ "Tipos — SKU" ], "summary": "Detalha uma variação", "description": "Retorna a variação da empresa autenticada com a sua grade de valores. Devolve `[]` quando a variação não existe.", "parameters": [ { "name": "idtypeskuvariation", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da variação." } ], "responses": { "200": { "description": "Variação encontrada (lista de 1 item) ou `[]`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeSkuVariationDetail" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "typeSkuVariationPut", "tags": [ "Tipos — SKU" ], "summary": "Atualiza variação", "description": "Atualiza nome, tipo e/ou ordem de uma variação (atualização parcial). Após atualizar, reinvoca `typeSkuVariationList` e devolve a lista.", "parameters": [ { "name": "idtypeskuvariation", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da variação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeSkuVariationCreate" } } }, "description": "Atualização parcial da variação (`ProductVariation`, `IDTypeProductVariationType`, `ProductVariationOrder`). `ProductVariationOrder` mantém a regra de unicidade por empresa." }, "responses": { "200": { "description": "Variação atualizada (devolve a lista de variações).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeSkuVariationItem" } } } } }, "400": { "description": "`[BadRequest] - Variação não existe`; `[BadRequest] - Variação padrão não existe`; `[BadRequest] - Já existe variação com essa ordem `; `[BadRequest] - Problema ao atualizar variação, validar se todos os dados obrigatórios foram informados (tipo, nome e ordem)`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "typeSkuVariationDelete", "tags": [ "Tipos — SKU" ], "summary": "Exclui variação", "description": "Exclui uma variação da empresa autenticada (a grade é removida em cascata). **Bloqueado** quando há SKU usando a variação. Após excluir, reinvoca `typeSkuVariationList` e devolve a lista.", "parameters": [ { "name": "idtypeskuvariation", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da variação." } ], "responses": { "200": { "description": "Variação excluída (devolve a lista de variações).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeSkuVariationItem" } } } } }, "400": { "description": "`[BadRequest] - Variação não existe`; `[BadRequest] - Existe SKU com essa variação. Remover do SKU antes de excluir`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/variation/{idtypeskuvariation}/value": { "get": { "operationId": "skuVariationValueList", "tags": [ "Tipos — SKU" ], "summary": "Lista valores da grade", "description": "Lista os valores da grade de uma variação, ordenados por `ProductVariationValueOrder` e nome.", "parameters": [ { "name": "idtypeskuvariation", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da variação." } ], "responses": { "200": { "description": "Lista de valores da grade.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GradeValueItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuVariationValuePost", "tags": [ "Tipos — SKU" ], "summary": "Cria valor da grade", "description": "Adiciona um valor à grade de uma variação. Após inserir, reinvoca `typeSkuVariationGet` e devolve o detalhe da variação.", "parameters": [ { "name": "idtypeskuvariation", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da variação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GradeValueCreate" } } }, "description": "Dados do valor da grade a cadastrar. `TypeProductVariationValue` (nome do valor — ex.: `Azul`, `M`) obrigatório. `ProductVariationValueOrder` é a ordem dentro da grade (única por variação). O par (`TypeProductVariationValue`, `IDTypeProductVariation`) precisa ser inédito." }, "responses": { "200": { "description": "Valor criado (devolve o detalhe da variação).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeSkuVariationDetail" } } } } }, "400": { "description": "`[BadRequest] - Variação não existe`; `[BadRequest] - Já existe esta grade para a variação`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/variation/{idtypeskuvariation}/value/{idtypeskuvariationvalue}": { "put": { "operationId": "skuVariationValuePut", "tags": [ "Tipos — SKU" ], "summary": "Atualiza valor da grade", "description": "Atualiza nome e ordem de um valor da grade. Após atualizar, reinvoca `typeSkuVariationGet` e devolve o detalhe da variação.", "parameters": [ { "name": "idtypeskuvariation", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da variação." }, { "name": "idtypeskuvariationvalue", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id do valor da grade." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GradeValueCreate" } } }, "description": "Atualiza o valor da grade (`TypeProductVariationValue`, `ProductVariationValueOrder`). Mantém a regra de unicidade do par (`TypeProductVariationValue`, `IDTypeProductVariation`)." }, "responses": { "200": { "description": "Valor atualizado (devolve o detalhe da variação).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeSkuVariationDetail" } } } } }, "400": { "description": "`[BadRequest] - Variação não existe`; `[BadRequest] - Já existe esta grade para a variação`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuVariationValueDelete", "tags": [ "Tipos — SKU" ], "summary": "Exclui valor da grade", "description": "Remove um valor da grade. **Bloqueado** quando há SKU usando o valor. Após excluir, reinvoca `typeSkuVariationGet` e devolve o detalhe da variação.", "parameters": [ { "name": "idtypeskuvariation", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da variação." }, { "name": "idtypeskuvariationvalue", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id do valor da grade." } ], "responses": { "200": { "description": "Valor excluído (devolve o detalhe da variação).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeSkuVariationDetail" } } } } }, "400": { "description": "`[BadRequest] - Grade não existe`; `[BadRequest] - Existe SKU com essa grade. Remover do SKU antes de excluir`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/category": { "get": { "operationId": "categoryList", "tags": [ "Categorias de Produto" ], "summary": "Lista categorias", "description": "Lista as categorias ativas da empresa autenticada. Com `Type=Tree` (modo usado pela tela) retorna a árvore aninhada, cada nó com `Children`. Sem `Type=Tree`, retorna uma lista achatada em que cada item traz `CategoryTree` — a trilha do caminho da raiz até a categoria (`Pai -> Filho -> Neto`).", "parameters": [ { "name": "Type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Use `Tree` para receber a árvore aninhada com `Children`. Omitido, retorna a lista achatada com a trilha `CategoryTree`." } ], "responses": { "200": { "description": "Árvore de categorias (modo `Type=Tree`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryTreeNode" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "categoryPost", "tags": [ "Categorias de Produto" ], "summary": "Cria categoria", "description": "Cria uma categoria para a empresa autenticada. Quando `Description`, `Keywords` ou `Title` não são informados, assumem o valor de `Name`. Após inserir, reinvoca `categoryGet` e devolve a categoria criada (em formato de lista).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryCreate" } } }, "description": "Dados da categoria a cadastrar. Apenas `Name` é obrigatório; `Description`, `Keywords` e `Title` herdam o valor de `Name` quando ausentes ou vazios. `ShowInStoreFront`, `ShowBrandFilter` e `ActiveStoreFrontLink` assumem `1` por default. `IDCategoryFather` cria categoria filha; `null`/ausente cria categoria de topo." }, "responses": { "200": { "description": "Categoria criada (em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryDetail" } } } } }, "400": { "description": "`[BadRequest] - Company não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/category/{idcategory}": { "get": { "operationId": "categoryGet", "tags": [ "Categorias de Produto" ], "summary": "Detalha categoria", "description": "Retorna os dados completos de uma categoria da empresa autenticada, incluindo `CategoryFather` (nome da categoria pai). Devolve uma lista vazia quando a categoria não existe.", "parameters": [ { "name": "idcategory", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da categoria." } ], "responses": { "200": { "description": "Dados da categoria (em formato de lista; vazia se não existir).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryDetail" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "categoryPut", "tags": [ "Categorias de Produto" ], "summary": "Atualiza categoria", "description": "Atualização parcial: apenas os campos enviados são alterados. Após atualizar, reinvoca `categoryGet` e devolve a categoria atualizada (em formato de lista).", "parameters": [ { "name": "idcategory", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da categoria." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryUpdate" } } }, "description": "Campos da categoria a atualizar. Todos opcionais — apenas os enviados são aplicados. `IDCategoryFather` aceita `null` explícito para mover a categoria para o topo, e não pode ser igual ao próprio id (categoria não pode ser superior dela mesma) nem apontar para categoria de outra empresa." }, "responses": { "200": { "description": "Categoria atualizada (em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryDetail" } } } } }, "400": { "description": "`[BadRequest] - Categoria não pode ser superior dela mesma`; `[BadRequest] - Categoria pai não localizada`; `[BadRequest] - Categoria não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "categoryDelete", "tags": [ "Categorias de Produto" ], "summary": "Exclui categoria", "description": "Exclusão lógica (`Status = 0`) de uma categoria da empresa autenticada. **Bloqueada** quando a categoria tem produtos ativos vinculados ou quando possui subcategorias.", "parameters": [ { "name": "idcategory", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da categoria." } ], "responses": { "200": { "description": "Categoria excluída. Corpo: string `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "`[BadRequest] - Categoria possui produto ativos. Alterar a categoria no cadastro do item antes de excluir a categoria`; `[BadRequest] - Categoria possui filhos (categoria inferior) que precisam ser removidas`; `[BadRequest] - Categoria não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/category/{idcategory}/sku-specification": { "get": { "operationId": "skuSpecificationFieldList", "tags": [ "Especificações por Categoria" ], "summary": "Lista especificações da categoria", "description": "Lista as especificações (campos) ativas da categoria, **incluindo as herdadas das categorias ancestrais** (a herança sobe a árvore). Cada campo traz seus valores em `FieldValue`.", "parameters": [ { "name": "idcategory", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da categoria." } ], "responses": { "200": { "description": "Especificações da categoria e ancestrais.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SpecFieldItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuSpecificationFieldIdPost", "tags": [ "Especificações por Categoria" ], "summary": "Cria especificação na categoria", "description": "Cria uma especificação (campo) na categoria. Após inserir, reinvoca `skuSpecificationFieldIdGet` e devolve o campo criado (em formato de lista).", "parameters": [ { "name": "idcategory", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da categoria." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecFieldCreate" } } }, "description": "Dados da especificação a cadastrar na categoria. `FieldName` e `IDStockKeepingUnitSpecificationsFieldTypes` são obrigatórios. `IDFieldExternal`, quando informado, precisa ser único dentro da categoria — o sistema rejeita duplicidade com erro de validação." }, "responses": { "200": { "description": "Especificação criada (em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SpecFieldDetail" } } } } }, "400": { "description": "`[BadRequest] - Já existe outra especificação com mesmo código externo`; `[BadRequest] - Categoria não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/category/{idcategory}/sku-specification/{idstockkeepingunitspecificationsfieldid}": { "get": { "operationId": "skuSpecificationFieldIdGet", "tags": [ "Especificações por Categoria" ], "summary": "Detalha especificação", "description": "Retorna uma especificação ativa da categoria com seus valores em `FieldValue`. Devolve uma lista vazia quando não existe.", "parameters": [ { "name": "idcategory", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da categoria." }, { "name": "idstockkeepingunitspecificationsfieldid", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da especificação (campo) da categoria." } ], "responses": { "200": { "description": "Dados da especificação (em formato de lista; vazia se não existir).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SpecFieldDetail" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "skuSpecificationFieldIdPut", "tags": [ "Especificações por Categoria" ], "summary": "Atualiza especificação", "description": "Atualização parcial da especificação: apenas os campos enviados são alterados. Após atualizar, reinvoca `skuSpecificationFieldIdGet` e devolve o campo (em formato de lista).", "parameters": [ { "name": "idcategory", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da categoria." }, { "name": "idstockkeepingunitspecificationsfieldid", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da especificação (campo) da categoria." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecFieldUpdate" } } }, "description": "Campos da especificação a atualizar. Todos opcionais. `IDFieldExternal` mantém a regra de unicidade dentro da categoria. As flags (`IsFilter`, `IsActive`, `IsRequired`, etc.) usam `1`/`0`." }, "responses": { "200": { "description": "Especificação atualizada (em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SpecFieldDetail" } } } } }, "400": { "description": "`[BadRequest] - ID Externo já existe para o campo: `; `[BadRequest] - Sku Specification não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuSpecificationFieldValuePost", "tags": [ "Especificações por Categoria" ], "summary": "Adiciona valor à especificação", "description": "Adiciona um valor a uma especificação do tipo lista. Após inserir, reinvoca `skuSpecificationFieldIdGet` e devolve o campo com seus valores (em formato de lista).", "parameters": [ { "name": "idcategory", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da categoria." }, { "name": "idstockkeepingunitspecificationsfieldid", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da especificação (campo) da categoria." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecValueCreate" } } }, "description": "Adiciona um valor à especificação (lista de opções). `Value` obrigatório. `IDFieldValueExternal` e `Position` são opcionais e gravados como `null` quando ausentes." }, "responses": { "200": { "description": "Valor adicionado; especificação retornada (em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SpecFieldDetail" } } } } }, "400": { "description": "`[BadRequest] - Sku Specification não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuSpecificationFieldIdDelete", "tags": [ "Especificações por Categoria" ], "summary": "Exclui especificação", "description": "Exclusão lógica (`Status = 0`) de uma especificação da categoria.", "parameters": [ { "name": "idcategory", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da categoria." }, { "name": "idstockkeepingunitspecificationsfieldid", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da especificação (campo) da categoria." } ], "responses": { "200": { "description": "Especificação excluída.", "content": { "application/json": { "schema": { "type": "object", "properties": { "Message": { "type": "string", "example": "Sucesso", "description": "Mensagem de confirmação da remoção (`\"sucesso\"` em caso de remoção bem-sucedida)." } } } } } }, "400": { "description": "`[BadRequest] - Sku Specification Field não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/category/{idcategory}/sku-specification/{idstockkeepingunitspecificationsfieldid}/{idstockkeepingunitspecificationsfieldvalues}": { "put": { "operationId": "skuSpecificationFieldValuePut", "tags": [ "Especificações por Categoria" ], "summary": "Atualiza valor da especificação", "description": "Atualiza um valor de uma especificação. Após atualizar, reinvoca `skuSpecificationFieldIdGet` e devolve o campo (em formato de lista).", "parameters": [ { "name": "idcategory", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da categoria." }, { "name": "idstockkeepingunitspecificationsfieldid", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da especificação (campo) da categoria." }, { "name": "idstockkeepingunitspecificationsfieldvalues", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id do valor da especificação." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecValueUpdate" } } }, "description": "Atualiza um valor da especificação. `Value` obrigatório. `IDFieldValueExternal` e `Position` opcionais." }, "responses": { "200": { "description": "Valor atualizado; especificação retornada (em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SpecFieldDetail" } } } } }, "400": { "description": "`[BadRequest] - Sku Specification Value não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuSpecificationFieldValueDelete", "tags": [ "Especificações por Categoria" ], "summary": "Exclui valor da especificação", "description": "Exclui (físico) um valor de uma especificação. Após excluir, reinvoca `skuSpecificationFieldIdGet` e devolve o campo (em formato de lista).", "parameters": [ { "name": "idcategory", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da categoria." }, { "name": "idstockkeepingunitspecificationsfieldid", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id da especificação (campo) da categoria." }, { "name": "idstockkeepingunitspecificationsfieldvalues", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Id do valor da especificação." } ], "responses": { "200": { "description": "Valor excluído; especificação retornada (em formato de lista).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SpecFieldDetail" } } } } }, "400": { "description": "`[BadRequest] - Sku Specification Value não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/specification/field-type": { "get": { "operationId": "typeSkuSpecificationFieldTypeList", "tags": [ "Tipos — SKU" ], "summary": "Lista tipos de campo de especificação", "description": "Lista os tipos de preenchimento disponíveis para as especificações (texto, número, lista de opções etc.), ordenados por nome. Lista padrão do sistema, igual para todas as contas.", "responses": { "200": { "description": "Tipos de campo de especificação.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SpecFieldTypeItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product": { "get": { "operationId": "hubProductList", "tags": [ "Hub — Anúncios" ], "summary": "Lista anúncios — Hub Anúncios", "description": "Lista os anúncios (ofertas publicadas nos canais de venda) da empresa autenticada, agrupados por anúncio. Cada item traz o produto vinculado, canal, status, qualidade, preços e o array `HubSku` com as variações. Use `GroupByHubSku=1` para receber uma linha por variação em vez de uma por anúncio. Página de até 400 registros.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (cada página = 400 registros)." }, { "name": "Search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca textual em código/nome do produto, código do anúncio (`IDProductHub`), código de referência (`IDSkuCompany`) e código de variação (`IDSkuHub`)." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra por integração (conta de canal) específica." }, { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra por tipo de canal (ex.: Mercado Livre, Shopee)." }, { "name": "IDSalesChannel", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra por canal de vendas." }, { "name": "IDProduct", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo SKU/produto vinculado." }, { "name": "IDSku", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra anúncios que contenham este SKU em alguma variação." }, { "name": "IDProductCompany", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código de referência do produto (`IDSkuCompany`)." }, { "name": "IDSkuCompany", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código de referência da variação." }, { "name": "IDHubProduct", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador interno do anúncio." }, { "name": "IDProductHub", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código do anúncio no canal (ex.: `MLB123456789`)." }, { "name": "IDSkuHub", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código da variação no canal." }, { "name": "SkuName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo nome do produto (busca parcial)." }, { "name": "BarCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código de barras." }, { "name": "IDBrand", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pela marca." }, { "name": "IDTypeSku", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo tipo de produto." }, { "name": "IDStatus", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo status do anúncio (`AdvertisementStatus`): `0` Inativo, `1` Ativo, `2` Fechado, `3` Pausado, `4` Em revisão, `5` Inabilitado canal." }, { "name": "HubProductSubStatus", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra pelo sub-status (mesma tabela de status)." }, { "name": "Published", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "`1` somente publicados no canal (com `IDProductHub`), `0` somente não publicados." }, { "name": "HasProduct", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "`1` somente anúncios vinculados a um produto, `0` somente sem vínculo." }, { "name": "HasSku", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "`1` somente anúncios com variação vinculada, `0` somente sem." }, { "name": "HasManualPrice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "`1` somente anúncios com preço manual em alguma variação, `0` somente sem." }, { "name": "Health", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Valor de qualidade do anúncio (%) usado com `HealthType`." }, { "name": "HealthType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comparador da qualidade: `greater` (maior que `Health`) ou `smaller` (menor que `Health`)." }, { "name": "AutopartsPendingCompatibility", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Autopeças: `1` somente anúncios com compatibilidade pendente." }, { "name": "AutopartsRequiredCompatibility", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Autopeças: `1` somente anúncios que exigem lista de compatibilidade." }, { "name": "GroupByHubSku", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "`1` retorna uma linha por variação (item) em vez de uma por anúncio." } ], "responses": { "200": { "description": "Lista de anúncios (ou de variações quando `GroupByHubSku=1`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductListItem" } } } } } } }, "post": { "operationId": "hubProductPost", "tags": [ "Hub — Anúncios" ], "summary": "Cria anúncio — Hub Anúncios", "description": "Cria um anúncio para um produto em uma integração (canal). O anúncio nasce pendente de sincronização — um processo assíncrono o envia ao canal. As variações (`HubSku`) são geradas automaticamente a partir do produto: para um produto com grade de variação, uma variação por componente; caso contrário, uma única variação.\n\nOs campos disponíveis dependem do canal — itens como `ListingTypeId`, `ShippingMode`, `OfficialStore` e preço por quantidade são específicos do Mercado Livre.\n\nPara **duplicar** um anúncio existente, informe a query string `IDHubProduct` com o anúncio de origem (e `IDCompanyIntegration` no corpo com o canal de destino); nesse fluxo os arrays `HubSku`, `Autoparts`, `HubProductSpecification` e `HubProductSalesPolicy` são copiados.", "parameters": [ { "name": "IDHubProduct", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Anúncio de origem a duplicar. Quando informado, o corpo é montado a partir desse anúncio." }, { "name": "IgnoreHubSku", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "`1` não cria automaticamente as variações (`HubSku`)." }, { "name": "NoInvoke", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "`1` retorna apenas a string `\"sucesso\"` em vez do anúncio criado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductCreate" } } }, "description": "Anúncio (produto no canal) a cadastrar. Estrutura completa em `HubProductCreate` — inclui dados gerais, especificações da categoria do canal, política comercial, imagens e (quando o anúncio é de autopeças) o vínculo com o catálogo de aplicação." }, "responses": { "200": { "description": "Anúncio criado (mesma estrutura do GET por id) ou `\"sucesso\"` quando `NoInvoke=1`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductDetail" } } } } }, "400": { "description": "`[BadRequest] - Integração não existe` · `[BadRequest] - Produto não existe` · `[BadRequest] - Produto sem componentes de variação` · `[BadRequest] - Já existe um anúncio com o mesmo codigo para essa integração` · `[BadRequest] - Template de mensagem não encontrado` · `[BadRequest] - Anúncio para duplicar não encontrado`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/{idhubproduct}": { "get": { "operationId": "hubProductGet", "tags": [ "Hub — Anúncios" ], "summary": "Detalha anúncio — Hub Anúncios", "description": "Retorna o detalhe completo de um anúncio: dados do canal, categoria, preços, status, qualidade, experiência de compra, avaliação, dados de catálogo, imagens, ficha técnica, variações (`HubSku`) e — para o Mercado Livre — preço por quantidade. A resposta é um array com um único objeto.", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." } ], "responses": { "200": { "description": "Detalhe do anúncio (array com um objeto; vazio se não existir).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductDetail" } } } } } } }, "put": { "operationId": "hubProductPut", "tags": [ "Hub — Anúncios" ], "summary": "Atualiza anúncio — Hub Anúncios", "description": "Atualiza um anúncio (atualização parcial — só os campos enviados são alterados). A mudança é reenviada ao canal de forma assíncrona. Quando a parametrização de atualização automática de preço está ativa e o canal aceita preço, alterar `PriceSellSet`/`PriceListSet` dispara o envio do preço.\n\nRegras: a categoria de um anúncio que já teve vendas no Mercado Livre não pode ser alterada; o preço a nível de anúncio fica bloqueado enquanto alguma variação tem preço manual (`PricingSet`).", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." }, { "name": "NoInvoke", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "`1` retorna apenas `\"sucesso\"` em vez do anúncio atualizado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductUpdate" } } }, "description": "Atualização do anúncio. Mesma estrutura do POST — campos não enviados preservam o valor atual." }, "responses": { "200": { "description": "Anúncio atualizado (mesma estrutura do GET por id) ou `\"sucesso\"` quando `NoInvoke=1`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductDetail" } } } } }, "400": { "description": "`[BadRequest] - Produto Hub não existe` · `[BadRequest] - Produto/Sku não existe` · `[BadRequest] - Integração não existe` · `[BadRequest] - Já existe uma anuncio igual para a mesma integração` · `[BadRequest] - Não pode ser alterada a categoria, pois já houve venda do anúncio` · `[BadRequest] - Variação anúncio tem preço manual setado. Remover antes de atualizar o preço a nível de anúncio` · `[BadRequest] - Template de mensagem não encontrado`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubProductDelete", "tags": [ "Hub — Anúncios" ], "summary": "Exclui anúncio — Hub Anúncios", "description": "Exclui o anúncio e suas variações do cadastro e comunica a remoção ao canal de forma assíncrona. Dependendo do canal e do status, o anúncio pode permanecer no marketplace (encerrado em vez de apagado).", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." } ], "responses": { "200": { "description": "Anúncio excluído.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "`[BadRequest] - Anúncio não existe` · `[BadRequest] - Erro ao deletar anúncio`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/{idhubproduct}/autoparts": { "get": { "operationId": "hubProductAutopartsGet", "tags": [ "Hub — Anúncios" ], "summary": "Lista compatibilidade de autopeças — Hub Anúncios", "description": "Lista os veículos compatíveis associados ao anúncio de autopeças (marca, modelo, ano, versão e demais atributos do veículo), as posições de aplicação e eventuais reclamações de compatibilidade registradas pelos compradores. Recurso específico de autopeças (principalmente Mercado Livre).", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." } ], "responses": { "200": { "description": "Veículos compatíveis (array vazio se não houver).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductAutopartsItem" } } } } } } }, "post": { "operationId": "hubProductAutopartsPost", "tags": [ "Hub — Anúncios" ], "summary": "Adiciona veículo compatível — Hub Anúncios", "description": "Associa um veículo (compatibilidade) ao anúncio de autopeças. Os atributos do veículo (`Brand`, `Model`, `Year`, etc.) só são usados para cadastrar o veículo no catálogo do canal quando ele ainda não existe; em geral basta o `ProductId` do veículo.", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." }, { "name": "NoInvoke", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "`1` retorna apenas `\"sucesso\"` em vez da lista atualizada." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductAutopartsCreate" } } }, "description": "Aplicação de autopeça a vincular ao anúncio. Identifica veículo/posição compatível conforme o catálogo do canal (ex.: marca/modelo/ano/posição). Estrutura completa em `HubProductAutopartsCreate`." }, "responses": { "200": { "description": "Lista de veículos compatíveis atualizada ou `\"sucesso\"` quando `NoInvoke=1`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductAutopartsItem" } } } } }, "400": { "description": "`[BadRequest] - Anúncio não existe` · `[BadRequest] - este veículo já existe no anúncio`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/{idhubproduct}/autoparts/{idhubproductautoparts}": { "put": { "operationId": "hubProductAutopartsPut", "tags": [ "Hub — Anúncios" ], "summary": "Atualiza veículo compatível — Hub Anúncios", "description": "Atualiza as observações e as posições de aplicação de um veículo compatível do anúncio de autopeças.", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." }, { "name": "idhubproductautoparts", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do veículo compatível." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductAutopartsUpdate" } } }, "description": "Atualização da aplicação de autopeça vinculada ao anúncio." }, "responses": { "200": { "description": "Lista de veículos compatíveis atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductAutopartsItem" } } } } }, "400": { "description": "`[BadRequest] - Autopartes anúncio não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubProductAutopartsDelete", "tags": [ "Hub — Anúncios" ], "summary": "Remove veículo compatível — Hub Anúncios", "description": "Remove um veículo compatível (e suas posições) do anúncio de autopeças.", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." }, { "name": "idhubproductautoparts", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do veículo compatível." } ], "responses": { "200": { "description": "Veículo removido.", "content": { "application/json": { "schema": { "type": "string", "example": "Sucesso" } } } }, "400": { "description": "`[BadRequest] - Autopartes anúncio não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/{idhubproduct}/offer": { "post": { "operationId": "hubProductOfferPost", "tags": [ "Hub — Anúncios" ], "summary": "Adiciona variação ao anúncio — Hub Anúncios", "description": "Adiciona uma variação (item) ao anúncio, vinculando um SKU. Aceita preço manual da variação (`PricingSet`), ficha técnica e ordem da variação. O preço da variação não pode coexistir com o preço a nível de anúncio.", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." }, { "name": "NoInvoke", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "`1` retorna apenas `\"sucesso\"` em vez do anúncio atualizado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductOfferCreate" } } }, "description": "Oferta (anúncio em variante de canal) a cadastrar para o produto. Cobre dados específicos da oferta — modalidade, preço, opções de envio. Estrutura completa em `HubProductOfferCreate`." }, "responses": { "200": { "description": "Anúncio atualizado (mesma estrutura do GET por id) ou `\"sucesso\"` quando `NoInvoke=1`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductDetail" } } } } }, "400": { "description": "`[BadRequest] - Anúncio não existe` · `[BadRequest] - Sku não existe` · `[BadRequest] - Este anúncio já tem este SKU` · `[BadRequest] - Este anúncio já tem este código de variação` · `[BadRequest] - Anúncio tem preço manual setado. Remover antes de atualizar o preço a nível de variação` · `[BadRequest] - Problema ao criar variação em anúncio`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/{idhubproduct}/offer/{idoffer}": { "get": { "operationId": "hubProductOfferGet", "tags": [ "Hub — Anúncios" ], "summary": "Detalha variação do anúncio — Hub Anúncios", "description": "Retorna o detalhe de uma variação (item) do anúncio: SKU vinculado, preços calculados, estoque, ficha técnica e imagens da variação. A resposta é um array com a variação correspondente.", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." }, { "name": "idoffer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da variação (`IDHubAdvertisement`)." } ], "responses": { "200": { "description": "Variação do anúncio (array com um objeto; vazio se não existir).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubSkuDetail" } } } } } } }, "put": { "operationId": "hubProductOfferPut", "tags": [ "Hub — Anúncios" ], "summary": "Atualiza variação do anúncio — Hub Anúncios", "description": "Atualiza uma variação (item) do anúncio (atualização parcial). Quando a atualização automática de preço está ativa e o canal aceita preço, alterar o preço manual (`PricingSet`) dispara o envio ao canal.", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." }, { "name": "idoffer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da variação (`IDHubAdvertisement`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductOfferUpdate" } } }, "description": "Atualização da oferta. Mesma estrutura do POST." }, "responses": { "200": { "description": "Anúncio atualizado (mesma estrutura do GET por id) ou `\"sucesso\"` quando `NoInvoke=1`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductDetail" } } } } }, "400": { "description": "`[BadRequest] - Anúncio não existe` · `[BadRequest] - Sku não existe` · `[BadRequest] - Já existe uma variação com este código` · `[BadRequest] - Anúncio tem preço manual setado. Remover antes de atualizar o preço a nível de variação`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubProductOfferDelete", "tags": [ "Hub — Anúncios" ], "summary": "Remove variação do anúncio — Hub Anúncios", "description": "Remove uma variação (item) do anúncio e comunica a remoção ao canal de forma assíncrona.", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." }, { "name": "idoffer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da variação (`IDHubAdvertisement`)." } ], "responses": { "200": { "description": "Anúncio atualizado (mesma estrutura do GET por id).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductDetail" } } } } }, "400": { "description": "`[BadRequest] - Variação não existe` · `[BadRequest] - Erro ao deletar`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/{idhubproduct}/quantity-pricing": { "post": { "operationId": "hubProductQuantityPricingPost", "tags": [ "Hub — Anúncios" ], "summary": "Adiciona preço por quantidade — Hub Anúncios", "description": "Adiciona uma faixa de preço por quantidade (desconto por volume) ao anúncio. Recurso do Mercado Livre, limitado a 5 faixas por anúncio; cada quantidade só pode aparecer uma vez.", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductQuantityPricingPayload" } } }, "description": "Faixa de preço por quantidade a cadastrar para o anúncio. Permite preço escalonado conforme a quantidade comprada." }, "responses": { "200": { "description": "Faixas de preço por quantidade do anúncio (todas).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductQuantityPricingItem" } } } } }, "400": { "description": "`[BadRequest] - Anúncio não existe` · `[BadRequest] - Quantidade precisa ser maior que zero` · `[BadRequest] - já existe preço para essa quantidade no anúncio` · `[BadRequest] - Anúncio não pode ter mais de 5 preços por quantidade`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/product/{idhubproduct}/quantity-pricing/{idhubproductquantitypricing}": { "put": { "operationId": "hubProductQuantityPricingPut", "tags": [ "Hub — Anúncios" ], "summary": "Atualiza preço por quantidade — Hub Anúncios", "description": "Atualiza uma faixa de preço por quantidade do anúncio.", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." }, { "name": "idhubproductquantitypricing", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da faixa de preço por quantidade." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubProductQuantityPricingPayload" } } }, "description": "Atualização da faixa de preço por quantidade. Mesma estrutura do POST." }, "responses": { "200": { "description": "Faixas de preço por quantidade do anúncio (todas).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductQuantityPricingItem" } } } } }, "400": { "description": "`[BadRequest] - Preço por quantidade do anúncio não existe` · `[BadRequest] - Quantidade precisa ser maior que zero` · `[BadRequest] - já existe preço para essa quantidade no anúncio`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubProductQuantityPricingDelete", "tags": [ "Hub — Anúncios" ], "summary": "Remove preço por quantidade — Hub Anúncios", "description": "Remove uma faixa de preço por quantidade do anúncio.", "parameters": [ { "name": "idhubproduct", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador interno do anúncio." }, { "name": "idhubproductquantitypricing", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da faixa de preço por quantidade." } ], "responses": { "200": { "description": "Faixa removida.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "`[BadRequest] - Preço por quantidade do anúncio não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/inventory-summary": { "get": { "operationId": "skuInventorySummaryList", "tags": [ "Inventário" ], "summary": "Lista inventários", "description": "Lista inventários da empresa, do mais recente para o mais antigo, paginada em blocos de 2000 (use `Page`). Os filtros são aplicados via query string. O filtro de **colaborador** considera o usuário em qualquer uma das três conferências.", "parameters": [ { "name": "Page", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Número da página (cada página tem 2000 registros). Quando omitido, vale `0`." }, { "name": "DateFrom", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Data inicial do intervalo (filtro pela criação do inventário, `RecordTimestamp`)." }, { "name": "DateTo", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Data final do intervalo. O sistema adiciona `23:59:59` ao valor." }, { "name": "IDStockKeepingUnitInventorySummary", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo código do inventário." }, { "name": "IDTypeStatusSkuInventory", "in": "query", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Status do inventário. Aceita lista separada por vírgula." }, { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "schema": { "type": "integer" }, "description": "Centro de distribuição." }, { "name": "IDStockKeepingUnitWarehouse", "in": "query", "schema": { "type": "integer" }, "description": "Armazém." }, { "name": "RecordUserStart", "in": "query", "schema": { "type": "integer" }, "description": "Colaborador atribuído (busca em qualquer uma das três conferências)." } ], "responses": { "200": { "description": "Lista de inventários.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventorySummaryListItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuInventorySummaryPost", "tags": [ "Inventário" ], "summary": "Cria inventário", "description": "Cria um novo inventário no status `2` (Aberto). Valida a existência do armazém ativo (deve pertencer à empresa), do tipo de inventário e do centro de distribuição. Após o INSERT, invoca internamente o sistema de leitura e devolve o inventário completo.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySummaryCreate" } } }, "description": "Abertura de um inventário. Informe `IDStockKeepingUnitWarehouse` (depósito a inventariar), `IDTypeInventorySummary` (modo: `1` Endereço, `2` SKU, `3` Livre, `4` Auditoria), `IDTypeQuantity` (política de fechamento dos saldos) e `InventoryDescription` (identificação livre)." }, "responses": { "200": { "description": "Inventário criado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventorySummaryDetail" } } } } }, "400": { "description": "`[BadRequest] - Empresa não existe`, `Armazém não localizado`, `Armazém deve ser informado`, `Tipo inventário não existe`, `Centro de distribuição não existe`, `Tipo quantidade (contagem) inventário não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/inventory-summary/{idstockkeepingunitinventorysummary}": { "parameters": [ { "name": "idstockkeepingunitinventorysummary", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Código do inventário." } ], "get": { "operationId": "skuInventorySummaryGet", "tags": [ "Inventário" ], "summary": "Detalha inventário", "description": "Retorna o inventário completo com os itens contados (`Items`), a fila de SKUs (`StockKeepingUnitInventorySummarySkuQueue`) e a fila de endereços (`StockKeepingUnitInventorySummaryLocationQueue`). Os itens trazem `QuantityInventoryDiff`/`Second`/`Third` calculados em relação ao saldo do lote. Endereços com coordenadas (`Floor`, `Street`, `Module`...) são ordenados por trajeto serpentino para otimizar a separação.", "parameters": [ { "name": "Draft", "in": "query", "schema": { "type": "integer", "enum": [ 1 ] }, "description": "Quando `1`, devolve o **rascunho** salvo (TTL 4 dias) em vez de consultar o banco." } ], "responses": { "200": { "description": "Inventário ou lista vazia (`[]`) quando não localizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventorySummaryDetail" } } } } } } }, "put": { "operationId": "skuInventorySummaryPut", "tags": [ "Inventário" ], "summary": "Atualiza inventário", "description": "Atualiza o cabeçalho do inventário. Usado para:\n\n- **Encerrar uma conferência** — `IDTypeStatusSkuInventory = 6` finaliza a 1ª, `7` finaliza a 2ª, `8` finaliza a 3ª. Cada transição grava o timestamp correspondente. Tentar repetir uma finalização já feita retorna erro.\n- **Atribuir colaborador** — `InventoryStartUser` só é aceito quando o status `< 6`; `InventorySecondUserStart` só quando o status `= 6`; `InventoryThirdUserStart` só quando o status `= 7`. O usuário precisa estar ativo (`Status = 1`) na empresa.\n\nAo finalizar a **1ª conferência** de um inventário do tipo Auditoria (`IDTypeInventorySummary = 4`), o sistema inclui automaticamente, com quantidade `0`, todos os lotes do armazém que estavam com saldo e ainda não foram contados — opcionalmente compensando saldos negativos quando `IDTypeQuantity = 3`.\n\nNão é possível atualizar inventários `Finalizados` (`1`) ou `Cancelados` (`4`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySummaryUpdate" } } }, "description": "Atualiza dados gerais do inventário (descrição, política de quantidade, status)." }, "responses": { "200": { "description": "Inventário atualizado (mesmo formato de `GET /sku/inventory-summary/{id}`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventorySummaryDetail" } } } } }, "400": { "description": "`[BadRequest] - Inventário não existe`, `Inventário já esta finalizado`, `Inventário esta cancelado`, `Inventário não pode ter a primeira/segunda/terceira conferência finalizada novamente`, `Colaborador primeira/segunda/terceira conferência não existe`, `Precisa finalizar a primeira conferência antes de definir o colaborador da segunda`, `Precisa finalizar a segunda conferência antes de definir o colaborador da terceira`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuInventorySummaryDelete", "tags": [ "Inventário" ], "summary": "Cancela inventário", "description": "Marca o inventário como Cancelado (`IDTypeStatusSkuInventory = 4`). Não dispara ajuste de estoque. Inventários já Finalizados (`1`) não podem ser cancelados.", "responses": { "200": { "description": "Cancelamento bem-sucedido. Retorna a string `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "`[BadRequest] - Inventário não existe`, `Inventário já esta finalizado`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/inventory-summary/{idstockkeepingunitinventorysummary}/finish": { "parameters": [ { "name": "idstockkeepingunitinventorysummary", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Código do inventário." } ], "post": { "operationId": "skuInventorySummaryFinishPost", "tags": [ "Inventário" ], "summary": "Finaliza inventário e gera os ajustes de estoque", "description": "Fecha o inventário gerando os ajustes de saldo: para cada SKU/lote contado, compara a `QuantityInventory` (ou a última conferência disponível) com a `QuantityBatch` e cria uma entrada (`IDTypeMovement=0`) ou saída (`IDTypeMovement=1`) em `StockKeepingUnitMovement`. Cada movimentação dispara um webhook `SkuBalanceInventoryFinish` na fila assíncrona configurada.\n\n**Inventário do tipo Endereço** — antes do ajuste, o sistema inclui automaticamente, com quantidade `0`, os lotes dos endereços que estavam na fila de contagem mas não foram lançados.\n\n**Custo aplicado** — o custo médio do SKU naquele armazém (`InventoryValue / QtyAvailable`); quando zero, usa `CostLastPurchase` do SKU. Quando o parâmetro `UseCostFromCostSet` está ativo na empresa, o sistema usa o **Custo Manual** (`CostSet`) cadastrado no SKU.\n\nDurante o processamento, o status passa a `5` (Processando) e, ao concluir, vai para `1` (Finalizado) gravando `InventoryFinishTimestamp` com o momento da finalização.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Corpo opcional — o sistema aceita `IDStockKeepingUnitWarehouse` e `InventoryDescription` por compatibilidade, mas os valores efetivos vêm sempre do cadastro do inventário." } } }, "description": "Finaliza o inventário — efetiva os ajustes de estoque calculados pela contagem (entradas e saídas). O corpo geralmente é vazio; o sistema usa o estado das contagens registradas." }, "responses": { "200": { "description": "Finalização bem-sucedida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryFinishResult" } } } }, "400": { "description": "`[BadRequest] - inventário não localizado para finalizar`, `inventário não tem itens`, `Status inventário não permite finalizar`, `Lote do item {IDSkuCompany} está inativo`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/inventory-summary/{idstockkeepingunitinventorysummary}/sku": { "parameters": [ { "name": "idstockkeepingunitinventorysummary", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Código do inventário." } ], "post": { "operationId": "skuInventorySummarySkuPost", "tags": [ "Inventário" ], "summary": "Adiciona SKU/endereço à fila ou lança contagem", "description": "Endpoint multi-uso, controlado pela query string:\n\n- `IDTypeQueue=1` — adiciona endereços na **fila de contagem** (`StockKeepingUnitInventorySummaryLocationQueue`). Quando `AddAllLocations=1`, inclui automaticamente todos os endereços do armazém com saldo de lote diferente de zero.\n- `IDTypeQueue=2` — adiciona SKUs na **fila de contagem** (`StockKeepingUnitInventorySummarySkuQueue`). Quando `AddAllSkus=1`, inclui todos os SKUs ativos da empresa com saldo de lote no centro de distribuição.\n- **Sem `IDTypeQueue`** — lança a **quantidade contada** de um SKU. Quando o body é um objeto único contendo `IDStockKeepingUnitLocation`, itens não enviados desse endereço são automaticamente zerados (uso pelo WMS de coletor).\n\n`IDTypeQuantity` (query) altera a estratégia de cálculo do saldo de referência. `Draft=1` salva o body como rascunho temporário (TTL 4 dias) em vez de persistir.\n\nAo receber a primeira contagem, o sistema atribui o usuário autenticado como `InventoryStartUser` e muda o status para `3` (Em andamento). Lançamentos de `QuantityInventorySecond` ou `QuantityInventoryThird` mudam o status para `9` ou `10` (Processando 2ª/3ª conf.).", "parameters": [ { "name": "IDTypeQueue", "in": "query", "schema": { "$ref": "#/components/schemas/IDTypeQueueEnum" }, "description": "Tipo de item da fila. Omita para lançamento de contagem." }, { "name": "AddAllLocations", "in": "query", "schema": { "type": "integer", "enum": [ 1 ] }, "description": "Junto com `IDTypeQueue=1`, adiciona automaticamente todos os endereços do armazém com saldo." }, { "name": "AddAllSkus", "in": "query", "schema": { "type": "integer", "enum": [ 1 ] }, "description": "Junto com `IDTypeQueue=2`, adiciona automaticamente todos os SKUs ativos da empresa com saldo." }, { "name": "IDTypeQuantity", "in": "query", "schema": { "$ref": "#/components/schemas/TypeInventorySummaryQuantityEnum" }, "description": "Sobrescreve a estratégia de quantidade do cadastro do inventário." }, { "name": "IDStockKeepingUnitLocation", "in": "query", "schema": { "type": "integer" }, "description": "Quando informado sem `IDTypeQueue`, o sistema considera que a contagem é por endereço e zera os SKUs deste endereço que não vieram no body." }, { "name": "Draft", "in": "query", "schema": { "type": "integer", "enum": [ 1 ] }, "description": "Quando `1`, salva o body como rascunho temporário (TTL 4 dias) em vez de persistir." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySkuQueueAdd" } } }, "description": "Enfileira um SKU para contagem dentro do inventário (modo `SKU` ou `Livre`)." }, "responses": { "200": { "description": "Lista atualizada de itens contados do inventário (mesmo formato dos `Items` do detalhe). Quando o body é array e ocorrem erros parciais, devolve a lista de erros.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/InventoryItemDetail" } }, { "type": "array", "items": { "$ref": "#/components/schemas/InventoryQueueAddError" } } ] } } } }, "400": { "description": "`[BadRequest] - Inventário não existe`, `Inventário já esta finalizado`, `Inventário esta cancelado`, `Sku não existe`, `Endereço não existe para armazém`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuInventorySummaryQueueDelete", "tags": [ "Inventário" ], "summary": "Remove item da fila", "description": "Remove um SKU ou um endereço da fila de contagem. É obrigatório enviar **uma** das duas query strings:\n\n- `IDStockKeepingUnitInventorySummarySkuQueue` — código do SKU na fila (remove de `StockKeepingUnitInventorySummarySkuQueue`).\n- `IDStockKeepingUnitInventorySummaryLocationQueue` — código do endereço na fila (remove de `StockKeepingUnitInventorySummaryLocationQueue`).", "parameters": [ { "name": "IDStockKeepingUnitInventorySummarySkuQueue", "in": "query", "schema": { "type": "integer" }, "description": "Código do SKU na fila." }, { "name": "IDStockKeepingUnitInventorySummaryLocationQueue", "in": "query", "schema": { "type": "integer" }, "description": "Código do endereço na fila." } ], "responses": { "200": { "description": "Remoção bem-sucedida. Retorna a string `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "`[BadRequest] - Inventário não encontrado`, `Inventário já esta finalizado`, `Inventário esta cancelado`, `Erro ao deletar item a ser inventariado`, `Erro ao deletar endereço a ser inventariado`, `Precisa ser enviado o endereço ou o item a ser inventariado para deletar`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/inventory-summary/{idstockkeepingunitinventorysummary}/sku/{idstockkeepingunitinventoryitems}": { "parameters": [ { "name": "idstockkeepingunitinventorysummary", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Código do inventário." }, { "name": "idstockkeepingunitinventoryitems", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Código do item contado dentro do inventário." } ], "put": { "operationId": "skuInventorySummarySkuPut", "tags": [ "Inventário" ], "summary": "Atualiza a quantidade lançada de um item", "description": "Atualiza a quantidade contada de um item já existente na lista de itens. O sistema escolhe a conferência ativa pelo status atual do inventário: status `3` (Em andamento) → grava `QuantityInventory`; status `6` ou `9` → grava `QuantityInventorySecond`; status `7` ou `10` → grava `QuantityInventoryThird`. Campos das demais conferências são ignorados.\n\nQuando `QuantityInventorySecond` (ou `Third`) é enviado e a conferência correspondente ainda não foi iniciada (sem `Timestamp`), o sistema atribui o usuário autenticado como colaborador da rodada e muda o status do inventário para Processando 2ª/3ª.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryItemUpdate" } } }, "description": "Atualiza a contagem do item do inventário (quantidade contada e observações)." }, "responses": { "200": { "description": "Item atualizado, com os dados consolidados do SKU + lote + endereço.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryItemDetail" } } } } }, "400": { "description": "`[BadRequest] - Sku inventário não encontrado`, `Inventário já esta finalizado`, `Inventário esta cancelado`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuInventorySummarySkuDelete", "tags": [ "Inventário" ], "summary": "Remove item contado", "description": "Remove uma linha de item já lançada na contagem (`StockKeepingUnitInventoryItems`). Não é possível remover quando o inventário está Finalizado (`1`) ou Cancelado (`4`).", "responses": { "200": { "description": "Remoção bem-sucedida. Retorna a string `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "`[BadRequest] - Sku inventário não encontrado`, `Inventário já esta finalizado`, `Inventário esta cancelado`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/inventory": { "get": { "operationId": "skuInventoryList", "tags": [ "Inventário (Legacy)" ], "summary": "Lista histórico de ajustes", "description": "Lista os ajustes de saldo lançados pela tela **Inventário** (`/app/inventory`) — uma linha por ajuste, com SKU, lote, armazém, quantidade contada, comentário, usuário e data. Paginada em blocos de 2000 (`Page`).", "parameters": [ { "name": "Page", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Número da página (cada página tem 2000 registros). Default `0`." }, { "name": "DateFrom", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Data inicial do intervalo (criação do ajuste)." }, { "name": "DateTo", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Data final do intervalo. O sistema adiciona `23:59:59` ao valor." }, { "name": "IDSku", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo código interno do SKU." }, { "name": "SkuName", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo nome do SKU (busca parcial)." }, { "name": "Barcode", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo código de barras principal." }, { "name": "IDSkuCompany", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo código de referência do SKU na empresa (busca parcial)." }, { "name": "Search", "in": "query", "schema": { "type": "string" }, "description": "Busca rápida — procura simultaneamente em `IDSku`, `SkuName`, `BarCode` e `IDSkuCompany`. Espaços viram `%` (LIKE)." } ], "responses": { "200": { "description": "Lista de ajustes.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryHistoryItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "skuInventoryPost", "tags": [ "Inventário (Legacy)" ], "summary": "Lança ajustes de saldo", "description": "Lança um array de ajustes de saldo. O sistema processa **item por item**, criando uma movimentação de estoque (`StockKeepingUnitMovement`) para cada item válido e um registro de ajuste (`StockKeepingUnitInventory`) apontando para ela. Para cada movimentação, dispara uma notificação `SkuBalanceAdjust` para o webhook.\n\n**Cálculo da diferença**:\n\n- Quando `IDMovementType = 0` ou `1`, força a direção e usa `QuantityInventory` como `Quantity` da movimentação.\n- Quando `IDMovementType = 3`, compara `QuantityInventory` contra o saldo disponível atual do SKU (`QtyAvailable`) e cria movimentação pela diferença.\n- Quando `IDMovementType` é omitido, compara `QuantityInventory` contra o saldo do **lote** (soma das movimentações do lote) e cria movimentação pela diferença.\n\n**Custo aplicado**: `CostSet` (custo manual) quando `UseCostFromCostSet = 1`; caso contrário, `CostAverage` apurado pelo balanço; quando o custo médio é zero, `CostLastPurchase` do SKU.\n\n**Auto-criação de lote**: quando o SKU não tem lote no armazém, o sistema cria automaticamente um lote no primeiro endereço (`Default = 1`) — quando não há endereço, cria um endereço `Principal` antes.\n\n**Erros parciais**: itens inválidos não interrompem o processamento — são acumulados em `tempError` e devolvidos no array de resposta.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryAdjustmentItem" } } } }, "description": "Ajuste avulso de estoque (entrada ou saída) sem passar por inventário fechado. Schema não detalhado nesta versão — confira o sistema `skuInventoryPost` para o contrato exato." }, "responses": { "200": { "description": "Resposta. Quando todos os itens foram processados com sucesso, devolve um array vazio. Quando há erros parciais, devolve a lista de falhas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryAdjustmentError" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/balance": { "get": { "operationId": "skuWareHouseBalanceList", "tags": [ "Saldo de Estoque" ], "summary": "Lista saldo consolidado por armazém + SKU", "description": "Lista o saldo consolidado de cada SKU em cada armazém, com colunas de quantidade nas várias situações (disponível, reservada, em produção, em manuseio, em pedido de compra, em recebimento) e valor calculado pelo custo médio (ou pelo custo manual, conforme o parâmetro `UseCostFromCostSet`). Paginada em blocos de 400 (`Page`).\n\nA chave `IDStockKeepingUnitWarehouseBalance` é uma string composta `{IDStockKeepingUnitWarehouse}-{IDSku}` gerada pelo sistema — não existe em banco.\n\nO filtro `SinceDateLastRecordModification` é útil para integrações: devolve apenas linhas que tiveram movimentação após a data informada.", "parameters": [ { "name": "Page", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Número da página (cada página tem 400 registros). Default `0`." }, { "name": "IDSku", "in": "query", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Filtra pelo código interno do SKU. Aceita lista separada por vírgula." }, { "name": "SkuName", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo nome (busca parcial)." }, { "name": "BarCode", "in": "query", "schema": { "type": "string" }, "description": "Código de barras principal." }, { "name": "IDSkuCompany", "in": "query", "schema": { "type": "string" }, "description": "Código de referência do SKU na empresa (busca parcial)." }, { "name": "IDTypeSku", "in": "query", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Tipo de SKU, lista separada por vírgula. Valores: `1` Clube, `2` Kit, `3` Sku, `4` Produto, `5` Serviço, `6` Matéria-prima, `7` Uso e consumo, `8` Caixa." }, { "name": "IDBrand", "in": "query", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Marca. Aceita lista separada por vírgula." }, { "name": "IDSupplier", "in": "query", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Fornecedor vinculado ao SKU. Aceita lista separada por vírgula." }, { "name": "SupplierCode", "in": "query", "schema": { "type": "string" }, "description": "Código que o fornecedor usa para identificar o produto." }, { "name": "Package", "in": "query", "schema": { "type": "string" }, "description": "Embalagem (`Package`) do SKU." }, { "name": "IDStockKeepingUnitWarehouse", "in": "query", "schema": { "type": "integer" }, "description": "Armazém específico." }, { "name": "IDTypeStockKeepingUnitWarehouse", "in": "query", "schema": { "$ref": "#/components/schemas/TypeStockKeepingUnitWarehouseEnum" }, "description": "Tipo de armazém." }, { "name": "IDStatusSku", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ] } }, "description": "Status do SKU, lista separada por vírgula: `0` Deletado, `1` Ativo, `2` Compra suspensa, `3` Inativo, `4` Venda suspensa. Default `1,2,3,4` (todos exceto deletados).", "style": "form", "explode": false }, { "name": "IDCompanyIntegration", "in": "query", "schema": { "type": "integer" }, "description": "Filtra SKUs que **têm** anúncio na integração informada." }, { "name": "IDCompanyIntegrationNot", "in": "query", "schema": { "type": "integer" }, "description": "Filtra SKUs que **não têm** anúncio na integração informada — usado para descobrir produtos pendentes de anúncio." }, { "name": "IDTypeCompanyIntegration", "in": "query", "schema": { "type": "integer" }, "description": "Filtra SKUs com anúncio em alguma integração do **tipo** informado (ex.: marketplace, ERP)." }, { "name": "IDTypeCompanyIntegrationNot", "in": "query", "schema": { "type": "integer" }, "description": "Filtra SKUs **sem** anúncio em integrações do tipo informado." }, { "name": "SinceDateLastRecordModification", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Devolve apenas SKUs que tiveram movimentação após a data informada (útil para integrações incrementais)." }, { "name": "Search", "in": "query", "schema": { "type": "string" }, "description": "Busca rápida — procura simultaneamente em `IDSku`, `SkuName`, `BarCode` e `IDSkuCompany`." } ], "responses": { "200": { "description": "Saldos consolidados. Lista vazia (`[]`) quando não há resultados.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StockBalanceItem" } } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/supplier": { "get": { "operationId": "skuSupplierList", "tags": [ "Fornecedores ↔ SKUs" ], "summary": "Lista vínculos SKU-fornecedor", "description": "Lista a visão consolidada de produtos e seus fornecedores na conta autenticada, com os dados do produto somados aos do vínculo. Os filtros são combinados por `AND`; `Search` busca por código do produto, nome, código de barras e código de referência (combinados por `OR`). A resposta é paginada em blocos de 5000 registros via `Page`.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página da listagem (cada página traz até 5000 registros)." }, { "name": "Search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca textual por código do produto, nome, código de barras e código de referência." }, { "name": "IDSku", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por identificador do produto." }, { "name": "SkuName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por nome do produto." }, { "name": "BarCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por código de barras." }, { "name": "IDSkuCompany", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por código de referência (parcial)." }, { "name": "IDBrand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por marca." }, { "name": "IDCategory", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por categoria." }, { "name": "SupplierCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por código do fornecedor (parcial)." }, { "name": "IDSupplier", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por fornecedor." }, { "name": "Package", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por indicador de embalagem." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra produtos anunciados em uma integração específica." }, { "name": "IDCompanyIntegrationNot", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra produtos NÃO anunciados em uma integração específica." }, { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra produtos anunciados em um tipo de canal de vendas." }, { "name": "IDTypeCompanyIntegrationNot", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra produtos NÃO anunciados em um tipo de canal de vendas." } ], "responses": { "200": { "description": "Lista de vínculos SKU-fornecedor.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSupplierListItem" } } } } } } } }, "/sku/supplier/{idsku}": { "get": { "operationId": "skuSupplierGet", "tags": [ "Fornecedores ↔ SKUs" ], "summary": "Lista fornecedores de um SKU", "description": "Retorna os fornecedores vinculados a um produto. Informe `IDStockKeepingUnitSuplierCode` para restringir a um vínculo específico.", "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto (SKU)." }, { "name": "IDStockKeepingUnitSuplierCode", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Restringe a resposta a um vínculo específico." } ], "responses": { "200": { "description": "Fornecedores do produto.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSupplierLink" } } } } } } }, "post": { "operationId": "skuSupplierPost", "tags": [ "Fornecedores ↔ SKUs" ], "summary": "Vincula fornecedor ao SKU", "description": "Cria um vínculo entre o produto e um fornecedor. Após inserir, reinvoca `skuSupplierGet` e devolve a lista de fornecedores do produto.", "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto (SKU)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuSupplierCreate" } } }, "description": "Vincula um fornecedor ao SKU com o código do SKU no catálogo do fornecedor, tamanho da embalagem e múltiplo de compra." }, "responses": { "200": { "description": "Fornecedores do produto após a inclusão.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSupplierLink" } } } } }, "400": { "description": "`[BadRequest] - Sku não existe`, `[BadRequest] - Fornecedor não existe` ou `[BadRequest] - Código e fornecedor já estão cadastrados`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku/supplier/{idsku}/{idstockkeepingunitsupliercode}": { "put": { "operationId": "skuSupplierPut", "tags": [ "Fornecedores ↔ SKUs" ], "summary": "Atualiza vínculo de fornecedor", "description": "Atualiza um vínculo SKU-fornecedor existente. Após salvar, reinvoca `skuSupplierGet` e devolve a lista de fornecedores do produto.", "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto (SKU)." }, { "name": "idstockkeepingunitsupliercode", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do vínculo a atualizar." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuSupplierUpdate" } } }, "description": "Atualiza o vínculo SKU↔fornecedor." }, "responses": { "200": { "description": "Fornecedores do produto após a atualização.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSupplierLink" } } } } }, "400": { "description": "`[BadRequest] - Fornecedor SKU não existe`, `[BadRequest] - Fornecedor não existe` ou `[BadRequest] - Código e fornecedor já estão cadastrados`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "skuSupplierDelete", "tags": [ "Fornecedores ↔ SKUs" ], "summary": "Remove vínculo de fornecedor", "description": "Remove o vínculo entre o produto e o fornecedor. O produto e o fornecedor continuam cadastrados. Após excluir, reinvoca `skuSupplierGet` e devolve os fornecedores restantes do produto.", "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto (SKU)." }, { "name": "idstockkeepingunitsupliercode", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do vínculo a remover." } ], "responses": { "200": { "description": "Fornecedores restantes do produto.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSupplierLink" } } } } }, "400": { "description": "`[BadRequest] - Sku não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user": { "get": { "operationId": "UserList", "tags": [ "Cadastro de Usuários" ], "summary": "Lista os usuários da empresa", "description": "Retorna os usuários vinculados à empresa autenticada, com o(s) perfil(is) de acesso agregados em `Privileges`, o último login (`LastLogin`), flags de vendedor e o status do vínculo. Por padrão lista apenas usuários **ativos**; use `AllStatus=1` para incluir inativos.\n\nQuando `Comission=1`, a operação muda de comportamento: em vez da lista de cadastro, calcula e devolve a **apuração de comissões** dos vendedores no período (`DateFrom`/`DateTo` por data do pedido, ou `InvoiceDateFrom`/`InvoiceDateTo` por data de faturamento), respeitando as regras de cada vendedor.", "parameters": [ { "name": "AllStatus", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "1 = inclui usuários inativos na listagem; ausente/0 = só ativos." }, { "name": "Salesman", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra apenas vendedores (1) ou não-vendedores (0)." }, { "name": "Technician", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Filtra apenas técnicos (1)." }, { "name": "IDUserJobPosition", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "description": "Filtra por cargo (uma das posições em `UserJobPositionList`)." }, { "name": "Comission", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "1 = retorna a apuração de comissões dos vendedores no período em vez da lista de cadastro." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Início do período (data do pedido) — usado com `Comission=1`." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do período (data do pedido) — usado com `Comission=1`." }, { "name": "InvoiceDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Início do período por data de faturamento — usado com `Comission=1`." }, { "name": "InvoiceDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Fim do período por data de faturamento — usado com `Comission=1`." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "description": "Restringe a apuração de comissão a uma empresa/filial faturadora." } ], "responses": { "200": { "description": "Lista de usuários da empresa (ou apuração de comissões quando `Comission=1`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserListItem" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "UserPost", "tags": [ "Cadastro de Usuários" ], "summary": "Cria um usuário", "description": "Cadastra um usuário na empresa autenticada. É obrigatório informar `UserName` e pelo menos um identificador de login: `Login` (e-mail) **ou** `UserCpfCnpj`. Quando só o documento é enviado, o sistema gera um login interno no formato `@email.com.br`. Quando um e-mail real é informado, um e-mail de boas-vindas é enviado.\n\nSe já existir um registro de pessoa com o mesmo `Login`/`UserCpfCnpj` em outra conta (ou desvinculado), o cadastro **reaproveita e revincula** esse registro à empresa atual em vez de duplicar. `Login` e `UserCpfCnpj` precisam ser únicos dentro da empresa.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCreate" } } }, "description": "Usuário a cadastrar na empresa autenticada. `UserName` é obrigatório e pelo menos um de `Login` (email) ou `UserCpfCnpj` precisa ser informado. Quando só o documento é enviado, o sistema gera um login interno `@email.com.br`. Se já existe pessoa com o mesmo `Login`/`UserCpfCnpj` desvinculada ou em outra empresa, o cadastro reaproveita e revincula em vez de duplicar." }, "responses": { "200": { "description": "Usuário criado. Quando o login foi gerado a partir do documento, retorna a string `\"sucesso\"`. Quando um e-mail real foi informado, retorna o detalhe completo do usuário (mesmo formato de `GET /user/{iduser}`).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "string", "example": "sucesso" }, { "type": "array", "items": { "$ref": "#/components/schemas/UserDetail" }, "maxItems": 1 } ] } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Cpf / Cnpj inválido, verificar os números digitados`\n- `Email inválido, verificar`\n- `Tipo de MFA inválido`\n- `Tipo de comissão não existe`\n- `Documento obrigatório quando não é informado`\n- `Documento e/ou email obrigatório para cadastrar usuário`\n- `Email já esta vinculado a outro usuário`\n- `Documento já esta vinculado a outro usuário`\n- `Empresa não existe`\n- `Problema ao criar usuário`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/{iduser}": { "parameters": [ { "name": "iduser", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do usuário." } ], "get": { "operationId": "UserGet", "tags": [ "Cadastro de Usuários" ], "summary": "Detalha um usuário", "description": "Retorna o cadastro completo do usuário na empresa: dados pessoais, flags de vendedor e comissão, cargos (`UserJobPositionList`), perfis de acesso (`UserPrivilegeGroup`), regras de comissão (`SalesmanComission`), vínculos de empresa/filial faturadora (`UserCompanyInvoice`), centros de distribuição (`UserCompanyDistributionCenter`), categorias de fornecedor (`UserCompanySupplierCategory`) e a auditoria de alterações (`UserLog`) e de acessos (`LoginLog`).\n\nPor padrão considera apenas o vínculo **ativo** (`status=1`); informe `status` na query para buscar por outro status. Quando não há vínculo no status pedido, retorna um array vazio (`[]`) com status 200.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Status do vínculo a buscar (1 = ativo, padrão; 0 = inativo)." } ], "responses": { "200": { "description": "Detalhe do usuário (array com 1 item) ou `[]` quando não há vínculo no status pedido.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserDetail" }, "maxItems": 1 } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "put": { "operationId": "UserPut", "tags": [ "Cadastro de Usuários" ], "summary": "Atualiza um usuário", "description": "Atualiza os dados do usuário na empresa. A atualização é **parcial** — apenas os campos enviados são alterados.\n\nQuando `Password` é enviado, a senha é validada contra a política da empresa (comprimento mínimo, complexidade, não repetir as 5 últimas senhas e validade). Alterar a senha de **outro** usuário exige o privilégio de redefinir senha; alterar a própria, não. Mudanças de campos são registradas em `UserLog` (valores DE/PARA).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdate" } } }, "description": "Atualização parcial do usuário — só os campos enviados são alterados. Quando `Password` é enviado, é validado contra a política da empresa (tamanho, complexidade, histórico das 5 últimas e validade). Trocar a senha de outro usuário exige privilégio de redefinir senha; trocar a própria, não. Mudanças são registradas em log com os valores de antes e depois." }, "responses": { "200": { "description": "Usuário atualizado. Retorna o detalhe completo (mesmo formato de `GET /user/{iduser}`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `A lista de cargos do usuário deve conter apenas IDs separados por vírgula`\n- `Cpf / Cnpj inválido, verificar os números digitados`\n- `Email inválido, verificar`\n- `Tipo de MFA inválido`\n- `Tipo de comissão não existe`\n- `Documento obrigatório quando não é informado`\n- `Documento e/ou email obrigatório para cadastrar usuário`\n- `A senha deve ter no mínimo N caracteres`\n- `A senha deve conter letras maiúsculas, minúsculas, números e caracteres especiais`\n- `Usuário não tem privilégio para resetar senha`\n- `A senha informada deve ser diferente das 5 últimas senhas utilizadas`\n- `Email já esta vinculado a outro usuário`\n- `Documento já esta vinculado a outro usuário`\n- `Usuário não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "UserDelete", "tags": [ "Cadastro de Usuários" ], "summary": "Remove o usuário da empresa", "description": "Remove o vínculo do usuário com a empresa autenticada (apaga o `UserCompany` e os perfis de acesso daquela empresa). O registro global da pessoa (`User`) **persiste** se ela ainda estiver vinculada a outra conta — assim o histórico e o login em outras empresas são preservados.", "responses": { "200": { "description": "Vínculo removido. Retorna o detalhe do usuário atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserDetail" }, "maxItems": 1 } } } }, "400": { "description": "Mensagem: `[BadRequest] - Usuário não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/{iduser}/privilege/privilege-group": { "parameters": [ { "name": "iduser", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do usuário." } ], "get": { "operationId": "iduserPrivilegeGroupGet", "tags": [ "Cadastro de Usuários" ], "summary": "Lista os perfis de acesso do usuário", "description": "Retorna os perfis de acesso (grupos de privilégio) atualmente vinculados ao usuário na empresa autenticada.", "responses": { "200": { "description": "Perfis de acesso vinculados ao usuário.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserPrivilegeGroupRef" } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "iduserPrivilegeGroupPost", "tags": [ "Cadastro de Usuários" ], "summary": "Substitui os perfis de acesso do usuário", "description": "Redefine, de uma vez, o conjunto de perfis de acesso do usuário: o corpo é a **lista completa** de identificadores de perfil (`IDUserPrivilegeGroup`) que o usuário deve passar a ter. Cada identificador é validado contra os perfis da empresa; os vínculos anteriores são apagados e os novos inseridos, e a operação é registrada em log.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "Lista de identificadores de perfil de acesso a vincular ao usuário.", "items": { "type": "integer", "format": "int32" }, "example": [ 12, 15 ] } } }, "description": "Array de identificadores de perfil de acesso (`IDUserPrivilegeGroup`) que o usuário deve passar a ter. Sobrescreve a lista existente — vínculos anteriores são apagados e os novos inseridos. Cada id é validado contra os perfis da empresa." }, "responses": { "200": { "description": "Perfis atualizados. Retorna o detalhe completo do usuário.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Privilegio não encontrado` (um dos IDs não pertence à empresa)\n- `User não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/{iduser}/company-invoice": { "parameters": [ { "name": "iduser", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do usuário." } ], "post": { "operationId": "userCompanyInvoicePost", "tags": [ "Cadastro de Usuários" ], "summary": "Vincula uma empresa/filial faturadora ao usuário", "description": "Adiciona ao usuário o acesso a uma empresa/filial faturadora (`IDCompany`). Define em quais filiais emitentes o usuário pode operar.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCompanyInvoiceCreate" } } }, "description": "Vínculo a cadastrar. `IDCompany` (identificador da empresa/filial faturadora) é obrigatório. Define em quais filiais emitentes o usuário pode operar." }, "responses": { "200": { "description": "Vínculo criado. Retorna o detalhe completo do usuário.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Empresa não existe`\n- `Usuário não encontrado`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/{iduser}/company-invoice/{idusercompanyinvoice}": { "parameters": [ { "name": "iduser", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do usuário." }, { "name": "idusercompanyinvoice", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do vínculo de empresa/filial faturadora." } ], "delete": { "operationId": "userCompanyInvoiceDelete", "tags": [ "Cadastro de Usuários" ], "summary": "Remove o vínculo de empresa/filial faturadora", "description": "Desfaz o acesso do usuário a uma empresa/filial faturadora. A operação é registrada em log.", "responses": { "200": { "description": "Vínculo removido. Retorna o detalhe completo do usuário.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserDetail" }, "maxItems": 1 } } } }, "400": { "description": "Mensagem: `[BadRequest] - Empresa não localizada no cadastro do usuário`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/{iduser}/distribution-center": { "parameters": [ { "name": "iduser", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do usuário." } ], "post": { "operationId": "userCompanyDistributionCenterPost", "tags": [ "Cadastro de Usuários" ], "summary": "Vincula um centro de distribuição ao usuário", "description": "Adiciona ao usuário o acesso a um centro de distribuição (`IDStockKeepingUnitDistributionCenter`). Restringe os CDs cujo estoque o usuário pode operar.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDistributionCenterCreate" } } }, "description": "Vínculo a cadastrar. `IDStockKeepingUnitDistributionCenter` (identificador do centro de distribuição) é obrigatório. Restringe os CDs cujo estoque o usuário pode operar." }, "responses": { "200": { "description": "Vínculo criado. Retorna o detalhe completo do usuário.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Centro de distribuição não existe`\n- `Usuário não encontrado`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/{iduser}/distribution-center/{idusercompanydistributioncenter}": { "parameters": [ { "name": "iduser", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do usuário." }, { "name": "idusercompanydistributioncenter", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do vínculo de centro de distribuição." } ], "delete": { "operationId": "userCompanyDistributionCenterDelete", "tags": [ "Cadastro de Usuários" ], "summary": "Remove o vínculo de centro de distribuição", "description": "Desfaz o acesso do usuário a um centro de distribuição. A operação é registrada em log.", "responses": { "200": { "description": "Vínculo removido. Retorna o detalhe completo do usuário.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserDetail" }, "maxItems": 1 } } } }, "400": { "description": "Mensagem: `[BadRequest] - Empresa não localizada no cadastro do usuário`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/{iduser}/supplier-category": { "parameters": [ { "name": "iduser", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do usuário." } ], "post": { "operationId": "userSupplierCategoryPost", "tags": [ "Cadastro de Usuários" ], "summary": "Vincula uma categoria de fornecedor ao usuário", "description": "Adiciona ao usuário o acesso a uma categoria de fornecedor (`IDSupplierCategory`). Restringe quais categorias de fornecedor o usuário enxerga/opera.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSupplierCategoryCreate" } } }, "description": "Vínculo a cadastrar. `IDSupplierCategory` (identificador da categoria de fornecedor) é obrigatório. Restringe os fornecedores que o usuário pode operar a essa categoria." }, "responses": { "200": { "description": "Vínculo criado. Retorna o detalhe completo do usuário.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserDetail" }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Categoria fornecedor não existe`\n- `Usuário não encontrado`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/{iduser}/supplier-category/{idusersuppliercategory}": { "parameters": [ { "name": "iduser", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do usuário." }, { "name": "idusersuppliercategory", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do vínculo de categoria de fornecedor." } ], "delete": { "operationId": "userSupplierCategoryDelete", "tags": [ "Cadastro de Usuários" ], "summary": "Remove o vínculo de categoria de fornecedor", "description": "Desfaz o acesso do usuário a uma categoria de fornecedor. A operação é registrada em log.", "responses": { "200": { "description": "Vínculo removido. Retorna o detalhe completo do usuário.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserDetail" }, "maxItems": 1 } } } }, "400": { "description": "Mensagem: `[BadRequest] - Categoria fornecedor não localizada no cadastro do usuário`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/user/{iduser}/image": { "parameters": [ { "name": "iduser", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do usuário." } ], "post": { "operationId": "userImagePost", "tags": [ "Cadastro de Usuários" ], "summary": "Define a foto do usuário", "description": "Define a imagem de perfil do usuário. Aceita dois formatos:\n- **Upload de arquivo** (`multipart/form-data`, campo `file`) — envia o binário da imagem.\n- **JSON com `Url`** — o sistema baixa a imagem dessa URL e a armazena.\n\nA imagem é salva no armazenamento público e o endereço final é gravado em `UserImageUrl`.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Arquivo de imagem a enviar." } } } }, "application/json": { "schema": { "type": "object", "required": [ "Url" ], "properties": { "Url": { "type": "string", "format": "uri", "description": "Endereço de onde baixar a imagem." } } } } }, "description": "Foto do usuário. Aceita dois formatos: `multipart/form-data` com o campo `file` (upload do binário) ou JSON `{Url}` (o sistema baixa a imagem desse endereço). A imagem é armazenada no bucket público e o endereço final é gravado em `UserImageUrl`." }, "responses": { "200": { "description": "Imagem definida com sucesso." }, "400": { "description": "Falha ao processar/baixar a imagem. Mensagem possível: `[BadRequest] - erro ao baixar imagem`." }, "404": { "description": "Usuário não encontrado na empresa." } } } }, "/user/{iduser}/verify": { "parameters": [ { "name": "iduser", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do usuário." } ], "post": { "operationId": "userVerifyPost", "tags": [ "Cadastro de Usuários" ], "summary": "Confirma a senha do usuário (reautenticação)", "description": "Revalida a senha do usuário para liberar uma ação sensível (reautenticação). Compara a senha enviada com a cadastrada e, opcionalmente, verifica se o usuário possui o privilégio informado em `UserPrivilege`. Em caso de sucesso, devolve o usuário com um token temporário (`TempAuthToken`) para autorizar a ação seguinte.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserVerifyRequest" } } }, "description": "Reautenticação. `Password` é obrigatória. `UserPrivilege` (opcional) faz o sistema verificar também se o usuário tem o privilégio informado antes de liberar a ação. Em caso de sucesso, devolve o usuário com um `TempAuthToken` para autorizar a próxima ação sensível." }, "responses": { "200": { "description": "Senha confirmada. Retorna o usuário com `TempAuthToken`.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDUser": { "type": "integer", "format": "int32", "description": "Identificador do usuário verificado." }, "Login": { "type": "string", "description": "Login do usuário." }, "UserName": { "type": "string", "description": "Nome de exibição do usuário." }, "TempAuthToken": { "type": "string", "description": "Token temporário para autorizar a ação seguinte." } }, "additionalProperties": true }, "maxItems": 1 } } } }, "400": { "description": "Erros (prefixo `[BadRequest]`):\n- `Usuário não tem senha cadastrada`\n- `Usuário não tem privilégio necessário para essa ação`\n- `Senha incorreta`\n- `Usuário não localizado`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/delivery-status": { "get": { "operationId": "orderDeliveryStatusList", "tags": [ "Tipos — Pedido" ], "summary": "Lista status de entrega de pedidos", "description": "Lista os status de acompanhamento de entrega aplicáveis a pedidos.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDStatusDelivery": { "type": "integer", "description": "Identificador do status de entrega.", "enum": [ 1, 2, 3, 4, 5, 6 ] }, "StatusDelivery": { "type": "string", "maxLength": 45, "nullable": true, "description": "Descrição do status de entrega (`No prazo`, `Atrasado`, `Em exceção`)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/cfop": { "get": { "operationId": "taxCfopList", "tags": [ "Tipos — Impostos" ], "summary": "Lista CFOPs aplicáveis", "description": "Lista as CFOPs cadastradas. Aceita três filtros opcionais que restringem a lista conforme a operação tributária pretendida.", "parameters": [ { "name": "InState", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por operação dentro do estado (`1`) ou fora (`0`)." }, { "name": "TpNf", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tipo de nota a que a CFOP se aplica (`0` entrada, `1` saída)." }, { "name": "NFCe", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra apenas CFOPs aplicáveis a NFC-e (`1`) quando informado." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "Cfop": { "type": "integer", "description": "Código Fiscal de Operações e Prestações (CFOP)." }, "CfopDescription": { "type": "string", "maxLength": 500, "description": "Descrição oficial do CFOP." }, "value": { "type": "string", "description": "Atalho da própria linha (uso interno do frontend)." }, "label": { "type": "string", "description": "Atalho da própria linha (uso interno do frontend)." }, "InState": { "type": "integer", "description": "`1` quando é CFOP de operação dentro do estado, `0` quando é interestadual." }, "TpNf": { "type": "integer", "description": "Tipo de NF: `0` entrada, `1` saída." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/bank-slip/status": { "get": { "operationId": "typeAccountsBankSlipStatusList", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Lista status possíveis de boleto", "description": "Lista os status possíveis do boleto bancário.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDStatusBankSlip": { "type": "integer", "description": "Status do boleto: `1` Aguardando pagamento, `2` Pago, `3` Pendente, `4` Cancelado, `5` Baixa manual, `6` Protesto.", "enum": [ 1, 2, 3, 4, 5, 6 ] }, "StatusBankSlip": { "type": "string", "maxLength": 45, "nullable": true, "description": "Descrição do status (`Em aberto`, `Pago`, `Vencido`, `Cancelado`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/status": { "get": { "operationId": "typeAccountsStatusList", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Lista status de contas a pagar e receber", "description": "Lista os status comuns de contas a pagar e contas a receber.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDStatusAccountPayableReceivable": { "type": "integer", "description": "Identificador do status da conta.", "enum": [ 0, 1, 2, 3, 4, 5, 6 ] }, "StatusAccountPayableReceivable": { "type": "string", "maxLength": 45, "description": "Descrição do status da conta (`Em aberto`, `Pago`, `Cancelado`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/acquirer/payment": { "get": { "operationId": "typeAcquirerPaymentList", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Lista formas de pagamento de adquirente", "description": "Lista os meios de pagamento exibidos pelas adquirentes. Quando filtrado, devolve apenas os meios suportados pela integração informada.", "parameters": [ { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador do tipo de integração da adquirente. Quando ausente, retorna todos os meios cadastrados." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypePaymentFrom": { "type": "integer", "description": "Identificador interno do tipo de pagamento na conciliação do adquirente." }, "TypePaymentFrom": { "type": "string", "maxLength": 45, "description": "Código do tipo de pagamento como o adquirente identifica (ex.: `credito`, `debito`, `pix`)." }, "TypePayment": { "type": "string", "maxLength": 45, "description": "Tipo de pagamento mapeado no idworks (`TypePaymentDescription`)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/acquirer/release": { "get": { "operationId": "typeAcquirerReleaseTypeList", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Lista tipos de liberação de venda", "description": "Lista os tipos de liberação de venda usados pelas adquirentes (à vista, parcelado, etc.).", "parameters": [ { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador do tipo de integração da adquirente." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeAcquirerReleaseType": { "type": "integer", "description": "Identificador do tipo de liberação do adquirente." }, "TypeAcquirerReleaseType": { "type": "string", "maxLength": 200, "description": "Descrição do tipo de liberação (`Pagamento`, `Devolução`, `Chargeback`, etc.)." }, "TypeAcquirerReleaseTypeCode": { "type": "string", "maxLength": 45, "description": "Código do tipo de liberação usado pelo adquirente na conciliação." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/acquirer/status": { "get": { "operationId": "typeAcquirerStatusList", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Lista status de transação das adquirentes", "description": "Lista os status de transação devolvidos pelas adquirentes e o status interno equivalente.", "parameters": [ { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador do tipo de integração da adquirente." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeAcquirerStatus": { "type": "integer", "description": "Identificador do status devolvido pelo adquirente." }, "TypeAcquirerStatusFrom": { "type": "string", "maxLength": 45, "description": "Código do status como o adquirente identifica (ex.: `Aprovado`, `Recusado`)." }, "TypeAcquirerStatus": { "type": "string", "maxLength": 45, "description": "Status mapeado no idworks (descrição amigável)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/bank": { "get": { "operationId": "typeBankList", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Lista bancos disponíveis", "description": "Lista os bancos cadastrados (código FEBRABAN e nome). Ordenado conforme uso/popularidade.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "BankNumber": { "type": "string", "maxLength": 3, "description": "Código (3 dígitos) do banco no padrão Febraban." }, "Bank": { "type": "string", "maxLength": 100, "nullable": true, "description": "Nome do banco. `null` quando não cadastrado." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/purchase/buy-order/status": { "get": { "operationId": "typeBuyOrderStatusList", "tags": [ "Tipos — Compras" ], "summary": "Lista status possíveis de pedido de compra", "description": "Lista os status possíveis de um pedido de compra (rascunho, enviado, recebido, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDStatusBuyOrder": { "type": "integer", "description": "Identificador do status do pedido de compra.", "enum": [ 0, 1, 2, 3, 5, 6, 7 ] }, "StatusBuyOrder": { "type": "string", "maxLength": 45, "description": "Descrição do status (`Aberto`, `Enviado`, `Recebido`, `Parcial`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/supplier/carrier-gateway": { "get": { "operationId": "typeCarrierGatewayList", "tags": [ "Tipos — Fornecedor" ], "summary": "Lista integrações de transportadora", "description": "Lista os gateways de transportadora suportados (integrações com Correios, Jadlog, Loggi, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDCarrierGateway": { "type": "integer", "description": "Identificador do gateway de cotação de frete." }, "CarrierGateway": { "type": "string", "maxLength": 45, "description": "Nome do gateway (ex.: `Interno`, `Intelipost`, `Frete Rápido`)." }, "FileName": { "type": "string", "maxLength": 45, "nullable": true, "description": "Caminho/nome do arquivo de logo do gateway, quando configurado." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/supplier/carrier": { "get": { "operationId": "typeCarrierList", "tags": [ "Tipos — Fornecedor" ], "summary": "Lista transportadoras", "description": "Lista as transportadoras cadastradas no catálogo público.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeCarrier": { "type": "integer", "description": "Identificador do tipo de transportadora." }, "TypeCarrier": { "type": "string", "maxLength": 45, "description": "Nome do tipo de transportadora." }, "CarrierLogoUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "URL do logo da transportadora (S3 público), quando preenchida." }, "FileName": { "type": "string", "maxLength": 45, "nullable": true, "description": "Nome do arquivo de logo no S3." }, "TrackingByOrder": { "type": "integer", "nullable": true, "description": "`1` quando o rastreio é feito por pedido (não por pacote)." }, "TypeCarrierCpfCnpj": { "type": "string", "maxLength": 45, "nullable": true, "description": "CPF/CNPJ default associado a esse tipo de transportadora, quando aplicável." }, "MarketplaceLabel": { "type": "integer", "nullable": true, "description": "`1` quando a transportadora gera etiqueta via marketplace (não tem etiqueta própria)." }, "EDI": { "type": "integer", "nullable": true, "description": "`1` quando a transportadora suporta integração EDI." }, "IDTypeCompanyIntegration": { "type": "integer", "nullable": true, "description": "Tipo de integração associado, quando o rastreio é feito via canal de integração." }, "TrackingEnabled": { "type": "integer", "description": "`1` quando a integração de rastreio está habilitada para a transportadora." }, "FtpFolder": { "type": "string", "maxLength": 45, "nullable": true, "description": "Pasta FTP padrão para arquivos EDI da transportadora, quando aplicável." }, "Show": { "type": "integer", "nullable": true, "description": "`1` quando o tipo de transportadora deve aparecer nas listagens da UI." }, "TypeCarrierExternalId": { "type": "integer", "nullable": true, "description": "Identificador externo (canal/marketplace) do tipo de transportadora." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/quotation/action": { "get": { "operationId": "typeCarrierQuotationActionList", "tags": [ "Tipos — Cotação" ], "summary": "Lista ações de regra de cotação", "description": "Lista as ações disponíveis para regras de cotação de frete (priorizar, descartar, sobrepor preço, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "TypeCarrierQuotationActionRule": { "type": "string", "maxLength": 45, "description": "Descrição da ação (ex.: `Acrescimo no frete`, `Excluir transportadoras`, `Forçar valor fixo`)." }, "IDTypeCarrierQuotationActionRule": { "type": "integer", "description": "Identificador do tipo de ação aplicada por uma regra de cotação." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/quotation/condition": { "get": { "operationId": "typeCarrierQuotationConditionList", "tags": [ "Tipos — Cotação" ], "summary": "Lista condições de regra de cotação", "description": "Lista as condições disponíveis para regras de cotação de frete (peso, valor, CEP, transportadora, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "TypeCarrierQuotationConditionRule": { "type": "string", "maxLength": 45, "description": "Descrição da condição (`Estado/Região`, `CEP Destino`, `Transportadora`, `Valor do pedido`, etc.)." }, "IDTypeCarrierQuotationConditionRule": { "type": "integer", "description": "Identificador do tipo de condição aceito em regras de cotação." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/cofins-cst": { "get": { "operationId": "typeCofinsCstList", "tags": [ "Tipos — Impostos" ], "summary": "Lista CST de COFINS", "description": "Lista os Códigos de Situação Tributária (CST) de COFINS.", "parameters": [ { "name": "TpNf", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tipo de nota (`0` entrada, `1` saída). Restringe os CSTs aos da operação." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfCstCofins": { "type": "string", "maxLength": 2, "description": "Código da CST de COFINS (NF-e)." }, "NfCstCofinsDescription": { "type": "string", "maxLength": 200, "description": "Descrição oficial da CST de COFINS." }, "value": { "type": "string", "description": "Atalho da própria linha (uso interno do frontend)." }, "label": { "type": "string", "description": "Atalho da própria linha (uso interno do frontend)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/report/custom/category": { "get": { "operationId": "typeCompanyReportCustomCategoryList", "tags": [ "Tipos — Relatórios" ], "summary": "Lista categorias de relatórios customizados", "description": "Lista as categorias/tipos de relatórios customizados disponíveis.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeCustomReport": { "type": "integer", "description": "Identificador da categoria/tipo de relatório personalizado." }, "CustomReportType": { "type": "string", "maxLength": 100, "description": "Nome da categoria do relatório." }, "CustomReportBaseTable": { "type": "string", "maxLength": 100, "description": "Tabela-base usada como fonte para os campos do relatório." }, "RecordTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora do cadastro da categoria." }, "DateLastRecordModification": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora da última alteração na categoria." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/report/custom/fields": { "get": { "operationId": "typeCompanyReportCustomFieldsList", "tags": [ "Tipos — Relatórios" ], "summary": "Lista campos disponíveis em um relatório customizado", "description": "Lista os campos selecionáveis em um relatório customizado, agrupados por seção. A resposta é um array com **um único objeto** contendo a identificação do relatório e o agrupamento de campos por seção em `FieldList`.", "parameters": [ { "name": "IDTypeCustomReport", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Identificador do tipo de relatório customizado." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "maxItems": 1, "items": { "type": "object", "properties": { "IDTypeCustomReport": { "type": "integer", "description": "Identificador do tipo de relatório personalizado." }, "ReportName": { "type": "string", "description": "Nome do relatório (e dos campos disponíveis nele)." }, "FieldList": { "type": "object", "description": "Mapa `FieldGroup` → lista de campos. Quando o campo não tem grupo, é agrupado em `\"Sem Grupo\"`.", "additionalProperties": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/consumer/classification": { "get": { "operationId": "typeConsumerClassificationList", "tags": [ "Tipos — Cliente" ], "summary": "Lista classificações de cliente", "description": "Lista as classificações usadas para segmentar clientes (atacado, varejo, VIP, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeConsumerClassification": { "type": "integer", "description": "Identificador da classificação do cliente.", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "TypeConsumerClassification": { "type": "string", "maxLength": 45, "description": "Descrição da classificação (ex.: `VIP`, `Inadimplente`, `Atacado`)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/consumer/status": { "get": { "operationId": "typeConsumerStatusList", "tags": [ "Tipos — Cliente" ], "summary": "Lista status possíveis de cliente", "description": "Lista os status que um cliente pode assumir (ativo, bloqueado, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeStatusConsumer": { "type": "integer", "description": "Identificador do status do cliente.", "enum": [ 0, 1, 2, 3 ] }, "TypeStatusConsumer": { "type": "string", "maxLength": 45, "description": "Descrição do status (`Ativo`, `Inadimplente`, `Bloqueado`, `Deletado`)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/country": { "get": { "operationId": "typeCountryList", "tags": [ "Tipos — Pedido" ], "summary": "Lista países", "description": "Lista os países cadastrados.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDCountry": { "type": "integer", "description": "Identificador interno do país." }, "Country": { "type": "string", "maxLength": 200, "description": "Nome do país." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/cte/sit": { "get": { "operationId": "typeCteSitList", "tags": [ "Tipos — CT-e" ], "summary": "Lista situações do CT-e", "description": "Lista as situações possíveis do CT-e (autorizado, cancelado, denegado, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "SitCte": { "type": "integer", "description": "Código da situação do CT-e na SEFAZ." }, "SitCteDescription": { "type": "string", "maxLength": 45, "nullable": true, "description": "Descrição da situação (ex.: `Autorizado`, `Cancelado`, `Denegado`)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/cte/toma": { "get": { "operationId": "typeCteTomaList", "tags": [ "Tipos — CT-e" ], "summary": "Lista tomadores do CT-e", "description": "Lista os tipos de tomador do serviço de transporte no CT-e (remetente, destinatário, expedidor, recebedor, outros).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "CtToma": { "type": "integer", "description": "Código do tomador do CT-e (0 a 4 conforme leiaute SEFAZ)." }, "CtTomaDescription": { "type": "string", "maxLength": 45, "nullable": true, "description": "Descrição do tomador (`Remetente`, `Expedidor`, `Recebedor`, `Destinatário`, `Outros`)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/cte/type": { "get": { "operationId": "typeCteTypelist", "tags": [ "Tipos — CT-e" ], "summary": "Lista tipos de CT-e", "description": "Lista os tipos de CT-e (normal, complemento de valores, anulação, substituto).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "CtTpCte": { "type": "integer", "description": "Código do tipo de CT-e na SEFAZ." }, "CtTpCteDescription": { "type": "string", "maxLength": 45, "nullable": true, "description": "Descrição do tipo (`Normal`, `Complemento de valores`, `Anulação`, `Substituição`)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/account/file-type": { "get": { "operationId": "typeFileTypeList", "tags": [ "Tipos — Contas e Pagamento" ], "summary": "Lista tipos de arquivo", "description": "Lista os tipos de arquivo suportados pelo upload (contrato, comprovante, foto, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeFile": { "type": "integer", "description": "Identificador do tipo de arquivo aceito em contas a pagar/receber.", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "TypeFile": { "type": "string", "maxLength": 45, "description": "Descrição do tipo de arquivo (ex.: `Comprovante`, `Boleto`, `Nota fiscal`)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/fulfillment/non-conformity": { "get": { "operationId": "typeFulfillmentNonconformity", "tags": [ "Tipos — Fulfillment" ], "summary": "Lista tipos de não-conformidade de fulfillment", "description": "Lista os tipos de não-conformidade aplicáveis ao processo de fulfillment.", "parameters": [ { "name": "ShowPicking", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Quando `1`, retorna apenas tipos visíveis na tela de picking; quando omitido retorna todos." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeFulfillmentNonconformity": { "type": "integer", "description": "Identificador do tipo de não-conformidade no fulfillment.", "enum": [ 1, 2, 4, 5, 6 ] }, "TypeFulfillmentNonconformity": { "type": "string", "maxLength": 45, "description": "Descrição (`Falta`, `Sobra`, `Avaria`, `Ressuprimento`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/goal/type": { "get": { "operationId": "typeGoalList", "tags": [ "Tipos — Metas" ], "summary": "Lista tipos de meta", "description": "Lista os tipos de meta suportados (faturamento, ticket médio, conversão, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeGoal": { "type": "integer", "description": "Identificador do tipo de meta.", "enum": [ 1, 2, 3, 4 ] }, "TypeGoal": { "type": "string", "maxLength": 45, "description": "Descrição do tipo de meta (ex.: `Vendas`, `Pedidos`, `Atendimentos`)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/hub/order/claim/reason": { "get": { "operationId": "typeHubOrderClaimReasonList", "tags": [ "Hub — Tipos de Referência" ], "summary": "Lista motivos de reclamação de pedido (Hub)", "description": "Lista os motivos de abertura de reclamações em pedidos do Hub. Quando filtrado por integração, retorna apenas os motivos válidos no marketplace correspondente.", "parameters": [ { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador do tipo de integração do marketplace." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeHubOrderClaimReason": { "type": "integer", "description": "Identificador interno do motivo da reclamação/disputa do pedido." }, "IDTypeHubOrderClaimReasonExternalId": { "type": "string", "maxLength": 45, "description": "Identificador do motivo no canal externo (marketplace)." }, "TypeHubOrderClaimReason": { "type": "string", "maxLength": 500, "description": "Descrição do motivo da reclamação." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/hub/order/claim/resolution-reason": { "get": { "operationId": "typeHubOrderClaimResolutionReasonList", "tags": [ "Hub — Tipos de Referência" ], "summary": "Lista motivos de resolução de reclamação (Hub)", "description": "Lista os motivos de resolução de reclamações de pedido do Hub.", "parameters": [ { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador do tipo de integração do marketplace." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeHubOrderClaimResolutionReason": { "type": "integer", "description": "Identificador interno do motivo da resolução da reclamação." }, "IDTypeHubOrderClaimResolutionReasonExternalId": { "type": "string", "maxLength": 45, "description": "Identificador da resolução no canal externo." }, "TypeHubOrderClaimResolutionReasonDescription": { "type": "string", "maxLength": 200, "description": "Descrição do motivo da resolução." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/hub/order/claim/stage": { "get": { "operationId": "typeHubOrderClaimStageList", "tags": [ "Hub — Tipos de Referência" ], "summary": "Lista estágios de reclamação (Hub)", "description": "Lista os estágios de evolução de uma reclamação de pedido do Hub.", "parameters": [ { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador do tipo de integração do marketplace." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeHubOrderClaimStage": { "type": "integer", "description": "Identificador interno do estágio da reclamação.", "enum": [ 1, 2, 3, 4, 5 ] }, "IDTypeHubOrderClaimStageExternalId": { "type": "string", "maxLength": 45, "description": "Identificador do estágio no canal externo." }, "TypeHubOrderClaimStageName": { "type": "string", "maxLength": 45, "description": "Nome do estágio (`Aberto`, `Em andamento`, `Fechado`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/hub/order/claim/type": { "get": { "operationId": "typeHubOrderClaimTypeList", "tags": [ "Hub — Tipos de Referência" ], "summary": "Lista tipos de reclamação (Hub)", "description": "Lista os tipos de reclamação de pedido (devolução, troca, garantia, etc.).", "parameters": [ { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador do tipo de integração do marketplace." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeHubOrderClaimType": { "type": "integer", "description": "Identificador interno do tipo de reclamação.", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "IDTypeHubOrderClaimTypeExternalId": { "type": "string", "maxLength": 45, "description": "Identificador do tipo no canal externo." }, "TypeHubOrderClaimTypeName": { "type": "string", "maxLength": 45, "nullable": true, "description": "Nome do tipo de reclamação (`Devolução`, `Cancelamento`, `Defeito`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/hub/status": { "get": { "operationId": "typeHubOrderStatusList", "tags": [ "Tipos — Pedido" ], "summary": "Lista status de pedidos do Hub", "description": "Lista os status de pedidos sincronizados a partir do Hub (marketplaces).", "parameters": [ { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador do tipo de integração do marketplace." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "OrderStatus": { "type": "string", "maxLength": 45, "description": "Código do status do pedido no canal de venda (externo)." }, "Description": { "type": "string", "maxLength": 45, "description": "Descrição amigável do status no canal." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/hub/status": { "get": { "operationId": "typeHubSkuStatusList", "tags": [ "Tipos — SKU" ], "summary": "Lista status de SKU no Hub", "description": "Lista os status de SKU no Hub (pendente, sincronizado, com divergência, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDStatusHubSku": { "type": "integer", "description": "Identificador do status do SKU no canal de venda.", "enum": [ 0, 1, 2, 3, 4, 5 ] }, "StatusHubSku": { "type": "string", "maxLength": 45, "description": "Descrição do status (`Ativo`, `Pausado`, `Encerrado`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/ibs-cbs": { "get": { "operationId": "typeIbsCbsCstList", "tags": [ "Tipos — Impostos" ], "summary": "Lista CST de IBS/CBS", "description": "Lista os Códigos de Situação Tributária (CST) de IBS/CBS. Aceita filtros booleanos para restringir a CSTs aplicáveis a cada modelo de documento fiscal.", "parameters": [ { "name": "NFe", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Quando `1`, restringe a CSTs válidos em NF-e." }, { "name": "NFCe", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Quando `1`, restringe a CSTs válidos em NFC-e." }, { "name": "NFSe", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Quando `1`, restringe a CSTs válidos em NFS-e." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDNfCstIbsCbs": { "type": "integer", "description": "Identificador interno da CST de IBS/CBS (Reforma Tributária)." }, "NfCstIbsCbsDescription": { "type": "string", "description": "Descrição oficial da CST." }, "cClassTrib": { "type": "string", "maxLength": 45, "description": "Código de classificação tributária (`cClassTrib`) conforme leiaute SEFAZ." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/icms-cst": { "get": { "operationId": "typeIcmsCstList", "tags": [ "Tipos — Impostos" ], "summary": "Lista CST/CSOSN de ICMS aplicáveis à filial", "description": "Lista os Códigos de Situação Tributária (CST/CSOSN) de ICMS aplicáveis à filial informada. Para cada CST, retorna a lista de `Fields` indicando quais campos do regime tributário ficam habilitados (`Disable: false`) ou desabilitados (`Disable: true`).", "parameters": [ { "name": "IDCompanyBranch", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Identificador da filial. Determina o regime tributário usado para filtrar os CSTs disponíveis." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "Cst": { "type": "string", "description": "Código da CST de ICMS." }, "CstDescription": { "type": "string", "description": "Descrição oficial da CST." }, "IDNfCstIcms": { "type": "integer", "description": "Identificador interno da CST." }, "value": { "type": "string", "description": "Valor utilizado em componentes de UI de seleção (corresponde ao `Cst`)." }, "label": { "type": "string", "description": "Rótulo utilizado em componentes de UI de seleção (corresponde ao `CstDescription`)." }, "Fields": { "type": "array", "description": "Lista de campos do regime tributário com indicação se estão habilitados.", "items": { "type": "object", "properties": { "Field": { "type": "string", "description": "Nome do campo (ex.: `vBC`, `pICMS`, `vICMS`)." }, "Disable": { "type": "boolean", "description": "`true` quando o campo deve aparecer desabilitado no formulário para esse CST." } } } } } } } } } }, "400": { "description": "Erro de validação. Mensagens possíveis:\n- `[BadRequest] - IDCompanyBranch não existe` — A filial informada não pertence à empresa autenticada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/icms-mod-bc": { "get": { "operationId": "typeIcmsModBcList", "tags": [ "Tipos — Impostos" ], "summary": "Lista modalidades de base de cálculo de ICMS", "description": "Lista as modalidades de determinação da base de cálculo do ICMS.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfModBc": { "type": "integer", "description": "Código da modalidade de base de cálculo do ICMS." }, "NfModBcDescription": { "type": "string", "maxLength": 45, "description": "Descrição da modalidade." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/icms-mod-bc-st": { "get": { "operationId": "typeIcmsModBcStList", "tags": [ "Tipos — Impostos" ], "summary": "Lista modalidades de base de cálculo do ICMS ST", "description": "Lista as modalidades de determinação da base de cálculo do ICMS ST.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfModBcST": { "type": "integer", "description": "Código da modalidade de base de cálculo do ICMS-ST." }, "NfModBcSTDescription": { "type": "string", "maxLength": 45, "description": "Descrição da modalidade." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/company/parameter/type": { "get": { "operationId": "typeIntegrationTypeList", "tags": [ "Tipos — Empresa" ], "summary": "Lista tipos de integração disponíveis", "description": "Lista os tipos de integração disponíveis para contratação. Pode ser filtrado por categoria (banco, marketplace, transportadora, etc.). Apenas integrações com `Show = 1` são retornadas.", "parameters": [ { "name": "IDTypeCompanyIntegrationCategory", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador da categoria de integração. Quando ausente, retorna todas as integrações visíveis." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeCompanyIntegration": { "type": "integer", "description": "Identificador do tipo de integração." }, "Integration": { "type": "string", "maxLength": 45, "description": "Nome curto da integração (slug usado em rotas)." }, "IntegrationName": { "type": "string", "maxLength": 45, "description": "Nome amigável da integração (`Mercado Livre`, `idworks`, `Correios`, etc.)." }, "IntegrationLogoUrl": { "type": "string", "maxLength": 200, "nullable": true, "description": "URL do logo da integração." }, "IDTypeCompanyIntegrationCategory": { "type": "integer", "description": "Categoria da integração." }, "IDSalesChannel": { "type": "integer", "nullable": true, "description": "Identificador do canal de venda associado, quando aplicável." }, "NfeInfIntermed": { "type": "string", "maxLength": 45, "nullable": true, "description": "Tipo de informação de intermediador para NF-e (`1` operação sem intermediador, `2` operação em site/marketplace)." }, "PathName": { "type": "string", "maxLength": 45, "nullable": true, "description": "Path name usado para rotear chamadas internas (ex.: `meli`, `magalu`). Vazio para integrações que não precisam." }, "Show": { "type": "integer", "nullable": true, "description": "`1` quando a integração deve aparecer nas listagens da UI." }, "UpdateOrderShipped": { "type": "integer", "nullable": true, "description": "`1` quando a integração atualiza automaticamente o status `Enviado` no canal." }, "UpdateOrderDelivered": { "type": "integer", "nullable": true, "description": "`1` quando a integração atualiza automaticamente o status `Entregue` no canal." }, "UpdateMarketplaceFee": { "type": "integer", "nullable": true, "description": "`1` quando a integração importa a taxa do marketplace." }, "GiftCard": { "type": "integer", "nullable": true, "description": "`1` quando a integração suporta vale-presente." }, "UpdateSkuBalance": { "type": "integer", "nullable": true, "description": "`1` quando a integração atualiza saldo de estoque no canal." }, "AuthUrl": { "type": "integer", "nullable": true, "description": "`1` quando a integração tem fluxo de autenticação OAuth." }, "HubPaymentCustom": { "type": "integer", "nullable": true, "description": "`1` quando o canal devolve pagamentos em formato customizado." }, "UpdateOrderFulfillment": { "type": "integer", "nullable": true, "description": "`1` quando a integração atualiza fulfillment no canal." }, "BankSlipUpdate": { "type": "integer", "nullable": true, "description": "`1` quando a integração atualiza boletos." }, "BankSlipCancel": { "type": "integer", "nullable": true, "description": "`1` quando a integração cancela boletos." }, "UpdateOrderStatus": { "type": "integer", "nullable": true, "description": "`1` quando a integração atualiza status genérico do pedido." }, "UpdateOrderStatusPending": { "type": "integer", "nullable": true, "description": "`1` quando a integração atualiza status `Pendente` (especial)." }, "CarrierQuotation": { "type": "integer", "nullable": true, "description": "`1` quando a integração é gateway de cotação de frete." }, "UpdateSkuPricing": { "type": "integer", "nullable": true, "description": "`1` quando a integração atualiza preços de SKU no canal." }, "SkuPricingFile": { "type": "string", "maxLength": 45, "nullable": true, "description": "Caminho do template de planilha de preços específico do canal." }, "IntegrationWebsite": { "type": "string", "maxLength": 300, "nullable": true, "description": "URL do site oficial da integração." }, "TypeCompanyIntegrationCategory.TypeCompanyIntegrationCategory": { "type": "string", "description": "Nome da categoria a que a integração pertence." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/di-intermedio": { "get": { "operationId": "typeInvoiceDIIntermedio", "tags": [ "Tipos — Impostos" ], "summary": "Lista tipos de intermédio (DI)", "description": "Lista os tipos de intermédio em operações de importação para informação na DI (Declaração de Importação).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfDITpIntermedio": { "type": "integer", "description": "Código do tipo de intermédio da DI (Declaração de Importação)." }, "NfDITpIntermedioDescription": { "type": "string", "maxLength": 45, "description": "Descrição do tipo de intermédio." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/di-viatransp": { "get": { "operationId": "typeInvoiceDIViaTransp", "tags": [ "Tipos — Impostos" ], "summary": "Lista vias de transporte (DI)", "description": "Lista as vias de transporte usadas na DI (marítima, aérea, rodoviária, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NftDITpViaTransp": { "type": "integer", "description": "Código da via de transporte na DI." }, "NftDITpViaTranspDescription": { "type": "string", "maxLength": 45, "description": "Descrição da via (`Marítima`, `Aérea`, `Rodoviária`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/invoice/event": { "get": { "operationId": "typeInvoiceEventList", "tags": [ "Tipos — Nota Fiscal" ], "summary": "Lista tipos de evento de nota fiscal", "description": "Lista os tipos de evento aplicáveis a notas fiscais (carta de correção, cancelamento, manifestação, etc.). Pode filtrar via `Type` por código parcial.", "parameters": [ { "name": "Type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca textual parcial pelo código do evento (`NfTpEvent` LIKE `%Type%`)." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfTpEvent": { "type": "integer", "description": "Código do tipo de evento de NF-e/CT-e na SEFAZ." }, "NfTpEventDescription": { "type": "string", "maxLength": 100, "description": "Descrição do evento (`Cancelamento`, `Carta de Correção`, `Confirmação da Operação`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/invoice/fin": { "get": { "operationId": "typeInvoiceFinList", "tags": [ "Tipos — Nota Fiscal" ], "summary": "Lista finalidades de emissão", "description": "Lista as finalidades de emissão da NF-e (normal, complementar, ajuste, devolução).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "FinNFe": { "type": "integer", "description": "Código da finalidade da NF-e (`1` normal, `2` complementar, `3` ajuste, `4` devolução)." }, "FinNfeDescription": { "type": "string", "maxLength": 45, "description": "Descrição da finalidade." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/invoice/sefaz-status": { "get": { "operationId": "typeInvoiceSefazStatus", "tags": [ "Tipos — Nota Fiscal" ], "summary": "Lista códigos de status da SEFAZ", "description": "Lista os códigos de status retornados pela SEFAZ ao processar notas fiscais. Útil para identificar e exibir mensagens de erro de emissão.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "State": { "type": "string", "maxLength": 2, "description": "UF do servidor SEFAZ consultado." }, "SefazcStat": { "type": "integer", "description": "Código de status retornado pela SEFAZ no último consulta-status." }, "LastUpdateTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora da última verificação do status." }, "SefazverAplic": { "type": "string", "maxLength": 45, "nullable": true, "description": "Versão da aplicação SEFAZ na última consulta." }, "EPECMode": { "type": "integer", "nullable": true, "description": "`1` quando a SEFAZ está em modo de contingência EPEC." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/invoice/type-issue": { "get": { "operationId": "typeInvoiceTypeIssueList", "tags": [ "Tipos — Nota Fiscal" ], "summary": "Lista tipos de emissão", "description": "Lista os tipos de emissão da NF-e (normal, contingência FS-IA, contingência SCAN, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfetpEmis": { "type": "integer", "description": "Código do tipo de emissão da NF-e (`1` normal, `2-9` contingências)." }, "NfetpEmisDescription": { "type": "string", "maxLength": 200, "nullable": true, "description": "Descrição do tipo de emissão." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/invoice/type": { "get": { "operationId": "typeInvoiceTypeList", "tags": [ "Tipos — Nota Fiscal" ], "summary": "Lista tipos de nota fiscal (entrada/saída)", "description": "Lista os tipos de nota fiscal pelo indicador de entrada (`0`) ou saída (`1`).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfTpNf": { "type": "integer", "description": "Código do tipo de operação da NF-e (`0` entrada, `1` saída)." }, "NfTpNfDescription": { "type": "string", "maxLength": 45, "description": "Descrição do tipo (`Entrada`, `Saída`)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/ipi-cenq": { "get": { "operationId": "typeIpiCEnqList", "tags": [ "Tipos — Impostos" ], "summary": "Lista códigos de enquadramento legal de IPI", "description": "Lista os códigos de enquadramento legal de IPI aplicáveis. O filtro `IpiCst` é interpretado pelo último dígito do CST: se for `2`, `4` ou `5`, restringe a códigos válidos para CSTs de imunidade/suspensão; caso contrário, retorna todos.", "parameters": [ { "name": "IpiCst", "in": "query", "required": false, "schema": { "type": "string" }, "description": "CST de IPI. Usado apenas pelo último dígito; se for `2`, `4` ou `5`, restringe a códigos de enquadramento aplicáveis. Outros valores são ignorados." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfIpiCEnq": { "type": "string", "maxLength": 3, "description": "Código de enquadramento do IPI." }, "NfIpiCEnqDescription": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Descrição do código de enquadramento." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/ipi-cst": { "get": { "operationId": "typeIpiCstList", "tags": [ "Tipos — Impostos" ], "summary": "Lista CST de IPI", "description": "Lista os Códigos de Situação Tributária (CST) de IPI.", "parameters": [ { "name": "TpNf", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tipo de nota (`0` entrada, `1` saída). Restringe os CSTs aos da operação." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfCstIpi": { "type": "string", "maxLength": 2, "description": "Código da CST de IPI." }, "NfCstIpiDescription": { "type": "string", "maxLength": 45, "description": "Descrição oficial da CST de IPI." }, "value": { "type": "string", "description": "Atalho da própria linha (uso interno do frontend)." }, "label": { "type": "string", "description": "Atalho da própria linha (uso interno do frontend)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/job/type": { "get": { "operationId": "typeJobTypeList", "tags": [ "Tipos — Jobs" ], "summary": "Lista tipos de job", "description": "Lista os tipos de job/tarefa executáveis pela conta (exportações, relatórios agendados, etc.) e o relatório (`IDTypeCompanyReport`) e `TemplateUrl` associados.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeJob": { "type": "integer", "description": "Identificador do tipo de job de importação." }, "TypeJob": { "type": "string", "maxLength": 45, "description": "Descrição do tipo (`Criar sku/produto`, `Criar pedido`, `Criar contas`, etc.)." }, "IDTypeCompanyReport": { "type": "integer", "nullable": true, "description": "Identificador do relatório associado ao tipo de job, quando aplicável." }, "TemplateUrl": { "type": "string", "maxLength": 1000, "nullable": true, "description": "URL do template de planilha (S3) usado por esse tipo de job." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/label/category": { "get": { "operationId": "typeLabelCategoryList", "tags": [ "Tipos — Etiquetas" ], "summary": "Lista categorias de etiqueta", "description": "Lista as categorias de etiqueta (modelos de impressão) — produto, embalagem, transporte, etc.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeLabelCategory": { "type": "integer", "description": "Identificador da categoria do template de etiqueta." }, "TypeLabelCategory": { "type": "string", "maxLength": 45, "nullable": true, "description": "Nome da categoria (`Endereço`, `Produto`, `Volume`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/label": { "get": { "operationId": "typeLabelList", "tags": [ "Tipos — Etiquetas" ], "summary": "Lista etiquetas cadastradas", "description": "Lista as etiquetas (modelos de impressão) cadastradas para a empresa. Inclui automaticamente as etiquetas padrão da conta `54`. Pode ser filtrada por categoria.", "parameters": [ { "name": "IDTypeLabelCategory", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por categoria de etiqueta." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "AccountName": { "type": "string", "description": "Conta (prefixo) a que pertence o template de etiqueta." }, "TypeLabelCategory": { "type": "string", "description": "Categoria da etiqueta." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/label/{idtypelabelcategory}/variable": { "parameters": [ { "name": "idtypelabelcategory", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da categoria de etiqueta (`IDTypeLabelCategory`)." } ], "get": { "operationId": "typeLabelVariableList", "tags": [ "Tipos — Etiquetas" ], "summary": "Lista variáveis de uma categoria de etiqueta", "description": "Lista as variáveis (placeholders) substituíveis nas etiquetas de uma determinada categoria.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeLabelCategoryVariable": { "type": "integer", "description": "Identificador da variável disponível para a categoria de etiqueta." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora do cadastro da variável." }, "IDTypeLabelCategory": { "type": "integer", "description": "Identificador da categoria à qual a variável pertence." }, "TypeLabelCategoryVariable": { "type": "string", "maxLength": 45, "description": "Nome técnico da variável (placeholder usado no template)." }, "TypeLabelCategoryVariableDescription": { "type": "string", "maxLength": 100, "description": "Descrição amigável da variável para exibição na UI." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/measurement": { "get": { "operationId": "typeMeasurementList", "tags": [ "Tipos — SKU" ], "summary": "Lista unidades de medida", "description": "Lista as unidades de medida usadas no cadastro de produtos e nas notas fiscais.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "MeasurementUnit": { "type": "string", "maxLength": 45, "description": "Sigla da unidade de medida (`UN`, `KG`, `M`, `L`, etc.)." }, "MeasurementUnitDescription": { "type": "string", "maxLength": 45, "description": "Nome da unidade de medida." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/event": { "get": { "operationId": "typeOrderEvent", "tags": [ "Tipos — Pedido" ], "summary": "Lista eventos de pedido", "description": "Lista os eventos registrados em pedidos (criação, alteração de status, anotação, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDEvent": { "type": "integer", "description": "Identificador do tipo de evento de pedido." }, "EventDescription": { "type": "string", "maxLength": 100, "description": "Descrição do evento (`Picking iniciado`, `Romaneio fechado`, `Cancelamento`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/invoice-status": { "get": { "operationId": "typeOrderInvoiceStatusList", "tags": [ "Tipos — Pedido" ], "summary": "Lista status de nota fiscal em pedidos", "description": "Lista os status de nota fiscal aplicáveis a pedidos. Quando filtrado, retorna apenas status compatíveis com notas de serviço (`ServiceInvoice = 1`) ou de produto (`= 0`).", "parameters": [ { "name": "ServiceInvoice", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restringe a status de NFS-e (`1`) ou NF-e (`0`)." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDStatusInvoice": { "type": "integer", "description": "Identificador do status da NF (`0` Pendente, `1` Erro, `2` Enviada, `3` Emitida, `4` Processando, `5` Pendente Conciliação EPEC, `6` Erro Conciliação EPEC, `7` Cancelada, `8` Denegada, `9` Inutilizada)." }, "StatusInvoice": { "type": "string", "maxLength": 45, "description": "Descrição do status da NF." }, "ServiceInvoice": { "type": "integer", "description": "`1` quando o status é de NF de serviço (NFSe); `0` para NF-e/NFC-e." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/resend": { "get": { "operationId": "typeOrderResendList", "tags": [ "Tipos — Pedido" ], "summary": "Lista motivos de reenvio de pedido", "description": "Lista os motivos disponíveis quando se reenvia (refaz) um pedido.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeOrderResend": { "type": "integer", "description": "Identificador do motivo de reenvio do pedido." }, "TypeOrderResend": { "type": "string", "maxLength": 45, "nullable": true, "description": "Descrição do motivo (`Extravio`, `Endereço errado`, `Avaria`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/return/category": { "get": { "operationId": "typeOrderReturnCategoryList", "tags": [ "Tipos — Pedido" ], "summary": "Lista categorias de devolução", "description": "Lista as categorias de motivo de devolução de pedido (defeito, arrependimento, divergência, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeOrderReturnCategory": { "type": "integer", "description": "Identificador da categoria de devolução.", "enum": [ 1, 2, 3 ] }, "TypeOrderReturnCategory": { "type": "string", "maxLength": 45, "description": "Nome da categoria (`Defeito`, `Arrependimento`, `Troca`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/return": { "get": { "operationId": "typeOrderReturnList", "tags": [ "Tipos — Pedido" ], "summary": "Lista motivos de devolução", "description": "Lista os motivos de devolução suportados.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeOrderReturn": { "type": "integer", "description": "Identificador do tipo de devolução." }, "TypeOrderReturn": { "type": "string", "maxLength": 45, "description": "Descrição do tipo de devolução." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/pis-cst": { "get": { "operationId": "typePisCstList", "tags": [ "Tipos — Impostos" ], "summary": "Lista CST de PIS", "description": "Lista os Códigos de Situação Tributária (CST) de PIS.", "parameters": [ { "name": "TpNf", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tipo de nota (`0` entrada, `1` saída). Restringe os CSTs aos da operação." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfCstPis": { "type": "string", "maxLength": 3, "description": "Código da CST de PIS." }, "NfCstPisDescription": { "type": "string", "maxLength": 300, "description": "Descrição oficial da CST de PIS." }, "value": { "type": "string", "description": "Atalho da própria linha (uso interno do frontend)." }, "label": { "type": "string", "description": "Atalho da própria linha (uso interno do frontend)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/purchase/status": { "get": { "operationId": "typePurchaseStatusList", "tags": [ "Tipos — Compras" ], "summary": "Lista status de processo de compra", "description": "Lista os status possíveis em um processo de compra (rascunho, em análise, aprovado, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDStatusPurchase": { "type": "integer", "description": "Identificador do status do recebimento." }, "StatusPurchase": { "type": "string", "maxLength": 45, "description": "Descrição do status (`Aberto`, `Em conferência`, `Conferência realizada`, `Finalizado`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sales-channel/commercial-condition": { "get": { "operationId": "typeSalesChannelCommercialConditionList", "tags": [ "Tipos — Canal de Venda" ], "summary": "Lista condições comerciais do canal de venda", "description": "Lista as condições comerciais (B2W, etc.) cadastradas para uma integração de canal de venda específica da empresa autenticada.", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Identificador da integração da empresa." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeSkuCommercialCondition": { "type": "integer", "description": "Identificador da condição comercial." }, "CommercialCondition": { "type": "string", "maxLength": 45, "nullable": true, "description": "Descrição da condição comercial (ex.: `Novo`, `Usado`, `Recondicionado`)." } } } } } } }, "400": { "description": "Erro de validação. Mensagens possíveis:\n- `[BadRequest] - IDCompanyIntegration é obrigatório` — Query `IDCompanyIntegration` ausente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sales-channel/sales-policy": { "get": { "operationId": "typeSalesChannelSalesPolicyList", "tags": [ "Tipos — Canal de Venda" ], "summary": "Lista políticas de venda do canal", "description": "Lista as políticas de venda (Sales Policy — VTEX, etc.) cadastradas para uma integração de canal de venda específica da empresa autenticada.", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Identificador da integração da empresa." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeSkuSalesPolicy": { "type": "integer", "description": "Identificador da política de venda." }, "SalesPolicy": { "type": "string", "maxLength": 45, "description": "Descrição da política (ex.: `Atacado`, `Varejo`, `Distribuidor`)." }, "value": { "type": "string", "description": "Atalho da própria linha (uso interno do frontend)." }, "label": { "type": "string", "description": "Atalho da própria linha (uso interno do frontend)." } } } } } } }, "400": { "description": "Erro de validação. Mensagens possíveis:\n- `[BadRequest] - IDCompanyIntegration é obrigatório` — Query `IDCompanyIntegration` ausente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/invoice/service/type": { "get": { "operationId": "typeServiceCodeList", "tags": [ "Tipos — Nota Fiscal" ], "summary": "Lista códigos de serviço (NFS-e)", "description": "Lista os códigos municipais de serviço aplicáveis. Por padrão usa o município cadastrado na empresa autenticada. Hoje só há códigos cadastrados para os municípios de São Paulo (3550308) e Barueri (3505708); demais municípios caem em uma lista genérica (CityCode `0`).", "parameters": [ { "name": "CityCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código IBGE do município. Quando ausente, usa o município cadastrado na empresa." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador da configuração de NFS-e da empresa (atualmente não usado para filtrar, mas aceito)." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDNfsServiceCode": { "type": "integer", "description": "Identificador interno do código de serviço da NFSe." }, "CityCode": { "type": "integer", "description": "Código do município (IBGE)." }, "ServiceCode": { "type": "string", "maxLength": 45, "description": "Código de serviço conforme cadastro municipal." }, "ServiceDescription": { "type": "string", "maxLength": 1000, "description": "Descrição do serviço." }, "ServiceAliquot": { "type": "number", "nullable": true, "description": "Alíquota padrão do serviço para o município (em fração `0–1` ou percentual, conforme cadastro)." } } } } } } }, "400": { "description": "Erro de validação. Mensagens possíveis:\n- `[BadRequest] - Empresa não esta com endereço preenchido no cadastro` — Empresa não tem `CompanyAddressIbgeCityCode` cadastrado.\n- `[BadRequest] - Empresa não existe` — Empresa não localizada pelo `accountname`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).\n\n**Mensagens sem prefixo padrão (podem cair como 500 ou no corpo do default):**\n- `Município não tem emissão de nota fiscal de serviço` — Nenhum código encontrado para o município (mensagem sem prefixo padrão).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/action": { "get": { "operationId": "typeSkuAction", "tags": [ "Tipos — SKU" ], "summary": "Lista ações de SKU", "description": "Lista as ações disponíveis para SKUs (vendas, transferência, ajuste, produção, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDSkuAction": { "type": "integer", "description": "Identificador do tipo de ação aplicável a SKUs." }, "ActionName": { "type": "string", "maxLength": 45, "description": "Nome da ação (`Importar custo`, `Ajustar saldo`, `Trocar status`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/location/address": { "get": { "operationId": "typeSkuAddressList", "tags": [ "Tipos — SKU" ], "summary": "Lista tipos de endereço de armazenagem", "description": "Lista os tipos de endereço de armazenagem (rua, prateleira, posição, etc.) usados no controle de localização de SKUs em depósito.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeAddress": { "type": "integer", "description": "Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado.", "enum": [ 1, 2, 3 ] }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora do cadastro do tipo." }, "TypeAddress": { "type": "string", "maxLength": 60, "description": "Nome do tipo de endereço (`Picking`, `Pulmão`, `Bloqueado`, `Quarentena`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/inventory-summary/status": { "get": { "operationId": "typeSkuInventorySummaryStatusList", "tags": [ "Tipos — SKU" ], "summary": "Lista status do resumo de inventário", "description": "Lista os status possíveis do resumo de inventário (agendado, em contagem, conferido, divergente, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeStatusSkuInventory": { "type": "integer", "description": "Identificador do status do inventário." }, "TypeStatusSkuInventory": { "type": "string", "maxLength": 45, "nullable": true, "description": "Descrição do status (`Aberto`, `Em andamento`, `Finalizado`, `Cancelado`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/type": { "get": { "operationId": "typeSkuTypeList", "tags": [ "Tipos — SKU" ], "summary": "Lista tipos de produto/SKU", "description": "Lista os tipos de produto/SKU (produto, kit, variação, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeProduct": { "type": "integer", "description": "Identificador do tipo de produto.", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "TypeProduct": { "type": "string", "maxLength": 45, "description": "Nome curto do tipo (`Simples`, `Kit`, `Variação`)." }, "TypeProductDescription": { "type": "string", "maxLength": 45, "description": "Descrição amigável do tipo de produto." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/status": { "get": { "operationId": "typeStatusSkuList", "tags": [ "Tipos — SKU" ], "summary": "Lista status de SKU", "description": "Lista os status que um SKU pode assumir.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeStatusSku": { "type": "integer", "description": "Identificador do status do SKU." }, "TypeStatusSku": { "type": "string", "maxLength": 45, "description": "Descrição do status (`Ativo`, `Inativo`, `Suspenso`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/production/status": { "get": { "operationId": "typeStatusSkuProductionList", "tags": [ "Tipos — SKU" ], "summary": "Lista status de produção de SKU", "description": "Lista os status do processo de produção de SKU.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeStatusSkuProduction": { "type": "integer", "description": "Status da etapa de produção: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado.", "enum": [ 1, 2, 3, 4 ] }, "TypeStatusSkuProduction": { "type": "string", "maxLength": 45, "description": "Descrição do status (`Aberta`, `Em andamento`, `Finalizada`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/supplier/type": { "get": { "operationId": "typeSupplierTypeList", "tags": [ "Tipos — Fornecedor" ], "summary": "Lista tipos de fornecedor", "description": "Lista os tipos de fornecedor (matéria-prima, revenda, serviços, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeSupplier": { "type": "integer", "description": "Identificador do tipo de fornecedor." }, "TypeSupplier": { "type": "string", "maxLength": 45, "description": "Descrição (`Fornecedor`, `Transportadora`, `Cliente`, `Fabricante`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/cst": { "get": { "operationId": "typeTaxCst", "tags": [ "Tipos — Impostos" ], "summary": "Lista códigos de origem da mercadoria", "description": "Lista os códigos de origem da mercadoria (0 nacional, 1 estrangeira importação direta, etc.) usados em CSTs.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfOrig": { "type": "integer", "description": "Código da origem da mercadoria conforme leiaute SEFAZ (`0` Nacional, `1` Importada, etc.)." }, "NfOrigDescription": { "type": "string", "maxLength": 150, "description": "Descrição da origem da mercadoria." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/crt": { "get": { "operationId": "typeTaxCstList", "tags": [ "Tipos — Impostos" ], "summary": "Lista CRT (regime tributário)", "description": "Lista os Códigos de Regime Tributário (CRT) — Simples Nacional, Regime Normal, etc.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "Crt": { "type": "integer", "description": "Código de Regime Tributário (CRT) da empresa." }, "CrtDescription": { "type": "string", "maxLength": 100, "description": "Descrição do regime (`Simples Nacional`, `Lucro Presumido`, `Lucro Real`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/mod-emi": { "get": { "operationId": "typeTaxModEmiList", "tags": [ "Tipos — Impostos" ], "summary": "Lista modelos de documento fiscal", "description": "Lista os modelos de documento fiscal (NF-e 55, NFC-e 65, NFS-e, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfModNf": { "type": "integer", "description": "Código da modalidade do documento fiscal (`55` NF-e, `65` NFC-e, `57` CT-e, etc.)." }, "NfModNfDescription": { "type": "string", "maxLength": 100, "description": "Descrição da modalidade." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/invoice/mod-frete": { "get": { "operationId": "typeTaxModFreteList", "tags": [ "Tipos — Nota Fiscal" ], "summary": "Lista modalidades de frete", "description": "Lista as modalidades de frete da NF-e (CIF, FOB, por conta de terceiros, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfModFrete": { "type": "integer", "description": "Código da modalidade de frete na NF-e." }, "NfModFreteDescription": { "type": "string", "maxLength": 200, "nullable": true, "description": "Descrição da modalidade (`Emitente`, `Destinatário`, `Terceiros`, `Sem frete`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/mot-des-icms": { "get": { "operationId": "typeTaxMotDesIcmsList", "tags": [ "Tipos — Impostos" ], "summary": "Lista motivos de desoneração de ICMS", "description": "Lista os motivos válidos para desoneração de ICMS.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfMotDesICMS": { "type": "integer", "description": "Código do motivo de desoneração de ICMS." }, "NfMotDesICMSDescription": { "type": "string", "maxLength": 200, "description": "Descrição do motivo de desoneração." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/nbs": { "get": { "operationId": "typeTaxNbs", "tags": [ "Tipos — Impostos" ], "summary": "Lista códigos NBS", "description": "Lista os códigos NBS (Nomenclatura Brasileira de Serviços). Sem o parâmetro `NBS`, retorna a lista paginada com `NBS` e `Description`. Quando `NBS` é informado (pontos opcionais), retorna um único objeto detalhado com os `CIndOp` aplicáveis e o `IBSLocation` de cada um.", "parameters": [ { "name": "NBS", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código NBS exato. Aceita formato com ou sem pontos (ex.: `1.0801.10.00` ou `108011000`). Quando informado, retorna o detalhe — caso contrário a lista geral." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "description": "Quando `NBS` não é informado: lista geral.", "items": { "type": "object", "properties": { "NBS": { "type": "string", "description": "Código NBS formatado com pontos (`1.0801.10.00`)." }, "Description": { "type": "string", "description": "Descrição do serviço (NBS) ou da categoria, conforme o modo de resposta." } } } }, { "type": "object", "description": "Quando `NBS` é informado: detalhe do código.", "properties": { "NBS": { "type": "string", "description": "Código do serviço na NBS (Nomenclatura Brasileira de Serviços)." }, "Description": { "type": "string", "description": "Descrição do serviço (NBS) ou da categoria, conforme o modo de resposta." }, "CIndOp": { "type": "array", "items": { "type": "object", "properties": { "CIndOp": { "type": "string", "description": "Código do indicador de operação (`cIndOp`) conforme leiaute da Reforma Tributária." }, "IBSLocation": { "type": "string", "description": "Código de localização IBS associado ao indicador de operação." } } }, "description": "Lista de códigos de indicador de operação (`CIndOp`) e respectivos códigos de localização IBS." } } } ] } } } }, "400": { "description": "Erro de validação. Mensagens possíveis:\n- `[BadRequest] - NBS não encontrado` — O código informado não existe na base.\n- `[BadRequest] - Erro ao listar NBS` — Falha ao consultar a base de NBS.\n- `[BadRequest] - Erro ao buscar NBS` — Falha ao consultar o detalhe do NBS informado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/pag-band": { "get": { "operationId": "typeTaxPagBandList", "tags": [ "Tipos — Impostos" ], "summary": "Lista bandeiras de cartão (NF-e)", "description": "Lista as bandeiras de cartão aceitas no campo de pagamento da NF-e.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "NfTBand": { "type": "string", "maxLength": 2, "description": "Código da bandeira do cartão na NF-e." }, "NfTBandDescription": { "type": "string", "maxLength": 100, "description": "Nome da bandeira (`Visa`, `Mastercard`, `Elo`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/tax/pag-type": { "get": { "operationId": "typeTaxPagTypeList", "tags": [ "Tipos — Impostos" ], "summary": "Lista categorias de pagamento (NF-e)", "description": "Lista as categorias de pagamento aceitas no campo de pagamento da NF-e.", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypePaymentCategory": { "type": "integer", "description": "Identificador da categoria de pagamento." }, "TypePaymentCategory": { "type": "string", "maxLength": 100, "description": "Descrição da categoria (`Dinheiro`, `Cartão de crédito`, `Pix`, `Boleto`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/tracking-status": { "get": { "operationId": "typeTrackingStatusList", "tags": [ "Tipos — Pedido" ], "summary": "Lista status de rastreamento", "description": "Lista os status de rastreamento. Quando filtrado, retorna apenas status que possuem template de e-mail associado.", "parameters": [ { "name": "EmailTemplate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Quando `1`, retorna apenas status com template de e-mail." } ], "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDStatusTracking": { "type": "integer", "description": "Identificador do status de rastreio." }, "StatusTracking": { "type": "string", "maxLength": 45, "description": "Descrição do status de rastreio (`Coletado`, `Em trânsito`, `Entregue`, `Devolvido`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/sku/warehouse": { "get": { "operationId": "typeWarehouseTypeList", "tags": [ "Tipos — SKU" ], "summary": "Lista tipos de depósito", "description": "Lista os tipos de depósito disponíveis (próprio, em trânsito, fulfillment, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeStockKeepingUnitWarehouse": { "type": "integer", "description": "Identificador do tipo de armazém." }, "TypeStockKeepingUnitWarehouse": { "type": "string", "maxLength": 45, "nullable": true, "description": "Descrição do tipo (`Padrão`, `Divergência`, `Quarentena`, `Bloqueio`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/hub/product/question-answer": { "get": { "operationId": "typehubProductQuestionAnswerList", "tags": [ "Hub — Tipos de Referência" ], "summary": "Lista status de pergunta de produto (Hub)", "description": "Lista os status possíveis de uma pergunta de produto em marketplaces (pendente, respondida, descartada, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDTypeHubProductQuestionAnswerStatus": { "type": "integer", "description": "Identificador do status de perguntas/respostas do produto no canal.", "enum": [ 1, 2, 3, 4, 7 ] }, "TypeHubProductQuestionAnswerStatus": { "type": "string", "maxLength": 45, "description": "Descrição do status (`Não respondida`, `Respondida`, `Excluída`, etc.)." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/user": { "get": { "operationId": "userJobPositionList", "tags": [ "Tipos — Usuário" ], "summary": "Lista cargos de usuário", "description": "Lista os cargos cadastrados para usuários (vendedor, gestor, etc.).", "responses": { "200": { "description": "Lista retornada.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDUserJobPosition": { "type": "integer", "description": "Identificador da função/cargo do usuário." }, "UserJobPositionName": { "type": "string", "maxLength": 45, "description": "Nome da função/cargo (ex.: `Operador`, `Separador`, `Conferente`, `Gestor`)." }, "UserJobPositionCategory": { "type": "string", "maxLength": 100, "nullable": true, "description": "Categoria da função, quando agrupada." } } } } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/type/{idordertype}/type-tax": { "parameters": [ { "name": "idordertype", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do tipo de pedido (`IDTypeOrder`)." } ], "post": { "operationId": "orderTypeOrderTaxPost", "tags": [ "Tipos — Pedido" ], "summary": "Vincula uma regra fiscal a um tipo de pedido", "description": "Cadastra uma nova vinculação entre um **tipo de pedido** e uma **regra fiscal** (`TypeTax`). Cada tipo de pedido só pode ter **uma vinculação por departamento fiscal** — se já existir uma vinculação para a mesma combinação (tipo de pedido × departamento fiscal da regra), a chamada falha.\n\nA resposta é o detalhe completo do tipo de pedido atualizado (mesmo formato do `GET /type/order/type/{idordertype}`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDTax" ], "properties": { "IDTax": { "type": "integer", "description": "Identificador da regra fiscal a ser vinculada. Precisa pertencer à mesma empresa e ter `Status = 1` no departamento fiscal correspondente." } } } } }, "description": "Vincula uma regra fiscal (CFOP) ao tipo de pedido. Apenas `IDTax` no corpo. O sistema valida que a regra existe, pertence à empresa autenticada e que ainda não existe outra regra do mesmo departamento fiscal vinculada a este tipo de pedido (apenas uma regra por departamento por tipo)." }, "responses": { "200": { "description": "Vinculação criada. Retorna o detalhe atualizado do tipo de pedido (`OrderTypeOrderGet`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeOrderDetail" } } } } }, "400": { "description": "Erro de validação. Mensagens possíveis:\n- `[BadRequest] - Tipo pedido não existe` — `idordertype` inválido ou de outra empresa.\n- `[BadRequest] - Regra tributária não existe` — `IDTax` inválido, de outra empresa ou inativa.\n- `[BadRequest] - Já existe uma regra tributária para esse tipo de pedido` — já existe vinculação para o mesmo departamento fiscal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/type/order/type/{idordertype}/type-tax/{idtypeordertax}": { "parameters": [ { "name": "idordertype", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do tipo de pedido (`IDTypeOrder`)." }, { "name": "idtypeordertax", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da vinculação tipo-pedido × regra fiscal (`IDTypeOrderTax`)." } ], "put": { "operationId": "orderTypeOrderTaxPut", "tags": [ "Tipos — Pedido" ], "summary": "Altera a regra fiscal vinculada ao tipo de pedido", "description": "Atualiza a regra fiscal (`IDTax`) de uma vinculação existente entre tipo de pedido e regra fiscal. Como cada tipo de pedido só pode ter uma vinculação por departamento fiscal, a chamada falha se a nova regra recair no mesmo departamento fiscal de outra vinculação do mesmo tipo de pedido.\n\nA resposta é o detalhe completo do tipo de pedido atualizado (mesmo formato do `GET /type/order/type/{idordertype}`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDTax" ], "properties": { "IDTax": { "type": "integer", "description": "Nova regra fiscal a vincular. Precisa pertencer à mesma empresa e ter `Status = 1`." } } } } }, "description": "Atualiza a regra fiscal vinculada ao tipo de pedido — apenas o campo `IDTax`. Mesmas validações do POST (regra existe na empresa; sem duplicidade de departamento fiscal no mesmo tipo de pedido)." }, "responses": { "200": { "description": "Vinculação atualizada. Retorna o detalhe atualizado do tipo de pedido.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeOrderDetail" } } } } }, "400": { "description": "Erro de validação. Mensagens possíveis:\n- `[BadRequest] - Tipo pedido não existe` — `idordertype` inválido ou de outra empresa.\n- `[BadRequest] - Regra tributária não existe` — `IDTax` inválido, de outra empresa ou inativa.\n- `[BadRequest] - Regra tributário do tipo de pedido não existe` — `idtypeordertax` inválido.\n- `[BadRequest] - Já existe uma regra tributária para esse tipo de pedido` — a nova regra cai no mesmo departamento fiscal de outra vinculação do mesmo tipo de pedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "orderTypeOrderTaxDelete", "tags": [ "Tipos — Pedido" ], "summary": "Remove a regra fiscal vinculada ao tipo de pedido", "description": "Remove uma vinculação existente entre tipo de pedido e regra fiscal.\n\nA resposta é o detalhe completo do tipo de pedido atualizado (mesmo formato do `GET /type/order/type/{idordertype}`).", "responses": { "200": { "description": "Vinculação removida. Retorna o detalhe atualizado do tipo de pedido.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TypeOrderDetail" } } } } }, "400": { "description": "Vinculação não encontrada. Mensagem: `[BadRequest] - Regra tributário do tipo de pedido não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Erro interno (prefixo `Error:`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/sku": { "get": { "operationId": "skuList", "tags": [ "Produtos e SKUs" ], "summary": "Lista SKUs da empresa", "description": "Lista SKUs paginados (lote de 500 por página em ambos os modos; offset = `Page × 500`). Aplica filtros, busca textual e variantes de cálculo de preço, estoque e métricas de venda conforme os parâmetros.", "parameters": [ { "name": "Page", "in": "query", "schema": { "type": "integer" }, "description": "Página (offset = `Page * 500`)." }, { "name": "Simple", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` retorna lista reduzida (resposta `SkuListItemSimple`). `0` retorna o detalhamento padrão." }, { "name": "Sales", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` inclui métricas históricas de venda no retorno." }, { "name": "Search", "in": "query", "schema": { "type": "string" }, "description": "Busca textual contra `IDSku`, nome `SkuName`, código de barras `BarCode` e código de referência `IDSkuCompany`. Espaços viram curinga interno." }, { "name": "IDSku", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador do produto/SKU." }, { "name": "SkuName", "in": "query", "schema": { "type": "string" }, "description": "Nome do SKU (busca `LIKE`)." }, { "name": "BarCode", "in": "query", "schema": { "type": "string" }, "description": "Código de barras exato. Aceita também códigos de balança quando a parametrização de uso de balança está ativa." }, { "name": "IDTypeSku", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo tipo de SKU." }, { "name": "IDBrand", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador da marca." }, { "name": "IDCategory", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador da categoria." }, { "name": "IDStatusSku", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ] } }, "description": "Lista de status separados por vírgula. Default `1,2,3,4`.", "style": "form", "explode": false }, { "name": "IDSkuCompany", "in": "query", "schema": { "type": "string" }, "description": "Código de referência (busca `LIKE`)." }, { "name": "IDSkuCompanyStrict", "in": "query", "schema": { "type": "string" }, "description": "Código de referência exato (sem `LIKE`)." }, { "name": "SupplierCode", "in": "query", "schema": { "type": "string" }, "description": "Código do fornecedor." }, { "name": "IDSupplier", "in": "query", "schema": { "type": "integer" }, "description": "Identificador do fornecedor." }, { "name": "IDSupplierCost", "in": "query", "schema": { "type": "integer" }, "description": "Quando informado, inclui o `LastValueCost` daquele fornecedor no item retornado (apenas no modo Simple)." }, { "name": "Package", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo tipo de embalagem." }, { "name": "IDCompanyIntegration", "in": "query", "schema": { "type": "integer" }, "description": "Filtra SKUs com vínculo à integração." }, { "name": "IDCompanyIntegrationNot", "in": "query", "schema": { "type": "integer" }, "description": "Filtra SKUs sem vínculo à integração." }, { "name": "IDTypeCompanyIntegration", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo tipo de integração da empresa." }, { "name": "IDTypeCompanyIntegrationNot", "in": "query", "schema": { "type": "integer" }, "description": "Exclui do resultado o tipo de integração da empresa informado." }, { "name": "SinceIDSku", "in": "query", "schema": { "type": "integer" }, "description": "Retorna apenas SKUs com `IDSku` maior ou igual ao informado." }, { "name": "SinceRecordTimestamp", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filtra registros criados a partir desta data/hora (formato ISO 8601)." }, { "name": "SinceDateLastRecordModification", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filtra registros modificados a partir desta data/hora (formato ISO 8601). Útil para sincronização incremental." }, { "name": "IDCompanyInvoice", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador da nota fiscal da empresa." }, { "name": "IDTypeBuyOrderMake", "in": "query", "schema": { "type": "integer", "enum": [ 1, 2, 3 ] }, "description": "Filtra pela sinalização de pedido de compra recomendado. Default `4`." }, { "name": "IDCompanySalesPolicy", "in": "query", "schema": { "type": "integer" }, "description": "Política comercial usada para `PriceSell`/`PriceList` no retorno." }, { "name": "AbcCurve", "in": "query", "schema": { "type": "string", "enum": [ "A", "B", "C" ] }, "description": "Filtra pela classificação da curva ABC do produto (`A`, `B` ou `C`)." }, { "name": "OwnProduction", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, restringe a itens de produção própria." }, { "name": "HasSupplier", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` SKUs com fornecedor cadastrado; `0` sem fornecedor." }, { "name": "Tags", "in": "query", "schema": { "type": "string" }, "description": "Lista de etiquetas (combinadas com `AND`)." }, { "name": "HasNoProduct", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` exclui SKUs vinculados a um produto-pai." }, { "name": "DateFrom", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filtra por `RecordTimestamp` a partir desta data." }, { "name": "DateTo", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Filtra por `RecordTimestamp` até esta data (inclusiva)." }, { "name": "QtyAvailable", "in": "query", "schema": { "type": "integer" }, "description": "Quantidade de referência para `HealthType`." }, { "name": "HealthType", "in": "query", "schema": { "type": "string", "enum": [ "greater", "smaller" ] }, "description": "Filtra SKUs com saldo maior ou menor que `QtyAvailable`." }, { "name": "SkuSimilarCode", "in": "query", "schema": { "type": "string" }, "description": "Filtra por SKUs em grupos que contenham este código similar." }, { "name": "IDStockKeepingUnitCollection", "in": "query", "schema": { "type": "integer" }, "description": "Filtra por coleção." }, { "name": "IDStockKeepingUnitLocationCategory", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador da categoria de localização do SKU." }, { "name": "IDStockKeepingUnitWarehouse", "in": "query", "schema": { "type": "string" }, "description": "Lista de armazéns separados por vírgula. Quando informado, as métricas de venda e estoque são restritas a esses armazéns." }, { "name": "IDTypeOrder", "in": "query", "schema": { "type": "integer" }, "description": "Quando informado, aplica a margem de segurança `SafetyStockPercent` do tipo de pedido sobre `QtyAvailable`." } ], "responses": { "200": { "description": "Lista de SKUs.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SkuListItemSimple" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SkuListItem" } } ] } } } }, "400": { "description": "Erro de validação dos filtros enviados." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "post": { "operationId": "skuPost", "tags": [ "Produtos e SKUs" ], "summary": "Cria um SKU", "description": "Cria um SKU com validações de marca, categoria, departamento fiscal, faturador, linha de produção, unidade de medida e tipo. Quando `PriceList`/`PriceSell` são enviados, cria um registro inicial de preço. Quando `Variations` é enviado, vincula valores de variação. Não permite duplicar `IDSkuCompany` nem `BarCode` para a empresa.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuCreateBody" } } }, "description": "Dados do SKU a cadastrar. `IDTypeSku` é obrigatório e define o tipo do SKU (produto normal, kit, variação, serviço, etc.). Quando o SKU é uma variação (`IDTypeSku=4` no produto-pai), informe `IDSkuCompanyComposing` para vincular a variação ao produto-pai. Preço inicial (`PriceSell`, `PriceList`) e variações iniciais (`Variations[]`) podem ser cadastrados na mesma requisição." }, "responses": { "200": { "description": "SKU criado. Retorna um array com o detalhe do SKU recém-criado, incluindo campos de sugestão de compra (`StockSafety`, `StockFree`, `StockReference`, `BuyOrderMake`, `IDTypeBuyOrderMake`, `BuyOrderMakeQuantity`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuListItem" } } } } }, "400": { "description": "Validação falhou. Prefixo `[BadRequest]`. Mensagens: `Marca não existe`, `Categoria não existe`, `Cód. referência já existe na base`, `Código de Barras já existe na base`, `Departamento fiscal não existe`, `Tipo sku não existe`, `Origem SKU não existe`, `Faturador não existe`, `Medida SKU não existe`, `Linha de produção não existe`, `Politica comercial não existe`, `Variação X e Grade Y não existe`, `Campo Tipo variação e Valor variação não enviados`, `Categoria localização não existe`, `Erro ao criar item`." }, "404": { "description": "Empresa não localizada. Prefixo `[NotFound]`. Mensagem: `Empresa não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } }, "parameters": [ { "name": "Composing", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Quando informado (valor verdadeiro), cria o SKU como componente/kit vinculado a um produto-pai: o código de referência recebe o sufixo `-KIT` derivado de `IDSkuCompanyComposing`, em vez de ser preenchido automaticamente com o `IDSku`." } ] } }, "/sku/{idsku}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do SKU." } ], "get": { "operationId": "skuGet", "tags": [ "Produtos e SKUs" ], "summary": "Detalha um SKU", "description": "Retorna o detalhe completo do SKU, com listas relacionadas (fornecedores, códigos de barras adicionais, embalagens) e campos calculados (saldo, custos, valor em estoque). Quando `Sales=1`, troca o detalhe pelas métricas históricas de venda calculadas a partir dos últimos 150 dias.", "parameters": [ { "name": "Sales", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` para retornar métricas históricas de venda em vez do detalhe completo." } ], "responses": { "200": { "description": "SKU encontrado. Lista com um único elemento (ou vazia, se não encontrar).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuDetail" } } } } }, "400": { "description": "Parâmetro de path ausente. Prefixo `[BadRequest]`. Mensagem: `não localizado`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "put": { "operationId": "skuPut", "tags": [ "Produtos e SKUs" ], "summary": "Atualiza um SKU", "description": "Atualiza os campos enviados do SKU. Alterações de `IDTypeSku` exigem que o item não tenha movimentações, lote, vínculo com kit, variação nem produto-pai. Alterações em `BarCode` validam unicidade contra códigos principais, adicionais e de embalagem da mesma empresa.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuUpdateBody" } } }, "description": "Atualização parcial do SKU — envie apenas os campos que quer alterar; os demais permanecem com o valor atual. Alterar `IDTypeSku` é restrito: o SKU não pode ter movimentação, lote, ser componente de kit, ter variação nem ser produto-pai (ver erros 400)." }, "responses": { "200": { "description": "SKU atualizado. Retorna o detalhe atualizado via `skuGet`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuDetail" } } } } }, "400": { "description": "Validação falhou. Prefixo `[BadRequest]`. Mensagens: `não localizado`, `NCM EX TIPI precisa ter 2 ou 3 dígitos`, `Marca não existe`, `Categoria não existe`, `Cod. Referência já existe na base`, `Código de Barras já existe no sku: `, `Departamento fiscal não existe`, `Não pode alterar o tipo de um item criado há mais de 30 dias`, `Item já teve movimentação ... não pode ser alterado o tipo`, `Item tem lote/composição/grade/sku filho ...`, `Tipo SKU não existe`, e variantes relacionadas a regras de mudança de tipo." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "delete": { "operationId": "skuDelete", "tags": [ "Produtos e SKUs" ], "summary": "Exclui um SKU", "description": "Remove o SKU. Bloqueia a exclusão se houver movimentação cadastrada ou se o SKU estiver anunciado em alguma integração — nesses casos a recomendação é alterar o status para inativo.", "responses": { "200": { "description": "SKU excluído.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Bloqueio. Prefixo `[BadRequest]`. Mensagens: `Sku já teve movimentação e não pode ser excluido. Alterar status para inativo`, `Sku tem anúncio e precisa remover antes de excluir o sku`, `Sku não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/image/{idsku}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "skuImageGet", "tags": [ "Imagens de SKU" ], "summary": "Lista as imagens de um SKU", "description": "Retorna as imagens do SKU ordenadas por `ImageOrder`. Quando o SKU está configurado para herdar imagens do produto-pai (`ShareProductImage = 1`), inclui também as imagens deste com `ProductImage = 1`.", "responses": { "200": { "description": "Lista de imagens.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuImage" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "post": { "operationId": "skuImagePost", "tags": [ "Imagens de SKU" ], "summary": "Envia uma imagem para o SKU", "description": "Aceita imagem via upload multipart (campo `file`) ou via URL externa (campo `Url` no JSON do body). A primeira imagem cadastrada vira automaticamente a principal. Quando `IDHubProduct` ou `IDHubAdvertisement` é informado, a imagem é vinculada ao anúncio correspondente.", "parameters": [ { "name": "Invoke", "in": "query", "schema": { "type": "string" }, "description": "Nome da rotina a executar após o upload, para refletir a alteração em uma integração específica." }, { "name": "IDImage", "in": "query", "schema": { "type": "integer" }, "description": "Quando informado, atualiza a imagem existente." }, { "name": "OnlyAdvertisement", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` salva a imagem como exclusiva de anúncio (não aparece na ficha do SKU)." }, { "name": "IDHubProduct", "in": "query", "schema": { "type": "integer" }, "description": "Vincula a imagem a um anúncio (produto no hub)." }, { "name": "IDHubAdvertisement", "in": "query", "schema": { "type": "integer" }, "description": "Vincula a imagem a uma variação de anúncio (SKU no hub)." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Arquivo de imagem." } } } }, "application/json": { "schema": { "type": "object", "properties": { "Url": { "type": "string", "description": "URL externa da imagem; o serviço baixa e armazena." } } } } }, "description": "Corpo do `POST /sku/image/{idsku}`: aceita três formatos — arquivo binário em `multipart/form-data` no campo `file`; corpo JSON `{ \"Url\": \"\" }` para baixar a imagem de uma URL; ou nenhum corpo quando a query traz `IDImage` (clonar uma imagem existente para o SKU). Demais opções (clone para anúncio, ordem, principal) vêm pela query string." }, "responses": { "200": { "description": "Imagem cadastrada.", "content": { "application/json": { "schema": { "type": "object", "description": "Retorno da rotina executada (varia conforme `Invoke`).", "additionalProperties": true } } } }, "400": { "description": "Anúncio inválido ou arquivo recusado. Mensagens variam: `Anúncio não encontrado`, `Variação anúncio não encontrada` (retornadas como `statusCode: 400`)." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/image/{idsku}/{idimage}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idimage", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da imagem." } ], "put": { "operationId": "skuImagePut", "tags": [ "Imagens de SKU" ], "summary": "Atualiza uma imagem do SKU", "description": "Atualiza atributos da imagem (principal, ordem, nome, variante de kit, URL).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "IsMain": { "type": "integer", "description": "`1` define como imagem principal." }, "ImageName": { "type": "string", "maxLength": 300, "description": "Novo nome de exibição da imagem." }, "Kit": { "type": "integer", "description": "Variante do kit (1 a 4) à qual a imagem se aplica." }, "Url": { "type": "string", "maxLength": 400, "description": "Nova URL da imagem." }, "ImageOrder": { "type": "integer", "description": "Ordem de exibição." } } } } }, "description": "Campos da imagem do SKU a atualizar — apenas os enviados são aplicados. Aceita `IsMain` (marca como imagem principal), `ImageName`, `Kit`, `Url` e `ImageOrder`." }, "responses": { "200": { "description": "Imagem atualizada. Retorna `skuImageGet`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuImage" } } } } }, "400": { "description": "SKU/imagem não encontrada. Prefixo `[BadRequest]`. Mensagem: `Company não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "delete": { "operationId": "skuImageDelete", "tags": [ "Imagens de SKU" ], "summary": "Remove uma imagem do SKU", "description": "Remove a imagem. Quando a imagem ainda está vinculada a um anúncio em hub, em vez de excluir, marca-a como exclusiva de anúncio (`OnlyAdvertisement = 1`). Quando a imagem removida era a principal, promove a próxima imagem por ordem.", "responses": { "200": { "description": "Imagem removida. Retorna `skuImageGet`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuImage" } } } } }, "400": { "description": "Imagem não pertence ao SKU/empresa. Prefixo `[BadRequest]`. Mensagem: `Sku não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/kit/summary/{idsku}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "kitSummaryGet", "tags": [ "Kits" ], "summary": "Resumo dos kits (variantes) de um SKU", "description": "Retorna o resumo de cada variante de kit do SKU (até 4 variantes), com quantidade montável, soma de preço/custo dos componentes e markup.", "responses": { "200": { "description": "Resumo das variantes.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KitSummary" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/kit/summary/{idsku}/{idstockkeepingunitkit}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idstockkeepingunitkit", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da variante de kit." } ], "put": { "operationId": "kitSummaryPut", "tags": [ "Kits" ], "summary": "Atualiza prioridade de uma variante de kit", "description": "Ajusta a prioridade de uma variante de kit do SKU. Aceita apenas para SKUs do tipo 1 ou 2.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Priority" ], "properties": { "Priority": { "type": "integer", "description": "Ordem de prioridade da variante." } } } } }, "description": "Corpo do `PUT /sku/kit/summary/{idsku}/{idstockkeepingunitkit}`: atualiza a prioridade do agrupamento do kit. Campos: `Priority` (obrigatório) e `IDStockKeepingUnitKit` (opcional — se omitido, usa o identificador do path)." }, "responses": { "200": { "description": "Prioridade atualizada. Retorna `kitGet`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KitItem" } } } } }, "400": { "description": "SKU não localizado ou não suporta kit. Prefixo `[BadRequest]`. Mensagem: `Sku não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/kit/{idsku}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "kitGet", "tags": [ "Kits" ], "summary": "Lista os componentes de um kit", "description": "Lista os componentes do kit selecionado (`kit=1..4`). Quando `Type=KitsRelated`, inverte a perspectiva e lista os kits em que este SKU aparece como componente.", "parameters": [ { "name": "kit", "in": "query", "schema": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "description": "Variante do kit. Default `1`." }, { "name": "Type", "in": "query", "schema": { "type": "string", "enum": [ "Components", "KitsRelated" ] }, "description": "`Components` lista componentes do kit do SKU; `KitsRelated` lista kits que usam este SKU como componente. Default `Components`." } ], "responses": { "200": { "description": "Lista de componentes (ou kits relacionados).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KitItem" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "post": { "operationId": "kitPost", "tags": [ "Kits" ], "summary": "Adiciona um componente ao kit", "description": "Adiciona um SKU componente à variante de kit do SKU pai. Quando a empresa usa atualização automática de medidas de kit, recalcula peso e dimensões do SKU pai a partir dos componentes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDSkuComponent", "Quantity" ], "properties": { "IDSkuComponent": { "type": "integer", "description": "SKU usado como componente. Precisa ser do tipo Sku, Matéria-prima ou Uso e consumo (`IDTypeSku` em 3, 6 ou 7)." }, "Quantity": { "type": "number", "description": "Quantidade do componente. Precisa ser maior que zero." }, "Kit": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Variante do kit. Default `1`." } } } } }, "description": "Dados do item componente do kit a adicionar. Obrigatórios: `IDSkuComponent` (SKU componente — precisa ser do tipo normal) e `Quantity` (maior que zero). Opcional: `Kit` (número do agrupamento dentro do kit; padrão 1)." }, "responses": { "200": { "description": "Componente adicionado. Retorna `kitGet`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KitItem" } } } } }, "400": { "description": "Validação falhou. Prefixo `[BadRequest]`. Mensagens: `Quantidade precisa ser maior que 0`, `Sku não existe`, `Sku Componente não existe`, `Componente não é do tipo normal`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/kit/{idsku}/{idstockkeepingunitkititems}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idstockkeepingunitkititems", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do componente dentro do kit." } ], "put": { "operationId": "kitPut", "tags": [ "Kits" ], "summary": "Atualiza um componente do kit", "description": "Troca o SKU componente, quantidade ou variante de kit do item. Recalcula medidas do SKU pai quando a atualização automática está habilitada.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDSkuComponent", "Quantity" ], "properties": { "IDSkuComponent": { "type": "integer", "description": "Identificador do SKU componente do kit." }, "Quantity": { "type": "number", "description": "Quantidade do componente no kit." }, "Kit": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Tipo de composição do kit: `1` Kit fixo, `2` Kit dinâmico, `3` Combo, `4` Grade." } } } } }, "description": "Campos do item componente do kit a atualizar. Aceita `IDSkuComponent` (componente — precisa ser do tipo normal), `Quantity` (maior que zero) e `Kit` (número do agrupamento; padrão 1)." }, "responses": { "200": { "description": "Componente atualizado. Retorna `kitGet`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KitItem" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Quantidade precisa ser maior que 0`, `Sku não existe`, `Sku Componente não existe`, `Componente não é do tipo normal`, `Erro ao processar a solicitação`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "delete": { "operationId": "kitDelete", "tags": [ "Kits" ], "summary": "Remove um componente do kit", "description": "Remove o componente do kit. Recalcula medidas do SKU pai quando a atualização automática está habilitada.", "responses": { "200": { "description": "Componente removido. Retorna `kitGet`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KitItem" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Falha ao deletar item kit`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/log": { "get": { "operationId": "skuLogList", "tags": [ "Log de SKU" ], "summary": "Lista logs de integração de SKU", "description": "Lista o histórico de integração dos SKUs (envios para hubs, alterações registradas). Paginação fixa de 4000 registros por página em ordem decrescente de id.", "parameters": [ { "name": "Page", "in": "query", "schema": { "type": "integer" }, "description": "Página (offset = `Page * 5000`)." }, { "name": "IDSku", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador do produto/SKU." }, { "name": "IDSkuCompany", "in": "query", "schema": { "type": "string" }, "description": "Código de referência (busca `LIKE`)." }, { "name": "SkuName", "in": "query", "schema": { "type": "string" }, "description": "Nome do SKU (busca `LIKE`)." }, { "name": "IDCompanyIntegration", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador da integração da empresa." }, { "name": "IDHubProduct", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador do produto no hub." }, { "name": "IDAction", "in": "query", "schema": { "type": "integer" }, "description": "Tipo de ação (`IDSkuAction`)." }, { "name": "Status", "in": "query", "schema": { "type": "integer" }, "description": "Filtra por `Header`: `1` sucesso, `2` inativo, outros = erro." }, { "name": "DateFrom", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Início do intervalo de datas no filtro (formato `YYYY-MM-DD`)." }, { "name": "DateTo", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo de datas no filtro (formato `YYYY-MM-DD`)." }, { "name": "IDStockKeepingUnitIntegrationLog", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador do log de integração do SKU." } ], "responses": { "200": { "description": "Lista de logs.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuLogItem" } } } } }, "400": { "description": "Erro de configuração da empresa. Prefixo `[BadRequest]`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/package": { "get": { "operationId": "skuPackageList", "tags": [ "Tipos de Embalagem" ], "summary": "Lista SKUs embalagem compartilhados", "description": "Lista os SKUs marcados como embalagem (`Package=1`) ativos. Inclui também SKUs de empresas relacionadas via integração quando essas empresas habilitam o compartilhamento de embalagens.", "parameters": [ { "name": "Page", "in": "query", "schema": { "type": "integer" }, "description": "Página (offset = `Page * 400`)." } ], "responses": { "200": { "description": "Lista de SKUs embalagem.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPackageItem" } } } } }, "400": { "description": "Erro de configuração da empresa. Prefixo `[BadRequest]`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/pricing": { "get": { "operationId": "skuPricingList", "tags": [ "Preços" ], "summary": "Lista preços de SKUs", "description": "Lista os preços cadastrados em cada política comercial. Paginação fixa de 2000 registros. Os filtros permitem cruzar por SKU, política, integração e janela de modificação.", "parameters": [ { "name": "Page", "in": "query", "schema": { "type": "integer" }, "description": "Página (offset = `Page * 2000`)." }, { "name": "IDSku", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador do produto/SKU." }, { "name": "SkuName", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo nome do produto (busca parcial)." }, { "name": "BarCode", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo código de barras do produto." }, { "name": "IDTypeSku", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo tipo de SKU." }, { "name": "IDBrand", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador da marca." }, { "name": "IDCategory", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador da categoria." }, { "name": "SupplierCode", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo código interno do fornecedor." }, { "name": "IDSupplier", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador do fornecedor." }, { "name": "Package", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo tipo de embalagem." }, { "name": "IDSkuCompany", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo identificador do vínculo SKU-empresa." }, { "name": "IDStockKeepingUnitPricing", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador da regra de precificação do SKU." }, { "name": "IDCompanySalesPolicy", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pela política de venda da empresa." }, { "name": "IDTypeCompanyIntegration", "in": "query", "schema": { "type": "integer" }, "description": "Filtra políticas que estão vinculadas a alguma integração deste tipo." }, { "name": "SinceDateLastRecordModification", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filtra registros modificados a partir desta data/hora (formato ISO 8601). Útil para sincronização incremental." }, { "name": "SinceDateLastRecordModificationFrom", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Início do intervalo da data da última modificação (formato ISO 8601)." }, { "name": "SinceDateLastRecordModificationTo", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Fim do intervalo da data da última modificação (formato ISO 8601)." } ], "responses": { "200": { "description": "Lista de preços.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPricing" } } } } }, "400": { "description": "Erro de configuração da empresa. Prefixo `[BadRequest]`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/pricing/{idsku}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "skuPricingPost", "tags": [ "Preços" ], "summary": "Cria um preço para o SKU", "description": "Cria um preço para o SKU numa política comercial (quando omitida, usa a política padrão da empresa). Com `UpdateIfPossible=1`, atualiza o preço já existente do SKU nessa política em vez de criar outro. Numa política do tipo Relativa à outra política, o preço é derivado do preço da política base; ao criar preço numa política Normal, os preços das políticas relativas derivadas dela são recalculados automaticamente. Preço de venda zerado é rejeitado quando a empresa não permite.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuPricingCreateBody" } } }, "description": "Dados da faixa de preço a cadastrar para o SKU. Obrigatórios: `PriceList` (preço de tabela), `PriceSell` (preço de venda), `DateFrom` e `DateTo` (datas válidas — vigência). Opcional: `IDCompanySalesPolicy` (política comercial associada — quando omitido, usa a política padrão da empresa)." }, "responses": { "200": { "description": "Preço criado. Retorna `skuPricingList` filtrado pelo SKU.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPricing" } } } } }, "400": { "description": "Validação falhou. Prefixo `[BadRequest]`. Mensagens: `Data DE ou ATÉ inválida`, `Sku não existe`, `Politica comercial não existe`, `Empresa não tem politica comercial padrão`, `Já existe um preço para essa política comercial e não pode ser criado outro (parametrização)`, `Não foi localizado preço da política comercial base: `, `Não é permitido inserir preço de venda zerado. Validar configuração da empresa`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } }, "parameters": [ { "name": "UpdateIfPossible", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1 ] }, "description": "Quando `1`, faz upsert: se já existe preço do SKU para a política, atualiza esse preço (valores e vigência) em vez de criar outro, e ignora o bloqueio de preço duplicado por política. Ausente ou diferente de `1`: sempre cria um novo preço." } ] } }, "/sku/pricing/{idsku}/{idstockkeepingunitpricing}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idstockkeepingunitpricing", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do preço." } ], "put": { "operationId": "skuPricingPut", "tags": [ "Preços" ], "summary": "Atualiza um preço do SKU", "description": "Atualiza um preço cadastrado. Aplica as mesmas validações de política e preço-zero da criação.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuPricingCreateBody" } } }, "description": "Campos da faixa de preço a atualizar. Aceita `PriceList`, `PriceSell`, `DateFrom`, `DateTo` (datas precisam ser válidas), `IDCompanySalesPolicy` e `IDStockKeepingUnitPricing` (alternativa ao path)." }, "responses": { "200": { "description": "Preço atualizado. Retorna `skuPricingList` filtrado pelo SKU.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPricing" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Data DE ou ATÉ inválida`, `Preço SKU não existe`, `Politica comercial não existe`, `Empresa não tem politica comercial padrão`, `Já existe um preço para essa política comercial e não pode ser criado outro (parametrização)`, `Não foi localizado preço da política comercial base`, `Não é permitido inserir preço de venda zerado. Validar configuração da empresa`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "delete": { "operationId": "skuPricingDelete", "tags": [ "Preços" ], "summary": "Remove um preço do SKU", "description": "Remove um preço. Notifica webhooks da empresa e devolve a lista atualizada.", "responses": { "200": { "description": "Preço removido. Retorna `skuPricingList` filtrado pelo SKU.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPricing" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Precisa enviar os parametros corretos para excluir o preço`, `Preço Sku não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/similarcategory/{idsku}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "skuSimilarCategoryGet", "tags": [ "Categorias Similares" ], "summary": "Lista categorias similares do SKU", "description": "Lista as categorias adicionais associadas ao SKU para fins de classificação cruzada (recomendação, navegação alternativa).", "responses": { "200": { "description": "Lista de categorias similares.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSimilarCategory" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "post": { "operationId": "skuSimilarCategoryPost", "tags": [ "Categorias Similares" ], "summary": "Adiciona uma categoria similar ao SKU", "description": "Vincula uma categoria adicional ao SKU.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDCategory" ], "properties": { "IDCategory": { "type": "integer", "description": "Identificador da categoria a vincular." } } } } }, "description": "Corpo do `POST /sku/similarcategory/{idsku}`: associa uma categoria de produtos similares ao SKU. Campo obrigatório: `IDCategory` (categoria — precisa existir na empresa)." }, "responses": { "200": { "description": "Categoria adicionada. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSimilarCategory" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `IDCategory não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/similarcategory/{idsku}/{idstockkeepinunitsimilarcategory}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idstockkeepinunitsimilarcategory", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do vínculo SKU/categoria similar." } ], "delete": { "operationId": "skuSimilarCategoryDelete", "tags": [ "Categorias Similares" ], "summary": "Remove uma categoria similar do SKU", "description": "Remove o vínculo entre o SKU e a categoria similar.", "responses": { "200": { "description": "Vínculo removido. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSimilarCategory" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagem: `Sku não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/specification/{idsku}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "skuSpecificationGet", "tags": [ "Especificações de SKU" ], "summary": "Lista as especificações técnicas aplicáveis ao SKU", "description": "Retorna os campos de especificação configurados para a categoria do SKU (incluindo categorias-pai por herança), com o valor atual de cada um quando preenchido. Para campos de seleção, `FieldValue` traz a lista de valores escolhidos.", "responses": { "200": { "description": "Lista de campos de especificação.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSpecificationField" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "post": { "operationId": "skuSpecificationPost", "tags": [ "Especificações de SKU" ], "summary": "Define as especificações técnicas do SKU", "description": "Substitui completamente o conjunto de valores de especificação do SKU. Cada item do array referencia um campo cadastrado (`IDStockKeepingUnitSpecificationsFieldId`); o valor é literal para texto/número/data e um array de objetos com `IDStockKeepingUnitSpecificationsFieldValues` para campos de seleção.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "IDStockKeepingUnitSpecificationsFieldId" ], "properties": { "IDStockKeepingUnitSpecificationsFieldId": { "type": "integer", "description": "Identificador do campo de especificação a vincular ao SKU." }, "FieldValue": { "description": "Valor literal (string/number/date) ou array de objetos `{ IDStockKeepingUnitSpecificationsFieldValues }` para campos combo/radio." } } } } } }, "description": "Lista das especificações do SKU (array que substitui as especificações atuais). Cada item traz `IDStockKeepingUnitSpecificationsFieldId` (campo de especificação) e `FieldValue` (valor texto, ou — quando o campo é checkbox/combo/radio — array de objetos com `IDStockKeepingUnitSpecificationsFieldValues` referenciando os valores cadastrados)." }, "responses": { "200": { "description": "Especificações gravadas. Retorna `skuSpecificationGet`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSpecificationField" } } } } }, "404": { "description": "Prefixo `[NotFound]`. Mensagens: `Sku não encontrado`, `Especificação ID não encontrada`, `Valor especificação ID não encontrada`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/tag": { "get": { "operationId": "skuTagList", "tags": [ "Tags de SKU" ], "summary": "Lista etiquetas livres usadas em SKUs", "description": "Lista as etiquetas cadastradas em SKUs da empresa, ordenadas alfabeticamente. Filtro opcional por SKU.", "parameters": [ { "name": "IDSku", "in": "query", "schema": { "type": "integer" }, "description": "Restringe as etiquetas a um SKU específico." } ], "responses": { "200": { "description": "Lista de etiquetas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuTag" } } } } }, "400": { "description": "Erro de configuração da empresa. Prefixo `[BadRequest]`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/template": { "get": { "operationId": "skuFileTemplateExport", "tags": [ "Templates de Importação" ], "summary": "Exporta planilha modelo para importação de SKUs", "description": "Gera e devolve a planilha modelo (arquivo) usada para importar SKUs em lote.", "responses": { "200": { "description": "Planilha gerada. Resposta tipicamente como URL de download ou conteúdo binário.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "500": { "description": "Erro interno." } } }, "post": { "operationId": "skuFileTemplateImport", "tags": [ "Templates de Importação" ], "summary": "Importa planilha de SKUs (job assíncrono)", "description": "Recebe uma planilha multipart e dispara o job de importação correspondente. O job é executado de forma assíncrona — a resposta confirma o agendamento. O tipo de planilha é definido pelo query `Type` (`sku`, `spec`, `carrier`, `correios`, `carrierIntelipost`).", "parameters": [ { "name": "Type", "in": "query", "schema": { "type": "string", "enum": [ "sku", "spec", "carrier", "correios", "carrierIntelipost" ] }, "description": "Tipo de planilha a importar." }, { "name": "IDSupplier", "in": "query", "schema": { "type": "integer" }, "description": "Obrigatório para `correios` e `carrierIntelipost`." }, { "name": "IDTypeJob", "in": "query", "schema": { "type": "integer" }, "description": "Quando informado, usa um job personalizado registrado em `TypeJob`." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Planilha (XLSX/CSV)." } } } } }, "description": "Corpo do `POST /sku/template`: planilha/arquivo a processar de forma assíncrona, enviado como `multipart/form-data`. O tipo de importação (SKU, especificação, transportadora, Correios, Intelipost) é determinado pela query `Type`; alguns tipos (ex.: `correios`) não exigem arquivo e usam metadados da query." }, "responses": { "200": { "description": "Job agendado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobScheduledResponse" } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Ação não encontrada`, `Erro ao processar ação em massa`." }, "404": { "description": "Recurso/rota não localizada (`statusCode: 404`)." }, "500": { "description": "Erro interno." } } } }, "/sku/variation": { "get": { "operationId": "skuProductVariationList", "tags": [ "Variações (Grade)" ], "summary": "Lista produtos-pai com suas variações", "description": "Lista pares (produto-pai, SKU variação) com a grade aplicada. Pode filtrar por SKU, marca, fornecedor, código de barras e tipo. Exclui SKUs com status zero (excluídos lógicos).", "parameters": [ { "name": "IDSku", "in": "query", "schema": { "type": "integer" }, "description": "Filtra pelo identificador do produto/SKU." }, { "name": "SkuName", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo nome do produto (busca parcial)." }, { "name": "BarCode", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo código de barras do produto." }, { "name": "SkuType", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo tipo de SKU." }, { "name": "Brand", "in": "query", "schema": { "type": "string" }, "description": "Filtra pela marca (busca pelo nome)." }, { "name": "SupplierCode", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo código interno do fornecedor." }, { "name": "Supplier", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo fornecedor (busca pelo nome)." }, { "name": "IDSkuCompany", "in": "query", "schema": { "type": "string" }, "description": "Filtra pelo identificador do vínculo SKU-empresa." } ], "responses": { "200": { "description": "Lista resumida de variações.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDProduct": { "type": "integer", "description": "Identificador do produto-pai a que a variação pertence." }, "IDSku": { "type": "integer", "description": "Identificador do SKU desta variação." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome do SKU (descrição da variação)." }, "ProductVariation": { "type": "string", "nullable": true, "description": "Nome do atributo de variação (ex.: `Cor`, `Tamanho`, `Sabor`)." }, "TypeProductVariationValue": { "type": "string", "nullable": true, "description": "Valor do atributo de variação (ex.: `Azul`, `M`, `Morango`)." } } } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/variation/{idsku}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do SKU produto-pai." } ], "get": { "operationId": "skuProductVariationGet", "tags": [ "Variações (Grade)" ], "summary": "Lista as variações de um produto-pai", "description": "Retorna os SKUs variações filhos do produto-pai, com preço, saldo, status e a grade aplicada em cada um.", "parameters": [ { "name": "IDCompanySalesPolicy", "in": "query", "schema": { "type": "integer" }, "description": "Política comercial usada para `PriceSell`/`PriceList`. Default: política padrão da empresa." }, { "name": "IDStockKeepingUnitWarehouse", "in": "query", "schema": { "type": "integer" }, "description": "Quando informado, retorna saldo apenas deste armazém." } ], "responses": { "200": { "description": "Lista de variações.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuProductVariation" } } } } }, "400": { "description": "Política comercial inválida. Prefixo `[BadRequest]`. Mensagem: `Política comercial não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "post": { "operationId": "skuProductVariationPost", "tags": [ "Variações (Grade)" ], "summary": "Vincula um SKU variação a um produto-pai", "description": "Vincula um SKU filho a um produto-pai. Bloqueia quando o filho já está vinculado a outro produto, quando há outra variação com a mesma grade no produto-pai ou quando o `IDSku` é o próprio produto-pai.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDSku" ], "properties": { "IDSku": { "type": "integer", "description": "SKU filho a vincular como variação." } } } } }, "description": "Corpo do `POST /sku/variation/{idsku}`: associa um SKU filho a este produto pai. Campo obrigatório: `IDSku` (SKU filho, precisa ser diferente do produto, existir na empresa, não estar vinculado a outro produto e ter grade diferente dos demais filhos)." }, "responses": { "200": { "description": "Vínculo criado. Retorna `skuProductVariationGet`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuProductVariation" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Produto e SKU são iguais`, `Sku já existe em outro Produto`, `Produto já possui SKU com a mesma grade`, `Sku não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/variation/{idsku}/{idstockkeepingunitproductvariation}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto-pai." }, { "name": "idstockkeepingunitproductvariation", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do vínculo produto/variação." } ], "delete": { "operationId": "skuProductVariationDelete", "tags": [ "Variações (Grade)" ], "summary": "Remove um SKU variação do produto-pai", "description": "Desvincula o SKU variação do produto-pai.", "responses": { "200": { "description": "Vínculo removido. Retorna `skuProductVariationGet`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuProductVariation" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagem: `Product Variation não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/barcode": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "barCodePost", "tags": [ "Códigos de Barras" ], "summary": "Adiciona um código de barras adicional ao SKU", "description": "Cadastra um código de barras adicional (além do principal). Bloqueia se o código já existe como principal, adicional ou de embalagem em qualquer SKU da empresa.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "BarCode" ], "properties": { "BarCode": { "type": "string", "maxLength": 20, "description": "Código de barras adicional." } } } } }, "description": "Corpo do `POST /sku/{idsku}/barcode`: cadastra um código de barras alternativo para o SKU. Campo obrigatório: `BarCode` (precisa ser único na empresa — não pode existir em outro SKU, embalagem ou código alternativo)." }, "responses": { "200": { "description": "Código cadastrado. Retorna o detalhe do SKU.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuDetail" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Código de Barras precisa ser preenchido`, `Código de barras embalagem precisa ser preenchido`, `Código de Barras já existe no sku: `, `Código de barras já existe no sku: `." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/barcode/{idstockkeepingunitbarcode}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idstockkeepingunitbarcode", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do código de barras adicional." } ], "delete": { "operationId": "barCodeDelete", "tags": [ "Códigos de Barras" ], "summary": "Remove um código de barras adicional do SKU", "description": "Remove o código de barras adicional. Notifica webhooks da empresa.", "responses": { "200": { "description": "Código removido. Retorna o detalhe do SKU.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuDetail" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagem: `Código de barras não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/barcodepackage": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "barCodePackagePost", "tags": [ "Códigos de Barras (Embalagem)" ], "summary": "Adiciona um código de barras de embalagem ao SKU", "description": "Cadastra um código de barras de embalagem (caixa, fardo, master) para o SKU, com o fator de conversão para unidades. Valida unicidade contra os demais códigos da empresa.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "BarCodePackage" ], "properties": { "BarCodePackage": { "type": "string", "maxLength": 20, "description": "Código de barras da embalagem." }, "PackageFactor": { "type": "integer", "description": "Quantidade de unidades por embalagem. Default `1`." } } } } }, "description": "Dados do código de barras de embalagem a cadastrar para o SKU. Obrigatório: `BarCodePackage` (precisa ser único na empresa). Opcional: `PackageFactor` (quantidade de unidades por embalagem; padrão 1)." }, "responses": { "200": { "description": "Código cadastrado. Retorna o detalhe do SKU.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuDetail" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Código de barras embalagem precisa ser preenchido`, `Código de barras já existe no sku: `, `Código de Barras já existe no sku: `." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/barcodepackage/{idstockkeepingunitbarcodepackage}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idstockkeepingunitbarcodepackage", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do código de barras de embalagem." } ], "put": { "operationId": "barCodePackagePut", "tags": [ "Códigos de Barras (Embalagem)" ], "summary": "Atualiza um código de barras de embalagem", "description": "Atualiza o código de embalagem ou o fator. Reaplica as validações de unicidade.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "BarCodePackage": { "type": "string", "maxLength": 20, "description": "Código de barras da embalagem do SKU." }, "PackageFactor": { "type": "integer", "description": "Default `1`." } } } } }, "description": "Campos do código de barras de embalagem a atualizar. Aceita `BarCodePackage` (precisa permanecer único na empresa) e `PackageFactor` (padrão 1 quando vazio)." }, "responses": { "200": { "description": "Código atualizado. Retorna o detalhe do SKU.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuDetail" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Código de Barras Embalagem não existe`, `Código de Barras embalagem precisa ser preenchido`, `Código de Barras Embalagem já existe`, `Código de barras já existe no sku: `, `Código de Barras já existe no sku: `." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "delete": { "operationId": "barCodePackageDelete", "tags": [ "Códigos de Barras (Embalagem)" ], "summary": "Remove um código de barras de embalagem", "description": "Remove o código de barras de embalagem.", "responses": { "200": { "description": "Código removido. Retorna o detalhe do SKU.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuDetail" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagem: `Código de Barras Embalagem não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/collection": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "skuCollectionAssociationGet", "tags": [ "Coleções" ], "summary": "Lista coleções associadas ao SKU", "description": "Lista as coleções a que o SKU está vinculado.", "responses": { "200": { "description": "Lista de associações.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuCollectionAssociation" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "post": { "operationId": "skuCollectionAssociationPost", "tags": [ "Coleções" ], "summary": "Associa o SKU a uma coleção", "description": "Vincula o SKU à coleção informada. Cada par SKU/coleção é único.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDStockKeepingUnitCollection" ], "properties": { "IDStockKeepingUnitCollection": { "type": "integer", "description": "Identificador da coleção." } } } } }, "description": "Corpo do `POST /sku/{idsku}/collection`: associa uma coleção ao SKU. Campo obrigatório: `IDStockKeepingUnitCollection` (coleção — precisa existir na empresa e ainda não estar associada ao SKU)." }, "responses": { "200": { "description": "Associação criada. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuCollectionAssociation" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Sku já possui essa coleção`, `Coleção não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/collection/{idstockkeepingunitcollectionassociation}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idstockkeepingunitcollectionassociation", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da associação SKU/coleção." } ], "put": { "operationId": "skuCollectionAssociationPut", "tags": [ "Coleções" ], "summary": "Troca a coleção de uma associação existente", "description": "Atualiza a coleção associada a um vínculo já existente.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDStockKeepingUnitCollection" ], "properties": { "IDStockKeepingUnitCollection": { "type": "integer", "description": "Identificador da coleção à qual o SKU será associado." } } } } }, "description": "Corpo do `PUT /sku/{idsku}/collection/{idstockkeepingunitcollectionassociation}`: troca a coleção da associação. Campo obrigatório: `IDStockKeepingUnitCollection` (nova coleção — precisa existir na empresa e não estar duplicada para o SKU)." }, "responses": { "200": { "description": "Associação atualizada. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuCollectionAssociation" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Coleção Sku não existe`, `Sku já possui essa coleção`, `Coleção não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "delete": { "operationId": "skuCollectionAssociationDelete", "tags": [ "Coleções" ], "summary": "Remove a associação SKU/coleção", "description": "Desvincula o SKU da coleção.", "responses": { "200": { "description": "Associação removida.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagem: `Coleção Sku não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/group": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "skuGroupAssociationGet", "tags": [ "Grupos de SKU" ], "summary": "Lista grupos associados ao SKU", "description": "Lista os grupos de SKU a que o SKU pertence, com os códigos similares cadastrados em cada grupo.", "responses": { "200": { "description": "Lista de associações.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuGroupAssociation" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "post": { "operationId": "skuGroupAssociationPost", "tags": [ "Grupos de SKU" ], "summary": "Associa o SKU a um grupo", "description": "Vincula o SKU ao grupo informado. Cada par SKU/grupo é único.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDStockKeepingUnitGroup" ], "properties": { "IDStockKeepingUnitGroup": { "type": "integer", "description": "Identificador do grupo ao qual o SKU será associado." } } } } }, "description": "Corpo do `POST /sku/{idsku}/group`: associa um grupo de SKUs ao SKU. Campo obrigatório: `IDStockKeepingUnitGroup` (grupo — precisa existir na empresa e ainda não estar associado ao SKU)." }, "responses": { "200": { "description": "Associação criada. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuGroupAssociation" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Sku já possui esse grupo`, `Grupo Sku não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/group/{idstockkeepingunitgroupassociation}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idstockkeepingunitgroupassociation", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da associação SKU/grupo." } ], "put": { "operationId": "skuGroupAssociationPut", "tags": [ "Grupos de SKU" ], "summary": "Troca o grupo de uma associação existente", "description": "Atualiza o grupo associado a um vínculo já existente.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDStockKeepingUnitGroup" ], "properties": { "IDStockKeepingUnitGroup": { "type": "integer", "description": "Novo identificador do grupo ao qual o SKU será associado." } } } } }, "description": "Corpo do `PUT /sku/{idsku}/group/{idstockkeepingunitgroupassociation}`: troca o grupo da associação. Campo obrigatório: `IDStockKeepingUnitGroup` (novo grupo — precisa existir na empresa e não estar duplicado para o SKU)." }, "responses": { "200": { "description": "Associação atualizada. Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuGroupAssociation" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Grupo Sku não existe`, `Sku já possui esse grupo`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "delete": { "operationId": "skuGroupAssociationDelete", "tags": [ "Grupos de SKU" ], "summary": "Remove a associação SKU/grupo", "description": "Desvincula o SKU do grupo.", "responses": { "200": { "description": "Associação removida.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagem: `Grupo Sku não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/label": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "skuLabelGet", "tags": [ "SKU — Etiqueta" ], "summary": "Gera etiqueta de SKU para impressão", "description": "Gera a etiqueta ZPL/PDF do SKU usando o modelo de etiqueta da empresa.", "responses": { "200": { "description": "Etiqueta gerada. Tipicamente retorna a etiqueta como ZPL/PDF ou URL para download.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Confirmação do job agendado." } } } }, "500": { "description": "Erro interno." } } } }, "/sku/{idsku}/serial": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "skuSerialGet", "tags": [ "Números de Série" ], "summary": "Lista números de série do SKU", "description": "Lista os números de série cadastrados para o SKU. Filtros opcionais permitem isolar livres, vinculados a uma entrada ou a uma saída.", "parameters": [ { "name": "Free", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` retorna apenas seriais não consumidos por venda (sem `IDSkuMovementOutbound`)." }, { "name": "IDSkuMovementInbound", "in": "query", "schema": { "type": "integer" }, "description": "Restringe seriais a uma entrada específica." }, { "name": "IDSkuMovementOutbound", "in": "query", "schema": { "type": "integer" }, "description": "Restringe seriais a uma saída específica." }, { "name": "IDTypeStatusSkuSerialNumber", "in": "query", "schema": { "type": "integer", "enum": [ 1, 2, 3 ] }, "description": "Filtra por status do serial." } ], "responses": { "200": { "description": "Lista de seriais.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSerial" } } } } }, "400": { "description": "Erro de configuração da empresa. Prefixo `[BadRequest]`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "post": { "operationId": "skuSerialPost", "tags": [ "Números de Série" ], "summary": "Cadastra números de série", "description": "Insere uma lista de números de série para o SKU. Quando `IDSkuMovementInbound` é informado, os seriais ficam vinculados a essa entrada (status `2` recebido); caso contrário, ficam livres (status `1`). Bloqueia se algum serial já existe para o SKU.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "SerialNumber" ], "properties": { "SerialNumber": { "type": "array", "items": { "type": "string", "maxLength": 45 }, "description": "Lista de seriais a cadastrar." }, "IDSkuMovementInbound": { "type": "integer", "nullable": true, "description": "Entrada associada (recebimento)." } } } } }, "description": "Dados dos números de série a cadastrar para o SKU. Obrigatório: `SerialNumber` (array dos seriais — não podem existir para o mesmo SKU). Opcional: `IDSkuMovementInbound` (movimentação de entrada — quando informada, valida que existe, remove os seriais já vinculados a ela e marca os novos como `IDTypeStatusSkuSerialNumber = 2`; sem ela usa o status 1)." }, "responses": { "200": { "description": "Seriais inseridos. Retorna `skuSerialGet` filtrado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuSerial" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Serial precisa ser preenchido`, `Serial já existe`, `Movimentação entrada não localizada`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/serial/{idstockkeepingunitserialnumber}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idstockkeepingunitserialnumber", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do serial." } ], "put": { "operationId": "skuSerialPut", "tags": [ "Números de Série" ], "summary": "Atualiza o número de série", "description": "Altera o conteúdo do número de série. Bloqueia quando o serial já saiu em uma venda.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "SerialNumber" ], "properties": { "SerialNumber": { "type": "string", "maxLength": 45, "description": "Número de série do SKU." } } } } }, "description": "Corpo do `PUT /sku/{idsku}/serial/{idstockkeepingunitserialnumber}`: atualiza o número de série. Campo obrigatório: `SerialNumber` (novo serial; não é permitido alterar um serial já enviado em venda)." }, "responses": { "200": { "description": "Serial atualizado.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Serial não existe`, `Serial já foi enviado em uma venda e não pode ser deletado`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "delete": { "operationId": "skuSerialDelete", "tags": [ "Números de Série" ], "summary": "Remove um número de série", "description": "Remove o serial. Bloqueia quando o serial já saiu em uma venda.", "responses": { "200": { "description": "Serial removido.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Serial não existe`, `Serial já foi enviado em uma venda e não pode ser deletado`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/variation": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "skuVariationGet", "tags": [ "Variações (Grade)" ], "summary": "Lista os valores de variação do SKU", "description": "Lista os pares (tipo de variação, valor) cadastrados para o SKU. Ex.: `Cor: Azul`, `Tamanho: M`.", "responses": { "200": { "description": "Lista de valores de variação.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuVariationValue" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "post": { "operationId": "skuVariationPost", "tags": [ "Variações (Grade)" ], "summary": "Adiciona um valor de variação ao SKU", "description": "Vincula um valor de variação (ex.: `Cor: Azul`) ao SKU. Cada tipo de variação só pode aparecer uma vez por SKU.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "IDTypeProductVariation", "IDTypeProductVariationValue" ], "properties": { "IDTypeProductVariation": { "type": "integer", "description": "Tipo de variação (ex.: cor, tamanho)." }, "IDTypeProductVariationValue": { "type": "integer", "description": "Valor da variação (ex.: azul, M)." } } } } }, "description": "Dados da variação (grade) a associar ao SKU. Obrigatórios: `IDTypeProductVariation` (tipo de variação — ex.: cor, tamanho — único por SKU) e `IDTypeProductVariationValue` (valor da variação)." }, "responses": { "200": { "description": "Valor de variação cadastrado. Retorna `skuVariationGet`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuVariationValue" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagens: `Sku não existe`, `Sku já tem esse tipo de variação`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/variation/{idstockkeepingunitvariation}": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "idstockkeepingunitvariation", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do valor de variação." } ], "delete": { "operationId": "skuVariationDelete", "tags": [ "Variações (Grade)" ], "summary": "Remove um valor de variação do SKU", "description": "Remove o vínculo entre o SKU e o valor de variação. Notifica webhooks da empresa.", "responses": { "200": { "description": "Valor removido. Retorna `skuVariationGet`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuVariationValue" } } } } }, "400": { "description": "Prefixo `[BadRequest]`. Mensagem: `Variação não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/sku/{idsku}/warehouse": { "parameters": [ { "name": "idsku", "in": "path", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "skuWarehouseIDSkuGet", "tags": [ "Armazéns" ], "summary": "Lista saldos do SKU por armazém", "description": "Lista o saldo do SKU em cada armazém ativo, com detalhamento de pedidos reservados, em separação, em produção, em recebimento, em pedido de compra e em ressuprimento. Respeita os centros de distribuição autorizados para o usuário e o ajuste de margem de segurança do tipo de pedido informado.", "parameters": [ { "name": "IDTypeOrder", "in": "query", "schema": { "type": "integer" }, "description": "Quando informado, aplica a margem `SafetyStockPercent` do tipo de pedido sobre as quantidades retornadas." }, { "name": "IDStockKeepingUnitDistributionCenter", "in": "query", "schema": { "type": "string" }, "description": "Lista de centros de distribuição separados por vírgula. Restringe os armazéns retornados." } ], "responses": { "200": { "description": "Lista de armazéns com saldo do SKU.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkuWarehouseBalance" } } } } }, "400": { "description": "Erro de validação dos parâmetros enviados." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/orders/{idorder}": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "get": { "operationId": "OrderGet", "tags": [ "Pedidos" ], "summary": "Detalhe completo do pedido", "description": "Retorna o pedido com itens, parcelas, pacotes, histórico, arquivos da nota fiscal e totalizadores. Use `?Economics=1` para receber, em vez disso, os indicadores econômicos (receitas, custos e margem) e `?ItemsInvoice=1` para receber apenas a lista de itens enriquecida com classificações tributárias para emissão fiscal. Quando a parametrização `Mostrar apenas nome do produto` está ligada, o nome do produto retornado nos itens não traz o prefixo da variação.", "parameters": [ { "name": "Economics", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, retorna `OrderEconomics` em vez de `OrderDetail`." }, { "name": "ItemsInvoice", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, retorna a lista de itens enriquecida com CFOP e CSTs (`OrderItemFiscal`)." } ], "responses": { "200": { "description": "Detalhe do pedido. O shape varia conforme as flags `Economics` e `ItemsInvoice`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/OrderDetail" }, "description": "Default (sem flags) — array com um único `OrderDetail`. Array vazio quando o pedido não existe na empresa." }, { "type": "array", "items": { "$ref": "#/components/schemas/OrderEconomics" }, "description": "Com `Economics=1`." }, { "type": "array", "items": { "$ref": "#/components/schemas/OrderItemFiscal" }, "description": "Com `ItemsInvoice=1`." } ] } } } }, "400": { "description": "Pedido inexistente ou identificador inválido. Mensagem possível: `[BadRequest] - não localizado`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "put": { "operationId": "OrderPut", "tags": [ "Pedidos" ], "summary": "Atualiza o pedido", "description": "Alem da atualizacao do pedido, aceita o modo de reenvio de notificacao: com Resend=1 (e TypeMessage), o endpoint apenas reenvia a mensagem do pedido do tipo indicado e devolve a resposta desse envio, sem alterar o pedido.", "parameters": [ { "name": "ValueAdjust", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, ativa o fluxo de ajuste de valor (desconto/acréscimo rateado)." }, { "name": "Resend", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando 1, o endpoint entra no modo de reenvio de notificacao do pedido: nao atualiza o pedido, apenas reenvia a mensagem do tipo TypeMessage e retorna a resposta do envio. Exige TypeMessage." }, { "name": "TypeMessage", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tipo da mensagem/notificacao a reenviar. Obrigatorio quando Resend=1; ausente retorna 400 com [BadRequest] - Precisa informar o parametro TypeMessage." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderUpdateBody" } } }, "description": "Atualização parcial do pedido. Apenas campos enviados são alterados. Quando o query param `ValueAdjust=1` está presente, o body é interpretado como ajuste de valor (`ValueAddOrDiscount`/`PercentAddOrDiscount`/`IncludeShipping`) — os demais campos são ignorados nesse modo." }, "responses": { "200": { "description": "Pedido atualizado. Geralmente retorna o `OrderDetail` recalculado (igual a `OrderGet`). Em alguns sub-fluxos (troca de armazém) retorna a string `\"sucesso\"`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderDetail" }, { "type": "array", "items": { "$ref": "#/components/schemas/OrderDetail" } }, { "type": "string", "example": "sucesso" } ] } } } }, "400": { "description": "Erros de validação (`[BadRequest]`): `Fator nota fiscal precisa ser entre 1 e zero`, `Prioridade pedido precisa ser entre 0 e 10`, `O status atual não permite atualização`, `Precisa enviar o valor ou percentual do desconto`, `Armazém pertence a um centro de distribuição diferente do pedido`, `Pedido já foi enviado e não pode ter o armazém alterado`, `Armazém não existe`, `Tipo pedido não existe`, `Integração não existe`, `Cliente não existe`, `Endereço não existe`, `Endereço entrega não existe`, `Vendedor não existe`, `Faturador não existe`, `Remova o pedido/pacotes do romaneio antes de alterar transportadora`, `Transportadora não existe`, `Romaneio percente a centro de distribuição diferente do pedido`, `Status romaneio não permite inclusão/remoção de novos pedidos`, `Romaneio não existe`, `Status Picking List não permite inclusão de novos pedidos`, `Picking List não existe`, `Centro de distribuição não existe`, `Empresa não tem centro de distribuição padrão`, `Pedido esta em mais de um centro de distribuição. Remover os itens de armazéns divergentes`, `Novo centro de distribuição diverge dos armazém dos itens já inseridos no pedido`, `Pedido não existe`, `Precisa informar o parametro TypeMessage`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "OrderDelete", "tags": [ "Pedidos" ], "summary": "Exclui o pedido (status 100)", "description": "Marca o pedido como excluído (status `100`), zera o frete e limpa picking/romaneio. Antes da exclusão, remove as movimentações de estoque, contas a receber, pacotes, origens, referências de NF, tags, nota fiscal vinculada (se houver) e o rastreamento da transportadora. Registra um evento de exclusão.\n\nBloqueado quando a nota fiscal associada está em status que impede mudança (enviada, emitida, processando, pendente conciliação EPEC, cancelada ou denegada — nesse caso desvincule a nota primeiro), quando o pedido está em romaneio ou em picking list (retire antes), ou quando o status atual não permite transição para `100`.\n\nApós excluir, retorna o `OrderDetail` atualizado (via invocação interna do `OrderGet`). Envie `?NoInvoke=1` para receber apenas a string `\"sucesso\"`.", "parameters": [ { "name": "NoInvoke", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, evita o reload do pedido e retorna apenas a string `\"sucesso\"`." } ], "responses": { "200": { "description": "Pedido excluído.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderDetail" }, { "type": "string", "example": "sucesso" } ] } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `Desvincular nota fiscal antes de alterar status`, `Pedido esta em romaneio , retirar antes de mudar status`, `Pedido esta na Picking List , retirar antes de mudar status`, `Status não permite atualização`, `Order não existe`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/sku": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "post": { "operationId": "orderSkuPost", "tags": [ "Pedidos" ], "summary": "Adiciona um item ao pedido", "description": "Inclui um produto no pedido. A criação propriamente dita (movimentação de estoque, cálculo de tributos com base no produto, política e UF) é delegada a um processo fiscal interno — o sistema valida regras de negócio antes (coerência de sinal de quantidade com itens existentes, bloqueio de produto com valor zero conforme o tipo de pedido e a parametrização `Permitir gratificação de produtos com valor zero`) e em seguida monta a linha consolidada do item para retorno, incluindo cálculo de comissão quando o pedido tem vendedor com regra vigente.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderSkuPostBody" } } }, "description": "Item a adicionar ao pedido. `IDSku` e `Quantity` são obrigatórios; demais campos passam pelo motor fiscal a partir do produto e da política de vendas." }, "responses": { "200": { "description": "Item adicionado. Retorna um array com o item criado. Quando o processo fiscal devolve resposta vazia, retorna a string `\"ok\"`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/OrderSkuMovement" } }, { "type": "string", "example": "ok" } ] } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `Pedido não encontrado`, `Pedido tem itens com quantidade negativa e item com quantidade positiva não pode ser adicionado`, `Pedido tem itens com quantidade positiva e item com quantidade negativa não pode ser adicionado`, `Não é permitido adicionar produtos com valor zero ao pedido (configuração no tipo de pedido)`, `Erro ao adicionar item em pedido`. Mensagens retornadas pelo processo fiscal (ex.: validações de estoque, preço, CFOP) também aparecem aqui com seu texto original.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/sku/{idskumovement}": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." }, { "name": "idskumovement", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da movimentação do item no pedido." } ], "put": { "operationId": "orderSkuPut", "tags": [ "Pedidos" ], "summary": "Atualiza um item do pedido", "description": "Atualiza quantidade, preço, armazém, classificação fiscal ou descontos de um item já existente. Quando quantidade/preço mudam, o motor fiscal recalcula tributos do item e atualiza os totais da nota; quando o armazém muda, valida que o novo armazém pertence ao mesmo centro de distribuição do pedido. Descontos acima do limite configurado para o vendedor são recusados — a mensagem traz o percentual aplicado e o limite. Em status finais (cancelado/excluído) e em estados intermediários incompatíveis a atualização é bloqueada. Após o sucesso, retorna o `OrderDetail` recalculado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderSkuPutBody" } } }, "description": "Campos do item do pedido a atualizar — apenas os enviados são aplicados. Inclui dados comerciais (`IDSku`, `Quantity`, `PriceList`, `PriceSelling`, `PriceSellingTotal`, `ValueDiscount`, `ValueShipping`, `Gratification`, `IDStockKeepingUnitWarehouse`, `QuantityNonconformity`, `IDTypeFulfillmentNonconformity`, `Comments`, `NfeNItemPed`) e os campos fiscais da NF-e do item (CFOP, ICMS/PIS/COFINS/IPI/II/ISS, FCP, ICMS-ST, importação, combustível e demais grupos de tributos)." }, "responses": { "200": { "description": "Item atualizado. Retorna o `OrderDetail` recalculado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `Pedido não existe`, `Sku não existe`, `Armazem não existe`, `Centro de distribuição do item é diferente do CD do pedido`, `O status atual não permite atualizar`, `Pedido tem itens com quantidade negativa e item com quantidade positiva não pode ser adicionado`, `Pedido tem itens com quantidade positiva e item com quantidade negativa não pode ser adicionado`, `Desconto aplicado maior que o permitido. Aplicado: % e desconto limite: %`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "orderSkuDelete", "tags": [ "Pedidos" ], "summary": "Remove um item do pedido", "description": "Exclui a movimentação do item, registra um evento no histórico do pedido e, quando havia outras movimentações posteriores do mesmo produto/armazém com marcação para reprocessar saldo, enfileira recálculo de custo médio (fila assíncrona `skuCostRecalculate`). Operação bloqueada quando o status do pedido não permite ajustes (somente status iniciais ou os ligados a atendimento — `50` a `56`, `70` a `74` — aceitam exclusão de item). Após remover, retorna o `OrderDetail` atualizado.", "responses": { "200": { "description": "Item removido. Retorna o `OrderDetail` recalculado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `Pedido não existe`, `O status atual não permite atualização`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/payment": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "post": { "operationId": "orderPaymentPost", "tags": [ "Pedidos" ], "summary": "Lança um pagamento (conta a receber) no pedido", "description": "Cria parcela(s) de recebimento para o pedido. A criação efetiva — incluindo geração de boleto/link de pagamento junto ao gateway quando o tipo de pagamento exige, e rateio de parcelas quando `SplitInstallment` é maior que 1 — é executada por um processo financeiro interno. Após o sucesso, retorna o `OrderDetail` recalculado.", "parameters": [ { "name": "SplitInstallment", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Quando maior que 1, divide o valor enviado nesse número de parcelas (vencimentos consecutivos)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderPaymentPostBody" }, { "type": "array", "items": { "$ref": "#/components/schemas/OrderPaymentPostBody" } } ] } } }, "description": "Pagamento ou lista de pagamentos a lançar no pedido. Cada item gera um título financeiro (`AccountsPayableReceivable`) e dispara a aplicação adequada (parcelamento, boleto, link de pagamento)." }, "responses": { "200": { "description": "Pagamento lançado. Retorna o `OrderDetail` recalculado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): mensagens do processo financeiro (validações de tipo de pagamento, banco, integração, etc.).", "content": { "application/json": { "schema": { "type": "string" } } } }, "404": { "description": "Pedido não encontrado (prefixo `[NotFound]`): `[NotFound] - Pedido não encontrado`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/payment/{idaccountpayablereceivable}": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." }, { "name": "idaccountpayablereceivable", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da conta a receber (parcela) do pedido." } ], "put": { "operationId": "orderPaymentPut", "tags": [ "Pedidos" ], "summary": "Atualiza uma parcela do pedido", "description": "Atualiza os dados de uma conta a receber lançada no pedido (valor, vencimento, tipo de pagamento, plano de contas, cliente/fornecedor, integração, descontos, juros e multas). Quando o título tem boleto/link de pagamento em aberto, a alteração de `Value`/`DateDue` dispara reemissão junto ao gateway; com boleto/link já pago, a alteração é bloqueada. Após o sucesso, retorna o `OrderDetail` recalculado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsPayableReceivableUpdateBody" } } }, "description": "Atualização parcial de um título financeiro do pedido. `IDConsumer` e `IDSupplier` são mutuamente exclusivos. Quando `Value`/`DateDue` mudam e o título já tem boleto/link emitido, o gateway é acionado para reemissão (boletos pagos são bloqueados)." }, "responses": { "200": { "description": "Título atualizado. Retorna o `OrderDetail` recalculado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)`, `Fornecedor não existe`, `Cliente não existe`, `Faturador não existe`, `Pagamento não existe`, `Banco não existe`, `Integração não existe`, `Boleto / link pagamento já esta pago e não pode ser alterado`, `Plano de contas não existe`, `Tipo documento não existe`, `Conta a receber não existe`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "orderPaymentDelete", "tags": [ "Pedidos" ], "summary": "Exclui uma parcela do pedido", "description": "Remove a conta a receber vinculada ao pedido. Bloqueada quando o título já está agendado, quando tem pagamento conciliado, ou — para contas a pagar de recebimento — quando a parametrização `Bloquear exclusão de contas a pagar atreladas a recebimento` está ativa. Quando havia GNRE vinculada, o link é desfeito. Registra um evento de exclusão no histórico do pedido e retorna o `OrderDetail` recalculado.", "parameters": [ { "name": "ChangeNextRepeat", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Aplicável apenas a títulos avulsos (sem pedido). Quando `1`, apaga também as próximas ocorrências da série de repetição (vencimentos futuros)." } ], "responses": { "200": { "description": "Título excluído. Retorna o `OrderDetail` recalculado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `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`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/packages": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "post": { "operationId": "orderPackagesPost", "tags": [ "Pedidos" ], "summary": "Cria pacotes para o pedido", "description": "Adiciona pacote(s) ao pedido. Quando `PackageQuantityTotal` é enviado, o sistema ajusta o total de pacotes do pedido para esse número (criando pacotes vazios numerados em sequência ou apagando os excedentes — pacotes com numeração mais alta primeiro). Quando `PackageQuantityTotal` é omitido, cria um único pacote com as dimensões informadas, no próximo `PackageNumber` disponível. Quando `IDSku` é enviado, adiciona uma movimentação do produto no pedido (quantidade 1, preço 0, armazém padrão da empresa) — usado para registrar embalagem/brinde. Bloqueado quando o pedido está em status `7` ou `8` (cancelado pelo cliente / cancelado). Retorna o `OrderDetail` recalculado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPackagePostBody" } } }, "description": "Cria um pacote único (informando dimensões) ou garante uma quantidade total de pacotes para o pedido via `PackageQuantityTotal`." }, "responses": { "200": { "description": "Pacote(s) criado(s). Retorna o `OrderDetail` recalculado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `Pedido não existe`, `O status atual não permite atualizar`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/packages/{idpackage}": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." }, { "name": "idpackage", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pacote dentro do pedido." } ], "put": { "operationId": "orderPackagesPut", "tags": [ "Pedidos" ], "summary": "Atualiza um pacote do pedido", "description": "Atualiza o código de rastreio do pacote e/ou o vínculo com romaneio. O pedido precisa ter transportadora definida; sem ela, a operação é recusada. O código de rastreio precisa ser único dentro da transportadora. Ao alterar o romaneio, o sistema valida que ele pertence à mesma transportadora e ao mesmo centro de distribuição do pedido, e que seu status permite alteração; pacotes já enviados (`IDStatusPackage=1`) não podem trocar de romaneio. Quando os valores enviados coincidem com os atuais, retorna a string `\"sucesso\"` sem reprocessar — caso contrário, retorna o `OrderDetail` recalculado.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPackagePutBody" } } }, "description": "Campos do volume (pacote) do pedido a atualizar. Aceita `ShippingId` (código de rastreio — precisa ser único na transportadora) e `IDOrdersCarrierCollectionList` (romaneio — precisa ser da mesma transportadora e centro de distribuição do pedido, estar em status que permite alteração e o pacote ainda não pode ter sido enviado). Atribuir o pacote a um novo romaneio limpa o `ShippingPlp` anterior." }, "responses": { "200": { "description": "Pacote atualizado.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderDetail" }, { "type": "string", "example": "sucesso" } ] } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `Volume/Pedido não existe`, `Pedido não possui transportadora`, `Código Rastreio já existe`, `Pacote já enviado`, `Romaneio pertence a transportadora divergente do pedido`, `Romaneio pertece a outro centro de distribuição`, `Status do romaneio não permite alterar pacote`, `Romaneio não existe`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "orderPackagesDelete", "tags": [ "Pedidos" ], "summary": "Remove um pacote do pedido", "description": "Remove o pacote e renumera os restantes em sequência. Por padrão, `idpackage` refere-se ao identificador interno do pacote. Use `?Type=ShippingId` para resolver por código de rastreio em vez do identificador. Bloqueado quando o pedido está em status que impede ajuste de pacotes (`6` separado, `7`/`8` cancelado, `17`/`19` finalizados). Retorna o `OrderDetail` recalculado.", "parameters": [ { "name": "Type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ShippingId" ] }, "description": "Quando `ShippingId`, o `idpackage` do path é tratado como código de rastreio (não como identificador do pacote)." } ], "responses": { "200": { "description": "Pacote removido. Retorna o `OrderDetail` recalculado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `Pedido não existe`, `O status atual não permite atualização`, `Volume não existe`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/file": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "get": { "operationId": "orderFileGet", "tags": [ "Pedidos" ], "summary": "Lista arquivos customizados do pedido", "description": "Retorna os arquivos customizados anexados ao pedido (assinatura digital de entrega, fotos de comprovante de entrega/devolução, etc.) com URLs pré-assinadas do S3 (validade de 2 dias) para download direto. Use `?IDTypeOrderFile` para filtrar por um tipo específico.", "parameters": [ { "name": "IDTypeOrderFile", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3 ] }, "description": "Filtra pelo tipo do arquivo customizado." } ], "responses": { "200": { "description": "Lista de arquivos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrderCustomFile" } } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "orderFilePost", "tags": [ "Pedidos" ], "summary": "Anexa um arquivo customizado ao pedido", "description": "Cria um registro de arquivo customizado para o pedido (assinatura digital, fotos de comprovante) e envia os anexos para o S3. Quando `?ChangeStatus=1` (ou quando o tipo do arquivo é `1` e a query não foi enviada), o pedido é avançado para entregue/devolvido (status `7` ou `8`, conforme o tipo da transportadora), todos os pacotes do pedido são marcados como enviados, as movimentações de estoque viram saída consolidada e é registrado um evento no histórico. Caso o status final seja enviado via `IDStatusOrder`, esse valor é usado em vez do default. Retorna a lista atualizada de arquivos (mesmo formato de `orderFileGet`).", "parameters": [ { "name": "IDTypeOrderFile", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "enum": [ 1, 2, 3 ] }, "description": "Tipo do arquivo (default `1` — comprovante de entrega)." }, { "name": "ChangeStatus", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, avança o status do pedido e dos pacotes. Default `1` quando `IDTypeOrderFile=1`, `0` caso contrário." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderFilePostBody" } } }, "description": "Arquivos customizados a anexar ao pedido — pelo menos um entre `Signature`, `DocumentImage`, `DocumentImage2` ou `DocumentImage3` precisa vir preenchido (data URL base64)." }, "responses": { "200": { "description": "Arquivo(s) anexado(s). Retorna a lista atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrderCustomFile" } } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `Pedido não existe`, `Não foi enviado um arquivo válido`. Também pode retornar `erro ao subir arquivo` (sem prefixo) quando o upload no S3 falha — o registro inserido é desfeito antes.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/file/{idorderscustomfile}": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." }, { "name": "idorderscustomfile", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do arquivo customizado." } ], "get": { "operationId": "orderFileDownloadGet", "tags": [ "Pedidos" ], "summary": "Baixa o conteúdo de um arquivo customizado", "description": "Faz o download do arquivo anexado ao pedido. O `idorderscustomfile` é resolvido a partir do path; o nome real do arquivo dentro do registro (assinatura, primeiro anexo etc.) é informado em `?FileName`. Quando `?View=1`, devolve o conteúdo bruto para visualização inline; caso contrário, devolve com `Content-Disposition: attachment` para download.", "parameters": [ { "name": "FileName", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Nome do arquivo a baixar — precisa coincidir com `File1Name` ou `File2Name` do registro." }, { "name": "View", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, devolve o conteúdo bruto para visualização inline em vez de anexo." } ], "responses": { "200": { "description": "Conteúdo do arquivo (bytes).", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Mensagens possíveis (prefixo `[NotFound]`): `Arquivo não encontrado`, `Arquivo não encontrado S3`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "orderFileDelete", "tags": [ "Pedidos" ], "summary": "Remove um arquivo customizado do pedido", "description": "Apaga o registro do arquivo customizado do pedido. Não remove os blobs do S3 (ficam como órfãos até limpeza periódica). Retorna a string `\"sucesso\"`.", "responses": { "200": { "description": "Operação concluída com sucesso.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "404": { "description": "Arquivo não encontrado. Mensagem (sem prefixo): `Arquivo Não encontrado`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/invoice": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "post": { "operationId": "orderInvoicePost", "tags": [ "Pedidos" ], "summary": "Emite a nota fiscal do pedido", "description": "Aciona a emissão fiscal do pedido. O contrato do corpo é o XML/JSON aceito pelo processo fiscal interno — campos como cabeçalho, itens, totais, transporte e meios de pagamento — e a resposta repete o retorno do processo. Em sucesso, devolve os dados da nota emitida (chave de acesso, número, protocolo, status SEFAZ); em erro de SEFAZ, a resposta traz o `errorMessage` original retornado pelo emissor, sem prefixo.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "Payload aceito pelo processo fiscal (contrato definido fora deste sistema)." } }, "application/xml": { "schema": { "type": "string", "description": "Payload XML aceito pelo processo fiscal." } } }, "description": "XML da NF-e a emitir/assinar. O conteúdo é assinado, transmitido à SEFAZ e o cadastro fiscal da empresa é atualizado. Content-Type deve ser `application/xml`." }, "responses": { "200": { "description": "Nota processada — retorno do processo fiscal (chave de acesso, protocolo, status etc.).", "content": { "application/json": { "schema": { "type": "object", "description": "Resposta do processo fiscal. Shape não confirmado nesta operação — depende do corpo enviado." } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `não localizado`, `erro ao emitir nota fiscal`. Também pode retornar um JSON com `errorMessage` vindo do processo fiscal (mensagens da SEFAZ, validações de cadastro, etc.).", "content": { "application/json": { "schema": { "type": "string" } } } }, "404": { "description": "Pedido não encontrado. Retorna JSON com `errorMessage` prefixado por `[NotFound]`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errorMessage": { "type": "string" }, "errorCode": { "type": "integer" }, "errorHelp": { "type": "string" } } } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "orderInvoiceRemove", "tags": [ "Pedidos" ], "summary": "Desvincula a nota fiscal do pedido", "description": "Desvincula a nota fiscal principal do pedido. Quando a nota está pendente (`0`) ou em erro (`1`), zera os dados de emissão (chave, dh emi, protocolo, recibo, status SEFAZ) e remove a marcação de nota principal — o registro fica disponível para retentativa. Quando a nota já foi cancelada/denegada/EPEC, mantém os dados emitidos mas remove a marcação de principal — o pedido fica livre para uma nova emissão. Bloqueado quando a nota está enviada (`2`) ou emitida (`3`). Registra um evento de desvinculação e retorna o `OrderDetail` recalculado.", "responses": { "200": { "description": "Nota fiscal desvinculada. Retorna o `OrderDetail` recalculado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `Pedido não existe`, `O status atual não permite desvincular nota fiscal`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/invoice/check": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "get": { "operationId": "orderInvoiceValidateGet", "tags": [ "Pedidos" ], "summary": "Consulta o status da nota fiscal junto à SEFAZ", "description": "Faz consulta na SEFAZ pela chave de acesso da nota fiscal emitida do pedido. Útil para sincronizar eventos que aconteceram fora do idworks:\n\n- `cStat=100` (autorizada): se a SEFAZ devolver procEventos com cartas de correção (`tpEvento=110110`) ainda não importadas, salva os XMLs como arquivos do tipo `6` no S3 e registra o evento de consulta. Retorna o `xMotivo` da SEFAZ no corpo.\n- `cStat=101/135/155` (cancelamento aceito): importa o XML de cancelamento (`tpEvento=110111/110112`) como arquivo do tipo `8`, atualiza a nota para cancelada e registra evento.\n- Outros: retorna erro com o `xMotivo` da SEFAZ.\n\nFunciona apenas quando a nota está emitida.", "responses": { "200": { "description": "Consulta processada. Quando há carta(s) de correção nova(s), retorna o `xMotivo` da SEFAZ; quando o cancelamento foi importado, devolve resposta vazia.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `Nota Fiscal não esta no status emitida`, `Certificado digital não encontrado`, e mensagens da SEFAZ (texto do `xMotivo`).", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/invoice/simulation": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "get": { "operationId": "orderInvoiceSimulationGet", "tags": [ "Pedidos" ], "summary": "Simula a emissão fiscal do pedido (DANFE/XML de pré-visualização)", "description": "Renderiza a simulação fiscal do pedido — útil para validar o cálculo de tributos e o conteúdo da DANFE antes de transmitir à SEFAZ. Usa `?Type=pdf` para retornar a DANFE em PDF; sem `Type`, retorna o XML simulado. A simulação roda o cálculo fiscal sem transmitir à SEFAZ.", "parameters": [ { "name": "Type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pdf" ] }, "description": "Quando `pdf`, retorna a DANFE em PDF. Omitido retorna XML." } ], "responses": { "200": { "description": "Documento simulado.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/xml": { "schema": { "type": "string" } } } }, "400": { "description": "Erro vindo do processo fiscal. Resposta repete o corpo retornado pelo processo.", "content": { "application/json": { "schema": { "type": "string" } } } }, "404": { "description": "Pedido não encontrado. Mensagem com prefixo `[NotFound]`: `Pedido não encontrar`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errorMessage": { "type": "string" } } } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/invoice/upload": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "post": { "operationId": "orderInvoiceUploadPost", "tags": [ "Pedidos" ], "summary": "Importa um XML de nota fiscal já emitida para o pedido", "description": "Importa um XML de NF-e/NFC-e autorizado para vincular ao pedido (cenário em que a nota foi emitida fora do idworks ou em sistema integrado). Validações:\n\n- XML precisa estar assinado (com `protNFe`).\n- CNPJ do emitente precisa bater com a empresa do pedido ou com uma empresa faturadora relacionada.\n- Quando a parametrização `ValidadeOrderInvoice` está ligada, valida o XML contra o schema da SEFAZ usando o certificado digital da faturadora.\n- Bloqueia XML já importado, pedido cancelado/excluído, pedido que já tenha nota vinculada (desvincular antes) e (a menos que `IgnoreTotalInvoiceValueImportOrder` esteja ligado) valor total da nota divergente do pedido.\n- Valida CPF/CNPJ do cliente.\n\nEm sucesso, atualiza o cabeçalho do pedido com os dados extraídos do XML, cria o registro da nota com a chave/protocolo/status, importa os impostos calculados nos itens (quando o item importado bate `IDSku`/`Quantity`/`PriceSelling` com a movimentação), salva o XML, importa as chaves referenciadas e registra um evento.", "requestBody": { "required": true, "content": { "application/xml": { "schema": { "type": "string", "description": "XML de NF-e/NFC-e assinado (com `protNFe`)." } } }, "description": "XML já autorizado da NF-e a importar/vincular ao pedido. O sistema valida assinatura (`protNFe` presente), conferência do CNPJ do emitente (precisa pertencer ao mesmo grupo da empresa) e bloqueia importação em pedidos cancelados/deletados." }, "responses": { "200": { "description": "XML importado e nota vinculada ao pedido.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Erros possíveis: `É necessário selecionar a conta`, `XML não é válido`, `XML não esta assinado`, `O arquivo não é um XML de Nota Fiscal válido`, `NF fiscal não pode ser importada em pedido com status cancelado/deletado`, `Empresa faturadora CNPJ: não localizada`, `Empresa faturadora não encontrada`, `Certificado digital não encontrado`, `XML já importado`, `Pedido já tem nota fiscal. Desvincular antes de importar uma nova`, `Número de série e NF informados já estão cadastrados para o IDOrder e faturador `, `Valor da NF diverge do valor do pedido. Valor total NF: `, `CPF/CNPJ do cliente é diferente do pedido`, e mensagens da SEFAZ (quando a validação contra schema falha).", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/invoice/{nfenumber}": { "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." }, { "name": "nfenumber", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Número da nota fiscal (mantido no path por convenção — o sistema resolve a nota pelo `idorder`)." } ], "put": { "operationId": "orderInvoicePut", "tags": [ "Pedidos" ], "summary": "Emite carta de correção (CC-e) na nota fiscal do pedido", "description": "Envia carta de correção à SEFAZ usando o motivo informado em `Comments`. Funciona apenas quando a nota está emitida. O número sequencial da CC-e é calculado pela quantidade de cartas já existentes (tipo de arquivo `6`). Em sucesso (`cStat=135` ou `136`), salva o XML protocolado como arquivo do tipo `6` e retorna as URLs do XML e da DANFE da carta. Em erro, retorna o `xMotivo` da SEFAZ.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Comments" ], "properties": { "Comments": { "type": "string", "description": "Motivo da correção (texto exibido na CC-e). Aceita URL-encoded." } } } } }, "description": "Carta de Correção Eletrônica (CCe) para a NF-e do pedido. `Comments` é o motivo/correção que vai para a SEFAZ. Só funciona com nota no status emitida (`IDStatusInvoice=3`)." }, "responses": { "200": { "description": "CC-e aceita. Retorna o arquivo criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "IDFile": { "type": "integer", "description": "Identificador do arquivo no idworks (extraído do nome do arquivo gerado)." }, "IDTypeFile": { "type": "integer", "enum": [ 6 ], "description": "Tipo do arquivo gerado — sempre `6` (Carta de Correção XML), já que este endpoint emite a CC-e." }, "UrlFileXml": { "type": "string", "description": "URL para baixar o XML da CC-e." }, "UrlFileDanfe": { "type": "string", "description": "URL para baixar a DANFE da CC-e em PDF." } } } } } }, "400": { "description": "Erros possíveis (`[BadRequest]`): `Nota Fiscal não esta no status emitida`, `Certificado digital não encontrado`, e mensagens da SEFAZ (texto do `xMotivo` vindo do retorno do evento).", "content": { "application/json": { "schema": { "type": "object", "properties": { "errorMessage": { "type": "string" } } } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "orderInvoiceDelete", "tags": [ "Pedidos" ], "summary": "Cancela a nota fiscal do pedido na SEFAZ", "description": "Cancela a nota fiscal emitida do pedido junto à SEFAZ. Funciona apenas com nota no status emitida. Quando o pedido tem notas referenciadas (retorno simbólico de importação), o cancelamento é replicado para cada uma delas. Quando a parametrização `Bloquear cancelamento de NF 24h após emissão` está ligada, recusa cancelamento de notas emitidas há mais de 24h. Em sucesso (`cStat=101/135/155`), grava o XML protocolado, atualiza a nota para cancelada e salva o XML do cancelamento como arquivo tipo `8`. Em erro, registra o evento e devolve o `xMotivo`.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "Comments": { "type": "string", "description": "Motivo do cancelamento. Default `Cancelamento de nota fiscal`." } } } } }, "description": "Cancelamento da NF-e do pedido. `Comments` é o motivo do cancelamento enviado à SEFAZ (padrão `Cancelamento de nota fiscal` quando omitido). Só permite cancelar notas no status emitida." }, "responses": { "200": { "description": "Cancelamento aceito pela SEFAZ.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Erros possíveis: `Nota Fiscal não esta no status emitida`, `Cancelamento de nota fiscal bloqueado por parametrização 24 horas após a emissão, NF emitida: `, `Certificado digital não encontrado`, e mensagens da SEFAZ (texto do `xMotivo` quando o cancelamento é recusado).", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Resposta com prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/carrier/edi": { "post": { "operationId": "carrierEdiPost", "tags": [ "Pedidos" ], "summary": "Envia EDI do pedido para a transportadora", "description": "Aciona a integração EDI configurada na transportadora do pedido — repassa os dados ao processo correspondente (Intelipost ou arquivo de EDI específico). Retorna a resposta do processo.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Retorno do processo EDI da transportadora.", "content": { "application/json": { "schema": { "type": "object", "description": "Conteúdo livre devolvido pelo processo EDI — formato depende da transportadora." } } } }, "400": { "description": "Pedido inexistente ou transportadora sem EDI configurado. Mensagens: `[BadRequest] - Pedido não encontrado`, `[BadRequest] - Transportadora não tem EDI configurado`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro retornado pelo processo EDI.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/carrier/quotation": { "get": { "operationId": "orderCarrierQuotationGet", "tags": [ "Pedidos" ], "summary": "Consulta a disputa de frete vinculada a um pedido", "description": "Retorna a disputa de frete mais recente registrada para o pedido com a lista de transportadoras que responderam. Já vem com os totais calculados (subtotal, total com ICMS, valor exibido) e ordenada por atendimento, prazo e valor.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Disputa encontrada (array de um único item) ou lista vazia se nunca houve disputa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotation" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "carrierAuctionPost", "tags": [ "Pedidos" ], "summary": "Dispara nova disputa de frete para o pedido", "description": "Soma o peso e o valor dos itens do pedido e dispara a consulta de cotação contra as transportadoras configuradas. Ao final, devolve o mesmo conteúdo de `GET /orders/{idorder}/carrier/quotation` com a disputa recém-criada.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Disputa criada e respondida pelas transportadoras.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotation" } } } } }, "400": { "description": "Pré-condições para a disputa não satisfeitas. Mensagens: `[BadRequest] - Pedido não encontrado`, `[BadRequest] - Pedido não tem CEP`, `[BadRequest] - Itens pedido não tem peso`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro reportado pelo processo de cotação.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/hub/{idorder}": { "get": { "operationId": "orderHubGetByOrder", "tags": [ "Pedidos" ], "summary": "Detalha um pedido integrado do hub", "description": "Retorna o pedido no marketplace junto com itens, pagamentos, mensagens, reclamações e ações disponíveis. Quando o pedido tem mensagens não lidas no Mercado Livre, marca-as como lidas via API antes de responder.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido no hub (`IDIntegration`). O endpoint aceita também o `IDOrder` do idworks quando consultado por essa chave pela mesma rota." } ], "responses": { "200": { "description": "Pedido localizado (array de um item) ou lista vazia se não houver correspondência.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubOrderDetail" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/hub/{idorder}/message": { "post": { "operationId": "orderHubMessageByOrderPost", "tags": [ "Pedidos" ], "summary": "Envia uma mensagem ao comprador do marketplace", "description": "Encaminha o conteúdo enviado ao canal de mensagens da integração do marketplace (mensagem normal do pedido ou mensagem de uma reclamação). Ao final retorna o detalhe atualizado do pedido no hub.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido idworks. A rota aceita também `idintegration` ou `idhuborderclaim` quando configurada com esses params alternativos." }, { "name": "Type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tipo de operação a executar na integração — `send_message` (padrão) ou outro valor suportado pelo processo para o marketplace específico." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Conteúdo da mensagem. O shape depende do marketplace (texto, anexos, opções de envio). Encaminhado integralmente ao processo da integração." } } }, "description": "Mensagem para a central de mensagens do canal (Mercado Livre, B2W etc.). O conteúdo é repassado ao canal; a estrutura específica varia por canal — ver documentação do canal correspondente." }, "responses": { "200": { "description": "Pedido no hub recarregado com a nova mensagem.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubOrderDetail" } } } } }, "400": { "description": "Pré-condições não satisfeitas. Mensagens: `[BadRequest] - Pedido não encontrado no hub`, `[BadRequest] - Integracão não tem envio de mensagem`, `[BadRequest] - Integracão não tem consulta de status` (quando o processo responde 404).", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro retornado pelo processo da integração.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/tracking/{idorder}": { "get": { "operationId": "orderTrackingGet", "tags": [ "Pedidos" ], "summary": "Consulta os eventos de rastreio já registrados para o pedido", "description": "Devolve os volumes do pedido e seus eventos de tracking já armazenados pelo idworks, junto com indicadores de cumprimento de prazo (consumidor e transportadora). Não dispara consulta nova à transportadora — para isso use `GET /orders/tracking/{idorder}/check`.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Pedido encontrado (array com um item) ou vazio quando o pedido não tem rastreio.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrderTrackingDetail" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/tracking/{idorder}/check": { "get": { "operationId": "checkTrackingStatusGet", "tags": [ "Pedidos" ], "summary": "Força a atualização do rastreio junto à transportadora", "description": "Dispara a consulta dos eventos mais recentes diretamente na transportadora do pedido (ou nos Correios quando o tipo é compatível) e devolve, ao final, a mesma estrutura de `GET /orders/tracking/{idorder}` já atualizada.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Rastreio atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrderTrackingDetail" } } } } }, "400": { "description": "Pré-condições não satisfeitas. Mensagens: `[BadRequest] - Pedido não existe`, `[BadRequest] - Tipo Transportadora não existe`, `[BadRequest] - Pacote não tem código de rastreio`, e erros do processo prefixados com `[BadRequest] -`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/return": { "post": { "operationId": "orderReturn", "tags": [ "Pedidos" ], "summary": "Gera o pedido de devolução a partir de um pedido existente", "description": "Recalcula o rateio de frete/despesas acessórias do pedido original, monta os itens (com quantidades negativas) e os pagamentos espelhados, e cria um pedido do tipo devolução. Pode opcionalmente reverter estoque, gerar recebimento, emitir nota fiscal de devolução e abrir voucher para o cliente. Ao final invoca `GET /orders/{idorder}` no pedido criado e devolve o detalhe.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido original que está sendo devolvido." }, { "name": "idtypeorderreturn", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Tipo de devolução (alternativa para chamadas só com query)." }, { "name": "idtypeorderreturncategory", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Categoria do tipo de devolução." }, { "name": "comments", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Observações." }, { "name": "balancechange", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Afeta estoque (`1`/`0`). Padrão `1`." }, { "name": "withvalue", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Mantém valores do pedido original (`1`/`0`). Padrão `1`." }, { "name": "idstockkeepingunitwarehouse", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Armazém destino." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderReturnBody" } } }, "description": "Parâmetros da devolução. Os mesmos campos podem ser passados em query string (snake_case). Sem `Items`, devolve todas as movimentações do pedido." }, "responses": { "200": { "description": "Pedido de devolução criado — devolve a estrutura completa do pedido criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "400": { "description": "Validações de cadastro. Mensagens: `[BadRequest] - Tipo devolução não existe`, `[BadRequest] - Tipo pedido de devolução não existe ou não está configurado corretamente. Precisa cadastrar`, `[BadRequest] - Armazém não existe`, `[BadRequest] - Tipo categoria devolução não existe`, `[BadRequest] - Cliente não existe`, `[BadRequest] - Endereço não existe`. Erros vindos da criação de pedido também chegam com a mensagem original.", "content": { "application/json": { "schema": { "type": "string" } } } }, "404": { "description": "Pedido original inexistente. Mensagem: `[NotFound] - Pedido não encontrado`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/invoice-xml": { "post": { "operationId": "OrderInvoiceXmlGet", "tags": [ "Pedidos" ], "summary": "Solicita o pacote ZIP com os XMLs de NFe dos pedidos", "description": "Gera de forma assíncrona um arquivo ZIP com os XMLs (autorização, cancelamento, inutilização, carta de correção) dos pedidos ou arquivos informados, sobe o ZIP em armazenamento temporário e envia o link de download por e-mail ao usuário que disparou a requisição. A resposta imediata é a URL pré-assinada de download (válida por 2 dias). Os filtros recebidos por query string entram no nome do arquivo gerado.", "parameters": [ { "name": "Key", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "IDFile", "IDOrder" ] }, "description": "Define se o conteúdo enviado no body é uma lista de identificadores de arquivos (`IDFile`) ou de pedidos (`IDOrder`, padrão)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "Lista de identificadores a empacotar (pedidos ou arquivos, conforme `Key`).", "items": { "type": "integer" } } } }, "description": "Array de IDs (de `IDFile`, `IDOrder` ou `IDNfCompany` conforme `?Key=`) cujos XMLs serão zipados e enviados por e-mail ao usuário solicitante." }, "responses": { "200": { "description": "URL temporária do ZIP gerado. O link também é enviado por e-mail.", "content": { "application/json": { "schema": { "type": "string", "description": "URL pré-assinada do ZIP." } } } }, "400": { "description": "Erro de validação — XML ausente, inválido ou não corresponde a uma NF-e processável.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro de upload do ZIP, falha de envio de e-mail ou erro interno. Prefixos `zipFile.upload error ...`, `catched error: ...` ou `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/invoice-xml/import": { "post": { "operationId": "orderImportXml", "tags": [ "Pedidos" ], "summary": "Importa um pedido a partir do XML de uma NF-e", "description": "Recebe o XML autorizado de uma NF-e e cria o pedido no idworks com itens, impostos, cliente, endereços e pagamentos extraídos. Quando os SKUs não estão cadastrados, a importação falha — exceto se a parametrização **Criar SKU automaticamente quando não existir** estiver ativa. Quando configurado, valida a assinatura junto à SEFAZ antes de importar.", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Integração que recebe o pedido importado." }, { "name": "importtype", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3, 5 ] }, "description": "Como localizar o SKU: `1` código do fornecedor, `2` código de barras (cEAN), `3` `IDSkuCompany` excluindo produto, `5` anúncio do hub. Quando omitido, tenta a sequência completa." }, { "name": "IDStockKeepingUnitWarehouse", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Armazém origem dos itens." }, { "name": "BalanceChange", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Se a importação deve afetar o saldo de estoque." }, { "name": "IDOrderType", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Tipo do pedido que será criado." }, { "name": "IDStatusOrder", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Status inicial do pedido criado." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Empresa faturadora. Quando omitida, usa a própria empresa autenticada." }, { "name": "CreateInbound", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Se deve criar um recebimento atrelado." }, { "name": "IDStockKeepingUnitWarehouseInbound", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Armazém de recebimento (quando `CreateInbound=1`)." }, { "name": "FinishInbound", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Se deve já finalizar o recebimento." }, { "name": "OrderFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Número de origem do pedido (sobrescreve `xPed` do XML)." }, { "name": "IDOrderFrom", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Pedido idworks de origem (para casos de devolução vinculada)." }, { "name": "Negative", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, sinais de frete/despesas/pagamentos são invertidos (devolução)." }, { "name": "AnyVariationIfProduct", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, aceita uma variação qualquer caso o código bata com um produto-pai." }, { "name": "SalesmanUserExtenalId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Vendedor identificado pelo identificador externo do usuário." }, { "name": "SalesmanUserId", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Vendedor identificado por `IDUser`." }, { "name": "IDStoreFrontCashier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Caixa do PDV vinculado ao pedido." }, { "name": "Payments", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Pagamentos a aplicar — cada item no formato `IDTypePayment,Value,InstallmentTotal,TID,NSU`. A soma precisa bater com o valor da NF." }, { "name": "IDNfCompany", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "NF previamente armazenada no idworks que deve receber esse pedido." } ], "requestBody": { "required": true, "content": { "application/xml": { "schema": { "type": "string", "description": "Conteúdo do XML autorizado (com `protNFe`)." } }, "application/json": { "schema": { "type": "string", "description": "XML serializado como string JSON, alternativo ao `application/xml`." } } }, "description": "XML de NF-e a importar como pedido. O sistema cria pedido, cliente, itens e movimentações de estoque conforme parametrização (`importtype`, `BalanceChange`, `IDStockKeepingUnitWarehouse` em query)." }, "responses": { "200": { "description": "Pedido criado.", "content": { "application/json": { "schema": { "type": "object", "description": "Resultado do processamento — geralmente o pedido criado." } } } }, "400": { "description": "Validações da NF/SEFAZ ou de pré-cadastro. Mensagens conhecidas: `Precisar enviar o XML no body da requisição`, `Erro ao converter XML`, `É necessário selecionar a conta`, `Precisa informar a integração`, `XML não esta assinado`, `XML já importado`, `Emissor da NF diferente da empresa no sistema idworks`, `Nota fiscal emitida em homologação`, `Número de série e NF informados já estão cadastrados para o pedido `, `Empresa faturadora não encontrada`, `NF não encontrada`, `NF já vinculada ao pedido `, `Certificado digital não encontrado`, `Erro validação SEFAZ`, `Armazém recebimento não cadastrado`, `SKU(s) não cadastrados: ...`, `SKU(s) sem codigo de barras cadastrados na nota fiscal`, `Tipo pagamento não cadastrado`, `Valor total do pagamento diverge do valor total da NF`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno do processo de retaguarda. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/template": { "get": { "operationId": "orderFileTemplateExportGet", "tags": [ "Pedidos" ], "summary": "Baixa o template de planilha para importação ou edição em lote", "description": "Devolve a planilha modelo correspondente ao tipo informado: pedidos (padrão), atualização de status de pedido, contas a pagar/receber, impostos de marketplace e ordens de serviço.", "parameters": [ { "name": "Type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Order", "OrderStatus", "AccountsPayable", "AccountsReceivable", "MarketplaceTaxes", "ServiceOrder" ] }, "description": "Tipo de planilha. Padrão `Order`." } ], "responses": { "200": { "description": "Arquivo XLSX retornado (planilha modelo).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Tipo inválido. Mensagem: `tipo de template não informado`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "orderFileTemplateImport", "tags": [ "Pedidos" ], "summary": "Importa planilha de pedidos / contas a pagar / contas a receber em lote", "description": "Recebe o arquivo enviado via multipart, salva no armazenamento temporário, cria um job e dispara o processamento assíncrono. A resposta retorna imediatamente o identificador do job — o resultado é enviado posteriormente por e-mail. Se já existe um job em andamento com o mesmo hash de arquivo, devolve o job existente.", "parameters": [ { "name": "Type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "AccountsPayable", "AccountsReceivable" ] }, "description": "Tipo de importação: omitido importa pedidos (padrão), `AccountsPayable` importa contas a pagar, `AccountsReceivable` importa contas a receber." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Planilha a importar." } } } } }, "description": "Disparo assíncrono do gerador de template — a chamada retorna imediatamente sem bloquear o cliente. Body opcional; quando enviado, é repassado integralmente para o gerador." }, "responses": { "200": { "description": "Job criado ou já em andamento. O resultado da importação chega por e-mail quando o processamento terminar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "IDJob": { "type": "integer", "description": "Identificador do job em processamento." }, "Message": { "type": "string", "description": "Mensagem amigável (geralmente `Arquivo em processamento, aguardar resposta por email`)." } } } } } }, "400": { "description": "Quando o body está vazio, o sistema responde com status `400` (sem `errorMessage`).", "content": { "application/json": {} } }, "404": { "description": "Empresa não encontrada para o `accountname` do contexto.", "content": { "application/json": {} } }, "500": { "description": "Erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "put": { "operationId": "orderFileTemplateExportPut", "tags": [ "Pedidos" ], "summary": "Aplica atualizações em lote a partir do template", "description": "Recebe os dados editados na planilha de template e aciona a rotina de atualização correspondente (ex.: alteração de status em massa pelo `Type=OrderStatus`). Consulte a tela do frontend que monta a planilha para o layout exato das colunas.", "parameters": [ { "name": "Type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Order", "OrderStatus", "AccountsPayable", "AccountsReceivable", "MarketplaceTaxes", "ServiceOrder" ] }, "description": "Tipo de atualização. Padrão `Order`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Conteúdo da planilha já estruturado." } } }, "description": "Conteúdo da planilha já estruturado para importação de pedidos — o layout das colunas segue a planilha modelo exportada por `GET /orders/template`." }, "responses": { "200": { "description": "Atualização aplicada. Conteúdo retornado depende do tipo.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validações. Mensagem: `tipo de template não informado`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/tag": { "get": { "operationId": "ordersTagList", "tags": [ "Pedidos" ], "summary": "Lista as etiquetas (tags) dos pedidos", "description": "Retorna o conjunto distinto de tags aplicadas aos pedidos da empresa, em ordem alfabética. Quando um `IDOrder` é informado, restringe à(s) tag(s) daquele pedido.", "parameters": [ { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Restringe a busca às tags de um pedido específico." } ], "responses": { "200": { "description": "Lista de tags.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "Tag": { "type": "string", "description": "Texto da etiqueta." }, "AccountName": { "type": "string", "description": "Conta dona da etiqueta." } } } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/duplicate": { "post": { "operationId": "orderDuplicate", "tags": [ "Pedidos" ], "summary": "Duplica um pedido existente", "description": "Cria uma cópia do pedido (com a opção de classificá-lo como reenvio, manter ou zerar valores e usar valor médio dos itens). Ao terminar, devolve o detalhe completo do pedido recém-criado.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido a duplicar." }, { "name": "IDTypeOrderResend", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Motivo do reenvio quando o duplicado representa uma reentrega." }, { "name": "Comments", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Observações a registrar no novo pedido." }, { "name": "BalanceChange", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Se a duplicação afeta saldo de estoque. Padrão `1`." }, { "name": "WithValue", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Mantém os valores do pedido original (`1`) ou zera (`0`)." }, { "name": "WithBatch", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Mantém os lotes do pedido original." }, { "name": "AverageValue", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, usa o valor médio dos itens em vez do valor original." } ], "responses": { "200": { "description": "Pedido duplicado — devolve a estrutura completa do pedido criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "404": { "description": "Pedido original não encontrado. Mensagem: `[NotFound] - Pedido não encontrado`.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro na duplicação ou erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/label": { "get": { "operationId": "orderLabelGet", "tags": [ "Pedidos" ], "summary": "Gera a etiqueta de envio do pedido", "description": "Monta a etiqueta de envio do pedido conforme a transportadora — pode usar layout customizado da empresa, etiqueta manual cadastrada no pedido, integração com marketplace/transportadora (Mercado Envios, Magalu Entregas, Shopee, Olist, Loggi, Total Express, Smartenvios, etc.) ou um dos templates padrão (Correios, padrão genérico, etiqueta de inconformidade). Retorna PDF (padrão) ou ZPL conforme os parâmetros e, dependendo da parametrização **Status do pedido após gerar etiqueta**, atualiza o status do pedido.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." }, { "name": "Download", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, força download do arquivo ZPL. Quando `0` e o canal retorna ZPL, devolve em texto puro. Sem o parâmetro, devolve um PDF gerado a partir do ZPL pelo serviço Labelary." }, { "name": "PackageNumber", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Número do volume específico a imprimir. Sem o parâmetro, imprime todos." }, { "name": "Zpl", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Marca que a saída deve ser tratada como ZPL." }, { "name": "OnlyLabel", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, devolve só a etiqueta — não inclui a DANFE." }, { "name": "OnlyInvoice", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, devolve só a nota fiscal/DANFE. Permite gerar mesmo sem transportadora cadastrada." }, { "name": "IDCompanyLabel", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Layout de etiqueta customizado da empresa a aplicar." }, { "name": "OnlyCheck", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, não atualiza o status do pedido após gerar a etiqueta." }, { "name": "Type", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 2 ] }, "description": "Quando `2`, imprime a etiqueta de inconformidade em vez da etiqueta de envio." }, { "name": "debug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sinalizador interno repassado para os workers de integração." } ], "responses": { "200": { "description": "Etiqueta gerada — formato depende dos parâmetros.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/epl2": { "schema": { "type": "string", "description": "Conteúdo ZPL (download direto)." } }, "text/plain": { "schema": { "type": "string", "description": "Conteúdo ZPL em texto." } }, "application/json": { "schema": { "type": "object", "description": "Resposta JSON quando o canal retorna apenas um link para a etiqueta (ex.: `LabelUrl`)." } } } }, "400": { "description": "Pré-condições não satisfeitas. Mensagens conhecidas: `Pedido não encontrado`, `Pedido sem transportadora`, `Nota fiscal não emitida`, `Etiqueta manual não localizada`, `Problema ao gerar etiqueta`, `Erro ao gerar etiqueta`, `Erro ao gerar PDF. Por favor clicar no botao de imprimir.` e a mensagem `errorMessage` do processo da transportadora quando aplicável.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/promotion": { "get": { "operationId": "orderPromotionGet", "tags": [ "Pedidos" ], "summary": "Lista as promoções/benefícios aplicados ao pedido", "description": "Retorna em uma só estrutura as promoções de PDV vinculadas ao pedido e os benefícios oriundos do marketplace (quando o pedido vem do hub).", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Sempre retorna um array de um item — listas vazias quando não há promoção/benefício.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrderPromotion" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/orders/{idorder}/start-handling": { "post": { "operationId": "orderStartHandling", "tags": [ "Pedidos" ], "summary": "Inicia o processamento (handling) de um pedido", "description": "Marca o pedido como em separação/processamento. Quando `NoInvoke=1`, devolve apenas a string `\"sucesso\"`; caso contrário, retorna o detalhe completo do pedido após a mudança.", "parameters": [ { "name": "idorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." }, { "name": "NoInvoke", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, evita a chamada de `OrderGet` ao final — retorna apenas a string `sucesso`." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "StatusComment": { "type": "string", "description": "Observação registrada na mudança de status." } } } } }, "description": "Inicia o manuseio (handling) do pedido — usado pela tela de Outbound. `StatusComment` opcional registra observação no histórico de status." }, "responses": { "200": { "description": "Pedido em processamento. Estrutura varia conforme `NoInvoke`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/OrderDetail" }, { "type": "string", "description": "Quando `NoInvoke=1`, devolve `\"sucesso\"`." } ] } } } }, "400": { "description": "Pedido inexistente. Mensagem: `[BadRequest] - Pedido não encontrado`. Erros do processamento são repassados como JSON na string.", "content": { "application/json": { "schema": { "type": "string" } } } }, "500": { "description": "Erro interno. Prefixo `Error:`.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/hub/carrier": { "get": { "operationId": "hubCarrierList", "tags": [ "Hub — DE-PARA Transportadora" ], "summary": "Lista mapeamentos — DE-PARA Transportadora", "description": "Retorna todos os DE-PARA cadastrados, ordenados por integração e nome.", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelos DE-PARA de uma integração específica." }, { "name": "IDCarrierFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo identificador da transportadora no canal." }, { "name": "IDCarrierTo", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pela transportadora interna mapeada." } ], "responses": { "200": { "description": "Array de mapeamentos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubCarrierMapping" } } } } } } }, "post": { "operationId": "hubCarrierPost", "tags": [ "Hub — DE-PARA Transportadora" ], "summary": "Cria mapeamento — DE-PARA Transportadora", "description": "Cria um novo DE-PARA e devolve a lista completa atualizada (re-invoca o List). Quando `CarrierAuctionByModal=1`, o sistema força `IDCarrierTo` para `null` — a transportadora final será escolhida em runtime pelo leilão por modal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubCarrierCreateBody" } } }, "description": "Mapeamento de transportadora a cadastrar. `IDCompanyIntegration` e `IDCarrierFrom` são obrigatórios. Quando `CarrierAuctionByModal = 1`, `IDCarrierTo` é forçado a `null` pelo servidor — a transportadora é escolhida em tempo de roteirização via leilão entre transportadoras do modal indicado em `IDCarrierModal`." }, "responses": { "200": { "description": "Lista atualizada após a criação.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubCarrierMapping" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Integração não cadastrada`\n- `Transportadora não cadastrada`\n- `Status pedido não existe`\n- `Modal não existe`\n- `Armazém não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/carrier/{idhubcarrier}": { "put": { "operationId": "hubCarrierPut", "tags": [ "Hub — DE-PARA Transportadora" ], "summary": "Atualiza mapeamento — DE-PARA Transportadora", "description": "Atualiza um DE-PARA existente e devolve a lista completa atualizada. Mesmas validações do POST.", "parameters": [ { "name": "idhubcarrier", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do mapeamento." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubCarrierUpdateBody" } } }, "description": "Mesma estrutura do POST. Todos os campos são revalidados." }, "responses": { "200": { "description": "Lista atualizada após a edição.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubCarrierMapping" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `de/para transportadora não existe`\n- `Integração não cadastrada`\n- `Transportadora não cadastrada`\n- `Status pedido não existe`\n- `Modal não existe`\n- `Armazém não existe`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubCarrierDelete", "tags": [ "Hub — DE-PARA Transportadora" ], "summary": "Remove mapeamento — DE-PARA Transportadora", "description": "Apaga o DE-PARA e devolve a lista completa atualizada.", "parameters": [ { "name": "idhubcarrier", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do mapeamento." } ], "responses": { "200": { "description": "Lista atualizada após remoção.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubCarrierMapping" } } } } }, "400": { "description": "`[BadRequest] - IDHubCarrier não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/carrier/auction": { "get": { "operationId": "hubCarrierAuctionGet", "tags": [ "Hub — DE-PARA Transportadora" ], "summary": "Cotação de frete — leilão entre transportadoras", "description": "Dispara o motor de cotação de frete (leilão) entre as transportadoras cadastradas. `GET` e `POST` da mesma rota têm o mesmo comportamento. Retorna a lista de transportadoras com `ShippingShowValue`, `TotalShowDaysTime`, `Attended` e os componentes de preço (ICMS, GRIS, advalorem, pedágio etc.).", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Quando informado, identifica a integração de origem da cotação (canal externo)." }, { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Tipo de integração — usado para entregar o response no formato esperado pelo canal (Tray, Meli, Convertize, etc.)." }, { "name": "debug", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, imprime o trace de cada regra avaliada." }, { "name": "online", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, persiste a cotação temporariamente sob a chave `CarrierQuotation:` (permitindo respostas subsequentes via `If-None-Match`). Default `0`." } ], "responses": { "200": { "description": "Resultado da cotação.", "content": { "application/json": { "schema": { "type": "object", "description": "Payload do motor de cotação — campos exatos não confirmados." } } } }, "304": { "description": "Resposta condicional — o `If-None-Match` enviado ainda é válido para o canal e a cotação anterior não mudou." }, "400": { "description": "Erros de negócio. Exemplos: `Empresa não localizada`, `Precisa enviar corpo`, `Precisa enviar o CEP destino`, `Peso precisa ser maior que zero`, `CEP destino XXXXX não existe`, `Dados para cotação não enviados`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "post": { "operationId": "hubCarrierAuctionPost", "tags": [ "Hub — DE-PARA Transportadora" ], "summary": "Cotação de frete — leilão entre transportadoras", "description": "Mesma função de `GET /hub/carrier/auction`, porém recebe os dados da cotação no corpo da requisição. O corpo tem ao menos `ShippingPostalCode` (CEP destino) e um array `Quotations[]` com `Weight`, `Height`, `Length`, `Width`, `ValueInvoice` por volume; aceita também `OriginPostalCode`, `Description`, `IDOrder`, `IDCompanyIntegration`, `IDSkuHub`, `IDSkuCompany`, `IDTypeCompanyIntegration`, `RecordUserCreated`.", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo identificador da integração da empresa." }, { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pelo tipo de integração da empresa." }, { "name": "debug", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, inclui informações adicionais de depuração na resposta." }, { "name": "online", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, restringe a integrações ou canais online." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Dados da cotação.", "properties": { "ShippingPostalCode": { "type": "string", "description": "CEP destino (somente números, padding à esquerda em 8 dígitos)." }, "OriginPostalCode": { "type": "string", "nullable": true, "description": "CEP origem. Quando omitido, usa o CEP da empresa." }, "ValueInvoice": { "type": "number", "nullable": true, "description": "Valor total da nota — referência para advalorem, GRIS e regras por faixa de valor." }, "IDOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "Pedido associado, quando a cotação está vinculada a um pedido existente." }, "Description": { "type": "string", "nullable": true, "description": "Descrição opcional da cotação (rótulo livre)." }, "RecordUserCreated": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do usuário que originou a cotação." }, "Quotations": { "type": "array", "description": "Volumes a cotar.", "items": { "type": "object", "properties": { "Weight": { "type": "number", "description": "Peso bruto (kg)." }, "Height": { "type": "number", "description": "Altura (cm)." }, "Length": { "type": "number", "description": "Comprimento (cm)." }, "Width": { "type": "number", "description": "Largura (cm)." }, "ValueInvoice": { "type": "number", "description": "Valor da nota do volume." } } } } } } } }, "description": "Dados da cotação de frete. Mínimo: `ShippingPostalCode` (CEP destino) e um array `Quotations[]` com `Weight`, `Height`, `Length`, `Width` e `ValueInvoice` por volume. Campos opcionais: `OriginPostalCode`, `Description`, `IDOrder`, `RecordUserCreated`." }, "responses": { "200": { "description": "Resultado da cotação.", "content": { "application/json": { "schema": { "type": "object", "description": "Payload do motor de cotação — campos exatos não confirmados." } } } }, "400": { "description": "Erros de negócio: `Precisa enviar corpo`, `Precisa enviar o CEP destino`, `Peso precisa ser maior que zero`, `CEP destino XXXXX não existe`, `Empresa não localizada`, `Dados para cotação não enviados`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/carrier/auction/{idcompanyintegration}": { "get": { "operationId": "hubCarrierAuctionByIntegrationGet", "tags": [ "Hub — DE-PARA Transportadora" ], "summary": "Cotação de frete a partir de uma integração específica", "description": "Mesma função das rotas `/hub/carrier/auction`, porém a integração de origem da cotação vem como parâmetro de path em vez de query.", "parameters": [ { "name": "idcompanyintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Integração de origem da cotação." } ], "responses": { "200": { "description": "Resultado da cotação.", "content": { "application/json": { "schema": { "type": "object", "description": "Payload do motor de cotação — campos exatos não confirmados." } } } }, "400": { "description": "Erros de negócio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/acquirer": { "get": { "operationId": "hubAcquirerList", "tags": [ "Hub — DE-PARA Adquirentes" ], "summary": "Lista mapeamentos — DE-PARA Adquirentes", "description": "Retorna todos os DE-PARA de adquirente cadastrados, ordenados pela integração.", "parameters": [ { "name": "IDAcquirerFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo identificador da adquirente no canal." }, { "name": "IDAcquirerTo", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pela adquirente cadastrada no idworks (`CompanyIntegration` do tipo adquirente)." } ], "responses": { "200": { "description": "Array de mapeamentos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubAcquirerMapping" } } } } } } }, "post": { "operationId": "hubAcquirerPost", "tags": [ "Hub — DE-PARA Adquirentes" ], "summary": "Cria mapeamento — DE-PARA Adquirentes", "description": "Cria um DE-PARA e devolve a lista atualizada (re-invoca o List). O sistema rejeita duplicidade exata (mesma integração, mesma adquirente do canal e mesma adquirente interna).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubAcquirerCreateBody" } } }, "description": "Mapeamento de adquirente a cadastrar. `IDAcquirerFrom` é o código da adquirente no canal (texto livre); `IDAcquirerTo` referencia outra `CompanyIntegration` da mesma empresa, do tipo adquirente." }, "responses": { "200": { "description": "Lista atualizada após criação.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubAcquirerMapping" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Integração não cadastrada`\n- `Integração adquirente não cadastrada`\n- `Já existe um de/para igual criado`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/acquirer/{idhubacquirer}": { "put": { "operationId": "hubAcquirerPut", "tags": [ "Hub — DE-PARA Adquirentes" ], "summary": "Atualiza mapeamento — DE-PARA Adquirentes", "description": "Atualiza um DE-PARA e devolve a lista atualizada. Mesmo body do POST. O sistema rejeita duplicidade contra outros registros existentes.", "parameters": [ { "name": "idhubacquirer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do mapeamento." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubAcquirerCreateBody" } } }, "description": "Mesma estrutura do POST. Todos os campos são revalidados." }, "responses": { "200": { "description": "Lista atualizada após edição.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubAcquirerMapping" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `De/Para adquirente não existe`\n- `Integração adquirente não cadastrada`\n- `Já existe um de/para igual criado`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubAcquirerDelete", "tags": [ "Hub — DE-PARA Adquirentes" ], "summary": "Remove mapeamento — DE-PARA Adquirentes", "description": "Apaga o DE-PARA.", "parameters": [ { "name": "idhubacquirer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do mapeamento." } ], "responses": { "200": { "description": "Texto literal `sucesso` quando a remoção é concluída.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "`[BadRequest] - De/Para adquirente não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/variation": { "get": { "operationId": "hubVariationList", "tags": [ "Hub — DE-PARA Variações" ], "summary": "Lista mapeamentos — DE-PARA Variações", "description": "Retorna os DE-PARA de variação cadastrados, ordenados por integração.", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pela integração." }, { "name": "IDVariationTo", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Filtra pela variação interna (`IDTypeProductVariation`)." }, { "name": "VariationName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca textual no nome da variação interna (`ProductVariation`) via `LIKE`." } ], "responses": { "200": { "description": "Array de mapeamentos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubVariationMapping" } } } } } } }, "post": { "operationId": "hubVariationPost", "tags": [ "Hub — DE-PARA Variações" ], "summary": "Cria mapeamento — DE-PARA Variações", "description": "Cria um DE-PARA e devolve a lista atualizada (re-invoca o List). O sistema valida unicidade do trio (variação interna, integração, DE-PARA de categoria).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubVariationCreateBody" } } }, "description": "Mapeamento de variação a cadastrar. A categoria do canal (`IDHubCategory`) intermedeia o mapeamento porque os atributos de variação disponíveis dependem da categoria do produto." }, "responses": { "200": { "description": "Lista atualizada após criação.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubVariationMapping" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Integração não cadastrada`\n- `Variação não cadastrada`\n- `Hub Categoria não existe`\n- `Já existe um de/para igual criado`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/variation/{idhubvariation}": { "put": { "operationId": "hubVariationPut", "tags": [ "Hub — DE-PARA Variações" ], "summary": "Atualiza mapeamento — DE-PARA Variações", "description": "Atualiza um DE-PARA e devolve a lista atualizada. Mesmas validações do POST mais a verificação de existência do registro.", "parameters": [ { "name": "idhubvariation", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do mapeamento." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubVariationCreateBody" } } }, "description": "Mesma estrutura do POST. Todos os campos são revalidados." }, "responses": { "200": { "description": "Lista atualizada após edição.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubVariationMapping" } } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `De/Para variação não existe`\n- `Variação não cadastrada`\n- `Hub Categoria não existe`\n- `Já existe um de/para igual criado`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } }, "delete": { "operationId": "hubVariationDelete", "tags": [ "Hub — DE-PARA Variações" ], "summary": "Remove mapeamento — DE-PARA Variações", "description": "Apaga o DE-PARA e devolve a lista atualizada.", "parameters": [ { "name": "idhubvariation", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do mapeamento." } ], "responses": { "200": { "description": "Lista atualizada após remoção.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubVariationMapping" } } } } }, "400": { "description": "`[BadRequest] - IDHubVariation não existe`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/resource/auth": { "get": { "operationId": "hubResourceAuthGet", "tags": [ "Hub — Recursos" ], "summary": "Callback de autenticação OAuth do canal", "description": "Endpoint de **callback** chamado pelos canais de venda após o usuário autorizar o idworks. Resolve a integração a partir de `state`/`reference`/`IDCompanyIntegration` (ou de credenciais específicas em `code`/`store`) e despacha para o fluxo de autenticação do tipo de integração — Bling, Cielo, Mercado Livre, Shopee, Olist, Amazon, Shopify, Mercado Pago, Tray, Magalu, Melhor Envio, Shein, Nuvemshop, TikTok, R3Express, Temu, Integra. Cada provedor tem seu próprio formato de corpo e resposta (HTML de redirect, JSON).", "parameters": [ { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Integração da empresa para a qual o callback se aplica. Quando ausente, o sistema tenta resolver via `state`, `reference`, `store` ou credenciais do canal." }, { "name": "IDTypeCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Tipo de integração. Usado para rotear o callback (ex.: `IDTYPECOMPANYINTEGRATION_INTEGRA`, `IDTYPECOMPANYINTEGRATION_NUVEMSHOP`)." }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Token de estado OAuth (`Token`) usado para correlacionar o callback com a integração originalmente disparada." }, { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Alias de `state` para provedores que repassam o token como `reference`." }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código de autorização devolvido pelo canal — usado nos fluxos OAuth padrão para trocar por token." }, { "name": "store", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador da loja no canal (`store_id`) — usado pelo Tray para localizar a integração." }, { "name": "an", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Subdomínio da conta — usado quando não há `requestContext` (chamadas externas diretas)." }, { "name": "shop_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador da loja no Shopee, repassado no callback de autorizacao do canal." }, { "name": "main_account_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador da conta principal no Shopee, repassado no callback quando a loja pertence a uma conta principal." }, { "name": "selling_partner_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador do vendedor (selling partner) devolvido pela Amazon no callback de autorizacao." }, { "name": "spapi_oauth_code", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Codigo de autorizacao OAuth da Amazon SP-API, usado no lugar de code no callback da Amazon." }, { "name": "api_address", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Endereco base da API da loja, repassado pela Tray no callback do canal." }, { "name": "url", "in": "query", "required": false, "schema": { "type": "string" }, "description": "URL da loja, repassada pela Tray no callback do canal." }, { "name": "tempToken", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Token temporario de autorizacao devolvido pela Shein no callback, trocado em seguida por token de acesso." }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Token de autorizacao devolvido pela R3Express no callback." }, { "name": "shop", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Dominio da loja Shopify devolvido no callback de instalacao do aplicativo." } ], "responses": { "200": { "description": "Resposta específica do canal — HTML de redirect, JSON com tokens ou texto plano." }, "400": { "description": "Erros de negócio:\n- `Precisa a query string IDCompanyIntegration ou state`\n- `Integração não encontrada. Verificar se a integração já esta cadastrada na idworks e os dados preenchidos (clicar na engrenagem)`\n- `Integração não tem autenticação por URL`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } } } } }, "/hub/resource/{idtypecompanyintegration}": { "get": { "operationId": "companyIntegrationResourceList", "tags": [ "Hub — Recursos" ], "summary": "Lista recursos disponíveis do tipo de integração", "description": "Retorna os recursos (`TypeSalesChannelResource`) cadastrados para o tipo de integração e o `ResourceType` indicado. Para `ResourceType=Autoparts`, o sistema ainda valida que a categoria `CategoryId` está na lista de categorias suportadas — se não estiver, devolve `[]` em vez da lista completa.", "parameters": [ { "name": "idtypecompanyintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Tipo de integração (canal)." }, { "name": "ResourceType", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Tipo de recurso a listar (ex.: `Autoparts`, `Category`, `CategoryAttribute`, `SkuCondition`, `TypeOffer`, `ModeShipping`, `OfficialStore`)." }, { "name": "CategoryId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador de categoria do canal. Obrigatório quando `ResourceType=Autoparts` para filtrar pela lista oficial do canal." } ], "responses": { "200": { "description": "Array de recursos disponíveis (vazio quando nenhum recurso casa com o filtro, ou quando a categoria não suporta `Autoparts`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubIntegrationResource" } } } } } } }, "post": { "operationId": "companyIntegrationResourcePost", "tags": [ "Hub — Recursos" ], "summary": "Consulta valores do recurso no canal", "description": "Atua como proxy para o serviço externo que consulta o canal de venda. Resolve o recurso cadastrado (identificado por IDTypeSalesChannelResource) e dispara um GET ao processo do canal enviando o conjunto de query params relevante para aquele recurso (categoria, marca, gênero, grade de tamanho, dados do anúncio, custos, restrições por veículo, etiqueta/coleta, etc.). O comportamento de cache da resposta é definido pelo cadastro do recurso, não por campo enviado pelo cliente: sem cache (sempre consulta o canal), com cache (busca a resposta armazenada e, em miss, consulta o canal e armazena por 3 dias) ou só-leitura de cache (usa a resposta armazenada, alimentada por outro processo).", "parameters": [ { "name": "idtypecompanyintegration", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Tipo de integração (canal)." }, { "name": "IDTypeSalesChannelResource", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do recurso cadastrado em `TypeSalesChannelResource` (vem do `GET /hub/resource/{idtypecompanyintegration}`)." }, { "name": "IDHubProduct", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Produto Hub interno a que a consulta se refere (quando o recurso depende do produto)." }, { "name": "IDHubAdvertisement", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Anúncio Hub interno (quando aplicável)." }, { "name": "IDCompanyIntegration", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Integração específica da empresa a usar como credencial no canal." }, { "name": "CategoryId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador da categoria no canal — chave da lista para vários `ResourceType`." }, { "name": "CategoryName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome da categoria no canal." }, { "name": "CatalogDomain", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Domínio de catálogo (Mercado Livre)." }, { "name": "Brand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Marca." }, { "name": "Gender", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Gênero (vestuário)." }, { "name": "SizeChart", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador da grade de tamanho." }, { "name": "GenderId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador do gênero no canal." }, { "name": "GridExternalId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador externo da grade." }, { "name": "IDHubProductSizeChart", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Grade de tamanho do produto Hub." }, { "name": "ProfitMargin", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Margem de lucro (cálculos de preço sugerido)." }, { "name": "FixedProfit", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Lucro fixo (cálculos de preço sugerido)." }, { "name": "OtherExpenses", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Outras despesas (cálculos de preço sugerido)." }, { "name": "Cost", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Custo do produto (cálculos de preço sugerido)." }, { "name": "Name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome do produto/anúncio para sugestões." }, { "name": "Type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tipo (filtro genérico — depende do recurso)." }, { "name": "BrandId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador da marca no canal (autopeças)." }, { "name": "ModelId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador do modelo (autopeças)." }, { "name": "YearId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Ano (autopeças)." }, { "name": "Filter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtro textual (autopeças)." }, { "name": "PowerId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Potência (autopeças)." }, { "name": "ShortVersionId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Versão curta (autopeças)." }, { "name": "EngineId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Motor (autopeças)." }, { "name": "FuelId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Combustível (autopeças)." }, { "name": "BodyTypeId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Carroceria (autopeças)." }, { "name": "TransmissionId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Transmissão (autopeças)." }, { "name": "GearId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Câmbio (autopeças)." }, { "name": "DoorsId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Quantidade de portas (autopeças)." }, { "name": "SteeringId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Direção (autopeças)." }, { "name": "TractionId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Tração (autopeças)." }, { "name": "ValvesId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Quantidade de válvulas (autopeças)." }, { "name": "Version", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Versão (autopeças)." }, { "name": "Quantity", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Quantidade (recursos que dependem da quantidade — `ModeShipping`)." }, { "name": "State", "in": "query", "required": false, "schema": { "type": "string" }, "description": "UF (frete por região)." }, { "name": "BuyerId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comprador (lista de modos de envio personalizados por comprador)." }, { "name": "IDOrdersCarrierCollectionList", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Lista de romaneios de coleta (CSV de identificadores) repassada ao processo do canal — usada por recursos de etiqueta/coleta." }, { "name": "LabelFormat", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Formato da etiqueta solicitada ao canal (repassado como format ao processo) — aplicável a recursos de geração de etiqueta." }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Token de autorização repassado ao processo do canal. Normalmente vem do contexto autenticado; aceito também via query como fallback." } ], "responses": { "200": { "description": "Resposta opaca devolvida pelo processo do canal. Estrutura varia por `ResourceType`/canal — não há schema único.", "content": { "application/json": { "schema": { "type": "object", "description": "Payload opaco do processo — formato definido pelo canal." } } } }, "400": { "description": "Mensagens `[BadRequest]`:\n- `Integração não encontrada`\n- `Integracão não tem recurso`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorMessage" } } } }, "500": { "description": "Falha repassada pelo processo do canal. Corpo JSON traz `errorMessage` e `errorCode` originados do canal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errorMessage": { "type": "string" }, "errorCode": { "type": "string", "nullable": true }, "errorHelp": { "type": "string", "nullable": true } } } } } } } } }, "/hub/notification": { "get": { "operationId": "hubIntegrationNotificationList", "tags": [ "Hub — Notificações" ], "summary": "Lista notificações de integração", "description": "Retorna o feed de problemas de integração detectados (pedidos com falha de importação, SKUs com erro de sincronização, etc.), com paginação fixa de 5.000 registros por página. Só lista tipos com `Show=1` (problemas que devem aparecer para o operador). Ordem por `IDHubNotification` crescente.", "parameters": [ { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Página solicitada (0-indexada). Cada página tem 5.000 registros — o offset aplicado é `Page * 5000`." } ], "responses": { "200": { "description": "Array de notificações.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HubNotification" } } } } } } } }, "/hub/notification/{idhubnotification}": { "delete": { "operationId": "hubIntegrationNotificationDelete", "tags": [ "Hub — Notificações" ], "summary": "Marca notificação como resolvida (remove do feed)", "description": "Apaga a notificação do feed da empresa. O sistema valida que a notificação pertence à empresa autenticada via `AccountName`.", "parameters": [ { "name": "idhubnotification", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador da notificação." } ], "responses": { "200": { "description": "Texto literal `sucesso` quando a remoção é concluída (também devolvido quando o id não existe — o `DELETE` é idempotente).", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } } } } }, "/consumer/{idconsumer}/address": { "get": { "operationId": "consumerAddressList", "summary": "Lista os endereços do cliente", "description": "Retorna todos os endereços ativos (`StatusAddress=1`) cadastrados para o cliente.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." } ], "responses": { "200": { "description": "Lista de endereços ativos. Pode vir vazia.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerAddress" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "post": { "operationId": "consumerAddressPost", "summary": "Cadastra um endereço para o cliente", "description": "Cria um novo endereço. Para `IDCountry=1` (Brasil), o sistema consulta a base de CEP para resolver o código IBGE do município; sem retorno da consulta, o cadastro falha. Para `IDCountry` diferente de `1`, valida o país e força `ShippingState=EX` e `ShippingCity=EXTERIOR`. Inscrição estadual em Minas Gerais é normalizada com zeros à esquerda até 13 dígitos (exceto `ISENTO`). Atualiza `DateLastRecordModification` do cliente.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerAddressCreateBody" } } }, "description": "Endereço a cadastrar. Para Brasil (`IDCountry=1` ou omitido), `ShippingPostalCode`, `ShippingState`, `ShippingCity` e `ShippingStreet` são obrigatórios e o sistema resolve o código IBGE do município a partir do CEP. Para outros países, `ShippingState` e `ShippingCity` são forçados a `EX`/`EXTERIOR` e a consulta de CEP é pulada. Quando `ShippingState=MG` e `ConsumerStateInscription` não for `ISENTO`, o sistema preenche a inscrição estadual com zeros à esquerda até 13 dígitos." }, "responses": { "200": { "description": "Endereço criado. Retorna o detalhe completo do cliente (mesmo shape de `GET /consumer/{idconsumer}`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerDetail" } } } } }, "400": { "description": "Validações: `[BadRequest] - Consumidor não existe` (cliente não pertence à empresa autenticada); `[BadRequest] - IDCountry não existe` (país informado não está cadastrado em `TypeCountry`)." }, "500": { "description": "`erro consultar cep` quando a consulta de CEP não retorna resultado. Demais erros internos com prefixo `Error:`." } } } }, "/consumer/{idconsumer}/address/{idaddress}": { "get": { "operationId": "consumerAddressGet", "summary": "Detalha um endereço do cliente", "description": "Retorna os dados de um endereço específico. Só retorna endereços ativos (`StatusAddress=1`).", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." }, { "name": "idaddress", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do endereço." } ], "responses": { "200": { "description": "Endereço encontrado. Vem vazio quando não há endereço ativo com o id informado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerAddress" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "put": { "operationId": "consumerAddressPut", "summary": "Atualiza um endereço do cliente", "description": "Atualização parcial — apenas os campos enviados são gravados. Quando `IDCountry` muda para um valor diferente de `1`, o sistema valida o país e força `ShippingState=EX` e `ShippingCity=EXTERIOR`. Para `IDCountry=1` (default quando omitido), dispara consulta de CEP para recalcular o código IBGE. Inscrição estadual em Minas Gerais é normalizada com zeros à esquerda até 13 dígitos. Atualiza `DateLastRecordModification` do cliente.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." }, { "name": "idaddress", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do endereço." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerAddressUpdateBody" } } }, "description": "Atualização do endereço. Atualização parcial — só os campos enviados são alterados. Aceita também `ConsumerEmail` e `ConsumerTelephone` específicos do endereço. Mesmas regras de país, CEP e inscrição estadual do POST." }, "responses": { "200": { "description": "Endereço atualizado. Retorna o detalhe completo do cliente.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerDetail" } } } } }, "400": { "description": "Validações: `[BadRequest] - Endereço não existe` (endereço não pertence ao cliente ou à empresa autenticada); `[BadRequest] - País não existe`." }, "500": { "description": "Mensagem retornada pela consulta de CEP quando ela falha. Demais erros com prefixo `Error:`." } } }, "delete": { "operationId": "consumerAddressDelete", "summary": "Remove um endereço do cliente", "description": "Marca o endereço como inativo (`StatusAddress=0`). O registro fica preservado para histórico de pedidos antigos.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." }, { "name": "idaddress", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do endereço." } ], "responses": { "200": { "description": "Endereço removido. Retorna a lista atualizada de endereços ativos do cliente (mesmo shape de `GET /consumer/{idconsumer}/address`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerAddress" } } } } }, "400": { "description": "`[BadRequest] - Consumer Address não existe` quando o endereço não pertence ao cliente ou à empresa autenticada." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/consumer/{idconsumer}/contact": { "post": { "operationId": "consumerContactPost", "summary": "Cadastra um contato para o cliente", "description": "Cria um contato vinculado ao cliente. Aceita também a chave `ContactTelephon` (typo histórico) como fallback para `ContactTelephone`. Se `LegalRepresentative` não for enviado, é gravado como `0`.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerContactCreateBody" } } }, "description": "Contato a cadastrar. `ContactName` é obrigatório; demais campos (`ContactEmail`, `ContactTelephone`, `ContactResponsability`, `LegalRepresentative`) são opcionais. Por compatibilidade histórica, o campo `ContactTelephon` (sem o último `e`) também é aceito como fallback para `ContactTelephone`." }, "responses": { "200": { "description": "Contato criado. Retorna o detalhe completo do cliente.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerDetail" } } } } }, "400": { "description": "`[BadRequest] - Consumidor não existe` quando o cliente não pertence à empresa autenticada." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/consumer/{idconsumer}/contact/{idconsumercontact}": { "put": { "operationId": "consumerContactPut", "summary": "Atualiza um contato do cliente", "description": "Atualização parcial — apenas os campos enviados são gravados no banco.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." }, { "name": "idconsumercontact", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do contato." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerContactUpdateBody" } } }, "description": "Atualização do contato. Atualização parcial — só os campos enviados são alterados." }, "responses": { "200": { "description": "Contato atualizado. Retorna o detalhe completo do cliente.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerDetail" } } } } }, "400": { "description": "`[BadRequest] - Cliente não existe` quando o contato não pertence ao cliente ou à empresa autenticada." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "delete": { "operationId": "consumerContactDelete", "summary": "Remove um contato do cliente", "description": "Exclui fisicamente o contato.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." }, { "name": "idconsumercontact", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do contato." } ], "responses": { "200": { "description": "Contato removido. Retorna o detalhe completo do cliente.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerDetail" } } } } }, "400": { "description": "`[BadRequest] - Consumidor não existe` quando o cliente não pertence à empresa autenticada." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/consumer/{idconsumer}/credit": { "post": { "operationId": "consumerCreditPost", "summary": "Cadastra um limite de crédito para o cliente", "description": "Cria um limite de crédito vinculado a uma forma de pagamento. Cada cliente pode ter no máximo um crédito por forma de pagamento — tentar cadastrar uma segunda entrada na mesma forma é rejeitado. A operação é registrada no histórico de alterações do cliente (`ConsumerLog`).", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerCreditBody" } } }, "description": "Limite de crédito a cadastrar. `IDTypePayment` e `CreditValue` são obrigatórios. Um cliente não pode ter dois créditos para a mesma forma de pagamento — o sistema bloqueia a duplicidade." }, "responses": { "200": { "description": "Crédito cadastrado. Retorna o detalhe completo do cliente.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerDetail" } } } } }, "400": { "description": "Validações: `[BadRequest] - Cliente não encontrado`; `[BadRequest] - Tipo Pagamento não cadastrado` (forma de pagamento não existe ou não pertence à empresa); `[BadRequest] - Já existe essa forma de crédito cadastrada para o cliente`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/consumer/{idconsumer}/credit/{idconsumercredit}": { "put": { "operationId": "consumerCreditPut", "summary": "Atualiza um limite de crédito do cliente", "description": "Atualiza valor, forma de pagamento e condições comerciais do crédito. Não pode trocar `IDTypePayment` para uma forma já usada em outro crédito do mesmo cliente. A operação é registrada no histórico de alterações do cliente.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." }, { "name": "idconsumercredit", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do registro de crédito." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerCreditBody" } } }, "description": "Atualização do crédito. Mesma estrutura do POST. `IDTypePayment` e `CreditValue` continuam obrigatórios; `CommercialConditions` é opcional." }, "responses": { "200": { "description": "Crédito atualizado. Retorna o detalhe completo do cliente.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerDetail" } } } } }, "400": { "description": "Validações: `[BadRequest] - Cliente não encontrado` (crédito não pertence ao cliente ou à empresa); `[BadRequest] - Tipo Pagamento não cadastrado`; `[BadRequest] - Já existe essa forma de crédito cadastrada para o cliente`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "delete": { "operationId": "consumerCreditDelete", "summary": "Remove um limite de crédito do cliente", "description": "Exclui o registro de crédito. A exclusão é registrada no histórico de alterações do cliente com o valor e a forma de pagamento removidos.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." }, { "name": "idconsumercredit", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do registro de crédito." } ], "responses": { "200": { "description": "Crédito removido. Retorna o detalhe completo do cliente.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerDetail" } } } } }, "400": { "description": "`[BadRequest] - Crédito cliente não encontrado` quando o crédito não pertence ao cliente ou à empresa autenticada." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/consumer/{idconsumer}/voucher": { "get": { "operationId": "consumerVoucherGet", "summary": "Lista os movimentos de vale do cliente", "description": "Retorna todos os movimentos de vale (entradas e saídas) do cliente, ordenados por data de gravação decrescente. Inclui o saldo acumulado por cliente + faturador (`BalanceValue`) calculado em janela ordenada.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "description": "Filtra os movimentos pelo faturador (empresa que detém o saldo). Quando ausente, retorna movimentos de todos os faturadores do cliente." } ], "responses": { "200": { "description": "Lista de movimentos de vale.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerVoucher" } } } } }, "500": { "description": "Erro interno. Prefixo `Error:`." } } }, "post": { "operationId": "consumerVoucherPost", "summary": "Gera um vale para o cliente", "description": "Registra um movimento de entrada (`IDTypeAccount=0`) — credita um vale a favor do cliente. O valor precisa ser numérico e estritamente positivo. Quando `IDCompanyInvoice` é informado e difere da empresa do cliente, o faturador é validado como faturador filho (`CompanyMain`); ausente, o vale é vinculado à própria empresa do cliente. A operação é registrada no histórico de alterações do cliente (`ConsumerLog`).", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerVoucherCreateBody" } } }, "description": "Vale (movimento de entrada) a cadastrar. `Value` é obrigatório, numérico e estritamente positivo. `IDCompanyInvoice` é opcional — se omitido, o vale é creditado na empresa do cliente; se informado, precisa ser um faturador filho da empresa principal (`CompanyMain`). `Comments` é livre." }, "responses": { "200": { "description": "Vale criado. Retorna a lista atualizada de movimentos de vale do cliente (mesmo shape de `GET /consumer/{idconsumer}/voucher`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerVoucher" } } } } }, "400": { "description": "Validações: `[BadRequest] - precisa informar um valor válido para gerar vale` (valor não numérico); `[BadRequest] - precisa informar um valor positivo para gerar vale`; `[BadRequest] - Cliente não existe`; `[BadRequest] - Faturador não existe`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/consumer/{idconsumer}/voucher/{idconsumervoucher}": { "delete": { "operationId": "consumerVoucherDelete", "summary": "Remove um vale do cliente", "description": "Exclui um movimento de vale. **Não permite exclusão** quando o valor do vale já foi (parcial ou totalmente) utilizado — o saldo disponível do cliente precisa cobrir o valor a remover, considerando todos os movimentos (entradas menos saídas). A exclusão é registrada no histórico de alterações do cliente; o `Comments` enviado entra no log.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." }, { "name": "idconsumervoucher", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do movimento de vale." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerVoucherDeleteBody" } } }, "description": "Corpo opcional com `Comments` — texto livre registrado no log de exclusão do vale." }, "responses": { "200": { "description": "Vale removido. Retorna a lista atualizada de movimentos de vale do cliente.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerVoucher" } } } } }, "400": { "description": "Validações: `[BadRequest] - Vale cliente não existe`; `[BadRequest] - Vale não pode ser excluido pois já teve seu valor (parcial ou total) utilizado`." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/consumer/{idconsumer}/salesman": { "post": { "operationId": "consumerSalesmanPost", "summary": "Vincula um vendedor ao cliente", "description": "Associa um vendedor (`IDAcess` ativo da mesma empresa do cliente) ao cliente. A combinação cliente + vendedor é única; um vínculo já existente é atualizado em vez de duplicado (upsert). A operação é registrada no histórico de alterações do cliente.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSalesmanBody" } } }, "description": "Vínculo cliente–vendedor a cadastrar. `IDAcess` é obrigatório e identifica o vínculo usuário–empresa (`IDAcess`) do vendedor — precisa estar ativo e pertencer à mesma empresa do cliente. A combinação `IDConsumer + IDAcess` é única; um vínculo já existente é preservado/atualizado (upsert)." }, "responses": { "200": { "description": "Vínculo registrado. Retorna o detalhe completo do cliente.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerDetail" } } } } }, "400": { "description": "Validações: `[BadRequest] - Cliente não existe`; `[BadRequest] - Vendedor não existe` (`IDAcess` não pertence à empresa do cliente ou o vínculo `UserCompany` está inativo)." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/consumer/{idconsumer}/salesman/{idconsumersalesman}": { "delete": { "operationId": "consumerSalesmanDelete", "summary": "Remove o vínculo de vendedor do cliente", "description": "Exclui o vínculo cliente-vendedor. A operação é registrada no histórico de alterações do cliente, incluindo o login do vendedor removido.", "tags": [ "Cadastro de Clientes" ], "parameters": [ { "name": "idconsumer", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do cliente." }, { "name": "idconsumersalesman", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador do vínculo cliente-vendedor." } ], "responses": { "200": { "description": "Vínculo removido. Retorna o detalhe completo do cliente.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumerDetail" } } } } }, "400": { "description": "`[BadRequest] - Vendedor associado ao cliente não existe` quando o vínculo não pertence ao cliente ou à empresa autenticada." }, "500": { "description": "Erro interno. Prefixo `Error:`." } } } }, "/user/signin/local": { "post": { "operationId": "UserSigninLocal", "tags": [ "Autenticação" ], "summary": "Login por email/CPF/CNPJ e senha", "description": "Endpoint público. Autentica o usuário na conta identificada pelo subdomínio. Aceita login por email ou por CPF/CNPJ no mesmo campo `email`. Aplica regras de expiração de senha (parametrização `Validade da Senha (Dias)`), bloqueio temporário após 3 tentativas falhas (10 minutos) e MFA quando habilitado para o usuário (`MFAEnabled`). Em MFA `email`, dispara o envio de um código de 6 dígitos (válido por 5 minutos); em MFA `totp`, valida o código informado em `mfacode` ou retorna a URL de cadastro `OtpAuthUrl` quando o segredo ainda não foi gerado. Email com domínio `@idworks.com.br` tem acesso a todas as contas (exceto a conta `idw`).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSigninLocalBody" } } }, "description": "Endpoint público. `email` (aceita `Login` email ou CPF/CNPJ — o sistema detecta o formato) e `password` são obrigatórios. `mfacode` é obrigatório apenas quando o usuário tem MFA habilitado (6 dígitos por email ou código atual do Google Authenticator). `expireinhour` (ex.: `12h`, `7d`) define a expiração do JWT — default `14h`." }, "responses": { "200": { "description": "Login concluído ou desafio de MFA emitido. Conforme o estado, o corpo é um `UserSigninResponse` (sucesso, com `token` JWT) ou um `UserSigninMFAChallenge` (cadastro/desafio de MFA pendente).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UserSigninResponse" }, { "$ref": "#/components/schemas/UserSigninMFAChallenge" } ] } } } }, "400": { "description": "Requisição inválida. Mensagens conhecidas:\n- `[BadRequest] - Login informado não é um email válido nem documento`\n- `[BadRequest] - Erro ao enviar código por email`\n- `[BadRequest] - Erro ao validar expiração de senha`\n- `[BadRequest] - Retornar em instantes` (sistema temporariamente travado)." }, "404": { "description": "`[NotFound] Verificar usuário, senha e subdomíno (url)` — usuário sem senha cadastrada." } } } }, "/user/workingday/workscale": { "get": { "operationId": "userWorkScaleList", "tags": [ "Jornada de Trabalho" ], "summary": "Lista as escalas de trabalho da empresa", "description": "Retorna as escalas de trabalho cadastradas, cada uma com a lista de turnos (`WorkShift`) — dia da semana, horário de início e fim. Aceita filtro opcional por uma escala específica.", "parameters": [ { "name": "IDUserWorkScale", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da escala. Quando informado, restringe a resposta a essa escala." } ], "responses": { "200": { "description": "Lista de escalas. Retorna `[]` quando não houver registros.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserWorkScale" } } } } } } }, "post": { "operationId": "userWorkScalePost", "tags": [ "Jornada de Trabalho" ], "summary": "Cadastra uma nova escala de trabalho", "description": "Cria uma escala vinculada à empresa autenticada. O nome precisa ser único dentro da empresa. Após a criação, devolve a escala recém-cadastrada já enriquecida com a lista de turnos (vazia neste momento).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWorkScaleCreateBody" } } }, "description": "Escala a cadastrar. Apenas `UserWorkScaleName` é obrigatório — o nome precisa ser único dentro da empresa. A escala nasce sem turnos; use `POST /user/workingday/workscale/shift` para defini-los." }, "responses": { "200": { "description": "Escala cadastrada. Retorna a escala recém-criada conforme o formato de `GET /user/workingday/workscale`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserWorkScale" } } } } }, "400": { "description": "Mensagens conhecidas:\n- `[BadRequest] - Escala já existe`\n- `[BadRequest] - Erro ao adicionar escala`\n- `[BadRequest] - Empresa não existe`." } } } }, "/user/workingday/workscale/shift": { "post": { "operationId": "userWorkShiftPost", "tags": [ "Jornada de Trabalho" ], "summary": "Substitui os turnos de uma escala", "description": "Apaga todos os turnos atuais da escala informada e insere os turnos enviados em `shifts` no lugar — operação de substituição em bloco, não incremental. Cada turno define dia da semana `WeekDay` (0=domingo a 6=sábado), horário de início `StartTime` e horário de fim `FinishTime`. Após a gravação, devolve a escala atualizada com os novos turnos.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWorkShiftCreateBody" } } }, "description": "Substituição em bloco dos turnos da escala. `IDUserWorkScale` identifica a escala; `shifts` é a lista completa dos turnos novos — o sistema apaga os turnos atuais e insere estes no lugar. Cada turno informa `WeekDay` (0 domingo a 6 sábado), `StartTime` e `FinishTime` (`HH:mm:ss`)." }, "responses": { "200": { "description": "Turnos gravados. Retorna a escala atualizada conforme o formato de `GET /user/workingday/workscale`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserWorkScale" } } } } }, "400": { "description": "Mensagens conhecidas:\n- `[BadRequest] - Escala não existe`\n- `[BadRequest] - Preencha corretamente os campos Dia da semana, horário de início/fim e escala`\n- `[BadRequest] - Preencha corretamente o dia da semana`." } } } }, "/user/workingday/workscale/{iduserworkscale}": { "put": { "operationId": "userWorkScalePut", "tags": [ "Jornada de Trabalho" ], "summary": "Renomeia uma escala de trabalho", "description": "Altera o nome da escala. O novo nome precisa ser único na empresa.", "parameters": [ { "name": "iduserworkscale", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da escala a renomear." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWorkScaleUpdateBody" } } }, "description": "Renomeia a escala. `UserWorkScaleName` é obrigatório e precisa ser único dentro da empresa." }, "responses": { "200": { "description": "Escala atualizada. Retorna a escala conforme o formato de `GET /user/workingday/workscale`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserWorkScale" } } } } }, "400": { "description": "Mensagens conhecidas:\n- `[BadRequest] - Preencha corretamente o nome da escala`\n- `[BadRequest] - Escala já existente com esse nome`\n- `[BadRequest] - Escala não existe`\n- `[BadRequest] - Escala não atualizada`." } } }, "delete": { "operationId": "userWorkScaleDelete", "tags": [ "Jornada de Trabalho" ], "summary": "Exclui uma escala de trabalho", "description": "Remove a escala e seus turnos. Só é permitido excluir escalas que não estejam vinculadas a nenhum colaborador.", "parameters": [ { "name": "iduserworkscale", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da escala a excluir." } ], "responses": { "200": { "description": "Escala excluída.", "content": { "application/json": { "schema": { "type": "string", "example": "Escala excluída com sucesso" } } } }, "400": { "description": "Mensagens conhecidas:\n- `[BadRequest] - Informe corretamente a escala`\n- `[BadRequest] - Há colaboradores com essa escala, altere antes de excluir`\n- `[BadRequest] - Escala não existe`." } } } }, "/user/notification": { "get": { "operationId": "userNotificationGet", "tags": [ "Notificações de Versão" ], "summary": "Lista as novidades da versão atual do sistema", "description": "Retorna a versão `Current = 1` do sistema com as novidades publicadas (`Updates`). Cada item traz se já foi confirmado pelo usuário autenticado (campo `Confirm`).", "responses": { "200": { "description": "Versão atual e suas novidades. Retorna `[]` quando não houver versão marcada como atual.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserNotification" } } } } } } } }, "/user/notification/{idsystemversionupdate}": { "delete": { "operationId": "userNotificationDelete", "tags": [ "Notificações de Versão" ], "summary": "Marca uma novidade como vista pelo usuário", "description": "Registra a confirmação de leitura de uma novidade pelo usuário autenticado (não apaga a novidade em si). Em chamadas seguintes ao `GET /user/notification`, o item passa a vir com `Confirm = 1`.", "parameters": [ { "name": "idsystemversionupdate", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "Identificador da novidade a confirmar." } ], "responses": { "200": { "description": "Confirmação registrada.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } } } } }, "/user/company": { "get": { "operationId": "userCompanyGet", "tags": [ "Cadastro de Usuários" ], "summary": "Lista as empresas vinculadas ao usuário autenticado", "description": "Retorna as empresas (vínculo `UserCompany`) às quais o usuário autenticado tem acesso, ordenadas por `AccountName`.", "responses": { "200": { "description": "Lista de vínculos do usuário com empresas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserCompany" } } } } }, "400": { "description": "`[BadRequest] - não encontrado` — nenhum vínculo localizado." } } } }, "/user/company-invoice": { "get": { "operationId": "userCompanyInvoiceGet", "tags": [ "Cadastro de Usuários" ], "summary": "Lista as empresas faturadoras vinculadas ao usuário", "description": "Retorna as empresas faturadoras (`UserCompanyInvoice`) às quais o usuário autenticado tem acesso, dentro do grupo da empresa identificada pelo subdomínio.", "responses": { "200": { "description": "Lista de empresas faturadoras. Retorna `[]` quando não houver vínculos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserCompanyInvoice" } } } } } } } }, "/user/menu": { "get": { "operationId": "userMenuGet", "tags": [ "Cadastro de Usuários" ], "summary": "Monta o menu lateral do usuário", "description": "Retorna os grupos de módulos visíveis ao usuário autenticado, considerando os privilégios do perfil de acesso atribuído. Cada grupo traz seus módulos e, em `Version = 2`, também submódulos aninhados (estrutura hierárquica `Module` dentro de `Module`). Quando `Version` é diferente de `2`, devolve apenas o primeiro nível.", "parameters": [ { "name": "Version", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2 ] }, "description": "Versão do formato. `2` inclui submódulos aninhados em cada item; qualquer outro valor retorna apenas o primeiro nível." } ], "responses": { "200": { "description": "Lista de grupos de módulos com seus módulos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserMenuGroup" } } } } }, "400": { "description": "`[BadRequest] - Usuário não encontrado`." } } } }, "/user/privilege": { "get": { "operationId": "userPrivilegeGet", "tags": [ "Cadastro de Usuários" ], "summary": "Retorna os privilégios do usuário ou recria os dados de login", "description": "Por padrão (`LoginData` ausente ou diferente de `1`), devolve a lista de perfis de acesso (`UserPrivilegeGroup`) da empresa com os módulos e privilégios de cada um, restritos ao que o usuário enxerga. Quando `LoginData=1`, recria o corpo de login do usuário autenticado — útil para o frontend reidratar a sessão com dados frescos (informações da empresa, tokens de helpdesk, parâmetros da integração de notificações).", "parameters": [ { "name": "LoginData", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, retorna o corpo de login (`UserLoginPayload`) em vez da lista de perfis. Default `0`." } ], "responses": { "200": { "description": "Conforme `LoginData`: lista de perfis (`UserPrivilegeGroup[]`) ou objeto `UserLoginPayload`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/UserPrivilegeGroup" } }, { "$ref": "#/components/schemas/UserLoginPayload" } ] } } } }, "400": { "description": "Mensagens conhecidas:\n- `[BadRequest] - Usuário precisa estar logado`\n- `[BadRequest] - Usuário não encontrado`." } } } }, "/tax": { "get": { "operationId": "taxList", "summary": "Lista os departamentos fiscais ativos", "description": "Retorna os departamentos fiscais (cadastro hierárquico que agrupa as regras tributárias dos SKUs) com filtros opcionais por identificador, nome e empresa. Limite máximo de 2000 registros por chamada.\n\nQuando o contexto autenticado indica `accountname=all`, a lista cobre todas as empresas relacionadas; caso contrário, restringe à empresa do subdomínio.", "tags": [ "Departamentos Tributários" ], "parameters": [ { "name": "IDTaxDepartment", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por identificador do departamento fiscal." }, { "name": "TaxDepartmentDescription", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por nome exato do departamento fiscal." }, { "name": "Status", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 1 }, "description": "Filtra por situação. `1` (default) retorna apenas departamentos ativos." } ], "responses": { "200": { "description": "Lista de departamentos fiscais.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxDepartmentSummary" } } } } } } }, "post": { "operationId": "taxPost", "summary": "Cria um departamento fiscal", "description": "Cria um novo departamento fiscal associado à empresa autenticada e retorna o registro completo já com o array de regras `Cfop` (vazio neste momento), usando a mesma estrutura do detalhe.\n\nO nome `TaxDepartmentDescription` deve ser único entre os departamentos ativos da empresa.", "tags": [ "Departamentos Tributários" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxDepartmentCreateBody" } } }, "description": "Dados do departamento fiscal a cadastrar. Apenas `TaxDepartmentDescription` (máx. 100) — o nome precisa ser único entre os departamentos ativos da empresa." }, "responses": { "200": { "description": "Departamento fiscal criado. Retorna o detalhe completo, no mesmo shape de `GET /tax/{idtaxdepartment}`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxDepartmentDetail" } } } } }, "400": { "description": "Validação ou conflito. Mensagens (prefixo `[BadRequest]`): `Empresa não existe`; `Já existe um departamento fiscal com este nome`." } } } }, "/tax/{idtaxdepartment}": { "parameters": [ { "name": "idtaxdepartment", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do departamento fiscal." } ], "get": { "operationId": "taxGet", "summary": "Retorna o detalhe de um departamento fiscal", "description": "Retorna o departamento fiscal junto do array `Cfop[]` com todas as regras fiscais federais já configuradas (PIS/COFINS, IPI saída e entrada, IBS/CBS, CFOPs por direção e estado, switches da regra). As regras ICMS por estado de cada CFOP devem ser obtidas via `GET /tax/{idtaxdepartment}/cfop/{idtax}`.\n\nFiltro opcional `IDCompany` restringe os CFOPs aos da filial informada (cenário multi-CNPJ).", "tags": [ "Departamentos Tributários" ], "parameters": [ { "name": "IDCompany", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Restringe os CFOPs retornados aos cadastrados na filial informada." } ], "responses": { "200": { "description": "Detalhe do departamento fiscal.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxDepartmentDetail" } } } } } } }, "put": { "operationId": "taxPut", "summary": "Atualiza o nome de um departamento fiscal", "description": "Altera o nome do departamento fiscal. Mantém a unicidade do nome entre os departamentos ativos da empresa. Após a atualização, retorna a lista completa de departamentos ativos (mesmo shape de `GET /tax`).", "tags": [ "Departamentos Tributários" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxDepartmentUpdateBody" } } }, "description": "Novo nome do departamento. Mesma regra de unicidade do POST: `TaxDepartmentDescription` único entre os departamentos ativos da empresa autenticada." }, "responses": { "200": { "description": "Departamento atualizado. Retorna a lista de departamentos da empresa.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxDepartmentSummary" } } } } }, "400": { "description": "Validação ou conflito. Mensagens (prefixo `[BadRequest]`): `Departamento fiscal não existe`; `Já existe um departamento fiscal com este nome`." } } }, "delete": { "operationId": "taxDelete", "summary": "Inativa um departamento fiscal", "description": "Inativa o departamento fiscal (soft delete via `Status=0`). A exclusão é bloqueada quando o departamento está em uso: vinculado a algum SKU ou referenciado pela regra fiscal de um Tipo de Pedido.\n\nRetorna a lista atualizada de departamentos ativos da empresa.", "tags": [ "Departamentos Tributários" ], "responses": { "200": { "description": "Departamento inativado. Retorna a lista de departamentos ativos.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxDepartmentSummary" } } } } }, "400": { "description": "Bloqueado por uso ou departamento inexistente. Mensagens (prefixo `[BadRequest]`): `Departamento fiscal não existe`; `Departamento fiscal esta em alguns SKUs, remover o departamento do SKU antes de deletar`; `Depatarmento fiscal esta na regra fiscal do tipo de pedido: \"\" ()`." } } } }, "/tax/{idtaxdepartment}/cfop": { "parameters": [ { "name": "idtaxdepartment", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do departamento fiscal." } ], "post": { "operationId": "taxCfopPost", "summary": "Cria uma regra fiscal (CFOP) dentro de um departamento", "description": "Cria uma regra fiscal federal dentro do departamento. A regra agrupa PIS/COFINS de saída e entrada, IPI (saída/entrada), IBS/CBS, os quatro CFOPs por direção e estado (dentro/fora do estado) e diversos switches que reconfiguram o cálculo (consumidor final `NfeindFinal`, contribuinte `NfeTaxPayer`, bonificação `Gratification`, cálculo reverso `ReverseTaxCalculation`, exportação `NfeExport`, emissão de NFCe `IssueNFCe`).\n\nValidações principais: alíquotas de PIS e COFINS limitadas a 50%; os CSTs de PIS e COFINS são obrigatórios; cada CFOP é validado contra o cadastro `NfCfop` e quanto ao primeiro dígito (saída no estado começa com 5 ou 7; saída fora do estado com 6; entrada no estado com 1 ou 3; entrada fora do estado com 2); enquadramento de IPI `IpiCEnq` é exigido em faixas específicas para CSTs `02/52` (300–399), `04/54` (0–99) e `05/55` (100–199); quando `IDNfCstIbsCbs` é informado, a classificação IBS/CBS precisa existir.\n\nRetorna o detalhe da regra recém-criada (mesmo shape de `GET /tax/{idtaxdepartment}/cfop/{idtax}`), com o array `Icms[]` ainda vazio.", "tags": [ "Departamentos Tributários" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxCfopCreateBody" } } }, "description": "Regra fiscal (CFOP) federal a cadastrar no departamento. `PisCst`, `CofinsCst` e `IDCompanyBranch` (filial emissora) são obrigatórios; alíquotas de PIS/COFINS são limitadas a 50%. Os 4 CFOPs (saída no estado/fora do estado, entrada no estado/fora do estado) são opcionais; quando informados, o primeiro dígito tem que casar com a direção (saída no estado: `5`/`7`, saída fora: `6`, entrada no estado: `1`/`3`, entrada fora: `2`) e o CFOP precisa existir em `NfCfop`. `IpiCst` exige enquadramento `IpiCEnq` coerente com o CST (`02`/`52` entre 300–399, `04`/`54` entre 0–99, `05`/`55` entre 100–199); sem `IpiCst`, `IpiAliquot` e `IpiCEnq` ficam nulos. `IDNfCstIbsCbs` quando informado é validado contra `NfCstIbsCbs`." }, "responses": { "200": { "description": "Regra fiscal criada. Retorna o detalhe completo.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxCfopDetail" } } } } }, "400": { "description": "Validação ou conflito. Mensagens (prefixo `[BadRequest]`): `Alíquota de PIS não pode ser maior que 50%`; `Alíquota de COFINS não pode ser maior que 50%`; `Precisa informa o CST PIS`; `Precisa informa o CST COFINS`; `CFOP de saída dentro do estado não incia com 5`; `CFOP de saída fora do estado não incia com 6`; `CFOP de entrada dentro do estado não incia com 1`; `CFOP de entrada fora do estado não incia com 2`; `CFOP de não existe`; `IPI CST 02 e 52 deve ter o enquadramento entre 300 e 399`; `IPI CST 04 e 54 deve ter o enquadramento entre 0 e 99`; `IPI CST 05 e 55 deve ter o enquadramento entre 100 e 199`; `Classificação IBS/CBS não encontrada`; `Departamento fiscal não existe`." } } } }, "/tax/{idtaxdepartment}/cfop/{idtax}": { "parameters": [ { "name": "idtaxdepartment", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do departamento fiscal." }, { "name": "idtax", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da regra fiscal (CFOP) dentro do departamento." } ], "get": { "operationId": "taxCfopGet", "summary": "Retorna o detalhe de uma regra fiscal (CFOP) com suas regras ICMS por estado", "description": "Retorna a regra fiscal completa: campos federais (PIS/COFINS saída e entrada, IPI saída e entrada, IBS/CBS), os quatro CFOPs por direção/estado com descrição resolvida e o array `Icms[]` com todas as regras ICMS por estado destino já configuradas para essa regra (cada item traz CST ICMS, alíquota, base de cálculo, ICMS ST, FCP, DIFAL e os campos de override por estado).", "tags": [ "Departamentos Tributários" ], "responses": { "200": { "description": "Detalhe da regra fiscal.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxCfopDetail" } } } } } } }, "put": { "operationId": "taxCfopPut", "summary": "Atualiza uma regra fiscal (CFOP)", "description": "Atualiza os campos federais da regra fiscal. Aceita atualização parcial — campos não enviados ficam inalterados, e strings vazias em `PisCstInbound` / `CofinsCstInbound` são interpretadas como remoção do CST de entrada.\n\nAplica as mesmas validações do `POST` (limite de 50% em PIS/COFINS, validade do CFOP por dígito inicial e cadastro, faixas do enquadramento IPI, classificação IBS/CBS existente).\n\nQuando a regra é marcada como `Standard=1` em conjunto com `NfeindFinal`, `NfeTaxPayer`, `IssueNFCe` e `Gratification`, o sistema bloqueia a alteração se já houver outra regra padrão no mesmo departamento cobrindo estado destino igual a uma das regras ICMS deste CFOP (impede duplicidade de regra principal por estado).\n\nRetorna o detalhe atualizado (mesmo shape do `GET`).", "tags": [ "Departamentos Tributários" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxCfopUpdateBody" } } }, "description": "Atualização parcial da regra fiscal — mesmos campos do POST, todos opcionais; os ausentes mantêm o valor atual. Mantém as mesmas validações de PIS/COFINS (≤ 50%), de coerência IPI CST/Enq, dígito inicial dos CFOPs por direção e existência do CFOP em `NfCfop`. `IDNfCstIbsCbs` segue validado contra `NfCstIbsCbs`." }, "responses": { "200": { "description": "Regra fiscal atualizada. Retorna o detalhe completo.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxCfopDetail" } } } } }, "400": { "description": "Validação ou conflito. Mensagens (prefixo `[BadRequest]`): mesmas do `POST`, mais `Departamento fiscal não existe`; `O estado já tem regra configurada em outro departamento PRINCIPAL: e não pode duplicar.`." } } }, "delete": { "operationId": "taxCfopDelete", "summary": "Remove uma regra fiscal (CFOP)", "description": "Remove a regra fiscal do departamento. A exclusão é bloqueada quando a regra está atrelada à regra fiscal de algum Tipo de Pedido.\n\nRetorna o detalhe do departamento pai após a exclusão (mesmo shape de `GET /tax/{idtaxdepartment}`).", "tags": [ "Departamentos Tributários" ], "responses": { "200": { "description": "Regra fiscal removida. Retorna o detalhe atualizado do departamento.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxDepartmentDetail" } } } } }, "400": { "description": "Bloqueado por uso ou registro inexistente. Mensagens (prefixo `[BadRequest]`): `Tipo imposto não existe`; `Regra fiscal esta atrelada ao tipo de pedido e não pode ser excluida`." } } } }, "/tax/{idtaxdepartment}/cfop/{idtax}/interstate": { "parameters": [ { "name": "idtaxdepartment", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do departamento fiscal." }, { "name": "idtax", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da regra fiscal (CFOP)." } ], "post": { "operationId": "taxInterstatePost", "summary": "Cria uma regra ICMS por estado destino", "description": "Cria uma regra ICMS para um estado destino dentro de uma regra fiscal (CFOP). A regra define ICMS próprio, ICMS ST, FCP (Fundo de Combate à Pobreza), DIFAL e overrides de CFOP/comentários para o estado em questão.\n\nO CST ICMS controla quais campos são obrigatórios; o sistema aplica regras específicas por CST:\n- `00` (Tributada integralmente): exige `IcmsModBC`, `IcmsAliquot`, `FecpAliquot`; limpa campos de ST e diferimento.\n- `10` (Tributada com ST): exige também `IcmsModBCST`; se `IcmsSTAliquot` não vier, copia `IcmsAliquot`.\n- `20` (Redução de base): exige `IcmsPRedBC` maior que zero; limpa ST e diferimento.\n- `30` (Isenta com ST): exige `IcmsModBCST` e `FecpAliquot`; limpa redução e modalidade BC.\n- `40`, `41`, `50`, `60` (isenções e ICMS recolhido por ST): zera os demais campos de ICMS, redução, ST e DIFAL.\n- `51` (Diferimento): exige `IcmsModBC`, `IcmsAliquot` e `FecpAliquot`; limpa campos de ST.\n- `70` (Redução com ST): exige `IcmsPRedBC` maior que zero, `IcmsModBC` e `IcmsModBCST` válidos.\n\nValidações comuns: alíquotas (`IcmsAliquot`, `FecpAliquot`, `IcmsDifalPRedBC`) devem ficar entre 0 e 100% (`0`–`1` em decimal). O CST informado precisa existir em `NfCstIcms` para o regime tributário da empresa. Não pode haver outra regra para o mesmo `StateTo` dentro da mesma regra fiscal. Quando o CFOP é `Standard=1`, o estado destino não pode coincidir com um estado já configurado em outro CFOP padrão do mesmo departamento (impede duplicidade da regra principal por estado).\n\nRetorna o registro criado já com descrições resolvidas (modalidades de BC, CST, UF).", "tags": [ "Departamentos Tributários" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxInterstateCreateBody" } } }, "description": "Regra de ICMS por estado destino vinculada a uma regra fiscal (CFOP). `StateTo` obrigatório e único por regra (não é permitido duplicar a UF). O conjunto de campos exigidos depende do `IcmsCst`: `00`/`10`/`20`/`51`/`70` exigem `IcmsModBC` (0–3) e `IcmsAliquot` (0–100%); `10`/`30`/`70` exigem ainda `IcmsModBCST` (0–6); `20`/`70` exigem `IcmsPRedBC`. CSTs `40`/`41`/`50`/`60` zeram automaticamente os campos de cálculo. `FecpAliquot` (≤ 100%) é obrigatória sempre que houver tributação. `IcmsDifalPRedBC` ≤ 100%. `IcmsSTAliquot` herda de `IcmsAliquot` quando não informado." }, "responses": { "200": { "description": "Regra ICMS criada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxInterstate" } } } } }, "400": { "description": "Validação. Mensagens (prefixo `[BadRequest]`): `Precisa selecionar o Mod Base Cal ICMS válido`; `Precisa informar alíquota ICMS`; `Alíquota ICMS precisa ser entre 0 e 100%`; `Precisa informar alíquota ICMS Fundo Pobreza`; `Alíquota ICMS Fundo Pobreza precisa ser entre 0 e 100%`; `Redução BC ICMS DIFAL precisa ser entre 0 e 100%`; `Redução BC ICMS precisa ser entre 0 e 100%`; `Precisa selecionar o Mod Base Cal ICMS ST válido (0,1,2,3,4,5,6)`; `Precisa selecionar o Mod Base Cal ICMS ST válido`; `ICMS CST é inválido. Verificar regime tributário da empresa`; `Configuração ja preenchida para estado: `; `Departamento fiscal não existe`; `O estado já tem regra configurada em outro departamento PRINCIPAL: e não pode duplicar.`." } } } }, "/tax/{idtaxdepartment}/cfop/{idtax}/interstate/{idtaxinterstate}": { "parameters": [ { "name": "idtaxdepartment", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do departamento fiscal." }, { "name": "idtax", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da regra fiscal (CFOP)." }, { "name": "idtaxinterstate", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da regra ICMS por estado." } ], "put": { "operationId": "taxInterstatePut", "summary": "Atualiza uma regra ICMS por estado destino", "description": "Atualiza a regra ICMS por estado destino. Mesmas validações por CST, alíquotas e limites do `POST`. Ao trocar o `StateTo`, o sistema verifica novamente se não há duplicidade contra outras regras (do mesmo CFOP e, quando o CFOP é `Standard=1`, contra outros CFOPs padrão do departamento).\n\nCampos textuais como `ItemCommentsInvoice` e `IcmsPMVAST*` mantêm o valor anterior quando omitidos no body.\n\nRetorna o registro atualizado com descrições resolvidas (modalidades de BC, CST, UF).", "tags": [ "Departamentos Tributários" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxInterstateUpdateBody" } } }, "description": "Atualização parcial da regra de ICMS por estado — mesmos campos do POST, todos opcionais. Mantém as mesmas validações por `IcmsCst` (campos obrigatórios variam com o CST informado) e os mesmos limites de 0–100% para alíquotas e reduções de base de cálculo." }, "responses": { "200": { "description": "Regra ICMS atualizada.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxInterstate" } } } } }, "400": { "description": "Validação. Mesmas mensagens do `POST` (prefixo `[BadRequest]`)." } } }, "delete": { "operationId": "taxInterstateDelete", "summary": "Remove uma regra ICMS por estado destino", "description": "Remove a regra ICMS de um estado destino dentro de uma regra fiscal (CFOP). Retorna o detalhe do departamento pai (mesmo shape de `GET /tax/{idtaxdepartment}`).", "tags": [ "Departamentos Tributários" ], "responses": { "200": { "description": "Regra ICMS removida. Retorna o detalhe atualizado do departamento.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxDepartmentDetail" } } } } }, "400": { "description": "Registro não localizado. Mensagem (prefixo `[BadRequest]`): `IDTaxDepartment não existe`." } } } }, "/invoice/danfe": { "get": { "operationId": "orderInvoiceGet", "summary": "Gera o DANFE (PDF) ou retorna o XML de uma nota fiscal", "description": "Gera dinamicamente o documento auxiliar da nota fiscal (DANFE em PDF) a partir do XML da nota, ou devolve o próprio XML quando `Type=XML`. O endpoint cobre vários cenários — NF-e modelo 55, NFCe modelo 65, CFe-SAT modelo 59, e eventos de NF-e (carta de correção, inutilização e cancelamento), escolhendo o renderizador adequado conforme o modelo fiscal do documento e o tipo do arquivo.\n\nA origem do XML é controlada por `Folder`: `Invoice` (notas emitidas pela empresa, localizadas por `File` = `IDFile` ou por `IDOrder`), `Inbound` com `Origin=Purchase` (XML recebido em pedido de compra) ou `Inbound` com `Origin=Feed` (XML capturado pelo monitor de notas). O PDF inclui o logotipo da empresa quando configurado.\n\nA resposta é binária (`application/pdf` ou `application/xml`), não JSON.", "tags": [ "NF-e / NFC-e" ], "parameters": [ { "name": "Folder", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "Invoice", "Inbound" ] }, "description": "Origem do XML. `Invoice` para notas emitidas pela empresa; `Inbound` para XMLs recebidos (combinar com `Origin`)." }, { "name": "File", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Quando `Folder=Invoice`, identifica o arquivo pelo `IDFile`. Quando `Folder=Inbound`, identifica pela chave de acesso da NF-e. Pelo menos um entre `File` e `IDOrder` é obrigatório." }, { "name": "IDOrder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Identificador do pedido cuja nota fiscal será impressa (alternativa a `File`)." }, { "name": "Origin", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Purchase", "Feed" ] }, "description": "Quando `Folder=Inbound`, define a origem do XML: `Purchase` (recebido em pedido de compra) ou `Feed` (monitor de notas)." }, { "name": "Type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "XML" ] }, "description": "Quando `XML`, devolve o arquivo XML cru em vez do PDF do DANFE." } ], "responses": { "200": { "description": "PDF do DANFE (Content-Type `application/pdf`) ou arquivo XML (Content-Type herdado, `Content-Disposition: attachment`).", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/xml": { "schema": { "type": "string" } } } }, "400": { "description": "Validação ou arquivo não localizado. Mensagens: `Precisa enviar o querystring Folder`; `Precisa enviar o querystring File ou IDOrder`; `Arquivo não encontrado`; `Arquivo não encontrado S3`; `Pedido não localizado` (no fluxo público de tracking)." } } }, "post": { "operationId": "orderInvoiceDanfeBulkPost", "summary": "Gera DANFEs em lote", "description": "Recebe uma lista de pedidos/notas e dispara a geração em lote dos DANFEs, gerando um único PDF com todas as notas. Útil para imprimir várias notas de uma vez a partir da listagem de pedidos.\n\nA empresa autenticada (resolvida pelo subdomínio) é expandida para todas as filiais relacionadas — o lote pode percorrer notas de qualquer empresa do grupo.\n\nO corpo é um array de `IDOrder`. A resposta é binária — um único `application/pdf` com as DANFEs das notas principais (`Main=1`) dos pedidos, concatenadas.", "tags": [ "NF-e / NFC-e" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "Lista de pedidos/notas a imprimir. Shape interno não confirmado (depende de `ServiceInvoice::DanfeBulk`).", "items": { "type": "object", "description": "Item da lista de impressão. Campos não confirmados no sistema — costumam carregar identificador do pedido e/ou da nota." } } } }, "description": "Lista dos `IDOrder` a imprimir em lote. O sistema busca a NF principal de cada pedido entre as filiais relacionadas à empresa autenticada e gera um único PDF com todas as DANFEs." }, "responses": { "200": { "description": "Lote processado. Conteúdo retornado depende do processo `ServiceInvoice::DanfeBulk` (contrato não confirmado)." }, "400": { "description": "Validação. Mensagens: `Precisa enviar os pedidos no corpo`; `Empresa não localizada`." } } } }, "/invoice/danfe65": { "get": { "operationId": "orderInvoice65Get", "summary": "Gera o DANFE NFCe (modelo 65), recibo não fiscal ou via TEF", "description": "Gera o documento auxiliar do consumidor (DANFE NFCe modelo 65) para um pedido. O comportamento muda conforme os parâmetros:\n- Sem `OnlyTEFReceipt` e com `InvoiceType=1` (default): emite o cupom fiscal NFCe.\n- Com `InvoiceType=2`: emite um recibo não fiscal correspondente ao pedido.\n- Com `InvoiceType=3`: emite o cupom de troca/devolução (não fiscal) do pedido.\n- Com `OnlyTEFReceipt=1`: concatena os recibos de TEF (loja e/ou comprador) registrados na intenção de venda informada — útil para reimprimir comprovantes de cartão.\n\nA resposta é binária (PDF do cupom/recibo) ou texto bruto (recibos TEF).", "tags": [ "NF-e / NFC-e" ], "parameters": [ { "name": "IDOrder", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Identificador do pedido a imprimir." }, { "name": "InvoiceType", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3 ], "default": 1 }, "description": "`1` (default) imprime o cupom fiscal NFCe; `2` imprime o recibo não fiscal; `3` imprime o cupom de troca/devolução (não fiscal)." }, { "name": "OrderGift", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, gera o cupom em modo presente (sem valores)." }, { "name": "IDOrderIntention", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador da intenção de venda (PDV). Usado para localizar pagamentos TEF e para vincular o cupom à intenção." }, { "name": "OnlyTEFReceipt", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, devolve apenas os recibos TEF da intenção informada — não emite cupom fiscal." }, { "name": "TEFReceiptStore", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `OnlyTEFReceipt=1`, inclui o recibo do estabelecimento (via loja)." }, { "name": "TEFReceiptBuyer", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `OnlyTEFReceipt=1`, inclui o recibo do comprador (via cliente)." } ], "responses": { "200": { "description": "Cupom fiscal NFCe (PDF), recibo/cupom não fiscal, ou texto concatenado dos recibos TEF, dependendo dos parâmetros.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Validação ou pedido não localizado. Mensagens: `necessário selecionar um pedido`; `Pedido não encontrado`." } } } }, "/invoice-service/{idserviceorder}/invoice/invoice-xml": { "get": { "operationId": "invoiceServiceXmlGet", "summary": "Baixa XML ou DANFSE em PDF da NFS-e", "description": "Devolve o arquivo da NFS-e emitida — XML (`Type=XML`) ou DANFSE em PDF (`Type=PDF`). O parâmetro `File` traz o nome base do arquivo (geralmente o `IDServiceOrder` da NFS-e).", "tags": [ "NFS-e" ], "parameters": [ { "name": "idserviceorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da NFS-e." }, { "name": "Type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "XML", "PDF" ] }, "description": "Formato do arquivo: `XML` baixa o XML; `PDF` gera e baixa a DANFSE." }, { "name": "File", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Nome base do arquivo a baixar. Aceita apenas dígitos; demais caracteres são removidos." }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Token de autenticação repassado na URL (usada como link direto)." } ], "responses": { "200": { "description": "Arquivo entregue como download (`Content-Disposition: attachment`).", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Arquivo não encontrado em S3 ou na NFS-e: `Arquivo não encontrado (2)`." } } } }, "/invoice-service/{idserviceorder}/payment": { "post": { "operationId": "invoiceServicePaymentPost", "summary": "Lança um pagamento da NFS-e", "description": "Cria uma ou mais contas a receber vinculadas à NFS-e. Quando `SplitInstallment=1`, gera uma conta por parcela (cada uma com `Value`); quando `0`, gera uma única conta consolidando o valor. Valida tipo de pagamento, tipo de documento, plano de contas, banco de recebimento, integração e empresa faturadora. Calcula a data de vencimento a partir do `DaysDue` do tipo de pagamento quando não enviada.", "tags": [ "NFS-e" ], "parameters": [ { "name": "idserviceorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da NFS-e." }, { "name": "SplitInstallment", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 1 }, "description": "Quando `1`, cada parcela vira uma conta a receber separada; quando `0`, uma única conta consolida o valor." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceServicePaymentCreateBody" } } }, "description": "Pagamento(s) a baixar contra a NFS-e. O sistema valida que a NFS-e pertence à empresa autenticada e aplica as regras do fluxo de pagamento (parcelamento via querystring `SplitInstallment`, atualização de status). Resposta devolve o detalhe da NFS-e atualizado (mesmo schema do `GET /invoice-service/{idserviceorder}`)." }, "responses": { "200": { "description": "Pagamento lançado. Retorna o detalhe atualizado da NFS-e." }, "400": { "description": "Validação falhou. Mensagens reais: `Tipo pagamento padrão não cadastrado para a empresa`, `Tipo pagamento não cadastrado`, `Tipo documento padrão não cadastrado para a empresa`, `Tipo registro padrão não cadastrado para a empresa`, `Banco de recebimento não cadastrado`, `Integração não cadastrada`, `Empresa faturadora não encontrada`." }, "404": { "description": "NFS-e não encontrada: `[NotFound] - Pedido não encontrado`." } } } }, "/invoice-service/{idserviceorder}/payment/{idaccountpayablereceivable}": { "put": { "operationId": "invoiceServicePaymentPut", "summary": "Atualiza um pagamento da NFS-e", "description": "Atualiza uma conta a receber lançada para a NFS-e. Valida tipo de pagamento, tipo de documento, plano de contas, banco e integração quando enviados, e recalcula `DaysDue` quando `DateDue` muda. Registra o que foi alterado no histórico da conta e no histórico da NFS-e.", "tags": [ "NFS-e" ], "parameters": [ { "name": "idserviceorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da NFS-e." }, { "name": "idaccountpayablereceivable", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da conta a receber a ser atualizada." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceServicePaymentUpdateBody" } } }, "description": "Atualização do título de pagamento vinculado à NFS-e — reutiliza o sistema de **conta a receber** (`accountsReceivablePut`). O corpo aceita os campos do título (valor, vencimento, plano de contas, observações etc.); apenas os enviados são alterados." }, "responses": { "200": { "description": "Pagamento atualizado. Retorna o detalhe atualizado da conta a receber." }, "400": { "description": "Validação falhou. Mensagens reais: `[BadRequest] - Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)`, `[BadRequest] - Conta a receber não existe`, `[BadRequest] - Fornecedor não existe`, `[BadRequest] - Cliente não existe`, `[BadRequest] - Faturador não existe`, `[BadRequest] - Pagamento não existe`, `[BadRequest] - Banco não existe`, `[BadRequest] - Integração não existe`, `[BadRequest] - Plano de contas não existe`, `[BadRequest] - Tipo documento não existe`, `[BadRequest] - Boleto / link pagamento já esta pago e não pode ser alterado`." } } }, "delete": { "operationId": "invoiceServicePaymentDelete", "summary": "Remove um pagamento da NFS-e", "description": "Exclui uma conta a receber lançada para a NFS-e. Bloqueada quando a conta já tem pagamento conciliado ou está agendada (`Scheduled=1`). Quando a conta tem origem em recebimento, a exclusão respeita a parametrização **Bloquear exclusão de contas vinculadas a recebimento**.", "tags": [ "NFS-e" ], "parameters": [ { "name": "idserviceorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da NFS-e." }, { "name": "idaccountpayablereceivable", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da conta a receber a remover." } ], "responses": { "200": { "description": "Pagamento removido. Retorna o detalhe atualizado da NFS-e." }, "400": { "description": "Validação falhou. Mensagens reais: `[BadRequest] - Pagamento não existe`, `[BadRequest] - Título esta agendado e não pode ser excluído`, `[BadRequest] - Contas a pagar já tem pagamento`, `[BadRequest] - Não é possível excluir um contas a pagar atrelado a um recebimento`." } } } }, "/purchase/buy-order/{idbuyorder}/log": { "get": { "operationId": "buyOrderLogGet", "summary": "Histórico do pedido de compra", "description": "Retorna o histórico de eventos do pedido de compra (inclusões/remoções de itens, alterações de status, lançamentos de pagamento, mesclagem com outro pedido). Cada linha traz o autor (`Login`) e a descrição da ação.", "tags": [ "Pedido de Compra" ], "parameters": [ { "name": "idbuyorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido de compra." } ], "responses": { "200": { "description": "Histórico do pedido de compra (ordem decrescente).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BuyOrderLog" } } } } } } } }, "/purchase/buy-order/{idbuyorder}/merge": { "post": { "operationId": "buyOrderMergePost", "summary": "Mescla dois pedidos de compra", "description": "Move todos os itens do pedido de compra da URL para o pedido informado no body (`IDBuyOrder`). O pedido de origem passa a status `7 Mesclado` e fica vazio. Ambos os pedidos precisam estar em status que permita edição (`0` Aberto, `1` Aguardando recebimento, `3` Perdido confirmado ou `6` Recebido parcialmente) e ter o **mesmo fornecedor**.", "tags": [ "Pedido de Compra" ], "parameters": [ { "name": "idbuyorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido de compra de origem (o que será mesclado e ficará vazio)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyOrderMergeBody" } } }, "description": "Pedido de compra de destino. Precisa estar em status que permita edição (`0`, `1`, `3` ou `6`) e ter o mesmo fornecedor do pedido de origem. Todos os itens do pedido da URL são movidos para este pedido; o pedido de origem passa a status `7 Mesclado` e fica vazio." }, "responses": { "200": { "description": "Pedidos mesclados. Retorna o detalhe atualizado do pedido de origem." }, "400": { "description": "Validação falhou. Mensagens reais: `[BadRequest] - Pedido de compra não existe`, `[BadRequest] - Status pedido de compra não permite mesclar`, `[BadRequest] - Pedido de compra destino não existe`, `[BadRequest] - Status pedido de compra destino não permite mesclar`, `[BadRequest] - Fornecedor divergente nos pedidos de compra`." } } } }, "/purchase/buy-order/{idbuyorder}/payment": { "post": { "operationId": "buyOrderPaymentPost", "summary": "Lança um pagamento do pedido de compra", "description": "Cria uma conta a pagar (`IDTypeAccount=1`, `Forecast=1`) vinculada ao pedido de compra. Usa o fornecedor e a empresa faturadora do próprio pedido. Valida tipo de pagamento, tipo de documento e plano de contas (exigindo que o plano seja de último nível). Registra a inclusão no histórico do pedido.", "tags": [ "Pedido de Compra" ], "parameters": [ { "name": "idbuyorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido de compra." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyOrderPaymentCreateBody" } } }, "description": "Dados do título a pagar a lançar no pedido de compra. O fornecedor e a empresa faturadora são herdados do próprio pedido. O plano de contas (`IDTypeAccountPayble`) precisa ser de último nível (folha do plano de contas)." }, "responses": { "200": { "description": "Pagamento lançado. Retorna o detalhe atualizado do pedido de compra." }, "400": { "description": "Validação falhou. Mensagens reais: `[BadRequest] - Pedido de compra não existe`, `[BadRequest] - Tipo pagamento não existe`, `[BadRequest] - Tipo documento não existe`, `[BadRequest] - Plano de contas não existe`, `[BadRequest] - Plano de contas não é último nível`." } } } }, "/purchase/buy-order/{idbuyorder}/payment/{idaccountpayablereceivable}": { "put": { "operationId": "buyOrderPaymentPut", "summary": "Atualiza um pagamento do pedido de compra", "description": "Atualiza uma conta a pagar vinculada ao pedido de compra. Mantém o fornecedor original do pedido. Valida tipo de pagamento, tipo de documento e plano de contas (exigindo último nível) quando enviados. Registra o diff de campos no histórico do pedido.", "tags": [ "Pedido de Compra" ], "parameters": [ { "name": "idbuyorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido de compra." }, { "name": "idaccountpayablereceivable", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da conta a pagar a ser atualizada." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyOrderPaymentCreateBody" } } }, "description": "Campos editáveis do título a pagar (atualização parcial). O fornecedor original do pedido é mantido. Validações de tipo de pagamento, tipo de documento e plano de contas valem quando os campos são enviados." }, "responses": { "200": { "description": "Pagamento atualizado. Retorna o detalhe atualizado do pedido de compra." }, "400": { "description": "Validação falhou. Mensagens reais: `[BadRequest] - Pagamento pedido de compra não existe`, `[BadRequest] - Tipo pagamento não existe`, `[BadRequest] - Tipo documento não existe`, `[BadRequest] - Plano de contas não existe`, `[BadRequest] - Plano de contas não é último nível`." } } }, "delete": { "operationId": "buyOrderPaymentDelete", "summary": "Remove um pagamento do pedido de compra", "description": "Exclui uma conta a pagar vinculada ao pedido de compra. Bloqueada quando o pedido está em status que não permite atualização (recebimentos com `IDStatusPurchase` `2`, `3` ou `7`). Registra a remoção no histórico do pedido.", "tags": [ "Pedido de Compra" ], "parameters": [ { "name": "idbuyorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido de compra." }, { "name": "idaccountpayablereceivable", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da conta a pagar a remover." } ], "responses": { "200": { "description": "Pagamento removido.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Validação falhou. Mensagens reais: `[BadRequest] - Pedido de compra não existe`, `[BadRequest] - Status não permite atualização`." } } } }, "/purchase/buy-order/{idbuyorder}/sku": { "post": { "operationId": "buyOrderSkuPost", "summary": "Adiciona item ao pedido de compra", "description": "Adiciona um SKU como item do pedido de compra. Só é permitido enquanto o pedido está em status `0 Aberto`. Valida que o SKU existe, está ativo (`IDStatusSku=1`) e é de um tipo comprável (`IDTypeSku` em `3`, `5`, `6` ou `7`). Resolve o armazém: se `IDStockKeepingUnitWarehouse` não vier, usa o armazém padrão da empresa; o centro de distribuição do item precisa bater com o do pedido (definido ou herdado do armazém).", "tags": [ "Pedido de Compra" ], "parameters": [ { "name": "idbuyorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido de compra." } ], "requestBody": { "description": "Adiciona um item (SKU) ao pedido de compra.", "content": { "application/json": { "schema": { "type": "object", "properties": { "IDSku": { "type": "integer", "description": "SKU a adicionar ao pedido de compra." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém de destino do item." }, "Quantity": { "type": "number", "format": "double", "description": "Quantidade a comprar." }, "ValueCostUnit": { "type": "number", "format": "double", "description": "Custo unitário de compra em R$." } }, "required": [ "IDSku", "Quantity" ] } } } }, "responses": { "200": { "description": "Item adicionado. Retorna o detalhe atualizado do pedido de compra." }, "400": { "description": "Validação falhou. Mensagens reais: `[BadRequest] - O status atual não permite atualização`, `[BadRequest] - SKU não cadastrado: `, `[BadRequest] - SKU não esta ativo`, `[BadRequest] - Warehouse não cadastrada: SKU -> `, `[BadRequest] - Centro de distribuição do item é diferente do pedido de compra`, `[BadRequest] - Erro ao inserir sku`." }, "404": { "description": "Pedido de compra não encontrado: `[NotFound] - Buy Order Not Found`." } } } }, "/purchase/buy-order/{idbuyorder}/sku/{idstockkeepingunitbuyorder}": { "put": { "operationId": "buyOrderSkuPut", "summary": "Atualiza item do pedido de compra", "description": "Atualiza um item do pedido de compra (SKU, armazém, quantidade, custo unitário, validade, observações, data prevista de entrega). Só é permitido enquanto o pedido está em status `0 Aberto`. O centro de distribuição do novo armazém precisa bater com o do pedido. Registra o diff de campos no histórico.", "tags": [ "Pedido de Compra" ], "parameters": [ { "name": "idbuyorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido de compra." }, { "name": "idstockkeepingunitbuyorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do item dentro do pedido de compra." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyOrderSkuUpdateBody" } } }, "description": "Campos editáveis do item do pedido de compra (atualização parcial): SKU, armazém, quantidade, custo unitário, validade, observações, data prevista de entrega. Pedido precisa estar em status `0 Aberto`. O centro de distribuição do novo armazém precisa bater com o do pedido." }, "responses": { "200": { "description": "Item atualizado. Retorna o detalhe atualizado do pedido de compra." }, "400": { "description": "Validação falhou. Mensagens reais: `[BadRequest] - Pedido de compra não existe`, `[BadRequest] - O status atual não permite atualizar`, `[BadRequest] - Sku não existe`, `[BadRequest] - Armazém não existe`, `[BadRequest] - Centro de distribuição do item é diferente do CD do pedido de compra`." } } }, "delete": { "operationId": "buyOrderSkuDelete", "summary": "Remove item do pedido de compra", "description": "Remove um item do pedido de compra. Só é permitido enquanto o pedido está em status `0 Aberto`. Registra a remoção no histórico.", "tags": [ "Pedido de Compra" ], "parameters": [ { "name": "idbuyorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido de compra." }, { "name": "idstockkeepingunitbuyorder", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do item dentro do pedido de compra." } ], "responses": { "200": { "description": "Item removido. Retorna o detalhe atualizado do pedido de compra." }, "400": { "description": "Validação falhou: `[BadRequest] - O status atual não permite atualizar`." }, "404": { "description": "Pedido de compra não encontrado: `[NotFound] - Pedido de compra não localizado`." } } } }, "/charge/bank-slip/{idbankslip}/order": { "post": { "operationId": "chargeBankSlipOrderPost", "summary": "Cria um pedido a partir de boleto pago", "description": "Gera um pedido (`Orders`) a partir de um boleto bancário pago avulso. O boleto precisa estar em status Pago (`IDStatusBankSlip=2`) e ainda não ter pedido vinculado. O pedido nasce com o cliente do boleto, o tipo de pedido padrão da empresa, a integração do tipo Stark (`IDTypeCompanyIntegration=16`) e um pagamento de categoria boleto (`Category=2`) já lançado com o `TID`/`NSU` e o valor do boleto. Ao final, o boleto fica vinculado ao novo pedido.", "tags": [ "Boleto Bancário" ], "parameters": [ { "name": "idbankslip", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do boleto bancário." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeBankSlipOrderBody" } } }, "description": "Corpo opcional — o sistema resolve cliente do boleto, integração padrão Stark, tipo de pedido padrão da empresa e tipo de pagamento de boleto a partir da configuração da empresa, sem necessidade de campos no body." }, "responses": { "200": { "description": "Pedido criado. Retorna o detalhe completo do pedido novo." }, "400": { "description": "Configuração da empresa incompleta. Mensagens reais: `[BadRequest] - IDTypeOrder não existe` (tipo de pedido padrão não cadastrado), `[BadRequest] - IDCompanyIntegration não existe` (integração Stark não cadastrada), `[BadRequest] - IDTypePayment não existe` (tipo de pagamento de boleto ativo não cadastrado)." }, "404": { "description": "Boleto inválido para criação de pedido. Mensagens reais: `[NotFound] - Boleto não existe`, `[NotFound] - Boleto não esta pago`, `[NotFound] - Boleto já tem pedido criado`." } } } }, "/company/bill": { "get": { "operationId": "companyBillingGet", "summary": "Lista as faturas mensais de cobrança da empresa", "description": "Retorna o histórico de faturas geradas, com vencimento, valor total, nota fiscal de serviço associada e boleto. Cada fatura traz o detalhamento das regras de cobrança aplicadas no mês.", "tags": [ "Cobrança" ], "responses": { "200": { "description": "Faturas encontradas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyBill" } } } } }, "500": { "description": "Erro interno." } } } }, "/company/bill/{idcompanybilling}/report": { "post": { "operationId": "companyBillingReportPost", "summary": "Gera o relatório detalhado de uma fatura e envia por e-mail", "description": "Gera a planilha com o detalhamento de uma fatura e a envia por e-mail ao usuário autenticado; a resposta HTTP não traz o arquivo (que chega por e-mail) e a planilha é montada e enviada durante a própria requisição, sem processamento em segundo plano.", "tags": [ "Cobrança" ], "parameters": [ { "name": "idcompanybilling", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da fatura." } ], "responses": { "200": { "description": "Relatório gerado e enviado por e-mail ao usuário durante a requisição. Sem corpo na resposta." }, "400": { "description": "Empresa ou fatura não localizada. Corpo JSON com `errorMessage` no formato `[BadRequest] - `: `[BadRequest] - Empresa não localizada`, `[BadRequest] - Fatura não localizada`." }, "500": { "description": "Erro interno ao gerar o relatório (ex.: fatura sem itens detalhados). Corpo vazio." } } } }, "/company/dashboard": { "get": { "operationId": "companyDashboardGet", "summary": "Retorna indicadores do painel inicial por categoria", "description": "Devolve os blocos de KPIs do painel inicial conforme a categoria solicitada. As categorias `8` e `9` têm comportamento próprio: financeiro consolida vencimentos do mês corrente; rastreio agrega entregas no prazo e atrasadas. As demais categorias retornam a lista de cartões configurados para a empresa.\n\nQuando `IDTypeCompanyDashboardCategory=8`, os filtros adicionais por data de vencimento, fornecedor, faturador e conta bancária da previsão se aplicam. Quando `IDTypeCompanyDashboardCategory=9`, vale a janela de embarque `ShippingDate*` e de criação do pedido `RecordTimestamp` via `DateFrom`/`DateTo` — sem datas, considera os últimos 7 dias.", "tags": [ "Dashboards" ], "parameters": [ { "name": "IDTypeCompanyDashboardCategory", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Categoria do painel a ser retornado. Valores especiais: `8` = financeiro (vencimentos); `9` = rastreio (entregas)." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de criação do pedido (apenas categoria rastreio)." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de criação do pedido (apenas categoria rastreio). O sistema concatena `23:59:59` ao filtrar." }, { "name": "ShippingDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial do embarque (apenas categoria rastreio)." }, { "name": "ShippingDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final do embarque (apenas categoria rastreio)." }, { "name": "DateDueFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de vencimento (apenas categoria financeiro). Default: `1900-01-01`." }, { "name": "DateDueTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de vencimento (apenas categoria financeiro). Default: `4000-01-01`." }, { "name": "IDTypeAccount", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Tipo da conta: `0` = entrada (receber); `1` = saída (pagar)." }, { "name": "IDTypeAccountPayableReceivable", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Tipo do título financeiro." }, { "name": "IDStatusAccountPayableReceivable", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6 ] }, "description": "Status do título financeiro." }, { "name": "IDSupplier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador do fornecedor." }, { "name": "IDCompanyInvoice", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador do faturador." }, { "name": "IDBankAccountForecast", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador da conta bancária de previsão." } ], "responses": { "200": { "description": "Indicadores retornados.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDashboardSummary" } }, { "type": "object", "properties": { "trackings": { "type": "array", "items": { "type": "object" }, "description": "Coleção de rastreios resumidos exibidos no dashboard." }, "otdacount": { "type": "object", "properties": { "onTime": { "type": "integer", "description": "Quantidade de entregas no prazo." }, "afterTime": { "type": "integer", "description": "Quantidade de entregas atrasadas." }, "exceptions": { "type": "integer", "description": "Quantidade de entregas com exceção (não entregue, devolvida ou em problema)." } }, "description": "Agregado de pontualidade de entrega (OTDA = On-Time Delivery Accuracy)." } } } ] } } } } } } }, "/company/dashboard/order/status": { "get": { "operationId": "companyDashboardOrderStatusGet", "summary": "Contagem de pedidos por status para o painel", "description": "Retorna o total de pedidos agrupado por status para o painel inicial. Respeita os centros de distribuição liberados ao usuário autenticado. Quando `Budget=1`, considera o conjunto de status reservados ao fluxo de orçamento; caso contrário, considera os status de pedido padrão (exclui o status `7`).", "tags": [ "Dashboards" ], "parameters": [ { "name": "Budget", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "Quando `1`, contabiliza apenas status do fluxo de orçamento." } ], "responses": { "200": { "description": "Contagem por status.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDashboardOrderStatus" } } } } } } } }, "/company/module": { "get": { "operationId": "companyModuleGet", "summary": "Lista os módulos contratados pela empresa com seus privilégios", "description": "Retorna os grupos de módulos disponíveis, cada um com a lista de módulos contratados pela empresa e os privilégios associados a cada módulo. Usado para montar a árvore de permissões do perfil de acesso.", "tags": [ "Módulos Contratados" ], "responses": { "200": { "description": "Módulos retornados.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyModule" } } } } } } } }, "/company/report/custom": { "get": { "operationId": "companyReportCustomList", "summary": "Lista os relatórios personalizados da empresa", "description": "Retorna os relatórios dinâmicos cadastrados pela empresa, incluindo a estrutura `ReportStructure` (campos selecionados, filtros, agrupamentos, ordenação), o tipo de relatório personalizado e a lista de campos referenciados.", "tags": [ "Relatórios Customizados" ], "parameters": [ { "name": "IDTypeCompanyReport", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filtra por um relatório específico." } ], "responses": { "200": { "description": "Lista de relatórios.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyReportCustom" } } } } } } }, "post": { "operationId": "companyReportCustomPost", "summary": "Cria um relatório personalizado", "description": "Monta um relatório dinâmico a partir da seleção de campos, filtros, agrupamentos e ordenação. O sistema monta a consulta correspondente a partir do tipo de relatório e dos relacionamentos disponíveis. Após salvar, é disparada a execução para gerar o conteúdo.", "tags": [ "Relatórios Customizados" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyReportCustomCreateBody" } } }, "description": "Configuração do relatório personalizado: nome, tipo base (`ReportType` → `TypeCustomReport`), campos selecionados (`Select`), filtros (`Where` com `FieldID` + `Value`), agrupamentos (`GroupBy`) e ordenação (`OrderBy`). O sistema monta a query para cada destino disponível (banco transacional e BigQuery, quando aplicável) e grava em `MySQLQuery1/2` e `BigQueryQuery1/2`." }, "responses": { "200": { "description": "Relatório criado e executado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyReportCustom" } } } } }, "400": { "description": "Empresa não localizada, tipo de relatório não informado, base não suportada ou nenhum campo selecionado. Mensagem em texto puro." } } } }, "/company/report/custom/{idtypecompanyreport}": { "put": { "operationId": "companyReportCustomPut", "summary": "Atualiza um relatório personalizado", "description": "Substitui a estrutura do relatório personalizado existente (campos, filtros, agrupamento, ordenação) e re-executa para regenerar o conteúdo.", "tags": [ "Relatórios Customizados" ], "parameters": [ { "name": "idtypecompanyreport", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do relatório personalizado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyReportCustomCreateBody" } } }, "description": "Atualização total da configuração do relatório personalizado — todos os campos do corpo são gravados. A SQL é regerada a partir da nova estrutura." }, "responses": { "200": { "description": "Relatório atualizado.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyReportCustom" } } } } }, "400": { "description": "Relatório não localizado, tipo de relatório não informado ou nenhum campo selecionado. Mensagem em texto puro." } } }, "delete": { "operationId": "companyReportCustomDelete", "summary": "Remove um relatório personalizado", "description": "Remove o vínculo do relatório com a empresa. O relatório só pode ser removido se pertencer à empresa autenticada.", "tags": [ "Relatórios Customizados" ], "parameters": [ { "name": "idtypecompanyreport", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do relatório personalizado." } ], "responses": { "200": { "description": "Relatório removido. Retorna o literal `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Nenhum relatório encontrado para deletar, falha na operação ou erro de configuração da empresa. Prefixo `[BadRequest]`." } } } }, "/company/status/order": { "get": { "operationId": "typeOrderStatusRuleList", "summary": "Lista as transições permitidas a partir de um status de pedido", "description": "Retorna os status de destino válidos para o status de origem informado, conforme as regras de transição configuradas. Cada destino indica se exige comentário e se exige data ao mover o pedido.", "tags": [ "Transições de Status" ], "parameters": [ { "name": "IDStatusOrder", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Status de origem do pedido." } ], "responses": { "200": { "description": "Transições permitidas.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "IDStatusOrder": { "type": "integer", "description": "Status de origem." }, "StatusOrder": { "type": "string", "nullable": true, "description": "Descrição do status de origem para a empresa." }, "IDStatusOrderTo": { "type": "integer", "description": "Status de destino permitido." }, "StatusOrderTo": { "type": "string", "description": "Descrição do status de destino para a empresa." }, "CommentsRequired": { "type": "integer", "description": "`1` quando o destino exige comentário." }, "DateRequired": { "type": "integer", "description": "`1` quando o destino exige data." } } } } } } }, "400": { "description": "`IDStatusOrder` é obrigatório. Prefixo `[BadRequest]`." } } } }, "/goal": { "get": { "operationId": "goalList", "summary": "Lista as metas cadastradas para a empresa", "description": "Retorna até 5.000 metas ordenadas pela data inicial decrescente. Aceita filtros por tipo de meta, identificador da meta e janela de início. Cada meta traz o tipo amigável.", "tags": [ "Metas" ], "parameters": [ { "name": "IDTypeGoal", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "description": "Tipo da meta: `1` vendedor, `2` faturador, `3` tipo de pedido, `4` integração." }, { "name": "IDCompanyGoal", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador da meta." }, { "name": "DateFromFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial mínima de vigência." }, { "name": "DateFromTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial máxima de vigência. O sistema concatena `23:59:59`." } ], "responses": { "200": { "description": "Metas retornadas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Goal" } } } } } } }, "post": { "operationId": "goalPost", "summary": "Cria uma meta para a empresa", "description": "Cria a meta principal e, conforme o `IDTypeGoal`, persiste o desdobramento por vendedor (`GoalSalesmans`), faturador (`GoalCompanyInvoices`), tipo de pedido (`GoalTypeOrders`) ou integração (`GoalCompanyIntegrations`). Bloqueia a criação quando já existe meta do mesmo tipo dentro do intervalo `DateFrom`–`DateTo`. Valida que `DateFrom` não seja maior que `DateTo` e que cada item do desdobramento pertença à empresa.", "tags": [ "Metas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalCreateBody" } } }, "description": "Meta a cadastrar. `IDTypeGoal`, `GoalName`, `DateFrom` e `DateTo` são obrigatórios. O desdobramento por item (`GoalSalesmans`, `GoalCompanyInvoices`, `GoalTypeOrders`, `GoalCompanyIntegrations`) precisa ser informado de acordo com o `IDTypeGoal` (1 vendedor, 2 faturador, 3 tipo de pedido, 4 integração). O sistema bloqueia quando já existe meta do mesmo tipo dentro do intervalo `DateFrom`–`DateTo` e valida que cada item pertença à empresa autenticada." }, "responses": { "200": { "description": "Meta criada. Retorna a representação completa da meta (delegado ao `goalGet`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Goal" } } } } }, "400": { "description": "Possíveis causas: tipo de meta inexistente, empresa não localizada, sobreposição com meta já cadastrada, `DateFrom` maior que `DateTo`, ou vendedor/faturador/tipo de pedido/integração inexistentes. Prefixo `[BadRequest]`." } } } }, "/goal/{idcompanygoal}": { "get": { "operationId": "goalGet", "summary": "Retorna uma meta com o desdobramento por item", "description": "Retorna a meta principal e, conforme o tipo, popula `GoalSalesmans`, `GoalCompanyInvoices`, `GoalTypeOrders` ou `GoalCompanyIntegrations` com os valores configurados para cada vendedor, faturador, tipo de pedido ou integração.", "tags": [ "Metas" ], "parameters": [ { "name": "idcompanygoal", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da meta." } ], "responses": { "200": { "description": "Meta retornada. Quando inexistente, retorna lista vazia.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Goal" } } } } } } }, "put": { "operationId": "goalPut", "summary": "Atualiza uma meta e seu desdobramento", "description": "Altera os dados principais da meta e substitui o desdobramento por vendedor, faturador, tipo de pedido ou integração de acordo com o `IDTypeGoal`. Aplica as mesmas validações do POST: bloqueia sobreposição com outras metas do mesmo tipo e exige `DateFrom` menor ou igual a `DateTo`.", "tags": [ "Metas" ], "parameters": [ { "name": "idcompanygoal", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da meta." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalUpdateBody" } } }, "description": "Mesmo contrato do POST. Os itens do desdobramento informados substituem os existentes — itens omitidos preservam os atuais. Mesmas validações de sobreposição, intervalo de datas e existência dos itens na empresa." }, "responses": { "200": { "description": "Meta atualizada. Retorna a representação completa (delegado ao `goalGet`).", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Goal" } } } } }, "400": { "description": "Mesmos cenários do POST. Prefixo `[BadRequest]`." } } }, "delete": { "operationId": "goalDelete", "summary": "Remove uma meta", "description": "Remove a meta e, em cascata, todos os desdobramentos por vendedor, faturador, tipo de pedido e integração.", "tags": [ "Metas" ], "parameters": [ { "name": "idcompanygoal", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador da meta." } ], "responses": { "200": { "description": "Meta removida. Retorna o literal `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Meta não existe. Prefixo `[BadRequest]`." } } } }, "/correios/reversa": { "get": { "operationId": "trackReverseList", "summary": "Lista as solicitações de logística reversa Correios", "description": "Retorna as coletas reversas abertas para os pedidos da empresa, com identificador da coleta, prazo, transportadora associada e origens do pedido. Pagina por blocos de 3.000 registros (`Page`) limitando 1.000 por página.", "tags": [ "Logística Reversa Correios" ], "parameters": [ { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo número do pedido (busca parcial via `LIKE`)." }, { "name": "OrderFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por uma origem associada ao pedido." }, { "name": "IDColeta", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo código da coleta Correios (busca parcial via `LIKE`)." }, { "name": "DateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de criação da coleta reversa." }, { "name": "DateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de criação da coleta reversa. O sistema concatena `23:59:59`." }, { "name": "DateReverseDeadlineFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial do prazo da coleta." }, { "name": "DateReverseDeadlineTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final do prazo da coleta. O sistema concatena `23:59:59`." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Número da página. Cada página retorna até 1.000 registros, com offset de 3.000 por página." } ], "responses": { "200": { "description": "Coletas retornadas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CorreiosReversa" } } } } } } }, "post": { "operationId": "reversaCorreiosPost", "summary": "Solicita uma coleta reversa Correios", "description": "Encaminha a solicitação de postagem reversa ao processo dos Correios. Aceita coleta domiciliar (`TipoColeta` informado) ou postagem em agência (`TipoColeta=0`, valor padrão quando omitido).", "tags": [ "Logística Reversa Correios" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorreiosReversaCreateBody" } } }, "description": "Solicitação de logística reversa Correios. `IDOrder` e `IDCarrier` são obrigatórios. `TipoColeta` define a modalidade — `0` (default, omitido) para postagem em agência, `1`/`2` para coleta domiciliar; quando domiciliar, `Schedule` carrega o agendamento (data e janela de horário). O corpo é encaminhado ao serviço de logística reversa dos Correios." }, "responses": { "200": { "description": "Solicitação aceita. Retorna o literal `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "500": { "description": "Erro retornado pelo processo dos Correios. Mensagem propagada do serviço externo." } } } }, "/correios/generaterange": { "post": { "operationId": "correiosGenerateRange", "summary": "Gera uma faixa de etiquetas Correios para a transportadora", "description": "Dispara a rotina que solicita uma nova faixa de códigos de rastreio (etiquetas) aos Correios para a transportadora informada. A transportadora precisa pertencer à empresa autenticada e ter tipo Correios.", "tags": [ "Faixa de Etiquetas Correios" ], "parameters": [ { "name": "IDCarrier", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Identificador da transportadora Correios. Enviado como query string." } ], "responses": { "200": { "description": "Geração disparada. Retorna o literal `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Transportadora inexistente para a empresa ou não é do tipo Correios. Prefixo `[BadRequest]`." }, "500": { "description": "Erro retornado pelo processo. Mensagem propagada do serviço externo." } } } }, "/correios/pi": { "get": { "operationId": "correiosPIList", "summary": "Lista as Postagens Imediatas Correios", "description": "Retorna as PIs (Postagens Imediatas) Correios abertas para os pacotes da empresa, com identificador da PI, status, datas de abertura e postagem, prazo máximo de entrega, motivo da reclamação e última mensagem de retorno. Pagina por blocos de 3.000 registros (`Page`) limitando 1.000 por página.", "tags": [ "Correios — PI" ], "parameters": [ { "name": "Order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo número do pedido (busca parcial via `LIKE`)." }, { "name": "OrderFrom", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por uma origem associada ao pedido." }, { "name": "ShippingDateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial do embarque do pacote." }, { "name": "ShippingDateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final do embarque do pacote. O sistema concatena `23:59:59`." }, { "name": "DateOpeningPIFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data inicial de abertura da PI." }, { "name": "DateOpeningPITo", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Data final de abertura da PI. O sistema concatena `23:59:59`." }, { "name": "StatusPI", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelo status da PI (busca parcial via `LIKE`)." }, { "name": "Page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Número da página. Cada página retorna até 1.000 registros, com offset de 3.000 por página." } ], "responses": { "200": { "description": "PIs retornadas.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CorreiosPI" } } } } } } } }, "/file": { "post": { "operationId": "filePost", "tags": [ "Arquivos" ], "summary": "Anexa arquivo a um consumidor", "description": "Faz upload de um arquivo `multipart/form-data` e vincula ao consumidor informado em `IDConsumer`. O arquivo é armazenado em bucket privado e o sistema responde com o registro criado, a chave interna `Key` e uma URL pré-assinada `UrlFile` (validade 48h). Limite de 3 arquivos por consumidor — quando atingido, é preciso remover um arquivo antes de adicionar outro.", "parameters": [ { "name": "FileSource", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "Consumer" ] }, "description": "Origem do arquivo. Hoje só `Consumer` é aceito; outros valores resultam em `[BadRequest]`." }, { "name": "IDConsumer", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do consumidor que receberá o arquivo. Validado contra a empresa autenticada (subdomínio)." }, { "name": "IDTypeFile", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "description": "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." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Conteúdo binário do arquivo. O nome original (incluindo extensão) é preservado para inferir a extensão usada na chave do bucket." } } } } }, "description": "Upload `multipart/form-data` com o campo `file` contendo o binário. O nome original (com extensão) é preservado para inferir a extensão usada na chave do bucket. Os metadados do arquivo (`FileSource`, `IDConsumer`, `IDTypeFile`) vão pela query." }, "responses": { "200": { "description": "Arquivo armazenado com sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } }, "400": { "description": "Falha de validação. Mensagens possíveis: `[BadRequest] - Empresa não identificada no contexto da requisição.`, `[BadRequest] - IDConsumer é obrigatório.`, `[BadRequest] - IDTypeFile é obrigatório.`, `[BadRequest] - Consumidor não existe`, `[BadRequest] - Tipo de arquivo não existe`, `[BadRequest] - O consumidor já possui 3 arquivos vinculados. Remova um arquivo para adicionar outro.`, `[BadRequest] - Arquivo não enviado`, `[BadRequest] - Arquivo sem extensão`, `[BadRequest] - FileSource inválido`." }, "500": { "description": "Erro interno. Falha ao gravar no bucket ou no banco." } } }, "delete": { "operationId": "fileDelete", "tags": [ "Arquivos" ], "summary": "Remove arquivo vinculado a um consumidor", "description": "Remove o vínculo de um arquivo de consumidor a partir do identificador `IDFile`. O registro é apagado mesmo que o objeto correspondente no bucket ainda exista (limpeza do bucket está atualmente desativada no sistema).", "parameters": [ { "name": "FileSource", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "Consumer" ] }, "description": "Origem do arquivo. Hoje só `Consumer` é aceito." }, { "name": "IDConsumer", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do consumidor dono do arquivo." }, { "name": "IDFile", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do arquivo a remover (`IDConsumerFile`)." } ], "responses": { "200": { "description": "Arquivo removido com sucesso. Retorna a string literal `\"sucesso\"`.", "content": { "application/json": { "schema": { "type": "string", "example": "sucesso" } } } }, "400": { "description": "Falha de validação. Mensagens possíveis: `[BadRequest] - ID do arquivo não informado`, `[BadRequest] - Arquivo não informado`, `[BadRequest] - Arquivo não existe`, `[BadRequest] - FileSource inválido`." }, "500": { "description": "Erro interno na execução da exclusão." } } } }, "/supplier/{idsupplier}/label": { "get": { "operationId": "supplierLabelGet", "tags": [ "Cadastro de Fornecedores" ], "summary": "Gera etiqueta personalizada do fornecedor (ZPL ou PDF)", "description": "Gera a etiqueta de identificação do fornecedor conforme o modelo configurado em `IDCompanyLabel`. Retorna PDF (convertido via Labelary) por padrão, ou ZPL bruto quando `Zpl=1` / arquivo `.zpl` quando `Download=1`.", "parameters": [ { "name": "idsupplier", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do fornecedor." }, { "name": "IDCompanyLabel", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do modelo de etiqueta cadastrado para a empresa." }, { "name": "Download", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` baixa o arquivo `.zpl` direto." }, { "name": "Zpl", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] }, "description": "`1` retorna o ZPL bruto (válido quando `Download=0`)." } ], "responses": { "200": { "description": "Etiqueta gerada. Tipo do conteúdo varia conforme `Download`/`Zpl`: `application/pdf` (padrão), `application/epl2` (`Download=1`) ou ZPL puro como texto (`Download=0` + `Zpl=1`).", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/epl2": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string", "description": "ZPL bruto." } } } }, "400": { "description": "Falha de validação. Mensagens possíveis: `Parâmetros inválidos, obrigatório informar account e IDCompanyLabel`, `Fornecedor não encontrado`, `Problema ao gerar etiqueta`." }, "500": { "description": "Erro interno na geração da etiqueta." } } } }, "/supplier/{idsupplier}/template": { "get": { "operationId": "carrierRateFileTemplateImport", "tags": [ "Cadastro de Fornecedores" ], "summary": "Baixa o arquivo de tabela de frete do transportador", "description": "Devolve, como anexo `.xlsx`, o arquivo de tabela de frete (`CarrierTableUpload`) anteriormente importado para o transportador (fornecedor com perfil de carrier). O `idsupplier` no path identifica o transportador e `IDFile` aponta o registro específico do upload a recuperar.", "parameters": [ { "name": "idsupplier", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do fornecedor (transportador)." }, { "name": "IDFile", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Identificador do upload da tabela (`IDCarrierTableUpload`)." } ], "responses": { "200": { "description": "Arquivo `.xlsx` da tabela de frete pronto para download.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Arquivo não encontrado. Mensagens possíveis: `[BadRequest] - Arquivo não encontrado`, `[NotFound] - Arquivo não encontrado S3`." }, "500": { "description": "Erro interno ao recuperar o arquivo do bucket." } } } } }, "components": { "securitySchemes": { "JWT": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Token JWT obtido via `POST /auth/token`. Enviado no header `Authorization: Bearer `." } }, "schemas": { "ApiErrorMessage": { "type": "object", "description": "Formato de resposta de erro. O campo `errorMessage` traz o prefixo (`[BadRequest]` ou `Error:`) seguido da descrição.", "properties": { "errorMessage": { "type": "string", "example": "[BadRequest] - Fornecedor ou cliente precisa ser preenchido (apenas um dos dois)", "description": "Texto do erro, sempre começando com o prefixo que define o status (`[BadRequest] - ...` para 400, `Error: ...` para 500). O conteúdo após o prefixo é a mensagem específica do sistema." } } }, "CompanyInvoiceListItem": { "type": "object", "description": "Linha da lista de NFs (`companyInvoiceList`). Vem de `NfCompany` (`N.*`) mais campos derivados de JOINs com `Orders`, `Company` (faturador), `TypeStatusInvoice`, `NfProcessCode`, `NfTpEmis`, `NfFin`, `NfTpNf`, `NfModNf`, `OrdersFile`. **Em modo \"pedidos pendentes\"** (quando `IDStatusInvoice` inclui `0`), a lista também devolve linhas vindas de `Orders` sem NF — nessas, todos os campos específicos da NF (`IDNfCompany`, `NfeNumber`, `NfeSerie`, `NfeChaveAcesso`, `NfedhEmi`, datas, valores, descrições de tipo) vêm como `null` e o `StatusInvoice` literal é `\"Pendente\"`.", "properties": { "IDNfCompany": { "type": "integer", "nullable": true, "description": "Id da NF. `null` em linhas de pedido sem NF (modo pendente)." }, "IDCompany": { "type": "integer", "description": "Id da empresa dona do pedido (`IDCompany`)." }, "AccountName": { "type": "string", "description": "Conta dona do pedido." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Id do faturador. `0`/`null` em pedidos pendentes." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Conta do faturador (`AccountName`)." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social do faturador." }, "CompanyCpfCnpjInvoice": { "type": "string", "nullable": true, "description": "CNPJ do faturador." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Id do pedido vinculado (`null` para numerações reservadas via `POST /invoice`)." }, "Order": { "type": "string", "nullable": true, "description": "Número do pedido visível ao cliente." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Cliente do pedido." }, "ConsumerCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ do cliente." }, "NfeNumber": { "type": "integer", "nullable": true, "description": "Número da NF." }, "NfeSerie": { "type": "integer", "nullable": true, "description": "Série da NF." }, "NfeModelo": { "type": "integer", "nullable": true, "description": "Modelo da NF (`55` NF-e, `65` NFC-e)." }, "NfModNfDescription": { "type": "string", "nullable": true, "description": "Descrição do modelo da NF." }, "NfeChaveAcesso": { "type": "string", "nullable": true, "description": "Chave de acesso (44 dígitos)." }, "NfedhEmi": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora de emissão da NF." }, "NfecStat": { "type": "integer", "nullable": true, "description": "Código de status do processo na SEFAZ." }, "NfProcessDescription": { "type": "string", "nullable": true, "description": "Descrição do processo SEFAZ (`NfProcessDescription`)." }, "NfetpEmis": { "type": "integer", "nullable": true, "description": "Tipo de emissão." }, "NfetpEmisDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo de emissão (`NfetpEmisDescription`)." }, "FinNfeDescription": { "type": "string", "nullable": true, "description": "Descrição da finalidade da NF (`FinNfeDescription`)." }, "NfTpNfDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo da NF (`NfTpNfDescription` — Entrada/Saída)." }, "IDStatusInvoice": { "type": "integer", "description": "Status da NF: `0` Pendente, `1` Erro, `2` Enviada, `3` Emitida, `4` Processando, `5` Pendente Conciliação EPEC, `6` Erro Conciliação EPEC, `7` Cancelada, `8` Denegada, `9` Inutilizada." }, "StatusInvoice": { "type": "string", "description": "Status textual (`StatusInvoice`); em linhas de pedido sem NF vem literal `\"Pendente\"`." }, "ValueNF": { "type": "number", "nullable": true, "description": "Valor total da NF (`NfeTotalValue`)." }, "IDFile": { "type": "integer", "nullable": true, "description": "Id do arquivo (`IDFile` com `IDTypeFile=2`) — base do download de XML/DANFE." } } }, "CompanyInvoiceCreate": { "type": "object", "description": "Corpo do `POST /invoice` (botão Gerar Numeração NF).", "required": [ "IDCompanyInvoice", "NfeSerie", "NfeNumber" ], "properties": { "IDCompanyInvoice": { "type": "integer", "description": "Id do faturador. Precisa ser uma empresa do grupo (`CompanyMain`) da conta autenticada." }, "NfeSerie": { "type": "integer", "description": "Série da NF a registrar." }, "NfeNumber": { "type": "integer", "description": "Número da NF a registrar." }, "NfeModelo": { "type": "integer", "default": 55, "description": "Modelo da NF (`55` ou `65`). Default: `55`." } } }, "ServiceInvoiceListItem": { "type": "object", "description": "Linha da lista de NFS-e (`invoiceServiceList`). Vem de `ServiceOrder` com `TypeStatusInvoice`, `IBGECityCode` (cidade/UF), `NfsServiceCode` (descrição do código de serviço, quando cadastrado), conta e faturador já resolvidos. `NfsValue` e `ValuePaid` são calculados pelo servidor.", "properties": { "IDServiceOrder": { "type": "integer", "description": "Id interno da NFS-e." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de criação da NFS-e." }, "IDCompany": { "type": "integer", "description": "Id da empresa dona da NFS-e." }, "AccountName": { "type": "string", "description": "Conta dona da NFS-e." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Id do faturador (`IDCompany` quando a NFS-e é faturada pela própria empresa)." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Conta do faturador." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social do faturador." }, "CityCode": { "type": "integer", "description": "Código IBGE da cidade de prestação do serviço." }, "CityName": { "type": "string", "description": "Nome da cidade (`CityName`)." }, "State": { "type": "string", "description": "UF da cidade (`State`)." }, "IDConsumer": { "type": "integer", "description": "Id do cliente." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Nome/razão social do cliente (gravado na NFS-e)." }, "ConsumerCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ do cliente (apenas dígitos)." }, "IDAddress": { "type": "integer", "nullable": true, "description": "Id do endereço de prestação do serviço." }, "NfsDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de emissão da NFS-e (preenchida após emissão)." }, "NfsServiceCode": { "type": "string", "nullable": true, "description": "Código de serviço municipal aplicado à NFS-e." }, "ServiceDescription": { "type": "string", "nullable": true, "description": "Descrição do código de serviço (`ServiceDescription`); `null` quando o município não tem o código cadastrado." }, "IDStatusInvoice": { "type": "integer", "description": "Status numérico da NFS-e." }, "StatusInvoice": { "type": "string", "description": "Status textual (`StatusInvoice` — Pendente, Erro, Enviada, Emitida, Cancelada…)." }, "NfsNumber": { "type": "integer", "nullable": true, "description": "Número da NFS-e atribuído pela prefeitura (após emissão)." }, "NfsVerificationCode": { "type": "string", "nullable": true, "description": "Código de verificação da NFS-e na prefeitura." }, "NfsValue": { "type": "number", "description": "Valor total: `NfsServiceQuantity * NfsServiceUnitValue`." }, "ValuePaid": { "type": "number", "nullable": true, "description": "Soma de `Value` das `AccountsPayableReceivable` vinculadas. `null` quando não há contas." } } }, "ServiceInvoiceCreate": { "type": "object", "description": "Corpo do `POST /invoice-service` (modal Nova NF de Serviço).", "required": [ "IDConsumer", "NfsServiceCode", "NfsServiceQuantity", "NfsServiceUnitValue" ], "properties": { "IDConsumer": { "type": "integer", "description": "Id do cliente. Precisa pertencer à empresa autenticada." }, "IDAddress": { "type": "integer", "nullable": true, "description": "Id do endereço de prestação do serviço (do cliente)." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Id do pedido de mercadoria vinculado, quando a NFS-e nasce a partir de um pedido." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Id do faturador. Quando omitido, usa a própria conta (`IDCompany` resolvido pelo prefix)." }, "NfsComments": { "type": "string", "nullable": true, "description": "Comentários/observações da NFS-e." }, "NfsServiceCode": { "type": "string", "description": "Código de serviço municipal." }, "NfsServiceQuantity": { "type": "integer", "description": "Quantidade do serviço prestado." }, "NfsServiceUnitValue": { "type": "number", "description": "Valor unitário do serviço." }, "NfsIRRFRetentionValue": { "type": "number", "nullable": true, "description": "Valor de retenção de IRRF." }, "NfsPISRetentionValue": { "type": "number", "nullable": true, "description": "Valor de retenção de PIS." }, "NfsCOFINSRetentionValue": { "type": "number", "nullable": true, "description": "Valor de retenção de COFINS." }, "NfsCSLLRetentionValue": { "type": "number", "nullable": true, "description": "Valor de retenção de CSLL." }, "NfsISSAliquot": { "type": "number", "nullable": true, "description": "Alíquota do ISS." } } }, "GnreListItem": { "type": "object", "description": "Linha da lista de guias GNRE (`orderGnreList`, modo padrão). Vem de `Gnre` com `TypeStatusGnre`, `GnreStateCode`, `Orders`, `NfCompany` principal, `Suppliers` (transportadora) e `Company`. Valores numéricos chegam como `decimal` e são convertidos para `Number` no sistema; quando `NaN`, vira `0`.", "properties": { "IDGnre": { "type": "integer", "description": "Id da guia GNRE." }, "IDOrder": { "type": "integer", "description": "Id do pedido amarrado à guia." }, "Order": { "type": "string", "description": "Número do pedido visível ao cliente." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de criação da guia." }, "DueDate": { "type": "string", "format": "date", "description": "Vencimento da guia." }, "BarCode": { "type": "string", "maxLength": 60, "nullable": true, "description": "Código de barras da guia (`BarCode`)." }, "ReceiptNumber": { "type": "string", "maxLength": 45, "nullable": true, "description": "Número do protocolo após emissão (`ReceiptNumber`)." }, "RevenueCode": { "type": "integer", "description": "Código de receita da UF (`RevenueCode`)." }, "Description": { "type": "string", "nullable": true, "description": "Descrição do código de receita (`Description`) para o estado de envio." }, "StatusProcessCode": { "type": "integer", "nullable": true, "description": "Código do status atual do processamento da guia (`StatusCode`)." }, "StatusDescription": { "type": "string", "nullable": true, "description": "Descrição do status atual (`StatusDescription`)." }, "GnreValue": { "type": "number", "description": "Valor principal da guia." }, "GnreInterest": { "type": "number", "description": "Juros." }, "GnreRestatement": { "type": "number", "description": "Correção/atualização monetária." }, "GnrePenalty": { "type": "number", "description": "Multa." }, "GnreTotalValue": { "type": "number", "description": "`GnreValue + GnreInterest + GnreRestatement + GnrePenalty` (computado no servidor)." }, "Comments": { "type": "string", "nullable": true, "description": "Comentários livres da guia." }, "ShippingState": { "type": "string", "description": "UF de destino do pedido." }, "NfeNumber": { "type": "string", "nullable": true, "description": "Número da NF principal vinculada (`NfeNumber`)." }, "NfeSerie": { "type": "string", "nullable": true, "description": "Série da NF principal." }, "NfedhEmi": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de emissão da NF principal." }, "IDStatusInvoice": { "type": "integer", "nullable": true, "description": "Status numérico da NF principal." }, "StatusInvoice": { "type": "string", "description": "Status textual da NF (`StatusInvoice`); `\"Pendente\"` quando o pedido ainda não tem status atribuído." }, "IDStatusOrder": { "type": "integer", "description": "Status numérico do pedido." }, "StatusOrder": { "type": "string", "description": "Status do pedido para a empresa (`StatusOrder`)." }, "IDCarrier": { "type": "integer", "nullable": true, "description": "Id da transportadora do pedido." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social da transportadora (`SupplierNameCorporateName`)." }, "AccountName": { "type": "string", "description": "Conta dona do pedido." }, "AccountNameInvoice": { "type": "string", "description": "Conta do faturador (`IDCompanyInvoice`)." }, "CompanyCpfCnpjInvoice": { "type": "string", "description": "CNPJ do faturador." }, "OrderFrom": { "type": "string", "nullable": true, "description": "Canais de origem do pedido. Quando o pedido vem de mais de um canal, vem como lista separada por vírgula." }, "ValueOrder": { "type": "number", "description": "Valor total do pedido: soma de `PriceSellingTotal` + `ValueShipping` + `NfeAccessoryExpenses`." } } }, "DifalSummaryItem": { "type": "object", "description": "Linha da apuração DIFAL (`orderGnreList` com `Summary=1`). Uma linha por pedido com NF principal modelo 55. O sinal de `ValueOrder`, `NfeValueIcmsUfDest` e `NfeValueFcpUfDest` segue `NfeType` (positivo para `NfeType=1` saída, negativo para `NfeType=0` entrada).", "properties": { "IDOrder": { "type": "integer", "description": "Id do pedido." }, "Order": { "type": "string", "description": "Número do pedido." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de criação do pedido." }, "ConsumerNameCorporateName": { "type": "string", "description": "Nome/razão social do cliente." }, "ShippingState": { "type": "string", "description": "UF de destino." }, "NfeType": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo da NF: `0` entrada, `1` saída. Define o sinal dos valores monetários." }, "NfeNumber": { "type": "string", "nullable": true, "description": "Número da NF principal." }, "NfeSerie": { "type": "string", "nullable": true, "description": "Série da NF principal." }, "NfedhEmi": { "type": "string", "format": "date-time", "nullable": true, "description": "Emissão da NF." }, "NfeChaveAcesso": { "type": "string", "nullable": true, "description": "Chave de acesso da NF (44 dígitos)." }, "IDStatusInvoice": { "type": "integer", "nullable": true, "description": "Status numérico da NF." }, "StatusInvoice": { "type": "string", "nullable": true, "description": "Status textual da NF." }, "GnreStatusDescription": { "type": "string", "nullable": true, "description": "Status atual da guia GNRE deste pedido (`StatusDescription`); `null` quando ainda não há guia gerada." }, "CompanyIntegrationName": { "type": "string", "description": "Nome da integração de origem (`CompanyIntegrationName`)." }, "IDStatusOrder": { "type": "integer", "description": "Status numérico do pedido." }, "StatusOrder": { "type": "string", "description": "Status textual do pedido para a empresa." }, "TypeOrder": { "type": "string", "description": "Nome do tipo de pedido." }, "AccountName": { "type": "string", "description": "Conta dona do pedido." }, "AccountNameInvoice": { "type": "string", "description": "Conta do faturador." }, "CompanyCpfCnpjInvoice": { "type": "string", "description": "CNPJ do faturador." }, "ShippingDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de envio (máximo de `ShippingDate` do pedido)." }, "OrderFrom": { "type": "string", "nullable": true, "description": "Canais de origem do pedido (concatenados)." }, "ValueOrder": { "type": "number", "description": "Valor total do pedido (com sinal por `NfeType`)." }, "NfeValueIcmsUfDest": { "type": "number", "description": "Soma de `NfeIcmsUfDestValue` (DIFAL ICMS) dos itens do pedido. Sinal por `NfeType`." }, "NfeValueFcpUfDest": { "type": "number", "description": "Soma de `NfeFcpUfDestValue` (FCP) dos itens do pedido. Sinal por `NfeType`." }, "NfTpNfDescription": { "type": "string", "description": "Descrição do tipo da NFe (`NfTpNfDescription`)." } } }, "OrderEventLogItem": { "type": "object", "description": "Linha do log de pedidos (`ordersLogList`). Cada item traz o evento (`EventDescription`), o usuário que executou (`User`), o pedido (`Order`) e a conta (`Company`) já resolvidos.", "properties": { "IDOrderEvents": { "type": "integer", "description": "Id único do registro do log." }, "IDOrder": { "type": "integer", "description": "Código interno do pedido (`IDOrder`)." }, "Order": { "type": "string", "description": "Número do pedido visível ao cliente (`Order`)." }, "IDEvent": { "type": "integer", "description": "Id do tipo de ação (`IDEvent`). Ex.: `0` Pedido criado, `2` Finalizar pedido, `19` Cancelar pedido, `35` Alteração status. Catálogo em `support data/TypeOrderEvents.csv`." }, "EventDescription": { "type": "string", "description": "Texto do tipo da ação (ex.: \"Pedido criado\", \"Cancelar pedido\")." }, "Header": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "Resultado: `0` Erro/Problema, `1` Sucesso, `2` Inativo." }, "Status": { "type": "string", "enum": [ "Erro", "Sucesso", "Inativo" ], "description": "Texto correspondente ao `Header` — computado pelo `SELECT` (`Header=1 → Sucesso, 2 → Inativo, demais → Erro`)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Momento em que o evento foi gravado." }, "RecordUserCreated": { "type": "integer", "description": "Id do usuário que disparou a ação (`IDUser`)." }, "Login": { "type": "string", "description": "Identificação do usuário: `UserName - Login`; quando `UserName` é nulo/vazio, vem só `Login`." }, "Comments": { "type": "string", "nullable": true, "description": "Texto livre gravado pela operação de origem (pode trazer corpo de erro / detalhe da ação)." }, "AccountName": { "type": "string", "description": "Identificador da conta da empresa dona do pedido." } } }, "BankAccount": { "type": "object", "description": "Conta bancária da empresa.", "properties": { "IDBankAccount": { "type": "integer", "format": "int32", "description": "Identificador da conta bancária." }, "Bank": { "type": "string", "maxLength": 100, "description": "Nome do banco." }, "BankNumber": { "type": "string", "maxLength": 3, "description": "Código Febraban do banco." }, "BankRouting": { "type": "string", "maxLength": 45, "nullable": true, "description": "Agência." }, "AccountNumber": { "type": "string", "maxLength": 45, "nullable": true, "description": "Número da conta." }, "MainIncome": { "type": "integer", "format": "int32", "description": "Indica se é a conta principal de recebimento (0/1)." }, "MainPayment": { "type": "integer", "format": "int32", "description": "Indica se é a conta principal de pagamento (0/1)." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa dona da conta." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de cadastro." }, "AccountNumberDigit": { "type": "string", "maxLength": 1, "nullable": true, "description": "Dígito verificador do número da conta." }, "Status": { "type": "integer", "format": "int32", "description": "Situação da conta: 0=inativa, 1=ativa." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "description": "Identificador da empresa faturadora." }, "IDCompanyIntegration": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da integração bancária, quando houver." }, "TefTerminal": { "type": "string", "maxLength": 45, "nullable": true, "description": "Terminal TEF associado." }, "IDTypeOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de pedido associado." }, "IDCompanyIntegrationPix": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da integração de Pix vinculada à conta." } } }, "BankAccountListItem": { "allOf": [ { "$ref": "#/components/schemas/BankAccount" }, { "type": "object", "description": "Item retornado por `GET /accounts/bank-account` — campos da conta bancária acrescidos de nomes resolvidos e saldos calculados.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio (identificador) da empresa dona da conta." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Subdomínio do faturador, quando houver." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social do faturador." }, "CompanyIntegrationName": { "type": "string", "nullable": true, "description": "Nome da integração bancária, quando houver." }, "TypeOrder": { "type": "string", "nullable": true, "description": "Descrição do tipo de pedido associado, quando houver." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Texto formatado com o tipo e nome da integração bancária." }, "Balance": { "type": "number", "description": "Saldo atual da conta: soma de entradas menos saídas até o momento da consulta. Sempre numérico (zero quando não há lançamentos)." }, "BalanceForecast": { "type": "number", "description": "Saldo previsto até `DateForecast`: saldo atual mais os lançamentos previstos cuja conta de previsão é esta." }, "CompanyIntegrationPix": { "type": "string", "nullable": true, "description": "Texto formatado com o tipo e nome da integração de Pix vinculada à conta, quando houver." } } } ] }, "AccountsPayableBase": { "type": "object", "description": "Campos comuns de uma conta a pagar.", "properties": { "Comments": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Observações." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência. Quando enviada como string vazia, é tratada como ausente." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data do documento. Quando enviada como string vazia, é tratada como ausente." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento. Obrigatório." }, "DocumentNumber": { "type": "string", "maxLength": 200, "nullable": true, "description": "Número do documento." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do fornecedor. Não pode vir junto com `IDConsumer`." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do cliente. Não pode vir junto com `IDSupplier`." }, "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de pagamento." }, "IDTypeDocument": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de documento." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do plano de contas." }, "Scheduled": { "type": "integer", "format": "int32", "nullable": true, "description": "Indica se a conta está agendada para pagamento automático (0/1). Padrão 0." }, "Value": { "type": "number", "description": "Valor do título, com duas casas decimais. Pode chegar como string em alguns clientes — confirme o parse no consumidor." }, "IDBankAccountForecast": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conta bancária prevista para o pagamento." }, "BankSlipBarCode": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Código de barras do boleto." }, "ValueDiscount": { "type": "number", "nullable": true, "description": "Valor de desconto, com duas casas decimais." }, "ValueInterest": { "type": "number", "nullable": true, "description": "Valor de juros, com duas casas decimais." }, "ValuePenalty": { "type": "number", "nullable": true, "description": "Valor de multa, com duas casas decimais." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da empresa faturadora. Quando omitido, assume a empresa autenticada." }, "Forecast": { "type": "integer", "format": "int32", "description": "Indica se o título é uma previsão (0/1). Padrão 0." } } }, "TaxRetentionItem": { "type": "object", "description": "Item de retenção de imposto. Cada retenção gera uma conta a pagar filha vinculada à conta principal.", "required": [ "IDSupplier", "Value", "DateDue" ], "properties": { "IDSupplier": { "type": "integer", "format": "int32", "description": "Identificador do fornecedor da retenção." }, "Value": { "type": "number", "description": "Valor da retenção. A soma de todas as retenções é abatida do `Value` da conta principal." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento da retenção." } } }, "AccountsPayableCreate": { "allOf": [ { "$ref": "#/components/schemas/AccountsPayableBase" }, { "type": "object", "description": "Corpo do `POST /accounts/payable`. `DateDue`, `Value`, `IDTypeDocument` e `IDTypeAccountPayableReceivable` são obrigatórios na prática — quando ausentes, a criação falha.", "required": [ "DateDue", "Value", "IDTypeDocument", "IDTypeAccountPayableReceivable" ], "properties": { "IDOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do pedido associado, quando houver." }, "Taxes": { "type": "array", "description": "Retenções de imposto.", "items": { "$ref": "#/components/schemas/TaxRetentionItem" } }, "Holiday": { "type": "integer", "enum": [ 1, 2 ], "nullable": true, "description": "Como tratar feriado e fim de semana nas datas da recorrência: 1=antecipar, 2=postergar; quando omitido, não ajusta." }, "PeriodType": { "type": "integer", "enum": [ 1, 2, 3 ], "nullable": true, "description": "Tipo de recorrência: 1=mensal, 2=semanal, 3=personalizado." }, "QuantityRepeat": { "type": "integer", "nullable": true, "description": "Número total de ocorrências (incluindo a inicial)." }, "PeriodTypeValue": { "type": "integer", "nullable": true, "description": "Quando `PeriodType=1`: dia do mês (1-31). Quando `2`: dia da semana (0-6). Quando `3`: intervalo em dias entre ocorrências." } } } ] }, "AccountsPayableUpdate": { "type": "object", "description": "Corpo do `PUT /accounts/payable/{idaccountpayable}`. Todos os campos são opcionais; apenas os enviados são atualizados (comportamento de atualização parcial).", "properties": { "Comments": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Observações." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data do documento." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento." }, "DocumentNumber": { "type": "string", "maxLength": 200, "nullable": true, "description": "Número do documento." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do fornecedor. Não pode vir junto com `IDConsumer`." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do cliente. Não pode vir junto com `IDSupplier`." }, "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de pagamento." }, "IDTypeDocument": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de documento." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do plano de contas." }, "Scheduled": { "type": "integer", "format": "int32", "nullable": true, "description": "Indica se a conta está agendada (0/1)." }, "Value": { "type": "number", "description": "Valor do título." }, "IDBankAccountForecast": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conta bancária prevista para o pagamento. O valor `\"0\"` é ignorado." }, "BankSlipBarCode": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Código de barras do boleto." }, "ValueDiscount": { "type": "number", "nullable": true, "description": "Valor de desconto." }, "ValueInterest": { "type": "number", "nullable": true, "description": "Valor de juros." }, "ValuePenalty": { "type": "number", "nullable": true, "description": "Valor de multa." }, "Forecast": { "type": "integer", "format": "int32", "description": "Indica se o título é uma previsão (0/1)." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da empresa faturadora." } } }, "CashFlowSummaryItem": { "type": "object", "description": "Item do modo Resumo de `GET /accounts/cash-flow`. Cada linha consolida um plano de contas em um mês (ou dia, quando `GroupBy=day`) com o total previsto (`TotalValue`), o total realizado (`ValuePaid`) e a quantidade de lançamentos. Considera o ano inteiro definido em `Year` e exclui contas com status **Não lançado**.", "properties": { "Month": { "type": "integer", "description": "Mês do agrupamento (1–12), extraído do vencimento." }, "Year": { "type": "integer", "description": "Ano do agrupamento, extraído do vencimento." }, "Date": { "type": "string", "format": "date-time", "description": "Data sintética do início do mês do agrupamento, no fuso da API. Usada pela UI para ordenar e formatar como `MMM/yyyy`." }, "TotalValue": { "type": "number", "description": "Total **previsto** no agrupamento. Já vem assinado: contas a pagar entram negativas, contas a receber positivas." }, "TotalQty": { "type": "integer", "description": "Quantidade de títulos no agrupamento." }, "ValuePaid": { "type": "number", "description": "Total **realizado** no agrupamento — soma dos lançamentos do extrato dos títulos do grupo. Assinado do mesmo modo que `TotalValue`." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo do lançamento: `0` entrada (a receber), `1` saída (a pagar)." }, "IDTypeAccountPayableReceivable": { "type": "integer", "nullable": true, "description": "Identificador do plano de contas do agrupamento." }, "IDTypeAccountPaybleFather": { "type": "integer", "nullable": true, "description": "Identificador do plano de contas pai (quando o agrupamento é uma sub-categoria)." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas do agrupamento." }, "CategoryTree": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Caminho completo do plano de contas, da raiz até a folha (ex.: `[\"Despesas\", \"Operacionais\", \"Aluguel\"]`). Usado pela UI como níveis do pivot." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Identificador da empresa faturadora (filial) do agrupamento." } } }, "CashFlowDetailItem": { "type": "object", "description": "Item do modo Detalhe de `GET /accounts/cash-flow?Type=Detail`. Cada linha é um título individual (`AccountsPayableReceivable`) que compõe a célula do resumo. Distinto e ordenado por vencimento.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio (`accountname`) da empresa dona do título." }, "IDAccountPayableReceivable": { "type": "integer", "description": "Identificador do título." }, "IDStatusAccountPayableReceivable": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6 ], "description": "Status do título: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo, 6=Vence hoje." }, "StatusAccountPayableReceivable": { "type": "string", "description": "Descrição amigável do status (correspondente ao `IDStatusAccountPayableReceivable`)." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência do título." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento do título." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo do lançamento: `0` entrada (a receber), `1` saída (a pagar)." }, "IDTypeAccountPayableReceivable": { "type": "integer", "nullable": true, "description": "Identificador do plano de contas do título." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas do título." }, "CategoryTree": { "type": "string", "nullable": true, "description": "Caminho completo do plano de contas em texto, separado por ` -> ` (ex.: `Despesas -> Operacionais -> Aluguel`)." }, "IDTypePayment": { "type": "integer", "nullable": true, "description": "Identificador do tipo de pagamento (Boleto, PIX, etc.)." }, "TypePaymentDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo de pagamento." }, "Value": { "type": "number", "description": "Valor **previsto** do título. Já vem assinado: a pagar entra negativo, a receber positivo." }, "ValuePaid": { "type": "number", "description": "Valor **realizado** do título — soma dos lançamentos do extrato. Assinado do mesmo modo que `Value`." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Nome ou razão social do fornecedor (ou cliente, quando o título é a receber)." } } }, "AccountsPayableListItem": { "type": "object", "description": "Item retornado por `GET /accounts/payable` e `POST /accounts/payable`. Inclui campos próprios da conta, descrições resolvidas dos relacionamentos, totais já calculados em `Number` (`ValueTotal`, `ValuePaid`, `ValuePaymentPending`) e dados resumidos do banco de pagamento.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da conta." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "description": "Identificador do título." }, "IDAccountPayableReceivableMain": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conta-raiz da série de recorrência." }, "IDStatusAccountPayableReceivable": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6 ], "nullable": true, "description": "Status do título: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo, 6=Vence hoje." }, "StatusAccountPayableReceivable": { "type": "string", "nullable": true, "description": "Descrição textual do status correspondente a `IDStatusAccountPayableReceivable`." }, "Comments": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Observações." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data do documento." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento." }, "DocumentNumber": { "type": "string", "maxLength": 200, "nullable": true, "description": "Número do documento." }, "RecordTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de criação do título." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do fornecedor." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do cliente (quando o título nasce de uma devolução/estorno)." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do fornecedor ou cliente vinculado (a coluna serve aos dois conforme `IDConsumer`)." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo de conta: 0=entrada (a receber), 1=saída (a pagar)." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do plano de contas." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas." }, "IDTypeDocument": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de documento." }, "TypeDocument": { "type": "string", "nullable": true, "description": "Descrição do tipo de documento." }, "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de pagamento." }, "TypePaymentDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo de pagamento." }, "IDPurchase": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da compra (recebimento) associada." }, "IDStatusPurchase": { "type": "integer", "format": "int32", "nullable": true, "description": "Status da compra associada." }, "IDOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador interno do pedido vinculado." }, "Scheduled": { "type": "integer", "format": "int32", "nullable": true, "description": "Indica se o título está agendado para pagamento automático (0/1)." }, "Forecast": { "type": "integer", "format": "int32", "description": "Indica se o título é uma previsão (1) ou um lançamento real (0)." }, "BankSlipBarCode": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Código de barras do boleto." }, "IDBankAccountForecast": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conta bancária prevista para o pagamento." }, "BankForecast": { "type": "string", "nullable": true, "description": "Nome do banco da conta prevista, eventualmente concatenado com o número da conta." }, "BankForecastAccountNumber": { "type": "string", "nullable": true, "description": "Número da conta bancária prevista." }, "BankPayment": { "type": "string", "nullable": true, "description": "Bancos onde os pagamentos foram lançados (lista concatenada quando há múltiplos)." }, "DateLastPayment": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora do último pagamento lançado." }, "Value": { "type": "number", "description": "Valor base do título (já convertido para número; zero quando inválido)." }, "ValueDiscount": { "type": "number", "description": "Valor de desconto (zero quando inválido)." }, "ValueInterest": { "type": "number", "description": "Valor de juros (zero quando inválido)." }, "ValuePenalty": { "type": "number", "description": "Valor de multa (zero quando inválido)." }, "ValueTotal": { "type": "number", "description": "Valor total efetivo: `Value + ValuePenalty + ValueInterest - ValueDiscount`." }, "ValuePaid": { "type": "number", "description": "Soma dos pagamentos já lançados." }, "ValuePaymentPending": { "type": "number", "description": "Saldo devedor: `ValueTotal - ValuePaid`." }, "TotalvNF": { "type": "number", "nullable": true, "description": "Valor total da nota fiscal de origem, quando a conta está vinculada a uma compra." }, "DocumentPdf": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se há arquivo PDF anexado." }, "DocumentXml": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se há arquivo XML anexado." }, "DocumentBankSlip": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se há boleto anexado." }, "DocumentPayment": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se há comprovante de pagamento anexado." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da empresa faturadora." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Subdomínio da empresa faturadora." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social da empresa faturadora." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Texto formatado com o tipo e nome da integração." }, "AccountsPayableReceivableCostCenter": { "type": "string", "nullable": true, "description": "Descrições dos centros de custo vinculados ao título, concatenadas e separadas por vírgula (ex.: \"Administrativo, Marketing\"). `null` quando o título não tem centro de custo vinculado." } } }, "AccountsPayableDetail": { "type": "object", "description": "Resposta detalhada do `GET /accounts/payable/{idaccountpayable}` (também o corpo do `PUT` após atualização). Inclui campos próprios da conta, descrições resolvidas dos relacionamentos (fornecedor, cliente, tipo de documento, tipo de pagamento, plano de contas) e listas auxiliares de arquivos, pagamentos, histórico e centros de custo. Campos vindos de relacionamentos opcionais podem ser nulos quando não há vínculo.", "properties": { "Comments": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Observações." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data do documento." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento." }, "DocumentNumber": { "type": "string", "maxLength": 200, "nullable": true, "description": "Número do documento." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "description": "Identificador da conta a pagar." }, "IDStatusAccountPayableReceivable": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6 ], "nullable": true, "description": "Status do título: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo, 6=Vence hoje. Padrão 0." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do fornecedor." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo de conta: 0=entrada (a receber), 1=saída (a pagar)." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do plano de contas." }, "IDTypeDocument": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de documento." }, "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de pagamento." }, "RecordTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de criação." }, "Scheduled": { "type": "integer", "format": "int32", "nullable": true, "description": "Indica se a conta está agendada (0/1)." }, "Value": { "type": "number", "description": "Valor do título, já convertido para número (zero quando inválido)." }, "IDBankAccountForecast": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conta bancária prevista." }, "IDOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do pedido associado." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da empresa faturadora." }, "IDAccountPayableReceivableMain": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conta-raiz da série de recorrência." }, "StatusAccountPayableReceivable": { "type": "string", "nullable": true, "description": "Descrição textual do status." }, "BankSlipBarCode": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Código de barras do boleto." }, "Forecast": { "type": "integer", "format": "int32", "description": "Indica se o título é uma previsão (0/1)." }, "ValueDiscount": { "type": "number", "description": "Valor de desconto (zero quando inválido)." }, "ValueInterest": { "type": "number", "description": "Valor de juros (zero quando inválido)." }, "ValuePenalty": { "type": "number", "description": "Valor de multa (zero quando inválido)." }, "ValueTotal": { "type": "number", "description": "Valor total efetivo: `Value + ValuePenalty + ValueInterest - ValueDiscount`." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas." }, "TypeDocument": { "type": "string", "nullable": true, "description": "Descrição do tipo de documento." }, "TypePaymentDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo de pagamento." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do fornecedor." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do cliente." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do cliente." }, "DocumentPdf": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se há arquivo PDF anexado." }, "DocumentXml": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se há arquivo XML anexado." }, "DocumentBankSlip": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se há boleto anexado." }, "DocumentPayment": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se há comprovante de pagamento anexado." }, "TotalvNF": { "type": "number", "nullable": true, "description": "Valor total da nota fiscal de origem, quando a conta está vinculada a uma compra." }, "Bank": { "type": "string", "nullable": true, "description": "Nome do banco da conta de previsão, podendo vir concatenado com o número da conta." }, "BankForecastAccountNumber": { "type": "string", "nullable": true, "description": "Número da conta bancária de previsão." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Subdomínio da empresa faturadora." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social da empresa faturadora." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Texto formatado com o tipo e nome da integração." }, "Files": { "type": "array", "description": "Arquivos anexados à conta. Inclui GNREs (quando houver) e demais arquivos (PDF, XML, boleto, comprovante).", "items": { "$ref": "#/components/schemas/FileAttachment" } }, "Payments": { "type": "array", "description": "Lançamentos do extrato bancário vinculados a esta conta.", "items": { "$ref": "#/components/schemas/BankStatementPayment" } }, "AccountsPayableReceivableLog": { "type": "array", "description": "Histórico de alterações da conta, em ordem decrescente de data.", "items": { "$ref": "#/components/schemas/AccountsPayableLogEntry" } }, "AccountsPayableReceivableCostCenter": { "type": "array", "description": "Centros de custo com o valor rateado a partir do total da conta.", "items": { "$ref": "#/components/schemas/AccountsPayableCostCenter" } }, "RelatedAccountsPayableReceivable": { "type": "array", "nullable": true, "description": "Contas filhas geradas por retenção de impostos, com totais já calculados.", "items": { "$ref": "#/components/schemas/RelatedAccountsPayable" } } } }, "FileAttachment": { "type": "object", "description": "Arquivo anexado a uma conta a pagar. Pode representar uma GNRE ou um arquivo comum (PDF, XML, boleto, comprovante de pagamento). As ramificações compartilham as chaves abaixo, com algumas variações nos identificadores.", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora do anexo." }, "IDFile": { "type": "integer", "format": "int32", "description": "Identificador do arquivo. Para GNREs, é igual ao `IDGnre`." }, "IDTypeFile": { "type": "string", "description": "Identificador do tipo de arquivo, como string. Para GNRE, vem fixado como `\"1\"`; para os demais, corresponde ao tipo cadastrado." }, "TypeFile": { "type": "string", "description": "Descrição do tipo de arquivo. `\"GNRE\"` para guia GNRE; para os demais, o nome do tipo cadastrado." }, "FileUrl": { "type": "string", "description": "URL completa para baixar o arquivo, já com token de acesso embutido." }, "IDGnre": { "type": "integer", "format": "int32", "description": "Identificador da GNRE. Presente apenas em itens do tipo GNRE." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "description": "Identificador da conta a pagar dona do arquivo. Presente apenas em itens que não são GNRE." } } }, "BankStatementPayment": { "type": "object", "description": "Lançamento do extrato bancário vinculado a uma conta a pagar.", "properties": { "DateTransactionTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora da transação (formato ISO 8601 com sufixo Z)." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Identificador da conta bancária onde o lançamento foi registrado." }, "IDBankStatement": { "type": "integer", "format": "int32", "description": "Identificador do lançamento no extrato." }, "TransactionDescription": { "type": "string", "maxLength": 100, "nullable": true, "description": "Descrição da transação." }, "TransactionDocument": { "type": "string", "maxLength": 45, "nullable": true, "description": "Documento da transação (TID, NSU ou similar)." }, "Value": { "type": "number", "description": "Valor lançado, com duas casas decimais." }, "Bank": { "type": "string", "description": "Nome do banco da conta onde a transação foi registrada." } } }, "AccountsPayableLogEntry": { "type": "object", "description": "Entrada do histórico de alterações de uma conta a pagar.", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora da alteração (formato ISO 8601 com sufixo Z)." }, "IDAccountsPayableReceivableLog": { "type": "integer", "format": "int32", "description": "Identificador da entrada do histórico." }, "RecordUserCreated": { "type": "integer", "format": "int32", "description": "Identificador do usuário responsável pela alteração." }, "Data": { "type": "string", "maxLength": 500, "nullable": true, "description": "Resumo da alteração em formato `chave: \"DE: PARA: \"` (string JSON serializada com os campos modificados)." }, "Login": { "type": "string", "description": "Login do usuário que fez a alteração." } } }, "AccountsPayableCostCenter": { "type": "object", "description": "Centro de custo associado a uma conta a pagar, com a fração rateada do valor total.", "properties": { "IDTypeCostCenter": { "type": "integer", "format": "int32", "description": "Identificador do tipo de centro de custo." }, "ValueRatio": { "type": "number", "description": "Fração do valor total alocada a este centro de custo (decimal com 4 casas, ex.: `0.3500` = 35%)." }, "TypeCostCenter": { "type": "string", "maxLength": 100, "description": "Nome do centro de custo." }, "ExternalCode": { "type": "string", "maxLength": 45, "nullable": true, "description": "Código externo do centro de custo, quando integrado a um sistema contábil." }, "Value": { "type": "number", "description": "Valor alocado a este centro: `ValueTotal × ValueRatio`, arredondado para 2 casas decimais." } } }, "RelatedAccountsPayable": { "type": "object", "description": "Conta filha gerada por retenção de impostos. Resume os campos da conta filha já com totais calculados.", "properties": { "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "description": "Identificador da conta filha." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data do documento." }, "DocumentNumber": { "type": "string", "maxLength": 200, "nullable": true, "description": "Número do documento." }, "IDStatusAccountPayableReceivable": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6 ], "nullable": true, "description": "Status do título: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo, 6=Vence hoje." }, "StatusAccountPayableReceivable": { "type": "string", "nullable": true, "description": "Descrição textual do status." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do cliente, quando aplicável." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do cliente." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do fornecedor, quando aplicável." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do fornecedor." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo de conta: 0=entrada (a receber), 1=saída (a pagar)." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas." }, "Value": { "type": "number", "description": "Valor base do título (zero quando inválido)." }, "ValueDiscount": { "type": "number", "description": "Valor de desconto (zero quando inválido)." }, "ValueInterest": { "type": "number", "description": "Valor de juros (zero quando inválido)." }, "ValuePenalty": { "type": "number", "description": "Valor de multa (zero quando inválido)." }, "ValueTotal": { "type": "number", "description": "Valor total efetivo: `Value + ValuePenalty + ValueInterest - ValueDiscount`." } } }, "BankAccountCreate": { "type": "object", "description": "Corpo do `POST /accounts/bank-account`.", "required": [ "Bank", "BankNumber" ], "properties": { "Bank": { "type": "string", "maxLength": 100, "description": "Nome do banco." }, "BankNumber": { "type": "string", "maxLength": 3, "description": "Código Febraban." }, "BankRouting": { "type": "string", "maxLength": 45, "nullable": true, "description": "Agência." }, "AccountNumber": { "type": "string", "maxLength": 45, "nullable": true, "description": "Número da conta." }, "AccountNumberDigit": { "type": "string", "maxLength": 1, "nullable": true, "description": "Dígito verificador do número da conta." }, "MainIncome": { "type": "integer", "enum": [ 0, 1 ], "description": "Conta principal de recebimento (0/1). Padrão 0. Quando 1, qualquer outra conta da mesma empresa/faturador é automaticamente desmarcada." }, "MainPayment": { "type": "integer", "enum": [ 0, 1 ], "description": "Conta principal de pagamento (0/1). Padrão 0. Quando 1, qualquer outra conta da mesma empresa/faturador é automaticamente desmarcada." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da empresa faturadora. Quando omitido, assume a empresa autenticada." }, "IDCompanyIntegration": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da integração bancária. Validado contra os cadastros da empresa." }, "IDCompanyIntegrationPix": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da integração de Pix vinculada à conta. Validado contra os cadastros da empresa." }, "IDTypeOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de pedido. Só faz sentido quando o tipo está habilitado para frente de caixa e pertence ao mesmo faturador da conta." }, "TefTerminal": { "type": "string", "maxLength": 45, "nullable": true, "description": "Terminal TEF associado." } } }, "BankAccountUpdate": { "type": "object", "description": "Corpo do `PUT /accounts/bank-account/{idbankaccount}`. Todos os campos são opcionais — só os enviados são atualizados. Para ativar o modo de **ajuste de saldo inicial**, envie `InitialBalance` e `InitialBalanceDate`; nesse modo, os campos de cadastro são ignorados.", "properties": { "Bank": { "type": "string", "maxLength": 100, "description": "Nome do banco." }, "BankNumber": { "type": "string", "maxLength": 3, "description": "Código Febraban. Não pode ser alterado quando a conta atual é interna (`000`) e existe caixa aberto vinculado." }, "BankRouting": { "type": "string", "maxLength": 45, "nullable": true, "description": "Agência." }, "AccountNumber": { "type": "string", "maxLength": 45, "nullable": true, "description": "Número da conta." }, "AccountNumberDigit": { "type": "string", "maxLength": 1, "nullable": true, "description": "Dígito verificador do número da conta." }, "MainIncome": { "type": "integer", "enum": [ 0, 1 ], "description": "Conta principal de recebimento (0/1). Quando 1, qualquer outra conta da mesma empresa/faturador é automaticamente desmarcada." }, "MainPayment": { "type": "integer", "enum": [ 0, 1 ], "description": "Conta principal de pagamento (0/1). Quando 1, qualquer outra conta da mesma empresa/faturador é automaticamente desmarcada." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "description": "Identificador da empresa faturadora. Quando omitido, assume a empresa autenticada." }, "IDCompanyIntegration": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da integração bancária. Validado contra os cadastros da empresa." }, "IDCompanyIntegrationPix": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da integração de Pix vinculada à conta. Validado contra os cadastros da empresa." }, "IDTypeOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de pedido. Só faz sentido quando o tipo está habilitado para frente de caixa e pertence ao mesmo faturador da conta." }, "TefTerminal": { "type": "string", "maxLength": 45, "nullable": true, "description": "Terminal TEF associado." }, "InitialBalance": { "type": "number", "description": "Saldo final desejado para a conta na data informada. Quando enviado junto com `InitialBalanceDate`, ativa o modo de ajuste de saldo (os demais campos são ignorados)." }, "InitialBalanceDate": { "type": "string", "format": "date", "description": "Data de referência para o ajuste de saldo. O lançamento de ajuste é gravado no dia anterior, às 23:59:59." } } }, "Brand": { "type": "object", "description": "Cadastro de marca.", "properties": { "IDBrand": { "type": "integer", "format": "int32", "description": "Identificador da marca." }, "Name": { "type": "string", "maxLength": 300, "description": "Nome da marca." }, "Description": { "type": "string", "maxLength": 300, "nullable": true, "description": "Descrição. Quando ausente no POST, herda o `Name`." }, "Keywords": { "type": "string", "maxLength": 500, "nullable": true, "description": "Palavras-chave para busca. Quando ausente no POST, herda o `Name`." }, "Title": { "type": "string", "maxLength": 300, "nullable": true, "description": "Título para exibição. Quando ausente no POST, herda o `Name`." }, "IsActive": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se a marca está ativa para uso em produtos. Padrão 1." }, "MenuHome": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se aparece em destaque no menu inicial. Padrão 0." }, "Score": { "type": "integer", "nullable": true, "description": "Pontuação manual para ordenação ou destaque." }, "RecordTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de cadastro." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "Situação: 0=inativa (excluída logicamente), 1=ativa." } } }, "BrandListItem": { "type": "object", "description": "Item de `GET /brand`. Versão resumida do cadastro de marca, com a empresa dona e um campo textual de status pronto para exibição.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da marca." }, "IDBrand": { "type": "integer", "format": "int32", "description": "Identificador da marca." }, "Name": { "type": "string", "maxLength": 300, "description": "Nome da marca." }, "IsActive": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se a marca está ativa para uso em produtos." }, "Status": { "type": "string", "enum": [ "Ativo", "Inativo" ], "description": "Texto pronto para exibição derivado de `IsActive`." } } }, "BrandCreate": { "type": "object", "description": "Corpo do `POST /brand`. Apenas `Name` é efetivamente exigido — os demais campos textuais herdam `Name` quando ausentes ou vazios.", "required": [ "Name" ], "properties": { "Name": { "type": "string", "maxLength": 300, "description": "Nome da marca." }, "Description": { "type": "string", "maxLength": 300, "nullable": true, "description": "Descrição da marca (rich text na UI). Quando ausente ou vazio, herda o valor de `Name`." }, "Keywords": { "type": "string", "maxLength": 500, "nullable": true, "description": "Palavras-chave para busca/SEO da marca. Quando ausente ou vazio, herda o valor de `Name`." }, "Title": { "type": "string", "maxLength": 300, "nullable": true, "description": "Título exibido em cabeçalho de página/SEO da marca. Quando ausente ou vazio, herda o valor de `Name`." }, "IsActive": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se a marca está ativa para uso em produtos (0/1). Padrão 1." }, "MenuHome": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se aparece em destaque no menu inicial (0/1). Padrão 0." }, "Score": { "type": "integer", "nullable": true, "description": "Pontuação manual para ordenação ou destaque (tinyint -128..127). Quando ausente ou vazio, fica `null`." } } }, "BrandUpdate": { "type": "object", "description": "Corpo do `PUT /brand/{idbrand}`. Todos os campos são opcionais — apenas os enviados são atualizados.", "properties": { "Name": { "type": "string", "maxLength": 300, "description": "Nome da marca." }, "Description": { "type": "string", "maxLength": 300, "nullable": true, "description": "Descrição da marca." }, "Keywords": { "type": "string", "maxLength": 500, "nullable": true, "description": "Palavras-chave para busca." }, "Title": { "type": "string", "maxLength": 300, "nullable": true, "description": "Título para exibição." }, "IsActive": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se a marca está ativa para uso em produtos (0/1)." }, "MenuHome": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se aparece em destaque no menu inicial (0/1)." }, "Score": { "type": "integer", "nullable": true, "description": "Pontuação manual para ordenação ou destaque." } } }, "BankStatementInternalResponse": { "type": "object", "description": "Resposta do `GET /accounts/bank-statement` no modo `Source=1` (extrato interno). Apresenta saldo anterior, lançamentos linha a linha com saldo corrente, totais por tipo e saldo final.", "properties": { "IDBankAccount": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conta consultada (eco do filtro)." }, "PeriodStart": { "type": "string", "nullable": true, "description": "Início do período (ISO 8601 com hora, eco normalizado de `DateFrom`)." }, "PeriodEnd": { "type": "string", "nullable": true, "description": "Fim do período (ISO 8601 com hora, eco normalizado de `DateTo`)." }, "AccountName": { "type": "string", "nullable": true, "description": "Subdomínio da empresa dona da conta. Nulo quando não há lançamentos." }, "PreviousBalance": { "type": "number", "description": "Saldo acumulado antes do início do período." }, "Entries": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementInternalEntry" }, "description": "Lançamentos do período, em ordem cronológica, com saldo corrente." }, "Receivables": { "type": "number", "description": "Total de entradas no período." }, "Payables": { "type": "number", "description": "Total de saídas no período." }, "FinalBalance": { "type": "number", "description": "Saldo final: `PreviousBalance + Receivables - Payables`." } } }, "BankStatementInternalEntry": { "type": "object", "description": "Lançamento do extrato interno, com saldo corrente após o lançamento.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da conta bancária." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária em que o lançamento interno foi registrado." }, "IDBankStatement": { "type": "integer", "format": "int32", "description": "Identificador do lançamento." }, "TransactionDate": { "type": "string", "format": "date", "nullable": true, "description": "Data da transação (`YYYY-MM-DD`)." }, "Document": { "type": "string", "nullable": true, "description": "Documento: número do título, quando conciliado; senão, `TransactionDocument`." }, "Description": { "type": "string", "nullable": true, "description": "Descrição: observação do título, quando conciliado; senão, `TransactionDescription`." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo do lançamento: 0=entrada, 1=saída." }, "Value": { "type": "number", "description": "Valor com sinal aplicado: positivo para entrada, negativo para saída." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Fornecedor da conta a pagar baixada. Vazio quando o lançamento se refere a conta a receber." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do fornecedor. Vazio quando não é conta a pagar." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Cliente da conta a receber baixada. Vazio quando o lançamento se refere a conta a pagar." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do cliente. Vazio quando não é conta a receber." }, "BankName": { "type": "string", "nullable": true, "description": "Bancos onde o lançamento foi registrado (lista concatenada por `|`)." }, "Balance": { "type": "number", "description": "Saldo corrente após este lançamento." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do título conciliado, quando houver." } } }, "BankStatementConciliationEntry": { "type": "object", "description": "Item da resposta do `GET /accounts/bank-statement` no modo `Source=2` (extrato bancário). Cada item é uma conciliação bancária com a lista de contas internas que a casam.", "properties": { "IDBankStatementConciliation": { "type": "integer", "format": "int32", "description": "Identificador da conciliação bancária (linha do extrato importado que está sendo conciliada)." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária do extrato." }, "TransactionDate": { "type": "string", "nullable": true, "description": "Data da transação no banco.", "format": "date" }, "BankTransactionID": { "type": "string", "nullable": true, "description": "Identificador da transação no banco (quando o banco fornece)." }, "Comments": { "type": "string", "nullable": true, "description": "Descrição da transação no banco." }, "BankValue": { "type": "number", "description": "Valor da transação no banco." }, "BankName": { "type": "string", "description": "Banco e número da conta, concatenados." }, "IDTypeStatusConciliation": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do status de conciliação.", "enum": [ 1, 2, 3, 4 ] }, "StatusDescription": { "type": "string", "nullable": true, "description": "Descrição do status de conciliação." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo do lançamento: 0=entrada, 1=saída." }, "InternalAccounts": { "type": "array", "items": { "$ref": "#/components/schemas/BankStatementConciliationInternal" }, "description": "Lançamentos internos vinculados a esta conciliação." }, "ERPValueTotal": { "type": "number", "description": "Soma dos valores dos lançamentos internos vinculados." }, "Difference": { "type": "number", "description": "`ERPValueTotal - BankValue`. Zero indica conciliação exata." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Empresa dona da conta bancária." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Filial faturadora vinculada quando o lançamento é segregado por empresa faturadora (ambientes multi-empresa). Vazio quando não se aplica." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social do faturador da conta bancária." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da conta." } } }, "BankStatementConciliationInternal": { "type": "object", "description": "Lançamento interno do idworks vinculado a uma conciliação bancária. Este schema mescla dois formatos do sistema `bankStatementList`:\n\n- **Modo `Source=2`** (item de `InternalAccounts[]` em `BankStatementConciliationEntry`) — devolve apenas `IDBankStatement`, `IDAccountPayableReceivable`, `Description`, `Document`, `Value`, `IDTypeAccount` (6 campos).\n- **Modo `Source=1` com `IDBankStatementConciliation`** — devolve `IDBankStatement`, `DateDue`, `IDSupplier`, `SupplierNameCorporateName`, `IDConsumer`, `ConsumerNameCorporateName`, `ValueTotal`, `TypePaymentDescription`, `TypeAccountPaybleDescription`, `BankForecast`, `BankPayment`, `StatusAccountPayableReceivable`, `IDAccountPayableReceivable`, `AccountName`, `IDTypeAccount`.\n\nCada description de campo abaixo indica em qual modo o campo é retornado.", "properties": { "IDBankStatement": { "type": "integer", "format": "int32", "description": "Identificador do lançamento interno (`AccountsPayableReceivableBankStatement`) — a baixa de uma conta a pagar ou receber registrada no sistema, candidata a casar com a linha do extrato bancário." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Título a pagar ou receber associado, quando houver." }, "Description": { "type": "string", "nullable": true, "description": "Descrição da transação interna. Presente apenas no modo `Source=2` (`InternalAccounts[]` dentro de `BankStatementConciliationEntry`)." }, "Document": { "type": "string", "nullable": true, "description": "Documento da transação interna. Presente apenas no modo `Source=2`." }, "Value": { "type": "number", "description": "Valor do lançamento interno (sempre positivo). Presente apenas no modo `Source=2` — no modo `Source=1` use `ValueTotal`." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo do lançamento: 0=entrada, 1=saída." }, "DateDue": { "type": "string", "format": "date", "nullable": true, "description": "Vencimento do título. Presente apenas no modo `Source=1` com `IDBankStatementConciliation`." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Fornecedor da conta a pagar associada. Vazio quando a baixa é de uma conta a receber. Presente apenas no modo `Source=1` com `IDBankStatementConciliation`." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do fornecedor. Vazio quando não é conta a pagar. Presente apenas no modo `Source=1` com `IDBankStatementConciliation`." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Cliente da conta a receber associada. Vazio quando a baixa é de uma conta a pagar. Presente apenas no modo `Source=1` com `IDBankStatementConciliation`." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do cliente. Vazio quando não é conta a receber. Presente apenas no modo `Source=1` com `IDBankStatementConciliation`." }, "ValueTotal": { "type": "number", "description": "Valor com sinal aplicado. Positivo para entrada, negativo para saída. Presente apenas no modo `Source=1` com `IDBankStatementConciliation`." }, "TypePaymentDescription": { "type": "string", "nullable": true, "description": "Descrição da forma de pagamento (ex.: `Boleto`, `Pix`, `Cartão de crédito`, `Transferência`). Presente apenas no modo `Source=1` com `IDBankStatementConciliation`." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas (categoria contábil). Presente apenas no modo `Source=1` com `IDBankStatementConciliation`." }, "BankForecast": { "type": "string", "nullable": true, "description": "Banco da conta prevista do título. Presente apenas no modo `Source=1` com `IDBankStatementConciliation`." }, "BankPayment": { "type": "string", "nullable": true, "description": "Banco do lançamento de pagamento. Presente apenas no modo `Source=1` com `IDBankStatementConciliation`." }, "StatusAccountPayableReceivable": { "type": "string", "nullable": true, "description": "Descrição do status atual (ex.: `Aberto`, `Pago`, `Recebido`, `Cancelado`, `Parcialmente baixado`). Presente apenas no modo `Source=1` com `IDBankStatementConciliation`." }, "AccountName": { "type": "string", "nullable": true, "description": "Subdomínio (conta) da empresa dona da baixa. Útil em ambiente multi-empresa. Presente apenas no modo `Source=1` com `IDBankStatementConciliation`." } } }, "SupplierDetail": { "type": "object", "description": "Cadastro completo de um fornecedor ou transportadora. Inclui os campos próprios do cadastro, descrições resolvidas dos relacionamentos, campos calculados (`SupplierType`, `CarrierRateUploadStatusDescription`) e listas auxiliares de contatos, faixas SRO dos Correios, uploads de tabela de frete e centros de custo. Campos com prefixo `Carrier*` ou que envolvem `CorreiosSRO` são preenchidos apenas quando o fornecedor opera como transportadora.", "properties": { "IDSupplier": { "type": "integer", "format": "int32", "description": "Identificador do fornecedor." }, "SupplierNameCorporateName": { "type": "string", "maxLength": 100, "description": "Nome ou razão social." }, "SupplierTradeName": { "type": "string", "maxLength": 60, "nullable": true, "description": "Nome fantasia." }, "SupplierCpfCnpj": { "type": "string", "maxLength": 14, "nullable": true, "description": "CPF (11 dígitos) ou CNPJ (14 dígitos), somente números." }, "SupplierType": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "description": "Tipo do fornecedor: `1` Produto, `2` Transportadora, `3` Pessoal, `4` Serviço, `5` Insumo, `6` Governo, `7` Transportadora p/ Devoluções, `8` Operador logístico, `9` Outros." }, "SupplierStateInscription": { "type": "string", "maxLength": 14, "nullable": true, "description": "Inscrição estadual." }, "SupplierCityInscription": { "type": "string", "maxLength": 14, "nullable": true, "description": "Inscrição municipal." }, "SupplierIdentityNumber": { "type": "string", "maxLength": 45, "nullable": true, "description": "Documento de identidade (pessoa física)." }, "SupplierBirthDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de nascimento (pessoa física)." }, "IDSupplierCivilStatus": { "type": "integer", "format": "int32", "nullable": true, "description": "Estado civil do fornecedor pessoa física: `1` Solteiro(a), `2` Casado(a), `3` Divorciado(a), `4` Viúvo(a), `5` União Estável, `6` Outros.", "enum": [ 1, 2, 3, 4, 5, 6 ] }, "TypeCivilStatusName": { "type": "string", "nullable": true, "description": "Descrição do estado civil." }, "SupplierTelephone": { "type": "string", "maxLength": 50, "nullable": true, "description": "Telefone principal." }, "SupplierEmail": { "type": "string", "maxLength": 45, "nullable": true, "description": "E-mail principal." }, "SupplierLogoUrl": { "type": "string", "maxLength": 500, "nullable": true, "description": "URL do logotipo." }, "ShippingPostalCode": { "type": "string", "maxLength": 10, "nullable": true, "description": "CEP." }, "ShippingStreet": { "type": "string", "maxLength": 45, "nullable": true, "description": "Logradouro." }, "ShippingNumber": { "type": "string", "maxLength": 60, "nullable": true, "description": "Número." }, "ShippingComplement": { "type": "string", "maxLength": 60, "nullable": true, "description": "Complemento." }, "ShippingNeighborhood": { "type": "string", "maxLength": 60, "nullable": true, "description": "Bairro." }, "ShippingCity": { "type": "string", "maxLength": 60, "nullable": true, "description": "Cidade." }, "ShippingState": { "type": "string", "maxLength": 2, "nullable": true, "description": "Sigla da unidade federativa." }, "IDSupplierCategory": { "type": "integer", "format": "int32", "description": "Identificador da categoria do fornecedor." }, "CategoryDescription": { "type": "string", "nullable": true, "description": "Descrição da categoria." }, "IDTypeSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de fornecedor (vinculado à categoria)." }, "TypeSupplier": { "type": "string", "nullable": true, "description": "Descrição do tipo de fornecedor." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Plano de contas padrão para títulos gerados deste fornecedor." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas padrão." }, "BankCode": { "type": "string", "maxLength": 3, "nullable": true, "description": "Código Febraban do banco do fornecedor." }, "Bank": { "type": "string", "nullable": true, "description": "Nome do banco correspondente ao `BankCode`." }, "BankAgency": { "type": "string", "maxLength": 45, "nullable": true, "description": "Agência." }, "BankCheckingAccount": { "type": "string", "maxLength": 45, "nullable": true, "description": "Conta corrente." }, "BankCheckingAccountType": { "type": "integer", "format": "int32", "nullable": true, "description": "Tipo de conta bancária." }, "PixKey": { "type": "string", "maxLength": 300, "nullable": true, "description": "Chave Pix." }, "SupplierPIS": { "type": "string", "maxLength": 45, "nullable": true, "description": "PIS do fornecedor (pessoa física)." }, "Comments": { "type": "string", "maxLength": 5000, "nullable": true, "description": "Observações." }, "DefaultPurchase": { "type": "integer", "format": "int32", "nullable": true, "description": "Marca o fornecedor como padrão para novas compras." }, "SupplierProductLeadTimeDays": { "type": "integer", "format": "int32", "nullable": true, "description": "Lead time padrão de entrega de produtos, em dias." }, "SupplierProductReliability": { "type": "integer", "format": "int32", "nullable": true, "description": "Avaliação de confiabilidade do fornecedor." }, "IDCompanyIntegration": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da integração da empresa associada." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Texto formatado com o tipo e nome da integração." }, "IDCompanyLabel": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do template de etiqueta usado pelo fornecedor." }, "LabelName": { "type": "string", "nullable": true, "description": "Nome do template de etiqueta." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do cadastro." }, "SupplierStatus": { "type": "integer", "enum": [ 0, 1 ], "description": "Situação do cadastro: 1=ativo. (Apenas registros ativos são retornados — campo presente por compatibilidade.)" }, "IDCarrierType": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de transportadora (quando o fornecedor opera como transportadora)." }, "TypeCarrier": { "type": "string", "nullable": true, "description": "Descrição do tipo de transportadora." }, "CarrierLogoUrl": { "type": "string", "nullable": true, "description": "URL do logotipo da transportadora." }, "IDTypeCompanyIntegration": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de integração da transportadora." }, "IDCarrierGateway": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do gateway de cotação." }, "CarrierGateway": { "type": "string", "nullable": true, "description": "Descrição do gateway de cotação." }, "IDCarrierModal": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do modal de transporte." }, "CarrierModal": { "type": "string", "nullable": true, "description": "Descrição do modal de transporte." }, "CarrierLabelType": { "type": "integer", "format": "int32", "nullable": true, "description": "Tipo da etiqueta da transportadora." }, "CarrierShippingIdRule": { "type": "string", "maxLength": 200, "nullable": true, "description": "Regra para o identificador de envio." }, "CarrierAuction": { "type": "integer", "format": "int32", "nullable": true, "description": "Indica se a transportadora participa de leilão de cotação." }, "CarrierAuctionPenalty": { "type": "number", "nullable": true, "description": "Penalidade aplicada à transportadora no leilão." }, "CarrierAdditionalBusinessDays": { "type": "integer", "format": "int32", "nullable": true, "description": "Dias úteis adicionais aplicados ao prazo." }, "CarrierShippingCutTime": { "type": "string", "nullable": true, "description": "Horário de corte para envio no mesmo dia (formato `HH:MM:SS`)." }, "CarrierICMSIncluded": { "type": "integer", "format": "int32", "nullable": true, "description": "Indica se o ICMS já está incluído no frete cotado." }, "CarrierCubageKmM": { "type": "integer", "format": "int32", "nullable": true, "description": "Fator de cubagem em quilos por metro cúbico." }, "CarrierCubageFreeWeight": { "type": "number", "nullable": true, "description": "Peso livre considerado antes de aplicar cubagem." }, "CarrierPriceRounding": { "type": "number", "nullable": true, "description": "Arredondamento aplicado ao preço final do frete." }, "CarrierOrdersLimitPerCollection": { "type": "integer", "format": "int32", "nullable": true, "description": "Limite de pedidos por coleta." }, "CarrierCollectionListEmail": { "type": "string", "maxLength": 500, "nullable": true, "description": "E-mails que recebem a lista de coleta (separados por vírgula)." }, "CarrierQuotationExternalId": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador externo usado na cotação." }, "CarrierRateUploadStatus": { "type": "integer", "enum": [ 0, 1, 2, 3 ], "nullable": true, "description": "Situação do último upload de tabela de frete: 0=pendente, 1=sucesso, 2=erro, 3=processando." }, "CarrierRateUploadStatusDescription": { "type": "string", "enum": [ "Sucesso", "Erro", "Processando" ], "nullable": true, "description": "Texto pronto para exibição derivado de `CarrierRateUploadStatus`. Nulo quando o status é pendente." }, "ContentDeclarationStates": { "type": "array", "items": { "type": "string", "maxLength": 2 }, "description": "Siglas das unidades federativas em que a transportadora exige declaração de conteúdo. Array vazio quando não exige em nenhuma." }, "PrintDanfe": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se a transportadora imprime DANFE junto com a etiqueta." }, "PrintDanfeA4": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se a impressão da DANFE é em A4." }, "ManualLabel": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se a etiqueta é gerada manualmente." }, "IgnoreCollectionList": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se a transportadora deve ser excluída da lista de coleta." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de cadastro." }, "Contacts": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierContact" }, "description": "Contatos cadastrados para o fornecedor." }, "CorreiosSRO": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierCorreiosSroRange" }, "description": "Faixas de números de SRO dos Correios disponíveis para a transportadora." }, "CarrierTableUpload": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierCarrierTableUpload" }, "description": "Uploads de tabela de frete, do mais recente para o mais antigo. O primeiro item é marcado como `Main = 1` (vigente)." }, "SuppliersCostCenter": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierCostCenterAllocation" }, "description": "Rateio padrão por centro de custo aplicado aos títulos gerados." }, "LabelAndDanfeSamePage": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` inclui os dados fiscais na mesma página da etiqueta; `0` não inclui." } } }, "SupplierContact": { "type": "object", "description": "Contato do fornecedor.", "properties": { "IDSuppliersContact": { "type": "integer", "format": "int32", "description": "Identificador do contato cadastrado para o fornecedor (uma linha por pessoa/telefone/e-mail no cadastro)." }, "ContactName": { "type": "string", "nullable": true, "description": "Nome do contato." }, "ContactEmail": { "type": "string", "nullable": true, "description": "E-mail." }, "ContactTelephone": { "type": "string", "nullable": true, "description": "Telefone." }, "ContactResponsability": { "type": "string", "nullable": true, "description": "Cargo ou área de responsabilidade." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de cadastro do contato." } } }, "SupplierCorreiosSroRange": { "type": "object", "description": "Faixa de números de SRO (rastreio) dos Correios disponível para a transportadora.", "properties": { "IDCorreiosSroRange": { "type": "integer", "format": "int32", "description": "Identificador da faixa de etiquetas SRO (Sistema de Rastreamento de Objetos) dos Correios alocada ao fornecedor — usada para emissão de rastreios em contratos de postagem." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "1=faixa ativa." }, "Prefix": { "type": "string", "nullable": true, "description": "Prefixo do código SRO (ex.: `AA`, `BR`)." }, "RangeInitial": { "type": "integer", "nullable": true, "description": "Primeiro número da faixa." }, "RangeFinal": { "type": "integer", "nullable": true, "description": "Último número da faixa." }, "CurrentRange": { "type": "integer", "nullable": true, "description": "Próximo número a ser usado." }, "DiffRange": { "type": "integer", "description": "Quantidade de números ainda disponíveis na faixa quando ativa. Zero quando inativa ou sem `CurrentRange`." } } }, "SupplierCarrierTableUpload": { "type": "object", "description": "Upload de tabela de frete da transportadora.", "properties": { "IDCarrierTableUpload": { "type": "integer", "format": "int32", "description": "Identificador do upload de tabela de frete vinculado ao fornecedor (quando o fornecedor é uma transportadora). Cada upload corresponde a uma planilha de tabela de frete importada." }, "FileName": { "type": "string", "nullable": true, "description": "Nome do arquivo enviado." }, "UrlFile": { "type": "string", "description": "URL completa para download do arquivo, já com token de acesso embutido." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora do upload (formato ISO 8601 com sufixo Z)." }, "Main": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica a tabela vigente: `1` no upload mais recente, `0` nos demais." } } }, "SupplierCostCenterAllocation": { "type": "object", "description": "Rateio padrão de centro de custo para títulos gerados a partir do fornecedor.", "properties": { "IDTypeCostCenter": { "type": "integer", "format": "int32", "description": "Centro de custo padrão associado ao fornecedor (uma linha por nível da árvore de centros de custos quando a empresa usa hierarquia)." }, "TypeCostCenter": { "type": "string", "maxLength": 100, "description": "Nome do centro de custo." }, "ExternalCode": { "type": "string", "maxLength": 45, "nullable": true, "description": "Código externo para integração contábil." }, "ValueRatio": { "type": "number", "description": "Fração do total (decimal com 4 casas, ex.: `0.3500` = 35%)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora do cadastro do rateio." } } }, "SupplierCategoryListItem": { "type": "object", "description": "Item de `GET /supplier/category`. Representa uma categoria de fornecedor da empresa, com o tipo de fornecedor já resolvido.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da categoria." }, "IDSupplierCategory": { "type": "integer", "format": "int32", "description": "Identificador da categoria." }, "CategoryDescription": { "type": "string", "maxLength": 45, "description": "Nome (descrição) da categoria." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa dona da categoria." }, "IDTypeSupplier": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "description": "Tipo de fornecedor. Valores: 1=Produto, 2=Transportadora, 3=Pessoal, 4=Serviço, 5=Insumo, 6=Governo, 7=Transportadora P/ Devoluções, 8=Operador logístico, 9=Outros." }, "TypeSupplier": { "type": "string", "enum": [ "Produto", "Transportadora", "Pessoal", "Serviço", "Insumo", "Governo", "Transportadora P/ Devoluções", "Operador logístico", "Outros" ], "description": "Texto pronto para exibição do tipo de fornecedor, resolvido a partir de `IDTypeSupplier`." }, "SuppliersCategoryStatus": { "type": "integer", "enum": [ 0, 1 ], "description": "Situação da categoria: 0=inativa (excluída logicamente), 1=ativa. A listagem só devolve `1`." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de cadastro." } } }, "SupplierCategoryCreate": { "type": "object", "description": "Corpo do `POST /supplier/category`. Ambos os campos são obrigatórios.", "required": [ "CategoryDescription", "IDTypeSupplier" ], "properties": { "CategoryDescription": { "type": "string", "maxLength": 45, "description": "Nome (descrição) da categoria." }, "IDTypeSupplier": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "description": "Tipo de fornecedor. Valores: 1=Produto, 2=Transportadora, 3=Pessoal, 4=Serviço, 5=Insumo, 6=Governo, 7=Transportadora P/ Devoluções, 8=Operador logístico, 9=Outros." } } }, "SupplierCategoryUpdate": { "type": "object", "description": "Corpo do `PUT /supplier/category/{idsuppliercategory}`. Os dois campos são sobrescritos a cada chamada (não é atualização parcial).", "required": [ "CategoryDescription", "IDTypeSupplier" ], "properties": { "CategoryDescription": { "type": "string", "maxLength": 45, "description": "Nome (descrição) da categoria." }, "IDTypeSupplier": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "description": "Tipo de fornecedor. Valores: 1=Produto, 2=Transportadora, 3=Pessoal, 4=Serviço, 5=Insumo, 6=Governo, 7=Transportadora P/ Devoluções, 8=Operador logístico, 9=Outros." } } }, "AccountsPayablePaymentCreate": { "type": "object", "required": [ "IDBankAccount", "DateTransactionTimestamp" ], "properties": { "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária onde o pagamento foi efetuado." }, "DateTransactionTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora da transação." }, "Value": { "type": "number", "nullable": true, "description": "Valor pago. Quando omitido, usa o saldo devedor total (`ValueTotal` - `ValuePaid`)." }, "TransactionDescription": { "type": "string", "default": "", "description": "Descrição da transação." }, "TransactionDocument": { "type": "string", "default": "", "description": "Documento da transação." }, "IDAccountsPayableReceivableConciliation": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conciliação bancária à qual este pagamento pertence." }, "IDAccountsPayableReceivableConciliationMarketplace": { "type": "integer", "nullable": true, "description": "Conciliação de marketplace vinculada ao pagamento." } } }, "AccountsPayableCostCenterSetItem": { "type": "object", "required": [ "IDTypeCostCenter", "ValueRatio" ], "properties": { "IDTypeCostCenter": { "type": "integer", "format": "int32", "description": "Identificador do centro de custo." }, "ValueRatio": { "type": "number", "description": "Proporção do rateio (ex.: `0.5` = 50%). A soma de todos os itens deve ser exatamente `1`." } } }, "AccountsReceivableCreate": { "type": "object", "description": "Corpo do `POST /accounts/receivable`. `DateDue` e `Value` são obrigatórios na prática (sem eles a criação falha no INSERT). `IDTypeDocument` e `IDTypeAccountPayableReceivable` também são exigidos pelo frontend e validados — quando omitidos, a criação cai em `[BadRequest] - Tipo documento não existe` ou `[BadRequest] - Plano de contas não existe`.", "required": [ "DateDue", "Value", "IDTypeDocument", "IDTypeAccountPayableReceivable" ], "properties": { "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento." }, "Value": { "type": "number", "description": "Valor do título, com duas casas decimais." }, "IDTypeDocument": { "type": "integer", "format": "int32", "description": "Identificador do tipo de documento. Validado contra os cadastrados da empresa." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "description": "Identificador do plano de contas. Validado contra os cadastrados da empresa." }, "IDTypePayment": { "type": "integer", "format": "int32", "description": "Identificador do tipo de pagamento. Validado contra os cadastrados da empresa." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do cliente. Não pode vir junto com `IDSupplier`." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do fornecedor (casos de devolução/estorno). Não pode vir junto com `IDConsumer`." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data de emissão do documento." }, "DocumentNumber": { "type": "string", "maxLength": 200, "nullable": true, "description": "Número do documento (nota fiscal, recibo, etc.)." }, "Comments": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Observações livres sobre o título." }, "TID": { "type": "string", "maxLength": 45, "nullable": true, "description": "TID — identificador da transação no adquirente, quando o título nasce de uma venda em cartão." }, "NSU": { "type": "string", "maxLength": 45, "nullable": true, "description": "NSU — número sequencial único do adquirente, quando o título nasce de uma venda em cartão." }, "Installment": { "type": "integer", "nullable": true, "description": "Número da parcela deste título (ex.: 2 para a 2ª parcela)." }, "InstallmentTotal": { "type": "integer", "nullable": true, "description": "Total de parcelas do plano de pagamento original." }, "IDBankAccountForecast": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conta bancária prevista para o recebimento. Validado contra as contas cadastradas na empresa." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da empresa faturadora. Quando omitido, assume a empresa autenticada. Quando informada e diferente, precisa estar vinculada como filial (`CompanyMain`) da empresa autenticada." }, "ValueDiscount": { "type": "number", "nullable": true, "description": "Valor de desconto, com duas casas decimais." }, "ValueInterest": { "type": "number", "nullable": true, "description": "Valor de juros, com duas casas decimais." }, "ValuePenalty": { "type": "number", "nullable": true, "description": "Valor de multa, com duas casas decimais." } } }, "AccountsReceivableUpdate": { "type": "object", "description": "Corpo do `PUT /accounts/receivable/{idaccountreceivable}`. Todos os campos são opcionais; apenas os enviados são atualizados (comportamento de atualização parcial). Quando o título tem boleto/link de pagamento associado, alterações de `Value` ou `DateDue` podem ser bloqueadas ou propagadas para o gateway.", "properties": { "Comments": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Observações." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data do documento." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento." }, "DocumentNumber": { "type": "string", "maxLength": 200, "nullable": true, "description": "Número do documento." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do cliente. Quando enviado, zera `IDSupplier` automaticamente." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do fornecedor. Quando enviado, zera `IDConsumer` automaticamente." }, "IDTypePayment": { "type": "integer", "format": "int32", "description": "Identificador do tipo de pagamento." }, "IDTypeDocument": { "type": "integer", "format": "int32", "description": "Identificador do tipo de documento." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "description": "Identificador do plano de contas." }, "Value": { "type": "number", "description": "Valor do título. Quando há boleto pago, a alteração é bloqueada." }, "Installment": { "type": "integer", "nullable": true, "description": "Número da parcela deste título (ex.: 2 para a 2ª parcela)." }, "InstallmentTotal": { "type": "integer", "nullable": true, "description": "Total de parcelas do plano de pagamento original." }, "TID": { "type": "string", "maxLength": 45, "nullable": true, "description": "TID — identificador da transação no adquirente, quando o título nasce de uma venda em cartão." }, "NSU": { "type": "string", "maxLength": 45, "nullable": true, "description": "NSU — número sequencial único do adquirente, quando o título nasce de uma venda em cartão." }, "IDBankAccountForecast": { "type": "integer", "format": "int32", "description": "Identificador da conta bancária prevista para o recebimento. O valor `\"0\"` é ignorado." }, "ValueDiscount": { "type": "number", "nullable": true, "description": "Valor de desconto." }, "ValueInterest": { "type": "number", "nullable": true, "description": "Valor de juros." }, "ValuePenalty": { "type": "number", "nullable": true, "description": "Valor de multa." }, "IDCompanyIntegration": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da integração originadora do título." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "description": "Identificador da empresa faturadora." }, "Forecast": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se o título é uma previsão (1) ou um lançamento real (0)." } } }, "AccountsReceivableListItem": { "type": "object", "description": "Item retornado por `GET /accounts/receivable`. Inclui campos próprios da conta, descrições resolvidas dos relacionamentos (cliente/fornecedor, plano de contas, tipo de documento, tipo de pagamento), dados do pedido associado, da nota fiscal de origem (quando há) e da integração; totais já calculados em `Number` (`ValueTotal`, `ValuePaid`, `ValuePaymentPending`).", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da conta." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "description": "Identificador do título." }, "IDStatusAccountPayableReceivable": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6 ], "nullable": true, "description": "Status do título: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo, 6=Vence hoje." }, "StatusAccountPayableReceivable": { "type": "string", "nullable": true, "description": "Descrição textual do status." }, "Comments": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Observações." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data do documento." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento." }, "DateLastPayment": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora do último pagamento lançado." }, "DocumentNumber": { "type": "string", "maxLength": 200, "nullable": true, "description": "Número do documento." }, "RecordTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de criação do título." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do cliente." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do fornecedor (quando o título é uma devolução/estorno)." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do cliente ou do fornecedor associado (a coluna serve aos dois conforme `IDConsumer`/`IDSupplier`)." }, "IDTypeAccount": { "type": "integer", "enum": [ 0 ], "description": "Tipo de conta. Sempre `0` (entrada / a receber) nesta listagem." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do plano de contas." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas." }, "IDTypeDocument": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de documento." }, "TypeDocument": { "type": "string", "nullable": true, "description": "Descrição do tipo de documento." }, "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de pagamento." }, "TypePaymentDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo de pagamento." }, "TypePaymentCategory": { "type": "string", "nullable": true, "description": "Categoria do tipo de pagamento (Dinheiro, Boleto, Cartão de Crédito, etc.)." }, "IDOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador interno do pedido vinculado." }, "Order": { "type": "string", "nullable": true, "description": "Número externo do pedido (ex.: `OT-1234`, `ML-5678`)." }, "OrderFrom": { "type": "string", "nullable": true, "description": "Pedidos de origem do canal de venda, concatenados quando houver múltiplos." }, "IDStatusOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Status do pedido vinculado." }, "OrderFinishConfirmation": { "type": "integer", "format": "int32", "nullable": true, "description": "Indica se o tipo de pedido exige confirmação para finalização (vem do `TypeOrder`)." }, "ValueOrder": { "type": "number", "nullable": true, "description": "Valor total do pedido associado: soma de `PriceSellingTotal` dos itens + `ValueShipping` + `NfeAccessoryExpenses`." }, "Installment": { "type": "integer", "nullable": true, "description": "Número da parcela deste título." }, "InstallmentTotal": { "type": "integer", "nullable": true, "description": "Total de parcelas do plano original." }, "TID": { "type": "string", "maxLength": 45, "nullable": true, "description": "TID — identificador da transação no adquirente, quando o título nasce de uma venda em cartão." }, "NSU": { "type": "string", "maxLength": 45, "nullable": true, "description": "NSU — número sequencial único do adquirente, quando o título nasce de uma venda em cartão." }, "NfeNumber": { "type": "integer", "format": "int32", "nullable": true, "description": "Número da nota fiscal principal de origem." }, "NfeChaveAcesso": { "type": "string", "nullable": true, "description": "Chave de acesso da nota fiscal principal de origem." }, "NfeDhEmi": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de emissão da nota fiscal principal de origem." }, "IDBankAccountForecast": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conta bancária prevista para o recebimento." }, "BankForecast": { "type": "string", "nullable": true, "description": "Nome do banco da conta prevista, eventualmente concatenado com o número da conta." }, "BankForecastAccountNumber": { "type": "string", "nullable": true, "description": "Número da conta bancária prevista." }, "BankPayment": { "type": "string", "nullable": true, "description": "Bancos onde os pagamentos foram lançados (lista concatenada quando há múltiplos)." }, "DaysDue": { "type": "integer", "format": "int32", "nullable": true, "description": "Diferença em dias entre a data atual e o vencimento." }, "Value": { "type": "number", "description": "Valor base do título (já convertido para número; quando o valor não é numérico, vira a posição do item (comportamento defensivo do legado))." }, "ValueDiscount": { "type": "number", "description": "Valor de desconto (zero quando inválido)." }, "ValueInterest": { "type": "number", "description": "Valor de juros (zero quando inválido)." }, "ValuePenalty": { "type": "number", "description": "Valor de multa (zero quando inválido)." }, "ValueTotal": { "type": "number", "description": "Valor total efetivo: `Value + ValuePenalty + ValueInterest - ValueDiscount` (arredondado para 2 casas)." }, "ValuePaid": { "type": "number", "description": "Soma dos pagamentos lançados." }, "ValuePaymentPending": { "type": "number", "description": "Saldo pendente de recebimento: `ValueTotal - ValuePaid` (arredondado para 2 casas)." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da empresa faturadora." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Subdomínio da empresa faturadora." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social da empresa faturadora." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Texto formatado com o tipo e nome da integração originadora." } } }, "AccountsReceivableDetail": { "type": "object", "description": "Resposta detalhada do `GET /accounts/receivable/{idaccountreceivable}` (também o corpo do `POST` e `PUT` após a operação). Inclui dados próprios da conta, descrições resolvidas dos relacionamentos, listas auxiliares (arquivos, pagamentos, histórico, centros de custo) e as contas filhas geradas por conciliação adquirente ou marketplace.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da conta." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "description": "Identificador da conta a receber." }, "IDStatusAccountPayableReceivable": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6 ], "nullable": true, "description": "Status do título: 0=Aberto, 1=Vencido, 2=Pago, 3=Pago Parcialmente, 4=Não lançado, 5=Pago com acréscimo, 6=Vence hoje." }, "StatusAccountPayableReceivable": { "type": "string", "nullable": true, "description": "Descrição textual do status." }, "Comments": { "type": "string", "maxLength": 2000, "nullable": true, "description": "Observações." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data do documento." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento." }, "DaysDue": { "type": "integer", "format": "int32", "nullable": true, "description": "Diferença em dias entre a data atual e o vencimento." }, "DocumentNumber": { "type": "string", "maxLength": 200, "nullable": true, "description": "Número do documento." }, "RecordTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de criação do título." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do cliente." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do fornecedor." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do cliente (ou fornecedor, quando `IDConsumer` é nulo)." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do fornecedor." }, "IDTypeAccount": { "type": "integer", "enum": [ 0 ], "description": "Tipo de conta. Sempre `0` (entrada) — o sistema filtra por `IDTypeAccount=0`." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do plano de contas." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas." }, "IDTypeDocument": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de documento." }, "TypeDocument": { "type": "string", "nullable": true, "description": "Descrição do tipo de documento." }, "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de pagamento." }, "TypePaymentDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo de pagamento." }, "IDOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador interno do pedido vinculado." }, "Order": { "type": "string", "nullable": true, "description": "Número externo do pedido." }, "IDStatusOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Status do pedido vinculado." }, "OrderFinishConfirmation": { "type": "integer", "format": "int32", "nullable": true, "description": "Indica se o tipo de pedido vinculado exige confirmação para finalização (herdado do `TypeOrder`)." }, "IDServiceOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da ordem de serviço vinculada, quando o título nasce de uma OS." }, "Installment": { "type": "integer", "nullable": true, "description": "Número da parcela deste título (ex.: 2 para a 2ª parcela)." }, "InstallmentTotal": { "type": "integer", "nullable": true, "description": "Total de parcelas do plano de pagamento original." }, "TID": { "type": "string", "maxLength": 45, "nullable": true, "description": "TID — identificador da transação no adquirente, quando o título nasce de uma venda em cartão." }, "NSU": { "type": "string", "maxLength": 45, "nullable": true, "description": "NSU — número sequencial único do adquirente, quando o título nasce de uma venda em cartão." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da empresa faturadora." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Subdomínio da empresa faturadora." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social da empresa faturadora." }, "IDCompanyIntegration": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da integração originadora." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Texto formatado com o tipo e nome da integração." }, "IDBankAccountForecast": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conta bancária prevista para o recebimento." }, "Bank": { "type": "string", "nullable": true, "description": "Nome do banco da conta prevista, eventualmente concatenado com o número da conta." }, "BankForecastAccountNumber": { "type": "string", "nullable": true, "description": "Número da conta bancária prevista." }, "Forecast": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se o título é uma previsão (1) ou um lançamento real (0)." }, "Value": { "type": "number", "description": "Valor base do título, já convertido para número (zero quando inválido)." }, "ValueDiscount": { "type": "number", "description": "Valor de desconto (zero quando inválido)." }, "ValueInterest": { "type": "number", "description": "Valor de juros (zero quando inválido)." }, "ValuePenalty": { "type": "number", "description": "Valor de multa (zero quando inválido)." }, "ValueTotal": { "type": "number", "description": "Valor total efetivo: `Value + ValuePenalty + ValueInterest - ValueDiscount`." }, "Files": { "type": "array", "description": "Arquivos anexados à conta (PDF, XML, boleto, comprovante de recebimento).", "items": { "$ref": "#/components/schemas/FileAttachment" } }, "Payments": { "type": "array", "description": "Lançamentos do extrato bancário vinculados a esta conta.", "items": { "$ref": "#/components/schemas/BankStatementPayment" } }, "AccountsPayableReceivableLog": { "type": "array", "description": "Histórico de alterações da conta, em ordem decrescente de data.", "items": { "$ref": "#/components/schemas/AccountsPayableLogEntry" } }, "AccountsPayableReceivableCostCenter": { "type": "array", "description": "Centros de custo com o valor rateado a partir do total da conta.", "items": { "$ref": "#/components/schemas/AccountsPayableCostCenter" } }, "RelatedAccountsPayableReceivable": { "type": "array", "nullable": true, "description": "Contas filhas geradas por conciliação (taxa adquirente, comissão de marketplace, antecipação, frete, cupom, impostos do marketplace).", "items": { "$ref": "#/components/schemas/RelatedAccountsPayable" } } } }, "AccountsReceivablePaymentCreate": { "type": "object", "description": "Corpo do `POST /accounts/receivable/{idaccountreceivable}/payment`.", "required": [ "IDBankAccount", "DateTransactionTimestamp" ], "properties": { "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária onde o recebimento foi lançado. Quando a conta tinha `IDBankAccountForecast` nulo, esse valor passa a ser a previsão." }, "DateTransactionTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora do recebimento." }, "Value": { "type": "number", "nullable": true, "description": "Valor recebido. Quando omitido, o sistema assume `null` (sem valor)." }, "TransactionDescription": { "type": "string", "default": "", "maxLength": 100, "description": "Descrição livre do lançamento." }, "TransactionDocument": { "type": "string", "default": "", "maxLength": 45, "description": "Documento associado ao lançamento (comprovante, TID, etc.)." }, "IDAccountsPayableReceivableConciliation": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conciliação adquirente à qual este lançamento se refere. Quando informado e o valor difere do título, dispara a redistribuição automática entre lançamentos relacionados e a criação do lançamento de taxa do adquirente." }, "IDAccountsPayableReceivableConciliationMarketplace": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conciliação de marketplace. Quando informado, gera automaticamente as contas filhas para comissão, antecipação, frete, cupom e impostos do marketplace conforme a parametrização da integração." } } }, "AccountsReceivableConciliationUpdate": { "type": "object", "description": "Corpo do `PUT /accounts/receivable/conciliation/{idaccountspayablereceivableconciliation}`. Apenas `Comments` é alterável.", "properties": { "Comments": { "type": "string", "maxLength": 255, "nullable": true, "description": "Observações sobre a conciliação." } } }, "AccountsReceivableConciliationListItem": { "type": "object", "description": "Item da resposta default de `GET /accounts/receivable/conciliation`. Cada item agrega os vínculos a contas a receber e a lançamentos do extrato bancário em `IDAccountPayableReceivable` (lista concatenada) e `IDOrder` (lista concatenada).", "properties": { "IDAccountsPayableReceivableConciliation": { "type": "integer", "format": "int32", "description": "Identificador único da conciliação." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da conciliação." }, "CompanyIntegration": { "type": "string", "description": "Texto formatado com o tipo e nome da integração adquirente." }, "IDCompanyIntegration": { "type": "integer", "format": "int32", "description": "Identificador da integração adquirente." }, "TID": { "type": "string", "maxLength": 45, "nullable": true, "description": "TID da transação no adquirente." }, "NSU": { "type": "string", "maxLength": 45, "nullable": true, "description": "NSU — número sequencial único da transação no adquirente." }, "ExternalIDOrderReference": { "type": "string", "maxLength": 45, "nullable": true, "description": "Referência externa do pedido enviada pelo adquirente." }, "Installment": { "type": "integer", "description": "Número da parcela." }, "InstallmentTotal": { "type": "integer", "description": "Total de parcelas." }, "SaleDate": { "type": "string", "format": "date", "nullable": true, "description": "Data da venda." }, "ReceivedDate": { "type": "string", "format": "date", "description": "Data de recebimento." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de cadastro da conciliação." }, "TotalValue": { "type": "number", "description": "Valor total declarado pelo adquirente (negativo em estornos)." }, "ReceivedValue": { "type": "number", "description": "Valor efetivamente recebido após taxas." }, "MerchantDiscountRateEffectiveValue": { "type": "number", "description": "Valor efetivo da taxa MDR (Merchant Discount Rate) cobrada pelo adquirente." }, "MerchantDiscountRateEffectiveValueRate": { "type": "number", "description": "Percentual efetivo da MDR: `MerchantDiscountRateEffectiveValue / TotalValue` (4 casas decimais)." }, "AnticipationRateEffectiveValue": { "type": "number", "description": "Valor efetivo da taxa de antecipação cobrada pelo adquirente." }, "AnticipationRateEffectiveValueRate": { "type": "number", "description": "Percentual efetivo da antecipação: `AnticipationRateEffectiveValue / TotalValue` (4 casas decimais)." }, "IDTypePaymentFrom": { "type": "integer", "format": "int32", "description": "Identificador do tipo de pagamento do adquirente." }, "TypePayment": { "type": "string", "description": "Descrição do tipo de pagamento do adquirente." }, "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "Sugestão de tipo de pagamento interno, baseada na categoria do adquirente e parametrização." }, "IDTypeAcquirerReleaseType": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de liberação do adquirente." }, "ReceivableIDBankAccount": { "type": "integer", "format": "int32", "nullable": true, "description": "Conta bancária declarada pelo adquirente para o recebimento." }, "Bank": { "type": "string", "nullable": true, "description": "Nome do banco da conta declarada pelo adquirente." }, "Status": { "type": "integer", "format": "int32", "description": "Status retornado pelo adquirente (`IDTypeAcquirerStatus`)." }, "TypeAcquirerStatus": { "type": "string", "description": "Descrição do status do adquirente." }, "ConciliationStatus": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Status interno de conciliação: 1=Não conciliado, 2=Conciliação automática, 3=Conciliação manual, 4=Conciliação parcial." }, "AutomaticReceivableAnticipation": { "type": "integer", "format": "int32", "nullable": true, "description": "Indica se a antecipação automática foi acionada pelo adquirente." }, "Comments": { "type": "string", "maxLength": 255, "nullable": true, "description": "Observações sobre a conciliação." }, "IDAccountPayableReceivable": { "type": "string", "nullable": true, "description": "Lista concatenada (por vírgula) dos identificadores de contas a receber vinculadas à conciliação." }, "IDOrder": { "type": "string", "nullable": true, "description": "Lista concatenada (por vírgula) dos identificadores de pedidos vinculados (via contas a receber)." } } }, "AccountsReceivableConciliationAuditItem": { "type": "object", "description": "Item da resposta de `GET /accounts/receivable/conciliation` quando `AuditRate=1`. Compara as taxas efetivas pagas com as taxas configuradas em `TypePaymentRate` e calcula o impacto financeiro da diferença.", "properties": { "IDAccountsPayableReceivableConciliation": { "type": "integer", "format": "int32", "description": "Identificador interno do lançamento de conciliação de cartão/marketplace (linha da prévia enviada pela adquirente)." }, "IntegrationName": { "type": "string", "description": "Texto formatado com o tipo e nome da integração adquirente." }, "TID": { "type": "string", "maxLength": 45, "nullable": true, "description": "TID (Transaction ID) da venda na adquirente. Identificador único da transação atribuído pelo gateway/adquirente." }, "NSU": { "type": "string", "maxLength": 45, "nullable": true, "description": "NSU (Número Sequencial Único) da transação na adquirente." }, "ExternalIDOrderReference": { "type": "string", "maxLength": 45, "nullable": true, "description": "Identificador externo do pedido na adquirente/marketplace (referência usada para casar a transação com o pedido na loja)." }, "SaleDate": { "type": "string", "format": "date", "nullable": true, "description": "Data da venda original no formato `YYYY-MM-DD` (data em que a transação foi capturada pela adquirente). Pode vir vazia quando a adquirente não informa." }, "ReceivedDate": { "type": "string", "format": "date", "description": "Data prevista de recebimento do valor pela conta da loja, no formato `YYYY-MM-DD` (após o prazo D+N da adquirente)." }, "Installment": { "type": "integer", "description": "Número da parcela desta transação (1, 2, 3...)." }, "InstallmentTotal": { "type": "integer", "description": "Total de parcelas da transação original (ex.: 6 quando é venda em 6x)." }, "TotalValue": { "type": "number", "description": "Valor total declarado pelo adquirente." }, "ReceivedValue": { "type": "number", "description": "Valor efetivamente recebido." }, "StatusAcquirer": { "type": "integer", "format": "int32", "description": "Status retornado pelo adquirente." }, "TypePayment": { "type": "string", "description": "Tipo de pagamento do adquirente." }, "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de pagamento associado em `TypePaymentRate`." }, "AutomaticReceivableAnticipation": { "type": "integer", "format": "int32", "nullable": true, "description": "`1` quando a parcela foi antecipada automaticamente pela adquirente (programa de antecipação automática contratado); `0`/`null` caso contrário." }, "IDOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Pedido vinculado à conciliação (quando há vínculo via conta a receber)." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Conta a receber vinculada à conciliação." }, "AppliedMDRValue": { "type": "number", "nullable": true, "description": "Valor da MDR efetivamente cobrada." }, "AppliedMDRPercent": { "type": "number", "description": "Percentual efetivo da MDR aplicada (4 casas decimais)." }, "ConfigMDRPercent": { "type": "number", "nullable": true, "description": "Percentual da MDR configurado em `TypePaymentRate`." }, "ConfigMDRValue": { "type": "number", "nullable": true, "description": "Valor esperado da MDR: `TotalValue × ConfigMDRPercent + ConfigFixedRate`." }, "AppliedAntValue": { "type": "number", "nullable": true, "description": "Valor da taxa de antecipação efetivamente cobrada." }, "AppliedAntPercent": { "type": "number", "description": "Percentual efetivo da antecipação aplicada (4 casas decimais)." }, "ConfigAntPercent": { "type": "number", "nullable": true, "description": "Percentual da antecipação configurado em `TypePaymentRate`." }, "ConfigAntValue": { "type": "number", "nullable": true, "description": "Valor esperado da antecipação: `TotalValue × ConfigAntPercent`." }, "ConfigFixedRate": { "type": "number", "description": "Taxa fixa adicional configurada para o tipo de pagamento." }, "DiffMDRPercent": { "type": "number", "description": "Diferença em percentual da MDR: efetivo - configurado (4 casas decimais)." }, "DiffAntPercent": { "type": "number", "description": "Diferença em percentual da antecipação: efetiva - configurada (4 casas decimais)." }, "DiffValue": { "type": "number", "description": "Diferença em valor entre o total efetivo cobrado e o esperado pela configuração: `(MDRAplicada + AntAplicada) - (MDREsperada + AntEsperada)`." }, "ValueDifferenceAllow": { "type": "number", "description": "Tolerância em valor configurada na empresa (`Key='ValueDifferenceAllow'`); zero quando não configurada." }, "IDAuditStatus": { "type": "integer", "enum": [ 1, 2, 3, 4, 5 ], "description": "Classificação calculada da auditoria: 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)." } } }, "AccountsReceivableMarketplaceConciliationItem": { "type": "object", "description": "Item agrupado de `GET /accounts/receivable/marketplace-conciliation`. Cada item corresponde a uma conciliação de marketplace, com a decomposição dos valores liberados (comissão, frete, antecipação, cupom, impostos) e a lista de contas a receber internas vinculadas.", "properties": { "IDAccountsPayableReceivableConciliationMarketplace": { "type": "integer", "format": "int32", "description": "Identificador único da conciliação de marketplace." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de cadastro da conciliação." }, "IDCompanyIntegration": { "type": "integer", "format": "int32", "description": "Identificador da integração de marketplace." }, "CompanyIntegration": { "type": "string", "description": "Texto formatado com o tipo e nome da integração." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona." }, "TID": { "type": "string", "maxLength": 40, "description": "TID da conciliação." }, "OrderId": { "type": "string", "maxLength": 45, "nullable": true, "description": "Identificador externo do pedido no marketplace." }, "IDOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador interno do pedido vinculado (resolvido via `HubOrder`)." }, "ShippingId": { "type": "string", "maxLength": 40, "nullable": true, "description": "Identificador do envio no marketplace." }, "Installment": { "type": "integer", "description": "Número da parcela declarada pelo marketplace." }, "InstallmentTotal": { "type": "integer", "description": "Total de parcelas declarado pelo marketplace." }, "SaleDate": { "type": "string", "format": "date", "nullable": true, "description": "Data da venda informada pelo marketplace." }, "ReceivedDate": { "type": "string", "format": "date", "nullable": true, "description": "Data prevista (ou efetiva) de recebimento do valor liberado pelo marketplace." }, "Comments": { "type": "string", "maxLength": 500, "nullable": true, "description": "Observações da conciliação." }, "TotalValue": { "type": "number", "nullable": true, "description": "Valor bruto declarado pelo marketplace." }, "ReceivedValue": { "type": "number", "nullable": true, "description": "Valor líquido recebido após deduções." }, "MarketplaceFeeValue": { "type": "number", "nullable": true, "description": "Valor de comissão cobrado pelo marketplace." }, "MarketplaceFeePct": { "type": "number", "nullable": true, "description": "Percentual da comissão sobre o `TotalValue`." }, "MarketplaceShippingFeeValue": { "type": "number", "nullable": true, "description": "Valor de frete cobrado pelo marketplace." }, "MarketplaceShippingFeePct": { "type": "number", "nullable": true, "description": "Percentual do frete sobre o `TotalValue`." }, "MarketplaceFinancingFeeValue": { "type": "number", "nullable": true, "description": "Valor de antecipação/financiamento cobrado pelo marketplace." }, "MarketplaceFinancingFeePct": { "type": "number", "nullable": true, "description": "Percentual da taxa de antecipação/financiamento sobre o `TotalValue`." }, "MarketplaceTaxesValue": { "type": "number", "nullable": true, "description": "Valor de tributos descontados pelo marketplace." }, "MarketplaceTaxesPct": { "type": "number", "nullable": true, "description": "Percentual dos tributos descontados pelo marketplace sobre o `TotalValue`." }, "MarketplaceCouponValue": { "type": "number", "nullable": true, "description": "Valor de cupom de desconto aplicado pelo marketplace." }, "MarketplaceCouponPct": { "type": "number", "nullable": true, "description": "Percentual do cupom de desconto aplicado pelo marketplace sobre o `TotalValue`." }, "IDTypeAcquirerStatus": { "type": "integer", "format": "int32", "description": "Identificador do status do marketplace." }, "TypeAcquirerStatus": { "type": "string", "description": "Descrição do status do marketplace." }, "IDTypeStatusConciliation": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Status de conciliação: `1` Não conciliado, `2` Conciliado automaticamente, `3` Conciliado manualmente, `4` Conciliado parcialmente." }, "IDBankAccount": { "type": "string", "nullable": true, "description": "Conta bancária configurada para a integração (vinda de `Key='IDBankAccount'`)." }, "InternalAccounts": { "type": "array", "description": "Contas a receber e a pagar internas vinculadas a esta conciliação (resultado do vínculo via `AccountsPayableReceivableBankStatement`).", "items": { "type": "object", "properties": { "IDBankStatement": { "type": "integer", "format": "int32", "description": "Identificador do lançamento no extrato bancário." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "description": "Identificador da conta a receber/pagar vinculada." }, "Document": { "type": "string", "nullable": true, "description": "Número do documento da conta." }, "Description": { "type": "string", "nullable": true, "description": "Observações da conta." }, "Value": { "type": "number", "description": "Valor líquido da conta — positivo quando é a receber (`IDTypeAccount=0`), negativo quando é a pagar (`IDTypeAccount=1`)." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo da conta vinculada: 0=entrada (a receber), 1=saída (a pagar)." } } } }, "ERPValueTotal": { "type": "number", "description": "Soma dos valores líquidos das `InternalAccounts` (a receber positivo, a pagar negativo). Permite bater com `ReceivedValue` do marketplace." }, "MarketplaceOtherFeeValue": { "type": "number", "nullable": true, "description": "Valor de outras taxas cobradas pelo marketplace." }, "MarketplaceOtherFeePct": { "type": "number", "nullable": true, "description": "Percentual das outras taxas do marketplace sobre o `TotalValue`." } } }, "BankStatementConciliationCreate": { "type": "object", "description": "Corpo do `POST /accounts/bank-statement`. Identifique **exatamente uma** conciliação (`IDBankStatementConciliation` ou `IDAccountsPayableReceivableConciliation`) e **exatamente uma** das listas (`Accounts` ou `Transfers`).", "required": [ "IDBankAccount" ], "properties": { "IDBankStatementConciliation": { "type": "integer", "format": "int32", "description": "Identificador da conciliação bancária. Mutuamente exclusivo com `IDAccountsPayableReceivableConciliation`." }, "IDAccountsPayableReceivableConciliation": { "type": "integer", "format": "int32", "description": "Identificador da conciliação de adquirente. Mutuamente exclusivo com `IDBankStatementConciliation`." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária em que os lançamentos serão registrados." }, "Accounts": { "type": "array", "description": "Lista de títulos a pagar/receber a serem conciliados. Mutuamente exclusivo com `Transfers`.", "items": { "type": "object", "required": [ "IDAccountPayableReceivable" ], "properties": { "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "description": "Identificador do título a pagar/receber." } } } }, "Transfers": { "type": "array", "description": "Lista de transferências entre contas (lançamentos do extrato sem título associado) a serem conciliadas. Mutuamente exclusivo com `Accounts`.", "items": { "type": "object", "required": [ "IDBankStatement" ], "properties": { "IDBankStatement": { "type": "integer", "format": "int32", "description": "Identificador do lançamento de transferência no extrato interno." } } } } } }, "BankStatementConciliationCreateResponse": { "type": "object", "description": "Resultado de `POST /accounts/bank-statement`. Espelha a estrutura de um item de `GET /accounts/bank-statement?Source=2` (conciliação bancária com a lista de contas internas vinculadas).", "properties": { "IDBankStatementConciliation": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conciliação bancária. Nulo quando o vínculo é com uma conciliação de adquirente." }, "IDAccountsPayableReceivableConciliation": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da conciliação de adquirente. Nulo quando o vínculo é com uma conciliação bancária." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária onde os lançamentos da conciliação foram registrados." }, "TransactionDate": { "type": "string", "nullable": true, "description": "Data do lançamento de conciliação reaproveitada para os lançamentos vinculados.", "format": "date" }, "BankTransactionID": { "type": "string", "nullable": true, "description": "Identificador externo do lançamento — `BankTransactionID` no caso bancário, `TID`/`NSU` no caso de adquirente." }, "Comments": { "type": "string", "nullable": true, "description": "Descrição reaproveitada do lançamento de conciliação. Para adquirente, vem como `Conciliação de adquirente`." }, "BankValue": { "type": "number", "description": "Valor do lançamento de conciliação (origem do vínculo)." }, "BankName": { "type": "string", "nullable": true, "description": "Nome amigável do lançamento — banco no caso bancário, integração no caso de adquirente." }, "IDTypeStatusConciliation": { "type": "integer", "enum": [ 1, 3, 4 ], "description": "Status final aplicado: 1=Não conciliado, 3=Conciliação manual (valores batem), 4=Conciliação parcial (ainda falta reconciliar). Em conciliação de adquirente, sempre `3`." }, "StatusDescription": { "type": "string", "description": "Descrição do status: `Não Conciliado`, `Concil. Manualmente`, `Concil. Parcialmente`." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo do lançamento: 0=entrada, 1=saída. Em conciliação de adquirente, sempre `0`." }, "InternalAccounts": { "type": "array", "description": "Lançamentos do extrato interno criados (ou reaproveitados) e vinculados à conciliação.", "items": { "type": "object", "properties": { "IDBankStatement": { "type": "integer", "format": "int32", "description": "Identificador do lançamento criado (ou reaproveitado) no extrato interno." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Título vinculado (vazio quando o vínculo é com uma transferência)." }, "Description": { "type": "string", "nullable": true, "description": "Descrição do lançamento (herdada do título conciliado)." }, "Document": { "type": "string", "nullable": true, "description": "Número do documento do lançamento (herdado do título conciliado)." }, "Value": { "type": "number", "description": "Valor do lançamento — positivo quando entrada (a receber), negativo quando saída (a pagar)." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo do lançamento: 0=entrada (a receber), 1=saída (a pagar)." } } } }, "ERPValueTotal": { "type": "number", "description": "Soma dos valores dos títulos conciliados nesta chamada." }, "AccountName": { "type": "string", "nullable": true, "description": "Subdomínio da empresa dona da conciliação." }, "Difference": { "type": "number", "description": "Diferença `BankValue - ERPValueTotal` — quanto ainda falta reconciliar para fechar o lançamento." } } }, "BankStatementTransferCreate": { "type": "object", "description": "Corpo do `POST /accounts/bank-statement/transfer`. A descrição informada é concatenada com o banco e o número da conta do outro lado nos dois lançamentos gerados.", "required": [ "IDBankFrom", "IDBankTo", "Value" ], "properties": { "IDBankFrom": { "type": "integer", "format": "int32", "description": "Conta bancária de origem (debitada)." }, "IDBankTo": { "type": "integer", "format": "int32", "description": "Conta bancária de destino (creditada). Tem que ser diferente de `IDBankFrom`." }, "Value": { "type": "number", "description": "Valor da transferência. Deve ser maior que zero." }, "Date": { "type": "string", "format": "date", "description": "Data da transação (`YYYY-MM-DD`). Default: hoje." }, "Description": { "type": "string", "description": "Descrição base aplicada aos dois lançamentos. Default: `Transferência entre contas`." }, "Document": { "type": "string", "nullable": true, "description": "Número do documento da transferência (eco em `TransactionDocument` nos dois lançamentos)." } } }, "BankStatementTransferCreateResponse": { "type": "object", "description": "Resultado de `POST /accounts/bank-statement/transfer`. Inclui a referência da transferência e os dois lançamentos do extrato (débito e crédito).", "properties": { "message": { "type": "string", "description": "Mensagem fixa de sucesso (`Transferência entre contas realizada com sucesso`)." }, "IDAccountsPayableReceivableBankStatementTransfer": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da referência da transferência. Pode ser nulo quando o registro de referência falha após os lançamentos terem sido gravados." }, "Transfer": { "type": "object", "description": "Detalhes consolidados da transferência.", "properties": { "From": { "type": "object", "description": "Conta debitada (origem).", "properties": { "IDBankAccount": { "type": "integer", "format": "int32", "description": "Identificador da conta bancária debitada (origem)." }, "Bank": { "type": "string", "nullable": true, "description": "Nome do banco da conta debitada." }, "AccountNumber": { "type": "string", "nullable": true, "description": "Número da conta debitada." }, "IDBankStatement": { "type": "integer", "format": "int32", "description": "Identificador do lançamento de débito no extrato." } } }, "To": { "type": "object", "description": "Conta creditada (destino).", "properties": { "IDBankAccount": { "type": "integer", "format": "int32", "description": "Identificador da conta bancária creditada (destino)." }, "Bank": { "type": "string", "nullable": true, "description": "Nome do banco da conta creditada." }, "AccountNumber": { "type": "string", "nullable": true, "description": "Número da conta creditada." }, "IDBankStatement": { "type": "integer", "format": "int32", "description": "Identificador do lançamento de crédito no extrato." } } }, "Value": { "type": "string", "description": "Valor da transferência com 2 casas decimais (eco normalizado de `Value`)." }, "TransactionDate": { "type": "string", "format": "date", "description": "Data da transação aplicada aos dois lançamentos (formato `YYYY-MM-DD`)." }, "Description": { "type": "string", "description": "Descrição base informada na requisição (antes da concatenação com o banco/conta do outro lado)." }, "Document": { "type": "string", "nullable": true, "description": "Número do documento informado na requisição, ecoado nos dois lançamentos." } } }, "InsertedTransactions": { "type": "array", "description": "Os dois lançamentos criados — primeiro o de débito (origem), depois o de crédito (destino).", "items": { "type": "object", "properties": { "IDBankStatement": { "type": "integer", "format": "int32", "description": "Identificador do lançamento criado no extrato." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Identificador da conta bancária onde o lançamento foi registrado." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "0=crédito (entrada), 1=débito (saída)." }, "Value": { "type": "string", "description": "Valor com 2 casas decimais." }, "Description": { "type": "string", "description": "Descrição final do lançamento — a base informada concatenada com o banco e número da conta do outro lado." }, "Type": { "type": "string", "enum": [ "Debit", "Credit" ], "description": "Sinal do lançamento: `Debit` para o débito na conta de origem, `Credit` para o crédito na conta de destino." } } } } } }, "BankStatementTransferDeleteResponse": { "type": "object", "description": "Resultado de `DELETE /accounts/bank-statement/transfer/{idbankstatement}`. Traz a referência removida e os dois lançamentos apagados.", "properties": { "Message": { "type": "string", "description": "Mensagem fixa de sucesso (`Transferência excluída com sucesso`)." }, "DeletedTransfer": { "type": "object", "properties": { "IDAccountsPayableReceivableBankStatementTransfer": { "type": "integer", "format": "int32", "description": "Identificador da referência da transferência removida." }, "Debit": { "type": "object", "description": "Lançamento de débito (saída) removido.", "properties": { "IDBankStatement": { "type": "integer", "format": "int32", "description": "Identificador do lançamento de débito removido." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Identificador da conta bancária debitada (origem da transferência)." }, "Value": { "type": "number", "description": "Valor do lançamento de débito removido." }, "Description": { "type": "string", "nullable": true, "description": "Descrição final do lançamento de débito removido." } } }, "Credit": { "type": "object", "description": "Lançamento de crédito (entrada) removido.", "properties": { "IDBankStatement": { "type": "integer", "format": "int32", "description": "Identificador do lançamento de crédito removido." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Identificador da conta bancária creditada (destino da transferência)." }, "Value": { "type": "number", "description": "Valor do lançamento de crédito removido." }, "Description": { "type": "string", "nullable": true, "description": "Descrição final do lançamento de crédito removido." } } } }, "description": "Detalhamento da transferência removida (referência e os dois lançamentos apagados)." } } }, "BankStatementConciliationRuleListItem": { "type": "object", "description": "Item de `GET /accounts/bank-statement/conciliation-rule`. Inclui os campos da regra, a descrição amigável do tipo de regra (`TypeBankStatementConciliationRule`) e o nome resolvido das entidades referenciadas (conta bancária, plano de contas, fornecedor, cliente, etc.).", "properties": { "IDBankStatementConciliationRule": { "type": "integer", "format": "int32", "description": "Identificador da regra." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da regra." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária à qual a regra se aplica." }, "Bank": { "type": "string", "description": "Nome do banco da `IDBankAccount`, concatenado com o número da conta quando disponível (formato `Banco - Número`)." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo de transação à qual a regra se aplica: `0` crédito (entrada), `1` débito (saída)." }, "TypeAccount": { "type": "string", "enum": [ "Crédito", "Débito" ], "description": "Descrição amigável de `IDTypeAccount` (`Crédito` ou `Débito`)." }, "Description": { "type": "string", "description": "Descrição livre da regra. Única por conta bancária." }, "IDTypeRule": { "type": "integer", "enum": [ 1, 2 ], "description": "Tipo da regra: `1` casa contra contas a pagar/receber, `2` casa contra transferências entre contas." }, "TypeBankStatementConciliationRule": { "type": "string", "enum": [ "Contas pagar/receber", "Transferência" ], "description": "Descrição amigável de `IDTypeRule`." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo 1) Filtra pelo plano de contas. Ignorado quando `IDTypeRule=2`." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas (quando aplicável)." }, "IDTypeDocument": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo 1) Filtra pelo tipo de documento." }, "TypeDocument": { "type": "string", "nullable": true, "description": "Descrição do tipo de documento." }, "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo 1) Filtra pelo tipo de pagamento." }, "TypePaymentDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo de pagamento." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo 1) Filtra pelo fornecedor." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Nome/razão social do fornecedor." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo 1) Filtra pelo cliente." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Nome/razão social do cliente." }, "IDBankAccountTo": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo 2) Conta bancária de destino da transferência." }, "BankTo": { "type": "string", "nullable": true, "description": "Nome do banco de destino (mesmo formato de `Bank`)." }, "BankStatementConciliationRuleStatus": { "type": "integer", "description": "Status interno da regra (1 = ativa)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de criação da regra." } } }, "BankStatementConciliationRuleCreate": { "type": "object", "description": "Corpo de `POST /accounts/bank-statement/conciliation-rule` e `PUT /accounts/bank-statement/conciliation-rule/{idbankstatementconciliationrule}`. Para `IDTypeRule=1`, os campos de filtro (plano de contas, tipo documento, tipo pagamento, fornecedor, cliente) são opcionais e usados como predicado adicional; `IDBankAccountTo` é ignorado. Para `IDTypeRule=2`, `IDBankAccountTo` é obrigatório e os filtros são ignorados.", "required": [ "IDBankAccount", "IDTypeRule" ], "properties": { "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária à qual a regra se aplica." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Tipo de transação: `0` crédito (entrada), `1` débito (saída)." }, "Description": { "type": "string", "nullable": true, "description": "Descrição livre da regra. Não pode repetir para a mesma conta bancária." }, "IDTypeRule": { "type": "integer", "enum": [ 1, 2 ], "description": "`1` contas a pagar/receber, `2` transferência." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo 1) Plano de contas usado como filtro adicional." }, "IDTypeDocument": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo 1) Tipo de documento usado como filtro adicional." }, "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo 1) Tipo de pagamento usado como filtro adicional." }, "IDSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo 1) Fornecedor usado como filtro adicional." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo 1) Cliente usado como filtro adicional." }, "IDBankAccountTo": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo 2) Conta bancária de destino. Obrigatório quando `IDTypeRule=2`. Não pode ser igual a `IDBankAccount`." } } }, "TypeAccountTreeNode": { "type": "object", "description": "Nó da árvore de planos de contas (`GET /type/account/type?Type=Tree`). Cada nó traz seus descendentes em `Children[]`. A descrição é prefixada com o `ExternalCode` quando ele existe (formato `-`). Filhos herdam a categoria do pai.", "properties": { "IDTypeAccountPayble": { "type": "integer", "format": "int32", "description": "Identificador do plano de contas." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do plano." }, "TypeAccountPaybleDescription": { "type": "string", "description": "Descrição do plano. Quando `ExternalCode` está preenchido, vem como `-`." }, "IDTypeAccountPaybleFather": { "type": "integer", "format": "int32", "description": "Identificador do plano pai. Vem `0` quando o plano é raiz (não-nulo via `IFNULL`)." }, "TypeAccountPaybleFatherDescription": { "type": "string", "nullable": true, "description": "Descrição do plano pai (preenchida apenas em nós filhos, propagada pelo sistema)." }, "Status": { "type": "integer", "enum": [ 1 ], "description": "Sempre `1` (apenas planos ativos são retornados)." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo do lançamento: `0` entrada (a receber), `1` saída (a pagar)." }, "IDTypeCategoryAccountPayble": { "type": "integer", "nullable": true, "description": "Categoria do plano (ver `GET /type/account/type/category`). Filhos herdam do pai." }, "TypeCategoryAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição da categoria (resolvida do JOIN)." }, "ExternalCode": { "type": "string", "nullable": true, "description": "Código de referência externo do plano. Único entre planos ativos da empresa." }, "InternalCode": { "type": "string", "nullable": true, "description": "Código de referência interno do plano. Único entre planos ativos da empresa." }, "InternalCodeShort": { "type": "string", "nullable": true, "description": "Versão reduzida do código interno." }, "DefaultOrder": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` quando este é o plano padrão para pedidos da empresa. Apenas um plano por empresa pode estar marcado." }, "DefaultPurchase": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` quando este é o plano padrão para compras da empresa. Apenas um plano por empresa pode estar marcado." }, "Children": { "type": "array", "description": "Descendentes diretos do nó, ordenados por descrição. Vazio para nós folha.", "items": { "type": "object", "description": "(referência recursiva a `TypeAccountTreeNode` — não expandida)" } } } }, "TypeAccountFlatItem": { "type": "object", "description": "Item da lista plana do plano de contas (`GET /type/account/type` sem `Type`). Mesmos campos do nó da árvore, com algumas diferenças: a descrição **não** é prefixada com `ExternalCode`, não vem `Children`, e o caminho hierárquico completo é exposto em `CategoryTree`.", "properties": { "IDTypeAccountPayble": { "type": "integer", "format": "int32", "description": "Identificador do plano de contas." }, "AccountName": { "type": "string", "description": "Subdomínio (identificador) da empresa dona do plano." }, "TypeAccountPaybleDescription": { "type": "string", "description": "Descrição do plano (sem o prefixo de `ExternalCode`)." }, "CategoryTree": { "type": "string", "description": "Caminho hierárquico do plano em texto, separado por ` -> ` (ex.: `Despesas -> Operacionais -> Aluguel`)." }, "IDTypeAccountPaybleFather": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do plano pai. `null` quando o plano é de topo (raiz)." }, "Status": { "type": "integer", "enum": [ 1 ], "description": "Situação do plano. Sempre `1` (apenas ativos são listados)." }, "IDTypeCategoryAccountPayble": { "type": "integer", "nullable": true, "description": "Categoria do plano. Filhos herdam do pai." }, "TypeCategoryAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição amigável da categoria do plano (`TypeAccountPaybleCategory`). `null` quando o plano não tem categoria associada." }, "ExternalCode": { "type": "string", "nullable": true, "description": "Código de referência externo, usado para amarrar o plano a um sistema terceiro (ERP, integração contábil)." }, "InternalCode": { "type": "string", "nullable": true, "description": "Código de referência interno completo do plano." }, "InternalCodeShort": { "type": "string", "nullable": true, "description": "Forma abreviada do código de referência interno." }, "DefaultOrder": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Quando `1`, este é o plano padrão usado em pedidos de venda (contas a receber). Apenas um plano por empresa pode ter `1`." }, "DefaultPurchase": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Quando `1`, este é o plano padrão usado em pedidos de compra (contas a pagar). Apenas um plano por empresa pode ter `1`." } } }, "TypeAccountCreate": { "type": "object", "description": "Corpo do `POST /type/account/type` e `PUT /type/account/type/{idtypeaccount}`. Quando `IDTypeAccountPaybleFather` é informado, a `IDTypeCategoryAccountPayble` enviada é **descartada** (filho herda do pai). Marcar `DefaultOrder=1` ou `DefaultPurchase=1` desmarca o plano anteriormente marcado como padrão da empresa.", "required": [ "TypeAccountPaybleDescription" ], "properties": { "TypeAccountPaybleDescription": { "type": "string", "description": "Descrição do plano. Não pode ser igual à descrição do plano pai." }, "IDTypeAccountPaybleFather": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do plano pai (omita para criar um plano raiz)." }, "IDTypeCategoryAccountPayble": { "type": "integer", "nullable": true, "description": "Categoria do plano (ver `GET /type/account/type/category`). Ignorado quando `IDTypeAccountPaybleFather` é informado." }, "IDTypeAccount": { "type": "integer", "enum": [ 0, 1 ], "default": 1, "description": "Tipo do lançamento: `0` entrada (a receber), `1` saída (a pagar). Default `1`." }, "ExternalCode": { "type": "string", "nullable": true, "description": "Código de referência externo. Único entre planos ativos da empresa." }, "InternalCode": { "type": "string", "nullable": true, "description": "Código de referência interno. Único entre planos ativos da empresa." }, "InternalCodeShort": { "type": "string", "nullable": true, "description": "Versão reduzida do código interno." }, "DefaultOrder": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para marcar este plano como padrão para pedidos da empresa." }, "DefaultPurchase": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para marcar este plano como padrão para compras da empresa." } } }, "TypeAccountCategoryListItem": { "type": "object", "description": "Item de `GET /type/account/type/category`.", "properties": { "IDTypeCategoryAccountPayble": { "type": "string", "description": "Identificador da categoria (devolvido como string)." }, "TypeCategoryAccountPaybleDescription": { "type": "string", "description": "Descrição da categoria." } } }, "SupplierListItem": { "type": "object", "description": "Item da resposta de `GET /supplier`. Traz os campos do cadastro (`Suppliers.*`) e algumas descrições resolvidas. Para o detalhe completo com `Contacts`, `SuppliersCostCenter` e demais relacionamentos, use `GET /supplier/{idsupplier}`.", "properties": { "IDSupplier": { "type": "integer", "format": "int32", "description": "Identificador interno do fornecedor." }, "SupplierNameCorporateName": { "type": "string", "description": "Nome ou razão social." }, "SupplierTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia." }, "SupplierCpfCnpj": { "type": "string", "nullable": true, "description": "CPF (11 dígitos) ou CNPJ (14 dígitos), somente números." }, "SupplierType": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "description": "Tipo do fornecedor: `1` Produto, `2` Transportadora, `3` Pessoal, `4` Serviço, `5` Insumo, `6` Governo, `7` Transportadora p/ Devoluções, `8` Operador logístico, `9` Outros." }, "SupplierEmail": { "type": "string", "nullable": true, "description": "E-mail do fornecedor." }, "SupplierTelephone": { "type": "string", "nullable": true, "description": "Telefone do fornecedor (somente números)." }, "SupplierLogoUrl": { "type": "string", "nullable": true, "description": "Para transportadoras, quando o fornecedor não tem logotipo próprio, é preenchido com o logotipo do tipo de transportadora." }, "IDSupplierCategory": { "type": "integer", "format": "int32", "description": "Identificador da categoria do fornecedor." }, "CategoryDescription": { "type": "string", "nullable": true, "description": "Nome da categoria do fornecedor." }, "IDTypeSupplier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do tipo de fornecedor (vinculado à categoria)." }, "ShippingPostalCode": { "type": "string", "nullable": true, "description": "CEP do endereço." }, "ShippingStreet": { "type": "string", "nullable": true, "description": "Logradouro do endereço." }, "ShippingNumber": { "type": "string", "nullable": true, "description": "Número do endereço." }, "ShippingComplement": { "type": "string", "nullable": true, "description": "Complemento do endereço." }, "ShippingNeighborhood": { "type": "string", "nullable": true, "description": "Bairro." }, "ShippingCity": { "type": "string", "nullable": true, "description": "Cidade." }, "ShippingState": { "type": "string", "nullable": true, "description": "Sigla da UF." }, "BankCode": { "type": "string", "nullable": true, "description": "Código Febraban do banco." }, "BankAgency": { "type": "string", "nullable": true, "description": "Agência bancária." }, "BankCheckingAccount": { "type": "string", "nullable": true, "description": "Número da conta bancária." }, "BankCheckingAccountType": { "type": "integer", "nullable": true, "description": "Tipo da conta bancária (ex.: corrente, poupança)." }, "PixKey": { "type": "string", "nullable": true, "description": "Chave Pix do fornecedor para repasse/pagamento." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Plano de contas padrão para títulos gerados deste fornecedor." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Nome do plano de contas padrão para títulos a pagar deste fornecedor." }, "IDCarrierType": { "type": "integer", "format": "int32", "nullable": true, "description": "Tipo de transportadora (apenas transportadoras)." }, "TypeCarrier": { "type": "string", "nullable": true, "description": "Nome do tipo de transportadora (apenas transportadoras)." }, "CarrierLogoUrl": { "type": "string", "nullable": true, "description": "URL do logotipo do tipo de transportadora (apenas transportadoras)." }, "IDCarrierGateway": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do gateway de transporte (apenas transportadoras)." }, "CarrierGateway": { "type": "string", "nullable": true, "description": "Nome do gateway de transporte (apenas transportadoras)." }, "IDCarrierModal": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da modalidade de transporte (apenas transportadoras)." }, "CarrierModal": { "type": "string", "nullable": true, "description": "Nome da modalidade de transporte (apenas transportadoras)." }, "CarrierAuction": { "type": "integer", "nullable": true, "description": "Quando 1, a transportadora participa do leilão de frete." }, "CarrierRateUploadStatusDescription": { "type": "string", "nullable": true, "description": "Status do último upload de tabela de frete: `Sucesso`, `Erro`, `Processando` ou nulo." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do cadastro." }, "SupplierStatus": { "type": "integer", "enum": [ 1 ], "description": "Sempre 1 (apenas ativos são listados)." } } }, "SupplierCreate": { "type": "object", "description": "Corpo do `POST /supplier`. Quando `SupplierCpfCnpj` for um CNPJ válido, os campos de endereço, contato, razão social, nome fantasia, inscrição estadual e data de nascimento (início de atividade) são **sobrescritos** com os dados da Receita Federal — só são lidos do corpo quando a consulta a `publica.cnpj.ws` falha.", "required": [ "IDSupplierCategory", "SupplierNameCorporateName" ], "properties": { "IDSupplierCategory": { "type": "integer", "format": "int32", "description": "Categoria do fornecedor. Precisa pertencer à empresa autenticada." }, "SupplierNameCorporateName": { "type": "string", "description": "Nome ou razão social. Para CNPJ, é sobrescrito com a razão social da Receita." }, "SupplierCpfCnpj": { "type": "string", "description": "CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita máscara — o sistema mantém apenas os dígitos." }, "SupplierTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia (sobrescrito para CNPJ)." }, "SupplierStateInscription": { "type": "string", "nullable": true, "description": "Inscrição estadual (sobrescrita para CNPJ)." }, "SupplierCityInscription": { "type": "string", "nullable": true, "description": "Inscrição municipal." }, "SupplierIdentityNumber": { "type": "string", "nullable": true, "description": "Documento de identidade (pessoa física)." }, "SupplierBirthDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de nascimento (PF) ou início de atividade (PJ — sobrescrito da Receita)." }, "IDSupplierCivilStatus": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3, 4, 5, 6 ], "description": "Estado civil do fornecedor pessoa física. Valores: 1=Solteiro(a), 2=Casado(a), 3=Divorciado(a), 4=Viúvo(a), 5=União Estável, 6=Outros." }, "SupplierTelephone": { "type": "string", "nullable": true, "description": "Telefone (sobrescrito para CNPJ)." }, "SupplierEmail": { "type": "string", "nullable": true, "description": "E-mail (sobrescrito para CNPJ)." }, "SupplierPIS": { "type": "string", "nullable": true, "description": "PIS do fornecedor pessoa física." }, "ShippingPostalCode": { "type": "string", "nullable": true, "description": "CEP (sobrescrito para CNPJ)." }, "ShippingStreet": { "type": "string", "nullable": true, "description": "Logradouro do endereço (sobrescrito para CNPJ a partir da Receita)." }, "ShippingNumber": { "type": "string", "nullable": true, "description": "Número do endereço (sobrescrito para CNPJ a partir da Receita)." }, "ShippingComplement": { "type": "string", "nullable": true, "description": "Complemento do endereço (sobrescrito para CNPJ a partir da Receita)." }, "ShippingNeighborhood": { "type": "string", "nullable": true, "description": "Bairro (sobrescrito para CNPJ a partir da Receita)." }, "ShippingCity": { "type": "string", "nullable": true, "description": "Cidade (sobrescrita para CNPJ a partir da Receita)." }, "ShippingState": { "type": "string", "nullable": true, "description": "Sigla da UF." }, "BankCode": { "type": "string", "nullable": true, "description": "Código Febraban do banco." }, "BankAgency": { "type": "string", "nullable": true, "description": "Agência bancária." }, "BankCheckingAccount": { "type": "string", "nullable": true, "description": "Número da conta bancária." }, "BankCheckingAccountType": { "type": "integer", "nullable": true, "description": "Tipo da conta bancária (ex.: corrente, poupança)." }, "PixKey": { "type": "string", "nullable": true, "description": "Chave Pix do fornecedor para repasse/pagamento." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres sobre o fornecedor." }, "SupplierProductLeadTimeDays": { "type": "integer", "nullable": true, "description": "Lead time padrão de entrega de produtos, em dias." }, "SupplierProductReliability": { "type": "integer", "nullable": true, "description": "Avaliação de confiabilidade do fornecedor." }, "CarrierAuction": { "type": "integer", "nullable": true, "description": "Apenas para transportadoras: 1 para participar do leilão de frete." }, "CarrierAuctionPenalty": { "type": "integer", "nullable": true, "description": "Apenas para transportadoras. Percentual de acréscimo aplicado ao preço da cotação durante o leilão de frete (ex.: 15 significa +15% sobre o valor de tabela)." }, "IDCarrierGateway": { "type": "integer", "nullable": true, "description": "Apenas para transportadoras. Identificador do gateway de transporte usado para integrar com a operadora." }, "IDCarrierType": { "type": "integer", "nullable": true, "description": "Apenas para transportadoras. Identificador do tipo de transportadora (Correios, JadLog, Total Express, etc.), conforme a tabela de tipos de transportadora." }, "CarrierAdditionalBusinessDays": { "type": "integer", "nullable": true, "description": "Apenas para transportadoras. Dias úteis adicionais somados ao prazo de entrega da transportadora." }, "CarrierShippingCutTime": { "type": "string", "nullable": true, "description": "Hora-limite de corte para coleta (formato `HH:mm:ss`)." }, "CarrierICMSIncluded": { "type": "integer", "nullable": true, "description": "Apenas para transportadoras. Indica se os valores da tabela de frete já incluem ICMS. 1=incluso (o imposto não é adicionado), 0=não incluso (o imposto é somado aos valores da tabela)." }, "CarrierCubageKmM": { "type": "number", "nullable": true, "description": "Apenas para transportadoras. Fator de cubagem em KG/m³ usado para converter volume em peso cubado." }, "CarrierCubageFreeWeight": { "type": "number", "nullable": true, "description": "Apenas para transportadoras. Peso mínimo (em KG) abaixo do qual a cubagem não é aplicada." }, "PrintDanfeA4": { "type": "integer", "nullable": true, "description": "Imprime a Nota Fiscal em A4 de forma automática. 1=imprime, 0=não imprime." }, "LabelAndDanfeSamePage": { "type": "integer", "nullable": true, "description": "Inclui os dados fiscais da nota (número, chave de acesso e código de barras) na parte inferior da etiqueta de transporte, sem imprimir a DANFE em folha avulsa. 1=inclui na etiqueta, 0=não inclui. Só tem efeito quando a impressão da DANFE simplificada (`PrintDanfe`) está ativa." }, "CarrierCollectionListEmail": { "type": "string", "nullable": true, "description": "E-mail destinatário para o envio do romaneio (coleta)." } } }, "SupplierUpdate": { "type": "object", "description": "Corpo do `PUT /supplier/{idsupplier}`. Atualização parcial — apenas campos enviados são alterados.", "required": [], "properties": { "IDSupplierCategory": { "type": "integer", "format": "int32", "description": "Categoria do fornecedor. Precisa pertencer à empresa autenticada." }, "SupplierNameCorporateName": { "type": "string", "description": "Nome ou razão social." }, "SupplierTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia." }, "SupplierCpfCnpj": { "type": "string", "description": "Quando muda, dispara a checagem de duplicidade se `BlockDuplicateSupplier=1`." }, "SupplierStateInscription": { "type": "string", "nullable": true, "description": "Inscrição estadual. Aceita o literal `ISENTO`; caso contrário o banco normaliza mantendo apenas os dígitos." }, "SupplierCityInscription": { "type": "string", "nullable": true, "description": "Inscrição municipal." }, "SupplierIdentityNumber": { "type": "string", "nullable": true, "description": "Documento de identidade (pessoa física)." }, "SupplierBirthDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de nascimento (PF) ou data de abertura (PJ). Envie no formato `YYYY-MM-DD`." }, "SupplierTelephone": { "type": "string", "nullable": true, "description": "Telefone. O banco normaliza mantendo apenas os dígitos." }, "SupplierEmail": { "type": "string", "nullable": true, "description": "E-mail do fornecedor." }, "SupplierPIS": { "type": "string", "nullable": true, "description": "PIS do fornecedor pessoa física." }, "ShippingPostalCode": { "type": "string", "nullable": true, "description": "CEP. O banco normaliza mantendo apenas os dígitos." }, "ShippingStreet": { "type": "string", "nullable": true, "description": "Logradouro do endereço." }, "ShippingNumber": { "type": "string", "nullable": true, "description": "Número do endereço." }, "ShippingComplement": { "type": "string", "nullable": true, "description": "Complemento do endereço." }, "ShippingNeighborhood": { "type": "string", "nullable": true, "description": "Bairro." }, "ShippingCity": { "type": "string", "nullable": true, "description": "Cidade." }, "ShippingState": { "type": "string", "nullable": true, "description": "Sigla da UF." }, "BankCode": { "type": "string", "nullable": true, "description": "Código Febraban do banco." }, "BankAgency": { "type": "string", "nullable": true, "description": "Agência bancária." }, "BankCheckingAccount": { "type": "string", "nullable": true, "description": "Número da conta bancária." }, "BankCheckingAccountType": { "type": "integer", "nullable": true, "description": "Tipo da conta bancária (ex.: corrente, poupança)." }, "PixKey": { "type": "string", "nullable": true, "description": "Chave Pix do fornecedor para repasse/pagamento." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres sobre o fornecedor." }, "DefaultPurchase": { "type": "integer", "nullable": true, "description": "1 marca o fornecedor como padrão para novas compras." }, "PrintDanfe": { "type": "integer", "nullable": true, "description": "Imprime a DANFE simplificada (ou declaração de conteúdo) ao finalizar o packing. 1=imprime, 0=imprime só a etiqueta de transporte." }, "PrintDanfeA4": { "type": "integer", "nullable": true, "description": "Imprime a Nota Fiscal em A4 de forma automática. 1=imprime, 0=não imprime." }, "LabelAndDanfeSamePage": { "type": "integer", "nullable": true, "description": "Inclui os dados fiscais da nota (número, chave de acesso e código de barras) na parte inferior da etiqueta de transporte, sem imprimir a DANFE em folha avulsa. 1=inclui na etiqueta, 0=não inclui. Só tem efeito quando a impressão da DANFE simplificada (`PrintDanfe`) está ativa." }, "ManualLabel": { "type": "integer", "nullable": true, "description": "Quando 1, permite anexar manualmente o arquivo de etiqueta na ficha do pedido." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração da empresa associada." }, "IDCompanyLabel": { "type": "integer", "nullable": true, "description": "Template de etiqueta. Precisa pertencer à empresa ou à empresa-padrão (54) e ser do tipo etiqueta de transportadora." }, "IDTypeAccountPayableReceivable": { "type": "integer", "nullable": true, "description": "Plano de contas padrão para títulos gerados deste fornecedor." }, "SupplierProductLeadTimeDays": { "type": "integer", "nullable": true, "description": "Lead time padrão de entrega de produtos, em dias." }, "SupplierProductReliability": { "type": "integer", "nullable": true, "description": "Avaliação de confiabilidade do fornecedor. Valores: 1=Alto, 2=Médio, 3=Baixo." }, "CarrierAuction": { "type": "integer", "nullable": true, "description": "Quando passa para 1 sem `CarrierQuotationExternalId` anterior, o sistema atribui o próximo id sequencial." }, "CarrierAuctionPenalty": { "type": "integer", "nullable": true, "description": "Apenas para transportadoras. Percentual de acréscimo aplicado ao preço da cotação durante o leilão de frete (ex.: 15 significa +15% sobre o valor de tabela)." }, "IDCarrierGateway": { "type": "integer", "nullable": true, "description": "Apenas para transportadoras. Identificador do gateway de transporte usado para integrar com a operadora." }, "IDCarrierType": { "type": "integer", "nullable": true, "description": "Apenas para transportadoras. Identificador do tipo de transportadora (Correios, JadLog, Total Express, etc.), conforme a tabela de tipos de transportadora." }, "IDCarrierModal": { "type": "integer", "nullable": true, "description": "Apenas para transportadoras. Modalidade de transporte (rodoviário, aéreo, etc.)." }, "CarrierShippingIdRule": { "type": "integer", "nullable": true, "description": "Regra de roteamento usada quando esta transportadora vence o leilão de frete." }, "CarrierAdditionalBusinessDays": { "type": "integer", "nullable": true, "description": "Apenas para transportadoras. Dias úteis adicionais somados ao prazo de entrega da transportadora." }, "CarrierShippingCutTime": { "type": "string", "nullable": true, "description": "Apenas para transportadoras. Horário-limite de corte para coleta no dia, no formato `HH:mm` (ex.: `17:00`)." }, "CarrierICMSIncluded": { "type": "integer", "nullable": true, "description": "Apenas para transportadoras. Indica se os valores da tabela de frete já incluem ICMS. 1=incluso (o imposto não é adicionado), 0=não incluso (o imposto é somado aos valores da tabela)." }, "CarrierCubageKmM": { "type": "number", "nullable": true, "description": "Apenas para transportadoras. Fator de cubagem em KG/m³ usado para converter volume em peso cubado." }, "CarrierCubageFreeWeight": { "type": "number", "nullable": true, "description": "Apenas para transportadoras. Peso mínimo (em KG) abaixo do qual a cubagem não é aplicada." }, "CarrierPriceRounding": { "type": "number", "nullable": true, "description": "Apenas para transportadoras. Centavos de arredondamento do preço do frete cotado. Valor entre 0,00 e 0,99; o arredondamento é feito por aproximação para o valor desejado." }, "CarrierOrdersLimitPerCollection": { "type": "integer", "nullable": true, "description": "Limite de pedidos por romaneio (coleta) desta transportadora." }, "CarrierCollectionListEmail": { "type": "string", "nullable": true, "description": "Apenas para transportadoras. E-mails (separados por vírgula) que recebem o romaneio digital assim que ele é assinado." }, "IgnoreCollectionList": { "type": "integer", "nullable": true, "description": "Quando 1, a transportadora é ignorada na geração automática de romaneio." }, "ContentDeclarationStates": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Lista de UFs em que a transportadora exige declaração de conteúdo. O sistema grava como string separada por vírgula." } } }, "SupplierContactCreate": { "type": "object", "description": "Corpo do `POST /supplier/{idsupplier}/contact`. Cria um contato (pessoa física) vinculado ao fornecedor.", "properties": { "ContactName": { "type": "string", "description": "Nome do contato." }, "ContactEmail": { "type": "string", "nullable": true, "description": "E-mail do contato." }, "ContactTelephone": { "type": "string", "nullable": true, "description": "Telefone do contato." }, "ContactResponsability": { "type": "string", "nullable": true, "description": "Cargo ou responsabilidade." } } }, "SupplierContactUpdate": { "type": "object", "description": "Corpo do `PUT /supplier/{idsupplier}/contact/{idsupplierscontact}`. Atualização parcial — apenas campos enviados são alterados.", "properties": { "ContactName": { "type": "string", "description": "Nome do contato." }, "ContactEmail": { "type": "string", "nullable": true, "description": "E-mail do contato." }, "ContactTelephone": { "type": "string", "nullable": true, "description": "Telefone do contato." }, "ContactResponsability": { "type": "string", "nullable": true, "description": "Cargo ou responsabilidade." } } }, "SupplierCostCenterRatio": { "type": "object", "description": "Item do array de rateio em `POST /supplier/{idsupplier}/cost-center`. A soma de `ValueRatio` de todos os itens precisa fechar em 1.", "required": [ "IDTypeCostCenter", "ValueRatio" ], "properties": { "IDTypeCostCenter": { "type": "integer", "format": "int32", "description": "Centro de custo. Precisa existir na empresa e estar ativo." }, "ValueRatio": { "type": "number", "format": "float", "description": "Fração do total alocada a este centro (0..1). A soma de todos os itens precisa fechar em 1." } } }, "TypeDocumentListItem": { "type": "object", "description": "Item de `GET /type/account/document`. Tipo de documento da empresa, com flags indicando se é padrão para pedidos (vendas) e/ou para compras.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do tipo de documento." }, "IDTypeDocument": { "type": "string", "description": "Identificador do tipo de documento. **Vem como string** na resposta (preserva zeros à esquerda)." }, "TypeDocument": { "type": "string", "maxLength": 45, "description": "Descrição do tipo de documento." }, "DefaultOrder": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Marca este tipo como padrão para pedidos de venda. Usado para sinalizar visualmente na lista de seleção em contas a receber e pedidos." }, "DefaultPurchase": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Marca este tipo como padrão para compras. Usado para sinalizar visualmente na lista de seleção em contas a pagar, pedido de compra e recebimento." } } }, "TypeDocumentCreate": { "type": "object", "description": "Corpo do `POST /type/account/document`. Apenas `TypeDocument` é exigido — os dois flags assumem `null` quando ausentes.", "required": [ "TypeDocument" ], "properties": { "TypeDocument": { "type": "string", "maxLength": 45, "description": "Descrição do tipo de documento." }, "DefaultOrder": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para marcar como padrão para pedidos de venda; `0` ou ausente para não marcar." }, "DefaultPurchase": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para marcar como padrão para compras; `0` ou ausente para não marcar." } } }, "TypeDocumentUpdate": { "type": "object", "description": "Corpo do `PUT /type/account/document/{idtypedocument}`. Os três campos são sobrescritos a cada chamada (não é atualização parcial).", "required": [ "TypeDocument" ], "properties": { "TypeDocument": { "type": "string", "maxLength": 45, "description": "Descrição do tipo de documento." }, "DefaultOrder": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para marcar como padrão para pedidos de venda; `0` ou nulo para desmarcar." }, "DefaultPurchase": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para marcar como padrão para compras; `0` ou nulo para desmarcar." } } }, "TypePaymentListItem": { "type": "object", "description": "Item da resposta de `GET /type/order/payment`. Cada tipo de pagamento pertence a uma categoria fixa (cartão de crédito, débito, Pix, boleto, dinheiro, vale-alimentação, vale-refeição, etc.). Categorias `1` (Cartão de Crédito) e `6` (Cartão de Débito) sempre vêm acompanhadas de uma bandeira (`NfTBand`).", "properties": { "IDTypePayment": { "type": "string", "description": "Identificador do tipo de pagamento, devolvido como string." }, "TypePaymentDescription": { "type": "string", "description": "Descrição livre escolhida pela empresa (ex.: 'PIX recebimento', 'Cartão Cielo Crédito')." }, "Category": { "type": "integer", "description": "Categoria do tipo de pagamento (`TypePaymentCategory`). Valores comuns: 1=Cartão de Crédito, 2=Boleto Bancário, 3=MarketPlace E-Commerce, 4=Transferência Bancária, 5=PIX, 6=Cartão de Débito, 7=Dinheiro, 12=Outros, 13=Cheque, 14=Crédito loja, 15-18=Vales." }, "TypePaymentCategory": { "type": "string", "description": "Descrição da categoria (`Cartão de Crédito`, `PIX`, `Dinheiro`, etc.)." }, "TypePaymentCategoryLogoUrl": { "type": "string", "nullable": true, "description": "URL do ícone da categoria." }, "NfTBand": { "type": "string", "nullable": true, "description": "Bandeira (`NfTBand`) quando a categoria é cartão. Exemplos: 01=Visa, 02=Mastercard, 03=Amex, 06=Elo." }, "NfTBandDescription": { "type": "string", "nullable": true, "description": "Descrição da bandeira." }, "NfTBandLogoUrl": { "type": "string", "nullable": true, "description": "URL do logo da bandeira." }, "DaysDue": { "type": "integer", "nullable": true, "description": "Prazo padrão de vencimento (em dias) usado na geração de contas a pagar/receber a partir deste tipo." }, "DefaultOrder": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Quando 1, este tipo é o padrão sugerido em novas vendas." }, "DefaultPurchase": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Quando 1, este tipo é o padrão sugerido em novas compras." }, "EnableFrenteCaixa": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Quando 1, o tipo aparece como opção na tela do PDV (frente de caixa)." }, "IncludeComission": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Quando 1, vendas pagas com este tipo entram no relatório de comissão do vendedor." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora do cadastro." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do cadastro." } } }, "TypePaymentCreate": { "type": "object", "description": "Corpo de `POST /type/order/payment` e `PUT /type/order/payment/{idtypepayment}` (atualização total). Quando `Category` for `1` ou `6`, `NfTBand` é obrigatório.", "required": [ "TypePaymentDescription", "Category" ], "properties": { "TypePaymentDescription": { "type": "string", "description": "Descrição livre (ex.: 'PIX recebimento', 'Cartão Cielo Crédito')." }, "Category": { "type": "integer", "description": "Categoria do tipo (`IDTypePaymentCategory`). Quando `1` (Cartão de Crédito) ou `6` (Cartão de Débito), `NfTBand` passa a ser obrigatório." }, "NfTBand": { "type": "string", "nullable": true, "description": "Bandeira do cartão. Obrigatório para categorias 1 e 6." }, "DaysDue": { "type": "integer", "nullable": true, "description": "Prazo padrão de vencimento em dias." }, "DefaultOrder": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Marca como padrão para novas vendas." }, "DefaultPurchase": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Marca como padrão para novas compras." }, "EnableFrenteCaixa": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Habilita uso no PDV." }, "IncludeComission": { "type": "integer", "enum": [ 0, 1 ], "description": "Inclui vendas no relatório de comissão. Default `1` quando omitido." } } }, "TypePaymentRateItem": { "type": "object", "description": "Taxa adquirente vinculada a um tipo de pagamento. Cada item combina uma integração adquirente, um método de pagamento da integração (`TypePayment`), uma faixa de parcelas e uma vigência, com a taxa cobrada nesse cenário (MDR + AR ou taxa fixa).", "properties": { "IDTypePaymentRate": { "type": "integer", "format": "int32", "description": "Identificador da taxa." }, "IDTypePayment": { "type": "integer", "format": "int32", "description": "Tipo de pagamento ao qual a taxa pertence." }, "IDCompanyIntegration": { "type": "integer", "format": "int32", "description": "Integração adquirente (Cielo, Rede, MercadoPago, etc.)." }, "CompanyIntegrationName": { "type": "string", "description": "Nome amigável da integração adquirente configurado pela empresa." }, "IntegrationName": { "type": "string", "description": "Nome do tipo de integração (categoria do adquirente)." }, "IntegrationLogoUrl": { "type": "string", "nullable": true, "description": "URL do logotipo da integração adquirente (quando cadastrado)." }, "IDTypeCompanyIntegration": { "type": "integer", "format": "int32", "description": "Identificador do tipo de integração (categoria do adquirente — gateway, banco, ERP, etc.)." }, "IDTypePaymentFrom": { "type": "integer", "format": "int32", "description": "Método de pagamento na nomenclatura do adquirente (`IDTypePaymentFrom`)." }, "TypePayment": { "type": "string", "description": "Descrição do método de pagamento do adquirente (bandeira + modalidade)." }, "MinInstallment": { "type": "integer", "description": "Quantidade mínima de parcelas para a taxa valer." }, "MaxInstallment": { "type": "integer", "description": "Quantidade máxima de parcelas para a taxa valer." }, "DaysDue": { "type": "integer", "nullable": true, "description": "Prazo de liberação do adquirente, em dias." }, "MerchantDiscountRate": { "type": "number", "nullable": true, "description": "Taxa MDR (Merchant Discount Rate) como fração (0.0299 = 2,99%)." }, "AnticipationRate": { "type": "number", "nullable": true, "description": "Taxa de antecipação como fração." }, "FixedRate": { "type": "number", "nullable": true, "description": "Taxa fixa em R$ (alternativa a MDR + AR — quando `> 0`, MDR e AR ficam ignorados)." }, "DateFrom": { "type": "string", "format": "date", "description": "Início da vigência." }, "DateTo": { "type": "string", "format": "date", "description": "Fim da vigência." } } }, "TypePaymentRateCreate": { "type": "object", "description": "Corpo de `POST /type/order/payment/{idtypepayment}/rate`. Cria uma combinação integração + método + faixa de parcelas + vigência com a taxa correspondente. A taxa pode ser **MDR + AR** (deixe `FixedRate=0`) ou **fixa** (deixe `MerchantDiscountRate=0` e `AnticipationRate=0`). Taxas negativas são rejeitadas.", "required": [ "IDCompanyIntegration", "IDTypePaymentFrom", "MinInstallment", "MaxInstallment", "DateFrom", "DateTo" ], "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int32", "description": "Integração adquirente." }, "IDTypePaymentFrom": { "type": "integer", "format": "int32", "description": "Método de pagamento do adquirente (bandeira + modalidade)." }, "MinInstallment": { "type": "integer", "description": "Quantidade mínima de parcelas. Tem que ser menor ou igual a `MaxInstallment`." }, "MaxInstallment": { "type": "integer", "description": "Quantidade máxima de parcelas." }, "DaysDue": { "type": "integer", "nullable": true, "description": "Prazo de liberação do adquirente em dias." }, "MerchantDiscountRate": { "type": "number", "description": "Taxa MDR como fração (0.0299 = 2,99%). Não pode ser negativo." }, "AnticipationRate": { "type": "number", "description": "Taxa de antecipação como fração. Não pode ser negativo." }, "FixedRate": { "type": "number", "description": "Taxa fixa em R$. Não pode ser negativo." }, "DateFrom": { "type": "string", "format": "date", "description": "Início da vigência." }, "DateTo": { "type": "string", "format": "date", "description": "Fim da vigência. Não pode sobrepor com outras taxas da mesma integração e faixa de parcelas." } } }, "TypePaymentRateUpdate": { "type": "object", "description": "Corpo de `PUT /type/order/payment/{idtypepayment}/rate/{idtypepaymentrate}`. Atualização parcial — apenas campos enviados são alterados. Mesmas regras de sobreposição e taxas negativas do `POST`.", "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int32", "description": "Integração adquirente (Cielo, Rede, MercadoPago, etc.) à qual a taxa se aplica." }, "IDTypePaymentFrom": { "type": "integer", "format": "int32", "description": "Método de pagamento na nomenclatura do adquirente (`IDTypePaymentFrom` — combinação bandeira + modalidade)." }, "MinInstallment": { "type": "integer", "description": "Quantidade mínima de parcelas para a taxa valer. Tem que ser ≤ `MaxInstallment`." }, "MaxInstallment": { "type": "integer", "description": "Quantidade máxima de parcelas para a taxa valer." }, "DaysDue": { "type": "integer", "nullable": true, "description": "Prazo de liberação do adquirente, em dias." }, "MerchantDiscountRate": { "type": "number", "description": "Taxa MDR (Merchant Discount Rate) como fração decimal (`0.0299` = 2,99%). Não pode ser negativa." }, "AnticipationRate": { "type": "number", "description": "Taxa de antecipação como fração decimal. Não pode ser negativa." }, "FixedRate": { "type": "number", "description": "Taxa fixa em R$ — alternativa a MDR + AR. Não pode ser negativa." }, "DateFrom": { "type": "string", "format": "date", "description": "Início da vigência da taxa (formato `YYYY-MM-DD`)." }, "DateTo": { "type": "string", "format": "date", "description": "Fim da vigência da taxa (formato `YYYY-MM-DD`). Não pode sobrepor com outras taxas da mesma integração e faixa de parcelas." } } }, "TypeCostCenterListItem": { "type": "object", "description": "Item da resposta de `GET /type/account/cost-center`. Centros de custo são usados para ratear o valor de uma conta a pagar/receber entre departamentos, projetos ou filiais.", "properties": { "IDTypeCostCenter": { "type": "integer", "format": "int32", "description": "Identificador do centro de custo." }, "TypeCostCenter": { "type": "string", "description": "Descrição do centro de custo (ex.: 'Marketing', 'TI - Infraestrutura')." }, "ExternalCode": { "type": "string", "nullable": true, "description": "Código externo opcional, usado para casar com sistemas terceiros (ERP, integração contábil)." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa dona do centro de custo." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do cadastro." }, "Status": { "type": "integer", "enum": [ 1 ], "description": "Sempre `1` (apenas ativos são listados)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora do cadastro." } } }, "TypeCostCenterCreate": { "type": "object", "description": "Corpo de `POST /type/account/cost-center` e `PUT /type/account/cost-center/{idtypecostcenter}`. Quando `ExternalCode` for informado, precisa ser único dentro da empresa entre os centros ativos.", "required": [ "TypeCostCenter" ], "properties": { "TypeCostCenter": { "type": "string", "description": "Descrição do centro de custo." }, "ExternalCode": { "type": "string", "nullable": true, "description": "Código externo opcional. Quando informado, precisa ser único na empresa." } } }, "TypeOrderListItem": { "type": "object", "description": "Item de `GET /type/order/type`. Inclui descrições de política comercial, faturador, armazém padrão e de devolução, tipo de retorno simbólico e devolução, plano de contas, centro de custo e finalidade NFe.", "properties": { "IDTypeOrder": { "type": "string", "description": "Identificador do tipo de pedido (devolvido como string)." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do tipo de pedido." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa dona do tipo de pedido." }, "TypeOrder": { "type": "string", "description": "Descrição do tipo de pedido." }, "OrderPrefix": { "type": "string", "description": "Prefixo (sigla) dos pedidos deste tipo." }, "IDCompanySalesPolicy": { "type": "integer", "format": "int32", "description": "Política comercial vinculada." }, "CompanySalesPolicy": { "type": "string", "description": "Descrição da política comercial." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` quando este é o tipo padrão da empresa. Apenas um pode estar marcado." }, "Resend": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` quando este é o tipo padrão para reenvio. Apenas um por empresa." }, "Return": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` quando este é o tipo padrão para devolução. Apenas um por empresa." }, "SymbolicReturn": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` quando este é o tipo padrão para retorno simbólico. Apenas um por empresa." }, "IncludeValueDashboard": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando o valor dos pedidos deste tipo entra nos indicadores do dashboard." }, "CreateBankSlipAfterInvoice": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para gerar boleto automaticamente após a emissão da nota fiscal." }, "RecalculateAccountsDueDateAfterInvoice": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para recalcular a data de vencimento das contas a receber a partir da emissão da nota fiscal." }, "BlockInvoiceToCompanySameDocument": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para bloquear NF quando o CNPJ do cliente é o mesmo do faturador." }, "BalanceChange": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` (padrão) movimenta o estoque; `0` não movimenta." }, "IssueNFCe": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para emitir NFCe (modelo 65) em vez de NFe." }, "MinimumMarkup": { "type": "number", "nullable": true, "description": "Markup mínimo exigido para finalizar pedidos. Abaixo só com privilégio." }, "InvoiceIntermedCNPJ": { "type": "string", "nullable": true, "description": "CNPJ que sobrescreve o intermediador da NFe (`infIntermed`)." }, "BlockSkuZeroValue": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para bloquear finalização do pedido quando há itens com valor de venda zero." }, "TypeOrderNfeindFinal": { "type": "integer", "nullable": true, "description": "Indicador `indFinal` padrão (`0` Normal, `1` Consumidor final)." }, "IndFinalDescription": { "type": "string", "nullable": true, "description": "Descrição amigável do `TypeOrderNfeindFinal`." }, "TypeOrderNfeComments": { "type": "string", "nullable": true, "description": "Texto fixo de comentário da NFe." }, "NfeFactorPercent": { "type": "number", "description": "Fator multiplicador do valor a faturar na NFe de produto e de serviço. Padrão `1.0000`." }, "EnableFrenteCaixa": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para exibir no módulo Frente de Caixa (PDV)." }, "CarrierQuotation": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` para realizar cotação automática de frete na finalização." }, "ConsumerVoucherDefault": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para gerar vale (crédito) por padrão na devolução." }, "OrderFinishConfirmation": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para pedir confirmação de finalização do pedido ao baixar o último título do contas a receber." }, "IsTransfer": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando o tipo é **transferência** entre filiais." }, "ServiceRequest": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando o tipo representa **ordem de serviço**." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Faturador (filial) padrão para emissão de NF." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Subdomínio do faturador." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social do faturador." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "format": "int32", "nullable": true, "description": "Armazém padrão para pedidos deste tipo." }, "WarehouseName": { "type": "string", "nullable": true, "description": "Nome do armazém padrão." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "format": "int32", "nullable": true, "description": "Centro de distribuição vinculado ao armazém padrão." }, "IDStockKeepingUnitWarehouseReturn": { "type": "integer", "format": "int32", "nullable": true, "description": "Armazém padrão para devolução." }, "WarehouseNameReturn": { "type": "string", "nullable": true, "description": "Nome do armazém de devolução padrão (`IDStockKeepingUnitWarehouseReturn`)." }, "MaximumDiscountPerItem": { "type": "number", "nullable": true, "description": "Percentual máximo de desconto por item (fração decimal entre 0 e 1)." }, "SafetyStockPercent": { "type": "number", "nullable": true, "description": "Percentual de estoque de segurança não exibido em pedidos manuais." }, "AutomaticCancelOpenOrderAfterHour": { "type": "integer", "nullable": true, "description": "Horas para cancelamento automático de pedido em aberto." }, "IDTypeOrderSymbolicStorageReturn": { "type": "integer", "format": "int32", "nullable": true, "description": "Tipo de pedido usado para gerar NF de retorno simbólico de armazenagem." }, "TypeOrderSymbolicStorageReturn": { "type": "string", "nullable": true, "description": "Descrição amigável do `IDTypeOrderSymbolicStorageReturn`." }, "IncludeInboundInvoiceReferenceKey": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para referenciar a chave da NF de entrada na NF de saída." }, "CfopConsiderSymbolicStorageReturn": { "type": "string", "nullable": true, "description": "CFOPs (separados por vírgula) a considerar como retorno simbólico." }, "NFeFinReturn": { "type": "integer", "nullable": true, "description": "Finalidade da NFe de retorno (`finNFe`)." }, "FinNfeDescription": { "type": "string", "nullable": true, "description": "Descrição da finalidade." }, "IDTypeOrderDefaultReturn": { "type": "integer", "format": "int32", "nullable": true, "description": "Tipo de pedido usado como devolução padrão a partir deste tipo." }, "TypeOrderDefaultReturn": { "type": "string", "nullable": true, "description": "Descrição amigável do `IDTypeOrderDefaultReturn`." }, "TypeOrderOrderPriority": { "type": "integer", "nullable": true, "description": "Prioridade no WMS (`0` mais alta, `10` mais baixa)." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Plano de contas padrão para contas a receber geradas pelos pedidos." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas." }, "IDTypeCostCenter": { "type": "integer", "format": "int32", "nullable": true, "description": "Centro de custo padrão." }, "TypeCostCenter": { "type": "string", "nullable": true, "description": "Descrição do centro de custo." }, "HandlingDays": { "type": "integer", "nullable": true, "description": "Dias de manuseio considerados no cálculo da data limite de expedição." }, "ShippingCutTime": { "type": "string", "nullable": true, "description": "Horário de corte para expedição (`HH:mm:ss`)." } } }, "TypeOrderDetail": { "type": "object", "description": "Resposta de `GET /type/order/type/{idordertype}`. Mesmos campos de `TypeOrderListItem` mais a lista de regras fiscais `TypeOrderTax[]`.", "allOf": [ { "$ref": "#/components/schemas/TypeOrderListItem" }, { "type": "object", "properties": { "TypeOrderTax": { "type": "array", "description": "Regras fiscais aplicáveis a este tipo de pedido — uma entrada por departamento fiscal cadastrado nos SKUs da empresa. `IDTax` vem nulo quando ainda não há regra associada.", "items": { "type": "object", "properties": { "IDTaxDepartment": { "type": "integer", "format": "int32", "description": "Identificador do departamento fiscal vinculado ao tipo de pedido." }, "TaxDepartmentDescription": { "type": "string", "description": "Nome do departamento fiscal." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa dona do tipo de pedido." }, "AccountName": { "type": "string", "description": "Conta (prefixo) da empresa." }, "CompanyNameCorporateName": { "type": "string", "description": "Razão social da empresa." }, "CompanyTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia da empresa." }, "IDTypeOrderTax": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da regra fiscal padrão do tipo de pedido, quando configurada." }, "IDTax": { "type": "integer", "format": "int32", "nullable": true, "description": "Regra fiscal aplicada a este par tipo de pedido + departamento." }, "TypeTaxName": { "type": "string", "nullable": true, "description": "Nome da regra fiscal padrão." }, "RecordTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora do cadastro do tipo de pedido." } } } } } } ] }, "TypeOrderCreate": { "type": "object", "description": "Corpo de `POST /type/order/type` e `PUT /type/order/type/{idordertype}`. **Apenas um tipo por empresa pode estar marcado** como `Default`, `Resend`, `Return` ou `SymbolicReturn` — marcar qualquer um destes em `1` desmarca o anterior automaticamente.", "required": [ "TypeOrder", "OrderPrefix", "IDCompanySalesPolicy" ], "properties": { "TypeOrder": { "type": "string", "description": "Descrição do tipo de pedido." }, "OrderPrefix": { "type": "string", "description": "Prefixo (sigla) usado para identificar os pedidos deste tipo." }, "IDCompanySalesPolicy": { "type": "integer", "format": "int32", "description": "Política comercial vinculada (obrigatória)." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para marcar como tipo padrão da empresa (desmarca o anterior)." }, "Resend": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para marcar como padrão de reenvio (desmarca o anterior)." }, "Return": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para marcar como padrão de devolução (desmarca o anterior)." }, "SymbolicReturn": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para marcar como padrão de retorno simbólico (desmarca o anterior)." }, "IncludeValueDashboard": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para incluir o valor dos pedidos no dashboard. Default `0` no POST." }, "CreateBankSlipAfterInvoice": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para gerar boleto automaticamente após a emissão da NFe. Default `0`." }, "RecalculateAccountsDueDateAfterInvoice": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para recalcular o vencimento das contas a receber a partir da emissão da NFe. Default `0`." }, "BlockInvoiceToCompanySameDocument": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para bloquear NFe quando o CNPJ do cliente é o do faturador. Default `0`." }, "BalanceChange": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` (default) movimenta estoque; `0` não." }, "IssueNFCe": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para emitir NFCe. Default `0`." }, "MinimumMarkup": { "type": "number", "nullable": true, "description": "Markup mínimo exigido." }, "InvoiceIntermedCNPJ": { "type": "string", "nullable": true, "description": "CNPJ a usar como intermediador da NFe." }, "BlockSkuZeroValue": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para bloquear item com valor zero. Default `1` no POST." }, "TypeOrderNfeindFinal": { "type": "integer", "nullable": true, "description": "`indFinal` padrão (`0` Normal, `1` Consumidor final)." }, "TypeOrderNfeComments": { "type": "string", "nullable": true, "description": "Texto fixo de comentário da NFe." }, "EnableFrenteCaixa": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para exibir este tipo no Frente de Caixa." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Faturador (filial). Precisa ser filial da própria empresa." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "format": "int32", "nullable": true, "description": "Armazém padrão para pedidos deste tipo. Precisa estar ativo." }, "IDStockKeepingUnitWarehouseReturn": { "type": "integer", "format": "int32", "nullable": true, "description": "Armazém padrão para devoluções." }, "CarrierQuotation": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para cotar frete automaticamente." }, "MaximumDiscountPerItem": { "type": "number", "nullable": true, "description": "Percentual máximo de desconto por item." }, "SafetyStockPercent": { "type": "number", "nullable": true, "description": "Percentual de estoque de segurança." }, "AutomaticCancelOpenOrderAfterHour": { "type": "integer", "nullable": true, "description": "Horas para cancelamento automático de pedido em aberto." }, "IDTypeOrderSymbolicStorageReturn": { "type": "integer", "format": "int32", "nullable": true, "description": "Tipo de pedido para gerar NF de retorno simbólico." }, "IncludeInboundInvoiceReferenceKey": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para referenciar chave da NF de entrada." }, "CfopConsiderSymbolicStorageReturn": { "type": "string", "nullable": true, "description": "CFOPs (separados por vírgula) a considerar como retorno simbólico." }, "ConsumerVoucherDefault": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para gerar vale por padrão na devolução." }, "NFeFinReturn": { "type": "integer", "nullable": true, "description": "Finalidade da NFe de retorno." }, "TypeOrderOrderPriority": { "type": "integer", "minimum": 0, "maximum": 10, "nullable": true, "description": "Prioridade no WMS (0–10)." }, "IDTypeAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Plano de contas padrão." }, "IDTypeCostCenter": { "type": "integer", "format": "int32", "nullable": true, "description": "Centro de custo padrão." }, "OrderFinishConfirmation": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` para confirmar finalização no último pagamento." }, "HandlingDays": { "type": "integer", "nullable": true, "description": "Dias de manuseio." }, "ShippingCutTime": { "type": "string", "nullable": true, "description": "Horário de corte (`HH:mm:ss`)." }, "IsTransfer": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` quando o tipo é transferência entre filiais. Default `0`." }, "ServiceRequest": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` quando o tipo representa ordem de serviço. Default `0`." }, "IDTypeOrderDefaultReturn": { "type": "integer", "format": "int32", "nullable": true, "description": "Tipo de pedido usado como devolução padrão." } } }, "PurchaseCfopInboundListItem": { "type": "object", "description": "Item de `GET /purchase/cfop-inbound`. Cada par `CfopFrom → CfopTo` define uma reescrita de CFOP aplicada ao receber NF-e: quando o CFOP do item da NF-e bate com `CfopFrom`, o movimento de estoque é gravado com `CfopTo`.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da regra." }, "IDStockKeepingUnitPurchaseCfopInbound": { "type": "integer", "format": "int32", "description": "Identificador da regra." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa dona da regra." }, "CfopFrom": { "type": "integer", "description": "CFOP de origem (o que vem na NF-e do fornecedor). Inteiro de 4 dígitos." }, "CfopFromDescription": { "type": "string", "description": "Descrição oficial do CFOP de origem (catálogo nacional)." }, "CfopTo": { "type": "integer", "description": "CFOP de destino (o que substituirá `CfopFrom` no movimento de estoque). Inteiro de 4 dígitos." }, "CfopToDescription": { "type": "string", "description": "Descrição oficial do CFOP de destino (catálogo nacional)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de cadastro." } } }, "PurchaseCfopInboundCreate": { "type": "object", "description": "Corpo do `POST /purchase/cfop-inbound`. Ambos os campos são obrigatórios e precisam corresponder a CFOPs existentes no catálogo nacional.", "required": [ "CfopFrom", "CfopTo" ], "properties": { "CfopFrom": { "type": "integer", "description": "CFOP de origem. Inteiro de 4 dígitos. Precisa existir no catálogo nacional de CFOPs." }, "CfopTo": { "type": "integer", "description": "CFOP de destino. Inteiro de 4 dígitos. Precisa existir no catálogo nacional de CFOPs." } } }, "PurchaseCfopInboundUpdate": { "type": "object", "description": "Corpo do `PUT /purchase/cfop-inbound/{idstockkeepingunitpurchasecfopinbound}`. Os dois campos são sobrescritos a cada chamada (não é atualização parcial).", "required": [ "CfopFrom", "CfopTo" ], "properties": { "CfopFrom": { "type": "integer", "description": "CFOP de origem. Inteiro de 4 dígitos. Precisa existir no catálogo nacional de CFOPs." }, "CfopTo": { "type": "integer", "description": "CFOP de destino. Inteiro de 4 dígitos. Precisa existir no catálogo nacional de CFOPs." } } }, "CompanyLabelListItem": { "type": "object", "description": "Modelo de etiqueta cadastrado pela empresa. Cada modelo combina uma categoria de uso (`TypeLabelCategory`), as dimensões em centímetros e o conteúdo — código ZPL bruto (modo 2) ou layout de canvas com variáveis (modo 1, gerado pelo editor visual).", "properties": { "IDCompanyLabel": { "type": "integer", "format": "int32", "description": "Identificador do modelo de etiqueta." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa dona do modelo." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do cadastro." }, "LabelName": { "type": "string", "description": "Nome livre do modelo (ex.: 'Etiqueta Embarque Correios 10x10')." }, "IDTypeLabelCategory": { "type": "integer", "format": "int32", "description": "Categoria do uso da etiqueta." }, "TypeLabelCategory": { "type": "string", "description": "Descrição da categoria (`Embarque (adicional transportadora)`, `Itens (recebimento)`, `Endereços`, etc.)." }, "HeightCm": { "type": "number", "description": "Altura da etiqueta em centímetros. Limitada a 20 cm pelo front." }, "WidthCm": { "type": "number", "description": "Largura da etiqueta em centímetros. Limitada a 20 cm pelo front." }, "Columns": { "type": "integer", "nullable": true, "description": "Quantidade de colunas (por linha) quando a etiqueta é impressa em layout multi-coluna." }, "BetweenColumnsCm": { "type": "number", "nullable": true, "description": "Espaçamento horizontal entre colunas, em centímetros." }, "EditorMode": { "type": "integer", "enum": [ 1, 2 ], "description": "Modo de edição: 1=Canvas (layout visual com variáveis e elementos), 2=ZPL (código bruto)." }, "LabelZpl": { "type": "string", "nullable": true, "description": "Código ZPL da etiqueta. No modo 2 é o código informado direto pelo usuário; no modo 1 o front gera o ZPL a partir do layout. Pode ser nulo enquanto a etiqueta ainda está sendo desenhada." }, "LogoWidth": { "type": "number", "nullable": true, "description": "Largura do logo dentro da etiqueta (modo Canvas)." }, "LogoHeight": { "type": "number", "nullable": true, "description": "Altura do logo dentro da etiqueta (modo Canvas)." }, "WordCountLimit": { "type": "integer", "nullable": true, "description": "Limite de caracteres usado em textos com truncagem (modo Canvas)." } } }, "CompanyLabelCreate": { "type": "object", "description": "Corpo de `POST /company/label`. Cria um modelo de etiqueta para a empresa autenticada.", "required": [ "LabelName", "IDTypeLabelCategory", "HeightCm", "WidthCm" ], "properties": { "LabelName": { "type": "string", "description": "Nome livre do modelo." }, "IDTypeLabelCategory": { "type": "integer", "format": "int32", "description": "Categoria do uso (precisa existir em `TypeLabelCategory`)." }, "HeightCm": { "type": "number", "description": "Altura em cm. Front limita a 20 cm." }, "WidthCm": { "type": "number", "description": "Largura em cm. Front limita a 20 cm." }, "Columns": { "type": "integer", "nullable": true, "description": "Quantidade de etiquetas por linha quando a folha tem layout multi-coluna (modo Canvas). Default 1." }, "BetweenColumnsCm": { "type": "number", "nullable": true, "description": "Espaçamento horizontal entre colunas, em centímetros (modo Canvas)." }, "EditorMode": { "type": "integer", "enum": [ 1, 2 ], "description": "1=Canvas (default quando omitido), 2=ZPL." }, "LabelZpl": { "type": "string", "nullable": true, "description": "Código ZPL bruto. Obrigatório quando `EditorMode=2`; no modo Canvas (1) é gerado pelo front a partir do layout." }, "LogoWidth": { "type": "number", "nullable": true, "description": "Largura do logotipo dentro da etiqueta, em pixels (modo Canvas)." }, "LogoHeight": { "type": "number", "nullable": true, "description": "Altura do logotipo dentro da etiqueta, em pixels (modo Canvas)." }, "WordCountLimit": { "type": "integer", "nullable": true, "description": "Limite de caracteres aplicado a textos com truncagem na etiqueta (modo Canvas)." } } }, "CompanyLabelUpdate": { "type": "object", "description": "Corpo de `PUT /company/label/{idcompanylabel}`. Atualização parcial — apenas campos enviados são alterados.", "properties": { "LabelName": { "type": "string", "description": "Nome livre do modelo." }, "IDTypeLabelCategory": { "type": "integer", "format": "int32", "description": "Categoria do uso (precisa existir em `TypeLabelCategory`)." }, "HeightCm": { "type": "number", "description": "Altura em cm. Front limita a 20 cm." }, "WidthCm": { "type": "number", "description": "Largura em cm. Front limita a 20 cm." }, "Columns": { "type": "integer", "nullable": true, "description": "Quantidade de etiquetas por linha quando a folha tem layout multi-coluna (modo Canvas)." }, "BetweenColumnsCm": { "type": "number", "nullable": true, "description": "Espaçamento horizontal entre colunas, em centímetros (modo Canvas)." }, "EditorMode": { "type": "integer", "enum": [ 1, 2 ], "description": "1=Canvas (layout visual com variáveis), 2=ZPL (código bruto)." }, "LabelZpl": { "type": "string", "nullable": true, "description": "Código ZPL bruto. Obrigatório quando `EditorMode=2`; no modo Canvas (1) é gerado pelo front a partir do layout." }, "LogoWidth": { "type": "number", "nullable": true, "description": "Largura do logotipo dentro da etiqueta, em pixels (modo Canvas)." }, "LogoHeight": { "type": "number", "nullable": true, "description": "Altura do logotipo dentro da etiqueta, em pixels (modo Canvas)." }, "WordCountLimit": { "type": "integer", "nullable": true, "description": "Limite de caracteres aplicado a textos com truncagem na etiqueta (modo Canvas)." } } }, "TypeOrderStatusListItem": { "type": "object", "description": "Item da resposta de `GET /type/order/status`. Cada item representa o vínculo de um status fixo do sistema (`IDStatusOrder`) com a empresa, contendo o **nome local** (`StatusOrder`, editável), a **cor** (`StatusColorCode`) e a **descrição padrão** (`StatusOrderDescription`, do sistema — não editável).", "properties": { "IDStatusOrder": { "type": "string", "description": "Identificador do status (devolvido como string via `CAST AS CHAR`). Lista fixa do sistema — valores comuns: 0=Aberto, 1=Fechado, 2=Iniciado picking, 3=Pré picking-list, 4=Finalizado picking, 5=Segurar pedido, 6=Aguardando expedição, 7=Enviado, 8=Entregue com sucesso, 9=Em espera, 10=Picking não conformidade, 11=Falta produto, 12=Falta produto a chegar, 13=Em tratativa, 14=Packing não conformidade, 15=Aguardando etiqueta, 16=Nota Fiscal, 17=Aguardando retirada, 19=Aguardando transportadora, 20=Em separação, 21=A faturar, 22=Aguardando romaneio, 23=Em espera etiqueta, 31=Aguardando aprovação crédito, 50-56=Orçamento e fluxos de aprovação, 70-79=Ordem de Serviço (OS), 89=Pagamento pendente canal, 90=Cancelado, 91=Extraviado, 92=Extraviado parcialmente, 93=Em Produção, 94=Devolvido, 95=Em devolução, 96=Fulfillment, 97=Reversa finalizada, 100=Deletado." }, "TypeStatusOrderCompany": { "type": "integer", "format": "int32", "description": "Chave primária do vínculo do status com a empresa (`IDTypeStatusOrderCompany`)." }, "StatusOrder": { "type": "string", "description": "Nome **local** do status, editável pela empresa nesta tela. Inicia com o nome padrão do sistema (`StatusOrderDescription`)." }, "StatusColorCode": { "type": "string", "nullable": true, "description": "Cor (geralmente um hexadecimal `#RRGGBB`) usada para destacar o status em listas e gráficos. Pode ser nula." }, "StatusOrderDescription": { "type": "string", "nullable": true, "description": "Descrição padrão do status no sistema (`StatusOrderDescription`) — não editável. Explica o que o status significa no fluxo." }, "Order": { "type": "number", "nullable": true, "description": "Posição numérica do status no fluxo (`Order`). Usada para ordenar a lista e desenhar a linha do tempo do pedido." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." } } }, "TypeOrderStatusUpdate": { "type": "object", "description": "Corpo de `PUT /type/order/status/{idstatusorder}`. **Apenas dois campos podem ser alterados** — nome local e cor.", "properties": { "StatusOrder": { "type": "string", "description": "Novo nome local do status (apresentado no idworks para os usuários da empresa). Obrigatório no front." }, "StatusColorCode": { "type": "string", "nullable": true, "description": "Cor que destaca o status em listas e gráficos. Geralmente um hexadecimal `#RRGGBB`. Pode ser nulo." } } }, "CompanySalesPolicyListItem": { "type": "object", "description": "Política comercial (tabela de preço) da empresa. Cada política agrupa os preços dos produtos para um cenário de venda — atacado, varejo, e-commerce, lojas específicas, distribuidores. Os campos relacionados à política base (`IDCompanySalesPolicyFrom`, `IDTypeCompanySalesPolicyOperation`, `OperationValue`, `PriceRounding`) só são preenchidos quando o tipo é Relativa (3).", "properties": { "IDCompanySalesPolicy": { "type": "integer", "format": "int32", "description": "Identificador da política comercial." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa dona da política." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." }, "CompanySalesPolicy": { "type": "string", "description": "Nome da política comercial (ex.: 'Tabela Atacado', 'Site E-commerce', 'Loja Centro')." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "1 quando esta é a política padrão da empresa (usada em vendas que não apontam para uma política específica). Apenas uma política por empresa pode ser padrão." }, "IDTypeCompanySalesPolicy": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Tipo da política: 1=Normal (preço cadastrado manualmente), 2=Custo médio (acompanha o custo médio do produto), 3=Relativa (calculada a partir de outra política)." }, "TypeCompanySalesPolicy": { "type": "string", "description": "Descrição do tipo (`Normal`, `Custo médio`, `Relativa à outra política`)." }, "Markup": { "type": "number", "nullable": true, "description": "Markup médio aplicado a esta política. Usado no recebimento de mercadoria para auxiliar na atualização do preço de venda. Aplicável a políticas Normal e Custo médio." }, "CostAverage": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Flag legada — `1` quando a política historicamente seguia o custo médio. Hoje a indicação correta é `IDTypeCompanySalesPolicy=2`." }, "IDCompanySalesPolicyFrom": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo Relativa) Identificador da política comercial base usada como referência. A política base precisa ser do tipo Normal ou Custo médio." }, "CompanySalesPolicyFrom": { "type": "string", "nullable": true, "description": "(Tipo Relativa) Nome da política comercial base." }, "IDTypeCompanySalesPolicyOperation": { "type": "integer", "enum": [ 1, 2 ], "nullable": true, "description": "(Tipo Relativa) Operação aplicada sobre a política base: 1=Multiplicação (ex.: base × 1.5), 2=Soma (ex.: base + 10,00). Valores negativos em `OperationValue` permitem reduzir o preço da base." }, "TypeCompanySalesPolicyOperation": { "type": "string", "nullable": true, "description": "(Tipo Relativa) Descrição da operação (`Multiplicação` ou `Soma`)." }, "OperationValue": { "type": "number", "nullable": true, "description": "(Tipo Relativa) Valor da operação. Para Multiplicação, é o fator multiplicador (ex.: 1.5 = +50%); para Soma, é o valor somado/subtraído (negativo reduz o preço da base)." }, "PriceRounding": { "type": "number", "nullable": true, "description": "(Tipo Relativa) Valor entre 0 e 0,99 usado para arredondar o preço calculado (ex.: 0,99 faz o preço terminar sempre em ,99)." } } }, "CompanySalesPolicyCreate": { "type": "object", "description": "Corpo de `POST /company/sales-policy`. Quando `IDTypeCompanySalesPolicy=3` (Relativa), os campos `IDCompanySalesPolicyFrom`, `IDTypeCompanySalesPolicyOperation` e `OperationValue` são obrigatórios.", "required": [ "CompanySalesPolicy" ], "properties": { "CompanySalesPolicy": { "type": "string", "description": "Nome da política comercial." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Quando 1, marca esta política como padrão (desmarca a anterior automaticamente)." }, "IDTypeCompanySalesPolicy": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Tipo: 1=Normal, 2=Custo médio, 3=Relativa. Default `1` quando omitido." }, "Markup": { "type": "number", "nullable": true, "description": "Markup médio (apenas tipos Normal e Custo médio)." }, "IDCompanySalesPolicyFrom": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo Relativa, obrigatório) Política base. Precisa ser Normal ou Custo médio — não aceita outra política Relativa." }, "IDTypeCompanySalesPolicyOperation": { "type": "integer", "enum": [ 1, 2 ], "nullable": true, "description": "(Tipo Relativa, obrigatório) 1=Multiplicação, 2=Soma." }, "OperationValue": { "type": "number", "nullable": true, "description": "(Tipo Relativa, obrigatório) Valor da operação. Negativos são aceitos para reduzir o preço da base." }, "PriceRounding": { "type": "number", "nullable": true, "description": "(Tipo Relativa) Arredondamento entre 0 e 0,99 (ex.: 0,99 faz o preço terminar em ,99)." }, "CostAverage": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Flag legada. Default `0`. Prefira usar `IDTypeCompanySalesPolicy=2` para Custo médio." } } }, "CompanySalesPolicyUpdate": { "type": "object", "description": "Corpo de `PUT /company/sales-policy/{idcompanysalespolicy}`. Somente o nome `CompanySalesPolicy` e a marca padrão `Default` são aplicados de forma parcial (só mudam se enviados). Os demais campos são sempre regravados: quando omitidos voltam ao padrão (`IDTypeCompanySalesPolicy`→1 Normal, `CostAverage`→0, `Markup`/`IDCompanySalesPolicyFrom`/`IDTypeCompanySalesPolicyOperation`/`OperationValue`/`PriceRounding`→nulo), zerando a configuração de política Relativa. Envie a configuração completa a cada atualização. Quando `IDTypeCompanySalesPolicy=3` (Relativa), `IDCompanySalesPolicyFrom`, `IDTypeCompanySalesPolicyOperation` e `OperationValue` são obrigatórios.", "properties": { "CompanySalesPolicy": { "type": "string", "description": "Nome da política comercial (ex.: 'Tabela Atacado', 'E-commerce', 'Distribuidor SP'). Aplicado de forma parcial — só muda se enviado." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "Aplicado de forma parcial — só muda se enviado. Quando 1, marca como padrão (desmarca a anterior). Quando 0, o sistema bloqueia se essa for a única padrão da empresa." }, "IDTypeCompanySalesPolicy": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Tipo da política: 1=Normal (preço cadastrado manualmente), 2=Custo médio (acompanha o custo médio do produto), 3=Relativa (calculada a partir de outra política). Quando omitido, volta para 1=Normal." }, "Markup": { "type": "number", "nullable": true, "description": "Markup médio aplicado a esta política. Usado no recebimento de mercadoria para auxiliar na atualização do preço de venda. Aplicável a políticas Normal e Custo médio. Quando omitido, é limpo (nulo)." }, "IDCompanySalesPolicyFrom": { "type": "integer", "format": "int32", "nullable": true, "description": "(Tipo Relativa) Identificador da política base usada como referência. A política base precisa ser do tipo Normal ou Custo médio. Quando omitido, é limpo (nulo)." }, "IDTypeCompanySalesPolicyOperation": { "type": "integer", "enum": [ 1, 2 ], "nullable": true, "description": "(Tipo Relativa) Operação aplicada sobre a política base: 1=Multiplicação (ex.: base × 1,5), 2=Soma (ex.: base + 10,00). Valores negativos em `OperationValue` permitem reduzir o preço da base. Quando omitido, é limpo (nulo)." }, "OperationValue": { "type": "number", "nullable": true, "description": "(Tipo Relativa) Valor da operação. Para Multiplicação, é o fator multiplicador; para Soma, é o valor somado/subtraído (negativo reduz o preço). Quando omitido, é limpo (nulo)." }, "PriceRounding": { "type": "number", "nullable": true, "description": "(Tipo Relativa) Valor entre 0 e 0,99 usado para arredondar o preço calculado (ex.: 0,99 faz o preço terminar sempre em ,99). Quando omitido, é limpo (nulo)." }, "CostAverage": { "type": "integer", "enum": [ 0, 1 ], "description": "Flag legada — `1` quando a política historicamente seguia o custo médio. Hoje a indicação correta é `IDTypeCompanySalesPolicy=2`. Quando omitido, volta para 0." } } }, "CarrierModalListItem": { "type": "object", "description": "Modalidade de transportadora da empresa. Cada modalidade descreve a forma de operação logística — exemplos comuns: Rodoviário, Aéreo, Marítimo, Fluvial, Próprio, Motoboy, Drone, Bicicleta.", "properties": { "IDCarrierModal": { "type": "integer", "format": "int32", "description": "Identificador da modalidade de transportadora." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador interno da empresa dona da modalidade." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." }, "CarrierModal": { "type": "string", "description": "Nome da modalidade." } } }, "CarrierModalCreate": { "type": "object", "description": "Corpo de `POST /carrier/modal` e `PUT /carrier/modal/{idcarriermodal}`. Apenas um campo — o nome da modalidade. Precisa ser único dentro da empresa.", "required": [ "CarrierModal" ], "properties": { "CarrierModal": { "type": "string", "description": "Nome da modalidade (ex.: 'Rodoviário', 'Aéreo', 'Motoboy'). Precisa ser único na empresa." } } }, "CompanyDetail": { "type": "object", "description": "Cadastro completo da empresa autenticada — todos os campos do cadastro da empresa mais agregados de inscrições estaduais, créditos do Simples e descrições resolvidas. A senha do certificado (`CertificadoPassword`) é sempre devolvida como `null` por segurança.", "properties": { "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa." }, "AccountName": { "type": "string", "description": "Subdomínio único da empresa no idworks (ex.: 'minhaempresa' → minhaempresa.idworks.com.br)." }, "CompanyStatus": { "type": "integer", "description": "Status do cadastro (ativo/inativo)." }, "CompanyNameCorporateName": { "type": "string", "description": "Razão social." }, "CompanyTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia." }, "CompanyCpfCnpj": { "type": "string", "description": "CNPJ ou CPF da empresa (somente dígitos)." }, "CompanyAddressPostalCode": { "type": "string", "nullable": true, "description": "CEP." }, "CompanyAddressStreet": { "type": "string", "nullable": true, "description": "Logradouro." }, "CompanyAddressNumber": { "type": "string", "nullable": true, "description": "Número do endereço." }, "CompanyAddressComplement": { "type": "string", "nullable": true, "description": "Complemento do endereço." }, "CompanyAddressNeighborhood": { "type": "string", "nullable": true, "description": "Bairro." }, "CompanyAddressCity": { "type": "string", "nullable": true, "description": "Cidade." }, "CompanyAddressState": { "type": "string", "nullable": true, "description": "Sigla da UF." }, "CompanyAddressIbgeCityCode": { "type": "string", "nullable": true, "description": "Código IBGE da cidade — atualizado automaticamente quando o CEP muda." }, "CompanyTelephone": { "type": "string", "nullable": true, "description": "Telefone de contato." }, "CompanyCityInscription": { "type": "string", "nullable": true, "description": "Inscrição municipal." }, "WebSiteUrl": { "type": "string", "nullable": true, "description": "URL do site da empresa, exibida em documentos fiscais e na frente de loja." }, "CompanyLogoUrl": { "type": "string", "nullable": true, "description": "URL do logotipo no bucket público do idworks." }, "CompanyLogoUrlThumbnail": { "type": "string", "nullable": true, "description": "URL do logotipo com sufixo `-thumbnail` (versão pequena gerada pelo CDN)." }, "NfeRegimeTributario": { "type": "integer", "nullable": true, "description": "Regime tributário (CRT): 1=Simples Nacional, 2=Simples Nacional excesso sublimite, 3=Regime Normal, 4=MEI." }, "CrtDescription": { "type": "string", "nullable": true, "description": "Descrição do regime tributário." }, "NfeSerie": { "type": "string", "nullable": true, "description": "Série atual da NFe modelo 55. Máximo 999." }, "NfeUltima": { "type": "integer", "nullable": true, "description": "Número da última NFe modelo 55 emitida." }, "NfeFeedStatus": { "type": "integer", "nullable": true, "description": "1 quando a empresa tem feed NFe ativo." }, "SefazAmbienteNF": { "type": "integer", "nullable": true, "description": "Ambiente de emissão NFe: 1=Produção, 2=Homologação." }, "NfceSerie": { "type": "string", "nullable": true, "description": "Série atual da NFCe (modelo 65)." }, "NfceUltima": { "type": "integer", "nullable": true, "description": "Número da última NFCe emitida." }, "NfceCSC": { "type": "string", "nullable": true, "description": "Código de Segurança do Contribuinte (CSC) da NFCe." }, "NfceCSCid": { "type": "string", "nullable": true, "description": "Identificador do CSC." }, "SefazAmbienteNFC": { "type": "integer", "nullable": true, "description": "Ambiente NFCe: 1=Produção, 2=Homologação." }, "SefazAmbienteServiceInvoice": { "type": "integer", "nullable": true, "description": "Ambiente NFSe: 1=Produção, 2=Homologação." }, "ServiceInvoiceUltima": { "type": "integer", "nullable": true, "description": "Número da última NFSe emitida." }, "NfseFeedStatus": { "type": "integer", "nullable": true, "description": "1 quando a empresa tem feed NFSe ativo." }, "CteFeedStatus": { "type": "integer", "nullable": true, "description": "1 quando a empresa tem feed CTe ativo. Mesma empresa (CNPJ) não pode ter CTe ativo em duas contas." }, "CertificadoBestBeforeDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de validade do certificado digital." }, "CertificadoIssuer1": { "type": "string", "nullable": true, "description": "Emissor do certificado (campo 1 do subject)." }, "CertificadoIssuer2": { "type": "string", "nullable": true, "description": "Emissor do certificado (campo 2 do subject)." }, "CertificadoPassword": { "type": "string", "nullable": true, "description": "Sempre `null` — a senha do certificado nunca é exposta pela API." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Identificador da integração NFe/NFSe principal (`IDTypeCompanyIntegration=16`)." }, "NfModNfDescription": { "type": "string", "description": "Texto fixo: 'NF-e emitida em substituição ao modelo 1 ou 1A'." }, "StateInscription": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyStateInscription" }, "description": "Inscrições estaduais cadastradas (uma por UF)." }, "CompanySimplesCred": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySimplesCredItem" }, "description": "Créditos do Simples Nacional registrados por período (mês/ano)." } } }, "CompanyStateInscription": { "type": "object", "description": "Inscrição estadual da empresa em uma UF específica.", "properties": { "IDCompanyStateInscription": { "type": "integer", "format": "int32", "description": "Identificador da inscrição estadual cadastrada para a empresa (uma inscrição por UF de atuação)." }, "State": { "type": "string", "description": "Sigla da UF (ex.: 'SP', 'RJ', 'MG')." }, "StateName": { "type": "string", "nullable": true, "description": "Nome do estado (resolvido via `TypePostalCode`)." }, "StateInscription": { "type": "string", "description": "Número da inscrição estadual (somente dígitos)." }, "NFeComments": { "type": "string", "nullable": true, "description": "Observações fiscais que aparecem na NFe emitida para destinatários deste estado." }, "NfeDifalIndFinal": { "type": "integer", "nullable": true, "description": "Flag de DIFAL — indicador de consumidor final para vendas interestaduais." }, "GNRE": { "type": "integer", "nullable": true, "description": "Flag indicando se a empresa precisa emitir GNRE para vendas para este estado." }, "CompanyStateInscriptionDueDay": { "type": "integer", "nullable": true, "description": "Dia do mês em que a GNRE vence para vendas a este estado." } } }, "CompanyStateInscriptionCreate": { "type": "object", "description": "Corpo de `POST /company/state-inscription` e `PUT /company/state-inscription/{idstateinscription}`. A inscrição é validada com o algoritmo oficial por UF.", "required": [ "State", "StateInscription" ], "properties": { "State": { "type": "string", "description": "Sigla da UF (ex.: 'SP', 'RJ', 'MG'). Apenas uma inscrição por estado." }, "StateInscription": { "type": "string", "description": "Número da inscrição estadual. Pode ter máscara — o sistema remove caracteres não numéricos. Para MG, faz padding com zeros à esquerda até 13 dígitos." }, "NFeComments": { "type": "string", "nullable": true, "description": "Texto livre acrescentado às informações complementares da NFe quando a venda ocorre nesta UF (máx. 255 caracteres)." }, "NfeDifalIndFinal": { "type": "integer", "nullable": true, "description": "Indicador de consumidor final para cálculo de DIFAL nas operações para esta UF: 0=Não, 1=Sim. Default 1." }, "GNRE": { "type": "integer", "nullable": true, "description": "Quando 1, esta UF emite GNRE (Guia Nacional de Recolhimento) para a empresa. Default 0." }, "CompanyStateInscriptionDueDay": { "type": "integer", "nullable": true, "description": "Dia do mês de vencimento da guia GNRE/ICMS-ST para esta UF (1–31)." } } }, "CompanySimplesCredItem": { "type": "object", "description": "Crédito do Simples Nacional registrado para um período (mês/ano). Usado pelo idworks para calcular o crédito de PIS/COFINS em vendas de empresas no regime do Simples Nacional.", "properties": { "IDCompanySimplesCred": { "type": "integer", "format": "int32", "description": "Identificador do crédito Simples Nacional cadastrado para a empresa (uma alíquota efetiva por anexo do Simples para cálculo de crédito a clientes)." }, "MonthYear": { "type": "string", "format": "date-time", "description": "Primeiro dia do mês de competência (início da vigência do crédito)." }, "PCred": { "type": "number", "description": "Percentual de crédito do PIS/COFINS aplicado a este período." }, "TotalEffectiveTax": { "type": "number", "nullable": true, "description": "Alíquota efetiva total dos tributos do Simples no período." } } }, "CompanySimplesCredCreate": { "type": "object", "description": "Corpo de `POST /company/simples-cred` e `PUT /company/simples-cred/{idcompanysimplescred}`. O sistema converte `MonthYear` para o primeiro dia do mês automaticamente.", "required": [ "MonthYear", "PCred" ], "properties": { "MonthYear": { "type": "string", "format": "date", "description": "Mês/ano de competência (qualquer dia do mês — o sistema usa o primeiro/último dia automaticamente)." }, "PCred": { "type": "number", "description": "Percentual de crédito do PIS/COFINS (ex.: 1.25 para 1,25%)." }, "TotalEffectiveTax": { "type": "number", "nullable": true, "description": "Alíquota efetiva total dos tributos do Simples no período (opcional)." } } }, "CompanyUpdate": { "type": "object", "description": "Corpo de `PUT /company`. Atualização parcial — apenas campos enviados são alterados.", "properties": { "CompanyNameCorporateName": { "type": "string", "description": "Razão social." }, "CompanyTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia." }, "CompanyCpfCnpj": { "type": "string", "description": "CNPJ ou CPF (somente dígitos)." }, "CompanyAddressPostalCode": { "type": "string", "nullable": true, "description": "CEP. Quando muda, o sistema consulta o CEP novo e atualiza `CompanyAddressIbgeCityCode`." }, "CompanyAddressStreet": { "type": "string", "nullable": true, "description": "Logradouro." }, "CompanyAddressNumber": { "type": "string", "nullable": true, "description": "Número do endereço." }, "CompanyAddressComplement": { "type": "string", "nullable": true, "description": "Complemento." }, "CompanyAddressNeighborhood": { "type": "string", "nullable": true, "description": "Bairro." }, "CompanyAddressCity": { "type": "string", "nullable": true, "description": "Cidade." }, "CompanyAddressState": { "type": "string", "nullable": true, "description": "Sigla da UF." }, "CompanyAddressIbgeCityCode": { "type": "string", "nullable": true, "description": "Código IBGE da cidade. Atualizado automaticamente quando `CompanyAddressPostalCode` muda." }, "CompanyTelephone": { "type": "string", "nullable": true, "description": "Telefone de contato." }, "CompanyCityInscription": { "type": "string", "nullable": true, "description": "Inscrição municipal." }, "WebSiteUrl": { "type": "string", "nullable": true, "description": "URL do site da empresa." }, "NfeRegimeTributario": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3, 4 ], "description": "Regime tributário (CRT): 1=Simples Nacional, 2=Simples Nacional excesso sublimite, 3=Regime Normal, 4=MEI." }, "NfeSerie": { "type": "string", "nullable": true, "description": "Série da NFe modelo 55. Máximo 999." }, "NfeUltima": { "type": "integer", "nullable": true, "description": "Número da última NFe modelo 55 — usado para sincronizar o contador quando a empresa migra de outro sistema." }, "SefazAmbienteNF": { "type": "integer", "nullable": true, "description": "1=Produção, 2=Homologação." }, "NfeFeedStatus": { "type": "integer", "nullable": true, "description": "Quando 1, ativa o feed de NFe (recebimento de XMLs de fornecedores). Apenas uma empresa por CNPJ pode manter o feed ativo." }, "NfceUltima": { "type": "integer", "nullable": true, "description": "Número da última NFCe emitida — usado para sincronizar o contador quando a empresa migra de outro sistema." }, "NfceSerie": { "type": "string", "nullable": true, "description": "Série da NFCe modelo 65. Máximo 999." }, "NfceCSC": { "type": "string", "nullable": true, "description": "Código de Segurança do Contribuinte (CSC) da NFCe." }, "NfceCSCid": { "type": "string", "nullable": true, "description": "Identificador do CSC da NFCe." }, "SefazAmbienteNFC": { "type": "integer", "nullable": true, "description": "Ambiente de emissão NFCe: 1=Produção, 2=Homologação." }, "SefazAmbienteServiceInvoice": { "type": "integer", "nullable": true, "description": "Ambiente de emissão NFSe: 1=Produção, 2=Homologação." }, "ServiceInvoiceUltima": { "type": "integer", "nullable": true, "description": "Número da última NFSe emitida — usado para sincronizar o contador quando a empresa migra de outro sistema." }, "CteFeedStatus": { "type": "integer", "nullable": true, "description": "Quando 1, o sistema bloqueia se outra empresa com mesmo CNPJ já tem CTe ativo." }, "CompanyStatus": { "type": "integer", "nullable": true, "description": "Status do cadastro (ativo/inativo)." } } }, "CompanyBranchResponse": { "type": "object", "description": "Resposta de `GET /company/branch` — empresa-matriz com a lista de filiais agregada em `Branch[]`.", "properties": { "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa-matriz." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa-matriz." }, "CompanyCpfCnpj": { "type": "string", "description": "CNPJ ou CPF da matriz (somente dígitos)." }, "CompanyTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia da matriz." }, "CompanyNameCorporateName": { "type": "string", "description": "Razão social da matriz." }, "CompanyLogoUrl": { "type": "string", "nullable": true, "description": "URL do logotipo da matriz." }, "CertificadoBestBeforeDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de validade do certificado digital da matriz." }, "NfeSerie": { "type": "string", "nullable": true, "description": "Série atual da NFe modelo 55 da matriz." }, "NfeUltima": { "type": "integer", "nullable": true, "description": "Número da última NFe modelo 55 emitida pela matriz." }, "NfceSerie": { "type": "string", "nullable": true, "description": "Série atual da NFCe (modelo 65) da matriz." }, "NfceUltima": { "type": "integer", "nullable": true, "description": "Número da última NFCe emitida pela matriz." }, "CompanyStatus": { "type": "integer", "description": "Status do cadastro da matriz (ativo/inativo)." }, "CrtDescription": { "type": "string", "nullable": true, "description": "Descrição do regime tributário da matriz." }, "Branch": { "type": "array", "description": "Filiais da empresa-matriz (vinculadas via `CompanyMain`).", "items": { "type": "object", "properties": { "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da filial." }, "AccountName": { "type": "string", "description": "Subdomínio da filial." }, "CompanyCpfCnpj": { "type": "string", "description": "CNPJ ou CPF da filial (somente dígitos)." }, "CompanyTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia da filial." }, "CompanyNameCorporateName": { "type": "string", "description": "Razão social da filial." }, "CompanyLogoUrl": { "type": "string", "nullable": true, "description": "URL do logotipo da filial." }, "CertificadoBestBeforeDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de validade do certificado digital da filial." }, "NfeSerie": { "type": "string", "nullable": true, "description": "Série atual da NFe modelo 55 da filial." }, "NfeUltima": { "type": "integer", "nullable": true, "description": "Número da última NFe modelo 55 emitida pela filial." }, "NfceSerie": { "type": "string", "nullable": true, "description": "Série atual da NFCe (modelo 65) da filial." }, "NfceUltima": { "type": "integer", "nullable": true, "description": "Número da última NFCe emitida pela filial." }, "CompanyStatus": { "type": "integer", "description": "Status do cadastro da filial (ativo/inativo)." }, "CrtDescription": { "type": "string", "nullable": true, "description": "Descrição do regime tributário da filial." } } } } } }, "CompanyReportGroup": { "type": "object", "description": "Grupo de relatórios disponíveis para a empresa. Cada grupo agrupa relatórios da mesma categoria (Vendas, Financeiro, Fiscal, Estoque, WMS, TMS, Anúncios, Integração, Customizado, etc.). A resposta de `GET /company/report` é um array de grupos, e cada grupo tem um array `CompanyReport[]` — cuja chave interna `TypeCompanyReport` é por sua vez um array de relatórios individuais com seus filtros.", "properties": { "CompanyReport": { "type": "array", "description": "Grupos de relatórios da empresa.", "items": { "type": "object", "properties": { "TypeCompanyReportGroup": { "type": "string", "description": "Nome do grupo (ex.: 'Vendas', 'Financeiro', 'Fiscal', 'Estoque', 'WMS', 'TMS', 'Anúncios', 'Integração', 'Customizado')." }, "IDTypeCompanyReportGroup": { "type": "integer", "format": "int32", "description": "Identificador do grupo de relatórios." }, "TypeCompanyReport": { "type": "array", "description": "Relatórios individuais do grupo.", "items": { "type": "object", "properties": { "IDTypeCompanyReport": { "type": "integer", "format": "int32", "description": "Identificador do tipo de relatório — usado em `POST /user/report` no campo `IDTypeCompanyReport`." }, "TypeCompanyReport": { "type": "string", "description": "Nome do relatório (ex.: 'Pedidos por período', 'Conciliação de Estoque')." }, "TypeCompanyReportQuery": { "type": "array", "description": "Filtros aceitos pelo relatório.", "items": { "type": "object", "properties": { "Type": { "type": "string", "enum": [ "RangerPicker", "InputGroup", "Select", "Input" ], "description": "Tipo do componente de filtro: `RangerPicker` para intervalo de datas (dois campos), `InputGroup` para par de valores numéricos, `Select` para lista pré-carregada, `Input` para texto livre." }, "Label": { "type": "string", "description": "Legenda exibida no formulário." }, "Param": { "type": "array", "items": { "type": "string" }, "description": "Lista de nomes de query string que o front envia ao gerar o relatório. RangerPicker/InputGroup têm 2 itens (`From`, `To`); Select tem até 3 (`nameValue`, `nameLabel`, `nameList`); Input tem 1." } } } } } } } } } } } }, "UserReportListItem": { "type": "object", "description": "Relatório gerado pelo usuário autenticado, com status atual e (quando pronto) o link de download.", "properties": { "IDUserReport": { "type": "integer", "format": "int32", "description": "Identificador interno do relatório gerado." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador interno da empresa dona do relatório." }, "IDTypeCompanyReport": { "type": "integer", "format": "int32", "description": "Tipo do relatório gerado." }, "TypeCompanyReport": { "type": "string", "description": "Nome do relatório (resolvido)." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." }, "IDTypeStatusUserReport": { "type": "integer", "description": "Status numérico interno.", "enum": [ 1, 2, 3 ] }, "Status": { "type": "string", "description": "Nome do status atual: `Processando`, `Gerado` ou `Sem dados`." }, "Query": { "type": "string", "description": "Query string com os filtros usados na geração (ex.: `DateFrom=2026-01-01&DateTo=2026-01-31`)." }, "SendEmail": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = enviar o link por e-mail ao usuário quando terminar; 0 = só disponibilizar pela tela." }, "Link": { "type": "string", "nullable": true, "description": "URL de download do arquivo. Vazio enquanto o relatório está sendo processado." }, "Comments": { "type": "string", "nullable": true, "description": "Comentários adicionais (ex.: número de linhas, mensagem de erro)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora da geração." }, "RecordUserCreated": { "type": "integer", "format": "int32", "description": "Identificador do usuário que pediu o relatório." } } }, "UserReportCreate": { "type": "object", "description": "Corpo de `POST /user/report`. Enfileira a geração de um relatório novo.", "required": [ "IDTypeCompanyReport", "Query" ], "properties": { "IDTypeCompanyReport": { "type": "integer", "format": "int32", "description": "Identificador do tipo de relatório. Escolha um dos tipos disponíveis para a empresa, retornados em `IDTypeCompanyReport` por `GET /company/report`." }, "Query": { "type": "string", "description": "Query string com os filtros do relatório, no formato `chave1=valor1&chave2=valor2` (ex.: `DateFrom=2026-06-23&DateTo=2026-06-23`). As chaves dependem do tipo de relatório. Precisa ser uma querystring: se vier um objeto JSON, a requisição é rejeitada com `[BadRequest]`." }, "SendEmail": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = enviar o link do arquivo por e-mail ao usuário quando o processamento terminar; 0 = só disponibilizar pela tela. Opcional." } } }, "UserComissionCreate": { "type": "object", "description": "Corpo de `POST /user/{iduser}/comission` e `PUT /user/{iduser}/comission/{idsalesmancomission}`. Define uma regra de comissão para o vendedor.", "required": [ "DateFrom", "DateTo", "ComissionPercent" ], "properties": { "DateFrom": { "type": "string", "format": "date", "description": "Início da vigência da regra (`YYYY-MM-DD`)." }, "DateTo": { "type": "string", "format": "date", "description": "Fim da vigência da regra (`YYYY-MM-DD`). Para regra sem prazo, use uma data distante (ex.: `2099-12-31`)." }, "ComissionPercent": { "type": "number", "description": "Percentual de comissão como fração (0.05 = 5%)." }, "DiscountPercentLimit": { "type": "number", "nullable": true, "description": "Percentual máximo de desconto permitido como fração (0.10 = 10%). Vendas com desconto acima desse limite **não pagam** essa comissão." }, "IDCategory": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da categoria de SKU (`StockKeepingUnitCategory`). Quando informado, a regra só vale para vendas de produtos dessa categoria. Quando nulo, vale para qualquer produto." } } }, "UserComissionDetail": { "type": "object", "description": "Detalhe do usuário com a lista atualizada de regras de comissão. Resposta de `POST/PUT/DELETE /user/{iduser}/comission*`.", "properties": { "IDUser": { "type": "integer", "format": "int32", "description": "Identificador do usuário (vendedor)." }, "UserName": { "type": "string", "description": "Nome do usuário." }, "Login": { "type": "string", "description": "Login (email) do usuário." }, "Salesman": { "type": "integer", "enum": [ 0, 1 ], "description": "1 quando o usuário é vendedor (acumula comissão em vendas)." }, "DiscountPercentLimit": { "type": "number", "nullable": true, "description": "Limite **padrão** de desconto para vendas do vendedor (aplicado quando nenhuma regra específica casa)." }, "IDTypeSalesmanCommission": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "nullable": true, "description": "Flux de liberação da comissão: 1=parcial vinculada às parcelas, 2=integral no faturamento, 3=integral após pagamento da 1ª parcela, 4=integral após pagamento da última parcela." }, "ExcludeCanceledOrdersCommission": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = pedidos cancelados não entram no cálculo da comissão." }, "ExcludeReturnedOrdersCommission": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = pedidos devolvidos não entram no cálculo da comissão." }, "SalesmanComission": { "type": "array", "description": "Regras de comissão vinculadas ao usuário.", "items": { "type": "object", "properties": { "IDSalesmanComission": { "type": "integer", "format": "int32", "description": "Identificador da regra de comissão." }, "IDAcess": { "type": "integer", "format": "int32", "description": "Vínculo do usuário com a empresa (`IDAcess`)." }, "DateFrom": { "type": "string", "format": "date", "description": "Início da vigência da regra (`YYYY-MM-DD`)." }, "DateTo": { "type": "string", "format": "date", "description": "Fim da vigência da regra (`YYYY-MM-DD`)." }, "DiscountPercentLimit": { "type": "number", "nullable": true, "description": "Limite máximo de desconto da regra como fração (0.10 = 10%). Vendas com desconto acima desse limite não pagam essa comissão." }, "ComissionPercent": { "type": "number", "description": "Percentual de comissão da regra como fração (0.05 = 5%)." }, "IDCategory": { "type": "integer", "format": "int32", "nullable": true, "description": "Categoria de SKU à qual a regra se aplica. `null` quando a regra vale para qualquer categoria." }, "Category": { "type": "string", "nullable": true, "description": "Descrição da categoria (resolvida)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora em que a regra foi cadastrada." } } } } } }, "StoreFrontCashierHistoryListItem": { "type": "object", "description": "Item de `GET /store-front/cashier/history`. Cada linha é uma abertura de caixa (`StoreFrontCashier`).", "properties": { "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa dona da conta bancária do caixa." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Identificador da conta bancária (caixa)." }, "Bank": { "type": "string", "description": "Nome do caixa (campo `Bank` da `BankAccount`)." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Faturador associado ao caixa." }, "IDStoreFrontCashier": { "type": "integer", "format": "int32", "description": "Identificador único da sessão de caixa." }, "RecordUserCreated": { "type": "integer", "format": "int32", "description": "Identificador do usuário que abriu o caixa." }, "Login": { "type": "string", "description": "Login do operador." }, "UserName": { "type": "string", "description": "Nome do operador." }, "RecordTimestampOpen": { "type": "string", "format": "date-time", "description": "Data e hora da abertura do caixa." }, "RecordTimestampClose": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora do fechamento. `null` enquanto o caixa segue aberto." }, "CommentsOpen": { "type": "string", "nullable": true, "description": "Comentários da abertura (saldo inicial declarado, observações)." }, "CommentsClose": { "type": "string", "nullable": true, "description": "Comentários do fechamento (sobras/quebras, observações)." } } }, "StoreFrontCashierHistoryDetail": { "type": "object", "description": "Resposta de `GET /store-front/cashier/history/{idstorefrontcashier}` e de `PUT /store-front/cashier/history/{idstorefrontcashier}/adjust/{idaccountpayablereceivable}`. Cabeçalho da sessão acompanhado das listas agregadas de pedidos, lançamentos bancários e totais por tipo de pagamento.", "properties": { "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador interno da empresa dona do caixa." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do caixa." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária (caixa) da sessão." }, "Bank": { "type": "string", "description": "Nome do caixa (ex.: `Caixa 1`, `Maquininha Cielo`)." }, "IDStoreFrontCashier": { "type": "integer", "format": "int32", "description": "Identificador da sessão de caixa." }, "RecordUserCreated": { "type": "integer", "format": "int32", "description": "Identificador do usuário operador que abriu a sessão." }, "Login": { "type": "string", "description": "Login do operador que abriu a sessão." }, "UserName": { "type": "string", "description": "Nome do operador que abriu a sessão." }, "RecordTimestampOpen": { "type": "string", "format": "date-time", "description": "Data/hora de abertura da sessão." }, "RecordTimestampClose": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora de fechamento. `null` enquanto a sessão estiver aberta." }, "CommentsOpen": { "type": "string", "nullable": true, "description": "Observações registradas pelo operador na abertura." }, "CommentsClose": { "type": "string", "nullable": true, "description": "Observações registradas pelo operador no fechamento (geralmente preenchidas quando há diferença entre o saldo apurado e o contado)." }, "TotalOrderValue": { "type": "number", "description": "Soma dos valores em `OrderList` (todos os pedidos da sessão, inclusive cancelados)." }, "TotalTransactionValue": { "type": "number", "description": "Soma dos valores em `TransactionList` (lançamentos bancários da sessão, considerando sinal original)." }, "OrderList": { "type": "array", "description": "Pedidos atendidos no caixa, uma linha por recebimento (`AccountsPayableReceivable`). Agrupado pelo par (`IDOrder`, `IDTypePayment`).", "items": { "type": "object", "properties": { "IDOrder": { "type": "integer", "format": "int32", "description": "Pedido vinculado ao recebimento." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "description": "Identificador do recebimento — passar para `PUT /store-front/cashier/history/{idstorefrontcashier}/adjust/{idaccountpayablereceivable}` ao editar." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Carimbo de data/hora do pedido (campo `RecordTimestamp` de `StoreFrontCashierOrder`)." }, "Value": { "type": "number", "description": "Soma das parcelas do recebimento agrupado." }, "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "Forma de pagamento do recebimento. `null` quando o pedido foi cancelado sem ter forma de pagamento atribuída." }, "TypePaymentDescription": { "type": "string", "nullable": true, "description": "Descrição amigável da forma de pagamento." }, "InstallmentTotal": { "type": "integer", "nullable": true, "description": "Quantidade de parcelas do recebimento." }, "TID": { "type": "string", "nullable": true, "description": "TID da maquininha (quando aplicável)." }, "NSU": { "type": "string", "nullable": true, "description": "NSU da maquininha (quando aplicável)." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Nome/Razão social do consumidor do pedido." }, "SalesmanLogin": { "type": "string", "nullable": true, "description": "Login do vendedor (`IDSalesMan`)." }, "SalesmanUsername": { "type": "string", "nullable": true, "description": "Nome do vendedor." }, "IDStatusOrder": { "type": "integer", "format": "int32", "description": "Status do pedido. `90` indica venda cancelada." }, "StatusOrder": { "type": "string", "description": "Descrição do status." }, "OrderComments": { "type": "string", "nullable": true, "description": "Comentários do pedido (especialmente úteis para vendas canceladas)." } } } }, "TransactionList": { "type": "array", "description": "Lançamentos bancários vinculados à sessão (`AccountsPayableReceivableBankStatement`): sangrias, suprimentos, recebimentos baixados, etc.", "items": { "type": "object", "properties": { "DateTransactionTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora do lançamento bancário." }, "TransactionDescription": { "type": "string", "description": "Texto livre do lançamento. Sangrias contêm a palavra `sangria` (a tela do extrato isola esses itens em uma seção separada)." }, "Value": { "type": "number", "description": "Valor absoluto. A tela aplica sinal negativo quando `IDTypeAccount = 1` (débito)." }, "IDTypeAccount": { "type": "integer", "format": "int32", "description": "`1` = débito (saída), demais = crédito (entrada)." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do recebimento conciliado por esse extrato (quando aplicável)." }, "IDBankStatement": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do extrato bancário de origem (quando o lançamento foi importado de OFX)." }, "IDOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Pedido vinculado ao recebimento (quando aplicável)." }, "IDStatusOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Status do pedido vinculado ao lançamento (quando há). `null` para lançamentos que não vieram de pedido (reforço/sangria/ajustes)." }, "StatusOrder": { "type": "string", "nullable": true, "description": "Descrição amigável do status do pedido." }, "OrderComments": { "type": "string", "nullable": true, "description": "Comentários do pedido (útil principalmente em pedidos cancelados)." } } } }, "PaymentSummary": { "type": "array", "description": "Total de recebimentos **válidos** (pedidos não cancelados) por tipo de pagamento. A lista parte dos tipos de pagamento ativos com `EnableFrenteCaixa = 1`, zerados, e é incrementada conforme `OrderList` é processada — tipos inativos aparecem apenas se houve recebimento neles.", "items": { "type": "object", "properties": { "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "Forma de pagamento. `null` em linhas agregadas que não casaram com um tipo cadastrado." }, "TypePaymentDescription": { "type": "string", "nullable": true, "description": "Descrição amigável da forma de pagamento." }, "TotalValue": { "type": "number", "description": "Soma arredondada em 2 casas." } } } } } }, "StoreFrontCashierHistoryAdjust": { "type": "object", "description": "Corpo de `PUT /store-front/cashier/history/{idstorefrontcashier}/adjust/{idaccountpayablereceivable}`. Todos os campos são opcionais — somente os enviados são alterados, exceto `InstallmentTotal`, que quando difere do valor atual dispara recálculo de parcelamento.", "properties": { "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "Novo tipo de pagamento. Precisa pertencer à mesma empresa do recebimento (`IDCompany`)." }, "TID": { "type": "string", "nullable": true, "description": "TID da maquininha (envie `null` para limpar)." }, "NSU": { "type": "string", "nullable": true, "description": "NSU da maquininha (envie `null` para limpar)." }, "InstallmentTotal": { "type": "integer", "nullable": true, "description": "Nova quantidade de parcelas. **Quando diferente do valor atual**, o sistema apaga os recebimentos do agrupamento `(IDOrder, IDTypePayment, IDTypeAccount, NSU, TID)` atual e recria o parcelamento com o valor total dividido em `InstallmentTotal` parcelas." } } }, "SkuPromotionListItem": { "type": "object", "description": "Item de `GET /sku/promotion`. Cabeçalho da promoção, sem as listas vinculadas (use o `GET /sku/promotion/{id}` para o detalhe).", "properties": { "IDStockKeepingUnitPromotion": { "type": "integer", "format": "int32", "description": "Identificador da promoção." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa dona da promoção." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." }, "IDTypeSkuPromotion": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Tipo: 1=Regular, 2=Compre e Ganhe, 3=Desconto Progressivo, 4=Compre Junto." }, "TypeSkuPromotion": { "type": "string", "description": "Descrição do tipo (resolvida)." }, "IDTypeSkuPromotionStatus": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ], "description": "Status: 0=Excluída, 1=Ativo, 2=Programada, 3=Finalizada, 4=Inativa." }, "TypeSkuPromotionStatus": { "type": "string", "description": "Status textual: `Ativo`, `Programada`, `Finalizada`, `Inativa` (`Excluída` quando o registro foi removido)." }, "StockKeepingUnitPromotionName": { "type": "string", "description": "Nome da promoção." }, "StockKeepingUnitPromotionDescription": { "type": "string", "nullable": true, "description": "Descrição livre da promoção." }, "DateFrom": { "type": "string", "format": "date-time", "description": "Início da vigência. `1900-01-01` indica \"para sempre\"." }, "DateTo": { "type": "string", "format": "date-time", "description": "Fim da vigência. `4000-01-01` indica \"para sempre\"." }, "PercentualDiscountValue": { "type": "number", "nullable": true, "description": "Fração 0–1 (0.10 = 10%). Usado em Regular, Compre Junto (lista principal)." }, "NominalDiscountValue": { "type": "number", "nullable": true, "description": "Valor em R$. Usado em Regular." }, "MinOrderValue": { "type": "number", "nullable": true, "description": "Valor mínimo do pedido para a promoção valer (Regular)." }, "MaxOrderValue": { "type": "number", "nullable": true, "description": "Valor máximo do pedido para a promoção valer (Regular)." }, "MinimumQuantityBuyTogether": { "type": "number", "nullable": true, "description": "Quantidade mínima de unidades para ativar a promoção (Compre e Ganhe / Compre Junto)." }, "PercentualDiscountValueBuyTogether": { "type": "number", "nullable": true, "description": "Fração 0–1 do desconto na lista complementar do Compre Junto." }, "Cumulative": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = pode acumular com outras promoções." }, "CumulativeManualPrice": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = aplica mesmo se houver preço manual no item." }, "AllowDifferentItemQuantitySum": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = soma quantidades de SKUs diferentes para atingir a quantidade mínima." }, "ExactlyQuantity": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = aplica só em quantidades múltiplas exatas (Progressivo)." }, "OnlyRegisteredConsumer": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = aplica somente quando o pedido tem cliente cadastrado." }, "BrandsIncluded": { "type": "integer", "enum": [ 0, 1 ], "description": "Default 1. 1 = aplicar em SKUs cujas marcas estão na lista; 0 = aplicar em SKUs cujas marcas NÃO estão na lista." }, "CategoriesIncluded": { "type": "integer", "enum": [ 0, 1 ], "description": "Default 1. 1 = aplicar em SKUs cujas categorias estão na lista; 0 = aplicar em SKUs cujas categorias NÃO estão na lista." }, "ProductsIncluded": { "type": "integer", "enum": [ 0, 1 ], "description": "Default 1. 1 = aplicar em SKUs cujos produtos-pai estão na lista; 0 = aplicar em SKUs cujos produtos-pai NÃO estão na lista." }, "SkusIncluded": { "type": "integer", "enum": [ 0, 1 ], "description": "Default 1. 1 = aplicar nos SKUs que estão na lista; 0 = aplicar nos SKUs que NÃO estão na lista." } } }, "SkuPromotionRestrictionRef": { "type": "object", "description": "Referência a um vínculo da promoção. Usado no body de POST/PUT (com apenas o id) e na resposta do GET (com id + nome resolvido).", "properties": { "IDBrand": { "type": "integer", "format": "int32", "description": "Marca à qual a restrição/aplicação da promoção se aplica." }, "IDCategory": { "type": "integer", "format": "int32", "description": "Categoria à qual a restrição/aplicação da promoção se aplica." }, "IDProduct": { "type": "integer", "format": "int32", "description": "`IDSku` com `IDTypeSku = 4` (produto pai)." }, "IDSku": { "type": "integer", "format": "int32", "description": "`IDSku` com `IDTypeSku ∈ {2,3,6,7,8}` (kit, sku, matéria-prima, uso e consumo, caixa)." }, "IDTypeOrder": { "type": "integer", "format": "int32", "description": "Tipo de pedido (venda, atacado, varejo, etc.) ao qual a promoção é restrita." }, "IDCompanySalesPolicy": { "type": "integer", "format": "int32", "description": "Política comercial à qual a promoção é restrita." }, "BrandName": { "type": "string", "description": "Apenas na resposta." }, "CategoryName": { "type": "string", "description": "Apenas na resposta." }, "ProductName": { "type": "string", "description": "Apenas na resposta — formato `IDSkuCompany | SkuName`." }, "IDProductCompany": { "type": "string", "description": "Apenas na resposta." }, "SkuName": { "type": "string", "description": "Apenas na resposta — formato `IDSkuCompany | SkuName`." }, "IDSkuCompany": { "type": "string", "description": "Apenas na resposta." }, "BarCode": { "type": "string", "description": "Apenas na resposta (somente para SKU/SkusBuyTogether)." }, "MainImageURL": { "type": "string", "nullable": true, "description": "Apenas na resposta (somente para SkusBuyTogether) — URL da imagem principal do SKU." }, "TypeOrder": { "type": "string", "description": "Descrição amigável do tipo de pedido." }, "CompanySalesPolicy": { "type": "string", "description": "Nome da política comercial." } } }, "SkuPromotionProgressiveTier": { "type": "object", "description": "Faixa de uma promoção de Desconto Progressivo. Cada faixa tem `Quantity` (gatilho — a partir de quantas unidades vale) e `DiscountPercent` **ou** `FixedPrice` (mutualmente exclusivos). `Quantity` precisa ser único entre as faixas. No `POST`/`PUT`, envie apenas `Quantity` + um dos dois campos de valor. No `GET`, vêm os 3 (o não usado vem `null`) + o id.", "properties": { "IDStockKeepingUnitPromotionProgressive": { "type": "integer", "format": "int32", "description": "Apenas na resposta." }, "Quantity": { "type": "number", "description": "Quantidade mínima de unidades para entrar nesta faixa." }, "DiscountPercent": { "type": "number", "nullable": true, "description": "Fração 0–1 do desconto. `null` quando se usa `FixedPrice`." }, "FixedPrice": { "type": "number", "nullable": true, "description": "Preço unitário fixo em R$ aplicado quando a faixa é ativada. `null` quando se usa `DiscountPercent`." } } }, "SkuPromotionCreate": { "type": "object", "description": "Corpo de `POST /sku/promotion`. Os campos exigidos variam por tipo — veja a descrição do POST para regras detalhadas.", "required": [ "IDTypeSkuPromotion", "StockKeepingUnitPromotionName", "DateFrom", "DateTo" ], "properties": { "IDTypeSkuPromotion": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "1=Regular, 2=Compre e Ganhe, 3=Desconto Progressivo, 4=Compre Junto." }, "StockKeepingUnitPromotionName": { "type": "string", "description": "Nome — gravado sem acentos (normalização NFD)." }, "StockKeepingUnitPromotionDescription": { "type": "string", "nullable": true, "description": "Descrição livre da promoção (opcional)." }, "DateFrom": { "type": "string", "format": "date-time", "description": "Início da vigência. Use `1900-01-01` para \"para sempre\"." }, "DateTo": { "type": "string", "format": "date-time", "description": "Fim da vigência. Use `4000-01-01` para \"para sempre\"." }, "Enabled": { "type": "integer", "enum": [ 0, 1 ], "description": "1=Ativo." }, "Cumulative": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` permite cumular com outras promoções no mesmo pedido; `0` (padrão) torna a promoção exclusiva." }, "CumulativeManualPrice": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` aplica a promoção mesmo quando o operador edita o preço manualmente no PDV; `0` (padrão) desabilita." }, "AllowDifferentItemQuantitySum": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` permite somar quantidades de SKUs diferentes da mesma promoção para atingir o gatilho de quantidade — útil em `Compre junto` quando o cliente pode misturar variações." }, "ExactlyQuantity": { "type": "integer", "enum": [ 0, 1 ], "description": "Só relevante para tipo 3." }, "OnlyRegisteredConsumer": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` restringe a promoção a consumidores identificados (cadastrados no pedido); `0` (padrão) aceita venda anônima." }, "PercentualDiscountValue": { "type": "number", "nullable": true, "description": "Fração 0–1. Usado em **tipo 1** (Regular, opcional — escolher entre % ou R$) e **tipo 4** (Compre Junto, obrigatório — desconto da lista principal)." }, "NominalDiscountValue": { "type": "number", "nullable": true, "description": "Valor em R$. Usado em **tipo 1** (Regular, opcional — alternativa ao %)." }, "MinOrderValue": { "type": "number", "nullable": true, "description": "Apenas tipo 1." }, "MaxOrderValue": { "type": "number", "nullable": true, "description": "Apenas tipo 1." }, "MinimumQuantityBuyTogether": { "type": "number", "nullable": true, "description": "Obrigatório nos tipos 2 e 4. Quantidade mínima de unidades (da lista principal no tipo 4)." }, "PercentualDiscountValueBuyTogether": { "type": "number", "nullable": true, "description": "Obrigatório no tipo 4. Fração 0–1 do desconto da lista complementar." }, "BrandsIncluded": { "type": "integer", "enum": [ 0, 1 ], "description": "Default 1. Apenas tipo 1." }, "CategoriesIncluded": { "type": "integer", "enum": [ 0, 1 ], "description": "Default 1. Apenas tipo 1." }, "ProductsIncluded": { "type": "integer", "enum": [ 0, 1 ], "description": "Default 1. Apenas tipo 1." }, "SkusIncluded": { "type": "integer", "enum": [ 0, 1 ], "description": "Default 1. Apenas tipo 1." }, "StockKeepingUnitPromotionBrands": { "type": "array", "items": { "type": "object", "required": [ "IDBrand" ], "properties": { "IDBrand": { "type": "integer", "description": "Identificador da marca participante (a promoção vale para todos os SKUs da marca)." } } }, "description": "Apenas tipo 1." }, "StockKeepingUnitPromotionCategories": { "type": "array", "items": { "type": "object", "required": [ "IDCategory" ], "properties": { "IDCategory": { "type": "integer", "description": "Identificador da categoria participante." } } }, "description": "Apenas tipo 1." }, "StockKeepingUnitPromotionProducts": { "type": "array", "items": { "type": "object", "required": [ "IDProduct" ], "properties": { "IDProduct": { "type": "integer", "description": "Identificador do produto-pai (SKU `IDTypeSku=4`) participante." } } }, "description": "Tipos 1 e 3. Cada `IDProduct` é um `IDSku` com `IDTypeSku = 4` (produto pai)." }, "StockKeepingUnitPromotionSkus": { "type": "array", "items": { "type": "object", "required": [ "IDSku" ], "properties": { "IDSku": { "type": "integer", "description": "Identificador do SKU participante." } } }, "description": "Tipos 1, 2, 3 e 4. Itens elegíveis (`IDTypeSku ∈ {2,3,6,7,8}`). Para tipo 2/4 é a lista de itens **que devem ser comprados** (lista principal)." }, "StockKeepingUnitPromotionSkusBuyTogether": { "type": "array", "items": { "type": "object", "required": [ "IDSku" ], "properties": { "IDSku": { "type": "integer", "description": "Identificador do SKU do grupo `Compre junto` (lista alternativa específica do tipo 4 — promoção `Compre junto`)." } } }, "description": "Tipos 2 e 4. No tipo 2 é a lista de **itens de brinde** (ganham com `PriceSellingTotal=0`); no tipo 4 é a **lista complementar** (recebem `PercentualDiscountValueBuyTogether`)." }, "StockKeepingUnitPromotionProgressive": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionProgressiveTier" }, "description": "Apenas tipo 3. Cada faixa precisa ter `Quantity` único." }, "StockKeepingUnitPromotionTypeOrders": { "type": "array", "items": { "type": "object", "required": [ "IDTypeOrder" ], "properties": { "IDTypeOrder": { "type": "integer", "description": "Identificador do tipo de pedido em que a promoção vale (ex.: somente vendas no PDV)." } } }, "description": "Tipos de pedido aceitos. Vazio = todos." }, "StockKeepingUnitPromotionSalesPolicies": { "type": "array", "items": { "type": "object", "required": [ "IDCompanySalesPolicy" ], "properties": { "IDCompanySalesPolicy": { "type": "integer", "description": "Identificador da política comercial em que a promoção vale (ex.: tabela de preço varejo)." } } }, "description": "Políticas comerciais aceitas. Vazio = todas." } } }, "SkuPromotionUpdate": { "description": "Corpo de `PUT /sku/promotion/{idstockkeepingunitpromotion}`. Mesmos campos do `POST` (exceto `IDTypeSkuPromotion`, que vem da promoção existente). Listas omitidas **não são tocadas**; listas enviadas (mesmo vazias) **substituem** os vínculos atuais. Inclui também `Enabled` para alternar ativo/inativo.", "allOf": [ { "$ref": "#/components/schemas/SkuPromotionCreate" } ] }, "SkuPromotionDetail": { "type": "object", "description": "Resposta de `GET /sku/promotion/{id}`, `POST /sku/promotion` e `PUT /sku/promotion/{id}`. Inclui o cabeçalho + todas as listas vinculadas com nomes resolvidos.", "allOf": [ { "$ref": "#/components/schemas/SkuPromotionListItem" }, { "type": "object", "properties": { "Enabled": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando a promoção está vigente e ativa; `0` quando inativa." }, "StockKeepingUnitPromotionBrands": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionRestrictionRef" }, "description": "Marcas incluídas/excluídas na restrição da promoção." }, "StockKeepingUnitPromotionCategories": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionRestrictionRef" }, "description": "Categorias incluídas/excluídas na restrição da promoção." }, "StockKeepingUnitPromotionProducts": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionRestrictionRef" }, "description": "Produtos (pai) incluídos/excluídos na restrição da promoção." }, "StockKeepingUnitPromotionSkus": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionRestrictionRef" }, "description": "SKUs incluídos/excluídos na restrição da promoção." }, "StockKeepingUnitPromotionTypeOrders": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionRestrictionRef" }, "description": "Tipos de pedido em que a promoção é válida (vazio = todos)." }, "StockKeepingUnitPromotionSkusBuyTogether": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionRestrictionRef" }, "description": "SKUs da lista de brinde/complementar (Compre e Ganhe / Compre Junto)." }, "StockKeepingUnitPromotionProgressive": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionProgressiveTier" }, "description": "Faixas de desconto progressivo (quantidade × desconto ou preço fixo)." }, "StockKeepingUnitPromotionSalesPolicies": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionRestrictionRef" }, "description": "Políticas comerciais em que a promoção é válida (vazio = todas)." } } } ] }, "SkuPromotionSkuItem": { "type": "object", "description": "Item de `GET /sku/promotion/sku/{idsku}`. Promoção vigente que casa com o SKU informado, com flags de inclusão por restrição.", "properties": { "IDStockKeepingUnitPromotion": { "type": "integer", "format": "int32", "description": "Identificador da promoção." }, "IDTypeSkuPromotion": { "type": "integer", "description": "Tipo da promoção: `1` Regular, `2` Compre e ganhe, `3` Desconto progressivo, `4` Compre junto.", "enum": [ 1, 2, 3, 4 ] }, "TypeSkuPromotion": { "type": "string", "description": "Descrição textual do tipo da promoção." }, "StockKeepingUnitPromotionName": { "type": "string", "description": "Nome da promoção." }, "StockKeepingUnitPromotionDescription": { "type": "string", "nullable": true, "description": "Descrição livre da promoção." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "DateFrom": { "type": "string", "format": "date-time", "description": "Data e hora de início da vigência." }, "DateTo": { "type": "string", "format": "date-time", "description": "Data e hora de término da vigência." }, "IDTypeSkuPromotionStatus": { "type": "integer", "description": "Status: `1` Ativo, `2` Programada, `3` Finalizada, `4` Inativa (`0` Excluída).", "enum": [ 0, 1, 2, 3, 4 ] }, "TypeSkuPromotionStatus": { "type": "string", "description": "Descrição textual do status." }, "PercentualDiscountValue": { "type": "number", "nullable": true, "description": "Desconto percentual aplicado (ex.: `0.10` = 10%)." }, "NominalDiscountValue": { "type": "number", "nullable": true, "description": "Desconto nominal em valor monetário." }, "MinOrderValue": { "type": "number", "nullable": true, "description": "Valor mínimo do pedido para a promoção ser aplicada." }, "MaxOrderValue": { "type": "number", "nullable": true, "description": "Valor máximo do pedido a partir do qual a promoção deixa de valer." }, "Cumulative": { "type": "integer", "description": "`1` permite cumular com outras promoções no mesmo pedido; `0` é exclusiva." }, "MinimumQuantityBuyTogether": { "type": "number", "nullable": true, "description": "Quantidade mínima do conjunto na promoção `Compre junto` para o desconto se aplicar." }, "PercentualDiscountValueBuyTogether": { "type": "number", "nullable": true, "description": "Desconto percentual aplicado na promoção `Compre junto`." }, "IncludeBrand": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = SKU passa na restrição de marca." }, "IncludeBrandType": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3, null ], "description": "1 = `BrandsIncluded=1` casou; 2 = lista vazia; 3 = `BrandsIncluded=0` casou (NÃO está)." }, "IncludeCategory": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando há categorias vinculadas à promoção." }, "IncludeCategoryType": { "type": "integer", "nullable": true, "description": "Modo de inclusão das categorias: `1` inclui apenas as categorias vinculadas; `2` exclui as categorias vinculadas (todas as outras participam)." }, "IncludeProd": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando há produtos-pai vinculados à promoção." }, "IncludeProdType": { "type": "integer", "nullable": true, "description": "Modo de inclusão dos produtos: `1` inclui apenas os listados; `2` exclui os listados." }, "IncludeSku": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando há SKUs vinculados à promoção." }, "IncludeSkuType": { "type": "integer", "nullable": true, "description": "Modo de inclusão dos SKUs: `1` inclui apenas os listados; `2` exclui os listados." }, "IncludeSkuTogether": { "type": "integer", "nullable": true, "enum": [ 0, 1, null ], "description": "1 = SKU está na lista de brindes/lista complementar da promoção (tipo 2/4)." } } }, "SkuPromotionOrderValidateItem": { "type": "object", "description": "Item do carrinho enviado em `POST /sku/promotion/order/validate`. O sistema agrupa por (`IDSku`, `IDStockKeepingUnitWarehouse`) somando quantidades antes de aplicar promoções.", "required": [ "IDSku", "Quantity", "PriceSelling" ], "properties": { "IDSku": { "type": "integer", "format": "int32", "description": "SKU do item do pedido a validar contra as promoções ativas." }, "Quantity": { "type": "number", "description": "Quantidade do SKU no item do pedido." }, "PriceSelling": { "type": "number", "description": "Preço unitário de venda corrente." }, "PriceList": { "type": "number", "nullable": true, "description": "Preço de tabela (de lista) — usado para detectar preço manual." }, "ValueDiscount": { "type": "number", "nullable": true, "description": "Valor de desconto já aplicado ao item (informativo — entra no cálculo de promoções acumuladas)." }, "IDCompanySalesPolicy": { "type": "integer", "format": "int32", "nullable": true, "description": "Política comercial do item — passa no filtro `StockKeepingUnitPromotionSalesPolicies`." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "format": "int32", "nullable": true, "description": "Armazém de origem do item (algumas promoções são restritas a armazéns específicos)." }, "IDStockKeepingUnitPromotion": { "type": "array", "items": { "type": "integer" }, "description": "Lista de promoções já aplicadas ao item — se vazia, o sistema recalcula." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome do SKU (informativo para retorno)." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal do SKU (informativo)." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência interno do SKU, definido pela empresa (informativo)." } } }, "SkuPromotionOrderValidateBody": { "type": "object", "description": "Corpo de `POST /sku/promotion/order/validate`.", "required": [ "Items" ], "properties": { "Items": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionOrderValidateItem" }, "description": "Lista de itens a validar contra as promoções da empresa. Cada item descreve um SKU, quantidade e preço; o sistema aplica as promoções vigentes e devolve descontos e ajustes calculados." }, "IDOrderType": { "type": "integer", "format": "int32", "description": "Tipo de pedido sendo montado — usado para filtrar promoções por `StockKeepingUnitPromotionTypeOrders`." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Cliente do pedido — quando vazio, descarta promoções com `OnlyRegisteredConsumer=1`." }, "IDStoreFrontCashier": { "type": "integer", "format": "int32", "nullable": true, "description": "Caixa do PDV aberto — necessário para persistir o carrinho em `StoreFrontCashierOrderTemp`." }, "IDStoreFrontCashierOrderTemp": { "type": "integer", "format": "int32", "nullable": true, "description": "Quando informado, atualiza o registro existente em `StoreFrontCashierOrderTemp`. Quando omitido, cria um novo e devolve o id gerado na resposta." } } }, "SkuPromotionOrderValidateResponse": { "type": "object", "description": "Resposta de `POST /sku/promotion/order/validate`. Espelha o body com os preços recalculados e a lista de promoções avaliadas por item.", "properties": { "Items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/SkuPromotionOrderValidateItem" }, { "type": "object", "properties": { "PriceSellingTotal": { "type": "number", "description": "Total recalculado após promoções (`PriceSelling × Quantity` no agrupamento)." }, "OriginalPriceSellingTotal": { "type": "number", "description": "Total antes das promoções." }, "ValueDiscountTotal": { "type": "number", "description": "`OriginalPriceSellingTotal - PriceSellingTotal`." }, "OriginalPriceSelling": { "type": "number", "description": "Preço de venda original do item, antes da promoção." }, "PromotionDiscountPercent": { "type": "number", "description": "`1 - PriceSellingTotal / OriginalPriceSellingTotal`." }, "StockKeepingUnitPromotionName": { "type": "array", "items": { "type": "string" }, "description": "Nomes das promoções aplicadas (formato `TipoPromocao - Nome`)." }, "Promotions": { "type": "array", "description": "Lista completa das promoções **avaliadas** para o item (não apenas as aplicadas), com flags de inclusão para diagnóstico.", "items": { "type": "object", "properties": { "IDStockKeepingUnitPromotion": { "type": "integer", "description": "Identificador da promoção aplicada." }, "IDTypeSkuPromotion": { "type": "integer", "description": "Tipo da promoção aplicada.", "enum": [ 1, 2, 3, 4 ] }, "TypeSkuPromotion": { "type": "string", "description": "Descrição do tipo de promoção." }, "StockKeepingUnitPromotionName": { "type": "string", "description": "Nome da promoção aplicada." }, "PercentualDiscountValue": { "type": "number", "nullable": true, "description": "Desconto percentual aplicado (fração `0–1`). `null` quando a promoção é por valor nominal." }, "NominalDiscountValue": { "type": "number", "nullable": true, "description": "Desconto nominal aplicado em R$. `null` quando a promoção é percentual." }, "MinOrderValue": { "type": "number", "nullable": true, "description": "Valor mínimo do pedido para a promoção valer. `null` quando não há mínimo." }, "MaxOrderValue": { "type": "number", "nullable": true, "description": "Valor máximo do pedido para a promoção valer. `null` quando não há máximo." }, "Cumulative": { "type": "integer", "description": "`1` quando a promoção pode acumular com outras de tipos diferentes." }, "AllowDifferentItemQuantitySum": { "type": "integer", "description": "`1` quando a quantidade mínima considera a soma de SKUs diferentes." }, "ExactlyQuantity": { "type": "integer", "description": "`1` quando a faixa progressiva só vale em múltiplos exatos da quantidade." }, "MinimumQuantityBuyTogether": { "type": "number", "nullable": true, "description": "Quantidade mínima a comprar (Compre e Ganhe / Compre Junto). `null` nos demais tipos." }, "PercentualDiscountValueBuyTogether": { "type": "number", "nullable": true, "description": "Desconto percentual da lista complementar (Compre Junto). `null` nos demais tipos." }, "GroupedQuantity": { "type": "number", "description": "Quantidade considerada para o gatilho — soma de SKUs diferentes quando `AllowDifferentItemQuantitySum=1`." }, "PrePriceSellingTotal": { "type": "number", "description": "Preço total antes desta promoção (auxiliar de cálculo)." }, "PreValueDiscountTotal": { "type": "number", "description": "Valor estimado do desconto da promoção — usado no desempate (maior desconto primeiro)." }, "StockKeepingUnitPromotionSkusBuyTogether": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionRestrictionRef" }, "description": "Apenas tipo 2/4." }, "StockKeepingUnitPromotionProgressive": { "type": "array", "items": { "$ref": "#/components/schemas/SkuPromotionProgressiveTier" }, "description": "Apenas tipo 3 — vem ordenado desc por `Quantity`." } } } } } } ] }, "description": "Lista de itens com os campos calculados das promoções aplicáveis (preço pré-desconto, valor do desconto, identificador da promoção, etc.)." }, "IDStoreFrontCashierOrderTemp": { "type": "integer", "format": "int32", "description": "Id do registro persistido/atualizado em `StoreFrontCashierOrderTemp` — devolvido também quando o request veio sem ele (insert)." }, "IDOrderType": { "type": "integer", "format": "int32", "description": "Tipo do pedido considerado na validação (algumas promoções valem só para tipos específicos)." }, "IDConsumer": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do consumidor considerado (promoções com `OnlyRegisteredConsumer=1` exigem este campo)." }, "IDStoreFrontCashier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do caixa do PDV, quando a validação é feita no contexto da frente de loja." } } }, "StoreFrontPaymentListItem": { "type": "object", "description": "Item de `GET /store-front/payment`. Cada linha é uma tentativa de cobrança feita no PDV (cartão via PayGo, Pix via StarkBank ou Pagar.me).", "properties": { "IDStoreFrontCashierPayment": { "type": "integer", "format": "int32", "description": "Identificador único da transação." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador interno da empresa dona do caixa." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da conta bancária." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Faturador (empresa de emissão da NFC-e) — pode ser diferente da empresa dona do caixa." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Subdomínio do faturador (empresa configurada para emitir a NFC-e da venda). Pode ser diferente do `AccountName`." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Nome/Razão social do faturador." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária (caixa) onde a transação foi originada." }, "Bank": { "type": "string", "description": "Nome do caixa (ex.: \"Caixa 1\", \"Maquininha Cielo\")." }, "IDCompanyIntegration": { "type": "integer", "format": "int32", "nullable": true, "description": "Integração configurada na conta bancária (`IDCompanyIntegration`) — determina se foi PayGo, StarkBank ou Pagar.me." }, "IDTypePayment": { "type": "integer", "format": "int32", "description": "Forma de pagamento (`IDTypePayment`). Para esta rota, sempre crédito (`Category=22`), débito (`Category=23`) ou Pix (`Category=24`)." }, "TypePaymentDescription": { "type": "string", "description": "Descrição amigável da forma de pagamento (ex.: `Crédito Visa 1x`, `Pix StarkBank`)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora da criação da transação." }, "RecordTimestampCancel": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora do cancelamento (preenchido apenas em transações canceladas)." }, "IDUserCancel": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do usuário que iniciou o cancelamento." }, "Value": { "type": "number", "description": "Valor total da transação em R$." }, "InstallmentTotal": { "type": "integer", "description": "Quantidade de parcelas (1 para Pix e débito)." }, "IDOrderIntention": { "type": "string", "description": "UUID que liga a tentativa de pagamento ao pedido fechado no PDV." }, "IDOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Pedido vinculado (resolvido via `IDOrderIntention`). `null` quando a transação ainda não virou pedido." }, "IDTypeStatusStoreFrontCashierPayment": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "description": "1=Pendente, 2=Em pagamento, 3=Creditado, 4=Expirado, 5=Cancelamento iniciado, 6=Em cancelamento, 7=Cancelado, 8=Pagamento recusado." }, "TypeStatusStoreFrontCashierPayment": { "type": "string", "description": "Descrição do status." }, "TefTerminal": { "type": "string", "nullable": true, "description": "Código do terminal TEF (id PayGo da maquininha física). `0` quando integração não é PayGo." }, "TID": { "type": "string", "nullable": true, "description": "TID/NSU retornado pelo adquirente." }, "AuthId": { "type": "string", "nullable": true, "description": "Código de autorização do adquirente." }, "Acquirer": { "type": "string", "nullable": true, "description": "Adquirente (Cielo, Rede, Stone etc.) — vem do adquirente real, não do gateway." }, "PaymentSystemName": { "type": "string", "nullable": true, "description": "Bandeira do cartão (Visa, Master, Elo etc.) ou \"Pix\"." }, "ReturnCode": { "type": "string", "nullable": true, "description": "Código de resposta do adquirente." }, "ReturnMessage": { "type": "string", "nullable": true, "description": "Mensagem de resposta do adquirente (usada em falhas)." }, "CardLastDigits": { "type": "string", "nullable": true, "description": "Últimos 4 dígitos do cartão." }, "Receipt": { "type": "string", "nullable": true, "description": "ZPL do comprovante via estabelecimento, com sufixo `\\r\\n VA` apendado para impressão direta." }, "ReceiptBuyer": { "type": "string", "nullable": true, "description": "ZPL do comprovante via cliente, com sufixo `\\r\\n VA` apendado." } } }, "StoreFrontPaymentPostBody": { "type": "object", "description": "Body de `POST /store-front/cashier/{idbankaccount}/payment`. Os campos exigidos são `IDTypePayment` e `Value`; o restante varia por integração.", "required": [ "IDTypePayment", "Value" ], "properties": { "IDTypePayment": { "type": "integer", "format": "int32", "description": "Tipo de pagamento (`IDTypePayment`). Precisa pertencer à empresa e ter `Category ∈ {22, 23, 24}` (crédito, débito, Pix)." }, "Value": { "type": "number", "description": "Valor total da cobrança em R$." }, "InstallmentTotal": { "type": "integer", "default": 1, "description": "Quantidade de parcelas. `1` para débito/Pix. Para crédito segue a configuração do tipo de pagamento e do parâmetro `parcelamentoAdmin` da integração." }, "IDOrderIntention": { "type": "string", "description": "UUID opcional para ligar a tentativa ao pedido. Quando omitido, o sistema gera um UUID novo e devolve no body." } } }, "StoreFrontPaymentPostResponse": { "type": "object", "description": "Resposta de `POST /store-front/cashier/{idbankaccount}/payment`. Campos variam por integração.", "properties": { "IDStoreFrontCashierPayment": { "type": "integer", "format": "int32", "description": "Identificador da transação criada — usar nas chamadas seguintes de `GET` e `DELETE`." }, "IDOrderIntention": { "type": "string", "description": "UUID que liga a tentativa ao pedido. Gerado pelo sistema quando omitido no body." }, "IDTypeStatusStoreFrontCashierPayment": { "type": "integer", "enum": [ 2 ], "description": "Status inicial da transação logo após iniciada: `2` Em pagamento. O ciclo completo (Pendente, Creditado, Expirado, Cancelado, etc.) é acompanhado via `GET` da transação." }, "ExternalId": { "type": "string", "nullable": true, "description": "Id da transação no gateway externo. PayGo: `intencaoVenda.id`. StarkBank: `uuid` do BR Code. Pagar.me: id do pedido." }, "PixCopiaCola": { "type": "string", "nullable": true, "description": "String Pix copia-cola (StarkBank: `id` do BR Code; Pagar.me: corpo do QR Code). Ausente para PayGo." }, "QrCodeImageUrl": { "type": "string", "format": "uri", "nullable": true, "description": "URL da imagem do QR Code (StarkBank: `pictureUrl`; Pagar.me: URL do gateway). Ausente para PayGo." }, "QrcodeExpirationTimeInSeconds": { "type": "integer", "nullable": true, "description": "Tempo de expiração do QR Code em segundos. Default 3600. Ausente para PayGo." }, "TID": { "type": "string", "nullable": true, "description": "TID do Pagar.me (já devolvido no POST). PayGo e StarkBank só preenchem no `GET`." } } }, "StoreFrontPaymentGetResponse": { "type": "object", "description": "Resposta de `GET /store-front/cashier/{idbankaccount}/payment/{idstorefrontcashierpayment}`. Combina campos atualizados na transação + indicador `Success`.", "properties": { "IDStoreFrontCashierPayment": { "type": "integer", "format": "int32", "description": "Identificador da transação consultada." }, "IDTypeStatusStoreFrontCashierPayment": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "description": "Status final da transação após o polling do gateway. `1` Pendente, `2` Em pagamento, `3` Creditado, `4` Expirado, `5` Cancelamento iniciado, `6` Em cancelamento, `7` Cancelado, `8` Pagamento recusado." }, "TypeStatusStoreFrontCashierPayment": { "type": "string", "description": "Descrição do status. Aparece quando o polling chegou a um veredicto (Creditado, Cancelado, Pagamento recusado, Expirado)." }, "Success": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` = transação finalizada com sucesso (Creditado ou Cancelado bem sucedido). `0` = falha (Expirado, Pagamento recusado, casos especiais PayGo `-2596`)." }, "TID": { "type": "string", "nullable": true, "description": "TID/NSU retornado pelo adquirente. Para PayGo, vem em `nsuTid` da resposta do terminal." }, "AuthId": { "type": "string", "nullable": true, "description": "Código de autorização do adquirente." }, "Acquirer": { "type": "string", "nullable": true, "description": "Nome do adquirente real que processou (Cielo, Rede, Stone etc.) — vem da resposta do gateway, não do cadastro da conta." }, "PaymentSystemName": { "type": "string", "nullable": true, "description": "Bandeira do cartão (`Visa`, `Master`, `Elo` etc.) ou `Pix`." }, "ReturnCode": { "type": "string", "nullable": true, "description": "Código de resposta do adquirente (cancelamentos e recusas trazem o motivo aqui)." }, "ReturnMessage": { "type": "string", "nullable": true, "description": "Mensagem textual do adquirente, geralmente preenchida em falhas e cancelamentos." }, "CardLastDigits": { "type": "string", "nullable": true, "description": "Últimos 4 dígitos do cartão. Extraído de `CARTAO:` ou `PWINFO_CARDPARCPAN` da resposta PayGo." }, "Receipt": { "type": "string", "nullable": true, "description": "ZPL via estabelecimento — extraído entre `PWINFO_RCPTMERCH =` e `PWINFO_RCPTCHOLDER` da resposta PayGo." }, "ReceiptBuyer": { "type": "string", "nullable": true, "description": "ZPL via cliente — extraído entre `PWINFO_RCPTCHOLDER =` e `PWINFO_RCPTCHSHORT`/`PWINFO_TRNORIGDATE`/`PWINFO_LANGUAGE` (na ordem)." }, "ExternalId": { "type": "string", "nullable": true, "description": "Apenas em respostas Pix (StarkBank/Pagar.me)." }, "PixCopiaCola": { "type": "string", "nullable": true, "description": "Apenas Pix." }, "QrCodeImageUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Apenas Pix." }, "QrcodeExpirationTimeInSeconds": { "type": "integer", "nullable": true, "description": "Apenas Pix." } } }, "StoreFrontCashierListItem": { "type": "object", "description": "Item de `GET /store-front/cashier`. Cada caixa do PDV (`BankAccount` do tipo caixinha) com status, operador e saldo atuais.", "properties": { "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária (caixa)." }, "Bank": { "type": "string", "description": "Nome do caixa (ex.: \"Caixa 1\", \"Maquininha Cielo\")." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do caixa." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Faturador (empresa de emissão da NFC-e). Quando vazio, o caixa não tem faturador configurado." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Subdomínio do faturador (empresa configurada para emitir a NFC-e da venda)." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social do faturador, exibida no cabeçalho dos recibos." }, "CompanyCpfCnpjInvoice": { "type": "string", "nullable": true, "description": "CNPJ do faturador (sem máscara), usado no cabeçalho dos recibos." }, "IDCompanyIntegration": { "type": "integer", "format": "int32", "nullable": true, "description": "Integração de pagamento (PayGo / StarkBank / Pagar.me) — usada quando a venda for processada via TEF/Pix." }, "StoreFrontCashierStatus": { "type": "integer", "enum": [ 1, 2 ], "description": "Status calculado: `1`=Fechado, `2`=Aberto." }, "StoreFrontCashierStatusDescription": { "type": "string", "enum": [ "Aberto", "Fechado" ], "description": "Descrição amigável do status calculado em tempo real. `Aberto` quando há sessão (`RecordTimestampClose` nulo); `Fechado` caso contrário." }, "IDStoreFrontCashier": { "type": "integer", "format": "int32", "nullable": true, "description": "Id da sessão aberta. Null quando o caixa está fechado." }, "RecordTimestampOpen": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora de abertura da sessão atual. Null quando fechado." }, "Login": { "type": "string", "nullable": true, "description": "Login do operador que abriu o caixa. Null quando fechado." }, "Balance": { "type": "number", "description": "Saldo corrente do caixa em R$ (soma de todos os lançamentos em `AccountsPayableReceivableBankStatement` até agora)." } } }, "StoreFrontCashierDetail": { "type": "object", "description": "Resposta de `GET /store-front/cashier/{idbankaccount}`. Snapshot do caixa aberto com totais financeiros, listas agregadas e ZPLs prontos para impressão.", "properties": { "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária (caixa)." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador interno da empresa dona do caixa." }, "BankNumber": { "type": "string", "example": "000", "description": "Sempre `'000'` (caixinha do PDV)." }, "IDStoreFrontCashier": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador da sessão aberta. `null` quando o caixa está fechado." }, "RecordTimestampOpen": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora de abertura da sessão atual. `null` quando fechado." }, "RecordUserCreated": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do operador que abriu a sessão. `null` quando fechado." }, "Login": { "type": "string", "nullable": true, "description": "Login do operador que abriu a sessão. `null` quando fechado." }, "UserName": { "type": "string", "nullable": true, "description": "Nome do operador que abriu a sessão. `null` quando fechado." }, "IDTypeOrder": { "type": "integer", "format": "int32", "description": "Tipo de pedido padrão do caixa. Quando a `BankAccount` não tem, o sistema usa o `DefaultFrenteCaixa=1` da empresa." }, "TypeOrder": { "type": "string", "description": "Nome do tipo de pedido padrão (`TypeOrder`)." }, "IDCompanySalesPolicy": { "type": "integer", "format": "int32", "description": "Política comercial herdada do tipo de pedido." }, "CompanySalesPolicy": { "type": "string", "description": "Política comercial aplicada (lista de preços e condições)." }, "CompanyCpfCnpjInvoice": { "type": "string", "description": "CNPJ do faturador (sem máscara) — usado no cabeçalho dos recibos." }, "CompanyNameCorporateNameInvoice": { "type": "string", "description": "Razão social do faturador." }, "IDOrderStoreFrontCashierOrderList": { "type": "string", "nullable": true, "description": "Lista CSV de `IDOrder` dos pedidos fechados nesta sessão." }, "Balance": { "type": "number", "description": "Saldo total do caixa em R$." }, "Income": { "type": "number", "description": "Créditos desde a abertura — descontada a parcela já contabilizada pelos pagamentos em dinheiro nos pedidos (para evitar dupla contagem)." }, "Outcome": { "type": "number", "description": "Débitos desde a abertura." }, "AdjustIn": { "type": "number", "description": "Reforços (créditos sem `IDAccountPayableReceivable`)." }, "AdjustOut": { "type": "number", "description": "Sangrias (débitos sem `IDAccountPayableReceivable`)." }, "TotalValueCancelled": { "type": "number", "description": "Diferença entre `Income` original e a soma dos pagamentos em dinheiro — útil para identificar discrepâncias com vendas canceladas." }, "PaymentSummary": { "type": "array", "description": "Total vendido por **tipo de pagamento** específico (descrição). Inclui tipos zerados habilitados no PDV (`EnableFrenteCaixa=1`) para o operador conferir.", "items": { "type": "object", "properties": { "IDTypePayment": { "type": "integer", "format": "int32", "nullable": true, "description": "Forma de pagamento. `null` em linhas agregadas que não casaram com um tipo cadastrado." }, "TypePaymentDescription": { "type": "string", "nullable": true, "description": "Descrição amigável da forma de pagamento." }, "Category": { "type": "integer", "nullable": true, "description": "Categoria do tipo de pagamento (`Category`). Determina o agrupamento em `PaymentCategorySummary`. Ex.: `1` Dinheiro, `22` Crédito, `23` Débito, `24` Pix." }, "TypePaymentCategory": { "type": "string", "nullable": true, "description": "Descrição amigável da categoria de pagamento (`Dinheiro`, `Crédito`, `Débito`, `Pix`, `Vale`, etc.)." }, "EnableFrenteCaixa": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando a forma de pagamento está habilitada para uso no PDV (aparece no menu de cobrança); `0` quando o tipo só recebeu vendas históricas." }, "TotalValue": { "type": "number", "description": "Total recebido no caixa nesta forma de pagamento em R$." } } } }, "PaymentCategorySummary": { "type": "array", "description": "Total vendido por **categoria** de pagamento (Crédito, Débito, Dinheiro, Pix, Vale, Crédito Loja etc.).", "items": { "type": "object", "properties": { "Category": { "type": "integer", "description": "Categoria do pagamento (`Category`). Ex.: `1` Dinheiro, `22` Crédito, `23` Débito, `24` Pix." }, "TypePaymentCategory": { "type": "string", "description": "Descrição amigável da categoria (`Dinheiro`, `Crédito`, `Débito`, `Pix`, `Vale`, etc.)." }, "EnableFrenteCaixa": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando a categoria tem pelo menos um tipo de pagamento habilitado para uso no PDV." }, "TotalValue": { "type": "number", "description": "Total recebido no caixa nesta categoria em R$." } } } }, "InvoiceSummary": { "type": "array", "description": "Vendas agrupadas por modelo de NF emitida.", "items": { "type": "object", "properties": { "NfeModelo": { "type": "integer", "nullable": true, "enum": [ 55, 65, null ], "description": "55=NF-e, 65=NFC-e, `null`=pendente (sem NF emitida)." }, "TotalValue": { "type": "number", "description": "Soma dos pedidos do grupo (NFC-e, NF-e ou pendente) em R$." }, "Count": { "type": "integer", "description": "Quantidade de notas." } } } }, "ReceiptBase64Encode": { "type": "string", "format": "byte", "description": "ZPL do recibo \"Fechamento de Caixa\" (Saldo Anterior + Total por tipo + Reforço + Sangria + Saldo Final). Codificado em base64 + cp850." }, "ReceiptFiscalBase64Encode": { "type": "string", "format": "byte", "description": "ZPL do recibo \"Resumo Fiscal\" (Total NFCe/NFe/Pendente + quantidades + breakdown por categoria de pagamento). Base64 + cp850." } } }, "StoreFrontCashierOpenBody": { "type": "object", "description": "Body de `POST /store-front/cashier/{idbankaccount}/open`. Senha do usuário operador é obrigatória.", "required": [ "Password" ], "properties": { "InitialBalance": { "type": "number", "description": "Valor declarado pelo operador como saldo inicial do caixa em R$. Quando difere em mais de R$ 0,01 do `Balance` calculado, gera lançamento \"Ajuste abertura de caixa\". Default: 0." }, "Comments": { "type": "string", "nullable": true, "description": "Observações sobre a abertura (gravado em `CommentsOpen`)." }, "Password": { "type": "string", "description": "Senha do usuário operador (validada via bcrypt contra a senha do usuário)." } } }, "StoreFrontCashierOpenResponse": { "type": "object", "description": "Resposta de `POST /store-front/cashier/{idbankaccount}/open`. Contexto operacional para inicializar o PDV.", "properties": { "IDStoreFrontCashier": { "type": "integer", "format": "int32", "description": "Identificador da sessão criada (ou retomada quando o mesmo operador já tinha o caixa aberto)." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária (caixa) aberta." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador interno da empresa dona do caixa." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador interno do faturador (empresa responsável pela emissão da NFC-e da venda). `null` quando não houver faturador configurado." }, "BankNumber": { "type": "string", "description": "Sempre `'000'` (banco caixinha do PDV)." }, "RecordTimestampOpen": { "type": "string", "format": "date-time", "description": "Data/hora em que a sessão foi aberta." }, "RecordUserCreated": { "type": "integer", "format": "int32", "description": "Identificador do operador que abriu a sessão." }, "Login": { "type": "string", "description": "Login do operador que abriu a sessão." }, "UserName": { "type": "string", "description": "Nome do operador que abriu a sessão." }, "IDTypeOrder": { "type": "integer", "format": "int32", "description": "Tipo de pedido padrão do caixa (ou `DefaultFrenteCaixa=1` da empresa quando a conta não tem)." }, "TypeOrder": { "type": "string", "description": "Nome do tipo de pedido padrão usado nas vendas (`TypeOrder`)." }, "IDCompanySalesPolicy": { "type": "integer", "format": "int32", "description": "Política comercial herdada do tipo de pedido." }, "CompanySalesPolicy": { "type": "string", "description": "Política comercial herdada do tipo de pedido (lista de preços + condições aplicadas no PDV)." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "format": "int32", "description": "Armazém padrão do tipo de pedido." }, "WarehouseName": { "type": "string", "description": "Nome do armazém padrão do tipo de pedido — origem do estoque das vendas do caixa." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "format": "int32", "nullable": true, "description": "Centro de distribuição do armazém padrão. `null` quando o armazém não estiver vinculado a um CD." }, "IssueNFCe": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = o tipo de pedido padrão emite NFCe automaticamente." } } }, "StoreFrontCashierCloseBody": { "type": "object", "description": "Body de `POST /store-front/cashier/{idbankaccount}/close`. Quando o `FinalBalance` difere do `Balance`, o front exige `Comments` preenchido.", "required": [ "Password" ], "properties": { "FinalBalance": { "type": "number", "description": "Valor apurado pelo operador na contagem física em R$. Diferenças geram lançamento \"Ajuste fechamento de caixa\"." }, "Comments": { "type": "string", "nullable": true, "description": "Observações sobre o fechamento (gravado em `CommentsClose`). Obrigatório quando há divergência." }, "Password": { "type": "string", "description": "Senha do usuário operador." } } }, "StoreFrontCashierAdjustBody": { "type": "object", "description": "Body de `POST /store-front/cashier/{idbankaccount}/adjust`. `Type` determina sangria (2) ou reforço (1).", "required": [ "Type", "Value", "Password" ], "properties": { "Type": { "type": "integer", "enum": [ 1, 2 ], "description": "`1` = Reforço (entrada), `2` = Sangria (saída)." }, "Value": { "type": "number", "description": "Valor em R$ (sempre positivo). Sangria não pode exceder o saldo." }, "Comments": { "type": "string", "nullable": true, "description": "Observações (anexadas à descrição da transação: \"Reforço: ...\" ou \"Sangria: ...\")." }, "Password": { "type": "string", "description": "Senha do usuário operador." } } }, "StoreFrontCashierOrderTempItem": { "type": "object", "description": "Item de `GET /store-front/cashier/{idbankaccount}/order-temp`. Rascunho de pedido em montagem no PDV, persistido automaticamente pelo motor de promoções a cada alteração do carrinho.", "properties": { "IDStoreFrontCashierOrderTemp": { "type": "integer", "format": "int32", "description": "Identificador do rascunho — passe para o `DELETE` quando o operador descarta a venda em andamento." }, "IDBankAccount": { "type": "integer", "format": "int32", "description": "Conta bancária (caixa) onde o rascunho foi gerado." }, "OrderData": { "type": "object", "additionalProperties": true, "description": "Estado completo do carrinho em JSON (já parseado): `Items[]`, `Payments[]`, `IDConsumer`, `IDOrderType`, `IDCompanySalesPolicy`, `IDSalesman`, etc. Usado pelo PDV para retomar a venda interrompida via `startOrderByTemp`." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Última atualização do rascunho." } } }, "WebhookLogListItem": { "type": "object", "description": "Item de `GET /webhook`. Representa **uma tentativa** de envio de webhook identificada pelo `UUID` da mensagem SQS de origem. Em caso de falha, `Attempts` é incrementado a cada nova tentativa e os campos `ResponseData` e `Status` refletem o último resultado.", "properties": { "IDWebhookLog": { "type": "integer", "format": "int32", "description": "Identificador da tentativa." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora da primeira tentativa de envio." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa dona da notificação." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." }, "Topic": { "type": "string", "maxLength": 45, "description": "Nome técnico do tópico que originou a notificação (`SkuPost`, `OrderStatus`, `InvoiceIssue`, `TrackingDelivered`, etc.). Corresponde ao campo `Key` das parametrizações do grupo `Webhook → Produto/Pedido/Transporte/...`." }, "EndPoint": { "type": "string", "maxLength": 200, "description": "URL HTTPS do destino que recebeu o `POST`. Cópia da parametrização `EndPoint` da integração `Webhook` no momento do envio." }, "PostData": { "type": "string", "maxLength": 5000, "description": "JSON serializado enviado no corpo da requisição. Inclui ao menos `Topic`, `AccountName` e identificadores do recurso afetado (`IDSku`, `IDOrder`, etc.) além de uma URL relativa para detalhe." }, "ResponseData": { "type": "string", "maxLength": 5000, "nullable": true, "description": "JSON serializado da resposta do destino. Em sucesso, é o corpo da resposta HTTP. Em erro, é a mensagem de erro (`err.response.data` ou `err.cause.reason`)." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "Resultado da última tentativa: `1` = sucesso (destino respondeu 2xx), `0` = erro." }, "StatusName": { "type": "string", "enum": [ "Sucesso", "Erro" ], "description": "Texto pronto para exibição derivado de `Status`." }, "Attempts": { "type": "integer", "nullable": true, "description": "Número de tentativas já feitas para esta mensagem. Incrementa a cada nova tentativa via reenfileiramento." } } }, "UserPrivilegeGroupListItem": { "type": "object", "description": "Item de `GET /user/privilege-group`. Cabeçalho do perfil — só os dados do grupo, sem a lista de privilégios atribuídos.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do perfil." }, "IDUserPrivilegeGroup": { "type": "integer", "format": "int32", "description": "Identificador do perfil." }, "PrivilegeGroupName": { "type": "string", "maxLength": 100, "description": "Nome do perfil (livre)." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa dona do perfil." }, "RecordUserCreated": { "type": "integer", "format": "int32", "description": "Identificador do usuário que criou o perfil." }, "IsConsumer": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, o perfil é destinado a **consumidores** (usuários externos com login restrito), e não a usuários internos da empresa." }, "UserPrivilegeGroupStatus": { "type": "integer", "enum": [ 0, 1 ], "description": "Situação: `0` = inativo (excluído logicamente), `1` = ativo. A listagem só devolve `1`." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de cadastro." } } }, "UserPrivilegeGroupCreate": { "type": "object", "description": "Corpo do `POST /user/privilege-group`. Apenas o nome — o perfil nasce **sem** nenhum privilégio. Use `POST /user/privilege-group/{idprivilegegroup}/resource` depois para atribuir os privilégios.", "required": [ "PrivilegeGroupName" ], "properties": { "PrivilegeGroupName": { "type": "string", "maxLength": 100, "description": "Nome do perfil. Sem restrição de duplicidade — é possível ter dois perfis com o mesmo nome na mesma empresa." } } }, "UserPrivilegeGroupUpdate": { "type": "object", "description": "Corpo do `PUT /user/privilege-group/{idprivilegegroup}`. Atualiza apenas o nome.", "required": [ "PrivilegeGroupName" ], "properties": { "PrivilegeGroupName": { "type": "string", "maxLength": 100, "description": "Novo nome do perfil." } } }, "UserPrivilegeGroupDetail": { "type": "object", "description": "Item de `GET /user/privilege-group/{idprivilegegroup}`. Representa **uma área** do menu (`ModuleGroupDescription`) com a lista de módulos do perfil. **Só vêm os módulos/privilégios atribuídos** ao perfil — para mostrar os disponíveis (não atribuídos), o frontend cruza com `GET /company/module`.", "properties": { "Module": { "type": "array", "description": "Módulos do perfil dentro desta área (deserializado pelo sistema a partir do `JSON_OBJECT` da query).", "items": { "type": "object", "properties": { "ModuleGroupDescription": { "type": "string", "description": "Nome da área do menu (ex.: `Financeiro`, `Fornecedores`, `Produtos`). Repetido em cada item." }, "ModuleDescription": { "type": "string", "description": "Nome do módulo dentro da área (ex.: `Contas a Pagar`, `Categoria Fornecedores`)." }, "IDModule": { "type": "integer", "format": "int32", "description": "Identificador do módulo." }, "Privilege": { "type": "array", "description": "Privilégios deste módulo já atribuídos ao perfil.", "items": { "type": "object", "properties": { "UserPrivilege": { "type": "string", "description": "Chave técnica do privilégio (ex.: `PrivilegeAccountsPayableView`)." }, "IDUserPrivilege": { "type": "integer", "format": "int32", "description": "Identificador numérico do privilégio. É o valor enviado no `POST .../resource`." }, "PrivilegeDescription": { "type": "string", "description": "Nome amigável do privilégio em PT (ex.: `Visualizar contas a pagar`)." } } } } } } } } }, "JobListItem": { "type": "object", "description": "Item de `GET /job`. Cabeçalho do job, sem a lista de resultados.", "properties": { "IDJob": { "type": "integer", "format": "int32", "description": "Identificador do job." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa." }, "IDTypeJob": { "type": "integer", "description": "Tipo da ação (`IDTypeJob`)." }, "TypeJob": { "type": "string", "description": "Nome amigável do tipo da ação (`TypeJob`). Ex.: `Criar sku/produto`, `Criar Contas a pagar`, `Importar extrato OFX`." }, "Login": { "type": "string", "description": "Login do usuário que criou o job." }, "RecordUserCreated": { "type": "integer", "format": "int32", "description": "Id do usuário que criou o job." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que o job foi criado." }, "StartedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o processamento começou. `null` enquanto não inicia." }, "FinishedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o processamento terminou. `null` enquanto está em andamento." }, "RestartedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o job foi reiniciado, se houve." }, "Attempts": { "type": "integer", "nullable": true, "description": "Número de tentativas de processamento." }, "IDFile": { "type": "string", "maxLength": 200, "nullable": true, "description": "Nome do arquivo armazenado no S3 (em `Temp/`). `null` para tipos que não exigem arquivo." }, "FileHash": { "type": "string", "maxLength": 45, "nullable": true, "description": "Hash SHA-256 do conteúdo enviado (base64). Usado pelo `POST /job` para evitar duplicação enquanto um job idêntico ainda está em processamento." }, "Metadata": { "type": "string", "maxLength": 1000, "nullable": true, "description": "JSON serializado com metadados específicos do tipo da ação (ex.: `{\"IDSupplier\":123}` para tabela de frete, `{\"IDBankAccount\":12}` para OFX)." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração relacionada, quando o tipo da ação usa uma (ex.: conciliação de adquirente)." } } }, "JobDetail": { "type": "object", "description": "Item de `GET /job/{idjob}`. Estende `JobListItem` com a lista paginada de resultados e a URL pré-assinada do arquivo original.", "allOf": [ { "$ref": "#/components/schemas/JobListItem" }, { "type": "object", "properties": { "Result": { "type": "array", "description": "Resultado linha-a-linha do processamento da planilha. Vazio (`[]`) enquanto o job não rodou.", "items": { "type": "object", "properties": { "IDJobsResult": { "type": "integer", "format": "int32", "description": "Identificador da linha de resultado." }, "Sheet": { "type": "string", "nullable": true, "description": "Nome da aba da planilha (quando há mais de uma)." }, "Line": { "type": "integer", "description": "Número da linha da planilha que originou este resultado." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` = sucesso, `0` = erro." }, "StatusName": { "type": "string", "enum": [ "Sucesso", "Erro" ], "description": "Texto pronto para exibição derivado de `Status`." }, "Description": { "type": "string", "nullable": true, "description": "Descrição do resultado da linha — para sucesso, descreve a ação executada; para erro, descreve o motivo (ex.: campo obrigatório faltando, valor inválido)." }, "ID": { "type": "integer", "nullable": true, "description": "Id do recurso afetado (SKU criado, pedido criado, conta a pagar criada, etc.)." }, "Name": { "type": "string", "nullable": true, "description": "Nome ou identificador externo do recurso afetado (ex.: código do SKU)." } } } }, "UrlFile": { "type": "string", "format": "uri", "nullable": true, "description": "URL pré-assinada do S3 para baixar o arquivo original enviado. Válida por 2 dias. `null` para jobs que não tiveram upload." } } } ] }, "JobPostResponse": { "type": "object", "description": "Resposta do `POST /job`. O processamento é assíncrono — use o `IDJob` para consultar o resultado em `GET /job/{idjob}`.", "properties": { "IDJob": { "type": "integer", "format": "int32", "description": "Identificador do job criado (ou reaproveitado, quando o mesmo arquivo já estava em processamento)." }, "Message": { "type": "string", "enum": [ "Arquivo em processamento, aguardar resposta por email", "Processo inserido na fila com sucesso" ], "description": "Mensagem padrão devolvida ao cliente. `Processo inserido na fila com sucesso` é usada apenas pelas rotas baseadas em SQS direta (ex.: `POST /sku/{idsku}/cost/recalculate`)." } } }, "CompanyIntegrationListItem": { "type": "object", "description": "Item de `GET /company/integration`. Cabeçalho de uma integração da empresa com o tipo já resolvido.", "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int32", "description": "Identificador da integração." }, "IDTypeCompanyIntegration": { "type": "integer", "description": "Identificador do tipo (`TypeCompanyIntegration`). Ex.: 10=Mercado Livre, 16=idworks, 50=Correios, 131=Stark Bank." }, "IDTypeCompanyIntegrationCategory": { "type": "integer", "description": "Categoria do tipo: 1=Canal de Venda, 2=Gateway, 3=Transportadora, 4=Adquirente, 9=Banco. Outras: 7=ERP, 8=WMS, 10=Hub, 14=Plataformas de e-commerce." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da integração." }, "CompanyIntegrationName": { "type": "string", "maxLength": 500, "description": "Nome da integração (livre). Default `Padrão`." }, "IntegrationName": { "type": "string", "maxLength": 45, "description": "Nome amigável do tipo (resolvido do catálogo)." }, "SalesChannelName": { "type": "string", "description": "Mesmo que `IntegrationName` — exposto também como nome do canal de venda (para integrações de marketplace)." }, "IDSalesChannel": { "type": "integer", "nullable": true, "description": "Identificador do canal de venda associado (quando aplicável)." }, "IntegrationLogoUrl": { "type": "string", "format": "uri", "maxLength": 200, "nullable": true, "description": "URL do logo do canal/integração (para exibição na lista)." }, "PathName": { "type": "string", "maxLength": 45, "nullable": true, "description": "Nome interno usado para rotear chamadas ao serviço de integração (ex.: `meli`, `magalu`). Vazio para integrações que não usam o serviço de integração." }, "AuthUrl": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Quando `1`, o tipo expõe um fluxo de **autenticação via URL** — a ação **Autenticar Integração** fica visível na linha da listagem." }, "HubPaymentCustom": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Flag do tipo indicando se o mapeamento de pagamento do Hub é personalizado." }, "Status": { "type": "integer", "enum": [ 0, 1, 2, 3 ], "description": "Status atual da integração: `1`=Ativo, `2`=Erro de autenticação, `3`=Não autenticado, `0`=Inativo." }, "ReputationLevel": { "type": "string", "nullable": true, "description": "Valor do parâmetro `ReputationLevel` desta integração (quando aplicável). Usado pela UI para colorir a linha (`1_red`, `2_orange`, `3_yellow`, `4_yellow`, `5_green`)." } } }, "CompanyIntegrationCreate": { "type": "object", "description": "Corpo do `POST /company/integration`. Cria a integração com o **mínimo** — só o tipo e um nome. O status inicial é derivado do catálogo do tipo. As parametrizações em si são preenchidas depois via `PUT .../parameter`.", "required": [ "IDTypeCompanyIntegration", "CompanyIntegrationName" ], "properties": { "IDTypeCompanyIntegration": { "type": "integer", "description": "Identificador do tipo de integração (`TypeCompanyIntegration`). Precisa existir no catálogo." }, "CompanyIntegrationName": { "type": "string", "maxLength": 500, "description": "Nome livre da integração. Útil quando a empresa tem mais de uma instância do mesmo tipo (ex.: duas contas de Mercado Livre)." } } }, "CompanyIntegrationUpdate": { "type": "object", "description": "Corpo do `PUT /company/integration/{idcompanyintegration}`. Edita apenas nome e status. Parametrizações são editadas em `PUT .../parameter`.", "properties": { "CompanyIntegrationName": { "type": "string", "maxLength": 500, "description": "Novo nome." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "Novo status. Use `1` para reativar uma integração que estava inativa, ou `0` para inativar (a inativação completa, com limpeza de Hub e parametrizações, é feita pelo `DELETE`)." } } }, "CompanyIntegrationParameter": { "type": "object", "description": "Parametrização da integração (linha de `CompanyParameters` cruzada com a definição em `TypeCompanyParameters`). Devolvida pelo `GET /company/integration/{idcompanyintegration}` e usada para renderizar a tela de configuração.", "properties": { "IDTypeCompanyIntegration": { "type": "integer", "description": "Identificador do tipo da integração à qual esta parametrização pertence." }, "IDTypeCompanyParameters": { "type": "integer", "description": "Identificador da parametrização no catálogo (`TypeCompanyParameters`)." }, "Key": { "type": "string", "maxLength": 100, "description": "Chave técnica da parametrização (ex.: `EndPoint`, `HeaderKeyAuth`, `GnreIDTypeDocument`)." }, "KeyName": { "type": "string", "maxLength": 100, "nullable": true, "description": "Nome amigável em PT (ex.: `Endpoint / URL`, `Tipo de documento para criar contas a pagar GNRE operação`)." }, "Description": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Texto explicativo da parametrização." }, "Type": { "type": "string", "description": "Tipo de campo: `string`, `password`, `boolean`, `checkbox`, `list`, `multi_list`, `string_copy` (texto pré-computado para o usuário copiar), `url_get` (URL gerada dinamicamente), `hidden` (não devolvido), etc." }, "Required": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Quando `1`, o campo é obrigatório." }, "ParameterOrder": { "type": "integer", "nullable": true, "description": "Ordem de exibição dentro do grupo." }, "IDTypeCompanyParametersGroup": { "type": "integer", "description": "Grupo lógico da parametrização (`TypeCompanyParametersGroup`)." }, "TypeCompanyParametersGroup": { "type": "string", "description": "Nome do grupo lógico (ex.: `Credenciais de Acesso`, `Fiscal Produto`, `Produto`, `Pedido`, `Transporte`, `GNRE`, `Webhook`)." }, "Value": { "type": "string", "nullable": true, "description": "Valor atual gravado. Para tipos `string_copy` e `url_get`, o sistema pode substituir por um valor calculado (ex.: URL de webhook personalizada para a empresa, com tokens embutidos). Para flags `TagBusiness` e `TagSellerWarehouse`, retorna `Sim`/`Não` em vez do `1`/`0` cru." }, "List": { "type": "array", "description": "Lista de opções (apenas para `Type` `list` ou `multi_list`). Cada item tem `Value` e `Label`. Algumas chaves específicas (ex.: `IDCompanyInvoice`, `GnreIDTypeDocument`, `IDBankAccount`, `IDTypeAccountPayableReceivable`) trazem aqui a lista correspondente da empresa.\n\nValores possíveis: itens de tabelas-tipo (`NfModFrete`, `CorreiosDiretoria`, etc.), planos de contas da empresa, contas bancárias da empresa, tipos de documento etc.)", "items": { "type": "object", "properties": { "Value": { "type": "string", "description": "Valor que deve ser gravado no campo `Value` ao escolher esta opção (ex.: `1`, `IDCompanyInvoice=123`, código de banco)." }, "Label": { "type": "string", "description": "Texto exibido na lista para o usuário (ex.: `Mercado Livre`, `Faturamento Matriz`, `Banco do Brasil`)." } } } } } }, "CompanyParameterValue": { "type": "object", "description": "Item do body de `PUT /company/integration/{idcompanyintegration}/parameter`.", "required": [ "Key" ], "properties": { "Key": { "type": "string", "description": "Chave técnica da parametrização (deve existir em `TypeCompanyParameters` para o tipo da integração)." }, "Value": { "nullable": true, "description": "Novo valor. Aceita string, número, booleano — convertido para string e gravado em `Value`. Espaços nas pontas são removidos (`trim`). `null` ou omitido grava `NULL`.", "type": "string" } } }, "ProductionListItem": { "type": "object", "description": "Item de `GET /sku/production`. Cabeçalho da OP com SKU produzido, status, armazém e pedido vinculado.", "properties": { "IDStockKeepingUnitProduction": { "type": "integer", "format": "int32", "description": "Identificador da ordem de produção." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de cadastro." }, "RecordUserCreated": { "type": "string", "description": "Login do usuário que criou a OP." }, "IDSku": { "type": "integer", "format": "int32", "description": "Id do SKU produzido." }, "IDSkuCompany": { "type": "string", "description": "Código externo do SKU." }, "SkuName": { "type": "string", "description": "Nome do SKU principal da ordem." }, "Quantity": { "type": "number", "description": "Quantidade a produzir (decimal 10,2)." }, "DateEstimated": { "type": "string", "format": "date", "nullable": true, "description": "Data estimada de conclusão." }, "IDTypeStatusSkuProduction": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Status da etapa de produção: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado." }, "TypeStatusSkuProduction": { "type": "string", "enum": [ "Finalizado", "Aberto", "Em andamento", "Cancelado" ], "description": "Texto pronto para exibição." }, "Comments": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Observações livres da ordem." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido vinculado (quando a OP foi criada a partir de um pedido)." }, "Order": { "type": "string", "nullable": true, "description": "Número externo do pedido." }, "OrderFrom": { "type": "string", "nullable": true, "description": "Canais de origem do pedido (concatenado)." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém de onde os insumos são consumidos e onde o produto final fica disponível." }, "WarehouseName": { "type": "string", "description": "Nome do depósito de destino da produção." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "nullable": true, "description": "Identificador do centro de distribuição associado ao depósito." }, "IDPurchase": { "type": "integer", "nullable": true, "description": "Recebimento gerado ao finalizar." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do SKU produzido (com sufixo `-thumbnail`)." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." } } }, "ProductionDetail": { "type": "object", "description": "Item de `GET /sku/production/{idstockkeepingunitproduction}`. Cabeçalho + custo total + itens consumidos + etapas com tempo gasto e decorrido.", "allOf": [ { "$ref": "#/components/schemas/ProductionListItem" }, { "type": "object", "properties": { "ValueCostTotal": { "type": "number", "description": "Soma de `ValueCostTotal` dos movimentos de consumo." }, "TimeSpentTotal": { "type": "string", "description": "Soma de `TimeSpent` lançado nas etapas. Formato `HH:MM:SS`." }, "TimeElapsedTotal": { "type": "string", "description": "Soma de (`RecordTimestampEnd` - `RecordTimestampStart`) das etapas. Formato `HH:MM:SS`." }, "Items": { "type": "array", "description": "Insumos/matérias-primas consumidos.", "items": { "type": "object", "properties": { "IDSkuMovement": { "type": "integer", "description": "Identificador da movimentação de estoque associada à ordem de produção." }, "IDSku": { "type": "integer", "description": "Identificador do SKU produzido." }, "IDSkuCompany": { "type": "string", "description": "Código do SKU na empresa." }, "SkuName": { "type": "string", "description": "Nome do SKU produzido." }, "Quantity": { "type": "number", "description": "Quantidade produzida." }, "ValueCostTotal": { "type": "number", "description": "Custo total da produção em R$." }, "ValueCostUnit": { "type": "number", "description": "`ValueCostTotal / Quantity`, 4 casas." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém de destino da produção." }, "WarehouseName": { "type": "string", "description": "Nome do armazém de destino." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do SKU produzido." }, "Comments": { "type": "string", "nullable": true, "description": "Observações da ordem de produção." }, "AccountName": { "type": "string", "description": "Conta (prefixo) da empresa." } } } }, "StockKeepingUnitProductionLineSteps": { "type": "array", "description": "Etapas da OP, ordenadas por `ProductionLineStepOrder`.", "items": { "type": "object", "properties": { "IDStockKeepingUnitProductionSteps": { "type": "integer", "description": "Identificador da etapa da ordem de produção." }, "IDStockKeepingUnitProductionLineSteps": { "type": "integer", "description": "Identificador da etapa na linha de produção." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação da ordem de produção." }, "ProductionLineStepName": { "type": "string", "description": "Nome da etapa da linha de produção." }, "ProductionLineStepOrder": { "type": "number", "description": "Ordem (sequência) da etapa na linha de produção." }, "IDTypeStatusSkuProduction": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Status da etapa de produção: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado." }, "TypeStatusSkuProduction": { "type": "string", "description": "Descrição do status da etapa." }, "TimeSpent": { "type": "string", "nullable": true, "description": "`HH:MM:SS` — informado pelo operador." }, "TimeElapsed": { "type": "string", "nullable": true, "description": "`HH:MM:SS` — diferença entre `RecordTimestampStart` e `RecordTimestampEnd`." }, "RecordTimestampStart": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de início da etapa. `null` enquanto não iniciada." }, "RecordTimestampEnd": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de conclusão da etapa. `null` enquanto não finalizada." }, "RecordUserCreatedEnd": { "type": "string", "nullable": true, "description": "Login do usuário que finalizou a etapa." }, "UserNameEnd": { "type": "string", "nullable": true, "description": "Nome do usuário que finalizou a etapa." } } } } } } ] }, "ProductionCreate": { "type": "object", "description": "Corpo do `POST /sku/production`.", "required": [ "IDSku", "Quantity", "IDStockKeepingUnitWarehouse" ], "properties": { "IDSku": { "type": "integer", "description": "SKU a produzir. Precisa ter `OwnProduction = 1` no cadastro do SKU." }, "Quantity": { "type": "number", "description": "Quantidade a produzir. Os componentes do kit do SKU são consumidos proporcionalmente." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém de onde os insumos são consumidos e onde o produto final fica disponível." }, "DateEstimated": { "type": "string", "format": "date", "nullable": true, "description": "Data estimada de conclusão." }, "Comments": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Observações livres da ordem de produção." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido que originou a OP (opcional)." } } }, "ProductionUpdate": { "type": "object", "description": "Corpo do `PUT /sku/production/{idstockkeepingunitproduction}`. Apenas campos enviados são atualizados.", "properties": { "DateEstimated": { "type": "string", "format": "date", "nullable": true, "description": "Data estimada de conclusão da ordem de produção." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres." }, "IDTypeStatusSkuProduction": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Status da etapa de produção: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Identificador do pedido de venda que originou esta ordem de produção (quando produção sob demanda)." } } }, "ProductionFinish": { "type": "object", "description": "Corpo do `POST /sku/production/{idstockkeepingunitproduction}/finish`. Todos opcionais.", "properties": { "IDPurchase": { "type": "integer", "nullable": true, "description": "Quando informado, lança o produto produzido neste Recebimento existente em vez de criar um novo." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "nullable": true, "description": "Centro de distribuição do recebimento. Default: o do armazém da OP." } } }, "ProductionFinishResponse": { "type": "array", "description": "Resposta de `POST /sku/production/{idstockkeepingunitproduction}/finish` — detalhe do Recebimento gerado (mesmo formato do `GET /purchase/{idpurchase}`).", "items": { "type": "object", "additionalProperties": true } }, "ProductionSkuAdd": { "type": "object", "description": "Corpo do `POST /sku/production/{idstockkeepingunitproduction}/sku`.", "required": [ "IDSku", "Quantity" ], "properties": { "IDSku": { "type": "integer", "description": "SKU a consumir (tipo 3=SKU, 6=matéria-prima, 7=variante)." }, "Quantity": { "type": "number", "description": "Quantidade do SKU a produzir nesta linha da ordem." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "nullable": true, "description": "Armazém do consumo. Default: o armazém da OP." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres do item de produção." } } }, "ProductionSkuUpdate": { "type": "object", "description": "Corpo do `PUT /sku/production/{idstockkeepingunitproduction}/sku/{idskumovement}`. Apenas campos enviados são atualizados.", "properties": { "Quantity": { "type": "number", "description": "Quantidade do SKU a produzir nesta linha." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Depósito de destino do item produzido." }, "ValueCostTotal": { "type": "number", "description": "Permite ajustar manualmente o custo total da linha." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres do item de produção." } } }, "ProductionStepUpdate": { "type": "object", "description": "Corpo do `PUT /sku/production/{idstockkeepingunitproduction}/steps/{idstockkeepingunitproductionsteps}`.", "required": [ "IDTypeStatusSkuProduction" ], "properties": { "IDTypeStatusSkuProduction": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Status da etapa de produção: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado." }, "TimeSpent": { "type": "string", "nullable": true, "description": "Tempo gasto na etapa, formato `HH:MM:SS`. Informado pelo operador para registrar o tempo efetivamente trabalhado (diferente do tempo decorrido entre início e fim)." } } }, "ProductionLineListItem": { "type": "object", "description": "Item de `GET /sku/production/line`. Linha de produção com suas etapas.", "properties": { "IDStockKeepingUnitProductionLine": { "type": "integer", "description": "Identificador da linha de produção." }, "ProductionLineName": { "type": "string", "maxLength": 100, "description": "Nome da linha de produção." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` = é a linha padrão da empresa (usada quando o SKU não tem linha vinculada)." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` = ativa." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "QtySteps": { "type": "integer", "description": "Quantidade de etapas cadastradas na linha." }, "StockKeepingUnitProductionLineSteps": { "type": "array", "description": "Etapas ordenadas por `ProductionLineStepOrder`.", "items": { "type": "object", "properties": { "IDStockKeepingUnitProductionLineSteps": { "type": "integer", "description": "Identificador da etapa da linha de produção." }, "ProductionLineStepName": { "type": "string", "maxLength": 100, "description": "Nome da etapa (ex.: Corte, Costura, Embalagem)." }, "ProductionLineStepOrder": { "type": "number", "description": "Decimal (3,1) — permite inserir entre etapas existentes com `1.5`." } } } } } }, "ProductionLineCreate": { "type": "object", "description": "Corpo do `POST /sku/production/line`.", "required": [ "ProductionLineName" ], "properties": { "ProductionLineName": { "type": "string", "maxLength": 100, "description": "Nome da linha de produção." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` = marca como padrão (desmarca a anterior)." } } }, "ProductionLineUpdate": { "type": "object", "description": "Corpo do `PUT /sku/production/line/{idstockkeepingunitproductionline}`.", "properties": { "ProductionLineName": { "type": "string", "maxLength": 100, "description": "Nome da linha de produção." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` define esta linha como padrão (apenas uma linha por empresa pode ser padrão)." } } }, "ProductionLineStepCreate": { "type": "object", "description": "Corpo dos endpoints `POST` e `PUT` de etapas de linha.", "required": [ "ProductionLineStepName", "ProductionLineStepOrder" ], "properties": { "ProductionLineStepName": { "type": "string", "maxLength": 100, "description": "Nome da etapa da linha de produção (ex.: Corte, Costura, Acabamento)." }, "ProductionLineStepOrder": { "type": "number", "description": "Decimal (3,1) — define a ordem dentro da linha." } } }, "TrackingTemplateListItem": { "type": "object", "description": "Item de `GET /carrier/tracking-template`. Cada linha é uma regra de disparo de mensagem amarrada a um status de tracking.", "properties": { "IDCarrierTrackingTemplate": { "type": "integer", "format": "int32", "description": "Identificador do template de rastreio." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do template." }, "CarrierTrackingTemplateName": { "type": "string", "maxLength": 100, "nullable": true, "description": "Nome amigável da regra (ex.: `Comunicado de envio`, `Aviso de entrega`)." }, "CarrierTrackingTemplateStatus": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` = ativo (dispara); `0` = inativo (não dispara)." }, "IDTypeCarrierTrackingTemplate": { "type": "integer", "enum": [ 1, 2 ], "description": "`1` = e-mail; `2` = WhatsApp/Webhook." }, "TypeCarrierTrackingTemplate": { "type": "string", "enum": [ "e-mail", "WhatsApp" ], "description": "Texto resolvido do tipo." }, "IDStatusTracking": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "description": "Macro status de tracking que dispara o template. 1=Finalizado, 2=Em andamento, 3=Atenção, 4=Não iniciado, 5=Saiu para entrega, 6=Extraviado, 7=Devolvido, 8=Postado." }, "StatusTracking": { "type": "string", "description": "Texto resolvido (Finalizado, Em andamento, Atenção, etc.)." }, "EmailTitle": { "type": "string", "maxLength": 150, "description": "Assunto do e-mail. Aceita variáveis (`{{IDOrder}}`, `{{ConsumerNameCorporateName}}`, etc.). Para tipo WhatsApp/Webhook, pode ficar vazio." }, "HTML": { "type": "string", "description": "Corpo do template (HTML para e-mail; texto/JSON para WhatsApp/Webhook). Aceita variáveis substituídas no momento do disparo." }, "CC": { "type": "string", "maxLength": 200, "nullable": true, "description": "Lista de e-mails em **CC**, separados por vírgula." }, "CCO": { "type": "string", "maxLength": 200, "nullable": true, "description": "Lista de e-mails em **CCO**, separados por vírgula." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração que entrega a mensagem (provedor de e-mail ou de WhatsApp configurado em Configurações → Integrações)." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Texto resolvido `IntegrationName - CompanyIntegrationName` da integração de entrega." }, "IDCompanyIntegrationOrderList": { "type": "array", "items": { "type": "string" }, "description": "Lista de identificadores das integrações de origem do pedido para as quais o template dispara. Vazio = dispara para todas. Armazenado no banco como string separada por vírgula e exposto como array." }, "IDTypeOrderList": { "type": "array", "items": { "type": "string" }, "description": "Lista de identificadores dos tipos de pedido para os quais o template dispara. Vazio = dispara para todos." } } }, "TrackingTemplateCreate": { "type": "object", "description": "Corpo do `POST /carrier/tracking-template`.", "required": [ "IDStatusTracking", "HTML", "IDTypeCarrierTrackingTemplate" ], "properties": { "CarrierTrackingTemplateName": { "type": "string", "maxLength": 100, "nullable": true, "description": "Nome amigável da regra." }, "IDTypeCarrierTrackingTemplate": { "type": "integer", "enum": [ 1, 2 ], "description": "`1` = e-mail; `2` = WhatsApp/Webhook. Default `1`." }, "IDStatusTracking": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "description": "Macro status que dispara o template." }, "HTML": { "type": "string", "description": "Corpo do template. HTML para e-mail; texto/JSON para WhatsApp/Webhook." }, "EmailTitle": { "type": "string", "maxLength": 150, "nullable": true, "description": "Assunto. Obrigatório para e-mail." }, "CC": { "type": "string", "maxLength": 200, "nullable": true, "description": "E-mails em CC separados por vírgula. Cada item validado contra regex de e-mail." }, "CCO": { "type": "string", "maxLength": 200, "nullable": true, "description": "E-mails em CCO separados por vírgula. Mesma validação." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração de entrega (provedor de e-mail/WhatsApp). Validada contra a empresa." }, "IDCompanyIntegrationOrderList": { "oneOf": [ { "type": "array", "items": { "type": "integer" } }, { "type": "string" } ], "description": "Restringe o disparo às integrações de origem do pedido informadas. Aceita array de ids ou string separada por vírgula. Vazio = todas. Validado contra `Show = 1`." }, "IDTypeOrderList": { "oneOf": [ { "type": "array", "items": { "type": "integer" } }, { "type": "string" } ], "description": "Restringe o disparo aos tipos de pedido informados. Aceita array de ids ou string separada por vírgula. Vazio = todos. Validado contra `Status = 1`." }, "CarrierTrackingTemplateStatus": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` = ativo (dispara); `0` = inativo. Default `1`." } } }, "TrackingTemplateUpdate": { "type": "object", "description": "Corpo do `PUT /carrier/tracking-template/{idcarriertrackingtemplate}`. Todos os campos opcionais — atualização parcial.", "properties": { "CarrierTrackingTemplateName": { "type": "string", "maxLength": 100, "nullable": true, "description": "Nome amigável da regra." }, "IDTypeCarrierTrackingTemplate": { "type": "integer", "enum": [ 1, 2 ], "description": "`1` = e-mail; `2` = WhatsApp/Webhook. Default `1`." }, "IDStatusTracking": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "description": "Macro status que dispara o template." }, "HTML": { "type": "string", "description": "Corpo do template. HTML para e-mail; texto/JSON para WhatsApp/Webhook." }, "EmailTitle": { "type": "string", "maxLength": 150, "nullable": true, "description": "Assunto. Obrigatório para e-mail." }, "CC": { "type": "string", "maxLength": 200, "nullable": true, "description": "E-mails em CC separados por vírgula. Cada item validado contra regex de e-mail." }, "CCO": { "type": "string", "maxLength": 200, "nullable": true, "description": "E-mails em CCO separados por vírgula. Mesma validação." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração de entrega (provedor de e-mail/WhatsApp). Validada contra a empresa." }, "IDCompanyIntegrationOrderList": { "oneOf": [ { "type": "array", "items": { "type": "integer" } }, { "type": "string" } ], "description": "Restringe o disparo às integrações de origem do pedido informadas. Aceita array de ids ou string separada por vírgula. Vazio = todas. Validado contra `Show = 1`." }, "IDTypeOrderList": { "oneOf": [ { "type": "array", "items": { "type": "integer" } }, { "type": "string" } ], "description": "Restringe o disparo aos tipos de pedido informados. Aceita array de ids ou string separada por vírgula. Vazio = todos. Validado contra `Status = 1`." }, "CarrierTrackingTemplateStatus": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` = ativo (dispara); `0` = inativo. Default `1`." } } }, "CarrierQuotationActionRuleEnum": { "type": "integer", "description": "Tipo de ação aplicada quando todas as condições da regra são atendidas.\n\n- `1` — Adicionar X dias no prazo (`ActionValue` = dias, inteiro)\n- `2` — Alterar o preço R$ (`ActionValue` = valor em reais a somar/subtrair ao preço cotado)\n- `3` — Alterar o preço X% (`ActionValue` = percentual sobre o preço cotado)\n- `5` — Adicionar ao preço um % do valor da nota X% (`ActionValue` = percentual aplicado sobre `OrderValue`)\n- `6` — Fixar o preço em (`ActionValue` = valor em reais que sobrescreve o frete cotado)\n- `7` — Fixar o preço em uma % do valor da nota (`ActionValue` = percentual sobre `OrderValue`)\n- `9` — Excluir transportadoras selecionadas (sem `ActionValue`; exige condição 3 — `Transportadora`)\n- `10` — Fixar o preço unitário R$ X (`ActionValue` = preço por item, multiplicado pela quantidade)\n- `13` — Adicionar prazo de manuseio do CD (`ActionValue` = dias úteis somados ao prazo)\n\nAções inativas (só aparecem em regras legadas): `4` (Frete proporcional para mais barato), `8` (Excluir), `11` (Frete grátis para o mais barato), `12` (Nunca aplicar frete grátis), `14` (Alterar o prazo por intervalo de janela fixa).", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14 ] }, "CarrierQuotationConditionRuleEnum": { "type": "integer", "description": "Tipo de condição. Todas as condições marcadas precisam ser verdadeiras (AND) para a regra disparar. Formato de `ConditionValue` (sempre array de strings):\n\n- `1` — Estado/Região: cada item é `UF` ou `UFCAPITAL`/`UFINTERIOR` (ex.: `SP`, `SPCAPITAL`).\n- `2` — CEP Destino: cada item é faixa `|` (8 dígitos cada, sem hífen).\n- `3` — Transportadora: cada item é `IDSupplier` (apenas fornecedores com `IDTypeSupplier=2` da empresa).\n- `4` — Valor do pedido: cada item é faixa `|` em reais (ponto decimal, sem R$).\n- `6` — Integração: cada item é `IDCompanyIntegration` da empresa.\n- `7` — Peso (kg): cada item é faixa `|`.\n- `8` — SKUs iguais a: cada item é `|`.\n- `9` — SKUs diferentes de: cada item é `|`.\n- `10` — CEP Origem: cada item é faixa `|`.\n\nCondição inativa no banco: `5` (Comparação preço de custo).", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ] }, "CarrierQuotationConditionPayload": { "type": "object", "description": "Uma condição da regra. O sistema valida `ConditionValue` de acordo com `IDTypeCarrierQuotationConditionRule`.", "required": [ "IDTypeCarrierQuotationConditionRule", "ConditionValue" ], "properties": { "IDTypeCarrierQuotationConditionRule": { "$ref": "#/components/schemas/CarrierQuotationConditionRuleEnum", "description": "Tipo da condição a aplicar na regra: `1` Estado/Região, `2` CEP Destino, `3` Transportadora, `4` Valor do pedido, `6` Integração, `7` Peso (kg), `8` Skus iguais a, `9` Skus diferentes de, `10` CEP Origem." }, "ConditionValue": { "type": "array", "items": { "type": "string" }, "description": "Lista de valores aceitos por esta condição. O formato depende do tipo:\n- 1 (Estado/Região): `[\"SP\", \"SPCAPITAL\", \"RJINTERIOR\"]`\n- 2 (CEP Destino), 10 (CEP Origem): `[\"01000000|01999999\", \"02000000|02999999\"]`\n- 3 (Transportadora): `[\"42\", \"108\"]` (lista de `IDSupplier`)\n- 4 (Valor do pedido): `[\"0|100.00\", \"100.01|500.00\"]`\n- 6 (Integração): `[\"15\", \"22\"]` (lista de `IDCompanyIntegration`)\n- 7 (Peso): `[\"0|5\", \"5.001|10\"]`\n- 8/9 (SKUs): `[\"12345|Camiseta polo M azul\", \"12346|Camiseta polo G azul\"]`" } } }, "CarrierQuotationConditionItem": { "type": "object", "description": "Condição da regra como devolvida pelo GET/list — `ConditionValue` já vem quebrado em vetor pelo separador `,`.", "properties": { "IDCarrierQuotationRuleCondition": { "type": "integer", "description": "Identificador da condição da regra de cotação de frete." }, "IDTypeCarrierQuotationConditionRule": { "$ref": "#/components/schemas/CarrierQuotationConditionRuleEnum", "description": "Tipo da condição: `1` Estado/Região (UF de destino), `2` CEP Destino, `3` Transportadora, `4` Valor do pedido, `6` Integração (canal de venda), `7` Peso (kg), `8` Skus iguais a (lista de SKUs incluídos), `9` Skus diferentes de (lista de SKUs excluídos), `10` CEP Origem." }, "TypeCarrierQuotationConditionRule": { "type": "string", "description": "Nome amigável da condição (ex.: `Estado/Região`, `CEP Destino`, `Transportadora`)." }, "ConditionValue": { "type": "array", "items": { "type": "string" }, "description": "Valores da condição. O formato depende de `IDTypeCarrierQuotationConditionRule`: lista de strings para tipos categóricos (UFs, transportadoras, integrações, SKUs); lista com par `[min, max]` para tipos de faixa (valor do pedido, peso, CEP)." } } }, "CarrierQuotationRuleLogItem": { "type": "object", "description": "Entrada do histórico de alterações da regra.", "properties": { "IDCarrierQuotationRuleLog": { "type": "integer", "description": "Identificador do registro de histórico (log) da regra de cotação — cada criação/alteração da regra gera uma linha." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que o registro de histórico foi gerado." }, "RecordUserCreated": { "type": "integer", "description": "`IDUser` que fez a alteração." }, "Login": { "type": "string", "description": "Login do usuário." }, "Data": { "type": "string", "description": "JSON serializado com as mudanças. Cada chave é o nome do campo alterado e o valor segue um destes formatos:\n- `\"DE: PARA: \"` — alteração de campo do cabeçalho.\n- `\"_Adicionado\": \"\"` — condição adicionada.\n- `\"_Removido\": \"\"` — condição removida." } } }, "CarrierQuotationRuleListItem": { "type": "object", "description": "Item de `GET /carrier/quotation/rule`.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da regra." }, "IDCarrierQuotationRule": { "type": "integer", "description": "Identificador da regra de simulação de frete." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de criação da regra." }, "CarrierQuotationRuleName": { "type": "string", "description": "Nome amigável da regra (exibido na grid)." }, "Priority": { "type": "integer", "minimum": 1, "description": "Ordem de execução. Menor valor é avaliado primeiro." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "`1`=Ativo, `0`=Inativo. (`2`=Excluído fica oculto na listagem.)" }, "DateFrom": { "type": "string", "format": "date", "description": "Início da vigência. `1900-01-01` quando vigência foi desligada (\"sempre vigente\")." }, "DateTo": { "type": "string", "format": "date", "description": "Fim da vigência. `4000-01-01` quando vigência foi desligada." }, "IDTypeCarrierQuotationActionRule": { "$ref": "#/components/schemas/CarrierQuotationActionRuleEnum", "description": "Tipo de ação aplicada quando todas as condições da regra são atendidas. Lista de valores em `CarrierQuotationActionRuleEnum`." }, "TypeCarrierQuotationActionRule": { "type": "string", "description": "Nome amigável da ação." }, "ActionValue": { "type": "string", "nullable": true, "description": "Valor associado à ação. Para ações de valor em R$ (`2`, `6`, `10`), vem como decimal em string (`\"15.50\"`); para `%` (`3`, `5`, `7`), valor percentual (`\"10\"` = 10%); para prazo (`1`, `13`), inteiro de dias (`\"2\"`); para ação `9` (Excluir transportadoras), vem `null`." }, "ConditionsRules": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotationConditionItem" }, "description": "Lista das condições (`AND` entre elas) que precisam ser verdadeiras para a regra disparar. Cada item segue `CarrierQuotationConditionItem`." }, "ConditionNames": { "type": "string", "description": "Nomes das condições concatenados por vírgula (usado na grid)." }, "CarrierQuotationRuleLog": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotationRuleLogItem" }, "description": "Histórico de alterações da regra. Cada entrada segue `CarrierQuotationRuleLogItem`." } } }, "CarrierQuotationRuleDetail": { "allOf": [ { "$ref": "#/components/schemas/CarrierQuotationRuleListItem" } ], "description": "Mesmo formato da listagem — o detalhe (`GET /carrier/quotation/rule/{idcarrierquotationrule}`) e o retorno do POST/PUT devolvem um array com 1 item." }, "CarrierQuotationRuleCreate": { "type": "object", "description": "Corpo do `POST /carrier/quotation/rule`. Toda regra precisa de pelo menos 1 condição.", "required": [ "CarrierQuotationRuleName", "Priority", "IDTypeCarrierQuotationActionRule", "Conditions" ], "properties": { "CarrierQuotationRuleName": { "type": "string", "description": "Nome da regra (apresentado na grid)." }, "Priority": { "type": "integer", "minimum": 1, "description": "Ordem de execução. Menor valor é avaliado primeiro. UI sugere 1, 2, 3..." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "`1`=Ativo (default), `0`=Inativo." }, "DateFrom": { "type": "string", "format": "date", "description": "Início da vigência (`YYYY-MM-DD`). Quando a UI desliga o switch \"Possui vigência\", o frontend envia `1900-01-01`." }, "DateTo": { "type": "string", "format": "date", "description": "Fim da vigência (`YYYY-MM-DD`). Quando o switch \"Possui vigência\" é desligado, o frontend envia `4000-01-01`." }, "IDTypeCarrierQuotationActionRule": { "$ref": "#/components/schemas/CarrierQuotationActionRuleEnum", "description": "Tipo de ação aplicada quando todas as condições da regra são atendidas. Valores em `CarrierQuotationActionRuleEnum`." }, "ActionValue": { "type": "string", "nullable": true, "description": "Valor da ação. Para ação `9` (Excluir transportadoras), enviar `null` ou omitir." }, "Conditions": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CarrierQuotationConditionPayload" }, "description": "Lista de condições (`AND` entre elas) — toda regra precisa de pelo menos uma. Cada item segue `CarrierQuotationConditionPayload`." } } }, "CarrierQuotationVolumeItem": { "type": "object", "description": "Um volume/produto do array `Quotations` do POST. Para **Volume** (`IDTypeSimulation=2`), envie dimensões diretamente. Para **Produto** (`IDTypeSimulation=1`), o frontend já multiplica os campos pela quantidade antes de chamar a API — o sistema recebe só o resultado.", "required": [ "Weight", "Height", "Width", "Length" ], "properties": { "Weight": { "type": "number", "format": "double", "minimum": 0.001, "description": "Peso em quilos. A soma dos pesos vira o peso total (`weight` no sistema)." }, "Height": { "type": "number", "format": "double", "description": "Altura em centímetros. Sistema pega o **maior** valor entre os volumes." }, "Width": { "type": "number", "format": "double", "description": "Largura em centímetros. Sistema **soma** os valores entre os volumes." }, "Length": { "type": "number", "format": "double", "description": "Comprimento em centímetros. Sistema pega o **maior** valor entre os volumes." }, "ValueInvoice": { "type": "number", "format": "double", "nullable": true, "description": "Valor da nota fiscal em reais. Usado para calcular Gris, Advalorem, Tde, taxas de seguro e outras taxas percentuais. Soma de todos os volumes vira `ValueInvoice` da simulação." }, "Quantity": { "type": "number", "format": "double", "nullable": true, "description": "Quantidade do produto. Só relevante quando `IDTypeSimulation=1` — neste caso o frontend já multiplica os campos antes de enviar." } } }, "CarrierQuotationCreate": { "type": "object", "description": "Corpo do `POST /carrier/quotation`.", "required": [ "ShippingPostalCode", "Quotations" ], "properties": { "ShippingPostalCode": { "type": "string", "description": "CEP destino. Aceita com ou sem hífen; o sistema remove caracteres não numéricos e padroniza em 8 dígitos com zeros à esquerda." }, "Description": { "type": "string", "nullable": true, "description": "Descrição livre para identificar a simulação na listagem." }, "Quotations": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CarrierQuotationVolumeItem" }, "description": "Lista de volumes/produtos a simular (mínimo 1). O sistema agrega: soma de pesos, larguras e valores de nota; pega o maior entre alturas e comprimentos; usa a contagem como `Volumes`. Cada item segue `CarrierQuotationVolumeItem`." }, "OriginPostalCode": { "type": "string", "nullable": true, "description": "CEP origem. Quando vazio, o sistema usa `CompanyAddressPostalCode` da empresa." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Quando a simulação é feita a partir de um pedido existente, amarra para fins de auditoria." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração de origem da chamada (preenchido automaticamente quando vem de marketplace)." }, "IDSkuHub": { "type": "string", "nullable": true, "description": "SKU enviado pelo canal (preenchido automaticamente quando vem de marketplace)." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "SKU local correspondente (preenchido automaticamente quando vem de marketplace)." } } }, "CarrierQuotationListItem": { "type": "object", "description": "Item de `GET /carrier/quotation`. Cabeçalho da simulação sem as linhas por transportadora.", "properties": { "IDCarrierQuotation": { "type": "integer", "description": "Identificador da simulação." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora da simulação." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da simulação." }, "Login": { "type": "string", "description": "Login do usuário que rodou a simulação." }, "Description": { "type": "string", "nullable": true, "description": "Descrição livre informada no `POST` para identificar a simulação na listagem." }, "ShippingPostalCode": { "type": "string", "description": "CEP destino, 8 dígitos." }, "ShippingState": { "type": "string", "description": "UF do CEP destino." }, "Weight": { "type": "number", "description": "Peso total agregado em kg (soma dos volumes)." }, "Height": { "type": "number", "description": "Maior altura entre os volumes em cm." }, "Width": { "type": "number", "description": "Soma das larguras dos volumes em cm." }, "Length": { "type": "number", "description": "Maior comprimento entre os volumes em cm." }, "ValueInvoice": { "type": "number", "nullable": true, "description": "Soma dos valores de nota dos volumes em R$. Base de cálculo para Gris, Advalorem e demais taxas percentuais." }, "Volumes": { "type": "integer", "description": "Quantidade de volumes enviados na cotação." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido vinculado à simulação (quando a cotação foi feita a partir de um pedido existente)." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração de origem da chamada (preenchido automaticamente quando a cotação vem de marketplace)." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Nome amigável `IntegrationName - CompanyIntegrationName`." }, "IDSkuHub": { "type": "string", "nullable": true, "description": "SKU do canal informado na cotação (preenchido automaticamente quando vem de marketplace)." }, "CarriersName": { "type": "string", "nullable": true, "description": "Lista de transportadoras que responderam, separadas por vírgula." }, "CarrierQuotationUUID": { "type": "string", "description": "UUID gerado no POST." } } }, "CarrierQuotationItemDetail": { "type": "object", "description": "Cotação devolvida por uma transportadora para a simulação.", "properties": { "IDCarrierQuotationRate": { "type": "integer", "description": "Identificador da linha de cotação retornada por uma transportadora dentro da cotação. Cada transportadora consultada gera uma linha; o usuário escolhe uma para o pedido." }, "IDCarrier": { "type": "integer", "description": "`IDSupplier` da transportadora." }, "SupplierNameCorporateName": { "type": "string", "description": "Razão social ou nome fantasia da transportadora cotada (`SupplierNameCorporateName`)." }, "CarrierLogoUrl": { "type": "string", "nullable": true, "description": "URL do logotipo da transportadora para exibição na tela de seleção." }, "CarrierModal": { "type": "string", "nullable": true, "description": "Modalidade da transportadora (cadastrada em **Modalidade Transportadora**)." }, "Attended": { "type": "integer", "enum": [ 0, 1, 3, 4 ], "description": "`1`=Atende, `0`=Não atende, `3`=Excluído por regra (ação 9), `4`=Fora da faixa de peso da tabela cadastrada." }, "AttendedDescription": { "type": "string", "description": "Texto pronto para exibição (`Atende`, `Não Atende`, `Excluído`, `Fora da faixa`)." }, "RateType": { "type": "string", "nullable": true, "description": "Tipo de tabela aplicada (varia por transportadora)." }, "WeightSelected": { "type": "number", "description": "Peso considerado no cálculo do frete em kg — maior entre `Weight` (peso real) e `WeightCubed` (peso cubado)." }, "WeightCubed": { "type": "number", "description": "Peso cubado em kg calculado a partir das dimensões do volume e do fator de cubagem da transportadora." }, "Weight": { "type": "number", "description": "Peso real total do volume em kg." }, "CarrierCubageKmM": { "type": "number", "description": "Índice de cubagem da transportadora (padrão 167)." }, "CarrierCubageFreeWeight": { "type": "number", "nullable": true, "description": "Peso mínimo abaixo do qual a cubagem é ignorada." }, "DaysTime": { "type": "number", "description": "Prazo final de entrega em dias úteis (após somar `CarrierAdditionalBusinessDays` e regras aplicáveis)." }, "CarrierAdditionalBusinessDays": { "type": "number", "description": "Dias úteis adicionais somados ao prazo base da tabela (ex.: dias de coleta + processamento configurados na transportadora)." }, "CutDaysTime": { "type": "integer", "description": "`1` quando a simulação rodou depois do horário de corte (`CarrierShippingCutTime`), `0` caso contrário." }, "RuleAdditionalDays": { "type": "number", "nullable": true, "description": "Dias adicionais por regra de simulação." }, "TotalDaysTime": { "type": "number", "description": "Soma de `DaysTime + CarrierAdditionalBusinessDays + CutDaysTime`." }, "TotalShowDaysTime": { "type": "number", "description": "Soma de `DaysTime + CarrierAdditionalBusinessDays + CutDaysTime + RuleAdditionalDays`." }, "ShipingValue": { "type": "number", "description": "Valor do frete cobrado pela transportadora antes das taxas adicionais e impostos (frete-peso/frete-valor)." }, "AdvaloremValue": { "type": "number", "description": "Valor do Ad valorem em reais (seguro proporcional ao valor da carga)." }, "AdvaloremValuePercent": { "type": "number", "description": "Alíquota percentual aplicada para cálculo do Ad valorem." }, "GrisValue": { "type": "number", "description": "Valor do GRIS (Gerenciamento de Risco) em reais." }, "GrisValuePercent": { "type": "number", "description": "Alíquota percentual aplicada para cálculo do GRIS." }, "TollValue": { "type": "number", "description": "Valor total de pedágio em reais." }, "TollFractionValue": { "type": "number", "description": "Valor de pedágio por fração de peso quando a transportadora cobra por fração (frequente no modal rodoviário)." }, "AccessDifficultyRateValue": { "type": "number", "description": "Taxa de dificuldade de acesso (TDA) — cobrança extra para regiões de difícil acesso." }, "DispatchFeeValue": { "type": "number", "description": "Taxa de despacho (TAS/TRT) cobrada por documento de transporte emitido." }, "DeliveryDifficultyRateValue": { "type": "number", "description": "Taxa de dificuldade de entrega — adicional para regiões/endereços específicos." }, "SECCATValue": { "type": "number", "description": "Valor da SECCAT (Seguro de Carga Aérea) — aplicada no modal aéreo." }, "TrafficRestrictionFeeValue": { "type": "number", "description": "Taxa de restrição de tráfego — adicional para entregas em zonas com restrição de circulação (centros urbanos)." }, "AdministrationFeeValue": { "type": "number", "description": "Taxa de administração da transportadora." }, "CTEFeeValue": { "type": "number", "description": "Taxa de emissão de CT-e (Conhecimento de Transporte Eletrônico)." }, "SUFRAMAFeeValue": { "type": "number", "description": "Taxa SUFRAMA — adicional para entregas na Zona Franca de Manaus." }, "FluvialInsuranceFee": { "type": "number", "description": "Adicional de seguro para transporte fluvial." }, "OtherFee": { "type": "number", "description": "Alíquota percentual de outras taxas da tabela da transportadora." }, "OtherFeeValue": { "type": "number", "description": "Valor em reais das outras taxas calculado a partir de `OtherFee`." }, "IcmsValue": { "type": "number", "description": "Valor do ICMS embutido no frete em reais." }, "AdjustedValue": { "type": "number", "description": "Ajuste vindo do `CarrierAuctionPenalty` da transportadora." }, "RuleAdditionalValue": { "type": "number", "nullable": true, "description": "Valor adicional aplicado pela regra de simulação." }, "CarrierQuotationRuleValueName": { "type": "string", "nullable": true, "description": "Nome da regra que alterou o valor (quando houve)." }, "CarrierQuotationRuleDaysName": { "type": "string", "nullable": true, "description": "Nome da regra que alterou o prazo (quando houve)." }, "IDCarrierQuotationRuleValue": { "type": "integer", "nullable": true, "description": "Identificador da regra de cotação aplicada que alterou o valor final (regra de ajuste de preço). Vazio quando nenhuma regra de valor foi aplicada." }, "IDCarrierQuotationRuleDays": { "type": "integer", "nullable": true, "description": "Identificador da regra de cotação aplicada que alterou o prazo de entrega. Vazio quando nenhuma regra de prazo foi aplicada." }, "PriceRounding": { "type": "number", "nullable": true, "description": "Quando definido entre 0 e 1, arredonda `ShippingShowValue` para terminar nesse valor (ex.: `0.90` arredonda preço final para terminar em `,90`)." }, "SubtotalShippingValue": { "type": "number", "nullable": true, "description": "Soma de todos os componentes sem ICMS. `null` quando `Attended != 1`." }, "TotalShippingValue": { "type": "number", "nullable": true, "description": "Subtotal + ICMS. `null` quando `Attended != 1`." }, "IcmsValuePercent": { "type": "number", "nullable": true, "description": "Alíquota de ICMS aplicada no frete." }, "ShippingShowValue": { "type": "number", "nullable": true, "description": "Total + `AdjustedValue` + `RuleAdditionalValue`, com aplicação opcional de `PriceRounding`. **É o valor final mostrado ao cliente.**" } } }, "CarrierQuotationDetail": { "type": "object", "description": "Resposta de `GET /carrier/quotation/{idcarrierquotation}` e do POST. Cabeçalho + array `CarrierQuotations` com as linhas por transportadora.", "allOf": [ { "$ref": "#/components/schemas/CarrierQuotationListItem" }, { "type": "object", "properties": { "CompanyAddressPostalCode": { "type": "string", "description": "CEP de origem (endereço da empresa)." }, "CompanyAddressState": { "type": "string", "description": "UF de origem (estado da empresa)." }, "OriginPostalCode": { "type": "string", "nullable": true, "description": "CEP de origem informado na cotação, quando difere do endereço da empresa." }, "ShippingIbgeCode": { "type": "string", "nullable": true, "description": "Código IBGE do município de destino." }, "ShippingSameCity": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando o CEP destino é da mesma cidade da empresa (ICMS zerado nestas simulações)." }, "CarrierQuotations": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotationItemDetail" }, "description": "Ordenado por `Attended DESC, TotalDaysTime ASC, TotalShippingValue ASC`." } } } ] }, "CarrierQuotationErrorTypeEnum": { "type": "integer", "description": "Tipo do erro de cotação de frete.\n- `1` — Variação canal não localizada: SKU do canal (`IDSkuHub`) sem mapeamento na integração.\n- `2` — Sku não localizado: SKU não cadastrado.\n- `3` — Cep não localizado: CEP destino fora da base ou inválido.\n- `4` — Sku sem peso cadastrado.\n- `5` — Sku sem dimensões cadastradas (largura, altura ou comprimento).\n- `6` — Tipo integração de venda não localizada.", "enum": [ 1, 2, 3, 4, 5, 6 ] }, "CarrierQuotationErrorListItem": { "type": "object", "description": "Item de `GET /carrier/quotation/error`.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da chamada que falhou." }, "IDCarrierQuotationError": { "type": "integer", "description": "Identificador do registro de erro." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Quando o erro foi gerado." }, "ShippingPostalCode": { "type": "string", "description": "CEP destino que originou a chamada, padronizado em 8 dígitos com zeros à esquerda.", "maxLength": 8 }, "RecordUserCreated": { "type": "integer", "description": "`IDUser` que originou a chamada. Vários canais usam usuários técnicos fixos (Madeira Madeira = 2, Carrefour = 4, Tray = 294, integrações externas genéricas = 134)." }, "IDTypeCarrierQuotationError": { "$ref": "#/components/schemas/CarrierQuotationErrorTypeEnum", "description": "Tipo do erro de cotação. Valores em `CarrierQuotationErrorTypeEnum`." }, "TypeCarrierQuotationError": { "type": "string", "description": "Nome amigável do tipo de erro." }, "IDSkuHub": { "type": "string", "nullable": true, "description": "SKU enviado pelo marketplace na hora da cotação. Vem preenchido em erros de tipo `1`, `4`, `5` (problemas no produto)." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração de origem da chamada." }, "CompanyIntegrationName": { "type": "string", "nullable": true, "description": "Nome da integração no formato `IntegrationName - CompanyIntegrationName`." } } }, "PreCollectionPackageListItem": { "type": "object", "description": "Item de `GET /orders/package` (fila do Pré-Romaneio). Lista pacotes com dados do pedido, transportadora e romaneio atual.", "properties": { "IDPackage": { "type": "integer", "description": "Identificador interno do pacote." }, "PackageNumber": { "type": "integer", "nullable": true, "description": "Número sequencial do pacote dentro do pedido (1, 2, 3 …)." }, "ShippingId": { "type": "string", "nullable": true, "description": "Código de rastreio do pacote (etiqueta da transportadora)." }, "IDStatusPackage": { "type": "integer", "nullable": true, "description": "`TypeStatusPackage`. `1` = ok, `2` = volume processando.", "enum": [ 1, 2 ] }, "StatusPackage": { "type": "string", "nullable": true, "description": "Nome amigável do status do pacote." }, "IDOrder": { "type": "integer", "description": "Pedido amarrado ao pacote." }, "Order": { "type": "string", "description": "Número amigável do pedido." }, "OrderFrom": { "type": "string", "nullable": true, "description": "Origem do pedido (canal de venda)." }, "OrderPriority": { "type": "integer", "nullable": true, "description": "Prioridade do pedido (0=mais alta, 10=mais baixa)." }, "IDStatusOrder": { "type": "integer", "description": "`TypeStatusOrder`. Códigos relevantes nesta tela: `6` Aguardando expedição, `22` Aguardando romaneio, `7` Enviado, `8` Entregue com sucesso, `5` Segurar pedido, `100` Deletado." }, "StatusOrder": { "type": "string", "description": "Nome amigável do status do pedido." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de criação do pacote." }, "IDCarrier": { "type": "integer", "nullable": true, "description": "Transportadora do pedido." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Nome da transportadora." }, "AccountName": { "type": "string", "description": "Conta (multi-empresa)." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "CD do pedido." }, "DistributionCenterName": { "type": "string", "description": "Nome do CD." }, "IDOrdersCarrierCollectionList": { "type": "integer", "nullable": true, "description": "Romaneio em que o pacote está amarrado (`null` quando ainda não foi para nenhum romaneio)." } } }, "PreCollectionPostPayload": { "type": "object", "required": [ "Search", "IDCarrier" ], "description": "Payload de `POST /fulfillment/packing/collection-list/order` (bipagem para amarrar pacote ao romaneio).", "properties": { "Search": { "type": "string", "description": "**Código de rastreio do pacote** (`ShippingId`) **ou** **chave de acesso da NF-e** (44 dígitos). O sistema detecta o formato via regex `^\\d{44}$`: chave NF-e busca por `NfeChaveAcesso` e amarra todos os pacotes da nota; rastreio busca por `ShippingId` e amarra apenas o pacote bipado (no modo `PackagesOnOrdersCarrierCollectionList=1`)." }, "IDCarrier": { "type": "integer", "description": "Identificador da transportadora bipada. Precisa coincidir com `IDCarrier` do pedido — divergência retorna `[BadRequest] - Transportadora informada divergente do pedido`." } } }, "OrderTrackingListItem": { "type": "object", "description": "Item de `GET /orders/tracking`. Combina cabeçalho do pedido, último status de tracking e indicadores de pontualidade.", "properties": { "AccountName": { "type": "string", "description": "Conta (subdomínio) que originou o pedido." }, "IDOrder": { "type": "integer", "description": "Identificador do pedido." }, "Order": { "type": "string", "description": "Número do pedido amigável." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de criação do pedido." }, "TypeOrder": { "type": "string", "description": "Nome do tipo de pedido." }, "NfeNumber": { "type": "integer", "nullable": true, "description": "Número da nota fiscal principal emitida para o pedido." }, "OrderFrom": { "type": "string", "nullable": true, "description": "Origens externas amarradas ao pedido, concatenadas por vírgula." }, "IDConsumer": { "type": "integer", "nullable": true, "description": "Identificador do cliente." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Nome/razão social do cliente." }, "ConsumerCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ do cliente." }, "ConsumerEmail": { "type": "string", "nullable": true, "description": "E-mail do cliente." }, "ValueShipping": { "type": "number", "nullable": true, "description": "Valor do frete cobrado no pedido." }, "ShippingPostalCode": { "type": "string", "nullable": true, "description": "CEP de entrega." }, "ShippingCity": { "type": "string", "nullable": true, "description": "Cidade de entrega." }, "ShippingState": { "type": "string", "nullable": true, "description": "UF de entrega." }, "ShippingDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Maior `ShippingDate` do pedido (data de postagem)." }, "ShippingId": { "type": "string", "nullable": true, "description": "Lista de códigos de rastreio dos pacotes, concatenada por vírgula." }, "ShippingEstimateDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data estimada de entrega prometida ao consumidor (vinda do canal de venda)." }, "CarrierDeliveryDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data estimada de entrega prometida pela transportadora." }, "DeliveredDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o pedido foi marcado como entregue (`IDEvent = 45`)." }, "FinishDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o pedido foi finalizado (`IDEvent IN (45,52,57)`)." }, "ConsumerDeliveryDateDifference": { "type": "integer", "nullable": true, "description": "Dias entre `DeliveredDate` e `ShippingEstimateDate` (negativo = antes, positivo = depois)." }, "CarrierDeliveryDateDifference": { "type": "integer", "nullable": true, "description": "Dias entre `DeliveredDate` e `CarrierDeliveryDate`." }, "TrackingIDStatus": { "type": "integer", "nullable": true, "description": "Último `TrackingIDStatus` do pedido (`TypeStatusTracking`)." }, "StatusTracking": { "type": "string", "nullable": true, "description": "Nome amigável do status (`Postado`, `Em andamento`, `Saiu para entrega`, `Finalizado`, `Atenção`, `Extraviado`, `Devolvido`)." }, "TrackingLastStatus": { "type": "string", "nullable": true, "description": "Descrição do último evento de tracking enviado pela transportadora (`Description`)." }, "TrackingLastStatusRecordTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora do último evento de tracking enviado pela transportadora." }, "IDStatusDeliveryConsumer": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3, 4, 6 ], "description": "Indicador de pontualidade vs. data estimada para o consumidor: `1`=entregue antes do prazo, `2`=entregue após o prazo, `3`=ainda dentro do prazo, `4`=atrasado, `6`=entregue no dia exato." }, "StatusDeliveryConsumer": { "type": "string", "nullable": true, "description": "Nome amigável do indicador acima." }, "IDStatusDeliveryCarrier": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3, 4, 6 ], "description": "Mesmos códigos do consumidor, calculados contra `CarrierDeliveryDate`." }, "StatusDeliveryCarrier": { "type": "string", "nullable": true, "description": "Nome amigável do indicador de pontualidade calculado contra `CarrierDeliveryDate`." }, "IDStatusOrder": { "type": "integer", "description": "Status do pedido no idworks. Ver `support data/TypeStatusOrder.csv` para a lista de valores (ex.: `0`=Aberto, `1`=Fechado, `7`=Enviado, `8`=Entregue com sucesso, `90`=Cancelado)." }, "StatusOrder": { "type": "string", "nullable": true, "description": "Nome amigável do `IDStatusOrder` (`StatusOrder` ou `TypeStatusOrderCompany` quando a empresa renomeou)." }, "IDCarrier": { "type": "integer", "nullable": true, "description": "Identificador da transportadora vinculada ao pedido." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Nome/razão social da transportadora." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração (canal de venda / loja) de origem do pedido." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "`IntegrationName - CompanyIntegrationName`." }, "SalesChannelName": { "type": "string", "nullable": true, "description": "Nome do canal de venda (`IntegrationName`)." } } }, "DistributionCenterItem": { "type": "object", "description": "Centro de distribuição (`StockKeepingUnitDistributionCenter`).", "properties": { "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Identificador do centro de distribuição." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa dona." }, "DistributionCenterName": { "type": "string", "maxLength": 100, "description": "Nome do centro de distribuição." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "Apenas 1 CD por empresa pode ser padrão." }, "ShippingStreet": { "type": "string", "nullable": true, "description": "Logradouro." }, "ShippingNumber": { "type": "string", "nullable": true, "description": "Número." }, "ShippingComplement": { "type": "string", "nullable": true, "description": "Complemento." }, "ShippingNeighborhood": { "type": "string", "nullable": true, "description": "Bairro." }, "ShippingCity": { "type": "string", "nullable": true, "description": "Cidade." }, "ShippingState": { "type": "string", "nullable": true, "maxLength": 2, "description": "UF." }, "ShippingPostalCode": { "type": "string", "nullable": true, "description": "CEP em 8 dígitos (sem hífen)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação." } } }, "DistributionCenterCreate": { "type": "object", "description": "Corpo do POST/PUT de Centro de Distribuição.", "required": [ "DistributionCenterName" ], "properties": { "DistributionCenterName": { "type": "string", "maxLength": 100, "description": "Nome do centro de distribuição." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "Default `1` quando ausente. Marcar `1` zera o `Default` dos demais CDs." }, "ShippingStreet": { "type": "string", "nullable": true, "description": "Logradouro do endereço do centro de distribuição." }, "ShippingNumber": { "type": "string", "nullable": true, "description": "Número do endereço." }, "ShippingComplement": { "type": "string", "nullable": true, "description": "Complemento (sala, andar)." }, "ShippingNeighborhood": { "type": "string", "nullable": true, "description": "Bairro." }, "ShippingCity": { "type": "string", "nullable": true, "description": "Cidade." }, "ShippingState": { "type": "string", "nullable": true, "maxLength": 2, "description": "UF (sigla do estado)." }, "ShippingPostalCode": { "type": "string", "nullable": true, "description": "Sistema remove caracteres não-numéricos." } } }, "TypeStockKeepingUnitWarehouseEnum": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 ], "description": "Tipo de armazém: `1` Saudável · `2` Divergência · `3` Quarentena · `4` Recebimento · `5` Falta · `6` Vencido · `7` Auditoria · `8` Avaria · `9` Devolução · `10` Ressuprimento · `11` Outlet." }, "WarehouseItem": { "type": "object", "description": "Armazém (`StockKeepingUnitWarehouse`).", "properties": { "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDStockKeepingUnitWarehouse": { "type": "string", "description": "Devolvido como string (pode ser um número grande)." }, "WarehouseName": { "type": "string", "maxLength": 100, "description": "Nome do depósito." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Centro de distribuição ao qual o depósito pertence." }, "DistributionCenterName": { "type": "string", "description": "Nome do centro de distribuição." }, "IDTypeStockKeepingUnitWarehouse": { "$ref": "#/components/schemas/TypeStockKeepingUnitWarehouseEnum", "description": "Natureza do depósito (vide enum em `IDTypeStockKeepingUnitWarehouse`)." }, "TypeStockKeepingUnitWarehouse": { "type": "string", "description": "Nome amigável do tipo." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "Armazém padrão (apenas 1 por empresa)." }, "DefaultPurchase": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Armazém padrão de recebimento de compras (apenas 1 por empresa)." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "`1`=Ativo, `0`=Inativo (após soft delete)." }, "SumQuantity": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, o estoque deste armazém soma no saldo agregado dos SKUs." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Empresa que fatura por este armazém (3PL/operador logístico)." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "`AccountName - CompanyNameCorporateName` da empresa faturadora resolvido." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Conta da empresa faturadora associada ao depósito (usada na emissão de NF-e quando o estoque sai deste depósito)." }, "ShippingStreet": { "type": "string", "nullable": true, "description": "Logradouro." }, "ShippingNumber": { "type": "string", "nullable": true, "description": "Número." }, "ShippingComplement": { "type": "string", "nullable": true, "description": "Complemento." }, "ShippingNeighborhood": { "type": "string", "nullable": true, "description": "Bairro." }, "ShippingCity": { "type": "string", "nullable": true, "description": "Cidade." }, "ShippingState": { "type": "string", "nullable": true, "maxLength": 2, "description": "UF." }, "ShippingPostalCode": { "type": "string", "nullable": true, "description": "CEP." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação." } } }, "WarehouseCreate": { "type": "object", "description": "Corpo do POST/PUT de Armazém.", "required": [ "WarehouseName", "IDStockKeepingUnitDistributionCenter", "IDTypeStockKeepingUnitWarehouse" ], "properties": { "WarehouseName": { "type": "string", "maxLength": 100, "description": "Nome do depósito." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "CD pai." }, "IDTypeStockKeepingUnitWarehouse": { "$ref": "#/components/schemas/TypeStockKeepingUnitWarehouseEnum", "description": "Natureza do depósito: `1` Saudável (estoque vendável), `2` Divergência, `3` Quarentena, `4` Recebimento, `5` Falta, `6` Vencido, `7` Auditoria, `8` Avaria, `9` Devolução, `10` Ressuprimento." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Empresa faturadora — precisa ser associada à conta autenticada via CompanyMain." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` define este depósito como padrão da empresa para movimentações de venda." }, "DefaultPurchase": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` define este depósito como padrão para entradas de compra." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` depósito ativo; `0` desativado (não aceita movimentações)." }, "SumQuantity": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` faz a quantidade deste depósito ser somada ao estoque total disponível para venda; `0` mantém o saldo isolado (ex.: depósito de quarentena)." }, "ShippingStreet": { "type": "string", "nullable": true, "description": "Logradouro do endereço do depósito." }, "ShippingNumber": { "type": "string", "nullable": true, "description": "Número." }, "ShippingComplement": { "type": "string", "nullable": true, "description": "Complemento." }, "ShippingNeighborhood": { "type": "string", "nullable": true, "description": "Bairro." }, "ShippingCity": { "type": "string", "nullable": true, "description": "Cidade." }, "ShippingState": { "type": "string", "nullable": true, "maxLength": 2, "description": "UF." }, "ShippingPostalCode": { "type": "string", "nullable": true, "description": "CEP." } } }, "SkuLocationCategoryItem": { "type": "object", "description": "Categoria de endereço (`StockKeepingUnitLocationCategory`).", "properties": { "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDStockKeepingUnitLocationCategory": { "type": "integer", "description": "Identificador da categoria de endereço." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa." }, "StockKeepingUnitLocationCategoryName": { "type": "string", "maxLength": 100, "description": "Nome da categoria de endereço." }, "IsActive": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` categoria ativa; `0` desativada (não aparece no cadastro de endereços)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação." } } }, "SkuLocationCategoryCreate": { "type": "object", "required": [ "StockKeepingUnitLocationCategoryName" ], "properties": { "StockKeepingUnitLocationCategoryName": { "type": "string", "maxLength": 100, "description": "Nome único por empresa." } } }, "PickingListBasketHistoryItem": { "type": "object", "description": "Registro do histórico de pedidos passados pelo cesto.", "properties": { "IDPickingListBasketHistory": { "type": "integer", "description": "Identificador da linha do histórico de uso do cesto de separação." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido que ocupou o cesto neste evento do histórico. Vazio quando o evento foi de criação/liberação sem pedido amarrado." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora do evento (ocupação ou liberação do cesto)." } } }, "PickingListBasketItem": { "type": "object", "description": "Cesto picking (`PickingListBasket`).", "properties": { "AccountName": { "type": "string", "description": "Identificador da empresa dona do cesto." }, "IDPickingListBasket": { "type": "integer", "description": "Identificador do cesto." }, "ExternalId": { "type": "string", "description": "Código externo (etiqueta/barcode). Único por CD." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Identificador do CD a que o cesto pertence." }, "DistributionCenterName": { "type": "string", "description": "Nome amigável do CD." }, "BasketHeight": { "type": "number", "nullable": true, "description": "Altura em cm." }, "BasketWidth": { "type": "number", "nullable": true, "description": "Largura em cm." }, "BasketLength": { "type": "number", "nullable": true, "description": "Comprimento em cm." }, "BasketMaxWeight": { "type": "number", "nullable": true, "description": "Peso máximo em kg." }, "PickingListBasketStatus": { "type": "integer", "enum": [ 0, 1 ], "description": "`1`=Ativo, `0`=Inativo." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido atualmente amarrado ao cesto." }, "IDPickingList": { "type": "integer", "nullable": true, "description": "Picking list em curso vinculada ao pedido do cesto." }, "PickingListBasketHistory": { "type": "array", "items": { "$ref": "#/components/schemas/PickingListBasketHistoryItem" }, "description": "Histórico cronológico (mais antigo → mais recente) das vinculações do cesto com pedidos durante a coleta. Vazio quando o cesto ainda não foi usado." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de criação do cesto." }, "PickingListRelated": { "type": "array", "nullable": true, "description": "Picking-lists relacionadas (pai/filhas da colméia). Presente apenas no primeiro item da resposta e somente quando a busca é por `ExternalId` ou `IDPickingListBasket` e o cesto tem picking-list vinculada; `[]` quando não há relacionadas.", "items": { "type": "object", "properties": { "IDPickingList": { "type": "integer" }, "IDPickingListStatus": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ] }, "RecordUserCreatedStartPicking": { "type": "integer", "nullable": true }, "IDTypePickingList": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "IDPickingListFather": { "type": "integer", "nullable": true }, "Checked": { "type": "integer", "enum": [ 0, 1 ], "nullable": true }, "IDPickingListBasket": { "type": "integer", "nullable": true }, "ExternalId": { "type": "string", "nullable": true }, "UserName": { "type": "string", "nullable": true }, "TypePickingList": { "type": "string" } } } }, "PickingListFather": { "type": "object", "nullable": true, "description": "Dados da picking-list pai (colméia). Presente apenas no primeiro item da resposta quando há picking-lists relacionadas.", "properties": { "RecordUserCreated": { "type": "integer" }, "RecordUserCreatedStartPicking": { "type": "integer", "nullable": true }, "RecordTimestampStartPicking": { "type": "string", "format": "date-time", "nullable": true }, "RecordTimestampFinishedPicking": { "type": "string", "format": "date-time", "nullable": true }, "IDPickingList": { "type": "integer" }, "IDPickingListStatus": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ] }, "PickingListPriority": { "type": "integer", "description": "Prioridade da picking-list (0 a 10)." }, "StatusPickingList": { "type": "string" }, "RecordTimestampEnd": { "type": "string", "format": "date-time", "nullable": true }, "RecordTimestamp": { "type": "string", "format": "date-time" }, "RecordUserCreatedStartPacking": { "type": "integer", "nullable": true }, "RecordTimestampStartPacking": { "type": "string", "format": "date-time", "nullable": true }, "IDTypePickingList": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "TypePickingList": { "type": "string" }, "QtyOrder": { "type": "integer" }, "QtyOrderDone": { "type": "integer" }, "ItemsQuantity": { "type": "number" }, "SkuQuantity": { "type": "integer" } } } } }, "PickingListBasketCreate": { "type": "object", "description": "Atualização parcial do cesto de picking. Nenhum campo é obrigatório; apenas os campos enviados são atualizados.", "properties": { "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Identificador do CD onde o cesto opera." }, "ExternalId": { "type": "string", "nullable": true, "description": "Código externo (etiqueta/barcode) do cesto. Único por CD — reenviar um código já usado por outro cesto do mesmo CD é rejeitado." }, "BasketHeight": { "type": "number", "nullable": true, "description": "Altura do cesto em centímetros." }, "BasketWidth": { "type": "number", "nullable": true, "description": "Largura do cesto em centímetros." }, "BasketLength": { "type": "number", "nullable": true, "description": "Comprimento do cesto em centímetros." }, "BasketMaxWeight": { "type": "number", "nullable": true, "description": "Peso máximo suportado em quilos." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido a vincular ao cesto. Enviar null desvincula o pedido atualmente amarrado. Mutuamente exclusivo com IDPickingList e não aceito quando o cesto já tem picking-list vinculada." }, "IDPickingList": { "type": "integer", "nullable": true, "description": "Picking-list a vincular ao cesto (fluxo colméia). Validada contra as picking-lists da empresa. Mutuamente exclusiva com IDOrder e não aceita quando o cesto já tem pedido vinculado." } } }, "SkuBatchItem": { "type": "object", "description": "Lote (`StockKeepingUnitBatch`) com endereço, saldo e dados do SKU resolvidos.", "properties": { "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDBatchNumber": { "type": "integer", "description": "Identificador único do lote." }, "IDSku": { "type": "integer", "description": "Identificador do SKU dono do lote." }, "IDSkuCompany": { "type": "string", "description": "Código de referência do SKU." }, "SkuName": { "type": "string", "description": "Nome do SKU." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal do SKU." }, "Batch": { "type": "integer", "enum": [ 0, 1 ], "description": "Vem do cadastro do SKU. `1` = SKU controla múltiplos lotes no mesmo endereço (rastreabilidade); `0` = unicidade SKU × endereço." }, "IDStockKeepingUnitLocation": { "type": "integer", "description": "Endereço (posição física) onde o lote está alocado." }, "Address": { "type": "string", "description": "Nome do endereço." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Depósito onde o lote está." }, "WarehouseName": { "type": "string", "description": "Nome do depósito." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Centro de distribuição do depósito." }, "DistributionCenterName": { "type": "string", "description": "Nome do centro de distribuição." }, "IDStockKeepingUnitLocationCategory": { "type": "integer", "nullable": true, "description": "Categoria do endereço." }, "StockKeepingUnitLocationCategoryName": { "type": "string", "nullable": true, "description": "Nome da categoria do endereço." }, "IDStockKeepingUnitLocationGroup": { "type": "integer", "nullable": true, "description": "Grupo de endereços do lote." }, "StockKeepingUnitLocationGroupName": { "type": "string", "nullable": true, "description": "Nome do grupo de endereços." }, "IDTypeAddress": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3 ], "description": "Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado." }, "TypeAddress": { "type": "string", "nullable": true, "description": "Descrição textual do tipo de endereço." }, "BestBeforeDate": { "type": "string", "format": "date", "description": "Validade. Default `4000-01-01` quando o produto não tem validade." }, "ManufacturingDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de fabricação (rastreabilidade)." }, "Comments": { "type": "string", "nullable": true, "description": "Descrição/identificador do lote (texto livre, ex.: `LOTE-2024-A1`)." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "Lote padrão do SKU (apenas 1 por SKU)." }, "IDTypeSku": { "type": "integer", "description": "Tipo do SKU (vide enum em `IDTypeSku`)." }, "AbcCurve": { "type": "string", "nullable": true, "description": "Curva ABC do SKU (A, B ou C)." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do SKU." }, "MainImageThumbnailURL": { "type": "string", "nullable": true, "description": "URL da miniatura." }, "BatchBalance": { "type": "number", "description": "Saldo do lote — soma de entradas (`IDTypeMovement=0` e `IDStatusSku=1`) menos saídas (`IDTypeMovement=1`), com `BalanceChange = 1`." }, "QtyHandling": { "type": "number", "description": "Quantidade em movimentação (saídas reservadas em `IDStatusSku=0`)." }, "QtyAvailable": { "type": "number", "description": "Saldo disponível do SKU no armazém (`QtyAvailable`)." }, "IDBatchStatus": { "type": "integer", "enum": [ 0, 1 ], "description": "Derivado: `1`=Ativo (saldo > 0), `0`=Inativo (saldo = 0)." }, "BatchStatus": { "type": "string", "enum": [ "Ativo", "Inativo" ], "description": "Situação do lote: `Ativo` quando ainda tem saldo disponível; `Inativo` quando zerado." }, "BatchDAgeInDays": { "type": "integer", "description": "Idade do lote em dias (hoje − RecordTimestamp)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do lote." }, "PriceSell": { "type": "number", "nullable": true, "description": "Preço de venda do SKU. Quando há promoção ativa e `IDCompanySalesPolicy` foi informado, já vem com o desconto aplicado. `null` quando o SKU não tem preço vigente." }, "PriceList": { "type": "number", "nullable": true, "description": "Preço de tabela (lista) do SKU. `null` quando não há preço vigente." }, "PercentualDiscountValue": { "type": "number", "nullable": true, "description": "Desconto percentual da promoção ativa do SKU, expresso como fração (ex.: `0.1` = 10%). Presente apenas quando `IDCompanySalesPolicy` é informado." } } }, "SkuBatchCreate": { "type": "object", "description": "Corpo do `POST /sku/batch/{idsku}`.", "required": [ "IDStockKeepingUnitLocation" ], "properties": { "IDStockKeepingUnitLocation": { "type": "integer", "description": "Endereço onde o lote será criado." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Validade. Obrigatório quando o SKU tem `BestBeforeRequired = 1`." }, "Comments": { "type": "string", "nullable": true, "description": "Descrição do lote. Obrigatória quando o SKU tem `BatchRequired = 1`." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "Marca como lote padrão (zera os demais do SKU)." } } }, "SkuBatchUpdate": { "type": "object", "description": "Corpo do PUT — atualização parcial.", "properties": { "IDBatch": { "type": "integer", "description": "Usado quando o id do lote vem no body em vez de path." }, "IDStockKeepingUnitLocation": { "type": "integer", "description": "Para transferir o lote para outro endereço. Não pode ser `null` (use DELETE para remover). Precisa ser do mesmo armazém do endereço atual." }, "BestBeforeDate": { "type": "string", "format": "date", "description": "Data de validade do lote." }, "ManufacturingDate": { "type": "string", "format": "date", "description": "Data de fabricação do lote." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres do lote." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` define este lote como o padrão de saída do SKU (consumido primeiro nas vendas); `0` lote alternativo." } } }, "TypeResupplyEnum": { "type": "integer", "description": "Tipo de ressuprimento: `1` Picking (reposição da picking), `2` Pulmão (movimentação para pulmão), `3` Recebimento (item recebido sendo endereçado).", "enum": [ 1, 2, 3 ] }, "TypeResupplyModeEnum": { "type": "integer", "description": "Modalidade de operação: `1` Individual (1 ressuprimento = 1 pedido), `2` Agrupado (vários pedidos agrupados), `3` Indireto (estoque interno sem amarração a pedido).", "enum": [ 1, 2, 3 ] }, "StatusResupplyEnum": { "type": "integer", "description": "Status: `1` Aberto, `2` Iniciado, `3` Finalizado, `4` Cancelado.", "enum": [ 1, 2, 3, 4 ] }, "ResupplyItem": { "type": "object", "description": "Ressuprimento (`StockKeepingUnitResupplyList`).", "properties": { "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDStockKeepingUnitResupplyList": { "type": "integer", "description": "Identificador do ressuprimento." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Centro de distribuição em que o ressuprimento ocorre." }, "DistributionCenterName": { "type": "string", "description": "Nome do centro de distribuição." }, "IDTypeResupply": { "$ref": "#/components/schemas/TypeResupplyEnum", "description": "Tipo: `1` Picking, `2` Pulmão, `3` Recebimento." }, "TypeResupply": { "type": "string", "description": "Picking / Pulmão / Recebimento." }, "IDTypeResupplyMode": { "$ref": "#/components/schemas/TypeResupplyModeEnum", "description": "Modo: `1` Individual, `2` Agrupado, `3` Indireto." }, "TypeResupplyMode": { "type": "string", "description": "Individual / Agrupado / Indireto." }, "IDResupplyStatus": { "$ref": "#/components/schemas/StatusResupplyEnum", "description": "Status: `1` Aberto, `2` Iniciado, `3` Finalizado, `4` Cancelado." }, "StatusResupply": { "type": "string", "description": "Descrição textual do status." }, "StockKeepingUnitResupplyListPriority": { "type": "integer", "minimum": 0, "maximum": 10, "nullable": true, "description": "0 (mais alta) a 10 (mais baixa). Quando o parâmetro `UseShippingHandlingTimeInResupplyPriority` está ativo, o sistema reduz a prioridade conforme a data de expedição se aproxima." }, "QtyOrder": { "type": "integer", "nullable": true, "description": "Pedidos vinculados (modalidade Individual/Agrupado)." }, "QtyResupply": { "type": "integer", "nullable": true, "description": "Itens pendentes de transferência. Quando `> 0`, a exclusão é bloqueada." }, "QtyResupplyItems": { "type": "integer", "nullable": true, "description": "Total de unidades pendentes." }, "RecordUserStart": { "type": "integer", "nullable": true, "description": "Colaborador atribuído (vira o campo `UserStartLogin` resolvido)." }, "UserStartLogin": { "type": "string", "nullable": true, "description": "Login do usuário que iniciou o ressuprimento." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Criação." }, "RecordTimestampStart": { "type": "string", "format": "date-time", "nullable": true, "description": "Início da separação (status passou a Iniciado)." }, "RecordTimestampFinished": { "type": "string", "format": "date-time", "nullable": true, "description": "Conclusão." } } }, "ResupplyCreate": { "type": "object", "description": "Corpo do POST. Manual ou por pedido.", "properties": { "IDTypeResupply": { "$ref": "#/components/schemas/TypeResupplyEnum", "description": "Tipo do ressuprimento: `1` Picking (do pulmão para o endereço de picking), `2` Pulmão (chegada nova ao pulmão), `3` Recebimento (do recebimento para o estoque)." }, "IDTypeResupplyMode": { "$ref": "#/components/schemas/TypeResupplyModeEnum", "description": "Modo de execução: `1` Individual, `2` Agrupado, `3` Indireto. Padrão `1`." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "nullable": true, "description": "Vazio = usa CD padrão da empresa." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres do ressuprimento." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Modo automático por pedido: aciona o processo e gera as listas necessárias com base no saldo do pedido." } } }, "ResupplyUpdate": { "type": "object", "description": "Corpo do PUT. Atualização parcial.", "properties": { "IDResupplyStatus": { "$ref": "#/components/schemas/StatusResupplyEnum", "description": "Status do ressuprimento: `1` Aberto, `2` Iniciado, `3` Finalizado, `4` Cancelado." }, "IDTypeResupply": { "$ref": "#/components/schemas/TypeResupplyEnum", "description": "Tipo do ressuprimento: `1` Picking, `2` Pulmão, `3` Recebimento." }, "IDTypeResupplyMode": { "$ref": "#/components/schemas/TypeResupplyModeEnum", "description": "Modo: `1` Individual, `2` Agrupado, `3` Indireto." }, "StockKeepingUnitResupplyListPriority": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Prioridade na fila de ressuprimento — menor valor é executado primeiro." }, "RecordUserStart": { "type": "integer", "nullable": true, "description": "Atribuir colaborador. Envie `null` para desatribuir." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres." } } }, "PurchaseScheduleStatusEnum": { "type": "integer", "description": "Status calculado pelo sistema (não persistido): `1` Recebido (check-in feito), `2` Agendado (futuro, sem check-in), `3` Atrasado (passou e sem check-in), `4` Não agendado (sem recebimento amarrado).", "enum": [ 1, 2, 3, 4 ] }, "PurchaseScheduleItem": { "type": "object", "description": "Agendamento de recebimento (`StockKeepingUnitPurchaseSchedule`) com dados do recebimento, fornecedor e NF resolvidos.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do agendamento." }, "IDStockKeepingUnitPurchaseSchedule": { "type": "integer", "description": "Identificador do agendamento." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa dona do agendamento." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Quando o agendamento foi criado." }, "StartTime": { "type": "string", "format": "date-time", "description": "Início do agendamento." }, "EndTime": { "type": "string", "format": "date-time", "description": "Fim do agendamento." }, "ScheduleTitle": { "type": "string", "nullable": true, "description": "Título amigável (livre)." }, "Comments": { "type": "string", "nullable": true, "description": "Observações." }, "IDPurchase": { "type": "integer", "nullable": true, "description": "Recebimento amarrado. Vazio = agendamento avulso." }, "IDSupplier": { "type": "integer", "nullable": true, "description": "Fornecedor resolvido a partir do recebimento amarrado. Vazio quando o agendamento é avulso." }, "SupplierCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ do fornecedor (apenas dígitos). Vazio em agendamento avulso." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Nome ou razão social do fornecedor. Vazio em agendamento avulso." }, "serie": { "type": "string", "nullable": true, "description": "Série da NF." }, "nNF": { "type": "string", "nullable": true, "description": "Número da NF." }, "dhEmi": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora de emissão da NF." }, "qVol": { "type": "number", "nullable": true, "description": "Quantidade de volumes da NF." }, "Weight": { "type": "number", "nullable": true, "description": "Peso bruto da NF (`pesoB` no XML)." }, "ItemsQuantity": { "type": "number", "nullable": true, "description": "Soma das quantidades dos itens do recebimento." }, "SkuQuantity": { "type": "integer", "nullable": true, "description": "Número de SKUs distintos no recebimento." }, "CheckinTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando o recebimento foi conferido fisicamente (check-in na portaria)." }, "IDStatusPurchase": { "type": "integer", "nullable": true, "description": "Status do recebimento (`IDStatusPurchase`)." }, "StatusPurchase": { "type": "string", "nullable": true, "description": "Nome amigável do status." }, "StockKeepingUnitPurchaseScheduleStatus": { "$ref": "#/components/schemas/PurchaseScheduleStatusEnum", "description": "Status do agendamento calculado pelo sistema (não persistido): `1` Recebido, `2` Agendado, `3` Atrasado, `4` Não agendado." }, "StockKeepingUnitPurchaseScheduleStatusDescription": { "type": "string", "enum": [ "Recebido", "Agendado", "Atrasado", "Não agendado" ], "description": "Descrição amigável do status do agendamento: `Recebido` (check-in feito), `Agendado` (futuro, ainda sem check-in), `Atrasado` (passou do `EndTime` sem check-in), `Não agendado` (sem recebimento amarrado)." } } }, "PurchaseScheduleCreate": { "type": "object", "description": "Corpo do POST/PUT de Agendamento.", "required": [ "StartTime", "EndTime" ], "properties": { "StartTime": { "type": "string", "format": "date-time", "description": "Início. Precisa ser ≤ EndTime." }, "EndTime": { "type": "string", "format": "date-time", "description": "Fim." }, "ScheduleTitle": { "type": "string", "nullable": true, "description": "Título amigável (livre, máx. 100)." }, "Comments": { "type": "string", "nullable": true, "description": "Observações (livre, máx. 500)." }, "IDPurchase": { "type": "integer", "nullable": true, "description": "Recebimento a amarrar. Vazio = agendamento avulso. Não pode estar já agendado." } } }, "PurchaseScheduleConfigTimetable": { "type": "object", "description": "Faixa de horário disponível em um dia da semana.", "required": [ "WeekDay", "StartTime", "EndTime" ], "properties": { "WeekDay": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Dia da semana: 0=Domingo, 1=Segunda, 2=Terça, 3=Quarta, 4=Quinta, 5=Sexta, 6=Sábado." }, "StartTime": { "type": "string", "description": "Horário de início (`HH:MM:SS`)." }, "EndTime": { "type": "string", "description": "Horário de término (`HH:MM:SS`). Precisa ser maior que `StartTime`." } } }, "PurchaseScheduleConfigItem": { "type": "object", "description": "Configuração de agendamento como devolvida por `GET /purchase/schedule/config`.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio da empresa dona da configuração." }, "IDStockKeepingUnitPurchaseScheduleConfig": { "type": "integer", "description": "Identificador da configuração." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa dona da configuração." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Quando a configuração foi criada." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Centro de distribuição ao qual a configuração se aplica. Cada CD aceita no máximo uma configuração." }, "DistributionCenterName": { "type": "string", "description": "Nome do centro de distribuição." }, "ScheduleDurationMinutes": { "type": "string", "description": "Duração de cada janela de agendamento (`HH:MM:SS`). Operações de pequeno volume costumam usar 30 min; grande volume usa 2h ou mais." }, "MaxItemsPerDay": { "type": "integer", "nullable": true, "description": "Quantidade máxima de **itens** (unidades de produto) que o CD aceita receber em um único dia." }, "MaxSchedulePerDay": { "type": "integer", "nullable": true, "description": "Quantidade máxima de **agendamentos** (notas fiscais) que o CD aceita em um único dia." }, "ScheduleMaximumTimeAheadDay": { "type": "integer", "nullable": true, "description": "Quantos dias à frente o agendamento fica disponível. Ex.: `60` = a partir de hoje, pode marcar até daqui a 60 dias." }, "ScheduleMinimumAdvanceTimeHour": { "type": "integer", "nullable": true, "description": "Antecedência mínima em **horas** para marcar um agendamento. Ex.: `2` = agendamento só pode ser marcado para começar daqui a 2h ou mais." }, "HourDifferenceAllowed": { "type": "string", "nullable": true, "description": "Tempo de tolerância (`HH:MM:SS`) entre o horário do agendamento e a chegada/check-in. Ex.: `00:30:00` = o check-in pode acontecer até 30 min depois do horário marcado sem ser considerado atrasado." }, "StockKeepingUnitPurchaseScheduleConfigTimetable": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseScheduleConfigTimetable" }, "description": "Quadro de horários disponíveis por dia da semana, ordenado por `WeekDay` e `StartTime`." } } }, "PurchaseScheduleConfigCreate": { "type": "object", "description": "Corpo do `POST /purchase/schedule/config`. Cria uma configuração de agendamento para um CD.", "required": [ "IDStockKeepingUnitDistributionCenter", "ScheduleDurationMinutes" ], "properties": { "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "CD destino. Cada CD pode ter no máximo 1 configuração." }, "ScheduleDurationMinutes": { "type": "integer", "description": "Duração de cada janela em minutos (o frontend converte de \"2h\", \"30m\", \"1h30\" para minutos antes de enviar). O sistema grava no campo TIME." }, "MaxItemsPerDay": { "type": "integer", "nullable": true, "description": "Quantidade máxima de itens (unidades de produto) que o CD aceita receber em um único dia. Sem limite quando vazio." }, "MaxSchedulePerDay": { "type": "integer", "nullable": true, "description": "Quantidade máxima de agendamentos (notas fiscais) que o CD aceita em um único dia. Sem limite quando vazio." }, "ScheduleMaximumTimeAheadDay": { "type": "integer", "nullable": true, "description": "Janela em dias para frente em que o agendamento aceita marcações." }, "ScheduleMinimumAdvanceTimeHour": { "type": "integer", "nullable": true, "description": "Antecedência mínima em horas." }, "HourDifferenceAllowed": { "type": "integer", "nullable": true, "description": "Tolerância em minutos (frontend converte para `HH:MM:SS` no banco)." }, "StockKeepingUnitPurchaseScheduleConfigTimetable": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseScheduleConfigTimetable" }, "description": "Faixas de horário por dia da semana. Quando omitido, a configuração é criada sem horários (sem disponibilidade)." } } }, "PurchaseScheduleConfigUpdate": { "type": "object", "description": "Corpo do `PUT /purchase/schedule/config/{id}`. Atualização parcial. Para `StockKeepingUnitPurchaseScheduleConfigTimetable`: enviar `[]` apaga todas as faixas; array preenchido substitui em bloco.", "properties": { "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Centro de distribuição alvo. Não pode coincidir com outro CD que já tenha configuração." }, "ScheduleDurationMinutes": { "type": "integer", "description": "Duração de cada janela de agendamento em minutos. O frontend converte strings como `2h`, `30m`, `1h30` para minutos antes de enviar; o sistema grava em campo `TIME`." }, "MaxItemsPerDay": { "type": "integer", "nullable": true, "description": "Quantidade máxima de itens (unidades de produto) que o CD aceita receber em um único dia. Sem limite quando vazio." }, "MaxSchedulePerDay": { "type": "integer", "nullable": true, "description": "Quantidade máxima de agendamentos (notas fiscais) que o CD aceita em um único dia. Sem limite quando vazio." }, "ScheduleMaximumTimeAheadDay": { "type": "integer", "nullable": true, "description": "Janela de dias à frente em que o agendamento aceita marcações. Ex.: `60` = de hoje até daqui a 60 dias." }, "ScheduleMinimumAdvanceTimeHour": { "type": "integer", "nullable": true, "description": "Antecedência mínima em horas para marcar um agendamento. Ex.: `2` = só pode marcar para começar daqui a 2h ou mais." }, "HourDifferenceAllowed": { "type": "integer", "nullable": true, "description": "Tolerância entre o horário marcado e a chegada/check-in. O frontend envia em minutos; o sistema grava em `TIME` (`HH:MM:SS`)." }, "StockKeepingUnitPurchaseScheduleConfigTimetable": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseScheduleConfigTimetable" }, "description": "Quadro de horários disponíveis por dia da semana. **Não enviado** = mantém o quadro atual. **Array vazio** (`[]`) = apaga todas as faixas (agendamento fica indisponível). **Array preenchido** = substitui em bloco (DELETE + INSERT)." } } }, "TypePickingListEnum": { "type": "integer", "description": "Tipo de picking list:\n- `1` — Picking: somente separação; o faturamento acontece depois.\n- `2` — Picking & Packing: separação + emissão da nota no mesmo passo (impressora sem fio).\n- `3` — Monopedido: cada picking list contém **um único pedido**.\n- `4` — Colméia: tipo cadastrado na tabela mas hoje não exposto no formulário da tela.", "enum": [ 1, 2, 3, 4 ] }, "PickingListConfigurationItem": { "type": "object", "description": "Configuração de picking list como devolvida por `GET /fulfillment/picking/configuration`. Campos CSV (`IDCompanyIntegrationList`, `IDOrderTypeList`, `IDCarrierList`, `WeekIntervalAutoGenerate`) vêm já em formato `array`.", "properties": { "AccountName": { "type": "string", "description": "Identificador da empresa dona da configuração." }, "IDPickingListConfiguration": { "type": "integer", "description": "Identificador da configuração." }, "IDCompany": { "type": "integer", "description": "Identificador interno da empresa dona da configuração." }, "PickingListConfigurationName": { "type": "string", "maxLength": 500, "description": "Nome da configuração (único por empresa)." }, "PickingListConfigurationStatus": { "type": "integer", "enum": [ 0, 1 ], "description": "`1`=Ativa (entra na geração automática), `0`=Inativa." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Identificador do CD a que a configuração se aplica." }, "DistributionCenterName": { "type": "string", "description": "Nome amigável do CD." }, "IDTypePickingList": { "$ref": "#/components/schemas/TypePickingListEnum", "description": "Tipo de picking-list: `1` Picking, `2` Picking & Packing, `3` Monopedido, `4` Colméia." }, "TypePickingList": { "type": "string", "description": "Nome amigável do tipo." }, "PickingPriority": { "type": "integer", "minimum": 0, "maximum": 10, "nullable": true, "description": "Prioridade desta configuração (0=mais alta, 10=mais baixa). Quando há mais de uma configuração competindo, executa primeiro a de menor prioridade." }, "OrderPriority": { "type": "integer", "minimum": 0, "maximum": 10, "nullable": true, "description": "Filtra `OrderPriority` para essa configuração (0=mais alta, 10=mais baixa)." }, "OrderCreateTimeLimit": { "type": "string", "nullable": true, "description": "Horário-limite de criação do pedido (`HH:MM:SS`). Apenas pedidos criados até esse horário no dia entram automaticamente." }, "IDCompanyIntegrationList": { "type": "array", "items": { "type": "string" }, "description": "Lista de integrações que a configuração processa. Vazio = todas." }, "IDOrderTypeList": { "type": "array", "items": { "type": "string" }, "description": "Lista de tipos de pedido. Vazio = todos." }, "IDCarrierList": { "type": "array", "items": { "type": "string" }, "description": "Lista de transportadoras. Vazio = todas." }, "ItemsQtyLimit": { "type": "integer", "nullable": true, "description": "Limite de unidades (somando todos os SKUs) por picking list gerada." }, "OrderQtyLimit": { "type": "integer", "nullable": true, "description": "Limite de pedidos por picking list gerada." }, "SkuQtyLimit": { "type": "integer", "nullable": true, "description": "Limite de SKUs diferentes por picking list gerada." }, "PickingListBasketLimit": { "type": "integer", "nullable": true, "description": "Limite de cestos por picking list (usado em operações com cesto picking — ver Cesto Picking)." }, "StartAutoGenerateTime": { "type": "string", "description": "Horário de início da janela diária (`HH:MM:SS`)." }, "FinishAutoGenerateTime": { "type": "string", "description": "Horário de fim da janela diária (`HH:MM:SS`). Precisa ser ≥ `StartAutoGenerateTime`." }, "IntervalAutoGenerateTime": { "type": "string", "nullable": true, "description": "Intervalo entre execuções (`HH:MM:SS`). Ex.: `02:00:00` = roda de 2 em 2 horas dentro da janela." }, "WeekIntervalAutoGenerate": { "type": "array", "items": { "type": "string" }, "description": "Dias da semana em que roda (0=Domingo … 6=Sábado)." }, "AutoGenerateLastTime": { "type": "string", "format": "date-time", "nullable": true, "description": "Última vez que o sistema executou essa configuração." }, "AutoGenerateNextTime": { "type": "string", "format": "date-time", "nullable": true, "description": "Próxima execução agendada." }, "UniqueSku": { "type": "integer", "enum": [ 0, 1 ], "description": "Flag interna — quando `1`, lista é exclusiva de pedidos com 1 SKU único." }, "PreferLocationMoreQuantity": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, na escolha de endereço de coleta o sistema prioriza o endereço com **maior saldo** para o SKU (esvaziando endereços antes); `0` mantém a regra padrão (endereço fixo / primeiro com saldo)." }, "IgnorePickingPreferenceByAllowResupplyLocation": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Quando `1`, ignora a regra global `PickingPreferenceByAllowResupplyLocation` ao montar a coleta — endereços de ressuprimento podem ser usados como origem mesmo sem pacote completo. `null` herda o comportamento padrão da empresa." } } }, "PickingListConfigurationCreate": { "type": "object", "description": "Corpo do `POST /fulfillment/picking/configuration`. Listas (`IDCompanyIntegrationList`, `IDOrderTypeList`, `IDCarrierList`, `WeekIntervalAutoGenerate`) podem ser arrays ou strings CSV.", "required": [ "PickingListConfigurationName", "IDStockKeepingUnitDistributionCenter", "StartAutoGenerateTime", "FinishAutoGenerateTime" ], "properties": { "PickingListConfigurationName": { "type": "string", "maxLength": 500, "description": "Nome único por empresa." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Identificador do CD a que a configuração se aplica. Precisa pertencer à empresa." }, "IDTypePickingList": { "$ref": "#/components/schemas/TypePickingListEnum", "description": "Tipo de picking-list: `1` Picking, `2` Picking & Packing, `3` Monopedido, `4` Colméia." }, "PickingListConfigurationStatus": { "type": "integer", "enum": [ 0, 1 ], "description": "Default `1` (Ativa)." }, "PickingPriority": { "type": "integer", "minimum": 0, "maximum": 10, "nullable": true, "description": "Prioridade da configuração na resolução automática (0=mais alta, 10=mais baixa). Quando dois pedidos casam em mais de uma configuração, vence a que tem menor `PickingPriority`." }, "OrderPriority": { "type": "integer", "minimum": 0, "maximum": 10, "nullable": true, "description": "Prioridade gravada nas picking-lists geradas (0=mais alta, 10=mais baixa). É a prioridade que aparece para o separador na fila de coleta." }, "OrderCreateTimeLimit": { "type": "string", "nullable": true, "description": "`HH:MM:SS` — pedidos criados até este horário no dia entram automaticamente." }, "IDCompanyIntegrationList": { "oneOf": [ { "type": "array", "items": { "type": "integer" } }, { "type": "string" } ], "description": "Lista de integrações (canais de venda) atendidas por esta configuração. Vazio = todas as integrações da empresa. Aceita array de inteiros ou string CSV." }, "IDTypeOrderList": { "oneOf": [ { "type": "array", "items": { "type": "integer" } }, { "type": "string" } ], "description": "Lista de tipos de pedido atendidos por esta configuração. Vazio = todos os tipos. Aceita array de inteiros ou string CSV." }, "IDCarrierList": { "oneOf": [ { "type": "array", "items": { "type": "integer" } }, { "type": "string" } ], "description": "Lista de transportadoras atendidas por esta configuração. Vazio = todas. Aceita array de inteiros ou string CSV. Cada item precisa ser um fornecedor da empresa do tipo Transportadora." }, "ItemsQtyLimit": { "type": "integer", "nullable": true, "description": "Quantidade máxima de itens (somatório de unidades) por picking-list gerada. Quando atingido, o sistema fecha a lista e abre uma nova. `null` = sem limite." }, "OrderQtyLimit": { "type": "integer", "nullable": true, "description": "Quantidade máxima de pedidos por picking-list gerada. Pode ser sobrescrito pelo query param `OrderQtyLimit` no `POST /fulfillment/picking`. `null` = sem limite." }, "SkuQtyLimit": { "type": "integer", "nullable": true, "description": "Quantidade máxima de SKUs distintos por picking-list gerada. `null` = sem limite." }, "PickingListBasketLimit": { "type": "integer", "nullable": true, "description": "Quantidade máxima de cestos disponíveis para esta configuração — usado para dimensionar quantos pedidos cabem em paralelo na esteira. `null` = sem limite." }, "StartAutoGenerateTime": { "type": "string", "description": "Horário de início da janela diária (`HH:MM:SS`)." }, "FinishAutoGenerateTime": { "type": "string", "description": "Horário de fim da janela diária. Precisa ser ≥ `StartAutoGenerateTime`." }, "IntervalAutoGenerateTime": { "type": "string", "nullable": true, "description": "Intervalo entre execuções da geração automática dentro da janela (`HH:MM:SS`). Ex.: `00:30:00` roda a cada 30 minutos. `null` = roda uma vez no início da janela." }, "WeekIntervalAutoGenerate": { "oneOf": [ { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, { "type": "string" } ], "description": "Dias da semana (0=Domingo … 6=Sábado). Vazio = todos os dias." } } }, "PickingListConfigurationUpdate": { "allOf": [ { "$ref": "#/components/schemas/PickingListConfigurationCreate" } ], "description": "Mesmo schema do create, mas todos os campos são opcionais — atualização parcial." }, "SkuLocationListItem": { "type": "object", "description": "Endereço como devolvido pelo `GET /sku/location?OnlyLocation=1`.", "properties": { "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDStockKeepingUnitLocation": { "type": "integer", "description": "Identificador do endereço." }, "Address": { "type": "string", "description": "Nome do endereço (no modo WMS é a concatenação `Andar-Rua-Módulo-Coluna-Nível`)." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "`1`=Ativo, `0`=Inativo." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Depósito onde fica o endereço." }, "WarehouseName": { "type": "string", "description": "Nome do depósito." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "nullable": true, "description": "Centro de distribuição." }, "DistributionCenterName": { "type": "string", "nullable": true, "description": "Nome do centro de distribuição." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando é o endereço padrão do armazém (apenas um por armazém)." }, "AddressPriority": { "type": "integer", "description": "Prioridade de ordenação na picking-list. Menor = maior prioridade." }, "Floor": { "type": "string", "nullable": true, "description": "Andar (WMS)." }, "Street": { "type": "string", "nullable": true, "description": "Rua/Corredor (WMS)." }, "Module": { "type": "string", "nullable": true, "description": "Módulo / Bloco (WMS). Numérico." }, "Column": { "type": "string", "nullable": true, "description": "Coluna (WMS). Alfanumérico — letras viram maiúsculas." }, "Level": { "type": "string", "nullable": true, "description": "Nível / Andar da prateleira (WMS). Numérico." }, "Height": { "type": "number", "format": "double", "nullable": true, "description": "Altura em cm (WMS)." }, "Width": { "type": "number", "format": "double", "nullable": true, "description": "Largura em cm (WMS)." }, "Length": { "type": "number", "format": "double", "nullable": true, "description": "Comprimento em cm (WMS)." }, "MaxWeight": { "type": "number", "format": "double", "nullable": true, "description": "Peso máximo suportado em kg (WMS)." }, "IDTypeAddress": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3 ], "description": "Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado." }, "TypeAddress": { "type": "string", "nullable": true, "description": "Nome do tipo (`Picking`, `Pulmão`, `Blocado`)." }, "IDStockKeepingUnitLocationCategory": { "type": "integer", "nullable": true, "description": "Categoria do endereço." }, "StockKeepingUnitLocationCategoryName": { "type": "string", "nullable": true, "description": "Nome da categoria." }, "IDStockKeepingUnitLocationGroup": { "type": "integer", "nullable": true, "description": "Grupo de endereços." }, "StockKeepingUnitLocationGroupName": { "type": "string", "nullable": true, "description": "Nome do grupo de endereços." }, "LocationSide": { "type": "integer", "nullable": true, "enum": [ 1, 2 ], "description": "`1`=Direito, `2`=Esquerdo." }, "AllowRessuply": { "type": "integer", "enum": [ 0, 1 ], "description": "`1`=Permite que tarefa de ressuprimento direcione SKU para este endereço." }, "StockKeepingUnitLocationIndex": { "type": "integer", "description": "Número sequencial gerado pela query." } } }, "SkuLocationBatchItem": { "type": "object", "description": "Endereço × lote como devolvido pelo `GET /sku/location` (sem `OnlyLocation`). Uma linha por lote vinculado ao endereço.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio (conta) da empresa dona do endereço." }, "IDStockKeepingUnitLocation": { "type": "integer", "description": "Identificador do endereço de armazenagem." }, "Address": { "type": "string", "description": "Texto do endereço de armazenagem (`Floor-Street-Module-Column-Level` ou nome livre)." }, "AddressSku": { "type": "string", "description": "Quando há lote: `Endereço | Código SKU | IDSku | Nome do produto`; quando não, é só `Address`." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém ao qual o endereço pertence." }, "WarehouseName": { "type": "string", "description": "Nome do armazém." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando o endereço é o padrão do armazém (usado como destino quando nenhum endereço específico é informado); `0` caso contrário." }, "AddressPriority": { "type": "integer", "description": "Prioridade do endereço na sugestão de separação/armazenagem (menor número = maior prioridade)." }, "IDBatchNumber": { "type": "integer", "nullable": true, "description": "Lote do SKU armazenado neste endereço. Vazio quando o endereço não tem saldo deste SKU em lote." }, "IDSku": { "type": "integer", "nullable": true, "description": "SKU armazenado no endereço (quando consultado por SKU). Vazio quando o endereço está vago." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência do SKU." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome do SKU armazenado." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal do SKU armazenado." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de validade do lote armazenado, no formato `YYYY-MM-DD`. Vazio quando o SKU não usa controle de validade." }, "QtyAddress": { "type": "number", "description": "Saldo do lote no endereço, calculado por soma de `StockKeepingUnitMovement` (`IDTypeMovement=0` entradas, `IDTypeMovement=1` saídas)." }, "Floor": { "type": "string", "nullable": true, "description": "Componente `Andar` do endereço estruturado." }, "Street": { "type": "string", "nullable": true, "description": "Componente `Rua` do endereço estruturado." }, "Module": { "type": "string", "nullable": true, "description": "Componente `Módulo` do endereço estruturado." }, "Column": { "type": "string", "nullable": true, "description": "Componente `Coluna` do endereço estruturado." }, "Level": { "type": "string", "nullable": true, "description": "Componente `Nível` do endereço estruturado." }, "Height": { "type": "number", "nullable": true, "description": "Altura útil do endereço em cm." }, "Width": { "type": "number", "nullable": true, "description": "Largura útil do endereço em cm." }, "Length": { "type": "number", "nullable": true, "description": "Profundidade útil do endereço em cm." }, "MaxWeight": { "type": "number", "nullable": true, "description": "Peso máximo suportado pelo endereço em kg." }, "IDTypeAddress": { "type": "integer", "nullable": true, "description": "Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado.", "enum": [ 1, 2, 3 ] }, "TypeAddress": { "type": "string", "nullable": true, "description": "Descrição amigável do tipo do endereço." }, "IDStockKeepingUnitLocationCategory": { "type": "integer", "nullable": true, "description": "Categoria do endereço (agrupamento configurável — ex.: refrigerados, perigosos, frágeis)." }, "StockKeepingUnitLocationCategoryName": { "type": "string", "nullable": true, "description": "Nome da categoria do endereço." } } }, "SkuLocationCreate": { "type": "object", "description": "Corpo do `POST /sku/location`. Os campos relevantes dependem do parâmetro `NewAddressParameter` (modo WMS ou legado).", "properties": { "Address": { "type": "string", "description": "**Modo legado**: obrigatório. Modo WMS: ignorado — o sistema monta a partir de Andar/Rua/Módulo/Coluna/Nível." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém destino. Obrigatório no modo WMS; opcional no legado." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "Modo legado: marca como endereço padrão (zera os demais do armazém). Default 0." }, "AddressPriority": { "type": "integer", "description": "Prioridade para ordenação na picking-list (menor = primeiro)." }, "Floor": { "type": "string", "description": "Modo WMS — Andar. Obrigatório no cadastro individual." }, "Street": { "type": "string", "description": "Modo WMS — Rua/Corredor. Obrigatório no cadastro individual." }, "Module": { "type": "string", "description": "Modo WMS individual — Módulo (numérico)." }, "Column": { "type": "string", "description": "Modo WMS individual — Coluna (alfanumérico)." }, "Level": { "type": "string", "description": "Modo WMS individual — Nível (numérico)." }, "Height": { "type": "number", "description": "Altura em cm — obrigatório no WMS, deve ser `> 0`." }, "Width": { "type": "number", "description": "Largura em cm — obrigatório no WMS, deve ser `> 0`." }, "Length": { "type": "number", "description": "Comprimento em cm — obrigatório no WMS, deve ser `> 0`." }, "MaxWeight": { "type": "number", "description": "Peso máximo em kg — obrigatório no WMS, deve ser `> 0`." }, "IDTypeAddress": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado." }, "IDStockKeepingUnitLocationCategory": { "type": "integer", "description": "Obrigatório no WMS. Categoria de endereço (precisa estar ativa)." }, "IDStockKeepingUnitLocationGroup": { "type": "integer", "nullable": true, "description": "Grupo de endereços ao qual a posição física pertence (agrupa endereços com características comuns, como mesma rua)." }, "LocationSide": { "type": "integer", "enum": [ 1, 2 ], "description": "Lado da rua: `1`=Direito, `2`=Esquerdo (WMS)." }, "AllowRessuply": { "type": "integer", "enum": [ 0, 1 ], "description": "Default `1`." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "Default `1`." }, "BulkLocation": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` ativa o cadastro em massa por faixas (WMS). Default `0`." }, "StartModule": { "type": "string", "description": "Cadastro em massa — primeiro módulo (numérico)." }, "EndModule": { "type": "string", "description": "Cadastro em massa — último módulo (numérico). Precisa ser ≥ `StartModule`." }, "StartColumn": { "type": "string", "description": "Cadastro em massa — primeira coluna. Aceita letras (A-Z) ou números; quando letras, `EndColumn` precisa estar no mesmo intervalo do alfabeto." }, "EndColumn": { "type": "string", "description": "Cadastro em massa — última coluna. Precisa ser ≥ `StartColumn`." }, "StartLevel": { "type": "string", "description": "Cadastro em massa — primeiro nível (numérico)." }, "EndLevel": { "type": "string", "description": "Cadastro em massa — último nível (numérico). Precisa ser ≥ `StartLevel`." }, "Concatenator": { "type": "string", "enum": [ "-", ".", "|" ], "description": "Caractere usado para juntar Andar/Rua/Módulo/Coluna/Nível no `Address`. Default `-`." } } }, "SkuLocationUpdate": { "type": "object", "description": "Corpo do `PUT /sku/location/{idstockkeepingunitlocation}`. Atualização parcial — só os campos enviados são alterados.", "properties": { "Address": { "type": "string", "description": "Identificação textual completa do endereço (gerada por concatenação de `Floor`, `Street`, `Module`, `Column`, `Level`)." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Mudança bloqueada quando o endereço tem movimento." }, "Default": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` define este endereço como padrão para o depósito." }, "AddressPriority": { "type": "integer", "description": "Prioridade do endereço na seleção automática durante o picking — menor valor é tentado primeiro." }, "Floor": { "type": "string", "description": "Andar/piso do endereço." }, "Street": { "type": "string", "description": "Rua/corredor do endereço." }, "Module": { "type": "string", "description": "Módulo (estante) do endereço." }, "Column": { "type": "string", "description": "Coluna do endereço." }, "Level": { "type": "string", "description": "Nível (prateleira) do endereço." }, "Height": { "type": "number", "description": "Altura útil do endereço em cm." }, "Width": { "type": "number", "description": "Largura útil em cm." }, "Length": { "type": "number", "description": "Profundidade útil em cm." }, "MaxWeight": { "type": "number", "description": "Capacidade máxima de peso em kg." }, "IDTypeAddress": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado." }, "IDStockKeepingUnitLocationCategory": { "type": "integer", "description": "Categoria do endereço (agrupamento por tipo de SKU permitido)." }, "IDStockKeepingUnitLocationGroup": { "type": "integer", "nullable": true, "description": "Grupo de endereços ao qual a posição pertence." }, "LocationSide": { "type": "integer", "enum": [ 1, 2 ], "description": "Lado do corredor: `1` esquerda, `2` direita (usado para roteirizar o picking)." }, "AllowRessuply": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` permite que o endereço seja origem ou destino de ressuprimento; `0` bloqueia." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` endereço ativo; `0` desativado." } } }, "SkuLocationGroupListItem": { "type": "object", "description": "Grupo de endereços do estoque.", "properties": { "IDStockKeepingUnitLocationGroup": { "type": "integer", "description": "Identificador do grupo de endereços." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do grupo." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa." }, "StockKeepingUnitLocationGroupName": { "type": "string", "maxLength": 100, "description": "Nome do grupo de endereços." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." } } }, "SkuLocationGroupCreate": { "type": "object", "description": "Corpo do `POST /sku/location/group` e do `PUT`.", "required": [ "StockKeepingUnitLocationGroupName" ], "properties": { "StockKeepingUnitLocationGroupName": { "type": "string", "maxLength": 100, "description": "Nome do grupo. Único por empresa." } } }, "UserWorkShiftItem": { "type": "object", "description": "Turno cadastrado dentro da escala vinculada ao colaborador.", "properties": { "IDUserWorkShift": { "type": "integer", "description": "Identificador do turno de trabalho cadastrado para a empresa (referência usada na escala de jornada do colaborador)." }, "WeekDay": { "type": "integer", "description": "Dia da semana (0=Domingo ... 6=Sábado, conforme cadastro)." }, "StartTime": { "type": "string", "description": "Início do turno (`HH:MM:SS`)." }, "FinishTime": { "type": "string", "description": "Fim do turno." } } }, "UserJobPositionRef": { "type": "object", "properties": { "IDUserJobPosition": { "type": "integer", "description": "Identificador do cargo do usuário (referência ao cadastro de cargos da empresa)." }, "UserJobPositionName": { "type": "string", "description": "Nome do cargo (ex.: `Operador de logística`, `Conferente`, `Gerente`)." } } }, "SkuLocationCategoryRef": { "type": "object", "properties": { "IDStockKeepingUnitLocationCategory": { "type": "integer", "description": "Identificador da categoria de endereço de armazenagem." }, "StockKeepingUnitLocationCategoryName": { "type": "string", "description": "Nome da categoria de endereço." } } }, "SkuLocationGroupRef": { "type": "object", "properties": { "IDStockKeepingUnitLocationGroup": { "type": "integer", "description": "Identificador do grupo de endereços de armazenagem (agrupamento usado para escalas/restrições de operação)." }, "StockKeepingUnitLocationGroupName": { "type": "string", "description": "Nome do grupo de endereços." } } }, "UserWorkingDayListItem": { "type": "object", "description": "Item de `GET /user/workingday`.", "properties": { "AccountName": { "type": "string", "description": "Identificador (subdomínio) da empresa do colaborador." }, "IDUserWorkingDay": { "type": "integer", "description": "Identificador do cadastro de colaborador." }, "IDUser": { "type": "integer", "description": "Identificador do usuário associado." }, "UserName": { "type": "string", "description": "Nome do colaborador." }, "LastActivityTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Último login/atividade do usuário." }, "IDAcess": { "type": "integer", "description": "Vínculo do usuário com a empresa (`IDAcess`)." }, "Status": { "type": "integer", "enum": [ 1, 2 ], "description": "`1`=Ativo, `2`=Inativo." }, "IDUserWorkScale": { "type": "integer", "description": "Identificador da escala de trabalho vigente." }, "UserWorkScaleName": { "type": "string", "description": "Nome da escala." }, "WorkShift": { "type": "array", "items": { "$ref": "#/components/schemas/UserWorkShiftItem" }, "description": "Turnos da escala (mesmo shape de `UserWorkShiftItem`): dia da semana e janela de horário." }, "IDUserJobPositionList": { "type": "string", "nullable": true, "description": "CSV de `IDUserJobPosition`." }, "JobPositions": { "type": "array", "items": { "$ref": "#/components/schemas/UserJobPositionRef" }, "description": "Funções que o colaborador pode exercer (`UserJobPositionRef`)." }, "IDUserJobPositionCurrent": { "type": "integer", "nullable": true, "description": "Função ativa no momento." }, "CurrentPositionName": { "type": "string", "nullable": true, "description": "Nome da função ativa (resolvido pelo sistema)." }, "IDUserUpper": { "type": "integer", "nullable": true, "description": "Identificador do colaborador supervisor." }, "UserUpperName": { "type": "string", "nullable": true, "description": "Nome do supervisor." }, "Categories": { "type": "array", "items": { "$ref": "#/components/schemas/SkuLocationCategoryRef" }, "description": "Categorias de endereço atendidas pelo colaborador (`SkuLocationCategoryRef`)." }, "LocationsGroup": { "type": "array", "items": { "$ref": "#/components/schemas/SkuLocationGroupRef" }, "description": "Grupos de endereço atendidos pelo colaborador (`SkuLocationGroupRef`)." } } }, "UserWorkingDayCreate": { "type": "object", "description": "Corpo do `POST /user/workingday`. Listas CSV (string com ids separados por vírgula).", "required": [ "IDUser", "IDUserJobPositionList", "IDUserWorkScale" ], "properties": { "IDUser": { "type": "integer", "description": "Usuário já cadastrado no sistema. Precisa ter vínculo com a empresa (`UserCompany`)." }, "IDUserJobPositionList": { "type": "string", "description": "CSV de `IDUserJobPosition` — funções que o colaborador pode exercer." }, "IDUserJobPositionCurrent": { "type": "integer", "nullable": true, "description": "Função ativa no momento — precisa estar dentro de `IDUserJobPositionList`." }, "IDUserWorkScale": { "type": "integer", "description": "Escala de trabalho (cadastrada em **Turnos dos Colaboradores**)." }, "IDUserUpper": { "type": "integer", "nullable": true, "description": "`IDUserWorkingDay` do supervisor." }, "IDStockKeepingUnitLocationCategoryList": { "type": "string", "nullable": true, "description": "CSV de `IDStockKeepingUnitLocationCategory` — categorias de endereço atendidas pelo colaborador (precisam estar ativas: `IsActive = 1`)." }, "IDStockKeepingUnitLocationGroupList": { "type": "string", "nullable": true, "description": "CSV de `IDStockKeepingUnitLocationGroup` — grupos de endereço atendidos pelo colaborador." } } }, "UserWorkingDayUpdate": { "type": "object", "description": "Corpo do `PUT /user/workingday/{idworkingday}`. Atualização parcial — campos ausentes ficam intactos. Para limpar `IDStockKeepingUnitLocationCategoryList`, `IDStockKeepingUnitLocationGroupList` ou `IDUserUpper` enviar string vazia.", "properties": { "IDUser": { "type": "integer", "description": "Usuário cujo cadastro de colaborador será atualizado. Precisa pertencer à empresa autenticada." }, "IDUserJobPositionList": { "type": "string", "description": "CSV de identificadores de função que o colaborador pode exercer. Lista substitui a anterior." }, "IDUserJobPositionCurrent": { "type": "integer", "nullable": true, "description": "Função ativa do colaborador no momento — precisa estar dentro de `IDUserJobPositionList`. Envie `null` para limpar." }, "IDUserWorkScale": { "type": "integer", "description": "Identificador da escala de trabalho (`UserWorkScale`) vigente." }, "IDUserUpper": { "type": "integer", "nullable": true, "description": "Identificador do colaborador (`UserWorkingDay`) supervisor. String vazia limpa o campo. Colaborador não pode ser seu próprio supervisor." }, "IDStockKeepingUnitLocationCategoryList": { "type": "string", "nullable": true, "description": "CSV de categorias de endereço atendidas pelo colaborador. String vazia limpa o campo." }, "IDStockKeepingUnitLocationGroupList": { "type": "string", "nullable": true, "description": "CSV de grupos de endereço atendidos pelo colaborador. String vazia limpa o campo." }, "Status": { "type": "integer", "enum": [ 1, 2 ], "description": "Status do colaborador: `1` Ativo, `2` Inativo." } } }, "CarrierQuotationRuleUpdate": { "type": "object", "description": "Corpo do `PUT /carrier/quotation/rule/{idcarrierquotationrule}`. **Não é atualização parcial** — campos do cabeçalho ausentes são gravados como NULL. Recomenda-se enviar o cabeçalho inteiro. `Conditions` segue diff: condições novas são inseridas, ausentes são removidas.", "properties": { "CarrierQuotationRuleName": { "type": "string", "description": "Nome da regra (exibido na grid)." }, "Priority": { "type": "integer", "minimum": 1, "description": "Ordem de execução. Menor valor é avaliado primeiro." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "`1`=Ativo, `0`=Inativo. Use o DELETE para soft delete (`Status=2`)." }, "DateFrom": { "type": "string", "format": "date", "description": "Início da vigência (`YYYY-MM-DD`). Quando a UI desliga o switch \"Possui vigência\", o frontend envia `1900-01-01`." }, "DateTo": { "type": "string", "format": "date", "description": "Fim da vigência (`YYYY-MM-DD`). Quando o switch \"Possui vigência\" é desligado, o frontend envia `4000-01-01`." }, "IDTypeCarrierQuotationActionRule": { "$ref": "#/components/schemas/CarrierQuotationActionRuleEnum", "description": "Tipo de ação aplicada quando todas as condições da regra são atendidas. Valores em `CarrierQuotationActionRuleEnum`." }, "ActionValue": { "type": "string", "nullable": true, "description": "Valor associado à ação. Mesmas regras do `POST`: decimal em string para R$ (`2`, `6`, `10`), percentual para `%` (`3`, `5`, `7`), inteiro de dias para prazo (`1`, `13`), `null` para ação `9` (Excluir transportadoras)." }, "Conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierQuotationConditionPayload" }, "description": "Lista de condições da regra. Diff é aplicado: condições ausentes são removidas, novas são inseridas. Cada item segue `CarrierQuotationConditionPayload`." } } }, "CollectionListListItem": { "type": "object", "description": "Item de lista de romaneios. Vem do endpoint `GET /fulfillment/packing/collection-list` e também é retornado pelos endpoints que invocam o `List` internamente (close, open, file, merge).", "properties": { "IDOrdersCarrierCollectionList": { "type": "integer", "format": "int64", "description": "Identificador único do romaneio (identificador em `OrdersCarrierCollectionList`)." }, "AccountName": { "type": "string", "description": "Prefixo da conta (subdomínio idworks) à qual o romaneio pertence." }, "AccountNameDistributionCenter": { "type": "string", "nullable": true, "description": "Prefixo da conta do CD (`StockKeepingUnitDistributionCenter` quando aplicável)." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do CD onde o romaneio foi criado." }, "DistributionCenterName": { "type": "string", "nullable": true, "description": "Nome do CD." }, "Login": { "type": "string", "nullable": true, "description": "Login do usuário que criou o romaneio." }, "UserName": { "type": "string", "nullable": true, "description": "Nome do usuário que criou o romaneio." }, "RecordUserCreated": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do usuário que criou o romaneio." }, "OrdersCarrierCollectionListStatus": { "type": "string", "enum": [ "Aberto", "Fechado", "Finalizado" ], "description": "Rótulo do status atual. Mapeia para `IDOrdersCarrierCollectionListStatus`: `1`=Aberto, `2`=Fechado, `3`=Finalizado." }, "SupplierNameCorporateName": { "type": "string", "description": "Nome / razão social da transportadora vinculada (`Suppliers`)." }, "SupplierLogoUrl": { "type": "string", "format": "uri", "nullable": true, "description": "URL do logo do tipo da transportadora (`CarrierLogoUrl`)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de criação do romaneio (`DD/MM/YY HH:mm:ss` na exibição)." }, "RecordTimestampEnd": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de finalização do romaneio. Preenchido quando `IDOrdersCarrierCollectionListStatus = 3`." }, "CarrierDriverDocument": { "type": "string", "nullable": true, "description": "RG/CPF do motorista. Preenchido após assinatura." }, "CarrierDriverNameCorporateName": { "type": "string", "nullable": true, "description": "Nome do motorista. Preenchido após assinatura." }, "CarLicensePlate": { "type": "string", "nullable": true, "description": "Placa do veículo. Preenchido após assinatura." }, "Comments": { "type": "string", "nullable": true, "description": "Comentário livre do motorista ou da retirada." }, "SigningRecordTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora em que o motorista assinou (preenche `POST .../file`). Quando `null`, o romaneio ainda não foi assinado." }, "QtyOrder": { "type": "integer", "description": "Quantidade de pedidos distintos no romaneio (soma dos vínculos por `IDOrdersCarrierCollectionList` e `IDOrdersCarrierCollectionList`)." }, "QtyPackage": { "type": "integer", "description": "Quantidade de volumes (`Packages`) no romaneio." }, "FileName1": { "type": "string", "format": "uri", "nullable": true, "description": "URL pré-assinada (validade 48 h) da imagem da assinatura do motorista. `null` enquanto o romaneio não foi assinado." }, "FileName2": { "type": "string", "format": "uri", "nullable": true, "description": "URL pré-assinada da primeira foto/anexo opcional (documento, comprovante). `null` quando não enviada." }, "FileName3": { "type": "string", "format": "uri", "nullable": true, "description": "URL pré-assinada do segundo anexo opcional." }, "FileName4": { "type": "string", "format": "uri", "nullable": true, "description": "URL pré-assinada do terceiro anexo opcional." }, "FileName5": { "type": "string", "format": "uri", "nullable": true, "description": "URL pré-assinada do PDF final do romaneio (gerado no momento da assinatura)." } } }, "CollectionListOrderItem": { "type": "object", "description": "Pedido vinculado a um romaneio (subobjeto de `Orders`). Reflete os dados que aparecem na tabela do modal de conferência.", "properties": { "IDOrder": { "type": "integer", "format": "int64", "description": "Identificador do pedido." }, "Order": { "type": "string", "description": "Número do pedido visível ao usuário." }, "IDStatusOrder": { "type": "integer", "description": "Status do pedido (`TypeStatusOrder`). Valores relevantes: `6` Aguardando expedição, `7` Enviado, `8` Entregue, `17` Retirada, `22` Aguardando romaneio." }, "StatusOrder": { "type": "string", "description": "Rótulo do status do pedido." }, "AccountName": { "type": "string", "description": "Prefixo da conta do pedido." }, "ConsumerCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ do destinatário." }, "ShippingReceiverName": { "type": "string", "nullable": true, "description": "Nome do destinatário (entrega)." }, "ShippingCity": { "type": "string", "nullable": true, "description": "Cidade de entrega." }, "ShippingState": { "type": "string", "nullable": true, "description": "UF de entrega." }, "ShippingId": { "type": "string", "nullable": true, "description": "Código de rastreio da transportadora gravado no pacote." }, "NfeNumber": { "type": "string", "nullable": true, "description": "Número da NF-e do pedido." }, "NfeChaveAcesso": { "type": "string", "nullable": true, "description": "Chave de acesso da NF-e (44 dígitos)." }, "NfeTotalValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor total da NF-e." }, "IDPackage": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do volume." }, "Package": { "type": "string", "nullable": true, "description": "Composição `Order-PackageNumber` usada na bipagem." }, "PackageNumber": { "type": "integer", "nullable": true, "description": "Número sequencial do volume dentro do pedido." }, "Weight": { "type": "number", "format": "double", "nullable": true, "description": "Peso do volume (`PackageWeight`). Quando vazio, calculado a partir da soma `SkuWeight * Quantity` dos movimentos." }, "IDCarrierType": { "type": "integer", "nullable": true, "description": "Tipo da transportadora. `30` e `32` representam retirada (canal/marketplace ou loja); influencia transição do pedido para status `17` no finish." }, "IDConsumer": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do cliente." }, "IDAddress": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do endereço de entrega." }, "IDOrderType": { "type": "integer", "nullable": true, "description": "Tipo do pedido (`TypeOrder`)." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração de origem do pedido (`CompanyIntegration`), quando aplicável." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Nome/razão social do faturador da NF do pedido (quando diferente da empresa de venda)." }, "CompanyCpfCnpjInvoice": { "type": "string", "nullable": true, "description": "CNPJ do faturador da NF." }, "CompanyLogoUrlInvoice": { "type": "string", "format": "uri", "nullable": true, "description": "URL do logo do faturador." }, "StatusColorCode": { "type": "string", "nullable": true, "description": "Cor (hex) do status do pedido configurada para a empresa, ex.: #33A7D8. Usada para colorir o badge de status na tela." } } }, "CollectionListPendingPackage": { "type": "object", "description": "Volume **pendente de embarque** — pacote de um pedido presente no romaneio que **não está** vinculado a este romaneio. Indica que o pedido pode ser despachado parcialmente. Subobjeto de `PedingPackages` (com o typo histórico do campo no banco).", "properties": { "IDOrder": { "type": "integer", "format": "int64", "description": "Identificador do pedido a que o volume pertence." }, "Order": { "type": "string", "description": "Código externo do pedido (número visível ao cliente)." }, "IDPackage": { "type": "integer", "format": "int64", "description": "Identificador do volume (etiqueta de envio) dentro do pedido." }, "PackageNumber": { "type": "integer", "description": "Número sequencial do volume dentro do pedido (1, 2, 3...)." }, "ShippingId": { "type": "string", "nullable": true, "description": "Código de rastreio atribuído pelo transportador/integração ao volume. Vazio até a coleta ser confirmada." }, "NfeNumber": { "type": "string", "nullable": true, "description": "Número da nota fiscal emitida para o volume. Vazio enquanto a NF-e não foi emitida." }, "ShippingReceiverName": { "type": "string", "nullable": true, "description": "Nome do destinatário do envio (impresso na etiqueta)." } } }, "CollectionListDetail": { "type": "object", "description": "Detalhe completo de um romaneio. Vem do endpoint `GET /fulfillment/packing/collection-list/{id}` e também é retornado por endpoints que invocam o `Get` internamente (put, finish, orderPut).", "properties": { "IDOrdersCarrierCollectionList": { "type": "integer", "format": "int64", "description": "Identificador do romaneio." }, "IDOrdersCarrierCollectionListStatus": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Status numérico. `1` Aberto, `2` Fechado, `3` Finalizado." }, "OrdersCarrierCollectionListStatus": { "type": "string", "enum": [ "Aberto", "Fechado", "Finalizado" ], "description": "Nome amigável do status do romaneio." }, "AccountName": { "type": "string", "description": "Identificador da empresa dona do romaneio." }, "CompanyNameCorporateName": { "type": "string", "description": "Nome / razão social da empresa que vendeu (ou do faturador, quando `ShowCompanyInvoiceCarrierCollection=1`)." }, "CompanyCpfCnpj": { "type": "string", "description": "CPF/CNPJ da empresa que emitiu o romaneio (ou do faturador, quando o parâmetro `Mostrar dados do faturador no romaneio` está ativo)." }, "CompanyLogoUrl": { "type": "string", "format": "uri", "nullable": true, "description": "URL pública da logo da empresa (ou do faturador, quando o parâmetro `Mostrar dados do faturador no romaneio` está ativo). `null` quando não cadastrada." }, "SupplierNameCorporateName": { "type": "string", "description": "Transportadora do romaneio." }, "SupplierLogoUrl": { "type": "string", "format": "uri", "nullable": true, "description": "URL pública da logo da transportadora (`CarrierLogoUrl`). `null` quando o tipo de transportadora não tem logo." }, "Login": { "type": "string", "nullable": true, "description": "Login do colaborador que finalizou o romaneio. `null` enquanto o romaneio não estiver finalizado." }, "UserName": { "type": "string", "nullable": true, "description": "Nome do colaborador que finalizou o romaneio. `null` enquanto o romaneio não estiver finalizado." }, "RecordTimestampEnd": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de finalização. `null` enquanto status != 3." }, "CarrierDriverDocument": { "type": "string", "nullable": true, "description": "RG ou CPF do motorista que retirou. Preenchido apenas após a assinatura (`POST .../file`)." }, "CarrierDriverNameCorporateName": { "type": "string", "nullable": true, "description": "Nome do motorista que retirou. Preenchido apenas após a assinatura." }, "CarLicensePlate": { "type": "string", "nullable": true, "description": "Placa do veículo (até 8 caracteres). Preenchida apenas após a assinatura." }, "Comments": { "type": "string", "nullable": true, "description": "Comentário livre informado no momento da assinatura. `null` quando não informado." }, "SigningRecordTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora da assinatura do motorista. `null` enquanto o romaneio não tiver sido assinado." }, "FileName1": { "type": "string", "format": "uri", "nullable": true, "description": "URL pré-assinada da assinatura (validade 48 h)." }, "FileName2": { "type": "string", "format": "uri", "nullable": true, "description": "URL do segundo arquivo anexo da assinatura. `null` quando não enviado." }, "FileName3": { "type": "string", "format": "uri", "nullable": true, "description": "URL do terceiro arquivo anexo da assinatura. `null` quando não enviado." }, "FileName4": { "type": "string", "format": "uri", "nullable": true, "description": "URL do quarto arquivo anexo da assinatura. `null` quando não enviado." }, "FileName5": { "type": "string", "format": "uri", "nullable": true, "description": "URL pré-assinada do PDF final do romaneio." }, "Orders": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionListOrderItem" }, "description": "Lista dos pedidos/volumes que compõem o romaneio." }, "PedingPackages": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionListPendingPackage" }, "description": "Volumes de pedidos deste romaneio que estão em **outro** romaneio (ou ainda sem amarração). Usado pelo frontend para avisar sobre split de pacotes ao fechar." } } }, "CollectionListPostPayload": { "type": "object", "required": [ "IDCarrier" ], "properties": { "IDCarrier": { "type": "integer", "format": "int64", "description": "Identificador da transportadora (`IDSupplier`) que vai retirar este romaneio. Precisa pertencer à mesma empresa (`IDCompany`)." } } }, "CollectionListPutPayload": { "type": "object", "required": [ "IDCarrier" ], "properties": { "IDCarrier": { "type": "integer", "format": "int64", "description": "Nova transportadora (`IDSupplier`). Precisa estar ativa (`SupplierStatus=1`), pertencer à mesma empresa e ser diferente da atual." } } }, "CollectionListFilePayload": { "type": "object", "required": [ "CarrierDriverDocument", "CarrierDriverNameCorporateName", "CarLicensePlate", "FileName1", "FileName5" ], "description": "Payload de assinatura do romaneio pelo motorista. Todos os arquivos (`FileName1..5`) são enviados como **data URIs base64** (`data:image/png;base64,...` ou `data:application/pdf;base64,...`). O sistema faz upload para o S3 `OrdersCarrierCollectionListFiles/`.", "properties": { "CarrierDriverDocument": { "type": "string", "description": "RG ou CPF do motorista que retirou." }, "CarrierDriverNameCorporateName": { "type": "string", "description": "Nome do motorista." }, "CarLicensePlate": { "type": "string", "maxLength": 8, "description": "Placa do veículo (até 8 caracteres alfanuméricos, em maiúsculas)." }, "Comments": { "type": "string", "nullable": true, "description": "Comentário livre da retirada." }, "FileName1": { "type": "string", "description": "Imagem da assinatura digital (data URI base64). Obrigatório." }, "FileName2": { "type": "string", "nullable": true, "description": "Primeira foto/anexo de apoio (documento, comprovante). Data URI base64." }, "FileName3": { "type": "string", "nullable": true, "description": "Segundo anexo opcional." }, "FileName4": { "type": "string", "nullable": true, "description": "Terceiro anexo opcional." }, "FileName5": { "type": "string", "description": "PDF completo do romaneio assinado (data URI base64). Obrigatório — esse é o documento persistido para impressão futura." } } }, "CollectionListMergePayload": { "type": "object", "required": [ "IDCollectionList" ], "properties": { "IDCollectionList": { "oneOf": [ { "type": "integer", "format": "int64" }, { "type": "array", "items": { "type": "integer", "format": "int64" } } ], "description": "Identificador (ou array de identificadores) dos romaneios **origem** que serão mesclados no romaneio destino (path param). Origens precisam estar em status `3` (Finalizado), não assinadas e com a mesma `IDCarrier` do destino. Origens são removidas da base após o merge (registros de `Orders` / `Packages` migrados para o destino)." } } }, "CollectionListOrderPutPayload": { "type": "object", "required": [ "IDCarrier", "IDPackageArray" ], "properties": { "IDCarrier": { "type": "integer", "format": "int64", "description": "Nova transportadora para os pedidos cujos pacotes serão removidos. Precisa estar ativa e pertencer à mesma empresa." }, "IDPackageArray": { "type": "array", "minItems": 1, "items": { "type": "integer", "format": "int64" }, "description": "Lista de `IDPackage` a serem removidos deste romaneio. Cada pacote precisa pertencer a este romaneio (validado contra `IDOrdersCarrierCollectionList` e `IDOrdersCarrierCollectionList`). Os pedidos correspondentes voltam para `IDStatusOrder = 22` (Aguardando expedição) com a nova transportadora atribuída." } } }, "PackingPickingListItem": { "type": "object", "description": "Item de pedido pendente de conferência no packing. Vem do `Items[]` em `GET /fulfillment/packing/picking-list/{id}`.", "properties": { "IDSku": { "type": "integer", "format": "int64", "description": "Identificador do SKU da linha da picking list." }, "IDSkuMovement": { "type": "integer", "format": "int64", "description": "Identificador da movimentação de estoque do pedido para este SKU." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência interna do SKU." }, "SkuName": { "type": "string", "description": "Nome do SKU a separar." }, "AbcCurve": { "type": "string", "nullable": true, "description": "Curva ABC do produto (A, B, C)." }, "SkuWeight": { "type": "number", "format": "double", "nullable": true, "description": "Peso unitário do SKU em kg." }, "Quantity": { "type": "number", "format": "double", "description": "Quantidade esperada deste SKU no pedido." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal." }, "BarCodeList": { "type": "array", "items": { "type": "string" }, "description": "Códigos de barras alternativos aceitos." }, "BarCodePackageList": { "type": "array", "items": { "type": "object", "properties": { "IDStockKeepingUnitBarCodePackage": { "type": "integer", "description": "Identificador do código de barras alternativo cadastrado para o SKU (embalagem secundária com fator de conversão)." }, "BarCodePackage": { "type": "string", "description": "Código de barras da embalagem alternativa (ex.: caixa com 12 unidades)." }, "PackageFactor": { "type": "number", "description": "Quantidade de unidades do SKU equivalente a 1 leitura deste código de barras (ex.: `12` = bipou 1 caixa, vale 12 unidades)." } } }, "description": "Códigos de barras de embalagens (caixa, fardo) com seu fator multiplicador." }, "Address": { "type": "string", "nullable": true, "description": "Endereço de armazenagem onde o item foi separado." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de validade (quando aplicável)." }, "Order": { "type": "string", "description": "Número do pedido (redundância para uso no card do item)." }, "PickingBasket": { "type": "string", "nullable": true, "description": "Identificador do cesto (colmeia) interno." }, "HasSerialNumber": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` se o SKU controla número de série/IMEI — exige bipagem individual." }, "MainImageURL": { "type": "string", "format": "uri", "nullable": true, "description": "URL da imagem principal do SKU para exibição na tela do separador." }, "IDSkuKit": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do SKU pai do kit, quando o item é parte de um kit." }, "KitSkuName": { "type": "string", "nullable": true, "description": "Nome do SKU kit-pai quando este item é componente de um kit sendo separado. Vazio quando o item não é componente de kit." }, "WarehouseName": { "type": "string", "nullable": true, "description": "Nome do armazém de onde o SKU deve ser separado." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Nome ou razão social do fornecedor preferencial do SKU (informativo)." }, "PickingListBasketExternalIdList": { "type": "array", "items": { "type": "string" }, "description": "Códigos externos dos cestos onde este item foi armazenado durante o picking." } } }, "PackingPickingListOrder": { "type": "object", "description": "Pedido dentro de uma picking-list, com todos os itens a conferir.", "properties": { "IDOrder": { "type": "integer", "format": "int64", "description": "Identificador do pedido a conferir." }, "Order": { "type": "string", "description": "Número do pedido (texto exibido na tela)." }, "IDStatusOrder": { "type": "integer", "description": "Status numérico atual do pedido. Ver `TypeStatusOrderEnum`." }, "StatusOrder": { "type": "string", "description": "Nome amigável do status atual do pedido." }, "IDPickingList": { "type": "integer", "format": "int64", "description": "Identificador da picking-list a que o pedido pertence." }, "IDTypePickingList": { "type": "integer", "description": "Tipo de picking-list: `1` Picking, `2` Picking & Packing, `3` Monopedido, `4` Colméia.", "enum": [ 1, 2, 3, 4 ] }, "TypePickingList": { "type": "string", "description": "Nome amigável do tipo de picking-list." }, "PickingBasket": { "type": "string", "nullable": true, "description": "Identificador sequencial do cesto/caixa atribuído ao pedido durante a separação (`PickingBasket`). `null` quando o pedido ainda não recebeu cesto." }, "PickingListBasketExternalIdList": { "type": "array", "items": { "type": "string" }, "description": "Lista de códigos externos (`ExternalId`) dos cestos usados na coleta deste pedido. Vazia quando nenhum cesto foi registrado." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Nome / razão social do consumidor." }, "OrdersSalesChannelLabelStatus": { "type": "string", "nullable": true, "description": "Status da etiqueta no canal de venda (Mercado Livre, Magalu, etc.)." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Transportadora amarrada ao pedido." }, "IDCarrierType": { "type": "integer", "nullable": true, "description": "Identificador do tipo de transportadora do pedido. `null` quando o pedido ainda não tem transportadora definida." }, "PrintDanfeA4": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se o pedido exige DANFE em formato A4 (em vez de simplificada)." }, "ManualLabel": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica que a etiqueta é gerada externamente (canal/marketplace) — usa fluxo de carregar arquivo." }, "OrderPriority": { "type": "integer", "description": "Prioridade do pedido (0=mais alta, 10=mais baixa)." }, "OrderComments": { "type": "string", "nullable": true, "description": "Observação do pedido (texto livre cadastrado pelo operador ou pelo canal de origem)." }, "IDConsumer": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do consumidor." }, "IDSupplier": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do fornecedor do pedido (quando vier de marketplace)." }, "AccountName": { "type": "string", "description": "Identificador da empresa dona do pedido." }, "Items": { "type": "array", "items": { "$ref": "#/components/schemas/PackingPickingListItem" }, "description": "Lista de itens esperados para conferência no packing deste pedido. Cada entrada representa um movimento de estoque (`StockKeepingUnitMovement`) a bipar." }, "Draft": { "description": "Rascunho do packing salvo (último body enviado via `POST .../order/{id}?Draft=1`). Quando vazio, retorna `[]`. Quando presente, contém os campos do body de packing parciais (`Items`, `Volumes`, `Packages`, `ItemsCheckedVol`, etc.) para restaurar o progresso do operador na tela." }, "StatusColorCode": { "type": "string", "nullable": true, "description": "Cor (hex) do status do pedido configurada para a empresa, ex.: #33A7D8. Usada para colorir o badge de status na tela de packing." } } }, "PackingItem": { "type": "object", "required": [ "IDSku", "Quantity" ], "description": "Item conferido no packing. Cada bipagem na tela acumula uma entrada deste tipo.", "properties": { "IDSku": { "type": "integer", "format": "int64", "description": "Identificador do SKU sendo embalado na operação de packing." }, "Quantity": { "type": "number", "format": "double", "description": "Quantidade conferida deste SKU neste volume." }, "PackageNumber": { "type": "integer", "default": 1, "description": "Número do volume em que este item foi alocado (1, 2, 3...). Default `1`." }, "SerialNumber": { "type": "string", "nullable": true, "description": "Número de série/IMEI do item. Obrigatório quando o SKU tem `HasSerialNumber=1`. Cada item com série precisa ser enviado individualmente (uma linha por unidade, `Quantity=1`)." }, "CommentsInvoice": { "type": "string", "nullable": true, "description": "Observação fiscal específica deste item (vai para a NF-e)." } } }, "PackingVolume": { "type": "object", "required": [ "PackageNumber" ], "description": "Dados físicos de um volume (peso e dimensões). Preenchidos quando a parametrização **Conferir peso e medidas ao adicionar volume** está ativa.", "properties": { "PackageNumber": { "type": "integer", "description": "Número sequencial do volume (1, 2, 3...)." }, "PackageWeight": { "type": "number", "format": "double", "description": "Peso do volume em kg." }, "PackageHeight": { "type": "number", "format": "double", "description": "Altura do volume em cm." }, "PackageLength": { "type": "number", "format": "double", "description": "Comprimento do volume em cm." }, "PackageWidth": { "type": "number", "format": "double", "description": "Largura do volume em cm." } } }, "PackingPackage": { "type": "object", "required": [ "IDSku", "Quantity", "PackageNumber" ], "description": "SKU tipo embalagem (Package=1) usado no volume. Preenchido quando a parametrização **Adicionar embalagem na conferência** está ativa. Cada embalagem entra como linha de movimentação no pedido (valor 0).", "properties": { "IDSku": { "type": "integer", "format": "int64", "description": "Identificador do SKU embalagem." }, "Quantity": { "type": "number", "format": "double", "description": "Quantidade de embalagens usadas neste volume (geralmente 1)." }, "PackageNumber": { "type": "integer", "description": "Volume em que esta embalagem foi usada." } } }, "PackingOrderPostPayload": { "type": "object", "description": "Payload de finalização (ou rascunho, com `?Draft=1`) do packing de um pedido. Quando todos os itens conferem com os esperados na picking-list (`Items` enviados batem com `StockKeepingUnitMovement` do pedido), o sistema cria os volumes, emite a NF-e e atualiza o status do pedido.", "properties": { "IDPickingList": { "type": "integer", "format": "int64", "description": "Identificador da picking-list a que o pedido pertence. Necessário para o salvamento de rascunho (`?Draft=1`)." }, "QuantityPackages": { "type": "integer", "default": 1, "description": "Quantidade total de volumes do pedido. O sistema reconcilia o número de linhas em `Packages` para bater com este valor (cria linhas faltantes, apaga excedentes)." }, "Items": { "type": "array", "items": { "$ref": "#/components/schemas/PackingItem" }, "description": "Lista de itens conferidos. Cada bipagem na tela vira uma entrada aqui." }, "Volumes": { "type": "array", "items": { "$ref": "#/components/schemas/PackingVolume" }, "description": "Peso e dimensões de cada volume. Opcional, mas exigido pelo frontend quando `AddPackageWeight=1`." }, "Packages": { "type": "array", "items": { "$ref": "#/components/schemas/PackingPackage" }, "description": "SKUs tipo embalagem usados nos volumes. Opcional, mas exigido pelo frontend quando `AddPackage=1`." }, "TempAuthToken": { "type": "string", "description": "Token temporário obtido via `POST /user/{id}/verify`. Obrigatório quando `PartialInvoice=1` (precisa do privilégio **Autorizar packing/faturamento parcial**)." } } }, "PickingListMergePayload": { "type": "object", "required": [ "IDPickingList" ], "properties": { "IDPickingList": { "type": "integer", "format": "int64", "description": "Identificador da picking-list **destino** (na qual a origem será mesclada). Origem (path param) e destino precisam estar em status `1` (Pendente). O destino mantém sua prioridade e configuração; os pedidos da origem têm `IDPickingList` reatribuído para o destino e a picking-list de origem é removida." } } }, "PickingListListItem": { "type": "object", "description": "Item da lista de picking-lists. Retornado por `GET /fulfillment/picking/picking-list` e usado como resposta dos handlers que invocam o List internamente (Merge).", "properties": { "IDPickingList": { "type": "integer", "format": "int64", "description": "Identificador da picking-list." }, "IDPickingListStatus": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Status numérico. `1` Picking-List Pendente, `2` Picking-List Iniciado, `3` Picking-List Coletado, `4` Packing Processando, `5` Packing Concluido, `6` Picking-List ag. continuidade, `7` Picking-List Iniciado 2." }, "StatusPickingList": { "type": "string", "description": "Nome do status conforme retornado pelo sistema: `Picking-List Pendente`, `Picking-List Iniciado`, `Picking-List Coletado`, `Packing Processando`, `Packing Concluido`, `Picking-List ag. continuidade`, `Picking-List Iniciado 2`." }, "IDTypePickingList": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Tipo de picking-list: `1` Picking, `2` Picking & Packing, `3` Monopedido, `4` Colméia." }, "TypePickingList": { "type": "string", "description": "Nome amigável do tipo de coleta (`Picking`, `Picking/Packing`, `Monopedido`, `Colméia`)." }, "PickingListPriority": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Prioridade da picking-list (0=mais alta, 10=mais baixa). Recalculada conforme parametrização `UseShippingHandlingTimeInPickingPriority`." }, "PickingListConfigurationName": { "type": "string", "nullable": true, "description": "Nome da configuração de picking que gerou a lista (de `PickingListConfiguration`)." }, "AccountName": { "type": "string", "description": "Identificador da empresa dona da picking-list." }, "RecordUserCreated": { "type": "integer", "format": "int64", "description": "Usuário que disparou a geração." }, "Login": { "type": "string", "nullable": true, "description": "Login do usuário criador." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de criação." }, "RecordUserCreatedStartPicking": { "type": "integer", "format": "int64", "nullable": true, "description": "Colaborador atribuído (separador)." }, "LoginStartPicking": { "type": "string", "nullable": true, "description": "Login do colaborador atribuído ou `null` quando não atribuído." }, "RecordTimestampStartPicking": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora em que a separação foi iniciada (`POST .../start`). `null` enquanto a picking-list estiver pendente." }, "RecordTimestampFinishedPicking": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora em que a separação foi finalizada (`POST .../finish`). `null` enquanto a coleta não terminou." }, "RecordUserCreatedStartPacking": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do colaborador que iniciou o packing dos pedidos desta picking-list. `null` antes do packing começar." }, "LoginStartPacking": { "type": "string", "nullable": true, "description": "Login do colaborador que iniciou o packing." }, "RecordTimestampStartPacking": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora em que o packing dos pedidos desta picking-list foi iniciado." }, "RecordTimestampEnd": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora em que o packing da lista terminou." }, "QtyOrder": { "type": "integer", "description": "Quantidade de pedidos na picking-list." }, "QtyOrderDone": { "type": "integer", "description": "Quantidade de pedidos já processados (status `IN (6, 7, 8, 17, 19, 22, 94, 95)`)." }, "ItemsQuantity": { "type": "number", "format": "double", "description": "Soma das quantidades de todos os movimentos de estoque da lista." }, "SkuQuantity": { "type": "integer", "description": "Quantidade de SKUs distintos." }, "ShippingEstimateDate": { "type": "string", "format": "date", "nullable": true, "description": "Data prevista de entrega mais próxima entre os pedidos da lista." }, "StockKeepingUnitLocationGroupName": { "type": "string", "nullable": true, "description": "Nomes (concatenados) dos grupos de endereço de armazenagem cobertos pela picking-list." }, "TypeOrder": { "type": "string", "nullable": true, "description": "Tipos de pedido (concatenados) presentes na lista." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Transportadoras (concatenadas)." }, "IDPickingListFather": { "type": "integer", "nullable": true, "description": "Identificador da picking-list pai em listas do tipo colméia (`IDTypePickingList=4`); `null` nas demais." }, "Checked": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se a picking-list foi conferida (`1`) ou não (`0`)." } } }, "PickingListMovementItem": { "type": "object", "description": "Linha da picking-list detalhada (vem de `GET /fulfillment/picking/picking-list/{id}`). Representa uma agregação de movimentos de estoque por SKU + (pedido + lote) ou, em modo agrupado, por SKU + endereço.", "properties": { "IDPickingList": { "type": "integer", "format": "int64", "description": "Identificador da picking-list a que a linha pertence." }, "TypePickingList": { "type": "string", "description": "Nome amigável do tipo de coleta (`Picking`, `Picking/Packing`, `Monopedido`, `Colméia`)." }, "IDSku": { "type": "integer", "format": "int64", "description": "Identificador do SKU a separar." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código interno do SKU usado pela empresa (referência). `null` quando não cadastrado." }, "SkuName": { "type": "string", "description": "Nome do SKU." }, "AbcCurve": { "type": "string", "nullable": true, "description": "Curva ABC do SKU (`A`, `B`, `C`). `null` quando ainda não classificado." }, "SkuWeight": { "type": "number", "format": "double", "nullable": true, "description": "Peso unitário do SKU em quilos. `null` quando não cadastrado." }, "Quantity": { "type": "number", "format": "double", "description": "Quantidade total (soma) deste agrupamento." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal do SKU. `null` quando não cadastrado." }, "BarCodeList": { "type": "array", "items": { "type": "string" }, "description": "Lista de códigos de barras alternativos aceitos durante a bipagem." }, "BarCodePackageList": { "type": "array", "items": { "type": "object", "properties": { "IDStockKeepingUnitBarCodePackage": { "type": "integer", "description": "Identificador da embalagem cadastrada." }, "BarCodePackage": { "type": "string", "description": "Código de barras da embalagem (caixa, fardo, display)." }, "PackageFactor": { "type": "number", "description": "Quantidade de unidades contidas na embalagem (ex.: `12` para um fardo de 12 unidades)." } } }, "description": "Lista de embalagens (pacote/caixa) com seus códigos de barras e quantidade equivalente em unidades. Permite bipar uma caixa fechada e o sistema contar o múltiplo correto." }, "Address": { "type": "string", "nullable": true, "description": "Endereço de armazenagem (rua-módulo-coluna-nível) onde o item será coletado." }, "IDBatch": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do lote a separar. `null` quando o SKU não opera por lote." }, "Batch": { "type": "boolean", "description": "Indica se o SKU é gerenciado por lote." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Validade do lote no formato `YYYY-MM-DD`. `null` quando o SKU não opera por lote." }, "ManufacturingDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de fabricação do lote no formato `YYYY-MM-DD`. `null` quando o SKU não opera por lote." }, "Comments": { "type": "string", "nullable": true, "description": "Observação cadastrada no lote (ex.: número do romaneio de entrada). `null` quando o lote não tem observação." }, "MainImageThumbnailURL": { "type": "string", "format": "uri", "nullable": true, "description": "URL pública da miniatura da imagem principal do SKU. `null` quando o SKU não tem imagem cadastrada." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do armazém de origem dentro do CD. `null` quando o item ainda não está alocado a um endereço." }, "WarehouseName": { "type": "string", "nullable": true, "description": "Nome do armazém de origem. `null` quando não alocado." }, "IDSkuKit": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do SKU kit do qual este item faz parte (composição). `null` quando o item não pertence a um kit." }, "KitSkuName": { "type": "string", "nullable": true, "description": "Nome do SKU kit pai. `null` quando o item não pertence a um kit." }, "IDOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "`null` em modo agrupado." }, "Order": { "type": "string", "nullable": true, "description": "Número do pedido (omitido em modo agrupado)." }, "IDStatusOrder": { "type": "integer", "nullable": true, "description": "Status numérico do pedido associado à linha. `null` na visão agrupada por SKU (`IDTypePickingList = 1`)." }, "StatusOrder": { "type": "string", "nullable": true, "description": "Nome amigável do status do pedido. `null` na visão agrupada por SKU." }, "IDConsumer": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do consumidor do pedido. `null` na visão agrupada por SKU." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Nome / razão social do consumidor do pedido. `null` na visão agrupada por SKU." }, "IDSupplier": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do fornecedor/marketplace do pedido. `null` na visão agrupada por SKU." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Transportadora do pedido (`null` em modo agrupado)." }, "AccountName": { "type": "string", "nullable": true, "description": "Identificador da empresa dona do pedido." }, "IDSkuMovement": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do movimento de estoque que originou a linha. Usado como path param em `PUT .../sku/{idskumovement}` para apontar inconformidade." }, "PickingBasket": { "type": "string", "nullable": true, "description": "Cesto/colmeia do pedido (em modo agrupado é `null`)." }, "PickingListBasketExternalId": { "type": "string", "nullable": true, "description": "Código externo do cesto (do `PickingListBasket`)." }, "PrintDanfeA4": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se a transportadora exige impressão da DANFE em A4 junto da etiqueta. `1` Sim, `0` Não." }, "ManualLabel": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se a transportadora opera com etiqueta manual (não emitida pelo canal de venda). `1` Sim, `0` Não." }, "RecordtimestampOrder": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora de criação do pedido. `null` na visão agrupada por SKU." }, "Floor": { "type": "integer", "nullable": true, "description": "Andar do endereço de coleta (usado na rota otimizada)." }, "Street": { "type": "string", "nullable": true, "description": "Identificador da rua dentro do CD (endereçamento físico). `null` quando o item ainda não tem endereço definido." }, "Module": { "type": "string", "nullable": true, "description": "Identificador do módulo (estrutura/estante) dentro da rua. `null` quando sem endereço." }, "Column": { "type": "string", "nullable": true, "description": "Identificador da coluna dentro do módulo. `null` quando sem endereço." }, "Level": { "type": "string", "nullable": true, "description": "Identificador do nível (altura/prateleira) dentro da coluna. `null` quando sem endereço." }, "LocationSide": { "type": "integer", "enum": [ 1, 2 ], "nullable": true, "description": "`1` lado direito (rua ímpar), `2` lado esquerdo (rua par)." }, "StatusColorCode": { "type": "string", "nullable": true, "description": "Cor (hex) do status do pedido configurada para a empresa, ex.: #33A7D8. null na visão agrupada por SKU." }, "IDStockKeepingUnitLocation": { "type": "integer", "nullable": true, "description": "Identificador do endereço de armazenagem da linha." }, "IDPickingListStatus": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7 ], "nullable": true, "description": "Status da picking-list a que a linha pertence." }, "IDPickingListFather": { "type": "integer", "nullable": true, "description": "Identificador da picking-list pai (colméia); `null` nas demais." }, "Checked": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se a picking-list foi conferida (`1`) ou não (`0`)." } } }, "PickingPostPayload": { "type": "array", "description": "Array de identificadores de pedido (`IDOrder`) a serem agrupados em picking-list(s). O sistema agrupa por **combinação de `IDStockKeepingUnitLocationGroup`** dos itens do pedido (mesmo CD obrigatório). Cada grupo único de endereços vira uma picking-list distinta.", "items": { "type": "integer", "format": "int64" } }, "PickingListPutPayload": { "type": "object", "description": "Body do PUT /fulfillment/picking/picking-list/{id}. Pelo menos um campo precisa ser informado. Com ?Draft=1 o body é gravado como rascunho temporário (TTL 4 dias) sem tocar o banco.", "properties": { "RecordUserCreatedStartPicking": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do colaborador atribuído. O colaborador precisa ter jornada de trabalho ativa e função de separador de pedido (IDUserJobPosition = 3). Aceita null para desatribuir. Só aceito quando a picking-list está em status 1, 2, 3, 4, 6 ou 7." }, "IDTypePickingList": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Tipo de picking-list: 1 Picking, 2 Picking & Packing, 3 Monopedido, 4 Colméia." }, "PickingListPriority": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Nova prioridade (0=mais alta, 10=mais baixa)." }, "IDPickingListStatus": { "type": "integer", "enum": [ 4, 6, 7 ], "description": "Move o status da picking-list. Apenas 4, 6 e 7 são aceitos — outros valores são ignorados; para 1->2 e 2->3 use /start e /finish. Setar 6 zera automaticamente RecordUserCreatedStartPicking." }, "Checked": { "type": "integer", "enum": [ 0, 1 ], "description": "Marca a conferência da picking-list (1 conferida, 0 não). Enviar vazio equivale a não alterar. Confirmar tipo/nullabilidade no DDL." } } }, "PickingListFinishPayload": { "type": "array", "description": "Array opcional informando, para cada pedido da picking-list, os códigos externos de cestos a serem registrados (`PickingListBasket`). Quando preenchido, o sistema registra (upsert) cada cesto vinculado por `(CD, ExternalId, IDOrder)`. Quando vazio ou ausente, a finalização só atualiza status e timestamps.", "items": { "type": "object", "required": [ "IDOrder", "PickingListBasketExternalIdList" ], "properties": { "IDOrder": { "type": "integer", "format": "int64", "description": "Identificador do pedido (usado quando o vínculo de cestos é informado por pedido)." }, "PickingListBasketExternalIdList": { "type": "array", "items": { "type": "string" }, "description": "Lista de códigos externos dos cestos usados na coleta deste pedido." } } } }, "PickingNonconformityPayload": { "type": "object", "required": [ "QuantityNonconformity", "IDTypeFulfillmentNonconformity" ], "properties": { "QuantityNonconformity": { "type": "number", "format": "double", "description": "Quantidade do SKU que entrou em inconformidade (faltou, está vencida ou avariada). Pode ser menor que a quantidade total do movimento — nesse caso, com `TransferIfPossible=1`, o movimento é dividido em dois (um para a quantidade ok, outro para a inconforme)." }, "IDTypeFulfillmentNonconformity": { "type": "integer", "enum": [ 1, 2, 5, 6 ], "description": "Tipo de inconformidade (de `TypeFulfillmentNonconformity`): `1` Avariado, `2` Vencido, `5` Falta, `6` Ressuprimento (atribuído pelo próprio sistema quando o pulmão tem saldo)." } } }, "OrdersListItem": { "type": "object", "description": "Item da resposta do `GET /orders` no modo padrão (sem `SkuView=1`). Combina dados do pedido (`Orders`), do status (`TypeStatusOrderCompany`), do tipo de pedido (`TypeOrder`), da NF principal (`NfCompany`), da integração (`CompanyIntegration` + `TypeCompanyIntegration`), da transportadora (`Suppliers`), do faturador (`Company` aliasado) e do CD (`StockKeepingUnitDistributionCenter`). Quando `SkuView=1` é passado, o shape muda: as colunas planas são substituídas por um campo `Items` (array de SKUs do pedido).", "properties": { "IDOrder": { "type": "integer", "format": "int64", "description": "Código interno do pedido." }, "Order": { "type": "string", "description": "Número do pedido (`Order`)." }, "OrderFrom": { "type": "string", "nullable": true, "description": "Número(s) do pedido no canal de origem (CSV agregado por `GROUP_CONCAT`)." }, "Recordtimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do pedido." }, "DateLastRecordModification": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora da última modificação do pedido." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) a que o pedido pertence." }, "Budget": { "type": "integer", "enum": [ 0, 1 ], "description": "`0` = pedido firme, `1` = orçamento." }, "BalanceChange": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` = movimenta estoque (pedido), `0` = só fiscal (nota sem movimento)." }, "IDStatusOrder": { "type": "integer", "description": "Status do pedido (`IDStatusOrder`)." }, "StatusOrder": { "type": "string", "description": "Descrição do status do pedido para a empresa (`StatusOrder` — permite override por empresa)." }, "StatusColorCode": { "type": "string", "nullable": true, "description": "Cor hex do status (`#RRGGBB`) — usada para colorir a coluna na grade." }, "IDOrderType": { "type": "integer", "description": "Tipo de pedido (`IDTypeOrder`)." }, "TypeOrder": { "type": "string", "description": "Descrição do tipo de pedido." }, "ServiceRequest": { "type": "integer", "enum": [ 0, 1 ], "description": "`ServiceRequest` — `1` indica que o tipo é ordem de serviço." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "nullable": true, "description": "Conta de integração que originou o pedido." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Rótulo amigável da conta de integração, no formato `IntegrationName - CompanyIntegrationName`." }, "SalesChannelName": { "type": "string", "nullable": true, "description": "Nome do canal de venda (`IntegrationName`)." }, "IntegrationName": { "type": "string", "nullable": true, "description": "Mesmo conteúdo de `SalesChannelName`. Mantido por compatibilidade com clientes antigos." }, "SalesChannelLogoUrl": { "type": "string", "nullable": true, "description": "URL do logo do canal." }, "IDSalesman": { "type": "integer", "format": "int64", "nullable": true, "description": "Vendedor (`IDUser`)." }, "Salesman": { "type": "string", "nullable": true, "description": "Vendedor, no formato `UserName - Login`." }, "IDCarrier": { "type": "integer", "format": "int64", "nullable": true, "description": "Transportadora (`IDSupplier`)." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social da transportadora." }, "IDCarrierType": { "type": "integer", "nullable": true, "description": "Tipo de transportadora (`IDCarrierType`)." }, "ManualLabel": { "type": "integer", "nullable": true, "description": "Indica se a transportadora emite etiqueta manual (`ManualLabel`)." }, "TrackingUrl": { "type": "string", "description": "URL pública do rastreio (`https://rastreioo.com.br/#/tracking//`)." }, "ShippingId": { "type": "string", "nullable": true, "description": "Código(s) de rastreio dos pacotes do pedido (CSV via `GROUP_CONCAT`)." }, "ShippingDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de envio do primeiro pacote (`ShippingDate`)." }, "ShippingEstimateDate": { "type": "string", "format": "date", "nullable": true, "description": "Data prevista de entrega ao cliente." }, "ShippingEstimateHandlingLimitDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data limite de expedição informada pelo canal (`ShippingEstimateHandlingLimitDate`). Usada principalmente para Mercado Livre." }, "ShippingAvailableLabelDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data em que a etiqueta do canal ficou disponível (`ShippingAvailableLabelDate`)." }, "HubOrderStatus": { "type": "string", "nullable": true, "description": "Descrição do status do pedido no canal de venda (`Description`)." }, "ShippingCity": { "type": "string", "nullable": true, "description": "Cidade de entrega." }, "ShippingState": { "type": "string", "nullable": true, "description": "UF de entrega." }, "ShippingPostalCode": { "type": "string", "nullable": true, "description": "CEP de entrega." }, "ShippingReceiverName": { "type": "string", "nullable": true, "description": "Nome do destinatário (pode diferir do cliente)." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Nome / razão social do cliente." }, "ConsumerCpfCnpj": { "type": "string", "nullable": true, "description": "Documento do cliente (CPF ou CNPJ)." }, "ConsumerEmail": { "type": "string", "nullable": true, "description": "E-mail do cliente." }, "IDConsumer": { "type": "integer", "format": "int64", "nullable": true, "description": "Código interno do cliente." }, "IDAddress": { "type": "integer", "format": "int64", "nullable": true, "description": "Endereço de entrega cadastrado (`IDAddress`)." }, "NfeNumber": { "type": "integer", "nullable": true, "description": "Número da NF principal." }, "NfeSerie": { "type": "integer", "nullable": true, "description": "Série da NF principal." }, "NfedhEmi": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de emissão da NF principal." }, "NfeChaveAcesso": { "type": "string", "nullable": true, "description": "Chave de acesso da NF principal (44 dígitos)." }, "NfePackages": { "type": "integer", "nullable": true, "description": "Quantidade de volumes informada na NF." }, "NfeNoPayment": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` indica NF emitida sem pagamento associado." }, "NfeComments": { "type": "string", "nullable": true, "description": "Observações da NF." }, "IDStatusInvoice": { "type": "integer", "description": "Status da NF: `0` Pendente, `1` Erro, `2` Enviada, `3` Emitida, `4` Processando, `5` Pendente Conciliação EPEC, `6` Erro Conciliação EPEC, `7` Cancelada, `8` Denegada, `9` Inutilizada." }, "StatusInvoice": { "type": "string", "description": "Descrição do status da NF principal. `Pendente` quando ainda não há NF." }, "Checked": { "type": "integer", "nullable": true, "description": "Marcação manual de conferido (`Checked`)." }, "ValueProduct": { "type": "number", "format": "double", "nullable": true, "description": "Soma dos `PriceSellingTotal` dos itens não gratificados." }, "ValueShipping": { "type": "number", "format": "double", "nullable": true, "description": "Valor do frete do pedido (`ValueShipping`)." }, "ValueOrder": { "type": "number", "format": "double", "nullable": true, "description": "Total do pedido: soma dos itens + `ValueShipping` + `NfeAccessoryExpenses`." }, "ValuePaid": { "type": "number", "format": "double", "nullable": true, "description": "Soma de `Value` do pedido (valor já recebido)." }, "ValueDiscount": { "type": "number", "format": "double", "nullable": true, "description": "Soma dos descontos por item (multiplicado pela quantidade)." }, "ProductCost": { "type": "number", "format": "double", "nullable": true, "description": "Custo total dos itens (`ValueCostTotal` agregado, ignorando embalagens e gratificações)." }, "QuantityProduct": { "type": "number", "format": "double", "description": "Soma das quantidades de itens do pedido." }, "QuantitySku": { "type": "integer", "description": "Quantidade de SKUs distintos do pedido." }, "IDPickingList": { "type": "integer", "format": "int64", "nullable": true, "description": "Picking-list atual do pedido." }, "IDOrdersCarrierCollectionList": { "type": "integer", "format": "int64", "nullable": true, "description": "Romaneio atual do pedido." }, "IDTypeOrderReturn": { "type": "integer", "format": "int64", "nullable": true, "description": "Motivo de devolução (`IDTypeOrderReturn`)." }, "TypeOrderReturn": { "type": "string", "nullable": true, "description": "Descrição do motivo de devolução." }, "IDTypeOrderResend": { "type": "integer", "format": "int64", "nullable": true, "description": "Motivo de reenvio (`IDTypeOrderResend`)." }, "TypeOrderResend": { "type": "string", "nullable": true, "description": "Descrição do motivo de reenvio." }, "OrdersSalesChannelLabelStatus": { "type": "string", "nullable": true, "description": "Status da etiqueta no canal (`Header`)." }, "OrderComments": { "type": "string", "nullable": true, "description": "Observações livres do pedido." }, "OrderPriority": { "type": "integer", "nullable": true, "description": "Prioridade manual do pedido (`OrderPriority`). Quando preenchido, vence a prioridade da configuração de picking-list na geração da picking." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "format": "int64", "nullable": true, "description": "Centro de distribuição vinculado ao pedido." }, "DistributionCenterName": { "type": "string", "nullable": true, "description": "Nome do CD." }, "IDStockKeepingUnitResupplyList": { "type": "string", "nullable": true, "description": "Listas de ressuprimento vinculadas ao pedido (CSV via `GROUP_CONCAT`)." }, "CompanyInvoiceTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia da empresa faturadora." }, "CompanyInvoiceAccountName": { "type": "string", "nullable": true, "description": "Conta (subdomínio) da empresa faturadora." }, "TypePayment": { "type": "string", "nullable": true, "description": "Descrição do tipo de pagamento da primeira parcela. Quando a parcela aceita mais de um tipo, vem como lista separada por vírgula." }, "Weight": { "type": "number", "format": "double", "nullable": true, "description": "Peso do pedido. Usa `PackageWeight` quando preenchido; senão, soma `SkuWeight * Quantity` dos itens." }, "Tags": { "type": "array", "items": { "type": "string" }, "description": "Tags do pedido (`Tag`). Devolvido como array." }, "Items": { "type": "array", "nullable": true, "description": "Presente apenas quando `SkuView=1`. Array de SKUs do pedido com nome, quantidade, valor unitário, kit, inconformidade e imagem principal.", "items": { "type": "object", "properties": { "IDSku": { "type": "integer", "format": "int64", "description": "SKU do item." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência do SKU." }, "SkuName": { "type": "string", "description": "Nome do SKU (concatenando o pai quando se trata de variação)." }, "SkuNameOnly": { "type": "string", "description": "Nome do SKU sem a parte herdada do pai." }, "Quantity": { "type": "number", "format": "double", "description": "Quantidade do item no pedido." }, "PriceSelling": { "type": "number", "format": "double", "description": "Preço unitário (calculado: `PriceSellingTotal / Quantity`, arredondado para 4 casas)." }, "PriceSellingTotal": { "type": "number", "format": "double", "description": "Valor total do item no pedido." }, "IDSkuKit": { "type": "integer", "format": "int64", "nullable": true, "description": "Quando o item faz parte de um kit, identifica o SKU do kit pai." }, "QuantityKit": { "type": "number", "format": "double", "nullable": true, "description": "Quantidade de kits que originou esta linha." }, "KitSkuName": { "type": "string", "nullable": true, "description": "Nome do SKU do kit pai." }, "KitIDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência do SKU do kit pai." }, "QuantityNonconformity": { "type": "number", "format": "double", "nullable": true, "description": "Quantidade do item em inconformidade (falta, vencido, avariado)." }, "IDTypeFulfillmentNonconformity": { "type": "integer", "nullable": true, "description": "Tipo de inconformidade (ver `TypeFulfillmentNonconformity`).", "enum": [ 1, 2, 4, 5, 6 ] }, "TypeFulfillmentNonconformity": { "type": "string", "nullable": true, "description": "Descrição da inconformidade." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do SKU." } } } } } }, "OrderStatusPutPayload": { "type": "object", "description": "Body do `PUT /orders/{idorder}/status`. Move o pedido para outro status — a tela **Outbound** usa este endpoint com `IDOrderStatusTo=90` (Cancelar).", "required": [ "IDOrderStatusTo" ], "properties": { "IDOrderStatusTo": { "type": "integer", "description": "Status destino (`IDStatusOrder`). A transição precisa estar cadastrada em `TypeStatusOrderRule` para a empresa. Valores comuns disparados por telas: `0` Aberto, `1` Fechado, `5` Segurar pedido, `9` Em espera, `13` Em tratativa, `90` Cancelado, `91` Extraviado, `92` Extraviado parcialmente, `94` Devolvido, `95` Em devolução, `97` Reversa finalizada." }, "StatusComment": { "type": "string", "description": "Comentário/motivo da transição. Obrigatório quando `CommentsRequired=1` para o destino (caso contrário, opcional). Quando informado, é gravado em `Comments`." }, "StatusDate": { "type": "string", "format": "date-time", "description": "Data e hora do evento. Quando omitido, usa o momento atual em America/Sao_Paulo. Não pode ser superior ao momento atual + 5 minutos." } } }, "InvoiceServiceFeedItem": { "type": "object", "description": "Item do feed de NFSe recebidas (`NfsEvents`). Cada linha é uma NFSe emitida por um fornecedor para o CNPJ da empresa, capturada da prefeitura via cron com autenticação por certificado digital.", "properties": { "IDNfsEvents": { "type": "integer", "format": "int64", "description": "Identificador único da NFSe no feed do idworks." }, "IDCompany": { "type": "integer", "format": "int64", "description": "Empresa que recebeu a nota (tomadora)." }, "IDCompanyInvoice": { "type": "integer", "format": "int64", "nullable": true, "description": "Faturador (filial) específica vinculada à nota." }, "AccountName": { "type": "string", "description": "Prefixo da conta da empresa tomadora." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Prefixo da conta do faturador." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Nome / razão social do faturador." }, "NfsNumber": { "type": "string", "description": "Número da NFSe." }, "NfsDate": { "type": "string", "format": "date-time", "description": "Data e hora de emissão pela prefeitura." }, "NfsChaveAcesso": { "type": "string", "nullable": true, "description": "Chave de acesso da NFSe." }, "NfsVerificationCode": { "type": "string", "nullable": true, "description": "Código de verificação." }, "NSU": { "type": "string", "nullable": true, "description": "Número Sequencial Único (controle do ambiente nacional)." }, "IDTypeStatusInvoiceService": { "type": "integer", "description": "Status numérico da nota." }, "StatusInvoiceService": { "type": "string", "description": "Label do status (Emitida, Cancelada, Substituída, Conferida, Pendente, Erro, etc.). Varia por município." }, "NfsCancelDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data do evento de cancelamento (quando `IDTypeStatusInvoiceService = 2`)." }, "CityCode": { "type": "integer", "description": "Código IBGE do município emissor. `0` indica Ambiente Nacional ADN." }, "CityName": { "type": "string", "description": "Nome do município emissor (`CityName`)." }, "State": { "type": "string", "description": "UF do município emissor (`State`)." }, "NfsServiceCode": { "type": "string", "description": "Código do serviço (CNAE municipal)." }, "ServiceDescription": { "type": "string", "description": "Descrição do código de serviço." }, "NfsSupplierCpfCnpj": { "type": "string", "description": "CPF/CNPJ do fornecedor (prestador)." }, "NfsSupplierNameCorporateName": { "type": "string", "description": "Nome / razão social do fornecedor." }, "NfsSupplierCityInscription": { "type": "string", "nullable": true, "description": "Inscrição municipal do fornecedor/prestador (quando informada na nota)." }, "IDSupplier": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do fornecedor no cadastro da empresa, quando há `Suppliers` com o mesmo CNPJ." }, "NfsValue": { "type": "number", "format": "double", "description": "Valor total da nota." }, "NfsISSAliquot": { "type": "number", "format": "double", "nullable": true, "description": "Alíquota de ISS aplicada (fração decimal — `0.05` = 5%)." }, "NfsISSValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor de ISS destacado na nota." }, "NfsISSRetained": { "type": "integer", "enum": [ 0, 1 ], "description": "Indica se o ISS foi retido pelo tomador. `1` retido (o tomador paga o ISS no lugar do prestador); `0` não retido." }, "NfsPisValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor de PIS destacado/retido na nota." }, "NfsCofinsValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor de COFINS destacado/retido na nota." }, "NfsIrValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor de IRRF retido pelo tomador." }, "NfsCsllValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor de CSLL retido pelo tomador." }, "NfsCreditValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor de crédito de ISS quando o município oferece programa de devolução parcial ao tomador (ex.: Nota Carioca)." }, "NfsComments": { "type": "string", "nullable": true, "description": "Discriminação / observações." }, "Show": { "type": "integer", "enum": [ 0, 1 ], "description": "Flag de soft-hide. Apenas `Show=1` aparecem." }, "Tags": { "type": "array", "items": { "type": "string" }, "description": "Tags atribuídas em `NfsEventsTag`." }, "XmlFile": { "type": "string", "format": "uri", "description": "URL pré-assinada para download do XML." }, "XmlDanfe": { "type": "string", "format": "uri", "description": "URL pré-assinada da DANFSE PDF." } } }, "CarrierInvoiceFeedItem": { "type": "object", "description": "Item retornado pelo `GET /cte`. Combina dados do CT-e (`CarrierInvoice`) com descrições resolvidas (`CtTpCte`, `CtCSit`, `CtToma`, `CttpServ`), eventual pedido vinculado (`Orders`, resolvido pela chave da NF-e citada), eventual conta a pagar associada (resolvida por fornecedor + `CTeNumber`), cálculos derivados (peso do pedido, diferenças de peso e frete) e URLs assinadas para XML/DANFE.", "properties": { "IDCarrierInvoice": { "type": "integer", "format": "int64", "description": "Código interno da linha do CT-e." }, "IDCompany": { "type": "integer", "format": "int64", "description": "Empresa dona da nota (`IDCompany`)." }, "IDCompanyInvoice": { "type": "integer", "format": "int64", "nullable": true, "description": "Empresa faturadora destinatária." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "CompanyInvoiceAccountName": { "type": "string", "nullable": true, "description": "Conta da empresa faturadora destinatária." }, "IDOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "Pedido vinculado (resolvido pela chave da NF-e citada no CT-e). `null` quando o CT-e referencia uma chave que não está no sistema." }, "Order": { "type": "string", "nullable": true, "description": "Número do pedido vinculado (`Order`)." }, "IDConsumer": { "type": "integer", "format": "int64", "nullable": true, "description": "Cliente do pedido vinculado." }, "ConsumerReceiverName": { "type": "string", "nullable": true, "description": "Nome do destinatário/cliente no pedido vinculado." }, "ConsumerCpfCnpj": { "type": "string", "nullable": true, "description": "Documento do cliente no pedido vinculado." }, "SupplierNameCorporateName": { "type": "string", "description": "Razão social da transportadora emissora do CT-e." }, "SupplierCpfCnpj": { "type": "string", "description": "CNPJ da transportadora." }, "IDCarrier": { "type": "integer", "format": "int64", "nullable": true, "description": "Transportadora cadastrada com integração ativa (`IDSupplier` via `TypeCarrier`)." }, "CTeDate": { "type": "string", "format": "date-time", "description": "Data e hora de emissão do CT-e." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que o CT-e foi inserido no banco do idworks." }, "CTeNumber": { "type": "integer", "description": "Número do CT-e." }, "CTeAccessKey": { "type": "string", "minLength": 44, "maxLength": 44, "description": "Chave de acesso do CT-e (44 dígitos)." }, "NSU": { "type": "integer", "nullable": true, "description": "Número Sequencial Único (`NSU`) atribuído pela SEFAZ." }, "CorreiosSRO": { "type": "string", "nullable": true, "description": "Código de rastreio dos Correios (`SRO`) — quando o CT-e é de transportador Correios e tem o campo preenchido." }, "CTeSit": { "type": "integer", "enum": [ 1, 3 ], "description": "Situação SEFAZ: `1` Uso autorizado, `3` CT-e Cancelada." }, "SitCteDescription": { "type": "string", "enum": [ "Uso autorizado", "CT-e Cancelada" ], "description": "Descrição amigável da situação." }, "CTeType": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ], "description": "Tipo: `0` Normal, `1` Complementar, `2` Anulação, `3` Substituição, `4` Fatura." }, "CtTpCteDescription": { "type": "string", "description": "Descrição amigável do tipo (`CT-e Normal`, `CT-e Complementar`, `Anulação`, `Substituição`, `Fatura`)." }, "CTeToma": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ], "description": "Tomador do frete: `0` Remetente, `1` Expedidor, `2` Recebedor, `3` Destinatário, `4` Outros." }, "CtTomaDescription": { "type": "string", "description": "Descrição amigável do tomador." }, "CTetpServ": { "type": "integer", "nullable": true, "description": "Código do tipo de serviço prestado (`CttpServ`)." }, "CttpServDescription": { "type": "string", "nullable": true, "description": "Descrição amigável do tipo de serviço." }, "InvoiceAccessKey": { "type": "string", "minLength": 44, "maxLength": 44, "description": "Chave de acesso da NF-e de produto vinculada (44 dígitos)." }, "InvoiceNumber": { "type": "integer", "nullable": true, "description": "Número da NF-e citada (posições 26 a 34 da chave de acesso `InvoiceAccessKey`)." }, "InvoiceSerie": { "type": "integer", "nullable": true, "description": "Série da NF-e citada (posições 23 a 25 da chave de acesso `InvoiceAccessKey`)." }, "Comments": { "type": "string", "nullable": true, "description": "Observações do CT-e (`Comments`)." }, "ShippingPostalCode": { "type": "string", "nullable": true, "description": "CEP do destinatário." }, "ShippingCity": { "type": "string", "nullable": true, "description": "Cidade do destinatário." }, "ShippingState": { "type": "string", "nullable": true, "description": "UF do destinatário." }, "WeightCharged": { "type": "number", "format": "double", "nullable": true, "description": "Peso cobrado pela transportadora no CT-e." }, "OrderWeight": { "type": "number", "format": "double", "nullable": true, "description": "Peso calculado do pedido (soma de peso × quantidade de cada item)." }, "WeightDifference": { "type": "number", "format": "double", "nullable": true, "description": "Diferença entre peso cobrado e peso do pedido (`WeightCharged - OrderWeight`)." }, "ValueShipping": { "type": "number", "format": "double", "nullable": true, "description": "Valor do frete (`ValueShipping`)." }, "ValueGrisInsurance": { "type": "number", "format": "double", "nullable": true, "description": "Valor de GRIS + seguro." }, "ValueICMS": { "type": "number", "format": "double", "nullable": true, "description": "ICMS do CT-e." }, "ValueISS": { "type": "number", "format": "double", "nullable": true, "description": "ISS do CT-e." }, "ValueTotalService": { "type": "number", "format": "double", "nullable": true, "description": "Valor total do serviço cobrado (frete + GRIS + ICMS + ISS + acessórios)." }, "ValueRate": { "type": "number", "format": "double", "nullable": true, "description": "Valor da tabela usado para gerar o CT-e." }, "OrderValueShipping": { "type": "number", "format": "double", "nullable": true, "description": "Valor do frete cobrado do cliente no pedido (`ValueShipping`)." }, "ValueShippingNet": { "type": "number", "format": "double", "nullable": true, "description": "Resultado financeiro: `OrderValueShipping - ValueTotalService`. Positivo = sobra; negativo = prejuízo." }, "ValueShippingAuction": { "type": "number", "format": "double", "nullable": true, "description": "Valor que o sistema simulou para a transportadora no momento do envio. `null` quando não há leilão de frete cadastrado." }, "ValueShippingAuctionNet": { "type": "number", "format": "double", "nullable": true, "description": "Diferença entre simulado e cobrado pela transportadora." }, "IDStatusShippingAuctionDif": { "type": "integer", "enum": [ 1, 2, 3 ], "nullable": true, "description": "Resultado da comparação simulado vs. cobrado: `1` simulado < cobrado, `2` simulado > cobrado, `3` empate. Só vem preenchido em modo `FreightConciliation=1`." }, "PriceSellingTotal": { "type": "number", "format": "double", "nullable": true, "description": "Valor total dos itens do pedido. Só vem preenchido em modo `FreightConciliation=1`." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int64", "nullable": true, "description": "Conta a pagar associada à transportadora (resolvida por `IDSupplier` + `DocumentNumber = CTeNumber`). `null` quando ainda não foi lançada." }, "XmlFile": { "type": "string", "format": "uri", "description": "URL assinada para baixar o XML do CT-e do S3." }, "XmlDanfe": { "type": "string", "format": "uri", "description": "URL assinada para visualizar a DANFE em PDF." } } }, "PurchaseFeedItem": { "type": "object", "description": "Item retornado pelo `GET /purchase/feed`. Combina dados de `NfEvents` com descrições resolvidas (`NfTpNf`, `NfCSit`, `NfTpEvent`), eventual recebimento criado (`IDPurchase`), eventual conta a pagar associada (`IDAccountPayableReceivable`, resolvida por fornecedor + número de documento), tags da linha (array agregado de `NfEventsTag`) e URLs assinadas para o XML e a DANFE.", "properties": { "IDNfEvents": { "type": "integer", "format": "int64", "description": "Código interno da linha do feed." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) a que a nota pertence." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Conta da empresa faturadora destinatária da nota." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social da empresa faturadora destinatária." }, "IDCompany": { "type": "integer", "format": "int64", "description": "Empresa dona da nota (`IDCompany`)." }, "IDCompanyInvoice": { "type": "integer", "format": "int64", "nullable": true, "description": "Empresa faturadora destinatária (quando há multi-empresa)." }, "SupplierNameCorporateName": { "type": "string", "description": "Razão social do fornecedor emitente da nota." }, "SupplierCpfCnpj": { "type": "string", "description": "CPF/CNPJ do fornecedor." }, "IDSupplier": { "type": "integer", "format": "int64", "nullable": true, "description": "Fornecedor cadastrado no idworks com este CNPJ (`IDSupplier`, ativo). Pode vir `null` se o fornecedor ainda não foi cadastrado." }, "NFeNumber": { "type": "integer", "description": "Número da NF-e." }, "NFeAccessKey": { "type": "string", "minLength": 44, "maxLength": 44, "description": "Chave de acesso da NF-e (44 dígitos)." }, "NFeDate": { "type": "string", "format": "date-time", "description": "Data e hora de emissão da NF-e." }, "NFeValue": { "type": "number", "format": "double", "description": "Valor total da NF-e (`NFeValue`)." }, "NFeTpNf": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo da operação informado no XML — `0` Entrada, `1` Saída." }, "NfTpNfDescription": { "type": "string", "enum": [ "Entrada", "Saída" ], "description": "Descrição amigável do tipo (`NfTpNfDescription`)." }, "NFeSit": { "type": "integer", "description": "Código da situação SEFAZ (`SitNFe`)." }, "SitNfeDescription": { "type": "string", "description": "Descrição da situação SEFAZ. Valores conhecidos: `Uso autorizado`, `Uso denegado`, `NF-e Cancelada`.", "enum": [ "Uso autorizado", "Uso denegado", "NF-e Cancelada" ] }, "NFeTpEvento": { "type": "integer", "nullable": true, "description": "Código do último evento registrado (`NfTpEvent`). Inclui manifestações do destinatário (`210200`/`210210`/`210220`/`210240`), eventos de transporte e eventos do próprio emitente (carta de correção, cancelamento)." }, "NfTpEventDescription": { "type": "string", "nullable": true, "description": "Descrição amigável do último evento." }, "IDPurchase": { "type": "integer", "format": "int64", "nullable": true, "description": "Recebimento criado a partir desta nota (`IDPurchase`). `null` quando ainda não foi criado." }, "IDAccountPayableReceivable": { "type": "integer", "format": "int64", "nullable": true, "description": "Conta a pagar associada à nota (resolvida por `IDSupplier` + `DocumentNumber = NFeNumber`). `null` quando ainda não há conta a pagar lançada." }, "XmlFile": { "type": "string", "format": "uri", "description": "URL assinada para baixar o XML do bucket S3. Formato: `https:////invoice/danfe?Folder=Inbound&Type=XML&Origin=Feed&token=&File=`." }, "XmlDanfe": { "type": "string", "format": "uri", "description": "URL assinada para visualizar a DANFE em PDF. Mesmo formato que `XmlFile`, com `Type=PDF`." }, "Tags": { "type": "array", "items": { "type": "string" }, "description": "Tags internas vinculadas à nota (`Tag`). Devolvido como array." } } }, "PurchaseItem": { "type": "object", "description": "Item de movimento de estoque vinculado ao recebimento (`StockKeepingUnitMovement`).", "properties": { "IDSkuMovement": { "type": "integer", "format": "int64", "description": "Identificador da linha de movimentação de estoque gerada para o item do recebimento (uma linha por SKU/lote no recebimento)." }, "IDSku": { "type": "integer", "format": "int64", "description": "Identificador do SKU recebido." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência interna do SKU." }, "SkuName": { "type": "string", "description": "Nome do SKU." }, "Quantity": { "type": "number", "format": "double", "description": "Quantidade do SKU recebida nesta linha." }, "ValueCostUnitPurchase": { "type": "number", "format": "double", "nullable": true, "description": "Custo unitário de compra (sem rateio de frete e impostos)." }, "ValueCostTotal": { "type": "number", "format": "double", "nullable": true, "description": "Custo total da linha (custo unitário × quantidade), já incluindo rateio de `ValueShipping`, descontos e tributos do item quando configurados na regra fiscal." }, "IDBatch": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do lote do SKU recebido (`IDBatchNumber`). Vazio quando o SKU não usa controle de lote." }, "Comments": { "type": "string", "nullable": true, "description": "Identificação do lote." }, "ManufacturingDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de fabricação do lote recebido, no formato `YYYY-MM-DD`. Obrigatória quando o SKU exige rastreabilidade." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de validade. `4000-01-01` indica ausência." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "format": "int64", "nullable": true, "description": "Armazém de destino do item recebido." }, "WarehouseName": { "type": "string", "nullable": true, "description": "Nome do armazém de destino." }, "IDStockKeepingUnitLocation": { "type": "integer", "format": "int64", "nullable": true, "description": "Endereço de armazenagem (rua/coluna/nível) sugerido para o item." }, "Address": { "type": "string", "nullable": true, "description": "Texto do endereço de armazenagem (`Floor-Street-Module-Column-Level` ou nome livre)." }, "NfeCFOP": { "type": "string", "nullable": true, "description": "CFOP do item no recebimento (4 dígitos). Quando informado, define a natureza fiscal da entrada." }, "NfeIcmsValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor do ICMS destacado para o item na NF-e de entrada." }, "NfeIcmsSTValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor do ICMS-ST (Substituição Tributária) destacado para o item." }, "NfeFcpSTValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor do FCP-ST (Fundo de Combate à Pobreza retido por ST) destacado para o item." }, "NfeIPIValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor do IPI destacado para o item." }, "NfePisValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor do PIS destacado para o item." }, "NfeCofinsValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor do COFINS destacado para o item." } } }, "PurchaseListItem": { "type": "object", "description": "Linha da lista de recebimentos retornada por `GET /purchase`.", "properties": { "IDPurchase": { "type": "integer", "format": "int64", "description": "Identificador do recebimento." }, "IDStatusPurchase": { "type": "integer", "description": "Status numérico (ver tabela na tag)." }, "StatusPurchase": { "type": "string", "description": "Descrição amigável do status do recebimento (`Aberto`, `Finalizado`, `Cancelada`, `Em conferência`, `Conferencia realizada`, `Ag. validação comercial`, `Ag. validação operacional`, `Recebimento autorizado`, `Recebimento recusado`, `Finalização recebimento autorizada`, `Ag. finalização comercial`, `Finalização recebimento recusada`, `Ag. finalização operacional`)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de criação." }, "CheckinTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data em que a mercadoria chegou no CD." }, "InvoiceFinishTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de finalização." }, "InvoiceFinishUser": { "type": "string", "nullable": true, "description": "Login do usuário que finalizou o recebimento. Vazio enquanto o recebimento não foi finalizado." }, "RecordUserCreated": { "type": "string", "nullable": true, "description": "Login do usuário que criou o recebimento." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do recebimento." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Subdomínio da filial faturadora (quando multi-empresa). Vazio quando o faturador é a própria empresa." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social da filial faturadora. Vazio quando o faturador é a própria empresa." }, "IDSupplier": { "type": "integer", "format": "int64", "description": "Identificador do fornecedor do recebimento." }, "SupplierNameCorporateName": { "type": "string", "description": "Razão social do fornecedor." }, "IDOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "Pedido de venda vinculado (devolução de cliente)." }, "Order": { "type": "string", "nullable": true, "description": "Código externo do pedido de venda vinculado." }, "IDBuyOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "Pedido de compra vinculado ao recebimento." }, "nNF": { "type": "string", "nullable": true, "description": "Número da NF-e." }, "chNFe": { "type": "string", "nullable": true, "description": "Chave de acesso (44 dígitos)." }, "dhEmi": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de emissão da NF." }, "TotalvNF": { "type": "number", "format": "double", "nullable": true, "description": "Valor total da NF importada (`vNF` do XML)." }, "ValueProductsTotal": { "type": "number", "format": "double", "nullable": true, "description": "Soma de `ValueCostTotal` dos itens do recebimento (custo total dos produtos)." }, "ValuePaymentTotal": { "type": "number", "format": "double", "nullable": true, "description": "Soma dos valores das contas a pagar vinculadas ao recebimento." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "format": "int64", "nullable": true, "description": "Centro de distribuição destino do recebimento." }, "DistributionCenterName": { "type": "string", "nullable": true, "description": "Nome do centro de distribuição." }, "WarehouseName": { "type": "string", "nullable": true, "description": "Nome do armazém quando o recebimento tem apenas um armazém envolvido." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres do recebimento." }, "StartTime": { "type": "string", "format": "date-time", "nullable": true, "description": "Data do agendamento (`StockKeepingUnitPurchaseSchedule`)." }, "StockKeepingUnitPurchaseScheduleStatus": { "type": "integer", "nullable": true, "description": "1=Recebido, 2=Agendado, 3=Atrasado, 4=Não agendado." }, "StockKeepingUnitPurchaseScheduleStatusDescription": { "type": "string", "nullable": true, "description": "Descrição amigável do status do agendamento amarrado (`Recebido`, `Agendado`, `Atrasado`, `Não agendado`). Vazio quando o recebimento não tem agendamento." }, "IDStockKeepingUnitPurchaseSchedule": { "type": "integer", "nullable": true, "description": "Identificador do agendamento de recebimento amarrado, quando houver." } } }, "PurchaseDetail": { "type": "object", "description": "Detalhe do recebimento — retornado por `GET /purchase/{id}` (sem `?ItemsInvoice=1`). Inclui cabeçalho, dados do XML, itens, pagamentos e — quando vinculado a pedido de compra — itens do pedido para conciliação.", "allOf": [ { "$ref": "#/components/schemas/PurchaseListItem" }, { "type": "object", "properties": { "Items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseItem" }, "description": "Itens (SKUs) do recebimento." }, "Payments": { "type": "array", "items": { "type": "object", "description": "Contas a pagar do recebimento (`AccountsPayableReceivable`)." }, "description": "Parcelas/pagamentos vinculados ao recebimento." }, "ItemsBuyOrder": { "type": "array", "nullable": true, "items": { "type": "object", "description": "Itens do pedido de compra vinculado, para conciliação." }, "description": "Itens do pedido de compra vinculado, para conciliação. `null` quando não há pedido de compra." }, "UrlFileXml": { "type": "string", "format": "uri", "nullable": true, "description": "URL pré-assinada para download do XML." }, "UrlFileDanfe": { "type": "string", "format": "uri", "nullable": true, "description": "URL pré-assinada da DANFE PDF." }, "natOp": { "type": "string", "nullable": true, "description": "Natureza da operação do XML." }, "ValueShipping": { "type": "number", "format": "double", "nullable": true, "description": "Valor do frete do recebimento em R$." }, "PurchaseCheckinApproved": { "type": "integer", "nullable": true, "enum": [ 0, 1 ], "description": "Estado de aprovação do checkin." }, "PurchaseReceiptApproved": { "type": "integer", "nullable": true, "enum": [ 0, 1 ], "description": "Estado de aprovação da finalização." } } } ] }, "PurchasePostPayload": { "type": "object", "required": [ "IDSupplier" ], "properties": { "IDSupplier": { "type": "integer", "format": "int64", "description": "Fornecedor." }, "IDOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "Pedido relacionado (devolução de cliente, por ex.)." }, "IDBuyOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "Pedido de compra vinculado." }, "IDCompanyInvoice": { "type": "integer", "format": "int64", "nullable": true, "description": "Filial faturadora. Default = empresa do token." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "format": "int64", "nullable": true, "description": "CD destino. Default = CD `Default=1` da empresa." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres do recebimento (texto). Aceita `null`/omitido." } } }, "PurchasePutPayload": { "type": "object", "description": "Body do PUT do recebimento. Campos editáveis variam conforme o status atual. `PurchaseCheckinApproved` e `PurchaseReceiptApproved` disparam transições de status com workflow de aprovação (exigem privilégios específicos).", "properties": { "IDSupplier": { "type": "integer", "format": "int64", "description": "Fornecedor do recebimento. Precisa pertencer à empresa autenticada." }, "IDOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "Pedido de venda vinculado ao recebimento (caso de devolução de cliente). Precisa pertencer à empresa." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres do recebimento." }, "IDStatusPurchase": { "type": "integer", "description": "Status alvo. Mudar para `0` (Aberto) em recebimento finalizado é uma reabertura — exige nenhuma venda dos produtos OU `InvoiceFinishTimestamp` há menos de 8 dias (`TotalDays < 8`)." }, "ValueShipping": { "type": "number", "format": "double", "description": "Frete — rateado proporcionalmente por `ValueCostTotal` em todos os movimentos." }, "IDBuyOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "Pedido de compra vinculado. Ao alterar, as contas a pagar do novo pedido de compra são marcadas com este `IDPurchase` e o status do pedido de compra passa para Aguardando recebimento (`1`)." }, "CheckinTimestamp": { "type": "string", "format": "date-time", "description": "Data em que a mercadoria chegou." }, "IDCompanyInvoice": { "type": "integer", "format": "int64", "nullable": true, "description": "Filial faturadora (em ambientes multi-empresa). Quando informado, precisa ser uma filial cadastrada em `CompanyMain` da empresa autenticada." }, "PurchaseCheckinApproved": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` aprova o checkin (status 5/6/8 → 7). `0` recusa (status 5/6 → 8). Exige privilégio Authorize Comercial ou Operational." }, "PurchaseReceiptApproved": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` aprova a finalização (status 10/12/11 → 9). `0` recusa (status 10/12 → 11). Exige privilégio Authorize Receipt Comercial ou Operational." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "format": "int64", "nullable": true, "description": "Centro de distribuição destino. Não pode ser alterado se já existem itens em um CD diferente do informado — remover os itens primeiro." }, "dhEmi": { "type": "string", "format": "date-time", "description": "Data de emissão da NF. Só editável quando XML não tem protocolo SEFAZ." }, "nNF": { "type": "string", "description": "Número da nota fiscal. Não pode existir outro recebimento com mesmo `nNF` para o mesmo fornecedor." }, "chNFe": { "type": "string", "description": "Chave de acesso da NF-e (44 dígitos). Não pode existir outro recebimento com a mesma chave." }, "natOp": { "type": "string", "description": "Natureza da operação descrita no XML." }, "NFeType": { "type": "integer", "description": "Tipo da NF-e: `0` Entrada, `1` Saída." }, "NFeFin": { "type": "integer", "description": "Finalidade da NF-e: `1` Normal, `2` Complementar, `3` Ajuste, `4` Devolução." } } }, "PurchaseSkuPostPayload": { "type": "object", "required": [ "IDSku", "Quantity", "IDStockKeepingUnitWarehouse" ], "properties": { "IDSku": { "type": "integer", "format": "int64", "description": "Identificador do SKU a entrar no estoque. Precisa pertencer à empresa, estar ativo (`IDStatusSku=1`) e ser de tipo comprável (`IDTypeSku` em `3`, `5`, `6` ou `7`)." }, "Quantity": { "type": "number", "format": "double", "description": "Quantidade. Precisa ser > 0." }, "ValueCostTotal": { "type": "number", "format": "double", "description": "Valor de custo total da linha (quantidade × custo unitário). Inclui frete rateado quando há `ValueShipping` no recebimento." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "format": "int64", "description": "Armazém destino. Precisa estar ativo e ser do mesmo CD do recebimento." }, "IDBatch": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do lote (`StockKeepingUnitBatch`). Quando vazio e o SKU exige rastreamento (`Batch=1`), o sistema cria um lote novo a partir do texto enviado em `Comments` e da `ManufacturingDate`." }, "IDStockKeepingUnitLocation": { "type": "integer", "format": "int64", "nullable": true, "description": "Endereço de armazenagem. Quando `DefaultLocationPurchase` está parametrizado para o CD, é forçado para esse endereço." }, "BestBeforeDate": { "type": "string", "format": "date", "description": "Data de validade. Default `4000-01-01`." }, "ManufacturingDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de fabricação do lote. Obrigatória quando o SKU tem `BatchRequired=1` ou rastreabilidade ativa. Precisa ser ≤ `BestBeforeDate`." }, "Comments": { "type": "string", "nullable": true, "description": "Lote (texto)." }, "NfeCFOP": { "type": "string", "nullable": true, "description": "CFOP do item neste recebimento (4 dígitos). Quando informado, precisa existir no catálogo nacional de CFOPs." } } }, "PurchaseCheckItem": { "type": "object", "required": [ "IDSku", "Quantity" ], "properties": { "IDSku": { "type": "integer", "format": "int64", "description": "Identificador do SKU conferido. Precisa pertencer ao recebimento (existir em `StockKeepingUnitMovement` do recebimento) ou ser SKU divergente (vai para o armazém de divergência do CD)." }, "Quantity": { "type": "number", "format": "double", "description": "Quantidade conferida fisicamente. Precisa ser > 0." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Default `4000-01-01`." }, "ManufacturingDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de fabricação do lote conferido. Quando o SKU exige rastreabilidade, é obrigatória e precisa ser ≤ `BestBeforeDate`." }, "BatchComments": { "type": "string", "nullable": true, "description": "Identificação textual do lote conferido (código do lote impresso no produto)." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres da conferência do item." }, "IDStockKeepingUnitPurchaseItemsCheckFile": { "type": "integer", "format": "int64", "nullable": true, "description": "Foto principal capturada via `/check/image?MainImg=1`." }, "IDStockKeepingUnitPurchaseItemsCheckFile1": { "type": "integer", "format": "int64", "nullable": true, "description": "Foto adicional 1 da etiqueta/produto (registrada via `POST /purchase/{idpurchase}/check/image`)." }, "IDStockKeepingUnitPurchaseItemsCheckFile2": { "type": "integer", "format": "int64", "nullable": true, "description": "Foto adicional 2 da etiqueta/produto." }, "IDStockKeepingUnitPurchaseItemsCheckFile3": { "type": "integer", "format": "int64", "nullable": true, "description": "Foto adicional 3 da etiqueta/produto." } } }, "PurchasePaymentPostPayload": { "type": "object", "required": [ "IDSupplier", "Value", "DateDue", "IDTypePayment", "IDTypeDocument", "IDTypeAccountPayble" ], "properties": { "IDSupplier": { "type": "integer", "format": "int64", "description": "Fornecedor do título a pagar. Em geral é o mesmo fornecedor do recebimento, mas pode ser diferente (ex.: empresa de frete pago à parte)." }, "Value": { "type": "number", "format": "double", "description": "Valor do título. Quando há retenções em `Taxes`, este é o líquido para o fornecedor." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento do título." }, "IDTypePayment": { "type": "integer", "format": "int64", "description": "Forma de pagamento (`TypePayment`). Precisa estar ativa para a empresa." }, "IDTypeDocument": { "type": "integer", "format": "int64", "description": "Tipo de documento (`TypeDocument`, ex.: Boleto, Duplicata, Nota Fiscal). Precisa estar ativo." }, "IDTypeAccountPayble": { "type": "integer", "format": "int64", "description": "Plano de contas." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data de emissão do documento. Quando vazio, herda da NF do recebimento na finalização." }, "DocumentNumber": { "type": "string", "nullable": true, "description": "Número do documento. Quando vazio, herda da NF do recebimento na finalização." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres do título." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência contábil (mês de referência do lançamento)." }, "BankSlipBarCode": { "type": "string", "nullable": true, "description": "Linha digitável ou código de barras do boleto. Quando preenchido, alimenta a leitura do boleto na conciliação bancária." }, "IDBankAccountForecast": { "type": "integer", "format": "int64", "nullable": true, "description": "Conta bancária prevista para a baixa. Precisa pertencer à empresa." }, "ValueDiscount": { "type": "number", "format": "double", "nullable": true, "description": "Valor de desconto previsto no título." }, "ValueInterest": { "type": "number", "format": "double", "nullable": true, "description": "Valor de juros previsto no título." }, "ValuePenalty": { "type": "number", "format": "double", "nullable": true, "description": "Valor de multa prevista no título." }, "Taxes": { "type": "array", "description": "Retenções fiscais. Cada item gera um título a pagar separado vinculado ao pagamento pai.", "items": { "type": "object", "required": [ "IDSupplier", "Value", "DateDue" ], "properties": { "IDSupplier": { "type": "integer", "format": "int64", "description": "Fornecedor da retenção (geralmente Receita Federal ou órgão equivalente)." }, "Value": { "type": "number", "format": "double", "description": "Valor da retenção fiscal. Gera um título a pagar separado vinculado ao título principal via `IDAccountPayableReceivableFather`." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento da guia da retenção (ex.: data limite de recolhimento do imposto retido)." } } } } } }, "PurchaseReceiptPayload": { "type": "array", "description": "Opcional. Lista dos itens efetivamente recebidos — um objeto por SKU (podendo repetir o SKU por lote/armazém). Quando o corpo é omitido, a lista é montada a partir da conferência salva.", "items": { "type": "object", "required": [ "IDSku", "Quantity" ], "properties": { "IDSku": { "type": "integer", "format": "int64", "description": "Identificador do SKU recebido. Precisa pertencer ao recebimento ou ser SKU divergente (roteado ao armazém de divergência do CD)." }, "Quantity": { "type": "number", "format": "double", "description": "Quantidade efetivamente recebida. Precisa ser > 0 — do contrário `[BadRequest] - Nenhum SKU pode ter quantidade menor ou igual a zero, verifique antes de finalizar`." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "format": "int64", "nullable": true, "description": "Armazém de destino do item recebido. Quando informado, precisa estar cadastrado e ativo; caso contrário `[BadRequest] - Armazém (IDStockKeepingUnitWarehouse) X não encontrado`." }, "IDStockKeepingUnitLocation": { "type": "integer", "format": "int64", "nullable": true, "description": "Endereço/localização de destino do item. Quando informado, precisa estar cadastrado e ativo; caso contrário `[BadRequest] - Endereço SKU X não encontrado`." }, "IDBatch": { "type": "integer", "format": "int64", "nullable": true, "description": "Lote de destino do item. Quando informado, precisa existir para o SKU; caso contrário `[BadRequest] - Lote (IDBatchNumber) X não encontrado para o sku: Y`." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de validade do lote. Default `4000-01-01`." }, "ManufacturingDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de fabricação do lote. Quando o SKU exige rastreabilidade, é obrigatória e precisa ser ≤ `BestBeforeDate`." }, "BatchComments": { "type": "string", "nullable": true, "description": "Identificação textual do lote recebido (código impresso no produto)." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres do item." } } } }, "HubSalesPolicyItem": { "type": "object", "description": "Mapeamento DE-PARA entre canal e política comercial interna.", "properties": { "IDHubSalesPolicy": { "type": "integer", "format": "int64", "description": "Identificador do mapeamento de política comercial." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Identificador da integração (canal): referência a `CompanyIntegration`." }, "CompanyIntegration": { "type": "string", "description": "Concatenação `{IntegrationName} - {CompanyIntegrationName}` para exibição." }, "CompanyIntegrationName": { "type": "string", "description": "Nome amigável da integração (canal) configurado pela empresa." }, "IntegrationName": { "type": "string", "description": "Nome do tipo de integração (Mercado Livre, Vtex, etc.)." }, "IDTypeCompanyIntegration": { "type": "integer", "description": "Tipo de integração. `10`=Mercado Livre, `23`=Vtex. Define quais campos têm comportamento especial." }, "IDSalesPolicyFrom": { "type": "string", "nullable": true, "description": "Código de política no canal (lado DE)." }, "IDSalesPolicyTo": { "type": "integer", "format": "int64", "description": "Identificador da política comercial interna (lado PARA): referência a `CompanySalesPolicy`." }, "CompanySalesPolicy": { "type": "string", "description": "Nome da política comercial interna." }, "ShippingFree": { "type": "integer", "nullable": true, "enum": [ 0, 1, null ], "description": "Filtro de frete grátis. `1`=Sim, `0`=Não, `null`=Ambos (ignorar filtro). Apenas para Mercado Livre; em outras integrações é forçado a `null`." }, "IDOrderType": { "type": "integer", "format": "int64", "nullable": true, "description": "Tipo de pedido (referência a `TypeOrder`)." }, "TypeOrder": { "type": "string", "nullable": true, "description": "Descrição do tipo de pedido." }, "AccountName": { "type": "string", "description": "Identificador da empresa proprietária do mapeamento." } } }, "HubSalesPolicyPayload": { "type": "object", "required": [ "IDCompanyIntegration", "IDSalesPolicyTo" ], "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal de venda) à qual o mapeamento se aplica." }, "IDSalesPolicyTo": { "type": "integer", "format": "int64", "description": "Política comercial interna (lado PARA)." }, "IDSalesPolicyFrom": { "type": "string", "nullable": true, "description": "Código de política no canal. **Obrigatório quando `IDTypeCompanyIntegration = 23` (Vtex)**." }, "ShippingFree": { "type": "integer", "nullable": true, "enum": [ 0, 1 ], "description": "Filtro de frete grátis (`1`=Sim, `0`=Não). Aceito apenas para Mercado Livre (`IDTypeCompanyIntegration = 10`). Forçado a `null` no servidor em qualquer outra integração." }, "IDOrderType": { "type": "integer", "format": "int64", "nullable": true, "description": "Tipo de pedido associado (filtro adicional)." } } }, "PaymentHubItem": { "type": "object", "description": "Mapeamento DE-PARA — Hub Pagamento.", "properties": { "IDHubPagamento": { "type": "integer", "format": "int64", "description": "Identificador do mapeamento de forma de pagamento." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal) à qual o mapeamento se aplica." }, "CompanyIntegration": { "type": "string", "description": "Concatenação `{IntegrationName} - {CompanyIntegrationName}`." }, "CompanyIntegrationName": { "type": "string", "description": "Nome amigável da integração configurado pela empresa." }, "IntegrationName": { "type": "string", "description": "Nome do tipo de integração (ex.: `Mercado Livre`, `Magalu`, `Shopee`)." }, "IDTypeCompanyIntegration": { "type": "integer", "description": "Tipo da integração (`IDTypeCompanyIntegration`)." }, "IDPaymentFrom": { "type": "string", "nullable": true, "description": "Código de forma de pagamento usado pelo canal (string). Em integrações cujo tipo NÃO é 23, 24, 34, 45 ou 53, na edição (PUT) o sistema preenche automaticamente este campo com o `IDSalesChannel` da integração quando o body envia vazio." }, "IDPaymentTo": { "type": "integer", "format": "int64", "description": "Tipo de pagamento interno (referência a `TypePayment`)." }, "AccountName": { "type": "string", "description": "Identificador da empresa proprietária do mapeamento." } } }, "PaymentHubPayload": { "type": "object", "required": [ "IDCompanyIntegration", "IDPaymentTo" ], "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal) à qual o mapeamento se aplica." }, "IDPaymentFrom": { "type": "string", "nullable": true, "description": "Código de forma de pagamento usado pelo canal (string). Em integrações cujo tipo NÃO é 23, 24, 34, 45 ou 53, na edição (PUT) o sistema preenche automaticamente este campo com o `IDSalesChannel` da integração quando o body envia vazio." }, "IDPaymentTo": { "type": "integer", "format": "int64", "description": "Tipo de pagamento interno (referência a `TypePayment`)." }, "Antifraud": { "type": "integer", "nullable": true, "description": "Indicador de antifraude do pagamento." } } }, "BrandHubItem": { "type": "object", "description": "Mapeamento DE-PARA — Hub Marcas.", "properties": { "IDHubMarcas": { "type": "integer", "format": "int64", "description": "Identificador do mapeamento de marca." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal) à qual o mapeamento se aplica." }, "CompanyIntegration": { "type": "string", "description": "Concatenação `{IntegrationName} - {CompanyIntegrationName}`." }, "CompanyIntegrationName": { "type": "string", "description": "Nome amigável da integração configurado pela empresa." }, "IntegrationName": { "type": "string", "description": "Nome do tipo de integração (ex.: `Mercado Livre`, `Magalu`, `Shopee`)." }, "IDTypeCompanyIntegration": { "type": "integer", "description": "Tipo da integração." }, "IDBrandFrom": { "type": "string", "nullable": true, "description": "Código de marca usado pelo canal (string)." }, "IDBrandTo": { "type": "integer", "format": "int64", "description": "Marca interna (referência a `StockKeepingUnitBrand`)." }, "AccountName": { "type": "string", "description": "Identificador da empresa proprietária do mapeamento." } } }, "BrandHubPayload": { "type": "object", "required": [ "IDCompanyIntegration", "IDBrandTo" ], "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal) à qual o mapeamento se aplica." }, "IDBrandFrom": { "type": "string", "nullable": true, "description": "Código de marca usado pelo canal (string)." }, "IDBrandTo": { "type": "integer", "format": "int64", "description": "Marca interna (referência a `StockKeepingUnitBrand`)." } } }, "CategoryHubItem": { "type": "object", "description": "Mapeamento DE-PARA — Hub Categorias.", "properties": { "IDHubCategorias": { "type": "integer", "format": "int64", "description": "Identificador do mapeamento de categoria." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal) à qual o mapeamento se aplica." }, "CompanyIntegration": { "type": "string", "description": "Concatenação `{IntegrationName} - {CompanyIntegrationName}`." }, "CompanyIntegrationName": { "type": "string", "description": "Nome amigável da integração configurado pela empresa." }, "IntegrationName": { "type": "string", "description": "Nome do tipo de integração." }, "IDTypeCompanyIntegration": { "type": "integer", "description": "Tipo da integração." }, "IDCategoryFrom": { "type": "string", "nullable": true, "description": "Código de categoria usado pelo canal (string)." }, "IDCategoryTo": { "type": "integer", "format": "int64", "description": "Categoria interna (referência a `StockKeepingUnitCategory`)." }, "AccountName": { "type": "string", "description": "Identificador da empresa proprietária do mapeamento." }, "CategoryFromTree": { "type": "string", "nullable": true, "description": "Árvore completa da categoria no canal (ex.: 'Eletrônicos > TV > Smart TV')." } } }, "CategoryHubPayload": { "type": "object", "required": [ "IDCompanyIntegration", "IDCategoryTo" ], "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal) à qual o mapeamento se aplica." }, "IDCategoryFrom": { "type": "string", "nullable": true, "description": "Código de categoria usado pelo canal (string)." }, "IDCategoryTo": { "type": "integer", "format": "int64", "description": "Categoria interna (referência a `StockKeepingUnitCategory`)." }, "CategoryFromTree": { "type": "string", "nullable": true, "description": "Árvore completa da categoria no canal (ex.: 'Eletrônicos > TV > Smart TV')." } } }, "WarehouseHubItem": { "type": "object", "description": "Mapeamento DE-PARA — Hub Estoque.", "properties": { "IDHubEstoque": { "type": "integer", "format": "int64", "description": "Identificador do mapeamento de armazém." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal) à qual o mapeamento se aplica." }, "CompanyIntegration": { "type": "string", "description": "Concatenação `{IntegrationName} - {CompanyIntegrationName}`." }, "CompanyIntegrationName": { "type": "string", "description": "Nome amigável da integração configurado pela empresa." }, "IntegrationName": { "type": "string", "description": "Nome do tipo de integração." }, "IDTypeCompanyIntegration": { "type": "integer", "description": "Tipo da integração." }, "IDStockKeepingUnitWarehouseFrom": { "type": "string", "nullable": true, "description": "Código de armazém usado pelo canal (string). **Obrigatório**." }, "IDStockKeepingUnitWarehouseTo": { "type": "integer", "format": "int64", "description": "Armazém interno (referência a `StockKeepingUnitWarehouse`, apenas ativos)." }, "AccountName": { "type": "string", "description": "Identificador da empresa proprietária do mapeamento." }, "IDOrderType": { "type": "integer", "format": "int64", "description": "Tipo de pedido (referência a `TypeOrder`). Obrigatório." }, "IDStatusOrder": { "type": "integer", "nullable": true, "description": "Status final opcional (apenas onde `ChangeOnCreate = 1`)." }, "WarehouseName": { "type": "string", "nullable": true, "description": "Nome do armazém interno mapeado (WarehouseName). Nulo quando não há armazém vinculado." }, "Status": { "type": "integer", "nullable": true, "enum": [ 0, 1 ], "description": "Indicador de armazém ativo: 1 = ativo, 0 = inativo. Refere-se ao armazém interno mapeado; não confundir com tipo de armazém." }, "TypeOrder": { "type": "string", "nullable": true, "description": "Descrição do tipo de pedido associado (TypeOrder). Nulo quando não definido." }, "StatusOrder": { "type": "string", "nullable": true, "description": "Nome do status do pedido aplicado no recebimento deste mapeamento (StatusOrder). Nulo quando não definido." }, "StatusColorCode": { "type": "string", "nullable": true, "description": "Código hexadecimal da cor do status do pedido (ex.: #18AA8C), para exibição. Nulo quando o status do pedido não está definido." } } }, "WarehouseHubPayload": { "type": "object", "required": [ "IDCompanyIntegration", "IDStockKeepingUnitWarehouseFrom", "IDStockKeepingUnitWarehouseTo", "IDOrderType" ], "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal) à qual o mapeamento se aplica." }, "IDStockKeepingUnitWarehouseFrom": { "type": "string", "nullable": true, "description": "Código de armazém usado pelo canal (string). **Obrigatório**." }, "IDStockKeepingUnitWarehouseTo": { "type": "integer", "format": "int64", "description": "Armazém interno (referência a `StockKeepingUnitWarehouse`, apenas ativos)." }, "IDOrderType": { "type": "integer", "format": "int64", "description": "Tipo de pedido aplicado quando o pedido entrar por este armazém." }, "IDStatusOrder": { "type": "integer", "nullable": true, "description": "Status final aplicado ao pedido na criação. Aceita apenas valores de `TypeStatusOrder` configurados com `ChangeOnCreate = 1`." } } }, "HubMessageItem": { "type": "object", "description": "Template de mensagem (`HubProductQuestionAnswerTemplate`).", "properties": { "IDHubProductQuestionAnswerTemplate": { "type": "integer", "format": "int64", "description": "Identificador do modelo de mensagem." }, "AccountName": { "type": "string", "description": "Identificador da empresa proprietária do modelo." }, "AnswerType": { "type": "integer", "enum": [ 1, 2 ], "description": "`1` Resposta pré-cadastrada, `2` Mensagem automática." }, "AnswerTypeDescription": { "type": "string", "description": "Descrição amigável do tipo de resposta (`Resposta pré-cadastrada` ou `Mensagem automática`)." }, "Title": { "type": "string", "nullable": true, "description": "Identificador da mensagem. Obrigatório quando `AnswerType=2`." }, "Answer": { "type": "string", "description": "Texto da mensagem com variáveis dinâmicas (`{{Nickname}}` etc.)." } } }, "HubMessagePayload": { "type": "object", "required": [ "AnswerType", "Answer" ], "properties": { "AnswerTemplate": { "type": "string", "description": "Texto do template de resposta." }, "AnswerTitle": { "type": "string", "nullable": true, "description": "Título do template de resposta." }, "AnswerType": { "type": "integer", "enum": [ 1, 2 ], "description": "Tipo de modelo. `1` Resposta pré-cadastrada (selecionada manualmente ao responder), `2` Mensagem automática (disparada por gatilho do canal)." } } }, "HubQuestionAnswerItem": { "type": "object", "description": "Pergunta do comprador sobre um anúncio do canal (`HubProductQuestionAnswer`).", "properties": { "IDHubProductQuestionAnswer": { "type": "integer", "format": "int64", "description": "Identificador interno da pergunta/resposta." }, "AccountName": { "type": "string", "description": "Identificador da empresa que recebeu a pergunta." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal) em que o anúncio está publicado." }, "CompanyIntegration": { "type": "string", "description": "Concatenação `{IntegrationName} - {CompanyIntegrationName}` para exibição." }, "IDHubProduct": { "type": "integer", "format": "int64", "description": "Identificador interno do anúncio (`IDHubProduct`) a que a pergunta se refere." }, "ProductName": { "type": "string", "description": "Nome do anúncio no momento da pergunta." }, "AdvertisementCode": { "type": "string", "description": "Código do anúncio no canal." }, "ReferenceCode": { "type": "string", "nullable": true, "description": "Código de referência do produto (SKU/EAN cadastrado)." }, "Question": { "type": "string", "description": "Texto da pergunta feita pelo comprador no canal." }, "Answer": { "type": "string", "nullable": true, "description": "Texto da resposta enviada. `null` enquanto a pergunta não tiver sido respondida." }, "Nickname": { "type": "string", "nullable": true, "description": "Apelido do comprador no canal." }, "QuestionTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora em que a pergunta foi feita pelo comprador." }, "AnswerTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora em que a resposta foi enviada. `null` enquanto não respondida." }, "IDTypeHubProductQuestionAnswerStatus": { "type": "integer", "enum": [ 1, 2, 3, 4, 7 ], "description": "Status da pergunta no canal: `1` Não respondido, `2` Respondido, `3` Nunca respondido, `4` Em análise, `7` Banido." }, "AdvertisementUrl": { "type": "string", "format": "uri", "nullable": true, "description": "URL pública do anúncio no canal." } } }, "HubOrderItem": { "type": "object", "description": "Linha do staging de Pedidos Integrados — pacote/pedido bruto vindo do canal. **Os nomes de campo abaixo são exatamente os emitidos pelo sistema** (`orderHubList` / `orderHubGet`), iguais aos nomes dos campos de `HubOrder` e entidades correlatas.", "properties": { "IDIntegration": { "type": "integer", "format": "int64", "description": "Identificador único da linha de staging (`IDIntegration`)." }, "AccountName": { "type": "string", "description": "Identificador da empresa dona do pedido." }, "IDCompany": { "type": "integer", "format": "int64", "description": "Empresa dona da integração (vinculo `IDCompany`). Presente em `orderHubGet`." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal) de onde o pedido veio." }, "CompanyIntegrationName": { "type": "string", "description": "Nome interno da integração (instância do canal na empresa)." }, "IntegrationName": { "type": "string", "description": "Nome do tipo de integração (ex.: `Meli`, `VTEX`, `Shopify`)." }, "IntegrationLogoUrl": { "type": "string", "nullable": true, "description": "URL do logo do tipo de integração (presente em `orderHubGet`)." }, "CompanyIntegration": { "type": "string", "description": "Concatenação `{IntegrationName} - {CompanyIntegrationName}` para exibição (montada apenas em `orderHubGet`)." }, "IDTypeCompanyIntegration": { "type": "integer", "description": "Tipo da integração (`IDTypeCompanyIntegration`)." }, "IDSalesChannel": { "type": "integer", "nullable": true, "description": "Identificador do canal de vendas (`IDSalesChannel`)." }, "SalesChannelName": { "type": "string", "description": "Nome do canal de vendas (alias de `IntegrationName`)." }, "OrderId": { "type": "string", "description": "Pedido origem (código no canal). Em alguns canais é o ID do pacote — vide `PackId`." }, "PackId": { "type": "string", "nullable": true, "description": "ID do pacote no canal (alguns canais agrupam vários pedidos)." }, "IDOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador do pedido idworks após criação. `null` enquanto não criado." }, "Order": { "type": "string", "nullable": true, "description": "Número do pedido idworks (`Order`). `null` enquanto o pedido idworks não tiver sido criado." }, "Status": { "type": "string", "description": "Status do pedido no canal (string crua devolvida pela integração)." }, "HubOrderStatus": { "type": "string", "nullable": true, "description": "Descrição amigável do status do canal (`Description`)." }, "IDStatusOrder": { "type": "integer", "nullable": true, "description": "Status do pedido idworks (`IDStatusOrder`). `null` enquanto o pedido não tiver sido criado." }, "StatusOrder": { "type": "string", "nullable": true, "description": "Descrição textual do status do pedido idworks (vazio enquanto não criado)." }, "IDStatusInvoice": { "type": "integer", "nullable": true, "description": "Status da NF (`IDStatusInvoice` quando `Main=1`)." }, "StatusInvoice": { "type": "string", "description": "Descrição textual do status da NF. `Pendente` quando ainda não foi emitida." }, "CreateOrder": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando o status do canal permite criar o pedido idworks; `0` caso contrário (`CreateOrder`)." }, "CreateOrderDescription": { "type": "string", "description": "`Sim`/`Não` correspondente ao `CreateOrder` (lookup em `TypeYesNo`)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora em que a linha de staging foi gravada no idworks." }, "CreationTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora do pedido no canal (`CreationTimestamp`)." }, "ConsumerFirstName": { "type": "string", "nullable": true, "description": "Primeiro nome do comprador retornado pelo canal." }, "ConsumerEmail": { "type": "string", "nullable": true, "description": "E-mail do comprador retornado pelo canal (frequentemente mascarado pela plataforma de origem)." }, "ConsumerDocument": { "type": "string", "nullable": true, "description": "CPF/CNPJ do comprador retornado pelo canal." }, "QuantityItems": { "type": "integer", "description": "Quantidade total de itens no pacote (soma das quantidades de `HubOrderProduct`)." }, "QuantityPayments": { "type": "integer", "description": "Número de registros de pagamento associados ao pacote." }, "TotalItemsValue": { "type": "number", "format": "double", "description": "Soma do valor dos itens (quantidade × preço de venda de cada item), sem frete/desconto/juros." }, "TotalDiscountValue": { "type": "number", "format": "double", "nullable": true, "description": "Desconto total aplicado ao pacote pelo canal." }, "TotalShippingValue": { "type": "number", "format": "double", "nullable": true, "description": "Valor de frete cobrado do comprador no canal." }, "TotalInterestValue": { "type": "number", "format": "double", "nullable": true, "description": "Acréscimo (juros/taxa) cobrado do comprador no canal — comum em parcelamento sem cartão." }, "TotalOrderValue": { "type": "number", "format": "double", "description": "Valor total do pacote (itens − descontos + frete + juros)." }, "IDWarehouseHub": { "type": "integer", "nullable": true, "description": "Identificador do armazém-hub destino (resolve a partir de `IDWarehouseHub` do primeiro item)." }, "Origin": { "type": "string", "nullable": true, "description": "Origem do registro (campo cru `Origin` — geralmente o nome do consumidor do webhook que gerou a linha)." }, "ShippingId": { "type": "string", "nullable": true, "description": "Código de rastreio quando aplicável." }, "ShippingCourierId": { "type": "string", "nullable": true, "description": "Identificador da transportadora no canal (`ShippingCourierId`)." }, "Coupon": { "type": "string", "nullable": true, "description": "Código do cupom de desconto aplicado no canal, quando houver." }, "UtmCampaign": { "type": "string", "nullable": true, "description": "Parâmetro `utm_campaign` capturado do checkout do canal." }, "UtmMedium": { "type": "string", "nullable": true, "description": "Parâmetro `utm_medium` capturado do checkout do canal." }, "UtmSource": { "type": "string", "nullable": true, "description": "Parâmetro `utm_source` capturado do checkout do canal." }, "UtmiCampaign": { "type": "string", "nullable": true, "description": "Parâmetro `utmi_campaign` capturado do checkout do canal (variante interna do canal)." }, "UtmiPage": { "type": "string", "nullable": true, "description": "Parâmetro `utmi_page` capturado do checkout do canal." }, "UtmiPart": { "type": "string", "nullable": true, "description": "Parâmetro `utmi_part` capturado do checkout do canal." }, "ShippingEstimateDate": { "type": "string", "format": "date", "nullable": true, "description": "Data estimada de entrega prometida ao comprador no canal." }, "ShippingEstimateHandlingLimitDate": { "type": "string", "format": "date", "nullable": true, "description": "Data limite que o canal estabelece para o pacote ser despachado." }, "SalesChannelOrderLink": { "type": "string", "format": "uri", "nullable": true, "description": "URL do pedido no canal de venda. Montado apenas para alguns tipos de integração (VTEX, Mercado Livre, SkyHub, Olist)." }, "SKUs": { "type": "array", "description": "Itens do pacote (`HubOrderProduct`). Cada item traz `IDSku, IDSkuHub, ProductDetail, IDSkuCompany, SkuName, Quantity, PriceSelling, IDWarehouseHub, IDProductHub, ValueDiscount, IDIntegrationProducts, IDHubProduct`.", "items": { "type": "object" } }, "Payments": { "type": "array", "description": "Pagamentos do pacote (`HubOrderPayment`). Cada item traz `Acquirer, Connector, Installments, PaymentSystem, PaymentSystemName, TransactionIdentifier, InterestValue, Value`.", "items": { "type": "object" } }, "Messages": { "type": "array", "description": "Histórico de mensagens trocadas com o comprador (presente apenas em `orderHubGet`).", "items": { "type": "object" } }, "Claims": { "type": "array", "description": "Reclamações abertas no canal (presente apenas em `orderHubGet`).", "items": { "type": "object" } }, "ClaimsMessages": { "type": "array", "description": "Mensagens vinculadas às reclamações (presente apenas em `orderHubGet`).", "items": { "type": "object" } } } }, "HubOrderPostPayload": { "type": "object", "required": [ "IDCompanyIntegration", "OrderFrom" ], "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal) de onde o pedido será buscado." }, "OrderFrom": { "type": "string", "description": "Código do pedido no canal (origem)." }, "ShippingId": { "type": "string", "nullable": true, "description": "ID de remessa — usado apenas para Mercado Livre OnSite (`IDTypeCompanyIntegration=1`)." } } }, "HubProductSizeChartRowAttribute": { "type": "object", "description": "Cada atributo de medida de uma linha da grade — por exemplo `BR_SIZE = M`, ou `WAIST_CIRCUMFERENCE_FROM = 72` com `Unit = cm`.", "properties": { "IDHubProductSizeChartRow": { "type": "integer", "format": "int64", "description": "Identificador interno do atributo." }, "IDHubProductSizeChart": { "type": "integer", "format": "int64", "description": "Grade de tamanho a que o atributo pertence." }, "FieldId": { "type": "string", "description": "Identificador técnico do campo de medida (ex.: `BR_SIZE`, `WAIST_CIRCUMFERENCE_FROM`). Os valores aceitos saem do catálogo do canal correspondente." }, "FieldName": { "type": "string", "description": "Nome legível do campo de medida exibido na grade." }, "FieldValue": { "type": "string", "description": "Valor da medida (ex.: `M`, `72`, `40-42`)." }, "Unit": { "type": "string", "nullable": true, "description": "Unidade de medida quando aplicável (ex.: `cm`, `kg`)." } } }, "HubProductSizeChartRow": { "type": "object", "description": "Linha (tamanho) da grade. Reúne todos os atributos de medida que descrevem aquele tamanho.", "properties": { "RowId": { "type": "string", "description": "Código único do tamanho dentro da grade (ex.: `1`, `S`, `38`). Não pode se repetir na mesma grade." }, "Attributes": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSizeChartRowAttribute" }, "description": "Lista de atributos de medida da linha." } } }, "HubProductSizeChartItem": { "type": "object", "description": "Resumo de uma grade de tamanho mapeada à integração.", "properties": { "IDHubProductSizeChart": { "type": "integer", "format": "int64", "description": "Identificador da grade de tamanho." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração à qual a grade pertence." }, "ExternalId": { "type": "string", "nullable": true, "description": "Identificador externo da grade no canal. Preenchido após sincronização bem-sucedida." }, "SizeChartName": { "type": "string", "description": "Nome amigável da grade (ex.: `Camisetas masculinas adulto`)." }, "TypeMeasure": { "type": "string", "description": "Tipo de medida da grade — ver lista de tipos em `TypeHubProductSizeChartTypeMeasure` (ex.: `BR_SIZE`, `CLOTHING_MEASURE`, `MIXED_MEASURE`)." }, "TypeMeasureDescription": { "type": "string", "description": "Descrição amigável do tipo de medida (ex.: `Medidas da peça`)." }, "Gender": { "type": "string", "nullable": true, "description": "Gênero a que a grade se aplica (ex.: `Masculino`, `Feminino`, `Unissex`)." }, "GenderId": { "type": "string", "nullable": true, "description": "Identificador técnico do gênero usado pelo canal." }, "CatalogDomain": { "type": "string", "nullable": true, "description": "Domínio de catálogo no canal (ex.: `MLB-FOOTWEAR`). Determina quais campos de medida estão disponíveis." }, "CatalogDomainName": { "type": "string", "nullable": true, "description": "Nome amigável do domínio de catálogo." }, "SizeChartStatus": { "type": "integer", "description": "Status da grade. `1` ativa · `2` pendente de sincronização." }, "CompanyIntegration": { "type": "string", "description": "Nome composto da integração (ex.: `Mercado Livre - Loja Principal`)." }, "CompanyIntegrationName": { "type": "string", "description": "Nome amigável da integração." }, "IntegrationLogoUrl": { "type": "string", "nullable": true, "description": "URL do logotipo do canal." }, "AccountName": { "type": "string", "description": "Identificador da empresa." } } }, "HubProductSizeChartDetail": { "allOf": [ { "$ref": "#/components/schemas/HubProductSizeChartItem" }, { "type": "object", "properties": { "HubProductSizeChartRow": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSizeChartRow" }, "description": "Linhas (tamanhos) que compõem a grade, com todos os atributos de medida." } } } ] }, "HubProductSizeChartCreate": { "type": "object", "required": [ "IDCompanyIntegration", "SizeChartName", "TypeMeasure" ], "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração à qual a grade será vinculada." }, "SizeChartName": { "type": "string", "description": "Nome amigável da grade." }, "TypeMeasure": { "type": "string", "description": "Tipo de medida — ver `TypeHubProductSizeChartTypeMeasure` (ex.: `MIXED_MEASURE`, `BR_SIZE`)." }, "Gender": { "type": "string", "nullable": true, "description": "Gênero da grade." }, "GenderId": { "type": "string", "nullable": true, "description": "Identificador técnico do gênero no canal." }, "CatalogDomain": { "type": "string", "nullable": true, "description": "Domínio de catálogo no canal (ex.: `MLB-FOOTWEAR`)." }, "HubProductSizeChartRow": { "type": "array", "description": "Linhas (tamanhos) da grade. Cada linha tem um `RowId` único e os atributos de medida que descrevem aquele tamanho.", "items": { "type": "object", "required": [ "RowId" ], "properties": { "RowId": { "type": "string", "description": "Código único do tamanho na grade." }, "Attributes": { "type": "array", "items": { "type": "object", "required": [ "FieldId", "FieldValue" ], "properties": { "FieldId": { "type": "string", "description": "Identificador técnico do campo de medida." }, "FieldName": { "type": "string", "description": "Nome legível do campo." }, "FieldValue": { "type": "string", "description": "Valor da medida." }, "Unit": { "type": "string", "nullable": true, "description": "Unidade da medida quando aplicável." } } }, "description": "Atributos de medida que descrevem o tamanho da linha (`FieldId`, `FieldValue`, opcionalmente `FieldName` e `Unit`)." } } } } } }, "HubProductSizeChartUpdate": { "type": "object", "description": "Apenas o nome e o tipo de medida podem ser alterados depois de criada a grade. Outros campos são imutáveis.", "properties": { "SizeChartName": { "type": "string", "description": "Novo nome da grade." }, "TypeMeasure": { "type": "string", "description": "Novo tipo de medida. **Não pode** ser alterado se a grade já foi sincronizada com o canal (existe `ExternalId`)." } } }, "HubProductSizeChartRowPayload": { "type": "object", "required": [ "RowId" ], "description": "Payload para adicionar uma nova linha (tamanho) à grade. `RowId` deve ser único dentro da grade. Atributos com `FieldId`+`FieldValue` já existentes nessa grade são rejeitados.", "properties": { "RowId": { "type": "string", "description": "Código único do tamanho." }, "Attributes": { "type": "array", "items": { "type": "object", "required": [ "FieldId", "FieldValue" ], "properties": { "FieldId": { "type": "string", "description": "Identificador técnico do campo de medida no canal (ex.: `BR_SIZE`)." }, "FieldName": { "type": "string", "description": "Nome legível do campo de medida exibido na grade." }, "FieldValue": { "type": "string", "description": "Valor da medida (ex.: `M`, `72`, `40-42`)." }, "Unit": { "type": "string", "nullable": true, "description": "Unidade de medida quando aplicável (ex.: `cm`, `kg`)." } } }, "description": "Atributos de medida da linha (cada um identifica uma característica do tamanho — ex.: `BR_SIZE`, `WAIST_CIRCUMFERENCE_FROM`)." } } }, "HubProductSizeChartRowUpdatePayload": { "type": "object", "description": "Payload para atualizar (upsert) atributos de uma linha existente. Combinações `FieldId` já existentes são atualizadas; novas são inseridas.", "properties": { "Attributes": { "type": "array", "items": { "type": "object", "required": [ "FieldId", "FieldValue" ], "properties": { "FieldId": { "type": "string", "description": "Identificador técnico do campo de medida no canal." }, "FieldName": { "type": "string", "description": "Nome legível do campo de medida." }, "FieldValue": { "type": "string", "description": "Novo valor da medida." }, "Unit": { "type": "string", "nullable": true, "description": "Unidade de medida quando aplicável." } } }, "description": "Atributos de medida a inserir ou atualizar — combinações `FieldId` já existentes são atualizadas; novas são adicionadas." } } }, "HubProductPromotionItem": { "type": "object", "description": "Resumo de uma promoção do hub vinculada à empresa autenticada. O conjunto de campos varia conforme o tipo da promoção e seu estágio de sincronização com o canal.", "properties": { "IDHubProductPromotion": { "type": "integer", "format": "int64", "description": "Identificador interno da promoção." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (canal) à qual a promoção pertence." }, "CompanyIntegration": { "type": "string", "description": "Nome composto da integração (ex.: `Mercado Livre - Loja Principal`)." }, "CompanyIntegrationName": { "type": "string", "description": "Nome amigável da integração configurado pela empresa." }, "IDTypeCompanyIntegration": { "type": "integer", "description": "Tipo da integração." }, "IntegrationLogoUrl": { "type": "string", "nullable": true, "description": "URL do logotipo do canal — usado pela tela para identificar visualmente a origem da promoção." }, "PromotionId": { "type": "string", "nullable": true, "description": "Identificador da promoção no canal externo." }, "PromotionName": { "type": "string", "nullable": true, "description": "Nome da promoção. Para `Campanha vendedor` é limitado a 25 caracteres." }, "IDTypeHubProductPromotion": { "type": "integer", "description": "Tipo de promoção. Consulte `/type/hub/product/promotion/type` para a lista completa." }, "TypeHubProductPromotionDescription": { "type": "string", "description": "Descrição amigável do tipo (ex.: `Tradicional`, `Campanha vendedor`, `Oferta relâmpago`)." }, "TypeHubProductPromotionId": { "type": "string", "description": "Identificador técnico do tipo no canal (ex.: `DEAL`, `SELLER_CAMPAIGN`, `LIGHTNING`)." }, "IDTypeHubProductPromotionStatus": { "type": "integer", "description": "Status. `1` Ativo · `2` Iniciado · `3` Programada · `4` Candidato · `5` Finalizada · `6` Ativação pendente · `7` Exclusão pendente · `8` Excluido.", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "TypeHubProductPromotionStatus": { "type": "string", "description": "Descrição amigável do status." }, "DateFrom": { "type": "string", "format": "date", "nullable": true, "description": "Início da vigência da promoção." }, "DateTo": { "type": "string", "format": "date", "nullable": true, "description": "Fim da vigência da promoção." }, "DateDeadline": { "type": "string", "format": "date", "nullable": true, "description": "Data limite para o vendedor aderir (campanhas com candidatura). Após essa data não é mais possível incluir itens." }, "SellerPercent": { "type": "number", "nullable": true, "description": "Percentual de desconto aplicado pelo vendedor (entre `0.10` e `0.70` para Campanha vendedor)." }, "IntegrationPercent": { "type": "number", "nullable": true, "description": "Percentual de co-participação assumido pelo canal." }, "IntegrationStatus": { "type": "integer", "description": "Estado da última sincronização. `0` Erro · `1` Sucesso · `2` Pendente." }, "IntegrationStatusName": { "type": "string", "nullable": true, "description": "Descrição do status de integração." }, "IntegrationErrorDescription": { "type": "string", "nullable": true, "description": "Mensagem de erro retornada pelo canal na última tentativa de sincronização." }, "HubProductPromotionItemCount": { "type": "integer", "description": "Quantidade de anúncios incluídos na promoção." }, "AccountName": { "type": "string", "description": "Identificador da empresa proprietária da promoção." }, "SellerCreate": { "type": "integer", "description": "`1` quando o vendedor pode criar este tipo de promoção localmente; `0` quando a promoção é gerada no canal e apenas recebida no idworks. **Não retornado pelo `GET /hub/product/promotion` (listagem)** — disponível apenas no GET de detalhe, no POST/PUT/DELETE de item e em endpoints que fazem o JOIN com `TypeHubProductPromotion`." } } }, "HubProductPromotionAdvertisement": { "type": "object", "description": "Anúncio incluído em uma promoção. Os campos preenchidos variam conforme o tipo da promoção (preço fixo, intervalo permitido, quantidade, etc.).", "properties": { "IDHubProductPromotionItem": { "type": "integer", "format": "int64", "description": "Identificador interno do item da promoção." }, "IDProductHub": { "type": "string", "description": "Identificador do anúncio no canal (ex.: `MLB123456789`)." }, "IDHubProduct": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador interno do anúncio quando há vínculo com cadastro idworks." }, "HubProductName": { "type": "string", "nullable": true, "description": "Nome do anúncio." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do anúncio." }, "SellingPrice": { "type": "number", "nullable": true, "description": "Preço promocional aplicado ao anúncio." }, "OriginalPrice": { "type": "number", "nullable": true, "description": "Preço original do anúncio no canal antes da promoção." }, "EffectiveDiscountPercent": { "type": "string", "nullable": true, "description": "Desconto efetivo calculado (`1 - SellingPrice / OriginalPrice`), com 4 casas decimais." }, "DateFrom": { "type": "string", "format": "date-time", "nullable": true, "description": "Início da vigência do anúncio dentro da promoção (pode ser diferente do `DateFrom` da promoção em tipos que permitem janela por anúncio)." }, "DateTo": { "type": "string", "format": "date-time", "nullable": true, "description": "Fim da vigência do anúncio dentro da promoção." }, "SellerPercent": { "type": "number", "nullable": true, "description": "Percentual de desconto efetivo do anúncio." }, "IntegrationPercent": { "type": "number", "nullable": true, "description": "Percentual de co-participação assumido pelo canal no anúncio." }, "MaximumDiscountedPrice": { "type": "number", "nullable": true, "description": "Preço mínimo permitido pelo canal para o anúncio (somente leitura)." }, "MinimumDiscountedPrice": { "type": "number", "nullable": true, "description": "Preço máximo permitido pelo canal para o anúncio (somente leitura)." }, "SetQuantityAvailable": { "type": "integer", "nullable": true, "description": "Quantidade reservada para a promoção (oferta relâmpago)." }, "MaximumQuantityAvailable": { "type": "integer", "nullable": true, "description": "Quantidade máxima permitida pelo canal." }, "MinimumQuantityAvailable": { "type": "integer", "nullable": true, "description": "Quantidade mínima exigida pelo canal." }, "IDTypeHubProductPromotionStatus": { "type": "integer", "description": "Status do anúncio na promoção. Consulte `/type/hub/product/promotion/status` para a lista completa.", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "TypeHubProductPromotionStatus": { "type": "string", "description": "Descrição amigável do status." }, "IntegrationStatus": { "type": "integer", "description": "`0` Erro · `1` Sucesso · `2` Pendente." }, "IntegrationStatusName": { "type": "string", "description": "Descrição do estado da última sincronização do anúncio com o canal." }, "IntegrationErrorDescription": { "type": "string", "nullable": true, "description": "Mensagem de erro retornada pelo canal na última tentativa de sincronização do anúncio." } } }, "HubProductPromotionDetail": { "allOf": [ { "$ref": "#/components/schemas/HubProductPromotionItem" }, { "type": "object", "properties": { "HasNextPageItems": { "type": "integer", "description": "`1` quando existem mais anúncios além desta página de 5000 itens; `0` quando o último lote foi entregue." }, "HubProductPromotionItems": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductPromotionAdvertisement" }, "description": "Anúncios incluídos na promoção (paginados em blocos de 5000)." } } } ] }, "HubProductPromotionCreate": { "type": "object", "required": [ "IDCompanyIntegration", "IDTypeHubProductPromotion" ], "description": "Criação manual de promoção. **Só funciona** para tipos com `SellerCreate = 1` no catálogo (atualmente `Desconto individual` e `Campanha vendedor`). As demais promoções são recebidas do canal e não podem ser criadas pela API.", "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração à qual a promoção será vinculada." }, "IDTypeHubProductPromotion": { "type": "integer", "description": "Tipo de promoção. Aceita apenas tipos com `SellerCreate = 1`." }, "PromotionName": { "type": "string", "description": "Nome da promoção. Para `Campanha vendedor` (tipo 8) é obrigatório e limitado a 25 caracteres. Acentuação é normalizada (removida)." }, "DateFrom": { "type": "string", "format": "date-time", "nullable": true, "description": "Início da vigência. Obrigatório para `Campanha vendedor`. Diferença para `DateTo` não pode passar de 31 dias." }, "DateTo": { "type": "string", "format": "date-time", "nullable": true, "description": "Fim da vigência. Obrigatório para `Campanha vendedor` e precisa ser maior que hoje." }, "SellerPercent": { "type": "number", "nullable": true, "description": "Percentual de desconto. Para `Campanha vendedor` precisa ficar entre `0.10` e `0.70` (10% a 70%)." } } }, "HubProductPromotionUpdate": { "type": "object", "description": "Atualização da promoção. **Só permitida** para tipos com `SellerCreate = 1`. Para `Campanha vendedor` em status `Iniciado` a `DateFrom` não pode ser alterada.", "properties": { "PromotionName": { "type": "string", "description": "Novo nome da promoção. Para `Campanha vendedor` mantém o limite de 25 caracteres." }, "DateFrom": { "type": "string", "format": "date-time", "nullable": true, "description": "Novo início da vigência. Em `Campanha vendedor` em status `Iniciado` (`IDTypeHubProductPromotionStatus=2`), não pode ser alterado." }, "DateTo": { "type": "string", "format": "date-time", "nullable": true, "description": "Novo fim da vigência. Diferença para `DateFrom` não pode passar de 31 dias." }, "SellerPercent": { "type": "number", "nullable": true, "description": "Novo percentual de desconto. Para `Campanha vendedor` precisa ficar entre `0.10` e `0.70` (10% a 70%)." } } }, "HubProductPromotionItemCreate": { "type": "object", "required": [ "IDProductHub" ], "description": "Inclusão de anúncio em promoção. Só funciona quando a promoção é `SellerCreate = 1`. Para `Desconto individual` (tipo 3) o sistema consulta o canal para validar que o desconto está entre 5% e 80% do preço anunciado.", "properties": { "IDProductHub": { "type": "string", "description": "Identificador do anúncio no canal (ex.: `MLB123456789`)." }, "IDSkuHub": { "type": "string", "nullable": true, "description": "Identificador do SKU/variação quando aplicável. Quando não informado, usa o próprio `IDProductHub`." }, "SellingPrice": { "type": "number", "description": "Preço promocional do anúncio." }, "DateFrom": { "type": "string", "format": "date-time", "nullable": true, "description": "Início. Obrigatório para `Desconto individual`." }, "DateTo": { "type": "string", "format": "date-time", "nullable": true, "description": "Fim. Obrigatório para `Desconto individual`. Intervalo máximo de 31 dias." } } }, "HubProductPromotionItemUpdate": { "type": "object", "description": "Atualização de anúncio em promoção. Os campos aceitos e as validações dependem do tipo da promoção: preço, intervalo de datas, quantidade. Ajustes fora dos limites mínimos e máximos definidos pelo canal são rejeitados.", "properties": { "SellingPrice": { "type": "number", "nullable": true, "description": "Preço promocional. Respeita `MinimumDiscountedPrice`/`MaximumDiscountedPrice` quando informados pelo canal." }, "SetQuantityAvailable": { "type": "integer", "nullable": true, "description": "Quantidade reservada (aplicável a `Oferta relâmpago`). Respeita `MinimumQuantityAvailable`/`MaximumQuantityAvailable`." }, "DateFrom": { "type": "string", "format": "date-time", "nullable": true, "description": "Novo início para o anúncio dentro da promoção. Obrigatório para `Desconto individual`." }, "DateTo": { "type": "string", "format": "date-time", "nullable": true, "description": "Novo fim para o anúncio dentro da promoção. Obrigatório para `Desconto individual`. Intervalo máximo de 31 dias em relação a `DateFrom`." } } }, "TypeHubProductPromotionStatusItem": { "type": "object", "properties": { "IDTypeHubProductPromotionStatus": { "type": "string", "description": "Identificador do status." }, "TypeHubProductPromotionStatus": { "type": "string", "description": "Descrição amigável." } } }, "TypeHubProductPromotionItem": { "type": "object", "properties": { "IDTypeHubProductPromotion": { "type": "string", "description": "Identificador do tipo." }, "TypeHubProductPromotionDescription": { "type": "string", "description": "Descrição amigável (ex.: `Tradicional`, `Campanha vendedor`, `Oferta do dia`)." } } }, "SkuCollectionItem": { "type": "object", "description": "Coleção de produtos (`StockKeepingUnitCollection` + `AccountName` da conta dona).", "properties": { "IDStockKeepingUnitCollection": { "type": "integer", "description": "Identificador da coleção." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa." }, "StockKeepingUnitCollectionName": { "type": "string", "maxLength": 100, "description": "Nome da coleção." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação." } } }, "SkuCollectionCreate": { "type": "object", "description": "Corpo do POST/PUT de Coleção.", "required": [ "StockKeepingUnitCollectionName" ], "properties": { "StockKeepingUnitCollectionName": { "type": "string", "maxLength": 100, "description": "Nome da coleção." } } }, "SkuGroupItem": { "type": "object", "description": "Grupo de SKUs equivalentes (`StockKeepingUnitGroup` + `AccountName`).", "properties": { "IDStockKeepingUnitGroup": { "type": "integer", "description": "Identificador do grupo de SKUs." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa." }, "SkuGroupName": { "type": "string", "maxLength": 100, "description": "Nome do grupo de SKUs." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação." } } }, "SkuGroupCreate": { "type": "object", "description": "Corpo do POST/PUT de Grupo SKU.", "required": [ "SkuGroupName" ], "properties": { "SkuGroupName": { "type": "string", "maxLength": 100, "description": "Nome do grupo." } } }, "SkuSimilarCodeItem": { "type": "object", "description": "Linha da lista de códigos similares (`skuSimilarCodeList`). Vem da `StockKeepingUnitSimilarCode` com `SkuGroupName` (do grupo) e `AccountName` (da empresa) já resolvidos.", "properties": { "IDStockKeepingUnitSimilarCode": { "type": "integer", "description": "Id do código similar." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de cadastro do código." }, "IDStockKeepingUnitGroup": { "type": "integer", "description": "Id do grupo SKU a que o código pertence." }, "SkuSimilarCode": { "type": "string", "maxLength": 45, "description": "Código alternativo." }, "SkuSimilarCodeTag": { "type": "string", "maxLength": 45, "nullable": true, "description": "Tag opcional para agrupar códigos por origem (ex.: nome do fornecedor, do canal)." }, "SkuGroupName": { "type": "string", "maxLength": 100, "description": "Nome do grupo SKU." }, "AccountName": { "type": "string", "description": "Identificador da conta da empresa proprietária do grupo." } } }, "SkuSimilarCodeCreate": { "type": "object", "description": "Corpo do POST/PUT de Código Similar.", "required": [ "IDStockKeepingUnitGroup", "SkuSimilarCode" ], "properties": { "IDStockKeepingUnitGroup": { "type": "integer", "description": "Id do grupo SKU. Precisa pertencer à empresa autenticada." }, "SkuSimilarCode": { "type": "string", "maxLength": 45, "description": "Código alternativo. Único por grupo." }, "SkuSimilarCodeTag": { "type": "string", "maxLength": 45, "nullable": true, "description": "Tag opcional para agrupar códigos por origem." } } }, "SkuSimilarCodeTagItem": { "type": "object", "description": "Linha da lista de tags (`skuSimilarCodeTagList`). Apenas as tags em uso, distintas, ordenadas alfabeticamente.", "properties": { "SkuSimilarCodeTag": { "type": "string", "maxLength": 45, "description": "Valor da tag." }, "AccountName": { "type": "string", "description": "Identificador da conta da empresa que usa a tag." } } }, "TypeSkuVariationItem": { "type": "object", "description": "Linha da lista de variações (`typeSkuVariationList`). `IDTypeProductVariation` vem como texto (CAST). O campo `TypeProductVariation` é o array com os valores da grade da variação.", "properties": { "IDTypeProductVariation": { "type": "string", "description": "Identificador da variação (devolvido como texto pelo `CAST` no SQL)." }, "ProductVariation": { "type": "string", "maxLength": 45, "description": "Nome da variação (ex.: `Tamanho`, `Cor`)." }, "ProductVariationOrder": { "type": "integer", "description": "Ordem de exibição (única por empresa)." }, "IDTypeProductVariationType": { "type": "integer", "description": "Id do tipo padrão (`TypeProductVariationType`)." }, "TypeProductVariationType": { "type": "string", "description": "Nome do tipo padrão (Cor, Tamanho, Voltagem…)." }, "AccountName": { "type": "string", "description": "Subdomínio (identificador) da empresa dona da variação." }, "TypeProductVariationValueList": { "type": "string", "nullable": true, "description": "Lista de valores da grade concatenada por vírgula (`GROUP_CONCAT`); `null` quando a variação não tem grade." }, "TypeProductVariation": { "type": "array", "description": "Valores da grade da variação.", "items": { "type": "object", "properties": { "IDTypeProductVariationValue": { "type": "string", "description": "Identificador do valor da grade (devolvido como texto pelo `CAST` no SQL)." }, "TypeProductVariationValue": { "type": "string", "maxLength": 100, "description": "Nome do valor da grade (ex.: `P`, `M`, `Azul`)." }, "ProductVariationValueOrder": { "type": "integer", "description": "Ordem de exibição do valor dentro da grade (única por variação)." } } } } } }, "TypeSkuVariationDetail": { "type": "object", "description": "Detalhe de uma variação com sua grade (`typeSkuVariationGet`). Devolvido também por POST/PUT/DELETE de valores da grade.", "properties": { "IDTypeProductVariation": { "type": "string", "description": "Identificador da variação (devolvido como texto pelo `CAST` no SQL)." }, "ProductVariation": { "type": "string", "maxLength": 45, "description": "Nome da variação." }, "IDTypeProductVariationType": { "type": "integer", "description": "Identificador do tipo padrão (Cor, Tamanho, Voltagem…)." }, "TypeProductVariationType": { "type": "string", "description": "Nome do tipo padrão." }, "TypeProductVariationValues": { "type": "array", "description": "Valores da grade da variação.", "items": { "type": "object", "properties": { "IDTypeProductVariationValue": { "type": "integer", "description": "Identificador do valor da grade." }, "TypeProductVariationValue": { "type": "string", "maxLength": 100, "description": "Nome do valor da grade." }, "ProductVariationValueOrder": { "type": "integer", "description": "Ordem de exibição do valor dentro da grade (única por variação)." } } } } } }, "TypeSkuVariationCreate": { "type": "object", "description": "Corpo do POST/PUT de variação. No PUT todos os campos são opcionais (atualização parcial). `ProductVariationOrder` é único por empresa; se omitido no POST, recebe `MAX+1`.", "required": [ "ProductVariation", "IDTypeProductVariationType" ], "properties": { "ProductVariation": { "type": "string", "maxLength": 45, "description": "Nome da variação." }, "IDTypeProductVariationType": { "type": "integer", "description": "Id do tipo padrão (de `GET /type/sku/variation/type`)." }, "ProductVariationOrder": { "type": "integer", "description": "Ordem de exibição (única por empresa)." } } }, "TypeProductVariationTypeItem": { "type": "object", "description": "Tipo padrão de variação do sistema (`TypeProductVariationType`). Lista fixa, igual para todas as empresas.", "properties": { "IDTypeProductVariationType": { "type": "string", "description": "Identificador do tipo padrão (Cor, Tamanho, Voltagem…). Tabela fixa do sistema — igual para todas as empresas." }, "TypeProductVariationType": { "type": "string", "maxLength": 45, "description": "Nome do tipo padrão." } } }, "GradeValueItem": { "type": "object", "description": "Valor da grade de uma variação (`skuVariationValueList`).", "properties": { "IDTypeProductVariationValue": { "type": "integer", "description": "Identificador do valor da grade." }, "TypeProductVariationValue": { "type": "string", "maxLength": 100, "description": "Nome do valor (ex.: `P`, `Azul`, `220V`)." }, "ProductVariationValueOrder": { "type": "integer", "description": "Ordem de exibição do valor dentro da grade (única por variação)." } } }, "GradeValueCreate": { "type": "object", "description": "Corpo do POST/PUT de valor da grade. `ProductVariationValueOrder` é único por variação.", "required": [ "TypeProductVariationValue" ], "properties": { "TypeProductVariationValue": { "type": "string", "maxLength": 100, "description": "Nome do valor da grade (ex.: Azul, M)." }, "ProductVariationValueOrder": { "type": "integer", "description": "Ordem do valor dentro da grade (única por variação)." } } }, "CategoryTreeNode": { "type": "object", "description": "Nó da árvore de categorias (resposta de `categoryList` com `Type=Tree`).", "properties": { "IDCategory": { "type": "integer", "description": "Id da categoria." }, "Name": { "type": "string", "description": "Nome da categoria." }, "IDCategoryFather": { "type": "integer", "description": "Id da categoria pai; `0` quando a categoria é de topo." }, "IsActive": { "type": "integer", "description": "Indica se a categoria está ativa (`1`) ou inativa (`0`)." }, "AccountName": { "type": "string", "description": "Conta dona da categoria." }, "Children": { "type": "array", "description": "Subcategorias deste nó (mesma estrutura, recursiva).", "items": { "type": "object", "description": "(referência recursiva a `CategoryTreeNode` — não expandida)" } } } }, "CategoryDetail": { "type": "object", "description": "Dados completos de uma categoria (resposta de `categoryGet`).", "properties": { "IDCategory": { "type": "integer", "description": "Id da categoria." }, "Name": { "type": "string", "description": "Nome da categoria." }, "Description": { "type": "string", "nullable": true, "description": "Descrição da categoria." }, "Title": { "type": "string", "nullable": true, "description": "Título usado na loja virtual." }, "Keywords": { "type": "string", "nullable": true, "description": "Palavras-chave usadas na loja virtual." }, "IDCategoryFather": { "type": "integer", "nullable": true, "description": "Id da categoria pai; `null` quando é de topo." }, "CategoryFather": { "type": "string", "nullable": true, "description": "Nome da categoria pai; `null` quando é de topo." }, "IsActive": { "type": "integer", "description": "Indica se a categoria está ativa (`1`) ou inativa (`0`)." }, "ShowInStoreFront": { "type": "integer", "nullable": true, "description": "Exibir a categoria na loja virtual (`1`/`0`)." }, "ShowBrandFilter": { "type": "integer", "nullable": true, "description": "Exibir o filtro de marca na categoria (`1`/`0`)." }, "ActiveStoreFrontLink": { "type": "integer", "nullable": true, "description": "Ativar o link da categoria na loja virtual (`1`/`0`)." }, "Score": { "type": "integer", "nullable": true, "description": "Peso/ordenação da categoria." }, "AccountName": { "type": "string", "description": "Conta dona da categoria." } } }, "CategoryCreate": { "type": "object", "required": [ "Name" ], "description": "Corpo para criação de categoria.", "properties": { "Name": { "type": "string", "description": "Nome da categoria." }, "Description": { "type": "string", "nullable": true, "description": "Descrição; assume `Name` quando omitida." }, "Title": { "type": "string", "nullable": true, "description": "Título na loja virtual; assume `Name` quando omitido." }, "Keywords": { "type": "string", "nullable": true, "description": "Palavras-chave na loja virtual; assume `Name` quando omitidas." }, "IDCategoryFather": { "type": "integer", "nullable": true, "description": "Id da categoria pai; `null`/ausente cria categoria de topo." }, "ShowInStoreFront": { "type": "integer", "description": "Exibir na loja virtual (`1`/`0`); padrão `1`." }, "ShowBrandFilter": { "type": "integer", "description": "Exibir filtro de marca (`1`/`0`); padrão `1`." }, "ActiveStoreFrontLink": { "type": "integer", "description": "Ativar link na loja virtual (`1`/`0`); padrão `1`." }, "Score": { "type": "integer", "nullable": true, "description": "Peso/ordenação da categoria." }, "IsActive": { "type": "integer", "description": "Categoria ativa (`1`) ou inativa (`0`)." } } }, "CategoryUpdate": { "type": "object", "description": "Corpo para atualização parcial de categoria. Envie apenas os campos a alterar.", "properties": { "Name": { "type": "string", "description": "Nome da categoria." }, "Description": { "type": "string", "description": "Descrição da categoria." }, "Title": { "type": "string", "description": "Título na loja virtual." }, "Keywords": { "type": "string", "description": "Palavras-chave na loja virtual." }, "IDCategoryFather": { "type": "integer", "nullable": true, "description": "Id da categoria pai; `null` move a categoria para o topo." }, "ShowInStoreFront": { "type": "integer", "description": "Exibir na loja virtual (`1`/`0`)." }, "ShowBrandFilter": { "type": "integer", "description": "Exibir filtro de marca (`1`/`0`)." }, "ActiveStoreFrontLink": { "type": "integer", "description": "Ativar link na loja virtual (`1`/`0`)." }, "Score": { "type": "integer", "description": "Peso/ordenação da categoria." }, "IsActive": { "type": "integer", "description": "Categoria ativa (`1`) ou inativa (`0`)." } } }, "SpecFieldItem": { "type": "object", "description": "Especificação (campo) de uma categoria, com seus valores (resposta de `skuSpecificationFieldList`).", "properties": { "IDStockKeepingUnitSpecificationsFieldId": { "type": "integer", "description": "Id da especificação." }, "FieldName": { "type": "string", "description": "Nome do campo." }, "FieldType": { "type": "string", "description": "Nome do tipo de preenchimento (texto, número, lista…)." }, "IDStockKeepingUnitSpecificationsFieldTypes": { "type": "integer", "description": "Id do tipo de preenchimento." }, "IDCategory": { "type": "integer", "description": "Id da categoria dona da especificação (pode ser uma ancestral, quando herdada)." }, "CategoryName": { "type": "string", "description": "Nome da categoria dona da especificação." }, "IDFieldExternal": { "type": "string", "nullable": true, "description": "Código externo do campo." }, "IsRequired": { "type": "integer", "nullable": true, "description": "Preenchimento obrigatório no produto (`1`/`0`)." }, "IsActive": { "type": "integer", "nullable": true, "description": "Campo ativo (`1`/`0`)." }, "IsFilter": { "type": "integer", "nullable": true, "description": "Usar como filtro na loja (`1`/`0`)." }, "IsOnProductDetails": { "type": "integer", "nullable": true, "description": "Exibir nos detalhes do produto (`1`/`0`)." }, "IsTopMenuLinkActive": { "type": "integer", "nullable": true, "description": "Ativar link no menu superior (`1`/`0`)." }, "IsSideMenuLinkActive": { "type": "integer", "nullable": true, "description": "Ativar link no menu lateral (`1`/`0`)." }, "FieldPosition": { "type": "integer", "nullable": true, "description": "Ordem de exibição do campo." }, "FieldValue": { "type": "array", "description": "Valores cadastrados para o campo (vazio para campos sem lista de opções).", "items": { "type": "object", "properties": { "Value": { "type": "string", "description": "Texto do valor." }, "IDStockKeepingUnitSpecificationsFieldValues": { "type": "integer", "description": "Id do valor." }, "IDFieldValueExternal": { "type": "string", "nullable": true, "description": "Código externo do valor." }, "IDField": { "type": "integer", "description": "Id da especificação dona do valor." }, "Position": { "type": "integer", "nullable": true, "description": "Ordem de exibição do valor." } } } } } }, "SpecFieldDetail": { "type": "object", "description": "Especificação (campo) detalhada com seus valores (resposta de `skuSpecificationFieldIdGet`).", "properties": { "IDStockKeepingUnitSpecificationsFieldId": { "type": "integer", "description": "Id da especificação." }, "FieldName": { "type": "string", "description": "Nome do campo." }, "FieldType": { "type": "string", "nullable": true, "description": "Nome do tipo de preenchimento." }, "IDStockKeepingUnitSpecificationsFieldTypes": { "type": "integer", "description": "Id do tipo de preenchimento." }, "IDCategory": { "type": "integer", "description": "Id da categoria dona da especificação." }, "IDFieldExternal": { "type": "string", "nullable": true, "description": "Código externo do campo." }, "IsActive": { "type": "integer", "nullable": true, "description": "Campo ativo (`1`/`0`)." }, "IsFilter": { "type": "integer", "nullable": true, "description": "Usar como filtro na loja (`1`/`0`)." }, "IsOnProductDetails": { "type": "integer", "nullable": true, "description": "Exibir nos detalhes do produto (`1`/`0`)." }, "IsRequired": { "type": "integer", "nullable": true, "description": "Preenchimento obrigatório no produto (`1`/`0`)." }, "IsTopMenuLinkActive": { "type": "integer", "nullable": true, "description": "Ativar link no menu superior (`1`/`0`)." }, "IsSideMenuLinkActive": { "type": "integer", "nullable": true, "description": "Ativar link no menu lateral (`1`/`0`)." }, "FieldValue": { "type": "array", "description": "Valores cadastrados para o campo.", "items": { "type": "object", "properties": { "Value": { "type": "string", "description": "Texto do valor." }, "IDStockKeepingUnitSpecificationsFieldValues": { "type": "integer", "description": "Id do valor." }, "IDFieldValueExternal": { "type": "string", "nullable": true, "description": "Código externo do valor." } } } } } }, "SpecFieldCreate": { "type": "object", "required": [ "FieldName", "IDStockKeepingUnitSpecificationsFieldTypes" ], "description": "Corpo para criação de uma especificação na categoria.", "properties": { "FieldName": { "type": "string", "description": "Nome do campo." }, "IDStockKeepingUnitSpecificationsFieldTypes": { "type": "integer", "description": "Id do tipo de preenchimento (ver `GET /type/sku/specification/field-type`)." }, "IDFieldExternal": { "type": "string", "nullable": true, "description": "Código externo do campo; deve ser único na categoria." }, "IsFilter": { "type": "integer", "nullable": true, "description": "Usar como filtro na loja (`1`/`0`)." }, "IsOnProductDetails": { "type": "integer", "nullable": true, "description": "Exibir nos detalhes do produto (`1`/`0`)." }, "IsTopMenuLinkActive": { "type": "integer", "nullable": true, "description": "Ativar link no menu superior (`1`/`0`)." }, "IsSideMenuLinkActive": { "type": "integer", "nullable": true, "description": "Ativar link no menu lateral (`1`/`0`)." }, "IsActive": { "type": "integer", "nullable": true, "description": "Campo ativo (`1`/`0`)." }, "IsRequired": { "type": "integer", "nullable": true, "description": "Preenchimento obrigatório no produto (`1`/`0`)." }, "FieldPosition": { "type": "integer", "nullable": true, "description": "Ordem de exibição do campo." } } }, "SpecFieldUpdate": { "type": "object", "description": "Corpo para atualização parcial de uma especificação. Envie apenas os campos a alterar.", "properties": { "FieldName": { "type": "string", "description": "Nome do campo." }, "IDStockKeepingUnitSpecificationsFieldTypes": { "type": "integer", "description": "Id do tipo de preenchimento." }, "IDFieldExternal": { "type": "string", "nullable": true, "description": "Código externo do campo; deve ser único na categoria." }, "IsFilter": { "type": "integer", "description": "Usar como filtro na loja (`1`/`0`)." }, "IsOnProductDetails": { "type": "integer", "description": "Exibir nos detalhes do produto (`1`/`0`)." }, "IsTopMenuLinkActive": { "type": "integer", "description": "Ativar link no menu superior (`1`/`0`)." }, "IsSideMenuLinkActive": { "type": "integer", "description": "Ativar link no menu lateral (`1`/`0`)." }, "IsActive": { "type": "integer", "description": "Campo ativo (`1`/`0`)." }, "IsRequired": { "type": "integer", "description": "Preenchimento obrigatório no produto (`1`/`0`)." }, "FieldPosition": { "type": "integer", "description": "Ordem de exibição do campo." } } }, "SpecValueCreate": { "type": "object", "required": [ "Value" ], "description": "Corpo para adicionar um valor a uma especificação do tipo lista.", "properties": { "Value": { "type": "string", "description": "Texto do valor." }, "IDFieldValueExternal": { "type": "string", "nullable": true, "description": "Código externo do valor." }, "Position": { "type": "integer", "nullable": true, "description": "Ordem de exibição do valor." } } }, "SpecValueUpdate": { "type": "object", "required": [ "Value" ], "description": "Corpo para atualização de um valor de especificação.", "properties": { "Value": { "type": "string", "description": "Texto do valor." }, "IDFieldValueExternal": { "type": "string", "nullable": true, "description": "Código externo do valor." }, "Position": { "type": "integer", "nullable": true, "description": "Ordem de exibição do valor." } } }, "SpecFieldTypeItem": { "type": "object", "description": "Tipo de preenchimento de uma especificação (lista padrão do sistema).", "properties": { "IDStockKeepingUnitSpecificationsFieldTypes": { "type": "string", "description": "Id do tipo de preenchimento." }, "FieldType": { "type": "string", "description": "Nome do tipo (ex.: texto, número, lista)." } } }, "HubProductSpecificationInput": { "type": "object", "description": "Item da ficha técnica (especificação) do anúncio.", "properties": { "IDStockKeepingUnitSpecificationsFieldId": { "type": "string", "description": "Identificador do campo da ficha técnica da categoria." }, "FieldName": { "type": "string", "description": "Nome do campo da ficha técnica." }, "FieldValue": { "type": "string", "description": "Valor do campo (texto, opção ou número). Use `NA` quando não se aplica." }, "IDSpecificationValue": { "type": "string", "nullable": true, "description": "Identificador do valor selecionado, quando aplicável." }, "SpecificationCustomValue": { "type": "string", "nullable": true, "description": "Valor livre, quando o campo permite texto." } } }, "HubSkuInput": { "type": "object", "description": "Variação a criar junto do anúncio (fluxo de duplicação).", "required": [ "IDSku" ], "properties": { "IDSku": { "type": "integer", "format": "int64", "description": "SKU vinculado à variação." }, "IDCommercialCondition": { "type": "integer", "format": "int64", "nullable": true, "description": "Condição comercial da variação." }, "EcommerceModal": { "type": "string", "nullable": true, "description": "Modalidade de e-commerce da variação." } } }, "HubProductSalesPolicyInput": { "type": "object", "description": "Política comercial associada ao anúncio (ex.: Vtex).", "required": [ "IDTypeSkuSalesPolicy" ], "properties": { "IDTypeSkuSalesPolicy": { "type": "integer", "format": "int64", "description": "Política comercial / condição de venda." } } }, "HubProductImageInput": { "type": "object", "description": "Imagem do anúncio.", "required": [ "IDImage", "ImageOrder" ], "properties": { "IDImage": { "type": "integer", "format": "int64", "description": "Identificador da imagem." }, "ImageOrder": { "type": "integer", "description": "Ordem de exibição da imagem." } } }, "HubProductAutopartsInput": { "type": "object", "description": "Veículo compatível copiado no fluxo de duplicação (autopeças).", "properties": { "ProductId": { "type": "string", "description": "Identificador do veículo no catálogo do canal." }, "Notes": { "type": "string", "nullable": true, "description": "Observações da compatibilidade." }, "PositionArray": { "type": "string", "nullable": true, "description": "Posições de aplicação no formato `Valor|IDValor` separadas por `----`." } } }, "HubProductCreate": { "type": "object", "description": "Corpo de criação do anúncio.", "required": [ "IDCompanyIntegration", "IDProduct" ], "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (conta de canal) do anúncio." }, "IDProduct": { "type": "integer", "format": "int64", "description": "SKU/produto vinculado ao anúncio." }, "IDProductHub": { "type": "string", "nullable": true, "description": "Código do anúncio no canal (preenchido ao vincular um anúncio já existente)." }, "HubProductName": { "type": "string", "nullable": true, "description": "Título do anúncio no canal." }, "HubEcommerceDescription": { "type": "string", "nullable": true, "description": "Descrição do anúncio (até 5.000 caracteres)." }, "CategoryId": { "type": "string", "nullable": true, "description": "Categoria do canal." }, "CategoryPath": { "type": "string", "nullable": true, "description": "Caminho/legenda da categoria." }, "AdvertisementStatus": { "type": "integer", "nullable": true, "description": "Status do anúncio: `0` Inativo, `1` Ativo, `2` Fechado, `3` Pausado, `4` Em revisão, `5` Inabilitado canal." }, "ListingTypeId": { "type": "string", "enum": [ "bronze", "free", "gold", "gold_premium", "gold_pro", "gold_special", "silver" ], "nullable": true, "description": "Tipo de anúncio (Mercado Livre)." }, "Condition": { "type": "string", "nullable": true, "description": "Condição do item (ex.: `new`, `used`, `refurbished`) — canais que suportam condição." }, "ShippingMode": { "type": "string", "enum": [ "custom", "me1", "me2", "not_specified" ], "nullable": true, "description": "Forma de entrega (Mercado Livre)." }, "ShippingFree": { "type": "boolean", "nullable": true, "description": "Frete grátis (Mercado Livre, Kabum)." }, "ShippingLocalPickUp": { "type": "boolean", "nullable": true, "description": "Permite retirada no local (Mercado Livre)." }, "LeadTimeDays": { "type": "integer", "nullable": true, "description": "Prazo de disponibilização (dias)." }, "WarrantyType": { "type": "string", "nullable": true, "description": "Tipo de garantia (ex.: garantia do vendedor / de fábrica / sem garantia)." }, "WarrantyTime": { "type": "integer", "nullable": true, "description": "Prazo de garantia." }, "WarrantyTimeType": { "type": "string", "nullable": true, "description": "Unidade do prazo de garantia (ex.: `days`, `months`, `years`)." }, "OfficialStore": { "type": "string", "nullable": true, "description": "Loja Oficial (Mercado Livre)." }, "ShowWithoutStock": { "type": "boolean", "nullable": true, "description": "Mantém o anúncio visível sem estoque." }, "Visible": { "type": "boolean", "nullable": true, "description": "Anúncio visível." }, "Comments": { "type": "string", "nullable": true, "description": "Observações internas." }, "IDHubProductQuestionAnswerTemplate": { "type": "integer", "format": "int64", "nullable": true, "description": "Modelo de perguntas e respostas (Mercado Livre)." }, "PriceListSet": { "type": "number", "nullable": true, "description": "Preço de (preço cheio) a nível de anúncio." }, "PriceSellSet": { "type": "number", "nullable": true, "description": "Preço por (preço de venda) a nível de anúncio." }, "NetPricingSet": { "type": "number", "nullable": true, "description": "Preço líquido, quando o canal suporta (Mercado Livre)." }, "HubProductSpecification": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSpecificationInput" }, "description": "Ficha técnica (especificações) do anúncio." }, "HubProductSalesPolicy": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSalesPolicyInput" }, "description": "Políticas comerciais (ex.: Vtex)." }, "PricingSet": { "type": "number", "nullable": true, "description": "Preço manual aplicado às variações criadas automaticamente." }, "HubSku": { "type": "array", "items": { "$ref": "#/components/schemas/HubSkuInput" }, "description": "Variações a criar (usado no fluxo de duplicação)." }, "Autoparts": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductAutopartsInput" }, "description": "Veículos compatíveis (usado no fluxo de duplicação — autopeças)." } } }, "HubProductUpdate": { "type": "object", "description": "Corpo de atualização parcial do anúncio (envie apenas os campos a alterar).", "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (conta de canal) do anúncio." }, "IDProduct": { "type": "integer", "format": "int64", "description": "SKU/produto vinculado ao anúncio." }, "IDProductHub": { "type": "string", "nullable": true, "description": "Código do anúncio no canal (preenchido ao vincular um anúncio já existente)." }, "HubProductName": { "type": "string", "nullable": true, "description": "Título do anúncio no canal." }, "HubEcommerceDescription": { "type": "string", "nullable": true, "description": "Descrição do anúncio (até 5.000 caracteres)." }, "CategoryId": { "type": "string", "nullable": true, "description": "Categoria do canal." }, "CategoryPath": { "type": "string", "nullable": true, "description": "Caminho/legenda da categoria." }, "AdvertisementStatus": { "type": "integer", "nullable": true, "description": "Status do anúncio: `0` Inativo, `1` Ativo, `2` Fechado, `3` Pausado, `4` Em revisão, `5` Inabilitado canal." }, "ListingTypeId": { "type": "string", "enum": [ "bronze", "free", "gold", "gold_premium", "gold_pro", "gold_special", "silver" ], "nullable": true, "description": "Tipo de anúncio (Mercado Livre)." }, "Condition": { "type": "string", "nullable": true, "description": "Condição do item (ex.: `new`, `used`, `refurbished`) — canais que suportam condição." }, "ShippingMode": { "type": "string", "enum": [ "custom", "me1", "me2", "not_specified" ], "nullable": true, "description": "Forma de entrega (Mercado Livre)." }, "ShippingFree": { "type": "boolean", "nullable": true, "description": "Frete grátis (Mercado Livre, Kabum)." }, "ShippingLocalPickUp": { "type": "boolean", "nullable": true, "description": "Permite retirada no local (Mercado Livre)." }, "LeadTimeDays": { "type": "integer", "nullable": true, "description": "Prazo de disponibilização (dias)." }, "WarrantyType": { "type": "string", "nullable": true, "description": "Tipo de garantia (ex.: garantia do vendedor / de fábrica / sem garantia)." }, "WarrantyTime": { "type": "integer", "nullable": true, "description": "Prazo de garantia." }, "WarrantyTimeType": { "type": "string", "nullable": true, "description": "Unidade do prazo de garantia (ex.: `days`, `months`, `years`)." }, "OfficialStore": { "type": "string", "nullable": true, "description": "Loja Oficial (Mercado Livre)." }, "ShowWithoutStock": { "type": "boolean", "nullable": true, "description": "Mantém o anúncio visível sem estoque." }, "Visible": { "type": "boolean", "nullable": true, "description": "Anúncio visível." }, "Comments": { "type": "string", "nullable": true, "description": "Observações internas." }, "IDHubProductQuestionAnswerTemplate": { "type": "integer", "format": "int64", "nullable": true, "description": "Modelo de perguntas e respostas (Mercado Livre)." }, "PriceListSet": { "type": "number", "nullable": true, "description": "Preço de (preço cheio) a nível de anúncio." }, "PriceSellSet": { "type": "number", "nullable": true, "description": "Preço por (preço de venda) a nível de anúncio." }, "NetPricingSet": { "type": "number", "nullable": true, "description": "Preço líquido, quando o canal suporta (Mercado Livre)." }, "HubProductSpecification": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSpecificationInput" }, "description": "Ficha técnica (especificações) do anúncio." }, "HubProductSalesPolicy": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSalesPolicyInput" }, "description": "Políticas comerciais (ex.: Vtex)." }, "CatalogProductId": { "type": "string", "nullable": true, "description": "Produto de catálogo (Mercado Livre); vazio desvincula do catálogo." }, "AutopartsException": { "type": "boolean", "nullable": true, "description": "Marca o anúncio como exceção de compatibilidade (autopeças)." }, "AutopartsUniversalCompatibility": { "type": "boolean", "nullable": true, "description": "Compatibilidade universal (autopeças, categorias elegíveis do Mercado Livre)." }, "HubProductImage": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductImageInput" }, "description": "Imagens do anúncio (substitui o conjunto atual; array vazio remove todas)." } } }, "HubSkuSpecificationInput": { "type": "object", "description": "Item de ficha técnica da variação.", "properties": { "IDStockKeepingUnitSpecificationsFieldId": { "type": "string", "description": "Identificador do campo da ficha técnica." }, "FieldName": { "type": "string", "description": "Nome do campo." }, "FieldValue": { "type": "string", "description": "Valor do campo (use `NA` quando não se aplica)." } } }, "HubSkuImageInput": { "type": "object", "description": "Imagem da variação.", "required": [ "IDImage", "ImageOrder" ], "properties": { "IDImage": { "type": "integer", "format": "int64", "description": "Identificador da imagem." }, "ImageOrder": { "type": "integer", "description": "Ordem de exibição." } } }, "HubProductOfferCreate": { "type": "object", "description": "Corpo de criação de variação do anúncio.", "required": [ "IDSku" ], "properties": { "IDSku": { "type": "integer", "format": "int64", "description": "SKU vinculado à variação." }, "IDSkuHub": { "type": "string", "nullable": true, "description": "Código da variação no canal." }, "PricingSet": { "type": "number", "nullable": true, "description": "Preço manual da variação (não coexiste com o preço a nível de anúncio)." }, "HubSkuOrder": { "type": "integer", "nullable": true, "description": "Ordem da variação na página do canal." }, "Comments": { "type": "string", "nullable": true, "description": "Observações internas." }, "HubSkuListingTypeId": { "type": "string", "enum": [ "bronze", "free", "gold", "gold_premium", "gold_pro", "gold_special", "silver" ], "nullable": true, "description": "Tipo de anúncio da variação (Mercado Livre)." }, "HubSkuShippingFree": { "type": "boolean", "nullable": true, "description": "Frete grátis da variação (Mercado Livre)." }, "EcommerceModal": { "type": "string", "nullable": true, "description": "Modalidade de e-commerce." }, "IDCommercialCondition": { "type": "integer", "format": "int64", "nullable": true, "description": "Condição comercial." }, "HubSkuSpecification": { "type": "array", "items": { "$ref": "#/components/schemas/HubSkuSpecificationInput" }, "description": "Ficha técnica da variação." } } }, "HubProductOfferUpdate": { "type": "object", "description": "Corpo de atualização parcial da variação (envie apenas os campos a alterar).", "properties": { "IDSku": { "type": "integer", "format": "int64", "nullable": true, "description": "SKU vinculado à variação (quando alterado)." }, "IDSkuHub": { "type": "string", "nullable": true, "description": "Código da variação no canal." }, "PricingSet": { "type": "number", "nullable": true, "description": "Preço manual da variação (não coexiste com o preço a nível de anúncio)." }, "HubSkuOrder": { "type": "integer", "nullable": true, "description": "Ordem da variação na página do canal." }, "Comments": { "type": "string", "nullable": true, "description": "Observações internas." }, "HubSkuListingTypeId": { "type": "string", "enum": [ "bronze", "free", "gold", "gold_premium", "gold_pro", "gold_special", "silver" ], "nullable": true, "description": "Tipo de anúncio da variação (Mercado Livre)." }, "HubSkuShippingFree": { "type": "boolean", "nullable": true, "description": "Frete grátis da variação (Mercado Livre)." }, "EcommerceModal": { "type": "string", "nullable": true, "description": "Modalidade de e-commerce." }, "IDCommercialCondition": { "type": "integer", "format": "int64", "nullable": true, "description": "Condição comercial." }, "HubSkuSpecification": { "type": "array", "items": { "$ref": "#/components/schemas/HubSkuSpecificationInput" }, "description": "Ficha técnica da variação." }, "HubSkuImage": { "type": "array", "items": { "$ref": "#/components/schemas/HubSkuImageInput" }, "description": "Imagens da variação (substitui o conjunto atual; array vazio remove todas)." } } }, "HubProductAutopartsPositionInput": { "type": "object", "description": "Posição de aplicação do veículo compatível.", "properties": { "SpecificationValue": { "type": "array", "description": "Valores de posição de aplicação.", "items": { "type": "string" } }, "IDSpecificationValue": { "type": "array", "description": "Identificadores dos valores de posição.", "items": { "type": "string" } } } }, "HubProductAutopartsCreate": { "type": "object", "description": "Corpo para adicionar um veículo compatível (autopeças).", "properties": { "ProductId": { "type": "string", "description": "Identificador do veículo no catálogo do canal." }, "Notes": { "type": "string", "nullable": true, "description": "Observações da compatibilidade." }, "Brand": { "type": "string", "nullable": true, "description": "Marca do veículo (usado só ao cadastrar veículo novo)." }, "Model": { "type": "string", "nullable": true, "description": "Modelo." }, "Year": { "type": "string", "nullable": true, "description": "Ano." }, "ShortVersion": { "type": "string", "nullable": true, "description": "Versão." }, "Engine": { "type": "string", "nullable": true, "description": "Motor." }, "Fuel": { "type": "string", "nullable": true, "description": "Combustível." }, "Power": { "type": "string", "nullable": true, "description": "Potência." }, "BodyType": { "type": "string", "nullable": true, "description": "Carroceria." }, "Transmission": { "type": "string", "nullable": true, "description": "Transmissão." }, "Gear": { "type": "string", "nullable": true, "description": "Câmbio." }, "Doors": { "type": "string", "nullable": true, "description": "Portas." }, "Steering": { "type": "string", "nullable": true, "description": "Direção." }, "Traction": { "type": "string", "nullable": true, "description": "Tração." }, "Valves": { "type": "string", "nullable": true, "description": "Válvulas." }, "Trim": { "type": "string", "nullable": true, "description": "Acabamento." } } }, "HubProductAutopartsUpdate": { "type": "object", "description": "Corpo de atualização de um veículo compatível (autopeças).", "properties": { "Notes": { "type": "string", "nullable": true, "description": "Observações da compatibilidade." }, "HubProductAutopartsPosition": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductAutopartsPositionInput" }, "description": "Posições de aplicação (substitui o conjunto atual; array vazio remove todas)." } } }, "HubProductQuantityPricingPayload": { "type": "object", "description": "Faixa de preço por quantidade (Mercado Livre).", "required": [ "Quantity", "Price" ], "properties": { "Quantity": { "type": "integer", "description": "Quantidade mínima da faixa (maior que zero)." }, "Price": { "type": "number", "description": "Preço por unidade na faixa." } } }, "HubSkuListSummary": { "type": "object", "description": "Resumo de variação na listagem de anúncios.", "properties": { "IDHubAdvertisement": { "type": "integer", "format": "int64", "description": "Identificador da variação." }, "IDSku": { "type": "integer", "format": "int64", "description": "SKU vinculado." }, "IDSkuHub": { "type": "string", "nullable": true, "description": "Código da variação no canal." }, "PricingCheck": { "type": "number", "nullable": true, "description": "Preço calculado para conferência." }, "PricingSet": { "type": "number", "nullable": true, "description": "Preço manual da variação." }, "OriginalPrice": { "type": "number", "nullable": true, "description": "Preço de tabela do SKU." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome do produto." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência da variação." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras." }, "ProductVariation": { "type": "string", "nullable": true, "description": "Atributos de variação (ex.: Cor, Tamanho)." }, "TypeProductVariationValue": { "type": "string", "nullable": true, "description": "Valores dos atributos de variação." }, "HubSkuOrder": { "type": "integer", "nullable": true, "description": "Ordem da variação." }, "PurchaseExperienceValue": { "type": "number", "nullable": true, "description": "Indicador de experiência de compra." }, "Comments": { "type": "string", "nullable": true, "description": "Observações." }, "MainImageURL": { "type": "string", "nullable": true, "description": "Imagem principal da variação." }, "AccountName": { "type": "string", "nullable": true, "description": "Conta." } } }, "HubProductListItem": { "type": "object", "description": "Item da listagem de anúncios.", "properties": { "IDHubProduct": { "type": "integer", "format": "int64", "description": "Identificador interno do anúncio." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração (conta de canal)." }, "AccountName": { "type": "string", "nullable": true, "description": "Conta." }, "IDProduct": { "type": "integer", "format": "int64", "nullable": true, "description": "SKU/produto vinculado." }, "IDProductHub": { "type": "string", "nullable": true, "description": "Código do anúncio no canal." }, "HubProductName": { "type": "string", "nullable": true, "description": "Título do anúncio." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome do produto." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência do produto." }, "Brand": { "type": "string", "nullable": true, "description": "Marca." }, "IDBrand": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador da marca." }, "IDTypeSku": { "type": "integer", "format": "int64", "nullable": true, "description": "Tipo do produto." }, "TypeProduct": { "type": "string", "nullable": true, "description": "Descrição do tipo do produto." }, "SalesChannelName": { "type": "string", "nullable": true, "description": "Nome do canal de vendas." }, "IntegrationName": { "type": "string", "nullable": true, "description": "Nome do canal/integração." }, "CompanyIntegrationName": { "type": "string", "nullable": true, "description": "Nome da conta de integração." }, "IDTypeCompanyIntegration": { "type": "integer", "format": "int64", "nullable": true, "description": "Tipo de canal." }, "LogoUrl": { "type": "string", "nullable": true, "description": "Logotipo do canal." }, "CategoryId": { "type": "string", "nullable": true, "description": "Categoria do canal." }, "AdvertisementStatus": { "type": "integer", "nullable": true, "description": "Status do anúncio: `0` Inativo, `1` Ativo, `2` Fechado, `3` Pausado, `4` Em revisão, `5` Inabilitado canal." }, "StatusHubSku": { "type": "string", "nullable": true, "description": "Status do anúncio (texto)." }, "HubProductSubStatus": { "type": "integer", "nullable": true, "description": "Sub-status (código)." }, "SubStatus": { "type": "string", "nullable": true, "description": "Sub-status (texto)." }, "AdvertisementUrl": { "type": "string", "nullable": true, "description": "Endereço do anúncio no canal." }, "ListingTypeId": { "type": "string", "enum": [ "bronze", "free", "gold", "gold_premium", "gold_pro", "gold_special", "silver" ], "nullable": true, "description": "Tipo de anúncio (Mercado Livre)." }, "ListingTypeDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo de anúncio." }, "Health": { "type": "number", "nullable": true, "description": "Qualidade do anúncio (%)." }, "PriceListSet": { "type": "number", "nullable": true, "description": "Preço de (preço cheio)." }, "PriceSellSet": { "type": "number", "nullable": true, "description": "Preço por (preço de venda)." }, "ShippingFree": { "type": "boolean", "nullable": true, "description": "Frete grátis." }, "ShippingMode": { "type": "string", "enum": [ "custom", "me1", "me2", "not_specified" ], "nullable": true, "description": "Forma de entrega (Mercado Livre)." }, "ShippingLocalPickUp": { "type": "boolean", "nullable": true, "description": "Retirada no local." }, "ShippingLogisticType": { "type": "string", "nullable": true, "description": "Tipo de logística do canal (ex.: `fulfillment`)." }, "ShippingLogisticValue": { "type": "string", "nullable": true, "description": "`Full` quando logística é fulfillment do Mercado Livre." }, "ShippingTags": { "type": "string", "nullable": true, "description": "Etiquetas de envio do canal." }, "ShippingTagsValue": { "type": "string", "nullable": true, "description": "`Flex` quando entrega no mesmo dia (Mercado Livre)." }, "OfficialStore": { "type": "string", "nullable": true, "description": "Loja Oficial (Mercado Livre)." }, "WarrantyTime": { "type": "integer", "nullable": true, "description": "Prazo de garantia." }, "WarrantyTimeType": { "type": "string", "nullable": true, "description": "Unidade do prazo de garantia." }, "ShowWithoutStock": { "type": "boolean", "nullable": true, "description": "Mantém visível sem estoque." }, "LeadTimeDays": { "type": "integer", "nullable": true, "description": "Prazo de disponibilização (dias)." }, "Catalog": { "type": "string", "nullable": true, "description": "`Catálogo` (participa) ou `Elegível` (poderia participar)." }, "CatalogListing": { "type": "boolean", "nullable": true, "description": "Participa do catálogo (Mercado Livre)." }, "CatalogEligible": { "type": "boolean", "nullable": true, "description": "Elegível ao catálogo." }, "CatalogStatus": { "type": "string", "nullable": true, "description": "Status de catálogo do canal (ex.: `winning`)." }, "CatalogStatusValue": { "type": "string", "nullable": true, "description": "Posição no catálogo: Vencedor, Competindo, Compartilhado, Não listado." }, "AutopartsPendingCompatibility": { "type": "integer", "nullable": true, "description": "Autopeças: tem compatibilidade pendente." }, "AutopartsRequiredCompatibility": { "type": "integer", "nullable": true, "description": "Autopeças: exige lista de compatibilidade." }, "AutopartsUniversalCompatibility": { "type": "integer", "nullable": true, "description": "Autopeças: compatibilidade universal." }, "HubProductAutopartsQuantity": { "type": "integer", "nullable": true, "description": "Quantidade de veículos compatíveis associados." }, "PurchaseExperienceValue": { "type": "number", "nullable": true, "description": "Indicador de experiência de compra." }, "IDHubProductQuestionAnswerTemplate": { "type": "integer", "format": "int64", "nullable": true, "description": "Modelo de perguntas e respostas." }, "AnswerTitle": { "type": "string", "nullable": true, "description": "Título do modelo de mensagem." }, "HubEcommerceDescription": { "type": "string", "nullable": true, "description": "Descrição do anúncio." }, "MainImageURL": { "type": "string", "nullable": true, "description": "Imagem principal." }, "MainImageThumbnailURL": { "type": "string", "nullable": true, "description": "Miniatura da imagem principal." }, "HubSku": { "type": "array", "items": { "$ref": "#/components/schemas/HubSkuListSummary" }, "description": "Variações do anúncio (resumo)." } } }, "HubProductSpecificationItem": { "type": "object", "description": "Item de ficha técnica do anúncio.", "properties": { "IDSpecification": { "type": "string", "nullable": true, "description": "Identificador do campo da ficha técnica." }, "SpecificationName": { "type": "string", "nullable": true, "description": "Nome do campo." }, "SpecificationValue": { "type": "string", "nullable": true, "description": "Valor do campo." }, "IDSpecificationValue": { "type": "string", "nullable": true, "description": "Identificador do valor selecionado." }, "SpecificationCustomValue": { "type": "string", "nullable": true, "description": "Valor livre." } } }, "HubProductSalesPolicyItem": { "type": "object", "description": "Política comercial associada ao anúncio.", "properties": { "IDTypeSkuSalesPolicy": { "type": "integer", "format": "int64", "description": "Identificador da política comercial." }, "SalesPolicy": { "type": "string", "nullable": true, "description": "Nome da política comercial." } } }, "HubProductImageItem": { "type": "object", "description": "Imagem do anúncio.", "properties": { "IDHubProductImage": { "type": "integer", "format": "int64", "description": "Identificador da imagem do anúncio." }, "IDImage": { "type": "integer", "format": "int64", "description": "Identificador da imagem." }, "ImageOrder": { "type": "integer", "description": "Ordem de exibição." }, "Url": { "type": "string", "nullable": true, "description": "Endereço da imagem." }, "ImageSize": { "type": "integer", "nullable": true, "description": "Tamanho do arquivo." }, "ImageWidth": { "type": "integer", "nullable": true, "description": "Largura." }, "ImageHeight": { "type": "integer", "nullable": true, "description": "Altura." }, "ImageName": { "type": "string", "nullable": true, "description": "Nome do arquivo." } } }, "HubProductHealthItem": { "type": "object", "description": "Pendência de qualidade do anúncio.", "properties": { "TypeHubProductHealthDescription": { "type": "string", "nullable": true, "description": "Pendência que reduz a qualidade do anúncio." } } }, "HubProductPurchaseExperienceItem": { "type": "object", "description": "Indicador de experiência de compra do anúncio.", "properties": { "PurchaseExperienceValue": { "type": "number", "nullable": true, "description": "Indicador de experiência de compra." } } }, "HubProductQuantityPricingItem": { "type": "object", "description": "Faixa de preço por quantidade (Mercado Livre).", "properties": { "IDHubProductQuantityPricing": { "type": "integer", "format": "int64", "description": "Identificador da faixa." }, "IDHubProduct": { "type": "integer", "format": "int64", "nullable": true, "description": "Anúncio." }, "Quantity": { "type": "integer", "description": "Quantidade mínima da faixa." }, "Price": { "type": "number", "description": "Preço por unidade na faixa." } } }, "HubSkuSpecificationItem": { "type": "object", "description": "Item de ficha técnica da variação.", "properties": { "IDSpecification": { "type": "string", "nullable": true, "description": "Identificador do campo da ficha técnica." }, "SpecificationName": { "type": "string", "nullable": true, "description": "Nome do campo." }, "SpecificationValue": { "type": "string", "nullable": true, "description": "Valor do campo." }, "IDSpecificationValue": { "type": "string", "nullable": true, "description": "Identificador do valor selecionado." } } }, "HubSkuImageItem": { "type": "object", "description": "Imagem da variação.", "properties": { "IDHubSkuImage": { "type": "integer", "format": "int64", "description": "Identificador da imagem da variação." }, "IDImage": { "type": "integer", "format": "int64", "description": "Identificador da imagem." }, "ImageOrder": { "type": "integer", "description": "Ordem de exibição." }, "Url": { "type": "string", "nullable": true, "description": "Endereço da imagem." }, "ImageSize": { "type": "integer", "nullable": true, "description": "Tamanho do arquivo." }, "ImageWidth": { "type": "integer", "nullable": true, "description": "Largura." }, "ImageHeight": { "type": "integer", "nullable": true, "description": "Altura." }, "ImageName": { "type": "string", "nullable": true, "description": "Nome do arquivo." }, "IDHubAdvertisement": { "type": "integer", "format": "int64", "nullable": true, "description": "Variação à qual a imagem pertence." } } }, "HubSkuDetail": { "type": "object", "description": "Variação (item) do anúncio.", "properties": { "IDHubAdvertisement": { "type": "integer", "format": "int64", "description": "Identificador da variação." }, "IDHubProduct": { "type": "integer", "format": "int64", "nullable": true, "description": "Anúncio ao qual pertence." }, "IDSku": { "type": "integer", "format": "int64", "nullable": true, "description": "SKU vinculado." }, "IDSkuHub": { "type": "string", "nullable": true, "description": "Código da variação no canal." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome do produto." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras." }, "AccountName": { "type": "string", "nullable": true, "description": "Conta." }, "ProductVariation": { "type": "string", "nullable": true, "description": "Atributos de variação." }, "TypeProductVariationValue": { "type": "string", "nullable": true, "description": "Valores dos atributos de variação." }, "HubSkuOrder": { "type": "integer", "nullable": true, "description": "Ordem da variação." }, "IDTypeSku": { "type": "integer", "format": "int64", "nullable": true, "description": "Tipo do produto." }, "TypeProduct": { "type": "string", "nullable": true, "description": "Descrição do tipo." }, "QtyAvailable": { "type": "number", "nullable": true, "description": "Quantidade disponível." }, "QtyToSell": { "type": "number", "nullable": true, "description": "Quantidade a vender." }, "QtySafetyStock": { "type": "integer", "nullable": true, "description": "Estoque de segurança." }, "InfiniteInventory": { "type": "boolean", "nullable": true, "description": "Estoque infinito." }, "SoldQuantity": { "type": "integer", "nullable": true, "description": "Quantidade vendida." }, "PricingSet": { "type": "number", "nullable": true, "description": "Preço manual da variação." }, "PricingCheck": { "type": "number", "nullable": true, "description": "Preço calculado para conferência." }, "PricingSell": { "type": "number", "nullable": true, "description": "Preço de venda calculado." }, "PricingList": { "type": "number", "nullable": true, "description": "Preço de tabela calculado." }, "OriginalPrice": { "type": "number", "nullable": true, "description": "Preço de tabela do SKU." }, "PriceMultiplyValue": { "type": "number", "nullable": true, "description": "Fator multiplicador de preço." }, "PriceAddValue": { "type": "number", "nullable": true, "description": "Acréscimo de preço." }, "PriceRounding": { "type": "number", "nullable": true, "description": "Arredondamento de preço." }, "CostAverage": { "type": "number", "nullable": true, "description": "Custo médio." }, "CostLastPurchase": { "type": "number", "nullable": true, "description": "Custo da última compra." }, "IDCommercialCondition": { "type": "integer", "format": "int64", "nullable": true, "description": "Condição comercial." }, "CommercialCondition": { "type": "string", "nullable": true, "description": "Descrição da condição comercial." }, "EcommerceModal": { "type": "string", "nullable": true, "description": "Modalidade de e-commerce." }, "HubSkuListingTypeId": { "type": "string", "enum": [ "bronze", "free", "gold", "gold_premium", "gold_pro", "gold_special", "silver" ], "nullable": true, "description": "Tipo de anúncio da variação (Mercado Livre)." }, "HubSkuShippingFree": { "type": "boolean", "nullable": true, "description": "Frete grátis da variação." }, "Comments": { "type": "string", "nullable": true, "description": "Observações." }, "MainImageURL": { "type": "string", "nullable": true, "description": "Imagem principal da variação." }, "PurchaseExperienceValue": { "type": "number", "nullable": true, "description": "Indicador de experiência de compra." }, "IDHubUserProduct": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador de User Product (Mercado Livre)." }, "HubSkuSpecification": { "type": "array", "items": { "$ref": "#/components/schemas/HubSkuSpecificationItem" }, "description": "Ficha técnica da variação." }, "HubSkuImage": { "type": "array", "items": { "$ref": "#/components/schemas/HubSkuImageItem" }, "description": "Imagens da variação." }, "PurchaseExperience": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductPurchaseExperienceItem" }, "description": "Experiência de compra da variação." } } }, "HubProductDetail": { "type": "object", "description": "Detalhe completo do anúncio.", "properties": { "IDHubProduct": { "type": "integer", "format": "int64", "description": "Identificador interno do anúncio." }, "IDProduct": { "type": "integer", "format": "int64", "nullable": true, "description": "SKU/produto vinculado." }, "IDProductHub": { "type": "string", "nullable": true, "description": "Código do anúncio no canal." }, "AccountName": { "type": "string", "nullable": true, "description": "Conta." }, "HubProductName": { "type": "string", "nullable": true, "description": "Título do anúncio." }, "EcommerceTitle": { "type": "string", "nullable": true, "description": "Título de e-commerce do produto." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome do produto (ou título de e-commerce, conforme parametrização)." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência do produto." }, "IDBrand": { "type": "integer", "format": "int64", "nullable": true, "description": "Marca." }, "IDTypeSku": { "type": "integer", "format": "int64", "nullable": true, "description": "Tipo do produto." }, "TypeProduct": { "type": "string", "nullable": true, "description": "Descrição do tipo." }, "HubEcommerceDescription": { "type": "string", "nullable": true, "description": "Descrição do anúncio." }, "EcommerceDescription": { "type": "string", "nullable": true, "description": "Descrição de e-commerce do produto." }, "Comments": { "type": "string", "nullable": true, "description": "Observações internas." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "nullable": true, "description": "Integração (conta de canal)." }, "IDTypeCompanyIntegration": { "type": "integer", "format": "int64", "nullable": true, "description": "Tipo de canal." }, "CompanyIntegrationName": { "type": "string", "nullable": true, "description": "Nome da conta de integração." }, "IntegrationName": { "type": "string", "nullable": true, "description": "Nome do canal." }, "SalesChannelName": { "type": "string", "nullable": true, "description": "Nome do canal de vendas." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Canal e conta (texto combinado)." }, "LogoUrl": { "type": "string", "nullable": true, "description": "Logotipo do canal." }, "PathName": { "type": "string", "nullable": true, "description": "Caminho interno do recurso." }, "CategoryId": { "type": "string", "nullable": true, "description": "Categoria do canal." }, "IDCategory": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador interno da categoria." }, "CategoryPath": { "type": "string", "nullable": true, "description": "Caminho/legenda da categoria." }, "AdvertisementStatus": { "type": "integer", "nullable": true, "description": "Status do anúncio: `0` Inativo, `1` Ativo, `2` Fechado, `3` Pausado, `4` Em revisão, `5` Inabilitado canal." }, "StatusHubSku": { "type": "string", "nullable": true, "description": "Status (texto)." }, "HubProductSubStatus": { "type": "integer", "nullable": true, "description": "Sub-status (código)." }, "Substatus": { "type": "string", "nullable": true, "description": "Sub-status (texto)." }, "ReviewReason": { "type": "string", "nullable": true, "description": "Motivo de revisão informado pelo canal." }, "ReviewRemedy": { "type": "string", "nullable": true, "description": "Ação sugerida para resolver a revisão." }, "AdvertisementUrl": { "type": "string", "nullable": true, "description": "Endereço do anúncio no canal." }, "ListingTypeId": { "type": "string", "enum": [ "bronze", "free", "gold", "gold_premium", "gold_pro", "gold_special", "silver" ], "nullable": true, "description": "Tipo de anúncio (Mercado Livre)." }, "ListingTypeDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo de anúncio." }, "Condition": { "type": "string", "nullable": true, "description": "Condição do item (ex.: `new`, `used`)." }, "ShippingMode": { "type": "string", "enum": [ "custom", "me1", "me2", "not_specified" ], "nullable": true, "description": "Forma de entrega (Mercado Livre)." }, "ShippingModeDescription": { "type": "string", "nullable": true, "description": "Descrição da forma de entrega." }, "ShippingFree": { "type": "string", "nullable": true, "description": "Frete grátis." }, "ShippingLocalPickUp": { "type": "string", "nullable": true, "description": "Retirada no local." }, "ShippingLogisticType": { "type": "string", "nullable": true, "description": "Tipo de logística (ex.: `fulfillment` = Full)." }, "ShippingTags": { "type": "string", "nullable": true, "description": "Etiquetas de envio (ex.: `self_service_in` = Flex)." }, "WarrantyType": { "type": "string", "nullable": true, "description": "Tipo de garantia." }, "WarrantyTime": { "type": "integer", "nullable": true, "description": "Prazo de garantia." }, "WarrantyTimeType": { "type": "string", "nullable": true, "description": "Unidade do prazo de garantia." }, "LeadTimeDays": { "type": "integer", "nullable": true, "description": "Prazo de disponibilização (dias)." }, "OfficialStore": { "type": "string", "nullable": true, "description": "Loja Oficial (Mercado Livre)." }, "ShowWithoutStock": { "type": "string", "nullable": true, "description": "Mantém visível sem estoque." }, "Visible": { "type": "string", "nullable": true, "description": "Anúncio visível." }, "Health": { "type": "number", "nullable": true, "description": "Qualidade do anúncio (%)." }, "TotalVisits": { "type": "integer", "nullable": true, "description": "Total de visitas (canal)." }, "SoldQuantity": { "type": "integer", "nullable": true, "description": "Quantidade vendida." }, "Rating": { "type": "number", "nullable": true, "description": "Avaliação média do produto no canal." }, "PurchaseExperienceValue": { "type": "number", "nullable": true, "description": "Indicador de experiência de compra." }, "PriceListSet": { "type": "number", "nullable": true, "description": "Preço de (preço cheio)." }, "PriceSellSet": { "type": "number", "nullable": true, "description": "Preço por (preço de venda)." }, "NetPricingSet": { "type": "number", "nullable": true, "description": "Preço líquido (Mercado Livre)." }, "NetPricingEligible": { "type": "boolean", "nullable": true, "description": "Elegível ao Preço Líquido (Mercado Livre)." }, "CatalogListing": { "type": "boolean", "nullable": true, "description": "Participa do catálogo." }, "CatalogEligible": { "type": "boolean", "nullable": true, "description": "Elegível ao catálogo." }, "CatalogProductId": { "type": "string", "nullable": true, "description": "Produto de catálogo (Mercado Livre)." }, "CatalogStatus": { "type": "string", "nullable": true, "description": "Status no catálogo (canal)." }, "CatalogPriceToWin": { "type": "number", "nullable": true, "description": "Preço para vencer a vitrine de catálogo." }, "CatalogOpportunity": { "type": "string", "nullable": true, "description": "Oportunidades de melhoria sugeridas pelo canal." }, "AutopartsException": { "type": "boolean", "nullable": true, "description": "Exceção de compatibilidade (autopeças)." }, "AutopartsUniversalCompatibility": { "type": "boolean", "nullable": true, "description": "Compatibilidade universal (autopeças)." }, "AutopartsUniversalCompatibilityAllowed": { "type": "integer", "nullable": true, "description": "Permite compatibilidade universal (autopeças/Mercado Livre)." }, "AutopartsPendingCompatibility": { "type": "boolean", "nullable": true, "description": "Compatibilidade pendente (autopeças)." }, "AutopartsRequiredCompatibility": { "type": "boolean", "nullable": true, "description": "Exige compatibilidade (autopeças)." }, "UserProductListing": { "type": "string", "nullable": true, "description": "User Product (Mercado Livre)." }, "UserProductEnabled": { "type": "integer", "nullable": true, "description": "User Product habilitado (Mercado Livre)." }, "HubUserProductEligible": { "type": "boolean", "nullable": true, "description": "Elegível a User Product (Mercado Livre)." }, "HubProductQuantityPricingAllowed": { "type": "integer", "nullable": true, "description": "Permite preço por quantidade (Mercado Livre)." }, "IDHubProductQuestionAnswerTemplate": { "type": "integer", "format": "int64", "nullable": true, "description": "Modelo de perguntas e respostas." }, "AnswerTitle": { "type": "string", "nullable": true, "description": "Título do modelo de mensagem." }, "AnswerTemplate": { "type": "string", "nullable": true, "description": "Conteúdo do modelo de mensagem." }, "MainImageURL": { "type": "string", "nullable": true, "description": "Imagem principal." }, "MainImageThumbnailURL": { "type": "string", "nullable": true, "description": "Miniatura da imagem principal." }, "CreatedTimestamp": { "type": "string", "nullable": true, "description": "Data de criação.", "format": "date-time" }, "RecordTimestamp": { "type": "string", "nullable": true, "description": "Data da última alteração.", "format": "date-time" }, "HubProductSpecification": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSpecificationItem" }, "description": "Ficha técnica do anúncio." }, "HubProductSalesPolicy": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductSalesPolicyItem" }, "description": "Políticas comerciais." }, "HubProductImage": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductImageItem" }, "description": "Imagens do anúncio." }, "HealthAction": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductHealthItem" }, "description": "Pendências que reduzem a qualidade." }, "PurchaseExperience": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductPurchaseExperienceItem" }, "description": "Indicadores de experiência de compra." }, "HubProductQuantityPricing": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductQuantityPricingItem" }, "description": "Faixas de preço por quantidade (Mercado Livre)." }, "HubSku": { "type": "array", "items": { "$ref": "#/components/schemas/HubSkuDetail" }, "description": "Variações (itens) do anúncio." } } }, "HubProductAutopartsPositionItem": { "type": "object", "description": "Posição de aplicação do veículo compatível.", "properties": { "SpecificationValue": { "type": "array", "items": { "type": "string" }, "description": "Valores de posição de aplicação." }, "IDSpecificationValue": { "type": "array", "items": { "type": "string" }, "description": "Identificadores dos valores de posição." } } }, "HubProductAutopartsItem": { "type": "object", "description": "Veículo compatível do anúncio de autopeças.", "properties": { "IDHubProductAutoparts": { "type": "integer", "format": "int64", "description": "Identificador do veículo compatível." }, "IDHubProduct": { "type": "integer", "format": "int64", "nullable": true, "description": "Anúncio." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "nullable": true, "description": "Integração (conta de canal)." }, "IDProductHub": { "type": "string", "nullable": true, "description": "Código do anúncio no canal." }, "ProductId": { "type": "string", "nullable": true, "description": "Identificador do veículo no catálogo do canal." }, "Notes": { "type": "string", "nullable": true, "description": "Observações." }, "Brand": { "type": "string", "nullable": true, "description": "Marca do veículo." }, "Model": { "type": "string", "nullable": true, "description": "Modelo." }, "Year": { "type": "string", "nullable": true, "description": "Ano." }, "Trim": { "type": "string", "nullable": true, "description": "Acabamento." }, "ShortVersion": { "type": "string", "nullable": true, "description": "Versão." }, "Engine": { "type": "string", "nullable": true, "description": "Motor." }, "Fuel": { "type": "string", "nullable": true, "description": "Combustível." }, "Power": { "type": "string", "nullable": true, "description": "Potência." }, "BodyType": { "type": "string", "nullable": true, "description": "Carroceria." }, "Transmission": { "type": "string", "nullable": true, "description": "Transmissão." }, "Gear": { "type": "string", "nullable": true, "description": "Câmbio." }, "Doors": { "type": "string", "nullable": true, "description": "Portas." }, "Steering": { "type": "string", "nullable": true, "description": "Direção." }, "Traction": { "type": "string", "nullable": true, "description": "Tração." }, "Valves": { "type": "string", "nullable": true, "description": "Válvulas." }, "IDHubOrderClaim": { "type": "integer", "format": "int64", "nullable": true, "description": "Reclamação de compatibilidade associada." }, "IDOrder": { "type": "integer", "format": "int64", "nullable": true, "description": "Pedido relacionado à reclamação." }, "ClaimQuantity": { "type": "integer", "nullable": true, "description": "Quantidade de reclamações de compatibilidade." }, "HubProductAutopartsPosition": { "type": "array", "items": { "$ref": "#/components/schemas/HubProductAutopartsPositionItem" }, "description": "Posições de aplicação." } } }, "TypeInventorySummaryEnum": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Tipo de inventário: `1` Endereço · `2` SKU · `3` Livre · `4` Auditoria." }, "StatusSkuInventoryEnum": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ], "description": "Status do inventário: `1` Finalizado · `2` Aberto · `3` Em andamento · `4` Cancelado · `5` Processando · `6` Fim 1ª conferência · `7` Fim 2ª conferência · `8` Fim 3ª conferência · `9` Processando 2ª conf. · `10` Processando 3ª conf." }, "TypeInventorySummaryQuantityEnum": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Estratégia de tratamento de saldo na contagem: `1` Não compensar negativos (padrão) · `2` Somar quantidade reservada (em manuseio) · `3` Compensar negativos." }, "IDTypeQueueEnum": { "type": "integer", "enum": [ 1, 2 ], "description": "Tipo de item da fila: `1` Endereço · `2` SKU." }, "InventorySummaryCreate": { "type": "object", "required": [ "IDTypeInventorySummary", "IDStockKeepingUnitDistributionCenter", "IDStockKeepingUnitWarehouse", "InventoryDescription" ], "properties": { "IDTypeInventorySummary": { "allOf": [ { "$ref": "#/components/schemas/TypeInventorySummaryEnum" } ], "description": "Tipo do inventário (Endereço, SKU, Livre ou Auditoria)." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Centro de distribuição. Deve pertencer à empresa autenticada." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém. Precisa estar ativo (`Status = 1`) e pertencer ao centro de distribuição informado." }, "InventoryDescription": { "type": "string", "description": "Descrição livre que identifica o inventário." }, "IDTypeQuantity": { "allOf": [ { "$ref": "#/components/schemas/TypeInventorySummaryQuantityEnum" } ], "description": "Estratégia de tratamento de saldo na contagem. Quando omitido, vale `1` (Não compensar negativos). No frontend a opção \"Compensar saldo negativo = Sim\" envia `3`." } } }, "InventorySummaryUpdate": { "type": "object", "description": "Atualização do cabeçalho do inventário: muda status (finalizando conferências) ou atribui o colaborador da conferência corrente.", "properties": { "IDTypeStatusSkuInventory": { "allOf": [ { "$ref": "#/components/schemas/StatusSkuInventoryEnum" } ], "description": "Novo status. Os valores aceitos são apenas `6` (Fim 1ª conferência), `7` (Fim 2ª conferência) ou `8` (Fim 3ª conferência) — o sistema registra o timestamp correspondente. Outros valores são rejeitados conforme o status atual do inventário." }, "InventoryStartUser": { "type": "integer", "description": "Colaborador da 1ª conferência. Só pode ser atribuído enquanto o inventário ainda não passou do fim da 1ª (status `< 6`). Precisa ser usuário ativo (`Status = 1`) na empresa." }, "InventorySecondUserStart": { "type": "integer", "description": "Colaborador da 2ª conferência. Só pode ser atribuído quando o inventário está no status `6` (Fim 1ª conferência). Precisa ser usuário ativo na empresa." }, "InventoryThirdUserStart": { "type": "integer", "description": "Colaborador da 3ª conferência. Só pode ser atribuído quando o inventário está no status `7` (Fim 2ª conferência). Precisa ser usuário ativo na empresa." } } }, "InventorySummaryListItem": { "type": "object", "description": "Inventário (`StockKeepingUnitInventorySummary`) no formato retornado pela listagem.", "properties": { "IDStockKeepingUnitInventorySummary": { "type": "integer", "description": "Código do inventário." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "nullable": true, "description": "Centro de distribuição em que o inventário acontece." }, "DistributionCenterName": { "type": "string", "nullable": true, "description": "Nome do centro de distribuição." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Depósito sob inventário." }, "WarehouseName": { "type": "string", "description": "Nome do depósito." }, "IDTypeInventorySummary": { "$ref": "#/components/schemas/TypeInventorySummaryEnum", "description": "Tipo do inventário: `1` Endereço (varrer endereços), `2` SKU (lista de SKUs), `3` Livre, `4` Auditoria." }, "TypeInventorySummary": { "type": "string", "description": "Endereço / Sku / Livre / Auditoria." }, "IDTypeStatusSkuInventory": { "$ref": "#/components/schemas/StatusSkuInventoryEnum", "description": "Status do inventário: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado, `5` Processando, `6` Fim 1ª conferência, `7` Fim 2ª conferência, `8` Fim 3ª conferência, `9` Processando 2ª conf., `10` Processando 3ª conf." }, "TypeStatusSkuInventory": { "type": "string", "description": "Descrição textual do status." }, "IDTypeQuantity": { "$ref": "#/components/schemas/TypeInventorySummaryQuantityEnum", "description": "Política de quantidade no fechamento: `1` Não compensar negativos, `2` Somar quantidade reservada, `3` Compensar negativos." }, "InventoryDescription": { "type": "string", "nullable": true, "description": "Descrição livre do inventário." }, "RecordUserCreated": { "type": "string", "description": "Login do usuário que criou o inventário." }, "InventoryStartUser": { "type": "integer", "nullable": true, "description": "Colaborador da 1ª conferência (ID)." }, "InventoryStartUserLogin": { "type": "string", "nullable": true, "description": "Login do usuário que iniciou o inventário." }, "InventoryStartTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Início da 1ª conferência." }, "InventoryFirstFinishTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Fim da 1ª conferência." }, "InventorySecondUserStart": { "type": "integer", "nullable": true, "description": "Identificador do usuário que iniciou a 2ª conferência." }, "InventorySecondUserStartLogin": { "type": "string", "nullable": true, "description": "Login do usuário da 2ª conferência." }, "InventorySecondStartTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de início da 2ª conferência." }, "InventorySecondFinishTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de fim da 2ª conferência." }, "InventoryThirdUserStart": { "type": "integer", "nullable": true, "description": "Identificador do usuário da 3ª conferência." }, "InventoryThirdUserStartLogin": { "type": "string", "nullable": true, "description": "Login do usuário da 3ª conferência." }, "InventoryThirdStartTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de início da 3ª conferência." }, "InventoryThirdFinishTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de fim da 3ª conferência." }, "InventoryFinishUser": { "type": "string", "nullable": true, "description": "Login do colaborador que abriu/finalizou (`InventoryStartUser` resolvido)." }, "InventoryFinishTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Fim do inventário (geração dos ajustes de estoque)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Criação do inventário." }, "StockKeepingUnitInventorySummarySkuQueueCount": { "type": "integer", "description": "Quantidade de SKUs na fila." }, "StockKeepingUnitInventorySummaryLocationQueueCount": { "type": "integer", "description": "Quantidade de endereços na fila." } } }, "InventoryItemDetail": { "type": "object", "description": "Item contado (`StockKeepingUnitInventoryItems`) com os dados do SKU e do lote.", "properties": { "IDStockKeepingUnitInventoryItems": { "type": "integer", "description": "Código do item contado." }, "IDSku": { "type": "integer", "description": "Identificador do SKU contado." }, "SkuName": { "type": "string", "description": "Nome do SKU." }, "IDSkuCompany": { "type": "string", "description": "Código do produto na empresa." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal." }, "Batch": { "type": "integer", "nullable": true, "description": "Indica se o SKU usa controle de lote (`1` = sim)." }, "RastroControl": { "type": "integer", "nullable": true, "description": "SKU exige rastreabilidade (`1` = sim)." }, "BatchRequired": { "type": "integer", "nullable": true, "description": "Lote obrigatório no lançamento (`1` = sim)." }, "BestBeforeRequired": { "type": "integer", "nullable": true, "description": "Data de validade obrigatória no lançamento (`1` = sim)." }, "QuantityBatch": { "type": "number", "nullable": true, "description": "Quantidade que o sistema esperava no lote (saldo apurado)." }, "QuantityInventory": { "type": "number", "nullable": true, "description": "Quantidade contada na 1ª conferência." }, "QuantityInventorySecond": { "type": "number", "nullable": true, "description": "Quantidade contada na 2ª conferência." }, "QuantityInventoryThird": { "type": "number", "nullable": true, "description": "Quantidade contada na 3ª conferência." }, "QuantityInventoryDiff": { "type": "number", "nullable": true, "description": "Diferença `QuantityInventory - QuantityBatch` (calculada)." }, "QuantityInventorySecondDiff": { "type": "number", "nullable": true, "description": "Diferença entre a quantidade contada na 2ª conferência e a quantidade do sistema." }, "QuantityInventoryThirdDiff": { "type": "number", "nullable": true, "description": "Diferença entre a quantidade contada na 3ª conferência e a quantidade do sistema." }, "IDBatch": { "type": "integer", "nullable": true, "description": "Código do lote contado." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de validade (vazia quando o sistema usa `4000-01-01` como sentinel)." }, "ManufacturingDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de fabricação do lote contado (quando o SKU é controlado por lote)." }, "BatchComments": { "type": "string", "nullable": true, "description": "Número do lote informado." }, "IDStockKeepingUnitLocation": { "type": "integer", "nullable": true, "description": "Endereço onde o lote está localizado." }, "Address": { "type": "string", "nullable": true, "description": "Descrição do endereço." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém do item." }, "WarehouseName": { "type": "string", "nullable": true, "description": "Nome do depósito do item." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "BarCodeList": { "type": "array", "description": "Códigos de barras alternativos do SKU.", "items": { "type": "string" } }, "BarCodePackageList": { "type": "array", "description": "Códigos de barras de embalagem (caixa, fardo) com fator de conversão.", "items": { "type": "object", "properties": { "IDStockKeepingUnitBarCodePackage": { "type": "integer", "description": "Identificador do código de barras de embalagem aceito para esta contagem (permite contar a caixa em vez da unidade)." }, "BarCodePackage": { "type": "string", "description": "Código de barras da embalagem." }, "PackageFactor": { "type": "number", "description": "Quantidade de unidades dentro da embalagem (multiplica a contagem)." } } } }, "MainImageThumbnailURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do SKU (thumbnail)." } } }, "InventorySkuQueueItem": { "type": "object", "description": "SKU presente na fila de contagem (`StockKeepingUnitInventorySummarySkuQueue`).", "properties": { "IDStockKeepingUnitInventorySummarySkuQueue": { "type": "integer", "description": "Identificador da entrada do SKU na fila de contagem do inventário." }, "IDSku": { "type": "integer", "description": "Identificador do SKU enfileirado para contagem." }, "SkuName": { "type": "string", "description": "Nome do SKU enfileirado." }, "IDSkuCompany": { "type": "string", "description": "Código de referência interno do SKU, definido pela empresa (campo `IDSkuCompany`)." } } }, "InventoryLocationQueueItem": { "type": "object", "description": "Endereço presente na fila de contagem (`StockKeepingUnitInventorySummaryLocationQueue`).", "properties": { "IDStockKeepingUnitInventorySummarySkuQueue": { "type": "integer", "description": "Mantido por compatibilidade — corresponde ao ID da fila de endereço." }, "IDStockKeepingUnitLocation": { "type": "integer", "description": "Identificador do endereço de armazenagem (rua/coluna/nível) incluído na fila de contagem do inventário." }, "Address": { "type": "string", "description": "Descrição do endereço." } } }, "InventorySummaryDetail": { "allOf": [ { "$ref": "#/components/schemas/InventorySummaryListItem" }, { "type": "object", "description": "Detalhe completo do inventário, retornado por `GET /sku/inventory-summary/{id}`. Inclui o tipo de quantidade resolvido, a lista de itens contados e as filas de SKUs e endereços.", "properties": { "TypeInventorySummaryQuantity": { "type": "string", "description": "Descrição textual (Não compensar negativos / Somar quantidade reservada / Compensar negativos)." }, "Items": { "type": "array", "description": "Itens contados (uma linha por SKU + lote).", "items": { "$ref": "#/components/schemas/InventoryItemDetail" } }, "StockKeepingUnitInventorySummarySkuQueue": { "type": "array", "description": "Fila de SKUs a inventariar (inventário tipo SKU).", "items": { "$ref": "#/components/schemas/InventorySkuQueueItem" } }, "StockKeepingUnitInventorySummaryLocationQueue": { "type": "array", "description": "Fila de endereços a inventariar (inventário tipo Endereço), ordenada para otimizar o percurso de picking quando os endereços têm coordenadas (`Floor`, `Street`, `Module`, `Column`, `Level`, `LocationSide`).", "items": { "$ref": "#/components/schemas/InventoryLocationQueueItem" } } } } ] }, "InventoryItemUpdate": { "type": "array", "description": "Lançamento de quantidade contada de um item. O sistema lê apenas a posição `[0]`. O sistema decide automaticamente em qual conferência a quantidade é registrada (1ª, 2ª ou 3ª) com base no status atual do inventário; campos das demais conferências são ignorados.", "items": { "type": "object", "properties": { "QuantityInventory": { "type": "number", "description": "Quantidade contada na 1ª conferência." }, "QuantityInventorySecond": { "type": "number", "description": "Quantidade contada na 2ª conferência. Quando informada e a 2ª conferência ainda não foi iniciada, o sistema atribui o usuário corrente como colaborador da 2ª e muda o status para `9` (Processando 2ª conf.)." }, "QuantityInventoryThird": { "type": "number", "description": "Quantidade contada na 3ª conferência. Quando informada e a 3ª conferência ainda não foi iniciada, o sistema atribui o usuário corrente como colaborador da 3ª e muda o status para `10` (Processando 3ª conf.)." }, "BestBeforeDate": { "type": "string", "format": "date", "description": "Data de validade do lote. Obrigatória quando o SKU tem `BestBeforeRequired = 1`." }, "ManufacturingDate": { "type": "string", "format": "date", "description": "Data de fabricação. Obrigatória quando o SKU tem `RastroControl = 1`." }, "BatchComments": { "type": "string", "description": "Número do lote informado. Obrigatório quando o SKU tem `BatchRequired = 1`." } } } }, "InventorySkuQueueAdd": { "description": "Item ou itens a adicionar na fila ou lançar contagem. Quando enviado como objeto único, processa apenas aquele; como array, processa um a um.\n\n- `IDTypeQueue=1` (Endereço) → o objeto deve conter `IDStockKeepingUnitLocation`.\n- `IDTypeQueue=2` (SKU) → o objeto deve conter `IDSku`.\n- Sem `IDTypeQueue` → lançamento de **contagem livre**; deve conter `IDSku`, `IDStockKeepingUnitWarehouse` e `QuantityInventory` (lote/validade/fabricação opcionais).", "oneOf": [ { "$ref": "#/components/schemas/InventorySkuQueueAddItem" }, { "type": "array", "items": { "$ref": "#/components/schemas/InventorySkuQueueAddItem" } } ] }, "InventorySkuQueueAddItem": { "type": "object", "properties": { "IDSku": { "type": "integer", "description": "SKU. Obrigatório para `IDTypeQueue=2` e para lançamento de contagem livre. Precisa ser do tipo Sku, Matéria-prima ou Uso e consumo (`IDTypeSku IN (3, 6, 7)`) e pertencer à empresa." }, "IDStockKeepingUnitLocation": { "type": "integer", "description": "Endereço. Obrigatório para `IDTypeQueue=1`. Precisa pertencer a um armazém do centro de distribuição do inventário." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém da contagem. Obrigatório para lançamento de contagem livre." }, "QuantityInventory": { "type": "number", "description": "Quantidade contada. Quando informada, distribui o saldo entre os lotes existentes (mais novo primeiro, com saldo positivo) e ajusta automaticamente." }, "IDBatchNumber": { "type": "integer", "description": "Lote específico (opcional). Quando enviado, a quantidade é lançada diretamente neste lote." }, "BestBeforeDate": { "type": "string", "format": "date", "description": "Data de validade do lote a contar no inventário, no formato `YYYY-MM-DD`. Obrigatória quando o SKU exige rastreabilidade de validade." }, "ManufacturingDate": { "type": "string", "format": "date", "description": "Data de fabricação do lote a contar, no formato `YYYY-MM-DD`. Obrigatória quando o SKU exige rastreabilidade de lote." }, "BatchComments": { "type": "string", "description": "Número do lote informado." } } }, "InventoryFinishResult": { "type": "string", "description": "Retorna a string literal `\"sucesso\"` quando o inventário foi finalizado. Os ajustes de estoque (entradas/saídas em `StockKeepingUnitMovement`) são gerados de forma assíncrona durante o processamento, e uma notificação `SkuBalanceInventoryFinish` é publicada no webhook configurado.", "example": "sucesso" }, "InventoryQueueAddError": { "type": "object", "description": "Erro parcial de adição em lote — quando a requisição envia um array, itens inválidos são acumulados aqui em vez de interromper a operação.", "properties": { "IDSku": { "type": "integer", "description": "SKU que falhou ao ser adicionado à fila de contagem." }, "Armazem": { "type": "integer", "description": "Identificador do armazém (`IDStockKeepingUnitWarehouse`) em que o SKU não pôde ser enfileirado (ex.: armazém não pertence à empresa ou não tem endereços ativos)." }, "Lote": { "type": "integer", "description": "Identificador do lote (`IDBatchNumber`) que falhou ao ser enfileirado. `0` quando o SKU não usa controle de lote." }, "Description": { "type": "string", "description": "Causa do erro: `Sku não existe`, `Armazém não existe`, `Lote não existe`." }, "Status": { "type": "integer", "enum": [ 0 ], "description": "Sempre `0` (falha)." } } }, "SkuMovementListItem": { "type": "object", "description": "Linha da listagem padrão de movimentação de estoque.", "properties": { "AccountName": { "type": "string", "description": "Conta (subdomínio) à qual o SKU pertence." }, "IDSkuMovement": { "type": "integer", "description": "Identificador único da movimentação." }, "IDSku": { "type": "integer", "description": "SKU envolvido na movimentação." }, "SkuName": { "type": "string", "description": "Nome do produto (concatenado com o nome do produto-pai em variações; respeita a parametrização `OnlySkuName`)." }, "IDSkuCompany": { "type": "string", "description": "Código de referência do SKU." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal do SKU." }, "Brand": { "type": "string", "nullable": true, "description": "Nome da marca do SKU." }, "CostSet": { "type": "number", "format": "float", "nullable": true, "description": "Custo manual cadastrado na ficha do SKU." }, "IDTypeMovement": { "type": "integer", "description": "Sentido da movimentação. `0` = entrada, `1` = saída.", "enum": [ 0, 1 ] }, "TypeSkuMovement": { "type": "string", "description": "Texto do sentido — `Entrada` quando `IDTypeMovement = 0`, `Saída` quando `IDTypeMovement = 1`.", "enum": [ "Entrada", "Saída" ] }, "TypeMovement": { "type": "string", "nullable": true, "description": "Origem da movimentação: `Recebimento`, `Venda`, `Transferência CD`, `Transferência endereço`, `Ajuste saldo estoque`, `Inventário`, `Produção`." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que a movimentação foi registrada." }, "DateLastRecordModification": { "type": "string", "format": "date-time", "nullable": true, "description": "Última modificação do registro — útil para o filtro `SinceDateLastRecordModification`." }, "Quantity": { "type": "number", "description": "Quantidade movimentada (sempre positiva — o sentido vem de `IDTypeMovement`)." }, "BalanceChange": { "type": "integer", "description": "`1` se a movimentação alterou o saldo físico; `0` se foi apenas registro fiscal (ex.: NF simplificada ou pedido do tipo Nota Fiscal sem movimentação de saldo).", "enum": [ 0, 1 ] }, "IDStatusSku": { "type": "integer", "nullable": true, "description": "Status do SKU na movimentação (`1` = saudável, `0` = não conformidade).", "enum": [ 0, 1, 2, 3, 4 ] }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém em que a movimentação aconteceu." }, "WarehouseName": { "type": "string", "description": "Nome do armazém da movimentação." }, "IDBatch": { "type": "integer", "nullable": true, "description": "Lote do item movimentado." }, "BatchComments": { "type": "string", "nullable": true, "description": "Descrição do lote." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Validade do lote." }, "ManufacturingDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de fabricação do lote." }, "Comments": { "type": "string", "nullable": true, "description": "Comentário livre da movimentação." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido que originou a movimentação (quando é venda)." }, "Order": { "type": "string", "nullable": true, "description": "Número/identificador do pedido." }, "IDPurchase": { "type": "integer", "nullable": true, "description": "Recebimento que originou a movimentação (quando é entrada de compra)." }, "IDStockKeepingUnitProduction": { "type": "integer", "nullable": true, "description": "Ordem de produção que originou a movimentação." }, "IDOriginIDSkuMovement": { "type": "integer", "nullable": true, "description": "Movimentação de origem (preenchida no par origem/destino de transferências)." }, "IDStockKeepingUnitInventory": { "type": "integer", "nullable": true, "description": "Conferência de inventário associada (quando aplicável)." }, "IDStockKeepingUnitInventorySummary": { "type": "integer", "nullable": true, "description": "Resumo de inventário associado." }, "IDTypeFulfillmentNonconformity": { "type": "integer", "nullable": true, "description": "Tipo de não conformidade no fulfillment (quando aplicável).", "enum": [ 1, 2, 4, 5, 6 ] }, "TypeFulfillmentNonconformity": { "type": "string", "nullable": true, "description": "Texto da não conformidade (resolvido a partir de `IDTypeFulfillmentNonconformity` via consulta)." }, "QuantityNonconformity": { "type": "number", "nullable": true, "description": "Quantidade marcada em não conformidade." }, "PriceSelling": { "type": "number", "format": "float", "nullable": true, "description": "Preço unitário de venda (preço total dividido pela quantidade)." }, "PriceSellingTotal": { "type": "number", "format": "float", "nullable": true, "description": "Preço total da venda (lado de saída)." }, "ValueCost": { "type": "number", "format": "float", "nullable": true, "description": "Custo unitário (custo total dividido pela quantidade). Somente para usuários com privilégio de visualização de custo." }, "ValueCostTotal": { "type": "number", "format": "float", "nullable": true, "description": "Custo total da movimentação." }, "ValueCostUnitPurchase": { "type": "number", "format": "float", "nullable": true, "description": "Alias de `ValueCost` para a listagem padrão (manter retrocompatibilidade do frontend)." }, "NfeIpiValue": { "type": "number", "format": "float", "nullable": true, "description": "Valor do IPI vinculado à movimentação (NF de entrada)." }, "NfeIcmsSTValue": { "type": "number", "format": "float", "nullable": true, "description": "Valor do ICMS-ST destacado para o item." }, "NfeFcpSTValue": { "type": "number", "format": "float", "nullable": true, "description": "Valor do FCP-ST destacado para o item." }, "ValueDiscount": { "type": "number", "format": "float", "nullable": true, "description": "Valor de desconto destacado para o item." }, "NfeCFOP": { "type": "string", "nullable": true, "description": "CFOP da NF associada." }, "NfeNumber": { "type": "integer", "nullable": true, "description": "Número da NF associada (de venda para `IDTypeMovement = 1`, de entrada para `IDTypeMovement = 0`)." }, "NfeDhEmi": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de emissão da NF associada." }, "IDStatusInvoice": { "type": "integer", "nullable": true, "description": "Identificador do status da NF." }, "StatusInvoice": { "type": "string", "nullable": true, "description": "Texto do status da NF (`Pendente`, `Emitida`, `Erro`, `Cancelada`)." }, "IDStatusOrder": { "type": "integer", "nullable": true, "description": "Status do pedido (quando origem é venda)." }, "StatusOrder": { "type": "string", "nullable": true, "description": "Status atual do pedido associado à movimentação (`Aberto`, `Faturado`, `Cancelado`, etc.). Vazio para movimentações sem pedido." }, "TypeOrder": { "type": "string", "nullable": true, "description": "Tipo do pedido (cadastrado em Tipo Pedido)." }, "IDOrderType": { "type": "integer", "nullable": true, "description": "Tipo do pedido associado à movimentação (venda, devolução, transferência, etc.). Vazio para movimentações sem pedido." }, "OrderFrom": { "type": "string", "nullable": true, "description": "Origens declaradas no pedido, sem repetições." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Canal de venda (integração) que originou o pedido. Vazio para movimentações sem pedido." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Nome da integração concatenado: `TipoIntegração - NomeIntegração`." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Filial faturadora do pedido associado. Vazio quando não se aplica." }, "CompanyInvoiceNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social da empresa faturadora." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Conta da empresa faturadora." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Nome ou razão social do cliente do pedido." }, "ConsumerCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ do cliente do pedido associado." }, "ConsumerEmail": { "type": "string", "nullable": true, "description": "E-mail do cliente do pedido associado." }, "IDConsumer": { "type": "integer", "nullable": true, "description": "Identificador do cliente do pedido associado." }, "ShippingState": { "type": "string", "nullable": true, "description": "UF de entrega do pedido." }, "InvoiceFinishTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de finalização do recebimento (quando origem é compra)." }, "CheckinTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de check-in do recebimento." }, "Login": { "type": "string", "nullable": true, "description": "Usuário responsável pela transferência ou ajuste (resolvido a partir do `IDUser` registrado em `StockKeepingUnitMovementTransfer` ou `StockKeepingUnitInventory`)." }, "IsTransfer": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se o tipo do pedido é de transferência entre centros de distribuição (`1`) ou não (`0`). Nulo quando a movimentação não está vinculada a um pedido." } } }, "SkuMovementKardexItem": { "type": "object", "description": "Linha do Kardex: para uma combinação SKU + armazém, mostra a movimentação com saldo acumulado e custo médio acumulado.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio (conta) da empresa dona da movimentação." }, "IDSkuMovement": { "type": "integer", "description": "Identificador da movimentação no kardex." }, "IDSku": { "type": "integer", "description": "SKU movimentado." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que a movimentação foi registrada." }, "DateCreated": { "type": "string", "format": "date-time", "description": "Data efetiva — usa `RecordTimestamp` do pedido (se venda) ou do recebimento (se entrada de compra); caso contrário a data da própria movimentação." }, "IDTypeMovement": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo da movimentação: `0` Saída, `1` Entrada." }, "TypeSkuMovement": { "type": "string", "enum": [ "Entrada", "Saída" ], "description": "Descrição textual do tipo: `Entrada` ou `Saída`." }, "TypeMovement": { "type": "string", "nullable": true, "description": "Origem da movimentação: `Recebimento`, `Venda`, `Transferência CD`, `Transferência endereço`, `Ajuste saldo estoque`, `Inventário`, `Produção`." }, "Login": { "type": "string", "nullable": true, "description": "Nome do usuário responsável pela movimentação (transferência ou ajuste manual de inventário). Nulo para movimentações geradas por venda, recebimento ou produção." }, "IDPurchase": { "type": "integer", "nullable": true, "description": "Recebimento que originou a movimentação. Vazio quando não veio de recebimento." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido de venda que originou a movimentação. Vazio quando não veio de pedido." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém da movimentação." }, "IDStockKeepingUnitProduction": { "type": "integer", "nullable": true, "description": "Ordem de produção que originou a movimentação. Vazio quando não veio de produção." }, "IDOriginIDSkuMovement": { "type": "integer", "nullable": true, "description": "Movimentação de origem em transferências/devoluções/estornos (aponta para a movimentação espelhada). Vazio em movimentações originais." }, "IDStockKeepingUnitInventory": { "type": "integer", "nullable": true, "description": "Acerto de inventário (linha individual) que originou a movimentação. Vazio quando não veio de inventário." }, "IDStockKeepingUnitInventorySummary": { "type": "integer", "nullable": true, "description": "Inventário (cabeçalho) que originou a movimentação. Vazio quando não veio de inventário." }, "Quantity": { "type": "number", "description": "Quantidade da movimentação atual (sempre positiva)." }, "ValueCost": { "type": "number", "format": "float", "description": "Custo unitário (custo total dividido pela quantidade)." }, "ValueCostTotal": { "type": "number", "format": "float", "description": "Custo total da movimentação." }, "CardexQty": { "type": "number", "description": "Saldo acumulado **após** esta linha. Calculado como soma cumulativa de entradas (entrada com `IDStatusSku = 1`) menos saídas, ordenado por `RecordTimestamp, IDSkuMovement`." }, "CardexValueCost": { "type": "number", "format": "float", "description": "Custo total acumulado **após** esta linha." }, "CardexAverageValueCost": { "type": "number", "format": "float", "description": "Custo médio acumulado = `CardexValueCost / CardexQty`, com duas casas decimais. `0` quando saldo acumulado é zero." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres da movimentação." }, "StatusInvoice": { "type": "string", "nullable": true, "description": "Status da NF-e associada à movimentação (`Pendente`, `Autorizada`, `Cancelada`, etc.). Vazio quando a movimentação não tem NF-e." }, "TypeFulfillmentNonconformity": { "type": "string", "nullable": true, "description": "Descrição do tipo de não conformidade quando a movimentação é uma divergência (avaria, falta, divergência de SKU). Vazio em movimentações normais." }, "IsTransfer": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se o tipo do pedido é de transferência entre centros de distribuição (`1`) ou não (`0`). Nulo quando a movimentação não está vinculada a um pedido." } } }, "SkuMovementKardexLocationItem": { "type": "object", "description": "Linha do Kardex por endereço: ordena cronologicamente as movimentações de um SKU em um endereço específico.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio (conta) da empresa dona da movimentação." }, "IDSkuMovement": { "type": "integer", "description": "Identificador da movimentação." }, "IDSku": { "type": "integer", "description": "SKU movimentado." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que a movimentação foi registrada." }, "DateCreated": { "type": "string", "format": "date-time", "description": "Data (sem hora) do dia da movimentação — usada para agrupamento por dia no relatório." }, "IDTypeMovement": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo da movimentação: `0` Saída, `1` Entrada." }, "TypeSkuMovement": { "type": "string", "enum": [ "Entrada", "Saída" ], "description": "Descrição textual do tipo: `Entrada` ou `Saída`." }, "TypeMovement": { "type": "string", "nullable": true, "description": "Origem da movimentação: `Recebimento`, `Venda`, `Transferência CD`, `Transferência endereço`, `Ajuste saldo estoque`, `Inventário`, `Produção`." }, "IDPurchase": { "type": "integer", "nullable": true, "description": "Recebimento que originou a movimentação. Vazio quando não veio de recebimento." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido de venda que originou a movimentação. Vazio quando não veio de pedido." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém em que a movimentação ocorreu." }, "IDStockKeepingUnitLocation": { "type": "integer", "description": "Endereço de armazenagem (rua/coluna/nível) movimentado." }, "IDBatch": { "type": "integer", "nullable": true, "description": "Lote movimentado. Vazio quando o SKU não usa controle de lote." }, "Quantity": { "type": "number", "description": "Quantidade movimentada (positiva)." }, "CardexQty": { "type": "number", "description": "Saldo acumulado no endereço após esta linha." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres da movimentação." }, "IsTransfer": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se o tipo do pedido é de transferência entre centros de distribuição (`1`) ou não (`0`). Nulo quando a movimentação não está vinculada a um pedido." } } }, "SkuMovementInboundItem": { "type": "object", "description": "Linha de entrada (recebimento) com dados de NF-e de compra e fornecedor.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio (conta) da empresa dona da movimentação." }, "IDSkuMovement": { "type": "integer", "description": "Identificador da movimentação de entrada." }, "IDSku": { "type": "integer", "description": "SKU que entrou em estoque." }, "IDSkuCompany": { "type": "string", "description": "Código de referência interno do SKU, definido pela empresa." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal do SKU." }, "IDTypeMovement": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo da movimentação: `0` Entrada, `1` Saída. Para a modalidade `SkuInbound` o valor é `0`." }, "TypeSkuMovement": { "type": "string", "enum": [ "Entrada", "Saída" ], "description": "Descrição textual do tipo: `Entrada` ou `Saída`." }, "TypeMovement": { "type": "string", "nullable": true, "description": "Origem da movimentação: `Recebimento`, `Venda`, `Transferência CD`, `Transferência endereço`, `Ajuste saldo estoque`, `Inventário`, `Produção`." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que a movimentação foi registrada." }, "BalanceChange": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando a movimentação altera o saldo de estoque; `0` quando é apenas registro contábil/fiscal sem efeito em saldo." }, "Quantity": { "type": "number", "description": "Quantidade movimentada na entrada." }, "ValueCost": { "type": "number", "format": "float", "description": "Custo unitário da entrada (já com rateio de frete/impostos quando aplicável)." }, "ValueCostTotal": { "type": "number", "format": "float", "description": "Custo total da entrada (`ValueCost × Quantity`)." }, "NfeIpiValue": { "type": "number", "format": "float", "nullable": true, "description": "Valor do IPI destacado para o item na NF-e de entrada." }, "NfeIcmsSTValue": { "type": "number", "format": "float", "nullable": true, "description": "Valor do ICMS-ST destacado para o item na NF-e de entrada." }, "NfeFcpSTValue": { "type": "number", "format": "float", "nullable": true, "description": "Valor do FCP-ST destacado para o item na NF-e de entrada." }, "ValueDiscount": { "type": "number", "format": "float", "nullable": true, "description": "Valor de desconto destacado para o item na NF-e de entrada." }, "NfeCFOP": { "type": "string", "nullable": true, "description": "CFOP do item na NF-e de entrada (4 dígitos)." }, "NfeNumber": { "type": "integer", "nullable": true, "description": "Número da NF-e de entrada." }, "NfeDhEmi": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de emissão da NF-e de entrada." }, "IDPurchase": { "type": "integer", "nullable": true, "description": "Recebimento (`StockKeepingUnitPurchase`) que originou a movimentação. Vazio para entradas avulsas (acerto de inventário, transferência)." }, "InvoiceFinishTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora em que o recebimento foi finalizado (estoque atualizado). Vazio enquanto o recebimento está aberto/em conferência." }, "CheckinTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora do check-in do recebimento (chegada física da carga)." }, "IDSupplier": { "type": "integer", "nullable": true, "description": "Fornecedor do recebimento. Vazio em entradas sem fornecedor (acerto, transferência interna)." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do fornecedor." }, "SupplierCode": { "type": "string", "nullable": true, "description": "Código que o fornecedor usa para o item (extraído do XML da NF de entrada)." }, "NfevProd": { "type": "number", "format": "float", "nullable": true, "description": "Valor do produto declarado no XML da NF de entrada." }, "IDBatch": { "type": "integer", "nullable": true, "description": "Lote movimentado. Vazio quando o SKU não usa controle de lote." }, "WarehouseName": { "type": "string", "description": "Nome do armazém de destino da entrada." }, "Address": { "type": "string", "nullable": true, "description": "Endereço físico em que o item foi alocado." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres da movimentação." }, "Login": { "type": "string", "nullable": true, "description": "Login do usuário que registrou a movimentação." } } }, "SkuMovementOutboundItem": { "type": "object", "description": "Linha de saída (venda) com dados de NF-e de venda e do pedido.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio (conta) da empresa dona da movimentação." }, "IDSkuMovement": { "type": "integer", "description": "Identificador da movimentação de saída." }, "IDSku": { "type": "integer", "description": "SKU que saiu do estoque." }, "IDSkuCompany": { "type": "string", "description": "Código de referência interno do SKU, definido pela empresa." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal do SKU." }, "IDTypeMovement": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo da movimentação: `0` Entrada, `1` Saída. Para a modalidade `SkuOutbound` o valor é `1`." }, "TypeSkuMovement": { "type": "string", "enum": [ "Entrada", "Saída" ], "description": "Descrição textual do tipo: `Entrada` ou `Saída`." }, "TypeMovement": { "type": "string", "nullable": true, "description": "Origem da movimentação: `Recebimento`, `Venda`, `Transferência CD`, `Transferência endereço`, `Ajuste saldo estoque`, `Inventário`, `Produção`." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que a movimentação foi registrada." }, "BalanceChange": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando a movimentação altera o saldo de estoque; `0` quando é apenas registro contábil/fiscal sem efeito em saldo." }, "Quantity": { "type": "number", "description": "Quantidade movimentada na saída." }, "PriceSelling": { "type": "number", "format": "float", "description": "Preço de venda unitário aplicado." }, "PriceSellingTotal": { "type": "number", "format": "float", "description": "Valor total da venda da linha (`PriceSelling × Quantity`)." }, "ValueCost": { "type": "number", "format": "float", "description": "Custo unitário do item baixado (custo médio do SKU no momento da saída)." }, "ValueCostTotal": { "type": "number", "format": "float", "description": "Custo total baixado da linha (`ValueCost × Quantity`)." }, "NfeCFOP": { "type": "string", "nullable": true, "description": "CFOP do item na NF-e de saída (4 dígitos)." }, "NfeNumber": { "type": "integer", "nullable": true, "description": "Número da NF-e de saída." }, "NfeDhEmi": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora de emissão da NF-e de saída." }, "IDStatusInvoice": { "type": "integer", "nullable": true, "description": "Status da NF: `0` Pendente, `1` Erro, `2` Enviada, `3` Emitida, `4` Processando, `5` Pendente Conciliação EPEC, `6` Erro Conciliação EPEC, `7` Cancelada, `8` Denegada, `9` Inutilizada." }, "StatusInvoice": { "type": "string", "nullable": true, "description": "Descrição textual do status da NF-e (referente a `IDStatusInvoice`)." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido de venda que originou a saída. Vazio para saídas avulsas." }, "Order": { "type": "string", "nullable": true, "description": "Código externo do pedido (número visível ao cliente)." }, "OrderFrom": { "type": "string", "nullable": true, "description": "Origem do pedido (canal/marketplace ou loja física)." }, "IDStatusOrder": { "type": "integer", "nullable": true, "description": "Status do pedido (referência: `TypeStatusOrder`)." }, "StatusOrder": { "type": "string", "nullable": true, "description": "Descrição amigável do status do pedido." }, "TypeOrder": { "type": "string", "nullable": true, "description": "Descrição do tipo do pedido (venda, devolução, transferência, etc.)." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração (canal de venda) do pedido." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Nome da integração (canal de venda)." }, "CompanyInvoiceNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social da filial faturadora do pedido." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Identificador da filial faturadora do pedido." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social ou nome do cliente do pedido." }, "ConsumerCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ do cliente do pedido." }, "ConsumerEmail": { "type": "string", "nullable": true, "description": "E-mail do cliente do pedido." }, "ShippingState": { "type": "string", "nullable": true, "description": "UF de entrega do pedido (sigla com 2 letras)." }, "IDTypeFulfillmentNonconformity": { "type": "integer", "nullable": true, "description": "Tipo da não conformidade da movimentação (avaria, falta, divergência de SKU). Vazio em movimentações normais.", "enum": [ 1, 2, 4, 5, 6 ] }, "TypeFulfillmentNonconformity": { "type": "string", "nullable": true, "description": "Descrição amigável da não conformidade." }, "QuantityNonconformity": { "type": "number", "nullable": true, "description": "Quantidade registrada como não conformidade na movimentação." }, "IDBatch": { "type": "integer", "nullable": true, "description": "Lote baixado. Vazio quando o SKU não usa controle de lote." }, "WarehouseName": { "type": "string", "description": "Nome do armazém de origem da saída." }, "Address": { "type": "string", "nullable": true, "description": "Endereço (rua/coluna/nível) de onde o SKU foi separado." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres da movimentação." }, "Login": { "type": "string", "nullable": true, "description": "Login do usuário que registrou a movimentação." }, "IsTransfer": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se o tipo do pedido é de transferência entre centros de distribuição (`1`) ou não (`0`). Nulo quando a movimentação não está vinculada a um pedido." } } }, "SkuMovementFiscalConciliationItem": { "type": "object", "description": "Linha da árvore de lotes consolidada (CTE recursiva). Para cada lote origem mostra movimentações descendentes e o saldo líquido.", "properties": { "IDSkuMovement": { "type": "integer", "description": "Identificador da movimentação de estoque conciliada com a nota fiscal." }, "IDPurchase": { "type": "integer", "nullable": true, "description": "Recebimento (`StockKeepingUnitPurchase`) que originou a movimentação. Vazio para movimentações de saída ou avulsas." }, "IDSku": { "type": "integer", "description": "SKU movimentado." }, "IDBatch": { "type": "integer", "nullable": true, "description": "Lote movimentado. Vazio quando o SKU não usa controle de lote." }, "IDTypeMovement": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo da movimentação para conciliação fiscal: `0` Saída, `1` Entrada." }, "IDOriginIDSkuMovement": { "type": "integer", "nullable": true, "description": "Movimentação de origem em casos de transferência/devolução/estorno (aponta para a movimentação espelhada). Vazio em movimentações originais." }, "BatchPath": { "type": "string", "description": "Caminho da árvore de lotes, ex.: `100>120>135`." }, "Quantity": { "type": "number", "description": "Quantidade movimentada (positiva)." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido de venda associado à saída. Vazio para entradas e movimentações sem pedido." }, "IDBatchOrigin": { "type": "integer", "description": "Lote raiz (recebimento original)." }, "BalanceChange": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando a movimentação altera o saldo de estoque; `0` quando é apenas registro fiscal sem efeito em saldo." }, "dhEmi": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de emissão da NF-e do recebimento original." }, "nNF": { "type": "integer", "nullable": true, "description": "Número da NF-e do recebimento original." }, "chNFe": { "type": "string", "nullable": true, "description": "Chave de acesso da NF-e do recebimento original." }, "InvoiceFinishTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora da finalização da NF-e que conciliou esta movimentação. Vazio enquanto a NF-e não está conciliada." }, "BalanceQuantity": { "type": "number", "description": "Quantidade líquida do lote (entradas menos saídas)." } } }, "SkuMovementTransferBody": { "type": "object", "description": "Corpo da requisição de transferência. A transferência pode ser **entre armazéns** (use `IDStockKeepingUnitWarehouseFrom` + `IDStockKeepingUnitWarehouseTo`) ou **entre lotes/endereços** (use `IDBatchFrom` + `IDBatchTo` ou `IDStockKeepingUnitLocationTo`). Origem e destino precisam estar no mesmo Centro de Distribuição.", "required": [ "IDSku", "Quantity" ], "properties": { "IDSku": { "type": "integer", "description": "SKU a ser transferido. Precisa ser do tipo Sku (`IDTypeSku = 3`), Matéria-prima (`6`) ou Uso e consumo (`7`)." }, "Quantity": { "type": "number", "description": "Quantidade a transferir. Precisa ser maior que zero." }, "IDStockKeepingUnitWarehouseFrom": { "type": "integer", "description": "Armazém de origem (transferência entre armazéns)." }, "IDStockKeepingUnitWarehouseTo": { "type": "integer", "description": "Armazém de destino (transferência entre armazéns)." }, "IDBatchFrom": { "type": "integer", "description": "Lote de origem (transferência entre lotes/endereços)." }, "IDBatchTo": { "type": "integer", "description": "Lote de destino (transferência entre lotes/endereços). Quando ausente, o sistema procura um lote compatível no endereço de destino — ou cria um novo se nenhum bate." }, "IDStockKeepingUnitLocationTo": { "type": "integer", "description": "Endereço físico de destino (alternativa a `IDBatchTo`). Combinado com `IDBatchFrom`, o sistema escolhe ou cria o lote de destino conforme as parametrizações `KeepUniqueBatchForFiscalConciliation` e `AllowSameItemDifferentBatchSameLocation`." }, "Comments": { "type": "string", "nullable": true, "description": "Comentário livre que fica gravado nas duas movimentações geradas." } } }, "SkuMovementTransferResponseItem": { "type": "object", "description": "Linha de movimentação criada pela transferência, com dados do lote. A resposta vem como array com duas linhas (saída + entrada).", "properties": { "IDSkuMovement": { "type": "integer", "description": "Identificador da movimentação gerada pela transferência (uma linha de saída na origem e uma de entrada no destino — este objeto descreve uma delas)." }, "IDSku": { "type": "integer", "description": "SKU transferido." }, "IDTypeMovement": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo da movimentação: `0` Saída (perna de saída da origem), `1` Entrada (perna de entrada no destino)." }, "IDStatusSku": { "type": "integer", "description": "Status do SKU na movimentação (referência: `TypeStatusSku`).", "enum": [ 0, 1, 2, 3, 4 ] }, "Quantity": { "type": "number", "description": "Quantidade transferida." }, "ValueCostTotal": { "type": "number", "format": "float", "description": "Custo total da movimentação transferida (preserva o custo médio da origem)." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém da movimentação (origem na perna de saída, destino na perna de entrada)." }, "IDBatch": { "type": "integer", "nullable": true, "description": "Lote transferido. Vazio quando o SKU não usa controle de lote." }, "IDOriginIDSkuMovement": { "type": "integer", "nullable": true, "description": "Movimentação espelhada — na perna de entrada aponta para a movimentação de saída correspondente; vazio na perna de saída." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres da transferência." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que a movimentação foi registrada." }, "IDStockKeepingUnitLocation": { "type": "integer", "nullable": true, "description": "Endereço (rua/coluna/nível) movimentado." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de validade do lote movimentado, no formato `YYYY-MM-DD`. Vazio quando o SKU não usa controle de validade." }, "ManufacturingDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de fabricação do lote movimentado, no formato `YYYY-MM-DD`. Vazio quando o SKU não usa controle de lote." } } }, "SkuMovementTransferBatchResponseItem": { "type": "object", "description": "Detalhamento de lote retornado quando `BatchResponse=1`. Lista todos os lotes ativos do SKU após a transferência, com endereço, saldo e quantidade disponível.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio (conta) da empresa dona do lote transferido." }, "IDBatchNumber": { "type": "integer", "description": "Identificador do lote transferido." }, "IDSku": { "type": "integer", "description": "SKU do lote transferido." }, "IDSkuCompany": { "type": "string", "description": "Código de referência interno do SKU, definido pela empresa." }, "SkuName": { "type": "string", "description": "Nome do SKU." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal do SKU." }, "IDStockKeepingUnitLocation": { "type": "integer", "description": "Endereço de destino do lote após a transferência." }, "Address": { "type": "string", "description": "Texto do endereço de destino (`Floor-Street-Module-Column-Level` ou nome livre)." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém de destino do lote." }, "WarehouseName": { "type": "string", "description": "Nome do armazém de destino." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Centro de distribuição a que pertence o armazém de destino." }, "DistributionCenterName": { "type": "string", "description": "Nome do centro de distribuição." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de validade do lote, no formato `YYYY-MM-DD`. Vazio quando o SKU não usa controle de validade." }, "ManufacturingDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de fabricação do lote, no formato `YYYY-MM-DD`. Vazio quando o SKU não usa controle de lote." }, "Comments": { "type": "string", "nullable": true, "description": "Identificação textual do lote (código impresso no produto) ou observações livres." }, "Default": { "type": "integer", "description": "`1` quando é o lote padrão do endereço.", "enum": [ 0, 1 ] }, "BatchBalance": { "type": "number", "description": "Saldo do lote (entradas que mexem o saldo menos saídas)." }, "IDBatchStatus": { "type": "integer", "description": "`1` quando há saldo, `0` quando o lote está zerado.", "enum": [ 0, 1 ] }, "BatchStatus": { "type": "string", "enum": [ "Ativo", "Inativo" ], "description": "Status do lote após a transferência: `Ativo` (lote ainda visível para movimentação) ou `Inativo` (lote zerado/ocultado)." }, "QtyAvailable": { "type": "number", "description": "Saldo disponível total do SKU no armazém em que está o lote." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do SKU." }, "MainImageThumbnailURL": { "type": "string", "nullable": true, "description": "URL da miniatura da imagem principal." }, "AbcCurve": { "type": "string", "nullable": true, "description": "Classificação ABC do SKU (`A`, `B`, `C`)." }, "DateLastSell": { "type": "string", "format": "date-time", "nullable": true, "description": "Data da última venda do SKU. Vazio quando o SKU nunca foi vendido." }, "IDTypeAddress": { "type": "integer", "nullable": true, "description": "Tipo de endereço de armazenagem: `1` Picking, `2` Pulmão, `3` Blocado.", "enum": [ 1, 2, 3 ] }, "TypeAddress": { "type": "string", "nullable": true, "description": "Descrição amigável do tipo de endereço." }, "IDStockKeepingUnitLocationCategory": { "type": "integer", "nullable": true, "description": "Categoria do endereço de destino (agrupamento configurável)." }, "StockKeepingUnitLocationCategoryName": { "type": "string", "nullable": true, "description": "Nome da categoria do endereço." }, "IDStockKeepingUnitLocationGroup": { "type": "integer", "nullable": true, "description": "Grupo de endereços ao qual o endereço de destino pertence." }, "IDTypeSku": { "type": "integer", "description": "Tipo do SKU: `1` Clube, `2` Kit, `3` Sku (produto normal), `4` Produto com variação, `5` Serviço, `6` Matéria-prima, `7` Uso e consumo, `8` Caixa fechada." }, "Batch": { "type": "integer", "description": "`1` quando o SKU usa controle de lote rastreável.", "enum": [ 0, 1 ] } } }, "SkuCostRecalculateAcceptedResponse": { "type": "object", "description": "Resposta da fila assíncrona — o recálculo é despachado para processamento em segundo plano.", "properties": { "status": { "type": "string", "example": "accepted", "description": "Status textual do enfileiramento — `accepted` quando o job de recálculo de custo foi enviado para processamento assíncrono." }, "message": { "type": "string", "nullable": true, "description": "Mensagem complementar do gateway assíncrono (geralmente vazia ou com identificador do job)." } } }, "InventoryAdjustmentItem": { "type": "object", "description": "Item de um lançamento de ajuste de saldo via `POST /sku/inventory`. O sistema aplica a regra `entrada/saída` automaticamente comparando `QuantityInventory` contra o saldo do lote, exceto quando `IDMovementType` força a direção.", "required": [ "IDStockKeepingUnitWarehouse", "IDSku", "QuantityInventory" ], "properties": { "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém onde o ajuste é feito. Precisa estar ativo (`Status = 1`) e pertencer à empresa autenticada." }, "IDSku": { "type": "integer", "description": "SKU a ajustar. Precisa ser do tipo Sku, Matéria-prima ou Uso e consumo (`IDTypeSku IN (3, 6, 7)`)." }, "QuantityInventory": { "type": "number", "description": "Quantidade contada (saldo desejado para o lote). O sistema calcula a diferença em relação ao saldo atual do lote e cria uma movimentação de entrada (`IDTypeMovement = 0`) ou saída (`IDTypeMovement = 1`)." }, "IDBatchNumber": { "type": "integer", "description": "Lote específico a ajustar. Quando omitido, o sistema usa o lote padrão do SKU no armazém — quando o SKU não tem lote nenhum, cria automaticamente um lote no endereço padrão (`Principal`)." }, "Comments": { "type": "string", "description": "Texto livre justificando o ajuste (auditoria, perda, achado, etc.). Gravado na movimentação." }, "IDStockKeepingUnitLocation": { "type": "integer", "description": "Endereço opcional (informativo)." }, "IDMovementType": { "type": "integer", "enum": [ 0, 1, 3 ], "description": "Força a direção do ajuste: `0` entrada explícita (soma `QuantityInventory` ao saldo), `1` saída explícita (subtrai `QuantityInventory`), `3` ajuste pela diferença entre `QuantityInventory` e o saldo disponível atual do SKU (`QtyAvailable`). Quando omitido, compara contra o saldo do lote e calcula a diferença automaticamente." } } }, "InventoryAdjustmentError": { "type": "object", "description": "Falha individual em um lançamento de ajuste. Quando o body é array, cada erro é acumulado nesta lista e o restante das linhas continua sendo processado.", "properties": { "SkuName": { "type": "string", "nullable": true, "description": "Nome do SKU cujo ajuste de estoque falhou durante o processamento — o sistema retorna este objeto na lista de erros quando o lançamento de movimentação para o SKU não pôde ser persistido." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência do SKU na empresa." }, "Description": { "type": "string", "description": "Causa do erro. Valores conhecidos: `Sku não cadastrado`, `Item não é do tipo SKU`, `Quantidade para ajustar saldo não é um número`, `Armazém não cadastrado`, `Lote não encontrado`, `Lote não pertence ao armazém`, `Lote está inativo`." }, "Status": { "type": "integer", "enum": [ 0 ], "description": "Sempre `0` (falha)." } } }, "InventoryHistoryItem": { "type": "object", "description": "Linha do histórico de ajustes (`StockKeepingUnitInventory` + movimentação relacionada). Cada linha representa um ajuste lançado pela tela Inventário.", "properties": { "IDStockKeepingUnitInventory": { "type": "integer", "description": "Código do ajuste." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDSku": { "type": "integer", "description": "Identificador do SKU." }, "SkuName": { "type": "string", "description": "Nome do SKU." }, "IDSkuCompany": { "type": "string", "description": "Código de referência do SKU." }, "Barcode": { "type": "string", "nullable": true, "description": "Código de barras principal." }, "Quantity": { "type": "number", "description": "Quantidade contada que foi lançada." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Depósito da movimentação." }, "WarehouseName": { "type": "string", "description": "Nome do depósito." }, "IDBatch": { "type": "integer", "nullable": true, "description": "Código do lote ajustado." }, "Comments": { "type": "string", "nullable": true, "description": "Comentário informado no lançamento." }, "Login": { "type": "string", "description": "Login do usuário que fez o ajuste." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora do lançamento." }, "IDSkuMovement": { "type": "integer", "description": "Movimentação de estoque (`StockKeepingUnitMovement`) gerada pelo ajuste." } } }, "StockBalanceItem": { "type": "object", "description": "Saldo consolidado de um SKU em um armazém, com as quantidades nas várias situações e o valor em estoque.", "properties": { "IDStockKeepingUnitWarehouseBalance": { "type": "string", "description": "Chave composta `IDStockKeepingUnitWarehouse-IDSku` (usada como `KeyTable` na tela). Não persiste em banco — é gerada pelo sistema." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Identificador do depósito." }, "WarehouseName": { "type": "string", "description": "Nome do depósito." }, "IDTypeStockKeepingUnitWarehouse": { "$ref": "#/components/schemas/TypeStockKeepingUnitWarehouseEnum", "description": "Natureza do depósito: `1` Saudável, `2` Divergência, `3` Quarentena, `4` Recebimento, `5` Falta, `6` Vencido, `7` Auditoria, `8` Avaria, `9` Devolução, `10` Ressuprimento, `11` Outlet." }, "TypeStockKeepingUnitWarehouse": { "type": "string", "description": "Descrição textual do tipo de armazém." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDSku": { "type": "integer", "description": "Identificador do SKU." }, "IDSkuCompany": { "type": "string", "description": "Código de referência do SKU." }, "SkuName": { "type": "string", "description": "Nome do SKU." }, "DateLastRecordModification": { "type": "string", "format": "date-time", "nullable": true, "description": "Última modificação do cadastro do SKU." }, "QtyAvailable": { "type": "number", "description": "Saldo disponível para venda (usa a quantidade ajustada quando configurada; caso contrário, a quantidade natural)." }, "InventoryValue": { "type": "number", "description": "Valor total do estoque disponível (custo × quantidade disponível). Usa o custo manual quando a empresa está configurada para custo fixo (`UseCostFromCostSet = 1`); caso contrário, o custo apurado." }, "CostAverage": { "type": "number", "description": "Custo médio do SKU no armazém. Usa o custo manual quando `UseCostFromCostSet = 1`; caso contrário, o valor total em estoque dividido pela quantidade disponível." }, "QtyReserved": { "type": "number", "description": "Quantidade reservada em pedidos ainda abertos." }, "QtyProduction": { "type": "number", "description": "Quantidade em ordens de produção iniciadas ou em andamento." }, "QtyBuyOrdem": { "type": "number", "description": "Quantidade em pedidos de compra ainda abertos (não cancelados nem concluídos)." }, "QtyToReceipt": { "type": "number", "description": "Quantidade em recebimentos ainda pendentes." }, "QtyHandling": { "type": "number", "description": "Quantidade em manuseio — itens de pedidos já em separação/expedição com saída de estoque pendente." }, "QtyOnStock": { "type": "number", "description": "Estoque físico calculado pelo sistema: `QtyAvailable + QtyReserved + QtyHandling`." } } }, "SkuSupplierLink": { "type": "object", "description": "Vínculo entre um SKU e um fornecedor.", "properties": { "IDStockKeepingUnitSuplierCode": { "type": "integer", "description": "Identificador do vínculo." }, "IDSupplier": { "type": "integer", "description": "Identificador do fornecedor." }, "SupplierNameCorporateName": { "type": "string", "description": "Nome / razão social do fornecedor." }, "SupplierCode": { "type": "string", "description": "Código do produto no fornecedor (o que aparece na nota fiscal dele).", "nullable": true }, "QuantityMultiply": { "type": "number", "description": "Multiplicador: unidades do produto que correspondem a uma unidade comprada do fornecedor." }, "PackageSize": { "type": "integer", "description": "Embalagem do fornecedor.", "nullable": true }, "LastValueCost": { "type": "number", "description": "Custo de tabela informado pelo fornecedor.", "nullable": true }, "PisAliquotInbound": { "type": "number", "description": "Alíquota de PIS de entrada em fração decimal (ex.: `0.0165` = 1,65%).", "nullable": true }, "CofinsAliquotInbound": { "type": "number", "description": "Alíquota de COFINS de entrada em fração decimal (ex.: `0.076` = 7,6%).", "nullable": true } } }, "SkuSupplierListItem": { "type": "object", "description": "Linha da lista consolidada de fornecedores e SKUs: dados do produto somados aos dados do vínculo com o fornecedor.", "properties": { "IDSku": { "type": "integer", "description": "Identificador do produto (SKU)." }, "IDStockKeepingUnitSuplierCode": { "type": "integer", "description": "Identificador do vínculo SKU-fornecedor." }, "SkuName": { "type": "string", "description": "Nome do produto. Para variações, vem prefixado com o nome do produto-pai.", "nullable": true }, "IDSkuCompany": { "type": "string", "description": "Código de referência do produto (código interno da empresa).", "nullable": true }, "BarCode": { "type": "string", "description": "Código de barras do produto.", "nullable": true }, "Category": { "type": "string", "description": "Nome da categoria do produto.", "nullable": true }, "IDCategory": { "type": "integer", "description": "Identificador da categoria.", "nullable": true }, "Brand": { "type": "string", "description": "Nome da marca do produto.", "nullable": true }, "IDBrand": { "type": "integer", "description": "Identificador da marca.", "nullable": true }, "AccountName": { "type": "string", "description": "Conta dona do produto." }, "Package": { "type": "integer", "description": "Indica se o produto é uma embalagem (`1`) ou não (`0`)." }, "Batch": { "type": "integer", "description": "Indica se o produto é controlado por lote (`1`) ou não (`0`)." }, "OwnProduction": { "type": "integer", "description": "Indica produção própria (`1`) ou não (`0`)." }, "SkuNCM": { "type": "string", "description": "NCM do produto.", "nullable": true }, "SkuCest": { "type": "string", "description": "CEST do produto.", "nullable": true }, "IDTaxDepartment": { "type": "integer", "description": "Identificador do departamento fiscal.", "nullable": true }, "CostAverage": { "type": "number", "description": "Custo médio do produto. Reflete o custo manual quando a parametrização \"Utilizar custo manual SKU\" está ativa.", "nullable": true }, "CostLastPurchase": { "type": "number", "description": "Custo da última compra. Reflete o custo manual quando a parametrização \"Utilizar custo manual SKU\" está ativa.", "nullable": true }, "SupplierCode": { "type": "string", "description": "Código do produto no fornecedor.", "nullable": true }, "IDSupplier": { "type": "integer", "description": "Identificador do fornecedor." }, "SupplierNameCorporateName": { "type": "string", "description": "Nome / razão social do fornecedor." }, "SupplierProductReliability": { "type": "integer", "description": "Confiabilidade do fornecedor para o produto.", "nullable": true }, "SupplierProductLeadTimeDays": { "type": "integer", "description": "Prazo de entrega do fornecedor, em dias.", "nullable": true }, "QuantityMultiply": { "type": "number", "description": "Multiplicador do vínculo." }, "PackageSize": { "type": "integer", "description": "Embalagem do fornecedor.", "nullable": true }, "LastValueCost": { "type": "number", "description": "Custo de tabela informado pelo fornecedor.", "nullable": true }, "PisAliquotInbound": { "type": "number", "description": "Alíquota de PIS de entrada (fração decimal).", "nullable": true }, "CofinsAliquotInbound": { "type": "number", "description": "Alíquota de COFINS de entrada (fração decimal).", "nullable": true }, "SkuHeight": { "type": "number", "description": "Altura do produto.", "nullable": true }, "SkuLength": { "type": "number", "description": "Comprimento do produto.", "nullable": true }, "SkuWidth": { "type": "number", "description": "Largura do produto.", "nullable": true }, "SkuWeight": { "type": "number", "description": "Peso do produto.", "nullable": true }, "AbcCurve": { "type": "string", "description": "Curva ABC do produto (`A`, `B` ou `C`).", "nullable": true }, "InfiniteInventory": { "type": "integer", "description": "Indica estoque infinito (`1`) ou não (`0`)." }, "QtySafetyStock": { "type": "number", "description": "Estoque de segurança do produto.", "nullable": true }, "QtyAvailable": { "type": "number", "description": "Quantidade disponível em estoque (calculada)." }, "PriceSell": { "type": "number", "description": "Preço de venda vigente do produto.", "nullable": true }, "PriceList": { "type": "number", "description": "Preço de tabela (lista) vigente do produto.", "nullable": true }, "IDProduct": { "type": "integer", "description": "Identificador do produto-pai, quando o SKU é uma variação.", "nullable": true }, "MainImageURL": { "type": "string", "description": "URL da imagem principal do produto.", "nullable": true }, "MainImageThumbnailURL": { "type": "string", "description": "URL da miniatura da imagem principal.", "nullable": true } } }, "SkuSupplierCreate": { "type": "object", "required": [ "IDSupplier", "QuantityMultiply", "SupplierCode" ], "properties": { "IDSupplier": { "type": "integer", "description": "Fornecedor a vincular. Deve existir na conta autenticada." }, "QuantityMultiply": { "type": "number", "description": "Multiplicador: unidades do produto que correspondem a uma unidade comprada do fornecedor." }, "SupplierCode": { "type": "string", "description": "Código do produto no fornecedor (o que aparece na nota fiscal dele). A combinação SKU + fornecedor + código não pode se repetir." }, "PackageSize": { "type": "integer", "description": "Embalagem do fornecedor. `0` ou vazio é tratado como nulo.", "nullable": true }, "LastValueCost": { "type": "number", "description": "Custo de tabela informado pelo fornecedor.", "nullable": true }, "PisAliquotInbound": { "type": "number", "description": "Alíquota de PIS de entrada em fração decimal (ex.: `0.0165` = 1,65%). Usada no cálculo do custo na entrada da nota fiscal quando a parametrização \"Subtrair PIS custo\" está ativa.", "nullable": true }, "CofinsAliquotInbound": { "type": "number", "description": "Alíquota de COFINS de entrada em fração decimal (ex.: `0.076` = 7,6%). Usada no cálculo do custo na entrada da nota fiscal quando a parametrização \"Subtrair Cofins custo\" está ativa.", "nullable": true } } }, "SkuSupplierUpdate": { "type": "object", "description": "Atualização parcial do vínculo: cada campo é alterado apenas quando enviado.", "properties": { "IDSupplier": { "type": "integer", "description": "Fornecedor a vincular. Deve existir na conta autenticada." }, "QuantityMultiply": { "type": "number", "description": "Multiplicador: unidades do produto que correspondem a uma unidade comprada do fornecedor." }, "SupplierCode": { "type": "string", "description": "Código do produto no fornecedor (o que aparece na nota fiscal dele). A combinação SKU + fornecedor + código não pode se repetir." }, "PackageSize": { "type": "integer", "description": "Embalagem do fornecedor. `0` ou vazio é tratado como nulo.", "nullable": true }, "LastValueCost": { "type": "number", "description": "Custo de tabela informado pelo fornecedor.", "nullable": true }, "PisAliquotInbound": { "type": "number", "description": "Alíquota de PIS de entrada em fração decimal (ex.: `0.0165` = 1,65%). Usada no cálculo do custo na entrada da nota fiscal quando a parametrização \"Subtrair PIS custo\" está ativa.", "nullable": true }, "CofinsAliquotInbound": { "type": "number", "description": "Alíquota de COFINS de entrada em fração decimal (ex.: `0.076` = 7,6%). Usada no cálculo do custo na entrada da nota fiscal quando a parametrização \"Subtrair Cofins custo\" está ativa.", "nullable": true } } }, "UserListItem": { "type": "object", "description": "Item da listagem de `GET /user`.", "properties": { "IDUser": { "type": "integer", "format": "int32", "description": "Identificador do usuário." }, "UserName": { "type": "string", "description": "Nome do usuário." }, "Login": { "type": "string", "description": "Login (e-mail real ou login interno gerado a partir do documento)." }, "UserImageUrl": { "type": "string", "nullable": true, "description": "URL da foto de perfil." }, "Privileges": { "type": "string", "nullable": true, "description": "Perfis de acesso vinculados, concatenados (nomes separados por vírgula)." }, "LastLogin": { "type": "string", "nullable": true, "description": "Data/hora do último acesso.", "format": "date-time" }, "Salesman": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = é vendedor." }, "RestrictAccessSalesman": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = vendedor só enxerga as próprias vendas." }, "DiscountPercentLimit": { "type": "number", "nullable": true, "description": "Limite de desconto (%) padrão do vendedor." }, "UserCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ do usuário (somente dígitos)." }, "UserTelephone": { "type": "string", "nullable": true, "description": "Telefone." }, "UserExtenalId": { "type": "string", "nullable": true, "description": "Código externo (integração)." }, "MFAEnabled": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = autenticação em dois fatores ativada." }, "StatusNameUser": { "type": "string", "description": "Descrição do status do vínculo (Ativo/Inativo)." }, "AccountName": { "type": "string", "description": "Subdomínio da conta." } } }, "UserDetail": { "type": "object", "description": "Detalhe completo do usuário. Resposta de `GET /user/{iduser}` e das operações de criação/edição/vínculos (que devolvem o usuário atualizado).", "properties": { "IDUser": { "type": "integer", "format": "int32", "description": "Identificador do usuário." }, "IDAcess": { "type": "integer", "format": "int32", "description": "Identificador do vínculo do usuário com a empresa." }, "Login": { "type": "string", "description": "Login do usuário." }, "UserName": { "type": "string", "description": "Nome do usuário." }, "UserCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ (somente dígitos)." }, "UserTelephone": { "type": "string", "nullable": true, "description": "Telefone." }, "UserExtenalId": { "type": "string", "nullable": true, "description": "Código externo (integração)." }, "UserImageUrl": { "type": "string", "nullable": true, "description": "URL da foto de perfil." }, "AccountName": { "type": "string", "description": "Subdomínio da conta." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "Status do vínculo: 1 = ativo, 0 = inativo." }, "LastLogin": { "type": "string", "nullable": true, "description": "Data/hora do último acesso.", "format": "date-time" }, "LastPasswordChange": { "type": "string", "nullable": true, "description": "Data/hora da última troca de senha.", "format": "date-time" }, "MFAEnabled": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = autenticação em dois fatores ativada." }, "MFAType": { "type": "string", "nullable": true, "enum": [ "email", "totp", null ], "description": "Tipo de autenticação em dois fatores: `email` (código por e-mail) ou `totp` (app autenticador). `null` desativa." }, "IDModuleFavorite": { "type": "integer", "format": "int32", "nullable": true, "description": "Módulo favorito (tela inicial) do usuário." }, "IDUserJobPositionList": { "type": "string", "nullable": true, "description": "IDs dos cargos do usuário, separados por vírgula." }, "Salesman": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = é vendedor." }, "RestrictAccessSalesman": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = vendedor só enxerga as próprias vendas." }, "DiscountPercentLimit": { "type": "number", "nullable": true, "description": "Limite de desconto (%) padrão do vendedor." }, "IDTypeSalesmanCommission": { "type": "integer", "format": "int32", "nullable": true, "description": "Forma de liberação da comissão: 1 = parcial vinculada às parcelas, 2 = integral no faturamento, 3 = integral após pagamento da 1ª parcela, 4 = integral após pagamento da última parcela.", "enum": [ 1, 2, 3, 4 ] }, "TypeSalesmanCommission": { "type": "string", "nullable": true, "description": "Descrição da forma de liberação da comissão." }, "ExcludeCanceledOrdersCommission": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = pedidos cancelados não entram na comissão." }, "ExcludeReturnedOrdersCommission": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = pedidos devolvidos não entram na comissão." }, "Technician": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = usuário é técnico." }, "UserJobPositionList": { "type": "array", "description": "Cargos do usuário.", "items": { "type": "object", "properties": { "IDUserJobPosition": { "type": "integer", "format": "int32", "description": "Identificador do cargo." }, "UserJobPositionName": { "type": "string", "description": "Nome do cargo." } } } }, "UserPrivilegeGroup": { "type": "array", "description": "Perfis de acesso vinculados ao usuário.", "items": { "type": "object", "properties": { "IDUserPrivilegeGroup": { "type": "integer", "format": "int32", "description": "Identificador do perfil de acesso." }, "PrivilegeGroupName": { "type": "string", "description": "Nome do perfil de acesso." } } } }, "SalesmanComission": { "type": "array", "description": "Regras de comissão do vendedor.", "items": { "type": "object", "properties": { "IDSalesmanComission": { "type": "integer", "format": "int32", "description": "Identificador da regra." }, "RecordTimestamp": { "type": "string", "description": "Data/hora de criação da regra.", "format": "date-time" }, "DateFrom": { "type": "string", "nullable": true, "description": "Início da vigência.", "format": "date" }, "DateTo": { "type": "string", "nullable": true, "description": "Fim da vigência.", "format": "date" }, "DiscountPercentLimit": { "type": "number", "nullable": true, "description": "Limite de desconto (%) para a regra valer." }, "ComissionPercent": { "type": "number", "nullable": true, "description": "Percentual de comissão." }, "IDCategory": { "type": "integer", "format": "int32", "nullable": true, "description": "Categoria de produto à qual a regra se aplica (quando preenchida)." }, "Category": { "type": "string", "nullable": true, "description": "Nome da categoria." }, "AccountName": { "type": "string", "description": "Subdomínio da conta." } } } }, "UserCompanyInvoice": { "type": "array", "description": "Empresas/filiais faturadoras que o usuário pode operar.", "items": { "type": "object", "properties": { "IDUserCompanyInvoice": { "type": "integer", "format": "int32", "description": "Identificador do vínculo." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa/filial faturadora." }, "AccountName": { "type": "string", "description": "Subdomínio da filial." }, "CompanyCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ da filial." }, "CompanyNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social da filial." } } } }, "UserCompanyDistributionCenter": { "type": "array", "description": "Centros de distribuição que o usuário pode operar.", "items": { "type": "object", "properties": { "IDUserCompanyDistributionCenter": { "type": "integer", "format": "int32", "description": "Identificador do vínculo." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "format": "int32", "description": "Identificador do centro de distribuição." }, "DistributionCenterName": { "type": "string", "nullable": true, "description": "Nome do centro de distribuição." }, "AccountName": { "type": "string", "description": "Subdomínio da conta." } } } }, "UserCompanySupplierCategory": { "type": "array", "description": "Categorias de fornecedor que o usuário pode operar.", "items": { "type": "object", "properties": { "IDUserCompanySupplierCategory": { "type": "integer", "format": "int32", "description": "Identificador do vínculo." }, "IDSupplierCategory": { "type": "integer", "format": "int32", "description": "Identificador da categoria de fornecedor." }, "CategoryDescription": { "type": "string", "nullable": true, "description": "Nome da categoria de fornecedor." }, "AccountName": { "type": "string", "description": "Subdomínio da conta." } } } }, "UserLog": { "type": "array", "description": "Auditoria de alterações no cadastro do usuário (mais recente primeiro).", "items": { "type": "object", "properties": { "IDUserLog": { "type": "integer", "format": "int32", "description": "Identificador do registro de log." }, "RecordTimestamp": { "type": "string", "description": "Data/hora da alteração.", "format": "date-time" }, "RecordUserCreated": { "type": "integer", "format": "int32", "nullable": true, "description": "Identificador do usuário que fez a alteração." }, "Login": { "type": "string", "nullable": true, "description": "Login de quem fez a alteração." }, "Data": { "type": "string", "description": "Descrição da alteração (DE/PARA dos campos)." } } } }, "LoginLog": { "type": "array", "description": "Histórico de acessos do usuário (mais recente primeiro).", "items": { "type": "object", "properties": { "IDUserLogin": { "type": "integer", "format": "int32", "description": "Identificador do acesso." }, "Login": { "type": "string", "description": "Login utilizado no acesso." }, "RecordTimestamp": { "type": "string", "description": "Data/hora do acesso.", "format": "date-time" }, "IP": { "type": "string", "nullable": true, "description": "Endereço de origem do acesso." }, "AccountName": { "type": "string", "description": "Subdomínio da conta." } } } } } }, "UserCreate": { "type": "object", "description": "Corpo de `POST /user`. Obrigatório `UserName` e pelo menos um de `Login` ou `UserCpfCnpj`.", "required": [ "UserName" ], "properties": { "UserName": { "type": "string", "description": "Nome do usuário." }, "Login": { "type": "string", "nullable": true, "description": "E-mail de login. Se omitido, o sistema gera um login interno a partir do documento." }, "UserCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ do usuário. Obrigatório quando `Login` não é informado." }, "UserTelephone": { "type": "string", "nullable": true, "description": "Telefone." }, "UserExtenalId": { "type": "string", "nullable": true, "description": "Código externo (integração)." }, "MFAEnabled": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = ativa autenticação em dois fatores." }, "MFAType": { "type": "string", "nullable": true, "enum": [ "email", "totp", null ], "description": "Tipo de autenticação em dois fatores: `email` (código por e-mail) ou `totp` (app autenticador). `null` desativa." }, "Salesman": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = marca o usuário como vendedor. Padrão 0." }, "RestrictAccessSalesman": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = vendedor só enxerga as próprias vendas. Padrão 0." }, "DiscountPercentLimit": { "type": "number", "nullable": true, "description": "Limite de desconto (%) padrão do vendedor." }, "IDTypeSalesmanCommission": { "type": "integer", "format": "int32", "nullable": true, "description": "Forma de liberação da comissão: 1 = parcial vinculada às parcelas, 2 = integral no faturamento, 3 = integral após pagamento da 1ª parcela, 4 = integral após pagamento da última parcela.", "enum": [ 1, 2, 3, 4 ] }, "ExcludeCanceledOrdersCommission": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = pedidos cancelados não entram na comissão." }, "ExcludeReturnedOrdersCommission": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = pedidos devolvidos não entram na comissão." } } }, "UserUpdate": { "type": "object", "description": "Corpo de `PUT /user/{iduser}`. Atualização parcial — só os campos enviados são alterados.", "properties": { "UserName": { "type": "string", "description": "Nome do usuário." }, "Login": { "type": "string", "nullable": true, "description": "E-mail de login." }, "UserCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ (somente dígitos)." }, "UserTelephone": { "type": "string", "nullable": true, "description": "Telefone." }, "UserExtenalId": { "type": "string", "nullable": true, "description": "Código externo (integração)." }, "Password": { "type": "string", "nullable": true, "description": "Nova senha. Validada contra a política da empresa (comprimento, complexidade, reuso e validade). Trocar a senha de outro usuário exige privilégio de redefinir senha." }, "MFAEnabled": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = ativa autenticação em dois fatores." }, "MFAType": { "type": "string", "nullable": true, "enum": [ "email", "totp", null ], "description": "Tipo de autenticação em dois fatores: `email` (código por e-mail) ou `totp` (app autenticador). `null` desativa." }, "IDModuleFavorite": { "type": "integer", "format": "int32", "nullable": true, "description": "Módulo favorito (tela inicial)." }, "IDUserJobPositionList": { "type": "string", "nullable": true, "description": "IDs dos cargos do usuário, separados por vírgula." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Status do vínculo: 1 = ativo, 0 = inativo." }, "Salesman": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = marca o usuário como vendedor." }, "RestrictAccessSalesman": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = vendedor só enxerga as próprias vendas." }, "DiscountPercentLimit": { "type": "number", "nullable": true, "description": "Limite de desconto (%) padrão do vendedor. Ignorado quando `Salesman=0`." }, "IDTypeSalesmanCommission": { "type": "integer", "format": "int32", "nullable": true, "description": "Forma de liberação da comissão: 1 = parcial vinculada às parcelas, 2 = integral no faturamento, 3 = integral após pagamento da 1ª parcela, 4 = integral após pagamento da última parcela.", "enum": [ 1, 2, 3, 4 ] }, "ExcludeCanceledOrdersCommission": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = pedidos cancelados não entram na comissão." }, "ExcludeReturnedOrdersCommission": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = pedidos devolvidos não entram na comissão." }, "Technician": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "1 = marca o usuário como técnico." } } }, "UserPrivilegeGroupRef": { "type": "object", "description": "Perfil de acesso vinculado a um usuário. Item de `GET /user/{iduser}/privilege/privilege-group`.", "properties": { "IDUserPrivilegeGroup": { "type": "integer", "format": "int32", "description": "Identificador do perfil de acesso." }, "PrivilegeGroupName": { "type": "string", "description": "Nome do perfil de acesso." } } }, "UserVerifyRequest": { "type": "object", "description": "Corpo de `POST /user/{iduser}/verify`.", "required": [ "Password" ], "properties": { "Password": { "type": "string", "description": "Senha do usuário a confirmar." }, "UserPrivilege": { "type": "integer", "format": "int32", "nullable": true, "description": "Privilégio a verificar (opcional). Quando informado, exige que o usuário possua esse privilégio para confirmar." } } }, "UserCompanyInvoiceCreate": { "type": "object", "description": "Corpo de `POST /user/{iduser}/company-invoice`.", "required": [ "IDCompany" ], "properties": { "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa/filial faturadora a vincular." } } }, "UserDistributionCenterCreate": { "type": "object", "description": "Corpo de `POST /user/{iduser}/distribution-center`.", "required": [ "IDStockKeepingUnitDistributionCenter" ], "properties": { "IDStockKeepingUnitDistributionCenter": { "type": "integer", "format": "int32", "description": "Identificador do centro de distribuição a vincular." } } }, "UserSupplierCategoryCreate": { "type": "object", "description": "Corpo de `POST /user/{iduser}/supplier-category`.", "required": [ "IDSupplierCategory" ], "properties": { "IDSupplierCategory": { "type": "integer", "format": "int32", "description": "Identificador da categoria de fornecedor a vincular." } } }, "SkuListItemSimple": { "type": "object", "description": "Item do listagem rasa de SKU (modo `Simple=1`).", "properties": { "IDSku": { "type": "integer", "description": "Identificador do SKU." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa dona do SKU." }, "IDStatusSku": { "type": "integer", "description": "Status do SKU: `1` Ativo, `2` Compra suspensa, `3` Inativo, `4` Venda suspensa (`0` é registro logicamente excluído).", "enum": [ 0, 1, 2, 3, 4 ] }, "BarCode": { "type": "string", "nullable": true, "maxLength": 20, "description": "Código de barras principal (EAN/GTIN)." }, "IDTypeSku": { "type": "integer", "description": "Tipo do SKU (vide os tipos de produto)." }, "IDSkuCompany": { "type": "string", "nullable": true, "maxLength": 100, "description": "Código de referência interno do SKU na empresa." }, "SkuNameOnly": { "type": "string", "nullable": true, "description": "Nome do SKU sem prefixo do produto-pai." }, "Batch": { "type": "integer", "description": "Indica se o SKU usa controle de lote." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa dona do SKU." }, "TypeProduct": { "type": "string", "description": "Descrição do tipo do SKU." }, "CostSet": { "type": "number", "nullable": true, "description": "Custo manual cadastrado para o SKU." }, "SerialNumber": { "type": "integer", "description": "Indica se o SKU é controlado por número de série." }, "CostAverage": { "type": "number", "nullable": true, "description": "Custo médio do SKU calculado a partir das movimentações de entrada." }, "CostLastPurchase": { "type": "number", "nullable": true, "description": "Custo da última compra registrada para o SKU (última nota fiscal de entrada)." }, "InventoryValue": { "type": "number", "nullable": true, "description": "Valor financeiro do estoque consolidado." }, "SkuHeight": { "type": "number", "nullable": true, "description": "Altura do SKU em cm." }, "SkuLength": { "type": "number", "nullable": true, "description": "Comprimento do SKU em cm." }, "SkuWidth": { "type": "number", "nullable": true, "description": "Largura do SKU em cm." }, "SkuWeight": { "type": "number", "nullable": true, "description": "Peso bruto do SKU em kg." }, "IDProduct": { "type": "integer", "nullable": true, "description": "Identificador do produto-pai, quando este SKU é variação." }, "RastroControl": { "type": "integer", "nullable": true, "description": "`1` quando o SKU tem rastreabilidade extra: nos recebimentos a data de fabricação e a data de validade do lote passam a ser obrigatórias além do número do lote (`Batch=1`)." }, "BestBeforeRequired": { "type": "integer", "nullable": true, "description": "`1` quando a data de validade é obrigatória nas entradas (válido apenas quando o SKU tem rastreabilidade por lote)." }, "BatchRequired": { "type": "integer", "nullable": true, "description": "`1` quando o número do lote é obrigatório nas entradas e saídas (válido apenas quando o SKU tem rastreabilidade por lote)." }, "TypeProductVariationValue": { "type": "string", "nullable": true, "description": "Valores de variação concatenados por vírgula (ex.: `Azul,M`)." }, "QtyAvailable": { "type": "string", "description": "Quantidade disponível em estoque (string com ajuste de margem de segurança)." }, "BarCodePackageList": { "type": "array", "description": "Códigos de barras de embalagem (caixa) do SKU.", "items": { "type": "object", "properties": { "BarCodePackage": { "type": "string", "description": "Código de barras alternativo cadastrado para o SKU (embalagem secundária, ex.: caixa com múltiplas unidades)." }, "PackageFactor": { "type": "integer", "description": "Quantidade de unidades por embalagem." } } } }, "PriceSell": { "type": "number", "nullable": true, "description": "Preço de venda do SKU na política comercial padrão da empresa." }, "PriceList": { "type": "number", "nullable": true, "description": "Preço de tabela (preço cheio) do SKU na política comercial padrão." }, "LastValueCost": { "type": "number", "nullable": true, "description": "Último custo do fornecedor (aparece apenas quando `IDSupplierCost` é enviado)." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do SKU." }, "MainImageThumbnailURL": { "type": "string", "nullable": true, "description": "URL da miniatura da imagem principal." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome do SKU; concatenado com o nome do produto-pai quando aplicável." }, "Quantity": { "type": "number", "nullable": true, "description": "Quantidade derivada quando o `BarCode` lido é de balança (valor por peso)." } } }, "SkuListItem": { "type": "object", "description": "Item da listagem padrão de SKU (modo completo). Schema parcial — a query do sistema retorna dezenas de campos calculados de vendas, estoque, custos e curva ABC.", "additionalProperties": true, "properties": { "IDSku": { "type": "integer", "description": "Identificador do SKU." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa dona do SKU." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome do SKU." }, "IDSkuCompany": { "type": "string", "nullable": true, "maxLength": 100, "description": "Código de referência interno do SKU, definido pela empresa." }, "BarCode": { "type": "string", "nullable": true, "maxLength": 20, "description": "Código de barras principal." }, "IDTypeSku": { "type": "integer", "description": "Tipo do SKU: `1` Clube (assinatura), `2` Kit, `3` Sku (produto normal), `4` Produto com variação (pai), `5` Serviço, `6` Matéria-prima, `7` Uso e consumo, `8` Caixa fechada." }, "TypeProduct": { "type": "string", "description": "Descrição textual do tipo do SKU (vide `IDTypeSku`)." }, "IDBrand": { "type": "integer", "nullable": true, "description": "Identificador da marca." }, "Brand": { "type": "string", "nullable": true, "description": "Nome da marca." }, "IDCategory": { "type": "integer", "nullable": true, "description": "Identificador da categoria." }, "Category": { "type": "string", "nullable": true, "description": "Nome da categoria." }, "CategoryTree": { "type": "string", "nullable": true, "description": "Caminho completo da categoria (`Pai -> Filha -> Neta`)." }, "IDStatusSku": { "type": "integer", "description": "Status do SKU: `1` Ativo, `2` Compra suspensa, `3` Inativo, `4` Venda suspensa (`0` é registro logicamente excluído).", "enum": [ 0, 1, 2, 3, 4 ] }, "TypeStatusSku": { "type": "string", "nullable": true, "description": "Descrição textual do status do SKU: `Ativo`, `Compra suspensa`, `Inativo`, `Venda suspensa`." }, "Package": { "type": "integer", "description": "`1` indica que o SKU é uma embalagem master (caixa/fardo) usada para venda agrupada; `0` é SKU normal." }, "QtyAvailable": { "type": "string", "description": "Quantidade disponível em estoque (soma de todos os depósitos), em formato string para preservar a precisão decimal." }, "PriceSell": { "type": "number", "nullable": true, "description": "Preço de venda na política comercial padrão da empresa." }, "PriceList": { "type": "number", "nullable": true, "description": "Preço de tabela (preço cheio, sem desconto) na política comercial padrão." }, "CostAverage": { "type": "number", "nullable": true, "description": "Custo médio calculado pelas movimentações de entrada." }, "CostSet": { "type": "number", "nullable": true, "description": "Custo manual cadastrado no SKU (sobrescreve os outros custos quando informado)." }, "CostLastPurchase": { "type": "number", "nullable": true, "description": "Custo da última compra (última nota fiscal de entrada)." }, "InventoryValue": { "type": "number", "nullable": true, "description": "Valor monetário do estoque do SKU. Vem do somatório de `InventoryValue` (acumulado pelas entradas com o custo de cada movimentação). Quando a parametrização `UseCostFromCostSet=1` está ativa, é calculado como `CostSet × QtyAvailable`." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do SKU." }, "MainImageThumbnailURL": { "type": "string", "nullable": true, "description": "URL da miniatura da imagem principal." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do registro." }, "DateLastRecordModification": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora da última alteração do registro." }, "MinimumBalanceDays": { "type": "integer", "nullable": true, "description": "Dias mínimos de cobertura de estoque usados no cálculo de sugestão de compra." }, "MaximumBalanceDays": { "type": "integer", "nullable": true, "description": "Dias máximos de cobertura de estoque usados no cálculo de sugestão de compra." } } }, "SkuDetail": { "type": "object", "description": "Detalhe completo de um SKU. Inclui os campos do cadastro do SKU, campos calculados (custos, estoque, valor) e listas relacionadas (fornecedores, códigos de barras adicionais, códigos de embalagem). Quando `Sales=1` na query, a resposta troca o detalhe pelas métricas históricas de venda (vide sistema).", "properties": { "IDSku": { "type": "integer", "description": "Identificador do SKU." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa dona do SKU." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "CompanyCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ da empresa do SKU." }, "CompanyNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social da empresa do SKU." }, "SkuName": { "type": "string", "nullable": true, "maxLength": 150, "description": "Nome do SKU." }, "ProductName": { "type": "string", "nullable": true, "description": "Nome do produto-pai, quando este SKU é variação." }, "IDProduct": { "type": "integer", "nullable": true, "description": "Quando este SKU é uma variação, identificador do SKU produto-pai que o agrupa." }, "IDSkuCompany": { "type": "string", "nullable": true, "maxLength": 100, "description": "Código de referência interno do SKU, definido pela empresa. Único por empresa." }, "BarCode": { "type": "string", "nullable": true, "maxLength": 20, "description": "Código de barras principal." }, "IDTypeSku": { "type": "integer", "description": "Tipo do SKU: `1` Clube, `2` Kit, `3` Sku (produto normal), `4` Produto com variação, `5` Serviço, `6` Matéria-prima, `7` Uso e consumo, `8` Caixa fechada." }, "TypeProduct": { "type": "string", "nullable": true, "description": "Descrição textual do tipo do SKU." }, "IDStatusSku": { "type": "integer", "description": "Status do SKU: `1` Ativo, `2` Compra suspensa, `3` Inativo, `4` Venda suspensa (`0` é registro logicamente excluído).", "enum": [ 0, 1, 2, 3, 4 ] }, "TypeStatusSku": { "type": "string", "nullable": true, "description": "Descrição textual do status (vide `IDStatusSku`)." }, "IDTypeSkuCondition": { "type": "integer", "nullable": true, "description": "Condição do produto: `1` novo, `2` usado, `3` recondicionado.", "enum": [ 1, 2, 3 ] }, "TypeSkuCondition": { "type": "string", "nullable": true, "description": "Descrição textual da condição: `Novo`, `Usado`, `Recondicionado`." }, "IDBrand": { "type": "integer", "nullable": true, "description": "Identificador da marca." }, "Brand": { "type": "string", "nullable": true, "description": "Nome da marca." }, "IDCategory": { "type": "integer", "nullable": true, "description": "Identificador da categoria." }, "Category": { "type": "string", "nullable": true, "description": "Nome da categoria." }, "IDTaxDepartment": { "type": "integer", "nullable": true, "description": "Identificador do departamento fiscal (regra tributária aplicada ao SKU)." }, "TaxDepartmentDescription": { "type": "string", "nullable": true, "description": "Descrição do departamento fiscal." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Empresa faturadora associada ao SKU." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Conta (subdomínio) da empresa faturadora vinculada ao SKU." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social da empresa faturadora." }, "IDCompanyInvoiceIDCompanyIntegrationList": { "type": "string", "nullable": true, "description": "Lista de integrações `IDCompanyIntegration` em que essa empresa faturadora deve ser usada." }, "SkuHeight": { "type": "number", "nullable": true, "description": "Altura do SKU em cm." }, "SkuLength": { "type": "number", "nullable": true, "description": "Comprimento do SKU em cm." }, "SkuWidth": { "type": "number", "nullable": true, "description": "Largura do SKU em cm." }, "SkuWeight": { "type": "number", "nullable": true, "description": "Peso bruto em kg." }, "SkuWeightNet": { "type": "number", "nullable": true, "description": "Peso líquido em kg." }, "SkuNCM": { "type": "string", "nullable": true, "maxLength": 12, "description": "Código NCM (Nomenclatura Comum do Mercosul) do SKU para fins fiscais." }, "SkuNCMExTipi": { "type": "string", "nullable": true, "maxLength": 3, "description": "Ex TIPI do NCM (2 ou 3 dígitos)." }, "SkuCest": { "type": "string", "nullable": true, "maxLength": 15, "description": "Código CEST (Código Especificador da Substituição Tributária)." }, "SkuCst": { "type": "integer", "nullable": true, "description": "Origem fiscal do SKU." }, "SkuCstDescription": { "type": "string", "nullable": true, "description": "Descrição textual da origem do produto (CST)." }, "MeasurementUnit": { "type": "string", "nullable": true, "maxLength": 45, "description": "Unidade de medida do SKU (`UN`, `KG`, `L`, `M`, etc.)." }, "MeasurementUnitDescription": { "type": "string", "nullable": true, "description": "Descrição da unidade de medida." }, "CostSet": { "type": "number", "nullable": true, "description": "Custo manual cadastrado." }, "CostAverage": { "type": "number", "nullable": true, "description": "Custo médio calculado pelas entradas." }, "CostLastPurchase": { "type": "number", "nullable": true, "description": "Custo da última compra registrada." }, "InventoryValue": { "type": "number", "nullable": true, "description": "Valor monetário do estoque (`CostAverage * QtyAvailable`)." }, "Batch": { "type": "integer", "description": "`1` quando o SKU é controlado por lote (rastreabilidade por número de lote nas movimentações)." }, "BatchRequired": { "type": "integer", "nullable": true, "description": "`1` quando o número do lote é obrigatório nas entradas e saídas (apenas válido se `Batch=1`)." }, "BestBeforeRequired": { "type": "integer", "nullable": true, "description": "`1` quando a data de validade é obrigatória nas entradas (apenas válido se `Batch=1`)." }, "BestBeforeMinimumDays": { "type": "integer", "nullable": true, "description": "Validade mínima aceita (em dias) no recebimento — entradas com validade menor que esse prazo são bloqueadas." }, "BestBeforeDays": { "type": "integer", "nullable": true, "description": "Prazo de validade padrão (em dias) sugerido para o lote a partir da data de fabricação." }, "RastroControl": { "type": "integer", "nullable": true, "description": "`1` quando o SKU tem rastreabilidade extra: nos recebimentos a data de fabricação e a data de validade do lote passam a ser obrigatórias além do número do lote (`Batch=1`)." }, "SerialNumber": { "type": "integer", "description": "`1` quando o SKU é controlado por número de série (cada unidade tem identificador único)." }, "Package": { "type": "integer", "description": "`1` quando o SKU representa uma embalagem master (caixa/fardo) usada para integração de catálogo." }, "PackageOccupation": { "type": "number", "nullable": true, "description": "Ocupação do SKU no endereçamento (fator multiplicador usado no cálculo de capacidade do endereço)." }, "QtyAvailable": { "type": "string", "description": "Quantidade disponível em estoque (string para preservar precisão decimal)." }, "QtyReserved": { "type": "string", "nullable": true, "description": "Quantidade reservada em pedidos não faturados." }, "QtySafetyStock": { "type": "number", "nullable": true, "description": "Estoque mínimo de segurança configurado." }, "MinimumPickingLocationQuantity": { "type": "number", "nullable": true, "description": "Quantidade mínima a manter no endereço de picking (gatilho de ressuprimento)." }, "MaximumPickingLocationQuantity": { "type": "number", "nullable": true, "description": "Quantidade máxima do endereço de picking (limite superior do ressuprimento)." }, "BuyOrdemQuantity": { "type": "string", "nullable": true, "description": "Quantidade total em pedidos de compra em aberto." }, "BuyOrderAlert": { "type": "integer", "nullable": true, "description": "`1` liga o alerta automático de compra quando o estoque cai abaixo da quantidade configurada." }, "BuyOrderAlertManualQuantity": { "type": "integer", "nullable": true, "description": "Quantidade que dispara o alerta de compra quando `BuyOrderAlert=1`." }, "KitsRelatedCount": { "type": "integer", "nullable": true, "description": "Quantos kits usam este SKU como componente (válido para SKUs do tipo normal)." }, "InfiniteInventory": { "type": "integer", "description": "`1` quando o SKU não controla estoque (vendas não decrementam — usado para serviços e itens digitais)." }, "OwnProduction": { "type": "integer", "description": "`1` quando o SKU é de produção própria (libera fluxos de ordem de produção)." }, "AbcCurve": { "type": "string", "nullable": true, "maxLength": 1, "description": "Classificação automática da curva ABC do SKU baseada em participação no faturamento (`A`, `B`, `C`)." }, "AbcCurveAdjust": { "type": "string", "nullable": true, "maxLength": 1, "description": "Curva ABC ajustada manualmente — sobrescreve `AbcCurve` quando preenchida." }, "IDStockKeepingUnitProductionLine": { "type": "integer", "nullable": true, "description": "Linha de produção associada ao SKU." }, "ProductionLineName": { "type": "string", "nullable": true, "description": "Nome da linha de produção." }, "IDStockKeepingUnitLocationCategory": { "type": "integer", "nullable": true, "description": "Categoria de endereçamento sugerida ao alocar o SKU." }, "StockKeepingUnitLocationCategoryName": { "type": "string", "nullable": true, "description": "Nome da categoria de endereçamento." }, "WarrantyTime": { "type": "string", "nullable": true, "maxLength": 45, "description": "Quantidade de garantia (número)." }, "WarrantyTimeType": { "type": "string", "nullable": true, "maxLength": 45, "description": "Unidade da garantia (`dias`, `meses`, `anos`)." }, "Comments": { "type": "string", "nullable": true, "maxLength": 500, "description": "Observações livres do SKU." }, "NfeComments": { "type": "string", "nullable": true, "maxLength": 200, "description": "Observações impressas na nota fiscal eletrônica." }, "NfeInvoiceAsKit": { "type": "integer", "nullable": true, "description": "`1` faz a NF-e detalhar os componentes do kit individualmente; `0` emite o kit como item único." }, "NfeFactorPercentSku": { "type": "number", "nullable": true, "description": "Fator percentual aplicado ao preço do SKU na emissão da NF-e (ex.: 0.95 reduz 5%). Quando preenchido, zera `NfeFactorFixedSkuValue`." }, "NfeFactorPercentSkuIDCompanyIntegrationList": { "type": "string", "nullable": true, "description": "Lista (separada por vírgula) dos identificadores de integração de empresa em que o fator percentual deve ser aplicado." }, "NfeFactorFixedSkuValue": { "type": "number", "nullable": true, "description": "Valor fixo aplicado ao preço do SKU na NF-e. Mutuamente exclusivo com `NfeFactorPercentSku`." }, "LeadTimeDays": { "type": "integer", "nullable": true, "description": "Lead time (em dias) entre a colocação do pedido de compra e a chegada do SKU." }, "EstimatedDateArrival": { "type": "string", "format": "date", "nullable": true, "description": "Data estimada de chegada do SKU em pedidos futuros — usada quando o item está em rota de reposição." }, "ShareProductImage": { "type": "integer", "nullable": true, "description": "`1` quando a variação compartilha as imagens do produto-pai; `0` usa imagens próprias." }, "KitAutomaticMeasureUpdate": { "type": "integer", "description": "`1` recalcula automaticamente medidas (peso, dimensões) do kit a partir dos componentes ao alterar a composição." }, "KitAutomaticPricingUpdate": { "type": "integer", "nullable": true, "description": "`1` recalcula automaticamente o preço do kit a partir dos componentes ao alterar a composição." }, "EcommerceDescription": { "type": "string", "nullable": true, "maxLength": 10000, "description": "Descrição completa do produto para vitrine de e-commerce (texto rico)." }, "EcommerceDescriptionShort": { "type": "string", "nullable": true, "maxLength": 3000, "description": "Descrição curta para vitrine de e-commerce (resumo)." }, "EcommerceKeyWords": { "type": "string", "nullable": true, "maxLength": 1000, "description": "Palavras-chave (SEO) separadas por vírgula." }, "EcommerceLinkId": { "type": "string", "nullable": true, "maxLength": 400, "description": "Identificador de URL amigável (slug) para a página do produto." }, "EcommerceMetaTagDescription": { "type": "string", "nullable": true, "maxLength": 3000, "description": "Meta tag description para SEO da página do produto." }, "EcommerceTitle": { "type": "string", "nullable": true, "maxLength": 200, "description": "Título da página do produto na vitrine de e-commerce." }, "EcommerceVideoUrl": { "type": "string", "nullable": true, "maxLength": 200, "description": "URL de vídeo de demonstração do produto." }, "EcommerceKitAutomaticDescription": { "type": "integer", "nullable": true, "description": "`1` faz a descrição do kit ser composta automaticamente concatenando as descrições dos componentes." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do SKU (ou imagem da primeira variação, quando aplicável)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do registro." }, "DateLastRecordModification": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora da última alteração do registro." }, "Tags": { "type": "array", "items": { "type": "string" }, "description": "Etiquetas livres do SKU." }, "Suppliers": { "type": "array", "description": "Fornecedores cadastrados para este SKU.", "items": { "type": "object", "properties": { "IDStockKeepingUnitSuplierCode": { "type": "integer", "description": "Identificador da relação SKU↔fornecedor." }, "IDSupplier": { "type": "integer", "description": "Identificador do fornecedor." }, "PackageSize": { "type": "number", "nullable": true, "description": "Tamanho da embalagem do fornecedor (quantidade por caixa)." }, "QuantityMultiply": { "type": "number", "nullable": true, "description": "Múltiplo mínimo de compra desse fornecedor." }, "SupplierCode": { "type": "string", "nullable": true, "description": "Código de referência do SKU no catálogo do fornecedor." } } } }, "BarCodeList": { "type": "array", "description": "Códigos de barras adicionais (além do principal).", "items": { "type": "object", "properties": { "IDStockKeepingUnitBarCode": { "type": "integer", "description": "Identificador do código de barras adicional." }, "AdditionalBarCode": { "type": "string", "description": "Código de barras adicional (alternativo ao principal)." } } } }, "BarCodePackageList": { "type": "array", "description": "Códigos de barras de embalagens (caixa, fardo, master).", "items": { "type": "object", "properties": { "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDStockKeepingUnitBarCodePackage": { "type": "integer", "description": "Identificador do código de barras de embalagem." }, "BarCodePackage": { "type": "string", "description": "Código de barras da embalagem (caixa/fardo/master)." }, "PackageFactor": { "type": "integer", "description": "Quantidade de unidades dentro da embalagem." }, "IDSkuKit": { "type": "integer", "nullable": true, "description": "Quando o código aponta para um kit equivalente, o SKU do kit." }, "IDSkuCompanyKit": { "type": "string", "nullable": true, "description": "Quando a embalagem corresponde a um kit, código de referência (`IDSkuCompany`) do kit equivalente." }, "SkuNameKit": { "type": "string", "nullable": true, "description": "Nome do kit equivalente, quando aplicável." } } } } } }, "SkuCreateBody": { "type": "object", "description": "Corpo para criar um novo SKU.", "required": [ "IDTypeSku" ], "properties": { "SkuName": { "type": "string", "nullable": true, "maxLength": 150, "description": "Nome do SKU." }, "IDSkuCompany": { "type": "string", "nullable": true, "maxLength": 100, "description": "Código de referência interno do SKU. Único por empresa. Quando omitido, é preenchido automaticamente com o próprio `IDSku` gerado (exceto quando `Composing` é enviado)." }, "IDTypeSku": { "type": "integer", "description": "Tipo do SKU. Obrigatório. 1=Clube, 2=Kit, 3=Sku (produto normal), 4=Produto (com variação), 5=Serviço, 6=Matéria-prima, 7=Uso e consumo, 8=Caixa.", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "BarCode": { "type": "string", "nullable": true, "maxLength": 20, "description": "Código de barras principal. Não pode duplicar entre SKUs da empresa. Quando omitido, é preenchido automaticamente com o `IDSku` gerado." }, "IDBrand": { "type": "integer", "nullable": true, "description": "Identificador da marca. Validado contra as marcas da empresa." }, "IDCategory": { "type": "integer", "nullable": true, "description": "Identificador da categoria do SKU." }, "IDTaxDepartment": { "type": "integer", "nullable": true, "description": "Identificador do departamento fiscal." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Empresa faturadora vinculada ao SKU (uma das empresas do grupo)." }, "IDStockKeepingUnitProductionLine": { "type": "integer", "nullable": true, "description": "Linha de produção associada ao SKU." }, "IDStockKeepingUnitLocationCategory": { "type": "integer", "nullable": true, "description": "Categoria de endereçamento para o SKU." }, "IDTypeSkuCondition": { "type": "integer", "nullable": true, "enum": [ 1, 2, 3 ], "description": "Condição do SKU: `1` Novo, `2` Usado, `3` Recondicionado. Default `1`." }, "MeasurementUnit": { "type": "string", "nullable": true, "maxLength": 45, "description": "Unidade de medida (`UN`, `KG`, `L`, etc.). Default `UN`. Validada contra as unidades cadastradas." }, "SkuHeight": { "type": "number", "nullable": true, "description": "Altura em cm." }, "SkuLength": { "type": "number", "nullable": true, "description": "Comprimento em cm." }, "SkuWidth": { "type": "number", "nullable": true, "description": "Largura em cm." }, "SkuWeight": { "type": "number", "nullable": true, "description": "Peso bruto em kg." }, "SkuWeightNet": { "type": "number", "nullable": true, "description": "Peso líquido em kg." }, "SkuNCM": { "type": "string", "nullable": true, "maxLength": 12, "description": "Código NCM (Nomenclatura Comum do Mercosul) do SKU." }, "SkuNCMExTipi": { "type": "string", "nullable": true, "maxLength": 3, "description": "Ex TIPI (2 ou 3 dígitos)." }, "SkuCest": { "type": "string", "nullable": true, "maxLength": 15, "description": "Código CEST (Especificador da Substituição Tributária)." }, "SkuCst": { "type": "integer", "nullable": true, "description": "Origem do SKU (validada contra a tabela de origens da NF-e)." }, "CostSet": { "type": "number", "nullable": true, "description": "Custo manual cadastrado." }, "Batch": { "type": "integer", "nullable": true, "description": "`1` controla por lote, `0` não controla. Na criação o valor é definido pela parametrização `AutomaticBatchEnabledSku` da empresa — o valor enviado no corpo é ignorado no cadastro." }, "BatchRequired": { "type": "integer", "nullable": true, "description": "`1` exige o número do lote nas movimentações de entrada/saída. Na criação o valor é definido pela parametrização `AutomaticBatchRequiredEnabledSku` — o valor enviado no corpo é ignorado no cadastro." }, "RastroControl": { "type": "integer", "nullable": true, "description": "`1` ativa o controle de rastreabilidade extra: nos recebimentos passam a ser obrigatórias as datas de fabricação e validade. Na criação o valor é definido pela parametrização `AutomaticRastroEnabledSku` — o valor enviado no corpo é ignorado no cadastro." }, "BestBeforeDays": { "type": "integer", "nullable": true, "description": "Prazo de validade padrão (em dias) a partir da data de fabricação." }, "MinimumPickingLocationQuantity": { "type": "number", "nullable": true, "description": "Quantidade mínima do endereço de picking — abaixo disso é disparado ressuprimento." }, "MaximumPickingLocationQuantity": { "type": "number", "nullable": true, "description": "Quantidade máxima do endereço de picking — limita o ressuprimento." }, "MinimumBalanceDays": { "type": "integer", "nullable": true, "description": "Dias mínimos de cobertura de estoque considerados no cálculo de sugestão de compra." }, "MaximumBalanceDays": { "type": "integer", "nullable": true, "description": "Dias máximos de cobertura de estoque considerados no cálculo de sugestão de compra." }, "QtySafetyStock": { "type": "number", "nullable": true, "description": "Estoque mínimo de segurança." }, "Package": { "type": "integer", "nullable": true, "description": "`1` indica que o SKU é uma embalagem master usada para integração de catálogo. Default `0`." }, "InfiniteInventory": { "type": "integer", "nullable": true, "description": "`1` quando o SKU não precisa controlar estoque." }, "OwnProduction": { "type": "integer", "nullable": true, "description": "`1` quando produção própria. Default `0`." }, "SerialNumber": { "type": "integer", "nullable": true, "description": "`1` quando o SKU é controlado por número de série." }, "EstimatedDateArrival": { "type": "string", "format": "date", "nullable": true, "description": "Data estimada de chegada do SKU em uma reposição futura." }, "LeadTimeDays": { "type": "integer", "nullable": true, "description": "Lead time (em dias) entre pedido de compra e recebimento." }, "WarrantyTime": { "type": "string", "nullable": true, "maxLength": 45, "description": "Quantidade de garantia (número)." }, "WarrantyTimeType": { "type": "string", "nullable": true, "maxLength": 45, "description": "Unidade da garantia (`dias`, `meses`, `anos`)." }, "Comments": { "type": "string", "nullable": true, "maxLength": 500, "description": "Observações livres do SKU." }, "NfeComments": { "type": "string", "nullable": true, "maxLength": 200, "description": "Observações que serão impressas na NF-e." }, "NfeInvoiceAsKit": { "type": "integer", "nullable": true, "description": "`1` faz a NF-e detalhar os componentes do kit; `0` emite o kit como item único." }, "EcommerceDescription": { "type": "string", "nullable": true, "maxLength": 10000, "description": "Descrição completa para vitrine de e-commerce (texto rico)." }, "EcommerceDescriptionShort": { "type": "string", "nullable": true, "maxLength": 3000, "description": "Descrição curta para vitrine de e-commerce." }, "EcommerceKeyWords": { "type": "string", "nullable": true, "maxLength": 1000, "description": "Palavras-chave SEO separadas por vírgula." }, "EcommerceLinkId": { "type": "string", "nullable": true, "maxLength": 400, "description": "Slug (URL amigável) da página do produto." }, "EcommerceMetaTagDescription": { "type": "string", "nullable": true, "maxLength": 3000, "description": "Meta tag description para SEO." }, "EcommerceTitle": { "type": "string", "nullable": true, "maxLength": 200, "description": "Título da página do produto. Quando omitido, assume o `SkuName`." }, "EcommerceVideoUrl": { "type": "string", "nullable": true, "maxLength": 200, "description": "URL de vídeo de demonstração." }, "EcommerceKitAutomaticDescription": { "type": "integer", "nullable": true, "description": "`1` monta a descrição do kit automaticamente a partir dos componentes." }, "ShareProductImage": { "type": "integer", "nullable": true, "description": "`1` para compartilhar as imagens do produto-pai com este SKU." }, "AbcCurveAdjust": { "type": "string", "nullable": true, "maxLength": 1, "description": "Curva ABC ajustada manualmente (`A`, `B`, `C`) — sobrescreve a curva calculada automaticamente." }, "KitAutomaticPricingUpdate": { "type": "integer", "nullable": true, "description": "`1` recalcula automaticamente o preço do kit ao alterar a composição." }, "Tags": { "type": "array", "items": { "type": "string" }, "description": "Etiquetas livres do SKU." }, "PriceList": { "type": "number", "nullable": true, "description": "Preço de tabela na criação. Quando informado junto com `PriceSell` cria um registro inicial de preço." }, "PriceSell": { "type": "number", "nullable": true, "description": "Preço de venda na criação. Dispara a criação do registro de preço inicial." }, "IDCompanySalesPolicy": { "type": "integer", "nullable": true, "description": "Política comercial usada para os preços enviados na criação (validada apenas quando `PriceSell` é informado). Quando omitida, usa a política padrão da empresa." }, "Variations": { "type": "array", "nullable": true, "description": "Variações iniciais do SKU (tipo de variação `cor`, `tamanho`, etc. e o valor correspondente).", "items": { "type": "object", "required": [ "IDTypeProductVariation", "IDTypeProductVariationValue" ], "properties": { "IDTypeProductVariation": { "type": "integer", "description": "Identificador do tipo de variação (ex.: cor, tamanho)." }, "IDTypeProductVariationValue": { "type": "integer", "description": "Identificador do valor da variação (ex.: azul, M)." } } } }, "IDSkuCompanyComposing": { "type": "string", "nullable": true, "description": "Quando criando uma variação/componente de kit, código de referência do produto-pai a vincular. Usado em conjunto com o query param `Composing`." } } }, "SkuUpdateBody": { "type": "object", "description": "Corpo para atualização parcial de um SKU. Todos os campos são opcionais; envie apenas o que quer alterar. Alterar `IDTypeSku` tem regras adicionais (item sem movimentação, sem lote, sem ser componente de kit, sem variação, sem produto-pai — ver respostas de erro).", "properties": { "SkuName": { "type": "string", "nullable": true, "maxLength": 150, "description": "Nome do SKU." }, "IDSkuCompany": { "type": "string", "nullable": true, "maxLength": 100, "description": "Código de referência interno. Único por empresa." }, "IDTypeSku": { "type": "integer", "description": "Alteração restrita: SKU não pode ter movimentação, lote, componentes de kit, variação nem produto-pai." }, "IDStatusSku": { "type": "integer", "description": "Status do SKU: `1` Ativo, `2` Compra suspensa, `3` Inativo, `4` Venda suspensa.", "enum": [ 0, 1, 2, 3, 4 ] }, "BarCode": { "type": "string", "nullable": true, "maxLength": 20, "description": "Código de barras principal. Não pode duplicar entre SKUs da empresa." }, "IDBrand": { "type": "integer", "nullable": true, "description": "Identificador da marca." }, "IDCategory": { "type": "integer", "nullable": true, "description": "Identificador da categoria." }, "IDTaxDepartment": { "type": "integer", "nullable": true, "description": "Identificador do departamento fiscal." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Empresa faturadora vinculada ao SKU." }, "IDCompanyInvoiceIDCompanyIntegrationList": { "type": "string", "nullable": true, "description": "Lista (separada por vírgula) dos identificadores de integração em que a empresa faturadora informada deve ser usada." }, "IDStockKeepingUnitProductionLine": { "type": "integer", "nullable": true, "description": "Linha de produção associada ao SKU." }, "IDStockKeepingUnitLocationCategory": { "type": "integer", "nullable": true, "description": "Categoria de endereçamento sugerida." }, "IDTypeSkuCondition": { "type": "integer", "nullable": true, "description": "Condição do SKU: `1` Novo, `2` Usado, `3` Recondicionado.", "enum": [ 1, 2, 3 ] }, "MeasurementUnit": { "type": "string", "nullable": true, "maxLength": 45, "description": "Unidade de medida (`UN`, `KG`, `L`, etc.)." }, "SkuHeight": { "type": "number", "nullable": true, "description": "Altura em cm." }, "SkuLength": { "type": "number", "nullable": true, "description": "Comprimento em cm." }, "SkuWidth": { "type": "number", "nullable": true, "description": "Largura em cm." }, "SkuWeight": { "type": "number", "nullable": true, "description": "Peso bruto em kg." }, "SkuWeightNet": { "type": "number", "nullable": true, "description": "Peso líquido em kg." }, "SkuNCM": { "type": "string", "nullable": true, "maxLength": 12, "description": "Código NCM do SKU." }, "SkuNCMExTipi": { "type": "string", "nullable": true, "maxLength": 3, "description": "Ex TIPI do NCM (2 ou 3 dígitos)." }, "SkuCest": { "type": "string", "nullable": true, "maxLength": 15, "description": "Código CEST." }, "SkuCst": { "type": "integer", "nullable": true, "description": "Origem do SKU (CST — Código de Situação Tributária)." }, "CostSet": { "type": "number", "nullable": true, "description": "Custo manual cadastrado (sobrescreve `CostAverage` quando informado)." }, "Batch": { "type": "integer", "nullable": true, "description": "`1` ativa controle por lote; `0` desativa." }, "BatchRequired": { "type": "integer", "nullable": true, "description": "`1` exige número do lote nas movimentações." }, "RastroControl": { "type": "integer", "nullable": true, "description": "`1` ativa o controle de rastro sanitário." }, "BestBeforeRequired": { "type": "integer", "nullable": true, "description": "`1` exige data de validade nas entradas." }, "BestBeforeMinimumDays": { "type": "integer", "nullable": true, "description": "Validade mínima aceita na entrada (em dias)." }, "BestBeforeDays": { "type": "integer", "nullable": true, "description": "Prazo de validade padrão (em dias) a partir da fabricação." }, "MinimumPickingLocationQuantity": { "type": "number", "nullable": true, "description": "Quantidade mínima no endereço de picking — gatilho de ressuprimento." }, "MaximumPickingLocationQuantity": { "type": "number", "nullable": true, "description": "Quantidade máxima do endereço de picking." }, "QtySafetyStock": { "type": "number", "nullable": true, "description": "Estoque mínimo de segurança." }, "Package": { "type": "integer", "nullable": true, "description": "`1` define o SKU como embalagem master." }, "PackageOccupation": { "type": "number", "nullable": true, "description": "Ocupação no endereçamento (fator de capacidade)." }, "InfiniteInventory": { "type": "integer", "nullable": true, "description": "`1` quando o SKU não controla estoque (serviços, itens digitais)." }, "OwnProduction": { "type": "integer", "nullable": true, "description": "`1` para produção própria (libera ordens de produção)." }, "SerialNumber": { "type": "integer", "nullable": true, "description": "`1` controla o SKU por número de série." }, "EstimatedDateArrival": { "type": "string", "format": "date", "nullable": true, "description": "Data estimada de chegada em reposição futura." }, "LeadTimeDays": { "type": "integer", "nullable": true, "description": "Lead time entre compra e recebimento (dias)." }, "WarrantyTime": { "type": "string", "nullable": true, "maxLength": 45, "description": "Quantidade de garantia." }, "WarrantyTimeType": { "type": "string", "nullable": true, "maxLength": 45, "description": "Unidade da garantia (`dias`, `meses`, `anos`)." }, "Comments": { "type": "string", "nullable": true, "maxLength": 500, "description": "Observações livres." }, "NfeComments": { "type": "string", "nullable": true, "maxLength": 200, "description": "Observações impressas na NF-e." }, "NfeInvoiceAsKit": { "type": "integer", "nullable": true, "description": "`1` detalha componentes do kit na NF-e; `0` emite como item único." }, "NfeFactorPercentSku": { "type": "number", "nullable": true, "description": "Quando enviado, zera `NfeFactorFixedSkuValue` automaticamente." }, "NfeFactorPercentSkuIDCompanyIntegrationList": { "type": "string", "nullable": true, "description": "Lista (separada por vírgula) dos identificadores de integração em que o fator percentual de NF-e deve ser aplicado." }, "NfeFactorFixedSkuValue": { "type": "number", "nullable": true, "description": "Só persistido se `NfeFactorPercentSku` for `null`." }, "EcommerceDescription": { "type": "string", "nullable": true, "maxLength": 10000, "description": "Descrição completa para vitrine." }, "EcommerceDescriptionShort": { "type": "string", "nullable": true, "maxLength": 3000, "description": "Descrição curta para vitrine." }, "EcommerceKeyWords": { "type": "string", "nullable": true, "maxLength": 1000, "description": "Palavras-chave SEO." }, "EcommerceLinkId": { "type": "string", "nullable": true, "maxLength": 400, "description": "Slug da URL do produto." }, "EcommerceMetaTagDescription": { "type": "string", "nullable": true, "maxLength": 3000, "description": "Meta description (SEO)." }, "EcommerceTitle": { "type": "string", "nullable": true, "maxLength": 200, "description": "Título da página do produto." }, "EcommerceVideoUrl": { "type": "string", "nullable": true, "maxLength": 200, "description": "URL de vídeo de demonstração." }, "EcommerceKitAutomaticDescription": { "type": "integer", "nullable": true, "description": "`1` compõe automaticamente a descrição do kit a partir dos componentes." }, "ShareProductImage": { "type": "integer", "nullable": true, "description": "`1` compartilha as imagens do produto-pai com a variação." }, "AbcCurveAdjust": { "type": "string", "nullable": true, "maxLength": 1, "description": "Curva ABC ajustada manualmente (`A`, `B`, `C`)." }, "KitAutomaticMeasureUpdate": { "type": "integer", "nullable": true, "description": "`1` para que medidas do kit sejam recalculadas automaticamente a partir dos componentes." }, "KitAutomaticPricingUpdate": { "type": "integer", "nullable": true, "description": "`1` recalcula automaticamente o preço do kit." }, "BuyOrderAlert": { "type": "integer", "nullable": true, "description": "Liga alerta de pedido de compra quando estoque cai abaixo da quantidade configurada." }, "BuyOrderAlertManualQuantity": { "type": "integer", "nullable": true, "description": "Quantidade que dispara o alerta de compra (`BuyOrderAlert=1`)." }, "Tags": { "type": "array", "items": { "type": "string" }, "description": "Etiquetas livres do SKU (atualização substitui o conjunto inteiro)." } } }, "SkuImage": { "type": "object", "description": "Imagem do SKU.", "properties": { "IDImage": { "type": "integer", "description": "Identificador da imagem." }, "IDSku": { "type": "integer", "description": "Identificador do SKU dono da imagem." }, "Url": { "type": "string", "nullable": true, "maxLength": 400, "description": "URL pública da imagem no CDN." }, "ImageName": { "type": "string", "nullable": true, "maxLength": 300, "description": "Nome original do arquivo enviado." }, "ImageSize": { "type": "integer", "nullable": true, "description": "Tamanho do arquivo em bytes." }, "ImageWidth": { "type": "integer", "nullable": true, "description": "Largura da imagem em pixels." }, "ImageHeight": { "type": "integer", "nullable": true, "description": "Altura da imagem em pixels." }, "ImageOrder": { "type": "integer", "description": "Ordem de exibição da imagem na galeria (números menores aparecem primeiro)." }, "IsMain": { "type": "integer", "description": "`1` indica a imagem principal." }, "Kit": { "type": "integer", "description": "Identifica a qual kit (1-4) a imagem está associada." }, "ShareProductImage": { "type": "integer", "nullable": true, "description": "`1` quando a imagem é compartilhada com as variações do produto-pai." }, "ProductImage": { "type": "integer", "nullable": true, "description": "`1` quando a imagem foi herdada do produto-pai." } } }, "KitItem": { "type": "object", "description": "Item (componente) de um kit.", "properties": { "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDStockKeepingUnitKitItems": { "type": "integer", "description": "Identificador da linha do componente no kit." }, "IDSkuComponent": { "type": "integer", "description": "Identificador do SKU usado como componente." }, "Quantity": { "type": "number", "description": "Quantidade do componente no kit." }, "Kit": { "type": "integer", "description": "Variante do kit (1 a 4)." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome do SKU componente." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência interno do SKU componente." }, "CostAverage": { "type": "number", "nullable": true, "description": "Custo médio unitário do componente." }, "CostAverageTotal": { "type": "number", "nullable": true, "description": "Custo médio total da participação do componente no kit (`CostAverage * Quantity`)." }, "CostSet": { "type": "number", "nullable": true, "description": "Custo manual unitário do componente." }, "CostSetTotal": { "type": "number", "nullable": true, "description": "Custo manual total da participação no kit." }, "CostLastPurchase": { "type": "number", "nullable": true, "description": "Custo da última compra do componente (unitário)." }, "CostLastPurchaseTotal": { "type": "number", "nullable": true, "description": "Custo da última compra total para a participação no kit." }, "QtyAvailable": { "type": "number", "nullable": true, "description": "Quantidade disponível do componente em estoque." }, "PriceSell": { "type": "number", "nullable": true, "description": "Preço de venda unitário do componente." }, "PriceSellTotal": { "type": "number", "nullable": true, "description": "Preço de venda total da participação do componente no kit." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do componente." }, "MainImageThumbnailURL": { "type": "string", "nullable": true, "description": "URL da miniatura da imagem principal do componente." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que o componente foi adicionado ao kit." } } }, "KitSummary": { "type": "object", "description": "Resumo de cada variante de kit (1 a 4) de um SKU pai.", "properties": { "index": { "type": "integer", "description": "Posição (1 a 4) do kit alternativo dentro do SKU. O sistema permite até 4 composições alternativas por kit (`Kit=1..4`)." }, "IDStockKeepingUnitKit": { "type": "integer", "description": "Identificador do registro de configuração do kit alternativo." }, "Active": { "type": "integer", "description": "`1` quando este kit é o ativo do SKU." }, "Kit": { "type": "integer", "description": "Número da variante (1 a 4)." }, "Priority": { "type": "integer", "nullable": true, "description": "Prioridade do kit alternativo na seleção automática durante a venda — menor valor é tentado primeiro." }, "QtyAvailable": { "type": "integer", "nullable": true, "description": "Quantidade montável a partir do estoque dos componentes." }, "QtySku": { "type": "integer", "nullable": true, "description": "Quantidade distinta de componentes." }, "QtyItems": { "type": "number", "nullable": true, "description": "Soma das quantidades dos componentes." }, "SumSellingPrice": { "type": "number", "nullable": true, "description": "Soma do preço de venda dos componentes dessa composição." }, "SumListPrice": { "type": "number", "nullable": true, "description": "Soma do preço de tabela dos componentes." }, "SumCostAverage": { "type": "number", "nullable": true, "description": "Soma do custo médio dos componentes." }, "Markup": { "type": "string", "nullable": true, "description": "`SumSellingPrice / SumCostAverage`, com duas casas." } } }, "SkuPricing": { "type": "object", "description": "Preço de um SKU em uma política comercial.", "properties": { "IDStockKeepingUnitPricing": { "type": "integer", "description": "Identificador do registro de preço." }, "IDSku": { "type": "integer", "description": "Identificador do SKU precificado." }, "IDCompanySalesPolicy": { "type": "integer", "description": "Identificador da política comercial (tabela de preço) a que o preço pertence." }, "CompanySalesPolicy": { "type": "string", "nullable": true, "description": "Nome da política comercial." }, "IDTypeCompanySalesPolicy": { "type": "integer", "nullable": true, "description": "Tipo da política comercial: `1` Normal, `2` Custo médio, `3` Relativa à outra política.", "enum": [ 1, 2, 3 ] }, "PriceList": { "type": "number", "nullable": true, "description": "Preço de tabela." }, "PriceSell": { "type": "number", "description": "Preço de venda. Não pode ser zerado (vide regras da empresa)." }, "DateFrom": { "type": "string", "format": "date", "description": "Vigência inicial. Default `1900-01-01`." }, "DateTo": { "type": "string", "format": "date", "description": "Vigência final. Default `4000-01-01`." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência interno do SKU." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal do SKU." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome do SKU." }, "TypeProduct": { "type": "string", "nullable": true, "description": "Descrição textual do tipo do SKU." }, "IDTypeSku": { "type": "integer", "nullable": true, "description": "Tipo do SKU (vide enum em `IDTypeSku`)." }, "CostSet": { "type": "number", "nullable": true, "description": "Custo manual cadastrado." }, "CostAverage": { "type": "number", "nullable": true, "description": "Custo médio calculado." }, "CostLastPurchase": { "type": "number", "nullable": true, "description": "Custo da última compra." }, "QtyAvailable": { "type": "string", "nullable": true, "description": "Quantidade disponível em estoque." }, "InventoryValue": { "type": "number", "nullable": true, "description": "Valor monetário do estoque." }, "Markup": { "type": "number", "nullable": true, "description": "Razão entre o preço de venda e o custo médio (`PriceSell / CostAverage`). Ex.: `2.5` indica que o preço é 2,5× o custo médio. `null` quando `CostAverage <= 0` ou `PriceSell <= 0`." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Integrações que consomem essa política, concatenadas." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do preço." }, "DateLastRecordModification": { "type": "string", "format": "date-time", "description": "Data e hora da última alteração do preço." } } }, "SkuPricingCreateBody": { "type": "object", "description": "Corpo para criar/atualizar um preço de SKU.", "required": [ "PriceSell", "DateFrom", "DateTo" ], "properties": { "PriceSell": { "type": "number", "description": "Preço de venda. Rejeitado quando zerado e a empresa não permite preço de venda zerado. Numa política do tipo Relativa à outra política (`IDTypeCompanySalesPolicy=3`), é recalculado a partir do preço da política base e o valor enviado é ignorado." }, "PriceList": { "type": "number", "nullable": true, "description": "Preço de tabela. Numa política Relativa à outra política, é recalculado a partir da política base." }, "DateFrom": { "type": "string", "format": "date", "description": "Início da vigência do preço. Obrigatório e deve ser uma data válida." }, "DateTo": { "type": "string", "format": "date", "description": "Fim da vigência do preço. Obrigatório e deve ser uma data válida." }, "IDCompanySalesPolicy": { "type": "integer", "nullable": true, "description": "Política comercial (tabela de preço) à qual o preço pertence. Quando omitido, usa a política padrão da empresa." } } }, "SkuSerial": { "type": "object", "description": "Número de série de um SKU.", "properties": { "IDStockKeepingUnitSerialNumber": { "type": "integer", "description": "Identificador do registro de número de série." }, "IDSku": { "type": "integer", "description": "Identificador do SKU controlado por número de série." }, "SerialNumber": { "type": "string", "maxLength": 45, "description": "Número de série único da unidade." }, "IDSkuMovementInbound": { "type": "integer", "nullable": true, "description": "Identificador da movimentação de entrada que cadastrou este número de série." }, "IDSkuMovementOutbound": { "type": "integer", "nullable": true, "description": "Identificador da movimentação de saída que consumiu este número de série (quando aplicável)." }, "IDTypeStatusSkuSerialNumber": { "type": "integer", "description": "Status do número de série: `1` Disponível, `2` Bloqueado, `3` Utilizado.", "enum": [ 1, 2, 3 ] }, "TypeStatusSkuSerialNumber": { "type": "string", "nullable": true, "description": "Status do número de série (em estoque, vendido, em garantia, etc.)." }, "IDPurchase": { "type": "integer", "nullable": true, "description": "Recebimento (entrada) que vinculou o serial." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido (saída) que consumiu o serial." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do registro." } } }, "SkuCollectionAssociation": { "type": "object", "description": "Vínculo entre SKU e coleção.", "properties": { "IDStockKeepingUnitCollectionAssociation": { "type": "integer", "description": "Identificador da associação SKU↔coleção." }, "IDSku": { "type": "integer", "description": "Identificador do SKU associado à coleção." }, "IDStockKeepingUnitCollection": { "type": "integer", "description": "Identificador da coleção." }, "StockKeepingUnitCollectionName": { "type": "string", "nullable": true, "description": "Nome da coleção." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que o SKU foi adicionado à coleção." } } }, "SkuGroupAssociation": { "type": "object", "description": "Vínculo entre SKU e grupo de SKU.", "properties": { "IDStockKeepingUnitGroupAssociation": { "type": "integer", "description": "Identificador da associação SKU↔grupo." }, "IDSku": { "type": "integer", "description": "Identificador do SKU." }, "IDStockKeepingUnitGroup": { "type": "integer", "description": "Identificador do grupo de SKUs." }, "SkuGroupName": { "type": "string", "nullable": true, "description": "Nome do grupo." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "StockKeepingUnitSimilarCode": { "type": "array", "description": "Códigos similares cadastrados no grupo.", "items": { "type": "object", "properties": { "IDStockKeepingUnitSimilarCode": { "type": "integer", "description": "Identificador do código similar vinculado ao SKU dentro deste grupo." }, "SkuSimilarCode": { "type": "string", "description": "Código de referência similar (texto livre, usado para mapear o SKU em sistemas externos)." }, "SkuSimilarCodeTag": { "type": "string", "nullable": true, "description": "Etiqueta/categoria do código similar (ex.: nome do canal ou marketplace que utiliza esse código)." } } } }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora em que o SKU foi vinculado ao grupo." } } }, "SkuVariationValue": { "type": "object", "description": "Valor de variação (grade) atribuído ao SKU. Ex.: variação `Cor` com valor `Azul`.", "properties": { "IDStockKeepingUnitVariation": { "type": "integer", "description": "Identificador do registro de variação do SKU." }, "IDSku": { "type": "integer", "description": "Identificador do SKU variação." }, "IDTypeProductVariation": { "type": "integer", "description": "Identificador do tipo de variação (ex.: cor, tamanho)." }, "ProductVariation": { "type": "string", "nullable": true, "description": "Nome da variação (ex.: `Cor`)." }, "IDTypeProductVariationValue": { "type": "integer", "description": "Identificador do valor da variação (ex.: azul, M)." }, "TypeProductVariationValue": { "type": "string", "nullable": true, "description": "Valor da variação (ex.: `Azul`)." } } }, "SkuProductVariation": { "type": "object", "description": "Associação entre um SKU variação e o seu produto-pai.", "properties": { "IDStockKeepingUnitProductVariation": { "type": "integer", "description": "Identificador do vínculo entre SKU pai e SKU variação." }, "IDProduct": { "type": "integer", "description": "SKU produto-pai." }, "IDSku": { "type": "integer", "description": "SKU variação filho." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome da variação." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal da variação." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência interno da variação." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "TypeProduct": { "type": "string", "nullable": true, "description": "Descrição textual do tipo do SKU." }, "IDTypeSku": { "type": "integer", "nullable": true, "description": "Tipo do SKU (vide enum em `IDTypeSku`)." }, "MeasurementUnit": { "type": "string", "nullable": true, "description": "Unidade de medida." }, "MeasurementUnitDescription": { "type": "string", "nullable": true, "description": "Descrição da unidade de medida." }, "SkuHeight": { "type": "number", "nullable": true, "description": "Altura em cm." }, "SkuLength": { "type": "number", "nullable": true, "description": "Comprimento em cm." }, "SkuWidth": { "type": "number", "nullable": true, "description": "Largura em cm." }, "SkuWeight": { "type": "number", "nullable": true, "description": "Peso bruto em kg." }, "SkuWeightNet": { "type": "number", "nullable": true, "description": "Peso líquido em kg." }, "SkuNCM": { "type": "string", "nullable": true, "description": "Código NCM." }, "SkuCest": { "type": "string", "nullable": true, "description": "Código CEST." }, "SkuCst": { "type": "integer", "nullable": true, "description": "Origem do SKU (CST)." }, "SkuCstDescription": { "type": "string", "nullable": true, "description": "Descrição textual da origem." }, "SkuNCMExTipi": { "type": "string", "nullable": true, "description": "Ex TIPI do NCM." }, "IDTaxDepartment": { "type": "integer", "nullable": true, "description": "Identificador do departamento fiscal." }, "TaxDepartmentDescription": { "type": "string", "nullable": true, "description": "Descrição do departamento fiscal." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal da variação." }, "ShareProductImage": { "type": "integer", "nullable": true, "description": "`1` quando a variação reusa as imagens do produto-pai." }, "IDStatusSku": { "type": "integer", "description": "Status da variação: `1` Ativo, `2` Compra suspensa, `3` Inativo, `4` Venda suspensa.", "enum": [ 0, 1, 2, 3, 4 ] }, "TypeStatusSku": { "type": "string", "nullable": true, "description": "Descrição textual do status." }, "ProductVariation": { "type": "string", "nullable": true, "description": "Variações ordenadas, concatenadas (`Cor,Tamanho`)." }, "TypeProductVariationValue": { "type": "string", "nullable": true, "description": "Valores correspondentes (`Azul,M`)." }, "TypeProductVariationValueOrder": { "type": "string", "nullable": true, "description": "Ordenação concatenada das variações (ex.: `Azul-M`) — usada para classificar a variação na grade." }, "ProductVariationArray": { "type": "array", "description": "Variações expandidas em pares nome/valor.", "items": { "type": "object", "properties": { "ProductVariation": { "type": "string", "description": "Nome do tipo de variação (ex.: `Cor`)." }, "TypeProductVariationValue": { "type": "string", "description": "Valor da variação (ex.: `Azul`)." } } } }, "PriceSell": { "type": "number", "nullable": true, "description": "Preço de venda da variação." }, "PriceList": { "type": "number", "nullable": true, "description": "Preço de tabela da variação." }, "QtyAvailable": { "type": "string", "nullable": true, "description": "Quantidade disponível em estoque." } } }, "SkuSpecificationField": { "type": "object", "description": "Campo de especificação técnica disponível para o SKU, com valor atual quando preenchido.", "properties": { "IDStockKeepingUnitSpecificationsFieldId": { "type": "integer", "description": "Identificador do campo de especificação cadastrado para a categoria." }, "IDStockKeepingUnitSpecifications": { "type": "integer", "nullable": true, "description": "Identificador do valor de especificação preenchido para este SKU (quando já foi salvo)." }, "FieldName": { "type": "string", "description": "Nome do campo de especificação (ex.: `Voltagem`, `Material`)." }, "IDStockKeepingUnitSpecificationsFieldTypes": { "type": "integer", "description": "Tipo do campo: `1` texto, `2` número, `3` data, `4` combo único, `5` combo múltiplo, `6` radio." }, "FieldType": { "type": "string", "nullable": true, "description": "Tipo de dado do campo (`text`, `number`, `select`, `date`, etc.)." }, "IDFieldExternal": { "type": "string", "nullable": true, "description": "Identificador externo do campo (mapeamento para marketplaces ou hubs)." }, "IDCategory": { "type": "integer", "description": "Categoria à qual o campo pertence." }, "CategoryName": { "type": "string", "nullable": true, "description": "Nome da categoria." }, "FieldValue": { "description": "Para tipos texto/número/data, o valor literal. Para tipos combo/radio, array de objetos `{IDStockKeepingUnitSpecificationsFieldValues, Value}`." } } }, "SkuLogItem": { "type": "object", "description": "Registro de log de integração de SKU.", "properties": { "IDStockKeepingUnitIntegrationLog": { "type": "integer", "description": "Identificador da linha de log de integração." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDSku": { "type": "integer", "description": "Identificador do SKU integrado." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência interno do SKU." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome do SKU." }, "Comments": { "type": "string", "nullable": true, "description": "Detalhe da operação (mensagem de erro ou JSON do corpo)." }, "Header": { "type": "integer", "description": "`1` sucesso, `2` inativo, demais valores = erro." }, "Status": { "type": "string", "description": "Tradução de `Header` (`Sucesso`, `Inativo`, `Erro`)." }, "IDAction": { "type": "integer", "description": "Tipo de ação registrada (`IDSkuAction`)." }, "ActionName": { "type": "string", "nullable": true, "description": "Ação executada na integração (ex.: `Create`, `Update`, `Delete`, `Stock`, `Price`)." }, "IDHubProduct": { "type": "integer", "nullable": true, "description": "Identificador do produto no Hub (intermediário entre o idworks e o canal de venda)." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Identificador da integração (loja/marketplace) que originou o log." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Nome da integração no formato `Tipo - Nome`." }, "RecordUserCreated": { "type": "string", "nullable": true, "description": "Login do usuário que disparou o registro." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora do log." } } }, "SkuWarehouseBalance": { "type": "object", "description": "Saldo do SKU em um armazém, com detalhamento por pedido/produção/recebimento/ressuprimento.", "properties": { "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Identificador do depósito." }, "WarehouseName": { "type": "string", "nullable": true, "description": "Nome do depósito." }, "Default": { "type": "integer", "nullable": true, "description": "`1` quando este é o depósito padrão da empresa." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "description": "Centro de distribuição ao qual o depósito pertence." }, "DistributionCenterName": { "type": "string", "nullable": true, "description": "Nome do centro de distribuição." }, "QtyAvailable": { "type": "string", "description": "Quantidade disponível neste depósito." }, "QtyOnStock": { "type": "string", "description": "Disponível + reservado + em separação." }, "QtyReserved": { "type": "string", "description": "Quantidade reservada em pedidos não faturados." }, "QtyHandling": { "type": "string", "description": "Em separação (picking/packing)." }, "QtyBuyOrdem": { "type": "string", "description": "Pedido de compra menos o já recebido." }, "QtyToReceipt": { "type": "string", "description": "Em recebimento." }, "QtyProduction": { "type": "string", "description": "Em produção." }, "QtyResupply": { "type": "string", "description": "Em ressuprimento." }, "InventoryValue": { "type": "number", "nullable": true, "description": "Valor monetário do saldo no depósito (`CostAverage * QtyAvailable`)." }, "CostAverage": { "type": "string", "nullable": true, "description": "Custo médio aplicado a este depósito." }, "QtyReservedOrders": { "type": "array", "items": { "type": "object", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do pedido reservado." }, "IDOrder": { "type": "integer", "description": "Identificador do pedido de venda." }, "IDStatusOrder": { "type": "integer", "description": "Status do pedido (vide tabela de status de pedido)." }, "Order": { "type": "string", "description": "Número de exibição do pedido." }, "StatusOrder": { "type": "string", "description": "Descrição textual do status do pedido." }, "Quantity": { "type": "number", "description": "Quantidade reservada por este pedido." } } }, "description": "Pedidos de venda em aberto que reservam estoque neste depósito." }, "QtyHandlingOrders": { "type": "array", "items": { "type": "object", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do pedido em manuseio." }, "IDOrder": { "type": "integer", "description": "Identificador do pedido." }, "IDStatusOrder": { "type": "integer", "description": "Status do pedido." }, "Order": { "type": "string", "description": "Número de exibição do pedido." }, "StatusOrder": { "type": "string", "description": "Descrição textual do status." }, "Quantity": { "type": "number", "description": "Quantidade em manuseio para este pedido." } } }, "description": "Pedidos em manuseio/separação que estão consumindo estoque deste depósito." }, "QtyProductionOrders": { "type": "array", "items": { "type": "object", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação da ordem." }, "IDStockKeepingUnitProduction": { "type": "integer", "description": "Identificador da ordem de produção." }, "IDTypeStatusSkuProduction": { "type": "integer", "description": "Status da etapa de produção: `1` Finalizado, `2` Aberto, `3` Em andamento, `4` Cancelado.", "enum": [ 1, 2, 3, 4 ] }, "TypeStatusSkuProduction": { "type": "string", "description": "Descrição textual do status." }, "Quantity": { "type": "number", "description": "Quantidade prevista pela ordem de produção." } } }, "description": "Ordens de produção em aberto que vão gerar entrada futura no depósito." }, "QtyBuyOrdemOrders": { "type": "array", "items": { "type": "object", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do pedido de compra." }, "IDBuyOrder": { "type": "integer", "description": "Identificador do pedido de compra." }, "IDStatusBuyOrder": { "type": "integer", "description": "Status do pedido de compra.", "enum": [ 0, 1, 2, 3, 5, 6, 7 ] }, "StatusBuyOrder": { "type": "string", "description": "Descrição textual do status." }, "Quantity": { "type": "number", "description": "Quantidade pedida." } } }, "description": "Pedidos de compra em aberto que vão gerar entrada futura no depósito." }, "QtyToReceiptOrders": { "type": "array", "items": { "type": "object", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do recebimento." }, "IDPurchase": { "type": "integer", "description": "Identificador do recebimento." }, "IDStatusPurchase": { "type": "integer", "description": "Status do recebimento." }, "StatusPurchase": { "type": "string", "description": "Descrição textual do status." }, "Quantity": { "type": "number", "description": "Quantidade a receber." } } }, "description": "Recebimentos (compras) em aberto pendentes de entrada efetiva." }, "QtyToResupply": { "type": "array", "items": { "type": "object", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora de criação do ressuprimento." }, "IDStockKeepingUnitResupplyList": { "type": "integer", "description": "Identificador do ressuprimento." }, "IDResupplyStatus": { "type": "integer", "description": "Status do ressuprimento: `1` Aberto, `2` Iniciado, `3` Finalizado, `4` Cancelado.", "enum": [ 1, 2, 3, 4 ] }, "StatusResupply": { "type": "string", "description": "Descrição textual do status." }, "Quantity": { "type": "number", "description": "Quantidade do ressuprimento." } } }, "description": "Ressuprimentos pendentes que vão movimentar estoque do/para este depósito." } } }, "SkuPackageItem": { "type": "object", "description": "SKU embalagem (`Package=1`) compartilhado entre empresas integradas via DE-PARA.", "properties": { "IDSku": { "type": "integer", "description": "Identificador do SKU embalagem." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa." }, "Package": { "type": "integer", "description": "`1` confirma que o SKU é uma embalagem master (caixa/fardo)." }, "IDTypeSku": { "type": "integer", "description": "Tipo do SKU." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência interno do SKU." }, "SkuName": { "type": "string", "nullable": true, "description": "Nome da embalagem." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal." }, "Batch": { "type": "integer", "description": "`1` quando a embalagem controla lote." }, "IDBrand": { "type": "integer", "nullable": true, "description": "Identificador da marca." }, "SkuNCM": { "type": "string", "nullable": true, "description": "Código NCM." }, "IDTaxDepartment": { "type": "integer", "nullable": true, "description": "Identificador do departamento fiscal." }, "IDCategory": { "type": "integer", "nullable": true, "description": "Identificador da categoria." }, "OwnProduction": { "type": "integer", "description": "`1` quando a embalagem é de produção própria." }, "EcommerceDescription": { "type": "string", "nullable": true, "description": "Descrição da embalagem para vitrine de e-commerce." }, "SkuCst": { "type": "integer", "nullable": true, "description": "Origem do SKU (CST)." }, "SkuCest": { "type": "string", "nullable": true, "description": "Código CEST." }, "CostSet": { "type": "number", "nullable": true, "description": "Custo manual." }, "CostAverage": { "type": "number", "nullable": true, "description": "Custo médio." }, "CostLastPurchase": { "type": "number", "nullable": true, "description": "Custo da última compra." }, "SkuHeight": { "type": "number", "nullable": true, "description": "Altura em cm." }, "SkuLength": { "type": "number", "nullable": true, "description": "Comprimento em cm." }, "SkuWidth": { "type": "number", "nullable": true, "description": "Largura em cm." }, "SkuWeight": { "type": "number", "nullable": true, "description": "Peso bruto em kg." }, "QtyAvailable": { "type": "string", "description": "Quantidade disponível em estoque." } } }, "SkuTag": { "type": "object", "description": "Etiqueta livre de SKU.", "properties": { "Tag": { "type": "string", "description": "Texto livre da etiqueta cadastrada no SKU." }, "AccountName": { "type": "string", "description": "Conta (subdomínio) da empresa dona da etiqueta." } } }, "SkuSimilarCategory": { "type": "object", "description": "Categoria similar associada ao SKU.", "properties": { "IDStockKeepingUnitSimilarCategory": { "type": "integer", "description": "Identificador da associação categoria-similar do SKU." }, "IDCategory": { "type": "integer", "description": "Identificador da categoria considerada similar." }, "CategoryTree": { "type": "string", "nullable": true, "description": "Caminho completo da categoria (`Pai -> Filha -> Neta`)." } } }, "JobScheduledResponse": { "type": "object", "description": "Resposta de confirmação de um job assíncrono (`statusCode` + `body`). O formato exato do `body` varia conforme o tipo de job.", "properties": { "statusCode": { "type": "integer", "description": "Status HTTP do retorno imediato — `202` indica que o job foi aceito e enfileirado para processamento em background; o resultado final não vem nesta resposta." }, "body": { "type": "string", "description": "Conteúdo JSON ou texto plano, dependendo do tipo de job." } }, "additionalProperties": true }, "OrderItem": { "type": "object", "description": "Item de pedido — produto vendido, com quantidade, preço e dados fiscais.", "properties": { "IDSku": { "type": "integer", "description": "Identificador do produto." }, "IDCategory": { "type": "integer", "nullable": true, "description": "Identificador da categoria do produto." }, "IDCategoryArray": { "type": "array", "items": { "type": "string" }, "description": "Cadeia de categorias (da raiz até a folha) do produto." }, "CommentsInvoice": { "type": "string", "nullable": true, "description": "Observações deste item na nota fiscal." }, "SkuName": { "type": "string", "description": "Nome completo do produto (inclui prefixo da variação quando aplicável)." }, "SkuNameOnly": { "type": "string", "nullable": true, "description": "Nome do produto sem o prefixo da variação. Removido da resposta quando a parametrização `OnlySkuName` está ligada." }, "ReverseTaxCalculation": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, ICMS-ST/IPI/FCP-ST somam ao total do item; quando `0`, já estão embutidos no preço." }, "NfeCFOP": { "type": "string", "nullable": true, "description": "CFOP fiscal aplicado a este item." }, "NfeIcmsCst": { "type": "string", "nullable": true, "description": "CST do ICMS." }, "SkuWeightTotal": { "type": "number", "nullable": true, "description": "Peso total (peso unitário x quantidade) em kg." }, "IDTypeSku": { "type": "integer", "nullable": true, "description": "Tipo do produto (`StockKeepingUnit`, `Kit`, etc.)." }, "NfeIbsCbsCST": { "type": "string", "nullable": true, "description": "CST IBS/CBS (reforma tributária)." }, "NfeIbsCbsBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo IBS/CBS." }, "NfeIbsAliquot": { "type": "number", "nullable": true, "description": "Alíquota IBS." }, "NfeIbspRedAliquot": { "type": "number", "nullable": true, "description": "Percentual de redução da alíquota IBS." }, "NfeIbsValue": { "type": "number", "nullable": true, "description": "Valor de IBS." }, "NfeCbsAliquot": { "type": "number", "nullable": true, "description": "Alíquota CBS." }, "NfeCbspRedAliquot": { "type": "number", "nullable": true, "description": "Percentual de redução da alíquota CBS." }, "NfeCbsValue": { "type": "number", "nullable": true, "description": "Valor de CBS." }, "AbcCurve": { "type": "string", "nullable": true, "description": "Classificação ABC do produto." }, "Quantity": { "type": "number", "description": "Quantidade vendida." }, "PriceSelling": { "type": "number", "description": "Preço unitário de venda (já com desconto aplicado)." }, "PriceList": { "type": "number", "description": "Preço unitário de tabela (antes do desconto)." }, "ValueDiscount": { "type": "number", "nullable": true, "description": "Valor unitário de desconto aplicado." }, "PercentDiscount": { "type": "number", "nullable": true, "description": "Percentual de desconto sobre o preço de tabela." }, "PriceSellingTotal": { "type": "number", "description": "Total do item (preço unitário com desconto x quantidade)." }, "IDSkuMovement": { "type": "integer", "description": "Identificador da movimentação deste item." }, "QtyAvailable": { "type": "number", "description": "Quantidade disponível em estoque no armazém do item." }, "PackageNumber": { "type": "integer", "nullable": true, "description": "Número do pacote ao qual este item foi alocado." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras do produto." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código interno do produto (SKU da empresa)." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa proprietária do produto." }, "Batch": { "type": "integer", "nullable": true, "description": "Identificador do lote (`IDBatch`)." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do produto." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Validade do lote." }, "Address": { "type": "string", "nullable": true, "description": "Endereço de estoque do lote (corredor/prateleira)." }, "IDStockKeepingUnitLocation": { "type": "integer", "nullable": true, "description": "Identificador do endereço de estoque." }, "AddressDefault": { "type": "string", "nullable": true, "description": "Endereço de estoque padrão do produto no armazém." }, "QuantityNonconformity": { "type": "number", "nullable": true, "description": "Quantidade não conforme apurada no atendimento." }, "IDTypeFulfillmentNonconformity": { "type": "integer", "nullable": true, "description": "Tipo da não conformidade.", "enum": [ 1, 2, 4, 5, 6 ] }, "TypeFulfillmentNonconformity": { "type": "string", "nullable": true, "description": "Descrição do tipo de não conformidade." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "nullable": true, "description": "Armazém de origem do item." }, "WarehouseName": { "type": "string", "nullable": true, "description": "Nome do armazém." }, "IDTaxDepartment": { "type": "integer", "nullable": true, "description": "Departamento fiscal do produto." }, "TaxDepartmentDescription": { "type": "string", "nullable": true, "description": "Descrição do departamento fiscal." }, "SkuNCM": { "type": "string", "nullable": true, "description": "NCM do produto." }, "SkuCst": { "type": "string", "nullable": true, "description": "Origem da mercadoria (CST de origem)." }, "NfOrigDescription": { "type": "string", "nullable": true, "description": "Descrição da origem da mercadoria." }, "Comments": { "type": "string", "nullable": true, "description": "Observações deste item." }, "IDSkuKit": { "type": "integer", "nullable": true, "description": "Quando o item é componente de um kit, traz o identificador do kit pai." }, "QuantityKit": { "type": "number", "nullable": true, "description": "Quantidade do kit." }, "KitSkuName": { "type": "string", "nullable": true, "description": "Nome do kit pai." }, "KitIDSkuCompany": { "type": "string", "nullable": true, "description": "Código interno do kit pai." }, "KitBarCode": { "type": "string", "nullable": true, "description": "Código de barras do kit pai." }, "Gratification": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, o item é brinde/bonificação e não compõe o valor do pedido." }, "NfeNItemPed": { "type": "string", "nullable": true, "description": "Número do item no pedido externo (referência para integrações fiscais)." }, "NfeValueFcpSt": { "type": "number", "description": "Valor FCP-ST do item." }, "NfeValueIpi": { "type": "number", "description": "Valor IPI do item." }, "NfeValueIcmsST": { "type": "number", "description": "Valor ICMS-ST do item." }, "EstimatedDeliveredDate": { "type": "string", "format": "date", "nullable": true, "description": "Previsão de entrega informada pelo fornecedor para itens vinculados a pedido de compra." }, "IDBuyOrder": { "type": "integer", "nullable": true, "description": "Pedido de compra que abastecerá este item." }, "BrandName": { "type": "string", "nullable": true, "description": "Marca do produto." }, "SerialNumberUsed": { "type": "string", "nullable": true, "description": "Lista de números de série utilizados na saída (separados por vírgula)." }, "IDSalesmanComission": { "type": "integer", "nullable": true, "description": "Regra de comissão aplicada a este item." }, "ComissionPercent": { "type": "number", "nullable": true, "description": "Percentual de comissão calculado para este item." }, "ComissionValue": { "type": "number", "nullable": true, "description": "Valor de comissão deste item." }, "ValueOrderItem": { "type": "number", "description": "Valor do item somando, quando aplicável, ICMS-ST/IPI/FCP-ST por fora." } } }, "OrderPayment": { "type": "object", "description": "Parcela / título financeiro vinculado ao pedido (forma de pagamento).", "properties": { "PaymentDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo de pagamento." }, "Category": { "type": "string", "nullable": true, "description": "Categoria do tipo de pagamento (cartão, boleto, dinheiro, etc.)." }, "Installment": { "type": "integer", "description": "Número da parcela." }, "InstallmentTotal": { "type": "integer", "description": "Total de parcelas." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento." }, "Value": { "type": "number", "description": "Valor da parcela." }, "IDAccountPayableReceivable": { "type": "integer", "description": "Identificador da conta a receber." }, "TID": { "type": "string", "nullable": true, "description": "TID retornado pela adquirente / identificador externo." }, "NSU": { "type": "string", "nullable": true, "description": "NSU retornado pela adquirente." }, "IDTypePayment": { "type": "integer", "description": "Identificador do tipo de pagamento." }, "IDConsumer": { "type": "integer", "nullable": true, "description": "Identificador do cliente pagador (quando difere do cliente do pedido)." }, "IDTypeAccountPayableReceivable": { "type": "integer", "nullable": true, "description": "Subtipo financeiro (plano de contas)." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas." }, "IDTypeDocument": { "type": "integer", "nullable": true, "description": "Tipo de documento financeiro." }, "BankSlipBarCode": { "type": "string", "nullable": true, "description": "Linha digitável do boleto, quando emitido." }, "BankSlipUrl": { "type": "string", "nullable": true, "description": "URL do PDF do boleto." }, "StatusBankSlip": { "type": "string", "nullable": true, "description": "Status atual do boleto." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração (adquirente) que originou o pagamento." }, "DaysDue": { "type": "integer", "nullable": true, "description": "Dias para vencimento contados da data do pedido." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Nome da integração de pagamento." }, "Bank": { "type": "string", "nullable": true, "description": "Banco previsto para recebimento." }, "IDBankAccountForecast": { "type": "integer", "nullable": true, "description": "Conta bancária prevista para recebimento." }, "Comments": { "type": "string", "nullable": true, "description": "Observações da parcela." } } }, "OrderPackage": { "type": "object", "description": "Pacote / volume gerado para o pedido (etiqueta de envio).", "properties": { "ShippingDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora do envio do pacote." }, "IDPackage": { "type": "integer", "description": "Identificador do pacote." }, "StatusPackage": { "type": "string", "description": "Status do pacote (criado, em separação, enviado, etc.)." }, "ShippingId": { "type": "string", "nullable": true, "description": "Código de postagem retornado pela transportadora." }, "ShippingPlp": { "type": "string", "nullable": true, "description": "Pré-lista de postagem (PLP)." }, "PackageNumber": { "type": "integer", "description": "Número sequencial do pacote dentro do pedido." }, "IDOrdersCarrierCollectionList": { "type": "integer", "nullable": true, "description": "Romaneio em que o pacote foi incluído." }, "PackageWeight": { "type": "number", "description": "Peso do pacote (kg). Quando não informado, o sistema calcula pelo peso dos itens." }, "PackageHeight": { "type": "number", "description": "Altura do pacote (cm)." }, "PackageLength": { "type": "number", "description": "Comprimento do pacote (cm)." }, "PackageWidth": { "type": "number", "description": "Largura do pacote (cm)." }, "UrlLabel": { "type": "string", "nullable": true, "description": "URL para visualizar a etiqueta do pacote. Null quando o pedido tem mais de 500 pacotes." }, "UrlLabelDownload": { "type": "string", "nullable": true, "description": "URL para baixar a etiqueta. Null quando o pedido tem mais de 500 pacotes." }, "TrackingUrl": { "type": "string", "description": "URL pública de rastreamento." } } }, "OrderEvent": { "type": "object", "description": "Evento registrado no histórico do pedido.", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Quando o evento aconteceu." }, "Comments": { "type": "string", "nullable": true, "description": "Detalhes do evento." }, "Event": { "type": "string", "description": "Descrição do tipo de evento." }, "RecordUserCreated": { "type": "string", "description": "Usuário que registrou o evento (nome - login)." }, "Status": { "type": "string", "description": "Cabeçalho do evento (informativo, alerta, erro)." }, "IDOrderEvents": { "type": "integer", "description": "Identificador do evento." } } }, "OrderFile": { "type": "object", "description": "Arquivo (XML/DANFE) vinculado à nota fiscal principal do pedido.", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Quando o arquivo foi vinculado." }, "IDFile": { "type": "integer", "description": "Identificador do arquivo." }, "IDTypeFile": { "type": "integer", "description": "Tipo do arquivo (XML, DANFE etc.).", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "TypeFile": { "type": "string", "description": "Descrição do tipo de arquivo." }, "UrlFileXml": { "type": "string", "description": "URL para baixar o XML." }, "UrlFileDanfe": { "type": "string", "description": "URL para baixar a DANFE em PDF." }, "UrlFileDanfeSimplificado": { "type": "string", "description": "URL para a DANFE simplificada (impressão por etiqueta)." } } }, "OrderNfeImportAddition": { "type": "object", "description": "Adição vinculada a uma DI (Declaração de Importação).", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de inclusão da adição." }, "NfeImportnAdicao": { "type": "string", "description": "Número da adição na DI." }, "NfeImportnSeqAdic": { "type": "string", "nullable": true, "description": "Número sequencial do item dentro da adição." }, "NfeImportcFabricante": { "type": "string", "nullable": true, "description": "Código do fabricante estrangeiro." }, "NfeImportvDescDI": { "type": "number", "nullable": true, "description": "Valor de desconto da DI." }, "NfeImportnDraw": { "type": "string", "nullable": true, "description": "Número do drawback, quando aplicável." }, "IDOrdersInvoiceImportAdditions": { "type": "integer", "description": "Identificador interno da adição." } } }, "OrderDetail": { "type": "object", "description": "Detalhe completo do pedido — cabeçalho, itens, pagamentos, pacotes, eventos, arquivos e dados fiscais.", "properties": { "IDOrder": { "type": "integer", "description": "Identificador do pedido." }, "Order": { "type": "string", "nullable": true, "description": "Número do pedido (visível ao usuário)." }, "Budget": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, o registro é um orçamento; quando `0`, é um pedido efetivado." }, "Checked": { "type": "integer", "nullable": true, "description": "Marcação de conferência interna." }, "Recordtimestamp": { "type": "string", "format": "date-time", "description": "Quando o pedido foi criado." }, "IDStatusOrder": { "type": "integer", "description": "Status atual do pedido." }, "StatusOrder": { "type": "string", "description": "Descrição do status do pedido." }, "StatusColorCode": { "type": "string", "nullable": true, "description": "Cor exibida na lista para o status." }, "IDOrderType": { "type": "integer", "description": "Tipo de pedido (venda, devolução, transferência, etc.)." }, "TypeOrder": { "type": "string", "description": "Descrição do tipo de pedido." }, "Return": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, o tipo de pedido é uma devolução." }, "ServiceRequest": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, o tipo de pedido é uma ordem de serviço." }, "IDServiceOrder": { "type": "integer", "nullable": true, "description": "Ordem de serviço vinculada, quando o tipo de pedido é serviço." }, "IDCompany": { "type": "integer", "description": "Empresa proprietária do pedido." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." }, "CompanyNameCorporateName": { "type": "string", "description": "Razão social da empresa." }, "CompanyTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia da empresa." }, "CompanyLogoUrl": { "type": "string", "nullable": true, "description": "URL do logo da empresa." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Empresa faturadora (quando o pedido é faturado por uma filial)." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Subdomínio da faturadora." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social da faturadora." }, "CompanyBudgetHeaderImageUrl": { "type": "string", "nullable": true, "description": "Imagem de cabeçalho do orçamento." }, "CompanyInvoiceLogoUrl": { "type": "string", "nullable": true, "description": "Logo da faturadora." }, "CompanyInvoiceCpfCnpj": { "type": "string", "nullable": true, "description": "CNPJ/CPF da faturadora." }, "CompanyInvoiceAddressState": { "type": "string", "nullable": true, "description": "UF da faturadora." }, "CompanyInvoiceCompanyTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia da faturadora." }, "CompanyInvoiceCompanyAddressStreet": { "type": "string", "nullable": true, "description": "Endereço da faturadora — rua." }, "CompanyInvoiceCompanyAddressCity": { "type": "string", "nullable": true, "description": "Endereço da faturadora — cidade." }, "CompanyInvoiceCompanyAddressComplement": { "type": "string", "nullable": true, "description": "Endereço da faturadora — complemento." }, "CompanyInvoiceCompanyAddressNeighborhood": { "type": "string", "nullable": true, "description": "Endereço da faturadora — bairro." }, "CompanyInvoiceCompanyAddressNumber": { "type": "string", "nullable": true, "description": "Endereço da faturadora — número." }, "CompanyInvoiceCompanyAddressPostalCode": { "type": "string", "nullable": true, "description": "Endereço da faturadora — CEP." }, "CompanyInvoiceStateInscription": { "type": "string", "nullable": true, "description": "Inscrição estadual da faturadora no estado de destino." }, "NfeRegimeTributario": { "type": "integer", "nullable": true, "description": "Regime tributário da faturadora (CRT: `1`=Simples Nacional, `2`=Simples Nacional excesso sublimite, `3`=Regime Normal, `4`=MEI)." }, "IDConsumer": { "type": "integer", "nullable": true, "description": "Cliente do pedido." }, "ConsumerType": { "type": "integer", "nullable": true, "description": "Tipo do cliente: `1` Pessoa Física, `2` Pessoa Jurídica, `3` Estrangeiro.", "enum": [ 1, 2, 3 ] }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Nome / razão social do cliente." }, "ConsumerCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ do cliente." }, "ConsumerEmail": { "type": "string", "nullable": true, "description": "Email do cliente." }, "ConsumerTelephone": { "type": "string", "nullable": true, "description": "Telefone do cliente." }, "ConsumerStateInscription": { "type": "string", "nullable": true, "description": "Inscrição estadual do endereço selecionado do cliente." }, "IDAddress": { "type": "integer", "nullable": true, "description": "Endereço de cobrança/principal do cliente." }, "ShippingCity": { "type": "string", "nullable": true, "description": "Endereço de cobrança — cidade." }, "ShippingComplement": { "type": "string", "nullable": true, "description": "Endereço de cobrança — complemento." }, "ShippingNeighborhood": { "type": "string", "nullable": true, "description": "Endereço de cobrança — bairro." }, "ShippingNumber": { "type": "string", "nullable": true, "description": "Endereço de cobrança — número." }, "ShippingPostalCode": { "type": "string", "nullable": true, "description": "Endereço de cobrança — CEP." }, "ShippingState": { "type": "string", "nullable": true, "description": "Endereço de cobrança — UF." }, "ShippingStreet": { "type": "string", "nullable": true, "description": "Endereço de cobrança — rua." }, "ShippingReceiverName": { "type": "string", "description": "Nome do recebedor no endereço de cobrança. Default: `(sem recebedor)`." }, "ShippingIDCountry": { "type": "integer", "nullable": true, "description": "País de cobrança." }, "IDAddressDelivery": { "type": "integer", "nullable": true, "description": "Endereço de entrega (quando diferente do principal)." }, "DeliveryShippingStreet": { "type": "string", "nullable": true, "description": "Endereço de entrega — rua." }, "DeliveryShippingNumber": { "type": "string", "nullable": true, "description": "Endereço de entrega — número." }, "DeliveryShippingComplement": { "type": "string", "nullable": true, "description": "Endereço de entrega — complemento." }, "DeliveryShippingNeighborhood": { "type": "string", "nullable": true, "description": "Endereço de entrega — bairro." }, "DeliveryShippingCity": { "type": "string", "nullable": true, "description": "Endereço de entrega — cidade." }, "DeliveryShippingState": { "type": "string", "nullable": true, "description": "Endereço de entrega — UF." }, "DeliveryShippingPostalCode": { "type": "string", "nullable": true, "description": "Endereço de entrega — CEP." }, "DeliveryShippingReceiverName": { "type": "string", "nullable": true, "description": "Recebedor no endereço de entrega." }, "DeliveryShippingReceiverCpfCnpj": { "type": "string", "nullable": true, "description": "Documento do recebedor." }, "DeliveryShippingReceiverTelephone": { "type": "string", "nullable": true, "description": "Telefone do recebedor." }, "IDCarrier": { "type": "integer", "nullable": true, "description": "Transportadora selecionada." }, "IDCarrierType": { "type": "integer", "nullable": true, "description": "Tipo da transportadora." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social da transportadora." }, "SupplierTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia da transportadora." }, "SupplierLogoUrl": { "type": "string", "nullable": true, "description": "Logo da transportadora." }, "ManualLabel": { "type": "integer", "nullable": true, "description": "Quando `1`, a transportadora exige etiqueta manual." }, "PrintDanfeA4": { "type": "integer", "nullable": true, "description": "Quando `1`, imprime DANFE A4 junto com a etiqueta." }, "ValueShipping": { "type": "number", "nullable": true, "description": "Valor do frete cobrado." }, "NfModFrete": { "type": "integer", "nullable": true, "description": "Modalidade de frete na nota fiscal." }, "NfModFreteDescription": { "type": "string", "nullable": true, "description": "Descrição da modalidade de frete." }, "ShippingEstimateDate": { "type": "string", "format": "date", "nullable": true, "description": "Previsão de entrega ao cliente." }, "ShippingEstimateHandlingLimitDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Prazo de handling pactuado com o marketplace." }, "CarrierDeliveryDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data efetiva de entrega registrada pela transportadora." }, "IDPickingList": { "type": "integer", "nullable": true, "description": "Picking list em que o pedido está incluído." }, "IDOrdersCarrierCollectionList": { "type": "integer", "nullable": true, "description": "Romaneio em que o pedido está incluído." }, "PickingListBasketExternalId": { "type": "string", "nullable": true, "description": "Identificadores externos das cestas do picking (separados por vírgula)." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "nullable": true, "description": "Centro de distribuição que atende o pedido." }, "DistributionCenterName": { "type": "string", "nullable": true, "description": "Nome do centro de distribuição." }, "Weight": { "type": "number", "nullable": true, "description": "Peso total do pedido em kg." }, "ExternalOrderId": { "type": "string", "nullable": true, "description": "Identificador externo do pedido (ex.: número da venda no marketplace)." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração (canal de venda) que originou o pedido." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Nome composto da integração (`tipo - nome`)." }, "SalesChannelName": { "type": "string", "nullable": true, "description": "Nome do tipo de canal de venda." }, "SalesChannelLogoUrl": { "type": "string", "nullable": true, "description": "Logo do canal de venda." }, "ShowShipped": { "type": "integer", "nullable": true, "description": "Quando `1`, o canal aceita atualização de envio." }, "ShowDelivered": { "type": "integer", "nullable": true, "description": "Quando `1`, o canal aceita atualização de entrega." }, "ShowMarketplaceFee": { "type": "integer", "nullable": true, "description": "Quando `1`, o canal traz tarifas do marketplace." }, "ShowFulfillment": { "type": "integer", "nullable": true, "description": "Quando `1`, o canal aceita atualização de fulfillment." }, "HubOrderStatus": { "type": "string", "nullable": true, "description": "Status do pedido no marketplace original." }, "IDSalesman": { "type": "integer", "nullable": true, "description": "Vendedor responsável." }, "Salesman": { "type": "string", "nullable": true, "description": "Vendedor — nome e login concatenados." }, "SalesmanName": { "type": "string", "nullable": true, "description": "Nome do vendedor." }, "IDCompanySalesPolicy": { "type": "integer", "nullable": true, "description": "Política de venda aplicada ao tipo de pedido." }, "CompanySalesPolicy": { "type": "string", "nullable": true, "description": "Descrição da política de venda." }, "IssueNFCe": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, o tipo de pedido emite NFC-e em vez de NF-e." }, "OrderPriority": { "type": "integer", "nullable": true, "description": "Prioridade de atendimento (0 a 10)." }, "OrderComments": { "type": "string", "nullable": true, "description": "Observações livres do pedido." }, "OrderFrom": { "type": "string", "nullable": true, "description": "Lista de origens do pedido (`OrderFrom`) separadas por vírgula." }, "BalanceChange": { "type": "number", "nullable": true, "description": "Saldo / troco a devolver ao cliente." }, "IDTypeOrderReturn": { "type": "integer", "nullable": true, "description": "Tipo de devolução (quando `Return=1`)." }, "TypeOrderReturn": { "type": "string", "nullable": true, "description": "Descrição do tipo de devolução." }, "IDTypeOrderReturnCategory": { "type": "integer", "nullable": true, "description": "Categoria da devolução (motivo).", "enum": [ 1, 2, 3 ] }, "TypeOrderReturnCategory": { "type": "string", "nullable": true, "description": "Descrição da categoria de devolução." }, "IDTypeOrderResend": { "type": "integer", "nullable": true, "description": "Quando o pedido é um reenvio, traz o tipo." }, "TypeOrderResend": { "type": "string", "nullable": true, "description": "Descrição do tipo de reenvio." }, "TypeOrderIDTypeAccountPayableReceivable": { "type": "integer", "nullable": true, "description": "Plano de contas padrão do tipo de pedido." }, "TypeOrderTypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas padrão." }, "OrdersSalesChannelLabelStatus": { "type": "string", "nullable": true, "description": "Status da etiqueta no canal de venda." }, "IDStockKeepingUnitResupplyList": { "type": "string", "nullable": true, "description": "Listas de reposição vinculadas ao pedido (ids separados por vírgula)." }, "IDPurchase": { "type": "integer", "nullable": true, "description": "Identificador da compra interna vinculada (resupply)." }, "Tags": { "type": "array", "items": { "type": "string" }, "description": "Tags aplicadas ao pedido (texto livre)." }, "IDNfCompany": { "type": "integer", "nullable": true, "description": "Identificador da nota fiscal principal." }, "IDStatusInvoice": { "type": "integer", "nullable": true, "description": "Status da nota fiscal principal." }, "StatusInvoice": { "type": "string", "nullable": true, "description": "Descrição do status da nota fiscal." }, "NfeChaveAcesso": { "type": "string", "nullable": true, "description": "Chave de acesso da NF-e principal (44 dígitos)." }, "NfeNumber": { "type": "string", "nullable": true, "description": "Número da NF-e." }, "NfeDhEmi": { "type": "string", "format": "date-time", "nullable": true, "description": "Data/hora de emissão da NF-e." }, "NfeSerie": { "type": "string", "nullable": true, "description": "Série da NF-e." }, "NfeModelo": { "type": "string", "nullable": true, "description": "Modelo do documento fiscal (`55`=NF-e, `65`=NFC-e)." }, "NfModNfDescription": { "type": "string", "nullable": true, "description": "Descrição do modelo do documento fiscal." }, "NfetpEmis": { "type": "integer", "nullable": true, "description": "Tipo de emissão (normal, contingência etc.)." }, "NfetpEmisDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo de emissão." }, "NfProcessCode": { "type": "string", "nullable": true, "description": "Código de processo SEFAZ retornado na última transmissão." }, "NfenRec": { "type": "string", "nullable": true, "description": "Número do recibo SEFAZ." }, "NfenProt": { "type": "string", "nullable": true, "description": "Número do protocolo SEFAZ." }, "NfeNatureOperation": { "type": "string", "nullable": true, "description": "Natureza da operação." }, "NfeDefaultNatureOperation": { "type": "string", "nullable": true, "description": "Natureza da operação inferida pelo CFOP do primeiro item." }, "NfeCfopPriority": { "type": "string", "nullable": true, "description": "CFOP prioritário para os itens." }, "NfeComments": { "type": "string", "nullable": true, "description": "Observações da nota fiscal." }, "NfeAccessoryExpenses": { "type": "number", "nullable": true, "description": "Despesas acessórias (outras despesas) da NF." }, "NfeFactorPercent": { "type": "number", "nullable": true, "description": "Fator de redução fiscal (0 a 1) aplicado na emissão." }, "NfeManualTax": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Quando `1`, os impostos são fixados manualmente (não recalculam)." }, "NfePackages": { "type": "integer", "nullable": true, "description": "Quantidade de volumes informada na NF." }, "NfeNoPayment": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Quando `1`, o pedido não gera contas a receber (cortesia/sem pagamento)." }, "NFeFin": { "type": "integer", "nullable": true, "description": "Indicador de finalidade da NF-e (1=normal, 2=complementar, 3=ajuste, 4=devolução)." }, "FinNfeDescription": { "type": "string", "nullable": true, "description": "Descrição da finalidade da NF-e." }, "NFeType": { "type": "integer", "nullable": true, "description": "Tipo da NF-e (0=entrada, 1=saída)." }, "NfTpNfDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo da NF-e." }, "NfeindFinal": { "type": "integer", "nullable": true, "description": "Indicador de consumidor final (0=não, 1=sim)." }, "IndFinalDescription": { "type": "string", "nullable": true, "description": "Descrição do indicador de consumidor final." }, "NfeExportaUFSaidaPais": { "type": "string", "nullable": true, "description": "UF de saída do país (operações de exportação)." }, "NfeExportaxLocExporta": { "type": "string", "nullable": true, "description": "Local de exportação (cidade)." }, "NfeExportaxLocDespacho": { "type": "string", "nullable": true, "description": "Local de despacho de exportação." }, "NfeChaveAcessoDevolucao": { "type": "string", "nullable": true, "description": "Chaves de NF-e referenciadas (para devolução / complemento), separadas por vírgula." }, "ValueProduct": { "type": "number", "description": "Soma de `PriceSellingTotal` dos itens não bonificados." }, "ValueOrder": { "type": "string", "description": "Total do pedido (produtos + frete + despesas acessórias), formatado com duas casas." }, "ValueComission": { "type": "number", "description": "Total de comissões calculadas para o vendedor." }, "NfeValueCofins": { "type": "number", "nullable": true, "description": "Total de COFINS do pedido." }, "NfeCofinsBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo total de COFINS." }, "NfeValueFcp": { "type": "number", "description": "Valor de FCP (reservado, sempre 0)." }, "NfeValueFcpStRet": { "type": "number", "description": "Valor de FCP-ST retido (reservado, sempre 0)." }, "NfeValueFcpUfDest": { "type": "number", "nullable": true, "description": "FCP destinado à UF de destino." }, "NfeValueIcms": { "type": "number", "nullable": true, "description": "Total de ICMS." }, "NfeValueIcmsBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo total de ICMS." }, "NfeValueIcmsUfDest": { "type": "number", "nullable": true, "description": "ICMS devido à UF de destino (DIFAL)." }, "NfeValueIcmsUfRemet": { "type": "number", "nullable": true, "description": "ICMS devido à UF do remetente (DIFAL)." }, "NfeValuePis": { "type": "number", "nullable": true, "description": "Total de PIS." }, "NfePisBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo total de PIS." }, "NfeValueIcmsST": { "type": "number", "nullable": true, "description": "Total de ICMS-ST." }, "NfeValueIcmsSTBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo total de ICMS-ST." }, "NfeValueIpi": { "type": "number", "nullable": true, "description": "Total de IPI." }, "NfeValueII": { "type": "number", "nullable": true, "description": "Total de Imposto de Importação." }, "NfeValueFcpSt": { "type": "number", "nullable": true, "description": "Total de FCP-ST." }, "NfeImportnDI": { "type": "string", "nullable": true, "description": "Número da DI / DSI." }, "NfeImportdDI": { "type": "string", "format": "date", "nullable": true, "description": "Data do registro da DI." }, "NfeImportxLocDesemb": { "type": "string", "nullable": true, "description": "Local do desembaraço aduaneiro." }, "NfeImportUFDesemb": { "type": "string", "nullable": true, "description": "UF do desembaraço aduaneiro." }, "NfeImportdDesemb": { "type": "string", "format": "date", "nullable": true, "description": "Data do desembaraço." }, "NfeImporttpViaTransp": { "type": "integer", "nullable": true, "description": "Via de transporte da importação." }, "NftDITpViaTranspDescription": { "type": "string", "nullable": true, "description": "Descrição da via de transporte." }, "NfeImportvAFRMM": { "type": "number", "nullable": true, "description": "Valor de AFRMM." }, "NfeImporttpIntermedio": { "type": "integer", "nullable": true, "description": "Tipo de intermédio da operação de importação." }, "NfDITpIntermedioDescription": { "type": "string", "nullable": true, "description": "Descrição do tipo de intermédio." }, "NfeImportCNPJ": { "type": "string", "nullable": true, "description": "CNPJ do adquirente / encomendante." }, "NfeImportUFTerceiro": { "type": "string", "nullable": true, "description": "UF do adquirente / encomendante." }, "NfeImportcExportador": { "type": "string", "nullable": true, "description": "Código do exportador." }, "NfeImportvDespAdu": { "type": "number", "nullable": true, "description": "Valor das despesas aduaneiras." }, "NfeImportIOF": { "type": "number", "nullable": true, "description": "Valor do IOF da importação." }, "Items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" }, "description": "Itens do pedido." }, "Payments": { "type": "array", "items": { "$ref": "#/components/schemas/OrderPayment" }, "description": "Parcelas / pagamentos do pedido." }, "Packages": { "type": "array", "items": { "$ref": "#/components/schemas/OrderPackage" }, "description": "Pacotes gerados para envio." }, "Events": { "type": "array", "items": { "$ref": "#/components/schemas/OrderEvent" }, "description": "Histórico de eventos do pedido (últimos 500)." }, "Files": { "type": "array", "items": { "$ref": "#/components/schemas/OrderFile" }, "description": "Arquivos da nota fiscal principal." }, "NfeImportAdditions": { "type": "array", "items": { "$ref": "#/components/schemas/OrderNfeImportAddition" }, "description": "Adições vinculadas à DI." }, "ConsumerIDCompanySalesPolicy": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador da política comercial padrão do cliente do pedido." } } }, "OrderEconomics": { "type": "object", "description": "Indicadores econômicos do pedido — receitas, custos, impostos e margem.", "properties": { "EconomicsOrderValue": { "type": "number", "nullable": true, "description": "Valor total do pedido (produtos + frete + despesas)." }, "EconomicsProductValue": { "type": "number", "nullable": true, "description": "Valor total dos produtos." }, "EconomicsProductValuePercent": { "type": "number", "nullable": true, "description": "Participação dos produtos no total." }, "EconomicsShippingValue": { "type": "number", "nullable": true, "description": "Valor do frete cobrado." }, "EconomicsShippingValuePercent": { "type": "number", "nullable": true, "description": "Participação do frete no total." }, "EconomicsAccessoryExpenses": { "type": "number", "nullable": true, "description": "Despesas acessórias." }, "EconomicsAccessoryExpensesPercent": { "type": "number", "nullable": true, "description": "Participação das despesas acessórias no total." }, "EconomicsMarketplaceFee": { "type": "number", "nullable": true, "description": "Tarifa do marketplace (negativa)." }, "EconomicsMarketplaceFeePercent": { "type": "number", "nullable": true, "description": "Participação da tarifa do marketplace." }, "EconomicsMarketplaceShippingFee": { "type": "number", "nullable": true, "description": "Tarifa de frete do marketplace (negativa)." }, "EconomicsMarketplaceShippingFeePercent": { "type": "number", "nullable": true, "description": "Participação da tarifa de frete do marketplace." }, "EconomicsMarketplaceCouponValue": { "type": "number", "nullable": true, "description": "Cupons aplicados pelo marketplace." }, "EconomicsMarketplaceCouponValuePercent": { "type": "number", "nullable": true, "description": "Participação dos cupons do marketplace." }, "EconomicsTransferValue": { "type": "number", "nullable": true, "description": "Valor que será transferido pela operação." }, "EconomicsTransferValuePercent": { "type": "number", "nullable": true, "description": "Participação do repasse no total." }, "EconomicsSIMPLESorIRCSLLValue": { "type": "number", "nullable": true, "description": "Estimativa de Simples ou IR/CSLL para o pedido." }, "EconomicsSIMPLESorIRCSLLValuePercent": { "type": "number", "nullable": true, "description": "Participação do imposto sobre o resultado." }, "EconomicsPisCofinsValue": { "type": "number", "nullable": true, "description": "Total de PIS/COFINS." }, "EconomicsPisCofinsValuePercent": { "type": "number", "nullable": true, "description": "Participação de PIS/COFINS." }, "EconomicsIcmsValue": { "type": "number", "nullable": true, "description": "Total de ICMS (próprio + DIFAL)." }, "EconomicsIcmsValuePercent": { "type": "number", "nullable": true, "description": "Participação de ICMS." }, "EconomicsIpiValue": { "type": "number", "nullable": true, "description": "Total de IPI." }, "EconomicsIpiValuePercent": { "type": "number", "nullable": true, "description": "Participação de IPI." }, "EconomicsNetRevenue": { "type": "number", "nullable": true, "description": "Receita líquida (após impostos e tarifas)." }, "EconomicsNetRevenuePercent": { "type": "number", "nullable": true, "description": "Participação da receita líquida sobre o total." }, "EconomicsProductCost": { "type": "number", "nullable": true, "description": "Custo dos produtos (negativo)." }, "EconomicsProductCostPercent": { "type": "number", "nullable": true, "description": "Participação do custo dos produtos." }, "EconomicsMarkUp": { "type": "number", "nullable": true, "description": "Mark-up (receita produto / custo produto)." }, "EconomicsGrossMargin": { "type": "number", "nullable": true, "description": "Margem bruta (receita líquida - custos diretos dos produtos)." }, "EconomicsGrossMarginPercent": { "type": "number", "nullable": true, "description": "Margem bruta percentual." }, "EconomicsPackagingCost": { "type": "number", "nullable": true, "description": "Custo das embalagens (itens marcados como `Package`)." }, "EconomicsPackagingCostPercent": { "type": "number", "nullable": true, "description": "Participação do custo de embalagens." }, "EconomicsShippingCost": { "type": "number", "nullable": true, "description": "Custo do frete pago à transportadora (CT-e)." }, "EconomicsShippingCostPercent": { "type": "number", "nullable": true, "description": "Participação do custo de frete." }, "EconomicsAdditionalCost": { "type": "number", "nullable": true, "description": "Outros custos lançados como contas a pagar no pedido." }, "EconomicsAdditionalCostPercent": { "type": "number", "nullable": true, "description": "Participação dos custos adicionais." }, "EconomicsContributionMargin": { "type": "number", "nullable": true, "description": "Margem de contribuição (após custos diretos, embalagens e frete real)." }, "EconomicsContributionMarginPercent": { "type": "number", "nullable": true, "description": "Margem de contribuição percentual." } } }, "OrderItemFiscal": { "type": "object", "description": "Item do pedido enriquecido com dados fiscais (CFOP, CST, classificação tributária) para emissão de NF.", "properties": { "IDSkuMovement": { "type": "integer", "description": "Identificador da movimentação." }, "IDSku": { "type": "integer", "description": "Identificador do produto." }, "IDOrder": { "type": "integer", "description": "Pedido ao qual o item pertence." }, "Quantity": { "type": "number", "description": "Quantidade vendida." }, "PriceSellingTotal": { "type": "number", "description": "Valor total do item." }, "PriceSelling": { "type": "number", "description": "Preço unitário (`PriceSellingTotal / Quantity`)." }, "ValueDiscount": { "type": "number", "nullable": true, "description": "Desconto total do item (unitário x quantidade)." }, "SkuName": { "type": "string", "description": "Nome do produto." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras do produto." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código interno (SKU) do produto." }, "SkuNCM": { "type": "string", "nullable": true, "description": "NCM do produto." }, "NfeCFOP": { "type": "string", "nullable": true, "description": "CFOP aplicado ao item." }, "CfopDescription": { "type": "string", "nullable": true, "description": "Descrição do CFOP." }, "IndexInvoice": { "type": "integer", "description": "Posição do item dentro da NF (1-based)." }, "NfeIbsCbsCST": { "type": "string", "nullable": true, "description": "CST IBS/CBS." }, "IDNfCstIbsCbs": { "type": "integer", "nullable": true, "description": "Identificador da classificação tributária IBS/CBS." }, "NfCstIbsCbsDescription": { "type": "string", "nullable": true, "description": "Descrição da classificação IBS/CBS (`cClassTrib - CST - nome`)." }, "NfeCofinsCst": { "type": "string", "nullable": true, "description": "CST de COFINS." }, "NfCstCofinsDescription": { "type": "string", "nullable": true, "description": "Descrição do CST de COFINS." }, "NfePisCst": { "type": "string", "nullable": true, "description": "CST de PIS." }, "NfCstPisDescription": { "type": "string", "nullable": true, "description": "Descrição do CST de PIS." }, "NfeIpiCst": { "type": "string", "nullable": true, "description": "CST de IPI." }, "NfCstIpiDescription": { "type": "string", "nullable": true, "description": "Descrição do CST de IPI." }, "NfeIcmsCst": { "type": "string", "nullable": true, "description": "CST de ICMS." }, "NfCstIcmsDescription": { "type": "string", "nullable": true, "description": "Descrição do CST de ICMS." }, "SkuCst": { "type": "string", "nullable": true, "description": "Origem da mercadoria (CST de origem)." }, "ICMSOrigDescription": { "type": "string", "nullable": true, "description": "Descrição da origem da mercadoria." }, "NfeIcmsModBC": { "type": "string", "nullable": true, "description": "Modalidade da base de cálculo do ICMS." }, "ICMSmodBCDescription": { "type": "string", "nullable": true, "description": "Descrição da modalidade de BC ICMS." }, "NfeIcmsSTModBaseCal": { "type": "string", "nullable": true, "description": "Modalidade da base de cálculo do ICMS-ST." }, "ICMSmodBCSTDescription": { "type": "string", "nullable": true, "description": "Descrição da modalidade de BC ICMS-ST." }, "NfeIpicEnq": { "type": "string", "nullable": true, "description": "Código de enquadramento do IPI." }, "IPIcEnqDescription": { "type": "string", "nullable": true, "description": "Descrição do enquadramento de IPI." } }, "additionalProperties": true }, "OrderUpdateBody": { "type": "object", "description": "Corpo de atualização parcial do pedido. Apenas campos enviados são alterados — campos omitidos permanecem como estão. Em `?ValueAdjust=1`, o corpo aceita apenas `ValueAddOrDiscount` / `PercentAddOrDiscount` / `IncludeShipping`.", "properties": { "Order": { "type": "string", "description": "Número do pedido (texto livre exibido ao usuário)." }, "Budget": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` = orçamento; `0` = pedido efetivado." }, "Checked": { "type": "integer", "description": "Marcação de conferência." }, "OrderComments": { "type": "string", "nullable": true, "description": "Observações livres do pedido." }, "OrderPriority": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Prioridade de atendimento (0 a 10)." }, "IDOrderType": { "type": "integer", "description": "Tipo de pedido (precisa existir na empresa)." }, "IDConsumer": { "type": "integer", "nullable": true, "description": "Cliente do pedido. Quando alterado, os dados de identificação (CPF/CNPJ, email, telefone, nome) são copiados do cadastro do cliente para o pedido." }, "IDAddress": { "type": "integer", "nullable": true, "description": "Endereço de cobrança / endereço principal do cliente. Quando alterado, os campos `Shipping*` do pedido são reescritos com o endereço selecionado." }, "IDAddressDelivery": { "type": "integer", "nullable": true, "description": "Endereço de entrega (quando diferente do endereço principal). Quando alterado, os campos `DeliveryShipping*` são reescritos." }, "IDCarrier": { "type": "integer", "nullable": true, "description": "Transportadora. Não pode ser alterado se o pedido (ou um de seus pacotes) já estiver em romaneio; nesse caso retorne ao romaneio antes." }, "IDOrdersCarrierCollectionList": { "type": "integer", "nullable": true, "description": "Romaneio em que o pedido é colocado. Precisa pertencer ao mesmo centro de distribuição do pedido e estar com status que permita inclusão." }, "IDPickingList": { "type": "integer", "nullable": true, "description": "Picking list em que o pedido é colocado. Precisa estar com status que permita inclusão." }, "IDSalesman": { "type": "integer", "nullable": true, "description": "Vendedor responsável (precisa ser usuário vinculado à empresa)." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Faturador (filial que emite a NF)." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Canal de venda (integração) ao qual o pedido pertence." }, "IDStockKeepingUnitDistributionCenter": { "type": "integer", "nullable": true, "description": "Centro de distribuição que atende o pedido. Não pode divergir do CD dos armazéns dos itens já lançados." }, "ValueShipping": { "type": "number", "nullable": true, "description": "Valor do frete cobrado." }, "NfeAccessoryExpenses": { "type": "number", "nullable": true, "description": "Despesas acessórias da nota fiscal." }, "ShippingEstimateDate": { "type": "string", "format": "date", "nullable": true, "description": "Previsão de entrega ao cliente." }, "NfeCfopPriority": { "type": "string", "nullable": true, "description": "CFOP prioritário a aplicar nos itens." }, "NfeComments": { "type": "string", "nullable": true, "description": "Observações da nota fiscal." }, "NFeFin": { "type": "integer", "description": "Finalidade da NF-e (1=normal, 2=complementar, 3=ajuste, 4=devolução)." }, "NFeType": { "type": "integer", "description": "Tipo da NF-e (0=entrada, 1=saída)." }, "NfeindFinal": { "type": "integer", "enum": [ 0, 1 ], "description": "Indicador de consumidor final." }, "NfModFrete": { "type": "integer", "description": "Modalidade de frete. Quando enviado vazio/null, o sistema grava `9` (sem frete)." }, "NfeNatureOperation": { "type": "string", "description": "Natureza da operação." }, "NfeFactorPercent": { "type": "number", "minimum": 0, "maximum": 1, "description": "Fator de redução fiscal (entre 0 e 1)." }, "NfeManualTax": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, fixa os impostos atuais e impede recálculo automático." }, "BalanceChange": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "`1` marca os itens como troca/saldo (não disparam recálculo de custo na troca de armazém); `0` trata como venda normal. Quando muda de `0` → `1` com nota ainda não emitida, dispara recálculo de custo de todos os itens." }, "NfePackages": { "type": "integer", "description": "Quantidade de volumes a declarar na NF." }, "NfeNoPayment": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, exclui todas as contas a receber do pedido (cortesia)." }, "ExternalOrderId": { "type": "string", "nullable": true, "description": "Identificador externo (número do pedido no marketplace, ERP, etc.)." }, "NfeExportaUFSaidaPais": { "type": "string", "nullable": true, "description": "UF de saída do país (exportações)." }, "NfeExportaxLocExporta": { "type": "string", "nullable": true, "description": "Local de exportação (cidade)." }, "NfeExportaxLocDespacho": { "type": "string", "nullable": true, "description": "Local de despacho." }, "Tags": { "type": "array", "items": { "type": "string" }, "description": "Lista de tags a sincronizar. Tags ausentes da lista são removidas; tags novas são inseridas." }, "OrderFrom": { "type": "string", "description": "Origem do pedido (texto livre, separado por vírgula quando múltiplo)." }, "NfeChaveAcessoDevolucao": { "type": "string", "nullable": true, "description": "Chaves de NF-e referenciadas (44 dígitos cada, separadas por vírgula). Reescreve a lista atual quando a nota ainda não foi emitida." }, "NfeImportnDI": { "type": "string", "nullable": true, "description": "Número da DI/DSI." }, "NfeImportdDI": { "type": "string", "format": "date", "nullable": true, "description": "Data do registro da DI." }, "NfeImportxLocDesemb": { "type": "string", "nullable": true, "description": "Local do desembaraço." }, "NfeImportUFDesemb": { "type": "string", "nullable": true, "description": "UF do desembaraço." }, "NfeImportdDesemb": { "type": "string", "format": "date", "nullable": true, "description": "Data do desembaraço." }, "NfeImporttpViaTransp": { "type": "integer", "nullable": true, "description": "Via de transporte da importação." }, "NfeImportvAFRMM": { "type": "number", "nullable": true, "description": "Valor de AFRMM." }, "NfeImporttpIntermedio": { "type": "integer", "nullable": true, "description": "Tipo de intermédio." }, "NfeImportCNPJ": { "type": "string", "nullable": true, "description": "CNPJ do adquirente/encomendante." }, "NfeImportUFTerceiro": { "type": "string", "nullable": true, "description": "UF do adquirente/encomendante." }, "NfeImportcExportador": { "type": "string", "nullable": true, "description": "Código do exportador." }, "NfeImportvDespAdu": { "type": "number", "nullable": true, "description": "Valor de despesas aduaneiras." }, "NfeImportIOF": { "type": "number", "nullable": true, "description": "Valor do IOF." }, "NfeImportAdditions": { "type": "array", "items": { "type": "object", "properties": { "NfeImportnAdicao": { "type": "string", "description": "Número da adição." }, "NfeImportnSeqAdic": { "type": "string", "nullable": true, "description": "Número sequencial dentro da adição." }, "NfeImportcFabricante": { "type": "string", "nullable": true, "description": "Código do fabricante estrangeiro." }, "NfeImportvDescDI": { "type": "number", "nullable": true, "description": "Valor de desconto da DI." }, "NfeImportnDraw": { "type": "string", "nullable": true, "description": "Número do drawback." } } }, "description": "Adições da DI (substituem as atuais quando enviadas)." }, "ValueAddOrDiscount": { "type": "number", "description": "Valor absoluto a somar (positivo) ou descontar (negativo) ao total do pedido. Usado quando `?ValueAdjust=1`." }, "PercentAddOrDiscount": { "type": "number", "description": "Percentual a aplicar (ex.: `-0.1` para desconto de 10%). Usado quando `?ValueAdjust=1`." }, "IncludeShipping": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, inclui frete e despesas acessórias no rateio do desconto/acréscimo. Usado quando `?ValueAdjust=1`." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Quando enviado, dispara o fluxo de troca de armazém de todos os itens (independe dos outros campos). O novo armazém precisa pertencer ao mesmo centro de distribuição do pedido e o pedido não pode ter movimentação de saída." }, "ShippingEstimateHandlingLimitDate": { "type": "string", "format": "date-time", "description": "Data/hora limite estimada de expedição (prazo de manuseio). Usada principalmente em pedidos integrados de canais de venda." } } }, "OrderSkuPostBody": { "type": "object", "description": "Item a adicionar ao pedido. Os campos mínimos exigidos pelo processo fiscal são `IDSku` e `Quantity` — os demais aceitam valores padrão e/ou são calculados pelo motor fiscal a partir do produto e da política de vendas.", "required": [ "IDSku", "Quantity" ], "properties": { "IDSku": { "type": "integer", "description": "Identificador do produto." }, "Quantity": { "type": "number", "description": "Quantidade. Sinal precisa ser coerente com os demais itens do pedido — itens positivos não podem coexistir com itens negativos no mesmo pedido." }, "PriceSelling": { "type": "number", "description": "Preço unitário aplicado. Quando enviado `0` e o tipo de pedido bloqueia produtos com valor zero, o item é rejeitado (salvo quando a parametrização `GratificationZeroValue` está ligada e existe preço de tabela > 0 na política de vendas vigente)." }, "PriceList": { "type": "number", "description": "Preço de tabela (antes do desconto)." }, "PriceSellingTotal": { "type": "number", "description": "Total do item. Quando omitido, é calculado por `PriceSelling * Quantity`." }, "ValueDiscount": { "type": "number", "nullable": true, "description": "Desconto unitário aplicado." }, "IDCompanySalesPolicy": { "type": "integer", "description": "Política de vendas usada para validar preço/desconto." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém de origem do item. Precisa pertencer ao centro de distribuição do pedido." }, "PackageNumber": { "type": "integer", "nullable": true, "description": "Número do pacote a alocar (criado depois via `/orders/{idorder}/packages`)." }, "Gratification": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, o item é brinde/bonificação e não soma no total do pedido." }, "NfeNItemPed": { "type": "string", "nullable": true, "description": "Referência do item no pedido externo (integrações fiscais)." }, "Comments": { "type": "string", "nullable": true, "description": "Observações internas do item." }, "CommentsInvoice": { "type": "string", "nullable": true, "description": "Observações do item para a NF-e." }, "IDSkuKit": { "type": "integer", "nullable": true, "description": "Quando o item é componente de um kit explícito, identificador do kit pai." }, "QuantityKit": { "type": "number", "nullable": true, "description": "Quantidade do kit pai." }, "IDBatch": { "type": "integer", "nullable": true, "description": "Lote do produto a usar na saída." } }, "additionalProperties": true }, "OrderSkuPutBody": { "type": "object", "description": "Atualização de um item já existente. Todos os campos são opcionais — campos omitidos não são alterados. Quantidade e preço passam pelo motor fiscal e disparam recálculo da nota; trocar `IDStockKeepingUnitWarehouse` valida que o armazém pertence ao mesmo CD do pedido.", "properties": { "IDSku": { "type": "integer", "description": "Quando enviado, valida que o produto existe na empresa." }, "Quantity": { "type": "number", "description": "Nova quantidade. Sinal precisa ser coerente com os demais itens do pedido." }, "PriceList": { "type": "number", "description": "Preço de tabela (antes do desconto)." }, "PriceSelling": { "type": "number", "description": "Novo preço unitário. Quando o desconto resultante excede o limite do vendedor, a operação é recusada." }, "PriceSellingTotal": { "type": "number", "description": "Total do item. Quando omitido, recalculado por `PriceSelling * Quantity`." }, "ValueDiscount": { "type": "number", "nullable": true, "description": "Desconto unitário aplicado." }, "ValueShipping": { "type": "number", "nullable": true, "description": "Quando enviado, atualiza o frete do pedido junto com o item." }, "NfeAccessoryExpenses": { "type": "number", "nullable": true, "description": "Quando enviado, atualiza despesas acessórias do pedido." }, "QuantityNonconformity": { "type": "number", "nullable": true, "description": "Quantidade não conforme apontada no atendimento." }, "IDTypeFulfillmentNonconformity": { "type": "integer", "nullable": true, "description": "Tipo de não conformidade.", "enum": [ 1, 2, 4, 5, 6 ] }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Novo armazém do item. Precisa pertencer ao mesmo centro de distribuição do pedido." }, "Gratification": { "type": "integer", "enum": [ 0, 1 ], "description": "Item de bonificação: `0`=não, `1`=sim. Itens marcados como bonificação não compõem o valor cobrado e seguem CFOP/CST específicos." }, "NfeNItemPed": { "type": "string", "nullable": true, "description": "Número do item no pedido de compra do cliente, replicado na NF-e (tag `nItemPed`)." }, "Comments": { "type": "string", "nullable": true, "description": "Observações internas do item." }, "CommentsInvoice": { "type": "string", "nullable": true, "description": "Observações do item que vão impressas na nota fiscal (tag `infAdProd`)." }, "NfeCFOP": { "type": "string", "nullable": true, "description": "CFOP aplicado ao item (4 dígitos). Quando omitido, recalculado pelo motor fiscal a partir do par origem/destino e do tipo de operação." }, "NfeCofinsAliquot": { "type": "number", "nullable": true, "description": "Alíquota de COFINS (%) — campo `pCOFINS` da NF-e." }, "NfeCofinsBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo do COFINS — campo `vBC` do grupo COFINS." }, "NfeCofinsCst": { "type": "string", "nullable": true, "description": "CST do COFINS (ver `support data/NfCstCofins.csv`)." }, "NfeCofinsValue": { "type": "number", "nullable": true, "description": "Valor de COFINS — campo `vCOFINS`." }, "NfeCofinsAliquotProd": { "type": "number", "nullable": true, "description": "Alíquota de COFINS por unidade tributável — campo `vAliqProd` do COFINS." }, "NfeCofinsQtyProd": { "type": "number", "nullable": true, "description": "Quantidade tributável de COFINS — campo `qBCProd`." }, "NfePisAliquot": { "type": "number", "nullable": true, "description": "Alíquota de PIS (%) — campo `pPIS`." }, "NfePisBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo do PIS — campo `vBC` do grupo PIS." }, "NfePisCst": { "type": "string", "nullable": true, "description": "CST do PIS (ver `support data/NfCstPis.csv`)." }, "NfePisValue": { "type": "number", "nullable": true, "description": "Valor de PIS — campo `vPIS`." }, "NfePisAliquotProd": { "type": "number", "nullable": true, "description": "Alíquota de PIS por unidade tributável — campo `vAliqProd` do PIS." }, "NfePisQtyProd": { "type": "number", "nullable": true, "description": "Quantidade tributável de PIS — campo `qBCProd`." }, "NfeIpiAliquot": { "type": "number", "nullable": true, "description": "Alíquota de IPI (%) — campo `pIPI`." }, "NfeIpiBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo do IPI — campo `vBC` do grupo IPI." }, "NfeIpiCst": { "type": "string", "nullable": true, "description": "CST do IPI (ver `support data/NfCstIpi.csv`)." }, "NfeIpiValue": { "type": "number", "nullable": true, "description": "Valor de IPI — campo `vIPI`." }, "NfeIpicEnq": { "type": "string", "nullable": true, "description": "Código de enquadramento do IPI — campo `cEnq` (ver `support data/NfIpiCEnq.csv`)." }, "NfeIpiQtyProd": { "type": "number", "nullable": true, "description": "Quantidade tributável do IPI — campo `qUnid`." }, "NfeIpiValueProd": { "type": "number", "nullable": true, "description": "Valor por unidade tributável do IPI — campo `vUnid`." }, "NfeIIValue": { "type": "number", "nullable": true, "description": "Valor de Imposto de Importação — campo `vII`." }, "NfeIIBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo do Imposto de Importação — campo `vBC` do grupo II." }, "NfeImportnAdicao": { "type": "string", "nullable": true, "description": "Número da adição (DI) — campo `nAdicao` da declaração de importação." }, "NfeIIDespAdu": { "type": "number", "nullable": true, "description": "Valor das despesas aduaneiras — campo `vDespAdu`." }, "NfeIIvAFRMM": { "type": "number", "nullable": true, "description": "Valor do AFRMM (Adicional ao Frete para Renovação da Marinha Mercante) — campo `vAFRMM`." }, "NfeIIIOF": { "type": "number", "nullable": true, "description": "Valor do IOF na importação — campo `vIOF`." }, "NfeIcmsFcpBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo do FCP (Fundo de Combate à Pobreza) na operação própria — campo `vBCFCP`." }, "NfeIcmsFcpAliquot": { "type": "number", "nullable": true, "description": "Alíquota do FCP (%) — campo `pFCP`." }, "NfeIcmsFcpValue": { "type": "number", "nullable": true, "description": "Valor do FCP — campo `vFCP`." }, "NfeFcpSTBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo do FCP retido por substituição tributária — campo `vBCFCPST`." }, "NfeFcpSTAliquot": { "type": "number", "nullable": true, "description": "Alíquota do FCP-ST (%) — campo `pFCPST`." }, "NfeFcpSTValue": { "type": "number", "nullable": true, "description": "Valor do FCP-ST — campo `vFCPST`." }, "NfeIcmsProprioAliquot": { "type": "number", "nullable": true, "description": "Alíquota efetiva do ICMS na operação própria (%) — campo `pICMS`." }, "NfeIcmsBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo do ICMS — campo `vBC`." }, "NfeIcmsCst": { "type": "string", "nullable": true, "description": "CST/CSOSN do ICMS (ver `support data/NfCstIcms.csv`)." }, "NfeIcmsModBC": { "type": "string", "nullable": true, "description": "Modalidade de determinação da base de cálculo do ICMS — campo `modBC` (ver `support data/NfModBc.csv`)." }, "NfeIcmsPRedBC": { "type": "number", "nullable": true, "description": "Percentual de redução da base de cálculo do ICMS — campo `pRedBC`." }, "NfeIcmsValue": { "type": "number", "nullable": true, "description": "Valor do ICMS — campo `vICMS`." }, "ICMScBenef": { "type": "string", "nullable": true, "description": "Código de benefício fiscal." }, "NfeFcpUfDestAliquot": { "type": "number", "nullable": true, "description": "Alíquota do FCP devido à UF de destino em operação interestadual a consumidor final — campo `pFCPUFDest`." }, "NfeIcmsInterstateAliquot": { "type": "number", "nullable": true, "description": "Alíquota interestadual aplicada em operação a consumidor final em outra UF — campo `pICMSInter`." }, "NfeIcmsUfDestAliquot": { "type": "number", "nullable": true, "description": "Alíquota interna da UF de destino em operação interestadual a consumidor final — campo `pICMSUFDest`." }, "NfeIcmsFcpUfDestBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo do FCP na UF de destino — campo `vBCFCPUFDest`." }, "NfeIcmsUfDestBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo do ICMS para a UF de destino — campo `vBCUFDest`." }, "NfeFcpUfDestValue": { "type": "number", "nullable": true, "description": "Valor do FCP devido à UF de destino — campo `vFCPUFDest`." }, "NfeIcmsUfDestValue": { "type": "number", "nullable": true, "description": "Valor do ICMS devido à UF de destino — campo `vICMSUFDest`." }, "NfeIcmsSTRetpST": { "type": "number", "nullable": true, "description": "Alíquota suportada pelo consumidor final do ICMS-ST retido anteriormente — campo `pST`." }, "NfeIcmsSTRetBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo do ICMS-ST retido anteriormente — campo `vBCSTRet`." }, "NfeIcmsSTRetSubstitutoValue": { "type": "number", "nullable": true, "description": "Valor do ICMS próprio do substituto — campo `vICMSSubstituto`." }, "NfeIcmsSTRetValue": { "type": "number", "nullable": true, "description": "Valor do ICMS-ST retido anteriormente — campo `vICMSSTRet`." }, "ICMSvBCFCPSTRet": { "type": "number", "nullable": true, "description": "Base de cálculo do FCP-ST retido anteriormente — campo `vBCFCPSTRet`." }, "ICMSpFCPSTRet": { "type": "number", "nullable": true, "description": "Alíquota do FCP-ST retido anteriormente — campo `pFCPSTRet`." }, "ICMSvFCPSTRet": { "type": "number", "nullable": true, "description": "Valor do FCP-ST retido anteriormente — campo `vFCPSTRet`." }, "NfeIcmsCredSnAliquot": { "type": "number", "nullable": true, "description": "Alíquota aplicável de cálculo do crédito de ICMS no Simples Nacional — campo `pCredSN`." }, "NfeIcmsCredSnValue": { "type": "number", "nullable": true, "description": "Valor do crédito de ICMS aproveitável no Simples Nacional — campo `vCredICMSSN`." }, "NfeIcmsSTAliquot": { "type": "number", "nullable": true, "description": "Alíquota do ICMS-ST (%) — campo `pICMSST`." }, "NfeIcmsSTBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo do ICMS-ST — campo `vBCST`." }, "NfeIcmsSTMVA": { "type": "number", "nullable": true, "description": "Margem de Valor Agregado do ICMS-ST (%) — campo `pMVAST`." }, "NfeIcmsSTModBaseCal": { "type": "string", "nullable": true, "description": "Modalidade de determinação da base de cálculo do ICMS-ST — campo `modBCST` (ver `support data/NfModBcST.csv`)." }, "NfeIcmsPRedBCST": { "type": "number", "nullable": true, "description": "Percentual de redução da base de cálculo do ICMS-ST — campo `pRedBCST`." }, "NfeIcmsSTValue": { "type": "number", "nullable": true, "description": "Valor do ICMS-ST — campo `vICMSST`." }, "NfeIbsCbsCST": { "type": "string", "nullable": true, "description": "CST conjunto de IBS/CBS da Reforma Tributária (ver `support data/NfCstIbsCbs.csv`)." }, "NfeIbsCbsBaseCal": { "type": "number", "nullable": true, "description": "Base de cálculo de IBS/CBS — campo `vBC` do grupo IBS/CBS." }, "NfeIbsAliquot": { "type": "number", "nullable": true, "description": "Alíquota do IBS (%) — campo `pIBS`." }, "NfeIbspRedAliquot": { "type": "number", "nullable": true, "description": "Percentual de redução da alíquota do IBS — campo `pRedAliq`." }, "NfeIbsValue": { "type": "number", "nullable": true, "description": "Valor do IBS — campo `vIBS`." }, "NfeCbsAliquot": { "type": "number", "nullable": true, "description": "Alíquota da CBS (%) — campo `pCBS`." }, "NfeCbspRedAliquot": { "type": "number", "nullable": true, "description": "Percentual de redução da alíquota da CBS — campo `pRedAliq`." }, "NfeCbsValue": { "type": "number", "nullable": true, "description": "Valor da CBS — campo `vCBS`." } } }, "OrderSkuMovement": { "type": "object", "description": "Item adicionado retornado pelo `orderSkuPost`. Mesmo shape do item dentro de `Items` (algumas chaves podem aparecer apenas quando o pedido tem vendedor com regra de comissão vigente).", "properties": { "IDSkuMovement": { "type": "integer", "description": "Identificador da linha de movimentação de estoque gerada para o item do pedido." }, "IDSku": { "type": "integer", "description": "Identificador do SKU adicionado ao pedido." }, "SkuName": { "type": "string", "description": "Nome do SKU." }, "Quantity": { "type": "number", "description": "Quantidade do SKU no item do pedido." }, "PriceSelling": { "type": "number", "description": "Preço de venda unitário aplicado (após descontos por unidade)." }, "PriceList": { "type": "number", "description": "Preço de tabela (preço cheio) do SKU no momento da venda." }, "PriceSellingTotal": { "type": "number", "description": "Valor total da linha já com desconto aplicado (`PriceSelling * Quantity`, onde `PriceSelling` é o preço unitário após desconto). Para o preço cheio antes do desconto, multiplique `PriceList * Quantity`." }, "ValueDiscount": { "type": "number", "nullable": true, "description": "Valor de desconto monetário aplicado ao item." }, "PercentDiscount": { "type": "number", "nullable": true, "description": "Percentual de desconto aplicado ao item." }, "QtyAvailable": { "type": "number", "description": "Quantidade disponível em estoque do SKU no momento da inclusão (informativo para a tela)." }, "PackageNumber": { "type": "integer", "nullable": true, "description": "Número do volume (caixa) ao qual o item foi alocado durante a separação. Vazio antes do empacotamento." }, "BarCode": { "type": "string", "nullable": true, "description": "Código de barras principal do SKU." }, "IDSkuCompany": { "type": "string", "nullable": true, "description": "Código de referência interno do SKU, definido pela empresa." }, "AccountName": { "type": "string", "description": "Subdomínio (conta) da empresa dona do pedido." }, "IDBatch": { "type": "integer", "nullable": true, "description": "Lote do SKU baixado (`IDBatchNumber`). Vazio quando o SKU não usa controle de lote." }, "AbcCurve": { "type": "string", "nullable": true, "description": "Classificação ABC do SKU (`A`, `B`, `C`) com base na participação no faturamento." }, "MainImageURL": { "type": "string", "nullable": true, "description": "URL da imagem principal do SKU para exibição na tela do pedido." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de validade do lote, no formato `YYYY-MM-DD`. Vazio quando o SKU não usa controle de validade." }, "Address": { "type": "string", "nullable": true, "description": "Endereço de armazenagem (rua-coluna-nível) de onde o SKU foi separado. Vazio antes da separação." }, "QuantityNonconformity": { "type": "number", "nullable": true, "description": "Quantidade do item registrada como não conformidade (avariada/faltante/divergente) na separação ou recebimento. Vazio quando não há não conformidade." }, "IDTypeFulfillmentNonconformity": { "type": "integer", "nullable": true, "description": "Tipo da não conformidade do item (ex.: avaria, falta, divergência de SKU). Vazio quando não há não conformidade.", "enum": [ 1, 2, 4, 5, 6 ] }, "TypeFulfillmentNonconformity": { "type": "string", "nullable": true, "description": "Descrição amigável do tipo de não conformidade." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém de origem do item baixado." }, "WarehouseName": { "type": "string", "nullable": true, "description": "Nome do armazém de origem." }, "IDTaxDepartment": { "type": "integer", "nullable": true, "description": "Departamento fiscal (regra tributária) aplicado ao item neste pedido." }, "TaxDepartmentDescription": { "type": "string", "nullable": true, "description": "Descrição do departamento fiscal." }, "IDTypeSku": { "type": "integer", "nullable": true, "description": "Tipo do SKU: `1` Clube, `2` Kit, `3` Sku (produto normal), `4` Produto com variação (pai), `5` Serviço, `6` Matéria-prima, `7` Uso e consumo, `8` Caixa fechada." }, "SkuNCM": { "type": "string", "nullable": true, "description": "Código NCM do SKU para fins fiscais." }, "SkuCst": { "type": "string", "nullable": true, "description": "Código CST (Código de Situação Tributária) do SKU." }, "NfOrigDescription": { "type": "string", "nullable": true, "description": "Descrição da origem da mercadoria para fins fiscais (ex.: `Nacional`, `Estrangeira - Importação direta`)." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres do item do pedido." }, "Gratification": { "type": "integer", "description": "`1` quando o item é uma gratificação/bonificação (não compõe receita); `0` quando é venda normal." }, "NfeFcpSTValue": { "type": "number", "description": "Valor do FCP-ST (Fundo de Combate à Pobreza retido por Substituição Tributária) calculado para o item." }, "NfeIcmsSTValue": { "type": "number", "description": "Valor do ICMS-ST (Substituição Tributária) calculado para o item." }, "NfeIpiValue": { "type": "number", "description": "Valor do IPI calculado para o item." }, "SkuWeightTotal": { "type": "number", "description": "Peso total da linha em kg (`SkuWeight × Quantity`) — usado em cálculos de frete." }, "IDCategory": { "type": "integer", "nullable": true, "description": "Categoria principal (folha) do SKU." }, "IDCategoryArray": { "type": "array", "items": { "type": "string" }, "description": "Hierarquia completa de categorias do SKU, do topo até a folha (ex.: `[1, 12, 145]`)." }, "IDSalesmanComission": { "type": "integer", "nullable": true, "description": "Identificador da regra de comissão de vendedor aplicada ao item." }, "ComissionPercent": { "type": "number", "nullable": true, "description": "Percentual de comissão calculado para o vendedor sobre o item." }, "ComissionValue": { "type": "number", "nullable": true, "description": "Valor de comissão em reais calculado para o vendedor sobre o item." }, "ValueOrderItem": { "type": "number", "description": "Valor do item para totalização do pedido. Quando o tipo de pedido **não** usa cálculo reverso de imposto (`ReverseTaxCalculation = 0`), soma os impostos retidos: `PriceSellingTotal + NfeValueIcmsST + NfeValueFcpSt + NfeValueIpi`. Quando usa cálculo reverso (impostos já embutidos no preço), repete `PriceSellingTotal`. O desconto do item já entrou no `PriceSellingTotal`, então não é subtraído de novo." } } }, "OrderPaymentPostBody": { "type": "object", "description": "Pagamento(s) a lançar no pedido. Aceita um único título ou um array de títulos — a aplicação efetiva (criação das parcelas, geração de boleto/link, etc.) é feita pelo processo financeiro. Os campos abaixo são os mínimos esperados; campos adicionais específicos do tipo de pagamento (`IDBankAccountForecast`, `DocumentNumber`, `TID`, `NSU`, `IDCompanyIntegration` etc.) também são aceitos.", "required": [ "IDTypePayment", "Value", "DateDue" ], "properties": { "IDTypePayment": { "type": "integer", "description": "Tipo de pagamento configurado na empresa." }, "Value": { "type": "number", "description": "Valor total a lançar. Quando `?SplitInstallment` é maior que 1, o processo rateia em parcelas." }, "Installment": { "type": "integer", "description": "Número da parcela (1-based). Default `1`." }, "InstallmentTotal": { "type": "integer", "description": "Total de parcelas. Default `1`." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento da primeira parcela." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data do documento." }, "DocumentNumber": { "type": "string", "nullable": true, "description": "Número do documento da forma de pagamento (ex.: número do cheque, número do boleto, número da nota promissória). Aceita vazio." }, "IDBankAccountForecast": { "type": "integer", "nullable": true, "description": "Conta bancária prevista para recebimento." }, "IDConsumer": { "type": "integer", "nullable": true, "description": "Cliente pagador (quando difere do cliente do pedido)." }, "IDTypeAccountPayableReceivable": { "type": "integer", "nullable": true, "description": "Plano de contas (subtipo financeiro)." }, "IDTypeDocument": { "type": "integer", "nullable": true, "description": "Tipo de documento financeiro." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração (adquirente, gateway, gateway de boleto)." }, "Comments": { "type": "string", "nullable": true, "description": "Observações livres do lançamento do pagamento." }, "TID": { "type": "string", "nullable": true, "description": "TID (Transaction ID) retornado pela adquirente/gateway de pagamento. Preenchido quando o pagamento é por cartão capturado em maquininha ou gateway." }, "NSU": { "type": "string", "nullable": true, "description": "NSU (Número Sequencial Único) retornado pela adquirente/gateway na captura do pagamento." }, "Forecast": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, o lançamento é previsão (ainda não confirmado)." } }, "additionalProperties": true }, "AccountsPayableReceivableUpdateBody": { "type": "object", "description": "Atualização parcial de um título financeiro vinculado ao pedido. `IDConsumer` e `IDSupplier` são mutuamente exclusivos — informe apenas um. Quando o título já tem boleto/link de pagamento pago, alterações em `Value`/`DateDue` são bloqueadas; quando o boleto/link ainda está em aberto, a alteração dispara reemissão junto ao gateway.", "properties": { "Comments": { "type": "string", "nullable": true, "description": "Observações do título." }, "IDTypePayment": { "type": "integer", "description": "Tipo de pagamento configurado na empresa." }, "TID": { "type": "string", "nullable": true, "description": "Identificador da transação no adquirente/gateway de pagamento. Quando alterado junto com `Value`/`DateDue`, dispara reemissão do boleto/link de pagamento." }, "NSU": { "type": "string", "nullable": true, "description": "Número sequencial único da transação fornecido pelo adquirente." }, "Value": { "type": "number", "description": "Valor do título." }, "Installment": { "type": "integer", "description": "Número da parcela atual (1 para a primeira). Usado em pagamentos parcelados." }, "InstallmentTotal": { "type": "integer", "description": "Quantidade total de parcelas do pagamento." }, "IDConsumer": { "type": "integer", "nullable": true, "description": "Cliente vinculado ao título (limpa `IDSupplier` quando enviado)." }, "IDSupplier": { "type": "integer", "nullable": true, "description": "Fornecedor vinculado ao título (limpa `IDConsumer` quando enviado)." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência. String vazia limpa o campo." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data do documento. String vazia limpa o campo." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento." }, "IDBankAccountForecast": { "type": "integer", "nullable": true, "description": "Conta bancária prevista. O literal string `\"0\"` é ignorado." }, "DocumentNumber": { "type": "string", "nullable": true, "description": "Número do documento (nota, recibo, boleto)." }, "IDTypeAccountPayableReceivable": { "type": "integer", "description": "Plano de contas." }, "IDTypeDocument": { "type": "integer", "description": "Tipo de documento financeiro." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração (adquirente/gateway) associada." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Filial faturadora (precisa pertencer ao mesmo grupo da empresa)." }, "ValueDiscount": { "type": "number", "nullable": true, "description": "Desconto aplicado no pagamento." }, "ValueInterest": { "type": "number", "nullable": true, "description": "Juros aplicados." }, "ValuePenalty": { "type": "number", "nullable": true, "description": "Multa aplicada." }, "Forecast": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, marca o título como previsão." } } }, "OrderPackagePostBody": { "type": "object", "description": "Pacote a criar / regenerar para o pedido. Aceita dois modos de uso: (a) criar um pacote único informando as dimensões; (b) garantir uma quantidade total de pacotes via `PackageQuantityTotal` (cria pacotes vazios até atingir o total ou apaga os excedentes — números mais altos primeiro).", "properties": { "PackageWeight": { "type": "number", "nullable": true, "description": "Peso do pacote (kg)." }, "PackageHeight": { "type": "number", "nullable": true, "description": "Altura do pacote (cm)." }, "PackageLength": { "type": "number", "nullable": true, "description": "Comprimento do pacote (cm)." }, "PackageWidth": { "type": "number", "nullable": true, "description": "Largura do pacote (cm)." }, "PackageQuantityTotal": { "type": "integer", "description": "Quando enviado, força a quantidade total de pacotes do pedido a esse valor (cria ou remove pacotes vazios)." }, "IDSku": { "type": "integer", "description": "Quando enviado, adiciona uma movimentação no pedido com esse produto como brinde/embalagem (quantidade `1`, preço `0`, armazém padrão da empresa)." } } }, "OrderPackagePutBody": { "type": "object", "description": "Atualização de um pacote — código de rastreio do envio e/ou vínculo com romaneio.", "properties": { "ShippingId": { "type": "string", "nullable": true, "description": "Código de rastreio do pacote retornado pela transportadora. Precisa ser único dentro da transportadora; envie string vazia ou `null` para limpar." }, "IDOrdersCarrierCollectionList": { "type": "integer", "nullable": true, "description": "Romaneio em que o pacote é incluído. Precisa pertencer à mesma transportadora e ao mesmo centro de distribuição do pedido e estar com status que permita inclusão. Envie `null` para retirar do romaneio." } } }, "OrderCustomFile": { "type": "object", "description": "Arquivo customizado anexado ao pedido (assinatura digital de entrega, foto de documento, fotos da entrega).", "properties": { "IDOrdersCustomFile": { "type": "integer", "description": "Identificador do arquivo." }, "IDOrder": { "type": "integer", "description": "Pedido vinculado." }, "IDTypeOrderFile": { "type": "integer", "description": "Tipo do arquivo (1=Entrega, 2=Devolução, etc. — consulte `TypeOrderFile`).", "enum": [ 1, 2, 3 ] }, "TypeOrderFile": { "type": "string", "description": "Descrição do tipo." }, "ConsumerDocument": { "type": "string", "nullable": true, "description": "Documento do recebedor." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Nome do recebedor." }, "Comments": { "type": "string", "nullable": true, "description": "Observações da entrega." }, "File1Name": { "type": "string", "nullable": true, "description": "Nome do arquivo de assinatura no S3." }, "File2Name": { "type": "string", "nullable": true, "description": "Nome do primeiro anexo (foto do documento)." }, "File3Name": { "type": "string", "nullable": true, "description": "Nome do segundo anexo." }, "File4Name": { "type": "string", "nullable": true, "description": "Nome do terceiro anexo." }, "UrlFile1Name": { "type": "string", "nullable": true, "description": "URL pré-assinada do S3 (validade 2 dias) para a assinatura." }, "UrlFile2Name": { "type": "string", "nullable": true, "description": "URL pré-assinada para o primeiro anexo." }, "UrlFile3Name": { "type": "string", "nullable": true, "description": "URL pré-assinada para o segundo anexo." }, "UrlFile4Name": { "type": "string", "nullable": true, "description": "URL pré-assinada para o terceiro anexo." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de inclusão." } }, "additionalProperties": true }, "OrderFilePostBody": { "type": "object", "description": "Arquivos customizados a anexar ao pedido. Pelo menos um entre `Signature`, `DocumentImage`, `DocumentImage2` ou `DocumentImage3` precisa vir preenchido (data URL base64).", "properties": { "Signature": { "type": "string", "description": "Imagem da assinatura do recebedor em formato data URL base64 (ex.: `data:image/png;base64,...`). Salva como `_Signature.`." }, "DocumentImage": { "type": "string", "nullable": true, "description": "Primeira imagem do documento/comprovante (data URL base64)." }, "DocumentImage2": { "type": "string", "nullable": true, "description": "Segunda imagem (data URL base64)." }, "DocumentImage3": { "type": "string", "nullable": true, "description": "Terceira imagem (data URL base64)." }, "ConsumerDocument": { "type": "string", "nullable": true, "description": "Documento do recebedor (CPF/CNPJ ou RG)." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Nome do recebedor." }, "Comments": { "type": "string", "nullable": true, "description": "Observações da entrega." }, "IDStatusOrder": { "type": "integer", "description": "Status final a aplicar quando `ChangeStatus=1`. Quando omitido, o sistema escolhe automaticamente (`8` para transportadoras de devolução — tipos 30/32 — e `7` para as demais)." } } }, "CarrierQuotationRate": { "type": "object", "description": "Cotação retornada por uma transportadora elegível na disputa.", "properties": { "IDCarrier": { "type": "integer", "description": "Identificador do fornecedor (transportadora)." }, "IDCarrierQuotationRate": { "type": "integer", "description": "Identificador interno da cotação retornada por essa transportadora." }, "Attended": { "type": "integer", "description": "Resultado da consulta — `1` atende, `0` não atende, `3` excluído pela regra, `4` fora da faixa." }, "AttendedDescription": { "type": "string", "description": "Texto correspondente ao código `Attended` — `Atende`, `Não Atende`, `Excluído` ou `Fora da faixa`." }, "DaysTime": { "type": "integer", "description": "Prazo de entrega em dias úteis informado pela transportadora.", "nullable": true }, "CarrierAdditionalBusinessDays": { "type": "integer", "description": "Dias úteis adicionais cadastrados na transportadora.", "nullable": true }, "CutDaysTime": { "type": "integer", "description": "Dias adicionais por horário de corte.", "nullable": true }, "TotalDaysTime": { "type": "integer", "description": "Soma de `DaysTime`, `CarrierAdditionalBusinessDays` e `CutDaysTime`." }, "TotalShowDaysTime": { "type": "integer", "description": "Prazo final exibido ao usuário (`TotalDaysTime` mais os dias adicionais da regra)." }, "RateType": { "type": "string", "description": "Tipo de tabela aplicada (peso, cubagem, valor).", "nullable": true }, "ShipingValue": { "type": "number", "description": "Valor base do frete antes das taxas adicionais.", "nullable": true }, "AdvaloremValue": { "type": "number", "description": "Valor da taxa ad valorem.", "nullable": true }, "AdvaloremValuePercent": { "type": "number", "description": "Percentual ad valorem sobre `ValueInvoice` da cotação.", "nullable": true }, "GrisValue": { "type": "number", "description": "Valor do GRIS (gerenciamento de risco).", "nullable": true }, "GrisValuePercent": { "type": "number", "description": "Percentual de GRIS sobre `ValueInvoice`.", "nullable": true }, "TollValue": { "type": "number", "description": "Valor do pedágio.", "nullable": true }, "TollFractionValue": { "type": "number", "description": "Valor de pedágio fracionado.", "nullable": true }, "AccessDifficultyRateValue": { "type": "number", "description": "Taxa de difícil acesso.", "nullable": true }, "DispatchFeeValue": { "type": "number", "description": "Taxa de despacho.", "nullable": true }, "DeliveryDifficultyRateValue": { "type": "number", "description": "Taxa de difícil entrega.", "nullable": true }, "SECCATValue": { "type": "number", "description": "Taxa SEC/CAT.", "nullable": true }, "TrafficRestrictionFeeValue": { "type": "number", "description": "Taxa de restrição de circulação.", "nullable": true }, "AdministrationFeeValue": { "type": "number", "description": "Taxa administrativa.", "nullable": true }, "CTEFeeValue": { "type": "number", "description": "Taxa de emissão de CT-e.", "nullable": true }, "SUFRAMAFeeValue": { "type": "number", "description": "Taxa SUFRAMA.", "nullable": true }, "FluvialInsuranceFee": { "type": "number", "description": "Taxa de seguro fluvial.", "nullable": true }, "OtherFee": { "type": "number", "description": "Outras taxas extras.", "nullable": true }, "OtherFeeValue": { "type": "number", "description": "Valor de outras taxas.", "nullable": true }, "IcmsValue": { "type": "number", "description": "Valor do ICMS aplicado sobre o frete.", "nullable": true }, "IcmsValuePercent": { "type": "number", "description": "Percentual de ICMS efetivo (`IcmsValue / TotalShippingValue`).", "nullable": true }, "AdjustedValue": { "type": "number", "description": "Ajuste manual aplicado pela regra de cotação.", "nullable": true }, "PriceRounding": { "type": "number", "description": "Arredondamento de centavos aplicado ao valor final.", "nullable": true }, "SubtotalShippingValue": { "type": "number", "description": "Soma do `ShipingValue` com todas as taxas, antes do ICMS. Vem `null` quando `Attended` é diferente de `1`.", "nullable": true }, "TotalShippingValue": { "type": "number", "description": "Subtotal mais `IcmsValue`. Vem `null` quando `Attended` é diferente de `1`.", "nullable": true }, "ShippingShowValue": { "type": "number", "description": "Valor final exibido ao usuário (total + ajustes da regra). Vem `null` quando `Attended` é diferente de `1`.", "nullable": true }, "WeightSelected": { "type": "number", "description": "Peso considerado na cotação (real ou cubado, o que for maior).", "nullable": true }, "WeightCubed": { "type": "number", "description": "Peso cubado calculado.", "nullable": true }, "Weight": { "type": "number", "description": "Peso real dos itens do pedido.", "nullable": true }, "CarrierCubageKmM": { "type": "number", "description": "Fator de cubagem por metro cúbico configurado na transportadora.", "nullable": true }, "CarrierCubageFreeWeight": { "type": "number", "description": "Peso mínimo isento de cubagem.", "nullable": true }, "SupplierNameCorporateName": { "type": "string", "description": "Razão social da transportadora.", "nullable": true }, "CarrierLogoUrl": { "type": "string", "description": "URL do logo da transportadora.", "nullable": true }, "CarrierModal": { "type": "string", "description": "Modalidade da transportadora (rodoviário, aéreo, etc.).", "nullable": true }, "CarrierQuotationRuleValueName": { "type": "string", "description": "Nome da regra de cotação aplicada para valor.", "nullable": true }, "CarrierQuotationRuleDaysName": { "type": "string", "description": "Nome da regra de cotação aplicada para prazo.", "nullable": true }, "IDCarrierQuotationRuleValue": { "type": "integer", "description": "Identificador da regra de valor aplicada.", "nullable": true }, "IDCarrierQuotationRuleDays": { "type": "integer", "description": "Identificador da regra de prazo aplicada.", "nullable": true }, "RuleAdditionalValue": { "type": "number", "description": "Valor extra aplicado pela regra.", "nullable": true }, "RuleAdditionalDays": { "type": "integer", "description": "Dias extras aplicados pela regra.", "nullable": true } } }, "CarrierQuotation": { "type": "object", "description": "Resultado da disputa de frete (auction) para um pedido. Ordenado por `Attended` descendente, depois prazo e valor totais.", "properties": { "IDCarrierQuotation": { "type": "integer", "description": "Identificador da disputa de frete." }, "IDOrder": { "type": "integer", "description": "Pedido relacionado.", "nullable": true }, "IDCompany": { "type": "integer", "description": "Empresa dona da cotação." }, "ValueInvoice": { "type": "number", "description": "Valor declarado para cálculo de ad valorem.", "nullable": true }, "Weight": { "type": "number", "description": "Peso total considerado na consulta.", "nullable": true }, "ShippingPostalCode": { "type": "string", "description": "CEP de destino consultado.", "nullable": true }, "Recordtimestamp": { "type": "string", "format": "date-time", "description": "Quando a disputa foi registrada.", "nullable": true }, "RecordUserCreated": { "type": "integer", "description": "Usuário que disparou a disputa.", "nullable": true }, "Login": { "type": "string", "description": "Login do usuário responsável pela disputa.", "nullable": true }, "CompanyAddressPostalCode": { "type": "string", "description": "CEP de origem da empresa.", "nullable": true }, "CompanyAddressState": { "type": "string", "description": "UF de origem da empresa.", "nullable": true }, "CarrierQuotations": { "type": "array", "description": "Lista de cotações por transportadora elegível.", "items": { "$ref": "#/components/schemas/CarrierQuotationRate" } } } }, "HubOrderSku": { "type": "object", "description": "Item do pedido no marketplace.", "properties": { "IDSku": { "type": "integer", "description": "Identificador do SKU interno.", "nullable": true }, "IDSkuHub": { "type": "string", "description": "Código do SKU no marketplace.", "nullable": true }, "IDSkuCompany": { "type": "string", "description": "Código do SKU no cadastro da empresa.", "nullable": true }, "SkuName": { "type": "string", "description": "Nome do SKU.", "nullable": true }, "Quantity": { "type": "number", "description": "Quantidade do item." }, "PriceSelling": { "type": "number", "description": "Preço de venda unitário do marketplace.", "nullable": true }, "ValueDiscount": { "type": "number", "description": "Desconto aplicado ao item.", "nullable": true }, "IDWarehouseHub": { "type": "string", "description": "Armazém do marketplace.", "nullable": true }, "IDProductHub": { "type": "string", "description": "Código do produto no marketplace.", "nullable": true }, "IDHubProduct": { "type": "integer", "description": "Identificador interno do produto no hub.", "nullable": true }, "IDIntegrationProducts": { "type": "string", "description": "Identificador do item dentro do pedido do marketplace.", "nullable": true }, "Comments": { "type": "string", "description": "Observações enviadas pelo comprador para o item.", "nullable": true }, "MainImageURL": { "type": "string", "description": "URL da imagem principal do SKU.", "nullable": true } } }, "HubOrderPaymentItem": { "type": "object", "description": "Pagamento recebido pelo marketplace.", "properties": { "Acquirer": { "type": "string", "description": "Adquirente do pagamento (Cielo, Stone, etc.).", "nullable": true }, "Connector": { "type": "string", "description": "Conector usado pelo marketplace.", "nullable": true }, "Installments": { "type": "integer", "description": "Número de parcelas." }, "PaymentSystem": { "type": "string", "description": "Tipo de meio de pagamento.", "nullable": true }, "PaymentSystemName": { "type": "string", "description": "Nome amigável do meio de pagamento.", "nullable": true }, "TransactionIdentifier": { "type": "string", "description": "Identificador da transação no adquirente.", "nullable": true }, "InterestValue": { "type": "number", "description": "Juros aplicados pelo parcelamento.", "nullable": true }, "Value": { "type": "number", "description": "Valor recebido." } } }, "HubOrderMessageItem": { "type": "object", "description": "Mensagem trocada com o comprador no marketplace (inclui mensagens sintéticas geradas a partir de reclamações).", "properties": { "IDHubOrderMessage": { "type": "integer", "description": "Identificador interno da mensagem.", "nullable": true }, "IDHubOrderMessageExternal": { "type": "string", "description": "Identificador da mensagem no marketplace.", "nullable": true }, "IDIntegration": { "type": "integer", "description": "Pedido do marketplace ao qual a mensagem pertence." }, "Message": { "type": "string", "description": "Texto da mensagem." }, "MessageTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de envio.", "nullable": true }, "ReadTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora em que o destinatário marcou como lida.", "nullable": true }, "Seller": { "type": "integer", "description": "Origem da mensagem — `1` quando enviada pelo lojista, demais valores indicam o comprador ou o marketplace." }, "Attachments": { "type": "array", "description": "URLs temporárias dos anexos da mensagem (assinadas, válidas por 2 dias).", "items": { "type": "string" } } } }, "HubOrderClaimAction": { "type": "object", "description": "Ação disponível para resolver uma reclamação no marketplace.", "properties": { "Mandatory": { "type": "integer", "description": "`1` quando a ação é obrigatória, `0` caso contrário." }, "IDTypeHubOrderClaimActionExternalId": { "type": "string", "description": "Identificador da ação no marketplace." }, "TypeHubOrderClaimActionDescription": { "type": "string", "description": "Descrição amigável da ação.", "nullable": true }, "PartialRefundOffers": { "type": "array", "description": "Ofertas de reembolso parcial disponíveis (apenas quando a ação é `allow_partial_refund`).", "items": { "type": "object", "properties": { "Amount": { "type": "number", "description": "Valor da oferta de reembolso parcial em reais — uma das opções predefinidas pelo marketplace para o vendedor oferecer ao comprador." }, "Percentage": { "type": "number", "description": "Percentual sobre o valor do pedido representado pela oferta de reembolso parcial." } } } }, "ReturnFailReasons": { "type": "array", "description": "Lista de motivos disponíveis para reprovar a revisão da devolução (apenas em `return_review_fail`).", "items": { "type": "object", "properties": { "Reason": { "type": "string", "description": "Código interno do motivo de recusa da revisão de devolução, no padrão do marketplace (ex.: `received_in_bad_condition`)." }, "ReasonName": { "type": "string", "description": "Descrição amigável do motivo de recusa, em português, para exibir ao vendedor." } } } }, "OptionsList": { "type": "array", "description": "Modalidades de envio disponíveis e os campos esperados para cada uma (em `add_shipping_evidence` e `send_tracking_number`).", "items": { "type": "object", "properties": { "ShippingMethod": { "type": "string", "description": "Método de envio para anexar como evidência: `mail` (Correios), `carrier` (transportadora), `delivered_by_seller` (entrega pelo próprio vendedor), etc." }, "ShippingMethodLabel": { "type": "string", "description": "Rótulo amigável do método de envio (ex.: `Correios`, `Transportadora`, `Entrega própria`)." }, "FieldList": { "type": "array", "items": { "type": "object", "properties": { "Field": { "type": "string", "description": "Nome técnico do campo a ser enviado no `POST /orders/hub/{idorder}/message` (ex.: `ShippingDate`, `ShippingId`, `Attachment`)." }, "FieldName": { "type": "string", "description": "Rótulo do campo em português para exibição na tela." }, "FieldType": { "type": "string", "description": "Tipo do campo no formulário: `date`, `string`, `array` (lista de anexos)." }, "FieldRequired": { "type": "integer", "description": "`1` quando o campo é obrigatório para registrar a evidência; `0` quando opcional." } } }, "description": "Lista de campos que o vendedor precisa preencher para registrar a evidência de envio neste método." } } } } } }, "HubOrderClaim": { "type": "object", "description": "Reclamação aberta no marketplace para o pedido.", "properties": { "IDHubOrderClaim": { "type": "integer", "description": "Identificador interno da reclamação." }, "IDHubOrderClaimExternal": { "type": "string", "description": "Identificador da reclamação no marketplace.", "nullable": true }, "ClaimStatus": { "type": "integer", "description": "Status atual da reclamação.", "nullable": true }, "ClaimCreationDate": { "type": "string", "format": "date-time", "description": "Data/hora de abertura.", "nullable": true }, "IDTypeHubOrderClaimType": { "type": "integer", "description": "Tipo da reclamação.", "nullable": true, "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "TypeHubOrderClaimTypeName": { "type": "string", "description": "Nome do tipo de reclamação.", "nullable": true }, "IDTypeHubOrderClaimStage": { "type": "integer", "description": "Estágio da reclamação.", "nullable": true, "enum": [ 1, 2, 3, 4, 5 ] }, "TypeHubOrderClaimStageName": { "type": "string", "description": "Nome do estágio.", "nullable": true }, "IDTypeHubOrderClaimReason": { "type": "integer", "description": "Motivo cadastrado.", "nullable": true }, "TypeHubOrderClaimReason": { "type": "string", "description": "Descrição do motivo.", "nullable": true }, "IDTypeHubOrderClaimResolutionReason": { "type": "integer", "description": "Motivo de resolução.", "nullable": true }, "TypeHubOrderClaimResolutionReasonDescription": { "type": "string", "description": "Descrição do motivo de resolução.", "nullable": true }, "ClaimTimestampLastUpdated": { "type": "string", "format": "date-time", "description": "Última atualização.", "nullable": true }, "ClaimResolutionDate": { "type": "string", "format": "date-time", "description": "Data de resolução.", "nullable": true }, "IDProductHub": { "type": "string", "description": "Produto envolvido.", "nullable": true }, "AutopartsProductId": { "type": "string", "description": "Identificador no catálogo de autopeças.", "nullable": true }, "AutopartsProductDetail": { "type": "string", "description": "Descrição do produto no catálogo de autopeças.", "nullable": true }, "IDHubProductAutoparts": { "type": "integer", "description": "Vínculo interno do produto com a base de autopeças.", "nullable": true }, "DueDate": { "type": "string", "format": "date-time", "description": "Prazo final para resposta.", "nullable": true }, "ActionResponsible": { "type": "string", "description": "Parte responsável pela próxima ação.", "nullable": true }, "ClaimTitle": { "type": "string", "description": "Título da reclamação.", "nullable": true }, "ClaimDescription": { "type": "string", "description": "Texto descritivo da reclamação.", "nullable": true }, "ClaimProblem": { "type": "string", "description": "Resumo do problema relatado.", "nullable": true }, "AvailableActions": { "type": "array", "description": "Ações disponíveis para resolver a reclamação. Vazio quando `ClaimStatus = 1`.", "items": { "$ref": "#/components/schemas/HubOrderClaimAction" } } } }, "HubOrderClaimMessage": { "type": "object", "description": "Mensagem trocada no contexto de uma reclamação.", "properties": { "IDHubOrderClaimMessage": { "type": "integer", "description": "Identificador da mensagem." }, "IDHubOrderClaim": { "type": "integer", "description": "Reclamação relacionada." }, "Sender": { "type": "integer", "description": "Origem da mensagem (`1` lojista, outros valores comprador/marketplace)." }, "Message": { "type": "string", "description": "Texto da mensagem." }, "MessageTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de envio.", "nullable": true }, "ReadTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora em que foi lida.", "nullable": true }, "Attachments": { "type": "array", "description": "URLs temporárias dos anexos.", "items": { "type": "string" } } } }, "HubOrderDetail": { "type": "object", "description": "Detalhe completo do pedido integrado a um marketplace (hub).", "properties": { "IDIntegration": { "type": "integer", "description": "Identificador do pedido no hub." }, "IDOrder": { "type": "integer", "description": "Pedido idworks vinculado, quando já existe.", "nullable": true }, "Order": { "type": "string", "description": "Número do pedido no idworks.", "nullable": true }, "OrderId": { "type": "string", "description": "Identificador do pedido no marketplace.", "nullable": true }, "PackId": { "type": "string", "description": "Identificador do pack de pedidos no marketplace.", "nullable": true }, "Status": { "type": "string", "description": "Status retornado pelo marketplace.", "nullable": true }, "HubOrderStatus": { "type": "string", "description": "Tradução do status para o vocabulário do idworks.", "nullable": true }, "CreateOrder": { "type": "integer", "description": "Sinaliza se o status atual já gera o pedido no idworks (`1`/`0`).", "nullable": true }, "CreateOrderDescription": { "type": "string", "description": "Descrição amigável do flag `CreateOrder`.", "nullable": true }, "CreationTimestamp": { "type": "string", "format": "date-time", "description": "Quando o pedido foi criado no marketplace.", "nullable": true }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Quando o pedido foi importado.", "nullable": true }, "AccountName": { "type": "string", "description": "Conta idworks responsável.", "nullable": true }, "IDCompanyIntegration": { "type": "integer", "description": "Integração de empresa associada ao pedido." }, "IDTypeCompanyIntegration": { "type": "integer", "description": "Tipo de integração (Mercado Livre, Olist, etc.)." }, "IDSalesChannel": { "type": "integer", "description": "Canal de venda usado.", "nullable": true }, "SalesChannelName": { "type": "string", "description": "Nome do canal de venda.", "nullable": true }, "SalesChannelLogoUrl": { "type": "string", "description": "URL do logo do canal.", "nullable": true }, "CompanyIntegrationName": { "type": "string", "description": "Nome amigável da conta integrada.", "nullable": true }, "CompanyIntegration": { "type": "string", "description": "Nome composto ` - `.", "nullable": true }, "SalesChannelOrderLink": { "type": "string", "description": "URL para o pedido na plataforma do marketplace (apenas para Mercado Livre, SkyHub e Olist).", "nullable": true }, "ConsumerDocument": { "type": "string", "description": "CPF/CNPJ do comprador informado pelo marketplace.", "nullable": true }, "ConsumerEmail": { "type": "string", "description": "E-mail do comprador.", "nullable": true }, "ConsumerFirstName": { "type": "string", "description": "Primeiro nome do comprador.", "nullable": true }, "IDConsumer": { "type": "integer", "description": "Cliente cadastrado no idworks, quando vinculado.", "nullable": true }, "Coupon": { "type": "string", "description": "Cupom aplicado.", "nullable": true }, "ShippingId": { "type": "string", "description": "Código de envio principal.", "nullable": true }, "ShippingCourierId": { "type": "string", "description": "Identificador da transportadora no marketplace.", "nullable": true }, "ShippingEstimateDate": { "type": "string", "format": "date", "description": "Previsão de entrega.", "nullable": true }, "ShippingEstimateHandlingLimitDate": { "type": "string", "format": "date-time", "description": "Prazo limite para o seller processar.", "nullable": true }, "IDWarehouseHub": { "type": "string", "description": "Armazém do marketplace usado no pedido.", "nullable": true }, "TotalOrderValue": { "type": "number", "description": "Valor total do pedido no marketplace.", "nullable": true }, "TotalShippingValue": { "type": "number", "description": "Valor do frete.", "nullable": true }, "TotalDiscountValue": { "type": "number", "description": "Desconto aplicado.", "nullable": true }, "TotalInterestValue": { "type": "number", "description": "Juros do parcelamento.", "nullable": true }, "TotalItemsValue": { "type": "number", "description": "Soma `Quantity * PriceSelling` dos itens." }, "QuantityItems": { "type": "number", "description": "Soma das quantidades dos itens." }, "QuantityPayments": { "type": "integer", "description": "Quantidade de pagamentos cadastrados." }, "UtmCampaign": { "type": "string", "description": "Campanha UTM.", "nullable": true }, "UtmMedium": { "type": "string", "description": "Mídia UTM.", "nullable": true }, "UtmSource": { "type": "string", "description": "Origem UTM.", "nullable": true }, "UtmiCampaign": { "type": "string", "description": "Campanha UTMi interna.", "nullable": true }, "UtmiPage": { "type": "string", "description": "Página UTMi.", "nullable": true }, "UtmiPart": { "type": "string", "description": "Parte UTMi.", "nullable": true }, "SKUs": { "type": "array", "description": "Itens do pedido.", "items": { "$ref": "#/components/schemas/HubOrderSku" } }, "Payments": { "type": "array", "description": "Pagamentos recebidos.", "items": { "$ref": "#/components/schemas/HubOrderPaymentItem" } }, "Messages": { "type": "array", "description": "Mensagens trocadas com o comprador, já incluindo entradas geradas a partir das reclamações.", "items": { "$ref": "#/components/schemas/HubOrderMessageItem" } }, "Claims": { "type": "array", "description": "Reclamações abertas para o pedido.", "items": { "$ref": "#/components/schemas/HubOrderClaim" } }, "ClaimsMessages": { "type": "array", "description": "Mensagens das reclamações.", "items": { "$ref": "#/components/schemas/HubOrderClaimMessage" } }, "Index": { "type": "integer", "description": "Posição do registro no array de resultados (preenchida internamente)." } } }, "OrderTrackingEvent": { "type": "object", "description": "Evento de rastreamento registrado pelos sistemas da transportadora.", "properties": { "IDCarrierTracking": { "type": "integer", "description": "Identificador interno do evento." }, "IDStatusTracking": { "type": "integer", "description": "Status interno do evento." }, "Description": { "type": "string", "description": "Descrição do status retornada pela transportadora.", "nullable": true }, "City": { "type": "string", "description": "Cidade onde o evento ocorreu.", "nullable": true }, "State": { "type": "string", "description": "UF do evento.", "nullable": true }, "Place": { "type": "string", "description": "Local específico (centro, agência).", "nullable": true }, "PickUpAddress": { "type": "string", "description": "Endereço de retirada quando aplicável.", "nullable": true }, "TrackingTimestamp": { "type": "string", "format": "date-time", "description": "Quando o evento foi reportado." }, "PackageNumber": { "type": "integer", "description": "Volume ao qual o evento se refere.", "nullable": true } } }, "OrderTrackingPackage": { "type": "object", "description": "Volume rastreável do pedido.", "properties": { "IDPackage": { "type": "integer", "description": "Identificador do volume." }, "PackageNumber": { "type": "integer", "description": "Número do volume dentro do pedido." }, "ShippingId": { "type": "string", "description": "Código de rastreio enviado pela transportadora.", "nullable": true }, "TrackingEvents": { "type": "array", "description": "Eventos retornados para esse volume, ordenados do mais recente para o mais antigo.", "items": { "$ref": "#/components/schemas/OrderTrackingEvent" } } } }, "OrderTrackingDetail": { "type": "object", "description": "Dados de rastreamento agrupados por pedido.", "properties": { "IDOrder": { "type": "integer", "description": "Identificador do pedido." }, "Order": { "type": "string", "description": "Número do pedido." }, "Recordtimestamp": { "type": "string", "format": "date-time", "description": "Quando o pedido foi criado.", "nullable": true }, "ShippingEstimateDate": { "type": "string", "format": "date", "description": "Previsão de entrega prometida ao consumidor.", "nullable": true }, "ConsumerNameCorporateName": { "type": "string", "description": "Nome do consumidor.", "nullable": true }, "ConsumerCpfCnpj": { "type": "string", "description": "CPF/CNPJ do consumidor.", "nullable": true }, "IDPackage": { "type": "integer", "description": "Volume principal do pedido.", "nullable": true }, "IDStatusPackage": { "type": "integer", "description": "Status do volume principal.", "nullable": true, "enum": [ 1, 2 ] }, "StatusPackage": { "type": "string", "description": "Descrição do status do volume.", "nullable": true }, "IDCarrierType": { "type": "integer", "description": "Tipo da transportadora.", "nullable": true }, "SupplierNameCorporateName": { "type": "string", "description": "Razão social da transportadora.", "nullable": true }, "CarrierLogoUrl": { "type": "string", "description": "URL do logo da transportadora.", "nullable": true }, "TrackingUrl": { "type": "string", "description": "URL pública para o consumidor acompanhar o rastreio." }, "ShippingDate": { "type": "string", "format": "date-time", "description": "Maior data de envio entre os volumes.", "nullable": true }, "ShippingId": { "type": "string", "description": "Lista de códigos de rastreio agregados (separados por vírgula).", "nullable": true }, "PackagesQty": { "type": "integer", "description": "Quantidade de volumes do pedido." }, "TrackingIDStatus": { "type": "integer", "description": "Maior status de rastreio entre os volumes.", "nullable": true }, "StatusTracking": { "type": "string", "description": "Descrição do status de rastreio.", "nullable": true }, "TrackingLastStatus": { "type": "string", "description": "Último status reportado pela transportadora.", "nullable": true }, "TrackingLastStatusRecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora do último status.", "nullable": true }, "ConsumerDeliveryDateDifference": { "type": "integer", "description": "Diferença em dias entre a entrega e o prazo prometido ao consumidor.", "nullable": true }, "CarrierDeliveryDateDifference": { "type": "integer", "description": "Diferença em dias entre a entrega e o prazo prometido pela transportadora.", "nullable": true }, "IDStatusDeliveryConsumer": { "type": "integer", "description": "Classificação SLA frente ao prazo do consumidor — `1` entregue no prazo, `2` entregue em atraso, `3` em trânsito dentro do prazo, `4` em trânsito atrasado, `6` entregue no dia limite.", "nullable": true }, "StatusDeliveryConsumer": { "type": "string", "description": "Descrição do `IDStatusDeliveryConsumer`.", "nullable": true }, "IDStatusDeliveryCarrier": { "type": "integer", "description": "Classificação SLA frente ao prazo da transportadora — mesma codificação.", "nullable": true }, "StatusDeliveryCarrier": { "type": "string", "description": "Descrição do `IDStatusDeliveryCarrier`.", "nullable": true }, "Packages": { "type": "array", "description": "Volumes do pedido. Quando a transportadora não suporta rastreio por volume, é retornado apenas o primeiro.", "items": { "$ref": "#/components/schemas/OrderTrackingPackage" } } } }, "OrderReturnItem": { "type": "object", "description": "Item a ser devolvido.", "properties": { "IDSkuMovement": { "type": "integer", "description": "Identificador da movimentação do pedido original que está sendo devolvida." }, "Quantity": { "type": "number", "description": "Quantidade a devolver." } }, "required": [ "IDSkuMovement", "Quantity" ] }, "OrderReturnBody": { "type": "object", "description": "Parâmetros para gerar o pedido de devolução. Os mesmos campos podem ser enviados por query string em snake_case (`idtypeorderreturn`, `comments`, `balancechange`, `withvalue`, `idstockkeepingunitwarehouse`, etc.) ou em PascalCase no body. Quando o body traz `Items`, apenas as movimentações listadas são devolvidas; sem `Items`, devolve todas as movimentações do pedido original.", "properties": { "IDTypeOrderReturn": { "type": "integer", "description": "Tipo de devolução cadastrado em `GET /type/order/return`. Obrigatório para devoluções enviadas no body." }, "IDTypeOrderReturnCategory": { "type": "integer", "description": "Categoria do tipo de devolução.", "nullable": true, "enum": [ 1, 2, 3 ] }, "Comments": { "type": "string", "description": "Observações que vão para o pedido de devolução.", "nullable": true }, "BalanceChange": { "type": "integer", "enum": [ 0, 1 ], "description": "Se a devolução afeta saldo de estoque (`1` afeta, `0` não). Padrão `1`." }, "WithValue": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, mantém preço e desconto do pedido original; quando `0`, zera os valores. Padrão `1`." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Armazém destino dos itens devolvidos. Validado contra os armazéns ativos da empresa.", "nullable": true }, "CreateInbound": { "type": "integer", "enum": [ 0, 1 ], "description": "Se deve gerar recebimento (`Inbound`) associado à devolução.", "nullable": true }, "ConsumerVoucher": { "type": "integer", "enum": [ 0, 1 ], "description": "Se deve gerar voucher de troca para o cliente.", "nullable": true }, "IssueInvoice": { "type": "integer", "enum": [ 0, 1 ], "description": "Se deve emitir nota fiscal de devolução automaticamente.", "nullable": true }, "IDConsumer": { "type": "integer", "description": "Cliente alvo da devolução. Quando informado junto com `IDAddress`, substitui o cliente/endereço do pedido original.", "nullable": true }, "IDAddress": { "type": "integer", "description": "Endereço alternativo de entrega para a devolução.", "nullable": true }, "Items": { "type": "array", "description": "Lista de movimentações a devolver. Quando omitido, devolve todos os itens.", "items": { "$ref": "#/components/schemas/OrderReturnItem" } } } }, "OrderPromotion": { "type": "object", "description": "Promoções do PDV (idworks) e benefícios do hub aplicados ao pedido.", "properties": { "StockKeepingUnitPromotion": { "type": "array", "description": "Promoções de PDV vinculadas ao pedido.", "items": { "type": "object", "properties": { "IDStockKeepingUnitPromotion": { "type": "integer", "description": "Identificador da promoção." }, "StockKeepingUnitPromotionName": { "type": "string", "description": "Nome da promoção." }, "IDOrdersPromotion": { "type": "integer", "description": "Vínculo entre pedido e promoção." } } } }, "HubOrderBenefit": { "type": "array", "description": "Benefícios/promoções aplicados pelo marketplace.", "items": { "type": "object", "properties": { "BenefitName": { "type": "string", "description": "Nome do benefício.", "nullable": true }, "IDIntegration": { "type": "integer", "description": "Pedido do marketplace." }, "IDIntegrationBenefits": { "type": "string", "description": "Identificador do benefício no marketplace.", "nullable": true } } } } } }, "HubCarrierMapping": { "type": "object", "description": "Registro do DE-PARA de transportadora — espelha colunas de `HubCarrier` enriquecidas com nomes já resolvidos (transportadora interna, integração, modal, armazém, status final).", "properties": { "IDHubCarrier": { "type": "integer", "format": "int64", "description": "Identificador do mapeamento." }, "AccountName": { "type": "string", "description": "Subdomínio da conta dona do registro." }, "IDCarrierFrom": { "type": "string", "maxLength": 450, "description": "Identificador da transportadora no canal de venda (texto livre — costuma ser o `IDCarrier`/código que chega no pedido do canal)." }, "IDCarrierTo": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador da transportadora cadastrada no idworks (`IDSupplier`). Fica `null` quando `CarrierAuctionByModal=1` (leilão por modal — o sistema escolhe a transportadora em runtime)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de criação do registro." }, "OrderOnHold": { "type": "integer", "description": "Indicador interno (`0`/`1`) — quando `1`, pedidos chegando com esta transportadora ficam retidos para análise.", "default": 0 }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração a que o DE-PARA pertence." }, "NfeModFrete": { "type": "integer", "nullable": true, "description": "Modalidade de frete a aplicar na NF-e do pedido. Valor casa com `NfModFrete` (`0`=Emitente, `1`=Destinatário, `2`=Terceiros, `3`=Próprio remetente, `4`=Próprio destinatário, `9`=Sem frete)." }, "IDStatusOrder": { "type": "integer", "nullable": true, "description": "Status do pedido que será aplicado automaticamente quando o pedido entrar com esta transportadora. Deve referenciar um `TypeStatusOrder` com `ChangeOnCreate=1`." }, "CarrierAuctionByModal": { "type": "integer", "nullable": true, "description": "Quando `1`, a transportadora final é escolhida em tempo de roteirização via leilão entre as transportadoras do modal indicado em `IDCarrierModal`. Quando `null`/`0`, usa a transportadora fixa em `IDCarrierTo`." }, "IDCarrierModal": { "type": "integer", "format": "int64", "nullable": true, "description": "Modal de transporte (`IDCarrierModal`) usado quando `CarrierAuctionByModal=1`." }, "CarrierAuctionByModalOrderPreference": { "type": "integer", "nullable": true, "description": "Critério de desempate no leilão por modal. `1` = menor preço, `2` = menor prazo." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "format": "int64", "nullable": true, "description": "Armazém de origem do pedido aplicado quando o pedido cai neste DE-PARA." }, "IDTypeCarrierAuction": { "type": "integer", "nullable": true, "description": "Tipo de leilão de frete habilitado para este DE-PARA. `1` = por modalidade, `2` = por prazo." }, "IDTypeCarrierAuctionTiebreaker": { "type": "integer", "nullable": true, "description": "Critério de desempate do leilão. `1` = transportadora com maior ocupação, `2` = transportadora com menor ocupação." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Nome resolvido da transportadora interna (`SupplierTradeName - SupplierNameCorporateName`, ou só o nome corporativo quando não tem nome fantasia)." }, "CompanyIntegrationName": { "type": "string", "description": "Nome cadastrado da integração." }, "IntegrationName": { "type": "string", "description": "Nome do tipo de integração (`IntegrationName`)." }, "IDTypeCompanyIntegration": { "type": "integer", "format": "int64", "description": "Tipo da integração." }, "CompanyIntegration": { "type": "string", "description": "Concatenação `{IntegrationName} - {CompanyIntegrationName}` para exibição." }, "NfModFreteDescription": { "type": "string", "nullable": true, "description": "Descrição da modalidade de frete." }, "StatusOrder": { "type": "string", "nullable": true, "description": "Nome do status do pedido aplicado (`StatusOrder`)." }, "CarrierModal": { "type": "string", "nullable": true, "description": "Nome do modal de transporte." }, "CarrierAuctionByModalOrderPreferenceDescription": { "type": "string", "nullable": true, "description": "Nome do critério de desempate por modal — `Preço` quando `CarrierAuctionByModalOrderPreference=1`, `Prazo` quando `=2`." }, "WarehouseName": { "type": "string", "nullable": true, "description": "Nome do armazém de origem (`WarehouseName`)." }, "StatusColorCode": { "type": "string", "nullable": true, "description": "Código hexadecimal da cor configurada para o status do pedido naquela empresa (ex.: #18AA8C); nulo quando usa a cor padrão." } } }, "HubCarrierCreateBody": { "type": "object", "required": [ "IDCompanyIntegration", "IDCarrierFrom" ], "description": "Corpo para criação de um DE-PARA de transportadora.", "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração a que o DE-PARA pertence. Validado contra `CompanyIntegration` da empresa autenticada." }, "IDCarrierFrom": { "type": "string", "maxLength": 450, "description": "Identificador da transportadora no canal (texto livre)." }, "IDCarrierTo": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador da transportadora interna (`IDSupplier`). Quando `CarrierAuctionByModal=1` o sistema força este campo para `null` (leilão por modal)." }, "NfeModFrete": { "type": "integer", "nullable": true, "description": "Modalidade de frete da NF-e. `0`=Emitente, `1`=Destinatário, `2`=Terceiros, `3`=Próprio remetente, `4`=Próprio destinatário, `9`=Sem frete." }, "IDStatusOrder": { "type": "integer", "nullable": true, "description": "Status do pedido aplicado na chegada. Validado contra `ChangeOnCreate=1`." }, "CarrierAuctionByModal": { "type": "integer", "nullable": true, "description": "`1` para ativar leilão por modal (a transportadora é escolhida em runtime)." }, "CarrierAuctionByModalOrderPreference": { "type": "integer", "nullable": true, "description": "Critério do leilão por modal. `1`=menor preço, `2`=menor prazo." }, "IDCarrierModal": { "type": "integer", "format": "int64", "nullable": true, "description": "Modal de transporte aplicável ao leilão. Validado contra `TypeCarrierModal` da empresa." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "format": "int64", "nullable": true, "description": "Armazém de origem. Validado contra `StockKeepingUnitWarehouse` da empresa." }, "IDTypeCarrierAuction": { "type": "integer", "nullable": true, "description": "Tipo de leilão. `1`=modalidade, `2`=prazo." }, "IDTypeCarrierAuctionTiebreaker": { "type": "integer", "nullable": true, "description": "Desempate do leilão. `1`=maior ocupação, `2`=menor ocupação." } } }, "HubCarrierUpdateBody": { "type": "object", "description": "Corpo para atualização de um DE-PARA de transportadora. Mesma estrutura do POST — todos os campos são revalidados.", "required": [ "IDCompanyIntegration", "IDCarrierFrom" ], "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração a que o DE-PARA pertence. Validado contra `CompanyIntegration` da empresa autenticada." }, "IDCarrierFrom": { "type": "string", "maxLength": 450, "description": "Identificador da transportadora no canal (texto livre)." }, "IDCarrierTo": { "type": "integer", "format": "int64", "nullable": true, "description": "Identificador da transportadora interna (`IDSupplier`). Quando `CarrierAuctionByModal=1` o sistema força este campo para `null` (leilão por modal)." }, "NfeModFrete": { "type": "integer", "nullable": true, "description": "Modalidade de frete da NF-e. `0`=Emitente, `1`=Destinatário, `2`=Terceiros, `3`=Próprio remetente, `4`=Próprio destinatário, `9`=Sem frete." }, "IDStatusOrder": { "type": "integer", "nullable": true, "description": "Status do pedido aplicado na chegada. Validado contra `ChangeOnCreate=1`." }, "CarrierAuctionByModal": { "type": "integer", "nullable": true, "description": "`1` para ativar leilão por modal (a transportadora é escolhida em runtime)." }, "CarrierAuctionByModalOrderPreference": { "type": "integer", "nullable": true, "description": "Critério do leilão por modal. `1`=menor preço, `2`=menor prazo." }, "IDCarrierModal": { "type": "integer", "format": "int64", "nullable": true, "description": "Modal de transporte aplicável ao leilão. Validado contra `TypeCarrierModal` da empresa." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "format": "int64", "nullable": true, "description": "Armazém de origem. Validado contra `StockKeepingUnitWarehouse` da empresa." }, "IDTypeCarrierAuction": { "type": "integer", "nullable": true, "description": "Tipo de leilão. `1`=modalidade, `2`=prazo." }, "IDTypeCarrierAuctionTiebreaker": { "type": "integer", "nullable": true, "description": "Desempate do leilão. `1`=maior ocupação, `2`=menor ocupação." } } }, "HubAcquirerMapping": { "type": "object", "description": "Registro do DE-PARA de adquirente — espelha `HubAcquirer` com nomes resolvidos das integrações envolvidas.", "properties": { "IDHubAcquirer": { "type": "integer", "format": "int64", "description": "Identificador do mapeamento." }, "AccountName": { "type": "string", "description": "Identificador da empresa proprietária do mapeamento." }, "IDAcquirerFrom": { "type": "string", "maxLength": 45, "description": "Identificador da adquirente no canal de venda (texto livre — código que chega no pedido importado do canal)." }, "IDAcquirerTo": { "type": "integer", "format": "int64", "description": "Identificador da adquirente cadastrada no idworks (apontando para um `CompanyIntegration` do tipo adquirente da empresa)." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração de venda a que o DE-PARA pertence." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de criação do mapeamento." }, "CompanyIntegration": { "type": "string", "description": "Concatenação `{IntegrationName} - {CompanyIntegrationName}` da integração de venda." }, "IDTypeCompanyIntegration": { "type": "integer", "format": "int64", "description": "Tipo da integração de venda." }, "CompanyIntegrationAcquirer": { "type": "string", "description": "Concatenação `{IntegrationName} - {CompanyIntegrationName}` da adquirente cadastrada (`IDAcquirerTo`)." } } }, "HubAcquirerCreateBody": { "type": "object", "required": [ "IDCompanyIntegration", "IDAcquirerFrom", "IDAcquirerTo" ], "description": "Corpo para criação/atualização de DE-PARA de adquirente. Mesma estrutura aceita por `POST` e `PUT`.", "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração de venda. Validado contra `CompanyIntegration` da empresa autenticada." }, "IDAcquirerFrom": { "type": "string", "maxLength": 45, "description": "Identificador da adquirente no canal (texto livre)." }, "IDAcquirerTo": { "type": "integer", "format": "int64", "description": "Adquirente cadastrada no idworks (referencia outra `CompanyIntegration` da mesma empresa, do tipo adquirente)." } } }, "HubVariationMapping": { "type": "object", "description": "Registro do DE-PARA de variação — espelha `HubVariation` enriquecido com o nome da variação interna, a integração e a categoria do canal.", "properties": { "IDHubVariation": { "type": "integer", "format": "int64", "description": "Identificador do mapeamento." }, "AccountName": { "type": "string", "description": "Identificador da empresa proprietária do mapeamento." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de criação do mapeamento." }, "IDVariationFrom": { "type": "string", "maxLength": 45, "description": "Identificador da variação no canal (código da variação, texto livre)." }, "IDVariationTo": { "type": "integer", "format": "int64", "description": "Identificador da variação interna (`IDTypeProductVariation`)." }, "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração a que o DE-PARA pertence." }, "IDHubCategory": { "type": "integer", "format": "int64", "description": "DE-PARA de categoria do canal (`IDHubCategory`). A categoria intermedeia o mapeamento porque os atributos disponíveis dependem da categoria do produto no canal." }, "VariationName": { "type": "string", "description": "Nome da variação interna (`ProductVariation`)." }, "IDSalesChannel": { "type": "integer", "nullable": true, "description": "Canal de venda do tipo de integração." }, "CompanyIntegrationName": { "type": "string", "description": "Nome amigável da integração configurado pela empresa." }, "IntegrationName": { "type": "string", "description": "Nome do tipo de integração." }, "CompanyIntegration": { "type": "string", "description": "Concatenação `{IntegrationName} - {CompanyIntegrationName}`." }, "CategoryFromTree": { "type": "string", "nullable": true, "description": "Árvore completa da categoria no canal (ex.: 'Eletrônicos > TV > Smart TV'), vinda do `HubCategory`." }, "IDTypeCompanyIntegration": { "type": "integer", "format": "int64", "description": "Tipo da integração." }, "IDCategoryFrom": { "type": "string", "nullable": true, "description": "Código da categoria no canal (do `HubCategory`)." } } }, "HubVariationCreateBody": { "type": "object", "required": [ "IDCompanyIntegration", "IDHubCategory", "IDVariationFrom", "IDVariationTo" ], "description": "Corpo para criação/atualização de DE-PARA de variação. Mesma estrutura aceita por `POST` e `PUT`.", "properties": { "IDCompanyIntegration": { "type": "integer", "format": "int64", "description": "Integração a que o DE-PARA pertence." }, "IDHubCategory": { "type": "integer", "format": "int64", "description": "DE-PARA de categoria do canal (obtido via `GET /hub/category`). Define o contexto em que a variação é válida." }, "IDVariationFrom": { "type": "string", "maxLength": 45, "description": "Identificador da variação no canal (texto livre)." }, "IDVariationTo": { "type": "integer", "format": "int64", "description": "Variação interna (`IDTypeProductVariation`). Validada contra a empresa autenticada." } } }, "HubIntegrationResource": { "type": "object", "description": "Recurso de canal de venda exposto para a tela — descreve o que pode ser consultado (categorias, atributos, modos de envio, etc.) para um tipo de integração. Vem de `TypeSalesChannelResource`.", "properties": { "IDTypeSalesChannelResource": { "type": "integer", "format": "int64", "description": "Identificador interno do recurso (`IDTypeSalesChannelResource`)." }, "ResourceType": { "type": "string", "maxLength": 45, "description": "Tipo do recurso (ex.: `Autoparts`, `Category`, `CategoryAttribute`, `SkuCondition`, `TypeOffer`, `ModeShipping`, `OfficialStore`)." }, "Resource": { "type": "string", "maxLength": 45, "description": "Chave técnica única do recurso dentro do tipo de integração." }, "ResourceDescription": { "type": "string", "maxLength": 500, "description": "Descrição do recurso — texto exibido na tela como tooltip/ajuda." }, "ResourceName": { "type": "string", "maxLength": 45, "description": "Nome amigável para exibição." }, "ResourceUrl": { "type": "string", "maxLength": 300, "description": "Endpoint relativo do processo que serve o recurso. O `POST /hub/resource/{idtypecompanyintegration}` o usa para montar a URL final." }, "ResourceOrder": { "type": "integer", "description": "Ordem de apresentação na tela." }, "ResourceKey": { "type": "string", "maxLength": 45, "nullable": true, "description": "Chave do recurso retornada pelo canal — usada para correlacionar a resposta com cadastros internos quando há mapeamento direto." }, "Confirm": { "type": "integer", "nullable": true, "description": "Quando `1`, a ação relacionada pede confirmação na tela." }, "IDTypeCompanyIntegration": { "type": "integer", "format": "int64", "nullable": true, "description": "Tipo de integração a que o recurso pertence." }, "RateLimit": { "type": "integer", "default": 1, "description": "Limite de requisições por janela (segundos) para evitar throttle no canal." }, "Cache": { "type": "integer", "default": 0, "description": "Política de armazenamento da resposta. `0` = sempre consulta o canal; `1` = armazenamento padrão (3 dias) com fallback para o canal em miss; `2` = só usa o armazenamento existente (alimentado por outro processo)." }, "IntegrationName": { "type": "string", "description": "Nome do tipo de integração (`IntegrationName`)." } } }, "HubNotification": { "type": "object", "description": "Notificação/problema de integração detectada pelo sistema (`HubIntegrationProblem`), com o tipo, categoria e o registro associado (pedido, SKU, anúncio, conforme o tipo do problema).", "properties": { "IDHubNotification": { "type": "integer", "format": "int64", "description": "Identificador da notificação." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data em que o problema foi detectado." }, "IDTypeHubIntegrationProblem": { "type": "integer", "description": "Tipo do problema (`IDTypeHubIntegrationProblem`)." }, "EmailStatus": { "type": "integer", "nullable": true, "description": "Status do disparo do e-mail de notificação ao operador. `null` quando não houve envio." }, "ID": { "type": "integer", "format": "int64", "description": "Identificador do registro afetado — o significado depende do tipo do problema (ex.: `IDOrder` para problemas de pedido, `IDSku` para SKU)." }, "Message": { "type": "string", "maxLength": 5000, "nullable": true, "description": "Mensagem específica do problema (quando o sistema captura o texto retornado pelo canal)." }, "IDCompany": { "type": "integer", "format": "int64", "description": "Identificador interno da empresa dona da notificação." }, "AccountName": { "type": "string", "description": "Identificador da empresa dona da notificação." }, "TypeHubIntegrationProblem": { "type": "string", "description": "Nome do tipo do problema (resolvido)." }, "Component": { "type": "string", "maxLength": 45, "nullable": true, "description": "Componente do frontend que sabe abrir o registro afetado a partir do `ID`." }, "TypeHubIntegrationProblemCategory": { "type": "string", "description": "Categoria do problema (resolvida de `TypeHubIntegrationProblemCategory`)." }, "Params": { "type": "string", "nullable": true, "description": "Concatenação `Params + ID` — string já pronta para o frontend usar como parâmetro de navegação para o registro afetado." } } }, "ConsumerAddress": { "type": "object", "description": "Endereço de entrega/cobrança do cliente.", "properties": { "IDAddress": { "type": "integer", "format": "int32", "description": "Identificador do endereço." }, "ConsumerStateInscription": { "type": "string", "maxLength": 20, "nullable": true, "description": "Inscrição estadual aplicada a este endereço. Quando `ShippingState=MG` e o valor não é `ISENTO`, o sistema completa com zeros à esquerda até 13 dígitos." }, "ShippingCity": { "type": "string", "maxLength": 100, "nullable": true, "description": "Cidade. Para endereços fora do Brasil (`IDCountry` diferente de `1`), o sistema grava `EXTERIOR`." }, "ShippingComplement": { "type": "string", "maxLength": 200, "nullable": true, "description": "Complemento do endereço." }, "ShippingNeighborhood": { "type": "string", "maxLength": 100, "nullable": true, "description": "Bairro." }, "ShippingNumber": { "type": "string", "maxLength": 80, "nullable": true, "description": "Número do endereço." }, "ShippingPostalCode": { "type": "string", "maxLength": 10, "nullable": true, "description": "CEP. Apenas dígitos são considerados para a consulta IBGE." }, "ShippingReceiverName": { "type": "string", "maxLength": 100, "nullable": true, "description": "Nome do recebedor." }, "ShippingState": { "type": "string", "maxLength": 2, "nullable": true, "description": "UF. Para endereços no exterior, o sistema grava `EX`." }, "ShippingStreet": { "type": "string", "maxLength": 100, "nullable": true, "description": "Logradouro." }, "ShippingIbgeCode": { "type": "integer", "format": "int32", "nullable": true, "description": "Código IBGE do município, resolvido a partir do CEP." }, "StatusAddress": { "type": "integer", "format": "int32", "description": "`1` ativo, `0` removido. A listagem só retorna endereços ativos." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de cadastro do endereço." }, "IDCountry": { "type": "integer", "format": "int32", "description": "Identificador do país. `1` = Brasil." }, "Country": { "type": "string", "description": "Nome do país." }, "ConsumerCpfCnpj": { "type": "string", "maxLength": 14, "nullable": true, "description": "CPF ou CNPJ associado ao endereço (pode divergir do cliente, ex.: entrega em nome de terceiro)." }, "ConsumerEmail": { "type": "string", "maxLength": 200, "nullable": true, "description": "E-mail associado ao endereço." }, "ConsumerTelephone": { "type": "string", "maxLength": 15, "nullable": true, "description": "Telefone associado ao endereço." } } }, "ConsumerAddressCreateBody": { "type": "object", "description": "Corpo do `POST` para cadastrar um endereço de cliente.", "required": [ "ShippingPostalCode", "ShippingState", "ShippingCity", "ShippingStreet" ], "properties": { "IDCountry": { "type": "integer", "format": "int32", "default": 1, "description": "Identificador do país. Default `1` (Brasil). Quando diferente de `1`, o sistema valida contra os países cadastrados, força `ShippingState=EX` e `ShippingCity=EXTERIOR` e pula a consulta de CEP." }, "ShippingPostalCode": { "type": "string", "maxLength": 10, "description": "CEP. Para `IDCountry=1`, o sistema consulta a base de CEP interna para resolver o código IBGE do município." }, "ShippingState": { "type": "string", "maxLength": 2, "description": "UF." }, "ShippingCity": { "type": "string", "maxLength": 100, "description": "Cidade." }, "ShippingNeighborhood": { "type": "string", "maxLength": 100, "nullable": true, "description": "Bairro." }, "ShippingStreet": { "type": "string", "maxLength": 100, "description": "Logradouro." }, "ShippingNumber": { "type": "string", "maxLength": 80, "nullable": true, "description": "Número." }, "ShippingComplement": { "type": "string", "maxLength": 200, "nullable": true, "description": "Complemento." }, "ShippingReceiverName": { "type": "string", "maxLength": 100, "nullable": true, "description": "Nome do recebedor." }, "ConsumerStateInscription": { "type": "string", "maxLength": 20, "nullable": true, "description": "Inscrição estadual. Quando `ShippingState=MG` e o valor não for `ISENTO`, é preenchido à esquerda com zeros até 13 dígitos." }, "ConsumerCpfCnpj": { "type": "string", "maxLength": 14, "nullable": true, "description": "CPF ou CNPJ vinculado ao endereço (quando difere do cliente)." } } }, "ConsumerAddressUpdateBody": { "type": "object", "description": "Corpo do `PUT` para atualizar um endereço de cliente. Todos os campos são opcionais — envie só os que mudaram.", "properties": { "IDCountry": { "type": "integer", "format": "int32", "description": "Identificador do país. Quando ausente, é assumido como `1` (Brasil). Diferente de `1` força `ShippingState=EX` e `ShippingCity=EXTERIOR` e pula a consulta de CEP." }, "ShippingPostalCode": { "type": "string", "maxLength": 10, "nullable": true, "description": "CEP. Para `IDCountry=1`, dispara consulta da base de CEP interna para resolver o código IBGE." }, "ShippingState": { "type": "string", "maxLength": 2, "nullable": true, "description": "UF." }, "ShippingCity": { "type": "string", "maxLength": 100, "nullable": true, "description": "Cidade." }, "ShippingNeighborhood": { "type": "string", "maxLength": 100, "nullable": true, "description": "Bairro." }, "ShippingStreet": { "type": "string", "maxLength": 100, "nullable": true, "description": "Logradouro." }, "ShippingNumber": { "type": "string", "maxLength": 80, "nullable": true, "description": "Número." }, "ShippingComplement": { "type": "string", "maxLength": 200, "nullable": true, "description": "Complemento." }, "ShippingReceiverName": { "type": "string", "maxLength": 100, "nullable": true, "description": "Nome do recebedor." }, "ConsumerStateInscription": { "type": "string", "maxLength": 20, "nullable": true, "description": "Inscrição estadual. Quando `ShippingState=MG` e o valor não for `ISENTO`, é preenchido à esquerda com zeros até 13 dígitos." }, "ConsumerCpfCnpj": { "type": "string", "maxLength": 14, "nullable": true, "description": "CPF ou CNPJ vinculado ao endereço." }, "ConsumerEmail": { "type": "string", "maxLength": 200, "nullable": true, "description": "E-mail vinculado ao endereço." }, "ConsumerTelephone": { "type": "string", "maxLength": 15, "nullable": true, "description": "Telefone vinculado ao endereço." } } }, "ConsumerContact": { "type": "object", "description": "Contato vinculado ao cliente.", "properties": { "IDConsumerContact": { "type": "integer", "format": "int32", "description": "Identificador do contato." }, "ContactName": { "type": "string", "maxLength": 100, "description": "Nome do contato." }, "ContactEmail": { "type": "string", "maxLength": 100, "nullable": true, "description": "E-mail do contato." }, "ContactTelephone": { "type": "string", "maxLength": 100, "nullable": true, "description": "Telefone do contato." }, "ContactResponsability": { "type": "string", "maxLength": 100, "nullable": true, "description": "Responsabilidade ou cargo do contato." }, "LegalRepresentative": { "type": "integer", "format": "int32", "default": 0, "description": "`1` quando o contato é representante legal do cliente; `0` caso contrário." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora do cadastro." } } }, "ConsumerContactCreateBody": { "type": "object", "description": "Corpo do `POST` para criar um contato.", "required": [ "ContactName" ], "properties": { "ContactName": { "type": "string", "maxLength": 100, "description": "Nome do contato." }, "ContactEmail": { "type": "string", "maxLength": 100, "nullable": true, "description": "E-mail do contato." }, "ContactTelephone": { "type": "string", "maxLength": 100, "nullable": true, "description": "Telefone do contato. Aceita também a chave `ContactTelephon` (typo histórico) como fallback." }, "ContactResponsability": { "type": "string", "maxLength": 100, "nullable": true, "description": "Responsabilidade ou cargo do contato." }, "LegalRepresentative": { "type": "integer", "format": "int32", "default": 0, "description": "`1` para marcar como representante legal; `0` caso contrário. Default `0`." } } }, "ConsumerContactUpdateBody": { "type": "object", "description": "Corpo do `PUT` para atualizar um contato. Apenas os campos enviados são alterados.", "properties": { "ContactName": { "type": "string", "maxLength": 100, "description": "Nome do contato." }, "ContactEmail": { "type": "string", "maxLength": 100, "nullable": true, "description": "E-mail do contato." }, "ContactTelephone": { "type": "string", "maxLength": 100, "nullable": true, "description": "Telefone do contato." }, "ContactResponsability": { "type": "string", "maxLength": 100, "nullable": true, "description": "Responsabilidade ou cargo do contato." }, "LegalRepresentative": { "type": "integer", "format": "int32", "description": "`1` para marcar como representante legal; `0` caso contrário." } } }, "ConsumerCreditBody": { "type": "object", "description": "Corpo do `POST`/`PUT` de crédito do cliente.", "required": [ "IDTypePayment", "CreditValue" ], "properties": { "IDTypePayment": { "type": "integer", "format": "int32", "description": "Forma de pagamento (`TypePayment`) cadastrada para a empresa autenticada. Um cliente não pode ter dois créditos para a mesma forma de pagamento." }, "CreditValue": { "type": "number", "format": "decimal", "multipleOf": 0.01, "description": "Valor do limite de crédito." }, "CommercialConditions": { "type": "string", "maxLength": 45, "nullable": true, "description": "Condições comerciais livres (ex.: prazo negociado, observações)." } } }, "ConsumerVoucher": { "type": "object", "description": "Movimento de vale (crédito ou consumo) do cliente.", "properties": { "IDConsumerVoucher": { "type": "integer", "format": "int32", "description": "Identificador do movimento." }, "IDConsumer": { "type": "integer", "format": "int32", "description": "Cliente dono do vale." }, "IDOrder": { "type": "integer", "format": "int32", "nullable": true, "description": "Pedido que originou o consumo do vale, quando aplicável." }, "Value": { "type": "number", "format": "decimal", "multipleOf": 0.01, "description": "Valor do movimento (sempre positivo). O sinal é dado por `IDTypeAccount`." }, "IDTypeAccount": { "type": "integer", "format": "int32", "enum": [ 0, 1 ], "description": "Tipo do movimento — `0` entrada (crédito gerado a favor do cliente), `1` saída (consumo do vale em um pedido)." }, "RecordUserCreated": { "type": "integer", "format": "int32", "nullable": true, "description": "Usuário que registrou o movimento." }, "Comments": { "type": "string", "maxLength": 200, "nullable": true, "description": "Comentário livre sobre o movimento." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Empresa faturadora dona do saldo (quando o vale é específico de um faturador)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora do movimento." }, "AccountName": { "type": "string", "description": "Nome da conta da empresa." }, "UserName": { "type": "string", "nullable": true, "description": "Nome do usuário que registrou." }, "Login": { "type": "string", "nullable": true, "description": "Login do usuário que registrou." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Nome da conta do faturador (`IDCompanyInvoice`)." }, "BalanceValue": { "type": "number", "format": "decimal", "multipleOf": 0.01, "description": "Saldo acumulado por cliente + faturador, calculado por janela ordenada pela data do movimento (`SUM` com `OVER PARTITION BY`)." } } }, "ConsumerVoucherCreateBody": { "type": "object", "description": "Corpo do `POST` para gerar um vale (movimento de entrada) para o cliente.", "required": [ "Value" ], "properties": { "Value": { "type": "number", "format": "decimal", "multipleOf": 0.01, "description": "Valor do vale. Precisa ser numérico e estritamente positivo." }, "Comments": { "type": "string", "maxLength": 200, "nullable": true, "description": "Comentário livre." }, "IDCompanyInvoice": { "type": "integer", "format": "int32", "nullable": true, "description": "Empresa faturadora à qual o vale fica vinculado. Se omitido, o sistema usa a empresa do cliente. Quando informado e diferente da empresa do cliente, é validado como faturador filho dela (`CompanyMain`)." } } }, "ConsumerVoucherDeleteBody": { "type": "object", "description": "Corpo opcional do `DELETE` de vale.", "properties": { "Comments": { "type": "string", "maxLength": 200, "nullable": true, "description": "Comentário livre registrado no log de exclusão." } } }, "ConsumerSalesmanBody": { "type": "object", "description": "Corpo do `POST` para vincular um vendedor ao cliente.", "required": [ "IDAcess" ], "properties": { "IDAcess": { "type": "integer", "format": "int32", "description": "Identificador do vínculo usuário-empresa (`IDAcess`) que representa o vendedor. Precisa estar ativo e pertencer à mesma empresa do cliente. A combinação `IDConsumer` + `IDAcess` é única; um vínculo já existente é mantido/atualizado (upsert)." } } }, "ConsumerDetail": { "type": "object", "description": "Detalhe completo do cliente devolvido pelos endpoints de criação/edição/exclusão de blocos vinculados. Inclui dados cadastrais, endereços, contatos, vendedores, créditos, cartões salvos, histórico de alterações (`ConsumerLog`) e arquivos. Mesmo shape de `GET /consumer/{idconsumer}`.", "properties": { "IDConsumer": { "type": "integer", "format": "int32", "description": "Identificador do cliente." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "description": "Nome (PF) ou razão social (PJ)." }, "ConsumerTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia." }, "ConsumerCpfCnpj": { "type": "string", "nullable": true, "description": "CPF (PF) ou CNPJ (PJ)." }, "ConsumerEmail": { "type": "string", "nullable": true, "description": "E-mail principal." }, "ConsumerTelephone": { "type": "string", "nullable": true, "description": "Telefone principal." }, "ConsumerBirthDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de nascimento (PF)." }, "ConsumerType": { "type": "integer", "format": "int32", "description": "Tipo do cliente: `1` Pessoa Física, `2` Pessoa Jurídica, `3` Estrangeiro.", "enum": [ 1, 2, 3 ] }, "StatusConsumer": { "type": "integer", "format": "int32", "description": "Status do cadastro (`TypeStatusConsumer`).", "enum": [ 0, 1, 2, 3 ] }, "Address": { "type": "array", "description": "Endereços ativos.", "items": { "$ref": "#/components/schemas/ConsumerAddress" } }, "Contacts": { "type": "array", "description": "Contatos do cliente.", "items": { "$ref": "#/components/schemas/ConsumerContact" } }, "ConsumerCredit": { "type": "array", "description": "Limites de crédito por forma de pagamento (já com saldo utilizado e disponível calculados).", "items": { "type": "object", "properties": { "IDConsumerCredit": { "type": "integer", "format": "int32", "description": "Identificador interno do crédito." }, "IDTypePayment": { "type": "integer", "format": "int32", "description": "Forma de pagamento à qual o crédito está vinculado (`IDTypePayment`)." }, "TypePaymentDescription": { "type": "string", "description": "Descrição da forma de pagamento." }, "CreditValue": { "type": "number", "format": "decimal", "multipleOf": 0.01, "description": "Valor do limite de crédito concedido para a forma de pagamento." }, "CommercialConditions": { "type": "string", "nullable": true, "description": "Condições comerciais livres (ex.: prazo negociado, observações)." }, "CreditValueUsed": { "type": "number", "format": "decimal", "multipleOf": 0.01, "description": "Valor já utilizado considerando contas a receber em aberto, líquido de baixas bancárias." }, "CreditValueLeft": { "type": "number", "format": "decimal", "multipleOf": 0.01, "description": "Saldo restante (`CreditValue - CreditValueUsed`)." } } } }, "ConsumerSalesman": { "type": "array", "description": "Vendedores vinculados.", "items": { "type": "object", "properties": { "IDConsumerSalesman": { "type": "integer", "format": "int32", "description": "Identificador do vínculo cliente–vendedor." }, "IDAcess": { "type": "integer", "format": "int32", "description": "Identificador do vínculo usuário–empresa que representa o vendedor (`IDAcess`)." }, "Login": { "type": "string", "description": "Login (email) do vendedor." }, "UserName": { "type": "string", "description": "Nome do vendedor." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora em que o vínculo foi criado." } } } }, "ConsumerCreditCard": { "type": "array", "description": "Cartões de crédito salvos.", "items": { "type": "object", "additionalProperties": true } }, "ConsumerLog": { "type": "array", "description": "Histórico de alterações do cadastro.", "items": { "type": "object", "additionalProperties": true } }, "ConsumerFile": { "type": "array", "description": "Arquivos anexos do cliente (com URL pré-assinada para download).", "items": { "type": "object", "additionalProperties": true } }, "ConsumerVoucherValue": { "type": "number", "format": "decimal", "multipleOf": 0.01, "nullable": true, "description": "Saldo total dos vales do cliente. Filtrado por faturador quando `BlockVoucherDifferentCompanyInvoice` está ativo." }, "OrderQuantity": { "type": "integer", "format": "int32", "description": "Total de pedidos do cliente." }, "OrderRevenueValueTotal": { "type": "number", "format": "decimal", "multipleOf": 0.01, "nullable": true, "description": "Soma das contas a receber do cliente." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora do cadastro." }, "DateLastRecordModification": { "type": "string", "format": "date-time", "nullable": true, "description": "Última atualização." } } }, "UserSigninLocalBody": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "description": "`Login` do usuário (email) ou CPF/CNPJ. O sistema detecta automaticamente o formato e busca pelo campo correspondente." }, "password": { "type": "string", "format": "password", "description": "Senha em texto plano. É comparada com o hash armazenado." }, "mfacode": { "type": "string", "nullable": true, "description": "Código de MFA. Obrigatório apenas quando o usuário tem `MFAEnabled = 1`: 6 dígitos recebidos por email (MFA `email`) ou o código atual do Google Authenticator (MFA `totp`)." }, "expireinhour": { "type": "string", "nullable": true, "description": "Tempo de expiração do token JWT, no formato aceito pelo `jsonwebtoken` (ex.: `12h`, `7d`). Default `14h`." } } }, "UserSigninResponse": { "type": "object", "description": "Resposta de login concluído com sucesso.", "properties": { "success": { "type": "boolean", "description": "Sempre `true` neste retorno." }, "token": { "type": "string", "description": "Token JWT a ser enviado em `Authorization` nas próximas requisições." }, "body": { "type": "object", "description": "Dados do usuário autenticado para o frontend exibir.", "properties": { "id": { "type": "integer", "description": "Identificador `IDUser`." }, "email": { "type": "string", "description": "`Login` do usuário (email)." }, "UserName": { "type": "string", "description": "Nome do usuário." }, "CompanyCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ da empresa." }, "Salesman": { "type": "integer", "nullable": true, "description": "Indica se o usuário é vendedor da empresa." }, "RestrictAccessSalesman": { "type": "integer", "nullable": true, "description": "Indica se o acesso do vendedor é restrito (vê apenas seus pedidos)." }, "CompanyNameCorporateName": { "type": "string", "description": "Razão social da empresa." }, "CompanyLogoUrl": { "type": "string", "nullable": true, "description": "URL do logo da empresa." }, "CompanyLogoUrlMain": { "type": "string", "nullable": true, "description": "URL do logo da empresa principal do grupo." }, "AccountNameMain": { "type": "string", "description": "`AccountName` da empresa principal do grupo." }, "CompanyNameCorporateNameMain": { "type": "string", "description": "Razão social da empresa principal do grupo." }, "ExternalDashboard": { "type": "string", "nullable": true, "description": "URL de dashboard externo configurado." }, "Theme": { "type": "string", "nullable": true, "description": "Tema visual padrão da empresa." }, "UserImageUrl": { "type": "string", "nullable": true, "description": "URL da foto do usuário." }, "IDModuleFavorite": { "type": "array", "items": { "type": "string" }, "description": "Lista de módulos favoritados pelo usuário (ids)." }, "HelpDeskToken": { "type": "string", "description": "JWT para autenticar o usuário no portal de chamados." }, "HelpDeskChatToken": { "type": "string", "description": "JWT para autenticar o usuário no chat de suporte." }, "CompanyPaymentStatus": { "type": "integer", "nullable": true, "description": "Status financeiro da empresa." }, "Parameters": { "type": "array", "description": "Parâmetros da integração de notificações da empresa.", "items": { "type": "object" } }, "ChatIA": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando o usuário tem habilitada a integração de chat com IA; caso contrário, `0`." }, "IDCompanyMainShare": { "type": "integer", "nullable": true, "description": "Identificador da empresa cujos dados estão sendo compartilhados com a empresa atual." }, "CompanyMainShare": { "type": "string", "nullable": true, "description": "`AccountName` da empresa que compartilha dados com a atual." }, "DaysBeforePasswordExpiration": { "type": "integer", "nullable": true, "description": "Dias restantes para a senha expirar. `null` quando não há expiração configurada." } } } } }, "UserSigninMFAChallenge": { "type": "object", "description": "Desafio de MFA. Retornado quando o usuário precisa fornecer (ou cadastrar) um segundo fator antes de receber o token.", "properties": { "MFAEnabled": { "type": "boolean", "description": "Sempre `true` neste retorno." }, "MFAType": { "type": "string", "enum": [ "email", "totp" ], "description": "Tipo de MFA configurado para o usuário." }, "EnrollmentRequired": { "type": "boolean", "nullable": true, "description": "Presente apenas no primeiro acesso com MFA `totp`. `true` indica que o usuário precisa cadastrar o segredo no Google Authenticator usando `OtpAuthUrl`." }, "OtpAuthUrl": { "type": "string", "nullable": true, "description": "URL no formato `otpauth://` para o usuário escanear no Google Authenticator. Presente apenas quando `EnrollmentRequired = true`." }, "Message": { "type": "string", "nullable": true, "description": "Mensagem orientando o próximo passo (ex.: `Código enviado por e-mail`, `Digite o codigo do Google Authenticator`)." } } }, "UserPasswordResetConfirmBody": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string", "format": "password", "description": "Nova senha em texto plano. Precisa atender às regras configuradas pela empresa (tamanho mínimo, complexidade, histórico)." } } }, "UserWorkScale": { "type": "object", "description": "Escala de trabalho com seus turnos.", "properties": { "AccountName": { "type": "string", "description": "Conta a que a escala pertence." }, "IDUserWorkScale": { "type": "integer", "format": "int32", "description": "Identificador da escala." }, "UserWorkScaleName": { "type": "string", "maxLength": 45, "description": "Nome da escala." }, "WorkShift": { "type": "array", "description": "Turnos que compõem a escala.", "items": { "type": "object", "properties": { "IDUserWorkShift": { "type": "integer", "format": "int32", "description": "Identificador do turno." }, "IDUserWorkScale": { "type": "integer", "format": "int32", "description": "Identificador da escala dona deste turno." }, "WeekDay": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Dia da semana: `0`=domingo, `1`=segunda, `2`=terça, `3`=quarta, `4`=quinta, `5`=sexta, `6`=sábado." }, "StartTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$", "description": "Horário de início do turno (`HH:mm:ss`)." }, "FinishTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$", "description": "Horário de fim do turno (`HH:mm:ss`)." } } } } } }, "UserWorkScaleCreateBody": { "type": "object", "required": [ "UserWorkScaleName" ], "properties": { "UserWorkScaleName": { "type": "string", "maxLength": 45, "description": "Nome da escala. Precisa ser único dentro da empresa." } } }, "UserWorkScaleUpdateBody": { "type": "object", "required": [ "UserWorkScaleName" ], "properties": { "UserWorkScaleName": { "type": "string", "maxLength": 45, "description": "Novo nome da escala. Precisa ser único dentro da empresa." } } }, "UserWorkShiftCreateBody": { "type": "object", "required": [ "IDUserWorkScale", "shifts" ], "properties": { "IDUserWorkScale": { "type": "integer", "format": "int32", "description": "Identificador da escala cujos turnos serão substituídos." }, "shifts": { "type": "array", "description": "Lista completa dos turnos da escala. O sistema apaga os turnos atuais e insere estes no lugar.", "items": { "type": "object", "required": [ "WeekDay", "StartTime", "FinishTime" ], "properties": { "WeekDay": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Dia da semana: `0`=domingo, `1`=segunda, `2`=terça, `3`=quarta, `4`=quinta, `5`=sexta, `6`=sábado." }, "StartTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$", "description": "Horário de início do turno (`HH:mm:ss`)." }, "FinishTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$", "description": "Horário de fim do turno (`HH:mm:ss`)." } } } } } }, "UserNotification": { "type": "object", "description": "Versão do sistema marcada como atual e suas novidades publicadas.", "properties": { "IDSystemVersion": { "type": "integer", "format": "int32", "description": "Identificador da versão." }, "Version": { "type": "string", "maxLength": 45, "description": "Número/rótulo da versão." }, "DateRelease": { "type": "string", "format": "date", "description": "Data de liberação da versão." }, "Current": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando esta é a versão atual exibida ao usuário." }, "Updates": { "type": "array", "description": "Novidades publicadas nessa versão.", "items": { "type": "object", "properties": { "IDSystemVersionUpdate": { "type": "integer", "format": "int32", "description": "Identificador da novidade." }, "Update": { "type": "string", "maxLength": 1000, "description": "Título da novidade." }, "Kind": { "type": "string", "maxLength": 45, "nullable": true, "description": "Categoria da novidade (ex.: `Novidade`, `Correção`)." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Quando a novidade foi publicada." }, "Description": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Descrição detalhada." }, "URLImage": { "type": "string", "maxLength": 500, "nullable": true, "description": "URL de imagem ilustrativa." }, "URLRedirect": { "type": "string", "maxLength": 500, "nullable": true, "description": "Link de saiba mais." }, "Confirm": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando o usuário autenticado já confirmou a leitura desta novidade; caso contrário, `0`." } } } } } }, "UserCompany": { "type": "object", "description": "Vínculo do usuário com uma empresa.", "properties": { "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa." }, "AccountName": { "type": "string", "description": "Identificador textual da conta (subdomínio)." }, "IDUser": { "type": "integer", "format": "int32", "description": "Identificador do usuário." }, "Salesman": { "type": "integer", "nullable": true, "description": "Indica se o usuário é vendedor nessa empresa." }, "CertificadoBestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Validade do certificado digital da empresa." }, "CompanyTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia." }, "NfeSerie": { "type": "string", "nullable": true, "description": "Série de NFe em uso." }, "NfeUltima": { "type": "integer", "nullable": true, "description": "Último número de NFe emitido." }, "CompanyNameCorporateName": { "type": "string", "description": "Razão social." }, "Login": { "type": "string", "description": "`Login` (email) do usuário." }, "UserName": { "type": "string", "description": "Nome do usuário." }, "CompanyLogoUrl": { "type": "string", "nullable": true, "description": "URL do logo da empresa." } } }, "UserCompanyInvoice": { "type": "object", "description": "Vínculo do usuário com uma empresa faturadora.", "properties": { "IDUserCompanyInvoice": { "type": "integer", "format": "int32", "description": "Identificador do vínculo." }, "IDCompany": { "type": "integer", "format": "int32", "description": "Identificador da empresa faturadora." }, "IDUser": { "type": "integer", "format": "int32", "description": "Identificador do usuário." }, "CompanyCpfCnpj": { "type": "string", "nullable": true, "description": "CPF/CNPJ da faturadora." }, "CompanyNameCorporateName": { "type": "string", "description": "Razão social da faturadora." }, "AccountName": { "type": "string", "description": "`AccountName` da faturadora." } } }, "UserMenuGroup": { "type": "object", "description": "Grupo de módulos exibido como uma seção no menu lateral.", "properties": { "IDModuleGroup": { "type": "integer", "format": "int32", "description": "Identificador do grupo." }, "ModuleGroupDescription": { "type": "string", "description": "Nome do grupo (ex.: `Financeiro`, `Estoque`)." }, "iconName": { "type": "string", "nullable": true, "description": "Ícone do grupo no menu antigo." }, "newIconName": { "type": "string", "nullable": true, "description": "Ícone do grupo no menu novo." }, "link": { "type": "string", "nullable": true, "description": "Link padrão do grupo." }, "index": { "type": "integer", "nullable": true, "description": "Ordem de exibição." }, "Module": { "type": "array", "description": "Módulos que compõem o grupo.", "items": { "$ref": "#/components/schemas/UserMenuItem" } } } }, "UserMenuItem": { "type": "object", "description": "Item de menu (módulo ou submódulo). Em `Version=2`, `Module` traz os submódulos aninhados.", "properties": { "IDUserPrivilege": { "type": "integer", "format": "int32", "description": "Identificador do privilégio que libera este item." }, "IDModule": { "type": "integer", "format": "int32", "description": "Identificador do módulo." }, "ModuleDescription": { "type": "string", "description": "Nome amigável do módulo (ex.: `Contas a Pagar`)." }, "link": { "type": "string", "nullable": true, "description": "Rota no frontend (ex.: `/accounts/payable`)." }, "icon": { "type": "string", "nullable": true, "description": "Ícone do item no menu antigo." }, "newIcon": { "type": "string", "nullable": true, "description": "Ícone do item no menu novo." }, "header": { "type": "string", "nullable": true, "description": "Título exibido no topo da tela." }, "KeyWords": { "type": "string", "nullable": true, "description": "Palavras-chave para a busca dentro do menu." }, "Module": { "type": "array", "nullable": true, "description": "Submódulos aninhados. Presente apenas em `Version=2`. Lista vazia `[]` quando não há filhos.", "items": { "type": "object", "properties": { "IDUserPrivilege": { "type": "integer", "format": "int32", "description": "Identificador do privilégio (`IDUserPrivilege`) que libera o item de menu para o usuário." }, "IDModule": { "type": "integer", "format": "int32", "description": "Identificador do módulo (`IDModule`) ao qual o item de menu pertence." }, "ModuleDescription": { "type": "string", "description": "Descrição amigável do módulo, exibida como rótulo do item no menu (ex.: `Contas a Pagar`, `Pedidos`, `SKUs`)." }, "link": { "type": "string", "nullable": true, "description": "Rota interna do frontend a que o item leva quando clicado (ex.: `/accounts/payable`). Vazio em itens que apenas agrupam submenus." }, "icon": { "type": "string", "nullable": true, "description": "Nome do ícone clássico exibido ao lado do item de menu (referência ao set de ícones do frontend)." }, "newIcon": { "type": "string", "nullable": true, "description": "Nome do ícone novo (set Phosphor/Lucide usado no redesign) exibido ao lado do item." }, "header": { "type": "string", "nullable": true, "description": "Título adicional exibido em cabeçalhos de seção do menu/breadcrumb quando o item é um agrupador." }, "KeyWords": { "type": "string", "nullable": true, "description": "Palavras-chave em português separadas por vírgula usadas pela busca global do menu para casar termos digitados pelo usuário com o item." } } } } } }, "UserPrivilegeGroup": { "type": "object", "description": "Perfil de acesso (grupo de privilégios) configurado para a empresa.", "properties": { "IDUserPrivilegeGroup": { "type": "integer", "format": "int32", "description": "Identificador do perfil." }, "PrivilegeGroupName": { "type": "string", "description": "Nome do perfil." }, "Module": { "type": "array", "description": "Módulos cobertos pelo perfil, cada um com seus privilégios.", "items": { "type": "object", "properties": { "IDModule": { "type": "integer", "format": "int32", "description": "Identificador do módulo." }, "ModuleDescription": { "type": "string", "description": "Nome do módulo." }, "Privilege": { "type": "array", "description": "Privilégios do módulo.", "items": { "type": "object", "properties": { "IDUserPrivilege": { "type": "integer", "format": "int32", "description": "Identificador do privilégio." }, "UserPrivilege": { "type": "string", "description": "Chave técnica do privilégio (ex.: `PrivilegeAccountsPayableInsert`)." }, "PrivilegeDescription": { "type": "string", "description": "Nome amigável do privilégio." } } } } } } } } }, "UserLoginPayload": { "type": "object", "description": "Payload de login reidratado. Mesmo formato do campo `body` retornado em `POST /user/signin/local`.", "properties": { "id": { "type": "integer", "description": "Identificador `IDUser`." }, "email": { "type": "string", "description": "`Login` do usuário." }, "UserName": { "type": "string", "description": "Nome do usuário." }, "Salesman": { "type": "integer", "nullable": true, "description": "`1` quando o usuário é vendedor (acessa relatórios de comissão e atua como vendedor em pedidos); `0`/`null` caso contrário." }, "RestrictAccessSalesman": { "type": "integer", "nullable": true, "description": "`1` quando o vendedor só enxerga os próprios pedidos/clientes (restrição de visão de carteira); `0`/`null` quando enxerga toda a base." }, "CompanyNameCorporateName": { "type": "string", "description": "Razão social da empresa em que o usuário está logado." }, "CompanyLogoUrl": { "type": "string", "nullable": true, "description": "URL do logotipo da empresa para exibição no cabeçalho." }, "CompanyLogoUrlMain": { "type": "string", "nullable": true, "description": "URL do logotipo da empresa-mãe quando o usuário está em uma filial (em ambientes multi-empresa). Repete `CompanyLogoUrl` quando não há empresa-mãe." }, "AccountNameMain": { "type": "string", "description": "Subdomínio da empresa-mãe (em ambientes multi-empresa). Repete o subdomínio da empresa atual quando não há empresa-mãe." }, "CompanyNameCorporateNameMain": { "type": "string", "description": "Razão social da empresa-mãe (em ambientes multi-empresa). Repete a razão social atual quando não há empresa-mãe." }, "ExternalDashboard": { "type": "string", "nullable": true, "description": "URL de dashboard externo embutido no sistema (ex.: relatórios em ferramenta de BI). Vazio quando não configurado." }, "Theme": { "type": "string", "nullable": true, "description": "Tema visual aplicado ao usuário (`light`/`dark` ou nome do tema customizado). Vazio quando usa o tema padrão." }, "UserImageUrl": { "type": "string", "nullable": true, "description": "URL da foto/avatar do usuário." }, "IDModuleFavorite": { "type": "array", "items": { "type": "string" }, "description": "Lista de IDs de módulos marcados como favoritos pelo usuário, para atalhos no menu." }, "HelpDeskToken": { "type": "string", "description": "Token JWT para autenticar o usuário no widget de help desk (Zendesk)." }, "HelpDeskChatToken": { "type": "string", "description": "Token JWT para autenticar o usuário no chat do help desk (Zendesk Chat)." }, "CompanyPaymentStatus": { "type": "integer", "nullable": true, "description": "Status financeiro da assinatura da empresa no idworks (ex.: `1` em dia, outros valores indicam inadimplência) — usado para bloquear funcionalidades quando a assinatura está em atraso." }, "Parameters": { "type": "array", "items": { "type": "object" }, "description": "Lista de parâmetros de integrações configuradas para a empresa, retornados quando o login é feito por um usuário com acesso a integrações (cada item traz a chave e o valor da parametrização da integração)." } } }, "TaxDepartmentSummary": { "type": "object", "description": "Resumo de departamento fiscal (formato da lista).", "properties": { "IDTaxDepartment": { "type": "integer", "description": "Identificador do departamento fiscal." }, "TaxDepartmentDescription": { "type": "string", "maxLength": 100, "description": "Nome do departamento fiscal." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "Situação. `1` ativo; `0` inativo." }, "AccountName": { "type": "string", "description": "Identificador da conta (subdomínio) à qual o departamento pertence." } } }, "TaxDepartmentCreateBody": { "type": "object", "required": [ "TaxDepartmentDescription" ], "properties": { "TaxDepartmentDescription": { "type": "string", "maxLength": 100, "description": "Nome do departamento fiscal. Deve ser único entre os departamentos ativos da empresa." } } }, "TaxDepartmentUpdateBody": { "type": "object", "required": [ "TaxDepartmentDescription" ], "properties": { "TaxDepartmentDescription": { "type": "string", "maxLength": 100, "description": "Novo nome do departamento fiscal. Deve permanecer único entre os departamentos ativos da empresa." } } }, "TaxDepartmentDetail": { "type": "object", "description": "Detalhe de um departamento fiscal com o array de regras fiscais (`Cfop[]`).", "properties": { "IDTaxDepartment": { "type": "integer", "description": "Identificador do departamento fiscal." }, "TaxDepartmentDescription": { "type": "string", "maxLength": 100, "description": "Nome do departamento fiscal." }, "Status": { "type": "integer", "enum": [ 0, 1 ], "description": "Situação. `1` ativo; `0` inativo." }, "AccountName": { "type": "string", "description": "Identificador da conta (subdomínio)." }, "Cfop": { "type": "array", "description": "Regras fiscais (CFOPs) cadastradas no departamento. Cada item ordenado pela flag `Standard` (regras padrão primeiro).", "items": { "$ref": "#/components/schemas/TaxCfopSummary" } } } }, "TaxCfopSummary": { "type": "object", "description": "Resumo de uma regra fiscal (CFOP) dentro do departamento (formato do array `Cfop[]` no `GET /tax/{idtaxdepartment}`).", "properties": { "IDTax": { "type": "integer", "description": "Identificador da regra fiscal." }, "IDTaxDepartment": { "type": "integer", "description": "Identificador do departamento fiscal." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa (matriz ou filial) à qual a regra pertence." }, "CompanyTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia da empresa." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social da empresa (usada na nota)." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Identificador da conta da empresa emissora." }, "TypeTaxName": { "type": "string", "nullable": true, "maxLength": 100, "description": "Apelido da regra fiscal." }, "Standard": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, indica que esta é a regra padrão da operação." }, "Gratification": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, regra de bonificação (saída sem cobrança)." }, "NfeindFinal": { "type": "integer", "enum": [ 0, 1 ], "description": "Indicador de consumidor final. `1` Consumidor Final; `0` Normal." }, "NfeindFinalDescription": { "type": "string", "description": "Descrição textual de `NfeindFinal` (`Consumidor Final` ou `Normal`)." }, "NfeTaxPayer": { "type": "integer", "enum": [ 0, 1 ], "description": "Indicador de destinatário contribuinte do ICMS." }, "NfeExport": { "type": "integer", "enum": [ 0, 1 ], "description": "Quando `1`, indica operação de importação/exportação." }, "TaxSkuCest": { "type": "string", "nullable": true, "maxLength": 15, "description": "CEST (Código Especificador da Substituição Tributária) — sobrescreve o cadastrado no SKU." }, "PisCst": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST PIS (saída)." }, "PisAliquot": { "type": "number", "nullable": true, "description": "Alíquota PIS (saída), em decimal (0–1)." }, "CofinsCst": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST COFINS (saída)." }, "CofinsAliquot": { "type": "number", "nullable": true, "description": "Alíquota COFINS (saída), em decimal (0–1)." }, "NfCstCofinsDescription": { "type": "string", "nullable": true, "description": "Descrição do CST COFINS (saída)." }, "NfCstPisDescription": { "type": "string", "nullable": true, "description": "Descrição do CST PIS (saída)." }, "PisCstInbound": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST PIS (entrada)." }, "PisAliquotInbound": { "type": "number", "nullable": true, "description": "Alíquota PIS (entrada), em decimal." }, "CofinsCstInbound": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST COFINS (entrada)." }, "CofinsAliquotInbound": { "type": "number", "nullable": true, "description": "Alíquota COFINS (entrada), em decimal." }, "NfCstCofinsInboundDescription": { "type": "string", "nullable": true, "description": "Descrição do CST COFINS (entrada)." }, "NfCstPisInboundDescription": { "type": "string", "nullable": true, "description": "Descrição do CST PIS (entrada)." }, "IpiCst": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST IPI (saída)." }, "IpiAliquot": { "type": "number", "nullable": true, "description": "Alíquota IPI (saída), em decimal." }, "IpiCEnq": { "type": "string", "nullable": true, "maxLength": 3, "description": "Enquadramento legal do IPI (saída)." }, "NfCstIpiDescription": { "type": "string", "nullable": true, "description": "Descrição do CST IPI (saída)." }, "NfIpiCEnqDescription": { "type": "string", "nullable": true, "description": "Descrição do enquadramento legal do IPI." }, "IpiCstInbound": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST IPI (entrada)." }, "IpiAliquotInbound": { "type": "number", "nullable": true, "description": "Alíquota IPI (entrada), em decimal." }, "NfCstIpiInboundDescription": { "type": "string", "nullable": true, "description": "Descrição do CST IPI (entrada)." }, "CfopOutboundInState": { "type": "integer", "nullable": true, "description": "CFOP de saída para operação dentro do estado (dígito inicial 5 ou 7)." }, "CfopOutboundInStateDescription": { "type": "string", "nullable": true, "description": "Descrição/Natureza da operação do CFOP de saída no estado." }, "CfopOutboundOutState": { "type": "integer", "nullable": true, "description": "CFOP de saída para operação fora do estado (dígito inicial 6)." }, "CfopOutboundOutStateDescription": { "type": "string", "nullable": true, "description": "Descrição/Natureza da operação do CFOP de saída fora do estado." }, "CfopInboundInState": { "type": "integer", "nullable": true, "description": "CFOP de entrada para operação dentro do estado (dígito inicial 1 ou 3)." }, "CfopInboundInStateDescription": { "type": "string", "nullable": true, "description": "Descrição/Natureza da operação do CFOP de entrada no estado." }, "CfopInboundOutState": { "type": "integer", "nullable": true, "description": "CFOP de entrada para operação fora do estado (dígito inicial 2)." }, "CfopInboundOutStateDescription": { "type": "string", "nullable": true, "description": "Descrição/Natureza da operação do CFOP de entrada fora do estado." } } }, "TaxCfopDetail": { "type": "object", "description": "Detalhe completo de uma regra fiscal (CFOP) com as regras ICMS por estado (`Icms[]`).", "properties": { "IDCompany": { "type": "integer", "description": "Identificador da empresa (matriz ou filial) à qual a regra pertence." }, "CompanyTradeName": { "type": "string", "nullable": true, "description": "Nome fantasia da empresa." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social da empresa (usada na nota)." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Identificador da conta da empresa emissora." }, "CompanyAddressStateInvoice": { "type": "string", "nullable": true, "maxLength": 2, "description": "UF da empresa emissora (usada para identificar operações no estado x fora do estado)." }, "IDTax": { "type": "integer", "description": "Identificador da regra fiscal." }, "IDTaxDepartment": { "type": "integer", "description": "Identificador do departamento fiscal." }, "TypeTaxName": { "type": "string", "nullable": true, "maxLength": 100, "description": "Apelido da regra fiscal." }, "Standard": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando é a regra padrão da operação." }, "Gratification": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando regra de bonificação." }, "NfeindFinal": { "type": "integer", "enum": [ 0, 1 ], "description": "Indicador de consumidor final." }, "NfeTaxPayer": { "type": "integer", "enum": [ 0, 1 ], "description": "Indicador de destinatário contribuinte do ICMS." }, "NfeExport": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando operação de importação/exportação." }, "ReverseTaxCalculation": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando aplica cálculo reverso (impostos por dentro do valor total)." }, "IssueNFCe": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` quando a regra emite NFCe modelo 65 em vez de NF-e modelo 55." }, "IIAliquot": { "type": "number", "nullable": true, "description": "Alíquota de Imposto de Importação, em decimal — relevante quando `NfeExport=1`." }, "TaxSkuCest": { "type": "string", "nullable": true, "maxLength": 15, "description": "CEST que sobrescreve o cadastrado no SKU." }, "PisCst": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST PIS (saída)." }, "PisAliquot": { "type": "number", "nullable": true, "description": "Alíquota PIS (saída), em decimal." }, "NfCstPisDescription": { "type": "string", "nullable": true, "description": "Descrição do CST PIS (saída)." }, "CofinsCst": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST COFINS (saída)." }, "CofinsAliquot": { "type": "number", "nullable": true, "description": "Alíquota COFINS (saída), em decimal." }, "NfCstCofinsDescription": { "type": "string", "nullable": true, "description": "Descrição do CST COFINS (saída)." }, "PisCstInbound": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST PIS (entrada)." }, "PisAliquotInbound": { "type": "number", "nullable": true, "description": "Alíquota PIS (entrada), em decimal." }, "NfCstPisInboundDescription": { "type": "string", "nullable": true, "description": "Descrição do CST PIS (entrada)." }, "CofinsCstInbound": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST COFINS (entrada)." }, "CofinsAliquotInbound": { "type": "number", "nullable": true, "description": "Alíquota COFINS (entrada), em decimal." }, "NfCstCofinsInboundDescription": { "type": "string", "nullable": true, "description": "Descrição do CST COFINS (entrada)." }, "IpiCst": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST IPI (saída)." }, "IpiAliquot": { "type": "number", "nullable": true, "description": "Alíquota IPI (saída), em decimal." }, "NfCstIpiDescription": { "type": "string", "nullable": true, "description": "Descrição do CST IPI (saída)." }, "IpiCEnq": { "type": "string", "nullable": true, "maxLength": 3, "description": "Enquadramento legal do IPI." }, "NfIpiCEnqDescription": { "type": "string", "nullable": true, "description": "Descrição do enquadramento legal do IPI." }, "IpiCstInbound": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST IPI (entrada)." }, "IpiAliquotInbound": { "type": "number", "nullable": true, "description": "Alíquota IPI (entrada), em decimal." }, "NfCstIpiInboundDescription": { "type": "string", "nullable": true, "description": "Descrição do CST IPI (entrada)." }, "IDNfCstIbsCbs": { "type": "integer", "nullable": true, "description": "Identificador da classificação tributária IBS/CBS." }, "NfCstIbsCbsDescription": { "type": "string", "nullable": true, "description": "Descrição da classificação IBS/CBS (`cClassTrib - cClassTribName`)." }, "CfopOutboundInState": { "type": "integer", "nullable": true, "description": "CFOP de saída dentro do estado." }, "CfopOutboundInStateDescription": { "type": "string", "nullable": true, "description": "Descrição/Natureza do CFOP de saída no estado." }, "CfopOutboundInStateNfeNatureOperation": { "type": "string", "nullable": true, "maxLength": 60, "description": "Natureza de operação customizada para o CFOP de saída no estado (quando preenchida, substitui a descrição padrão na nota)." }, "CfopOutboundOutState": { "type": "integer", "nullable": true, "description": "CFOP de saída fora do estado." }, "CfopOutboundOutStateDescription": { "type": "string", "nullable": true, "description": "Descrição/Natureza do CFOP de saída fora do estado." }, "CfopOutboundOutStateNfeNatureOperation": { "type": "string", "nullable": true, "maxLength": 60, "description": "Natureza de operação customizada para o CFOP de saída fora do estado." }, "CfopInboundInState": { "type": "integer", "nullable": true, "description": "CFOP de entrada dentro do estado." }, "CfopInboundInStateDescription": { "type": "string", "nullable": true, "description": "Descrição/Natureza do CFOP de entrada no estado." }, "CfopInboundInStateNfeNatureOperation": { "type": "string", "nullable": true, "maxLength": 60, "description": "Natureza de operação customizada para o CFOP de entrada no estado." }, "CfopInboundOutState": { "type": "integer", "nullable": true, "description": "CFOP de entrada fora do estado." }, "CfopInboundOutStateDescription": { "type": "string", "nullable": true, "description": "Descrição/Natureza do CFOP de entrada fora do estado." }, "CfopInboundOutStateNfeNatureOperation": { "type": "string", "nullable": true, "maxLength": 60, "description": "Natureza de operação customizada para o CFOP de entrada fora do estado." }, "Icms": { "type": "array", "description": "Regras ICMS por estado destino vinculadas a esta regra fiscal. Ordenadas por nome do estado.", "items": { "$ref": "#/components/schemas/TaxInterstate" } } } }, "TaxCfopCreateBody": { "type": "object", "required": [ "IDCompanyBranch", "PisCst", "CofinsCst", "Standard", "NfeindFinal", "TypeTaxName" ], "properties": { "IDCompanyBranch": { "type": "integer", "description": "Identificador da empresa (matriz ou filial) a que esta regra fiscal se aplica." }, "TypeTaxName": { "type": "string", "nullable": true, "maxLength": 100, "description": "Apelido da regra fiscal." }, "Standard": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` para marcar como regra padrão da operação (impede duplicidade de padrão por estado destino dentro do mesmo departamento)." }, "NfeindFinal": { "type": "integer", "enum": [ 0, 1 ], "description": "Indicador de consumidor final. `1` Consumidor Final; `0` Normal." }, "NfeTaxPayer": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "Indicador de destinatário contribuinte do ICMS." }, "Gratification": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "`1` para operação de bonificação." }, "NfeExport": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "`1` para operação de importação/exportação." }, "ReverseTaxCalculation": { "type": "integer", "enum": [ 0, 1 ], "default": 1, "description": "`1` aplica cálculo reverso (impostos por dentro do valor total)." }, "IssueNFCe": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "`1` emite NFCe modelo 65 em vez de NF-e modelo 55." }, "PisCst": { "type": "string", "maxLength": 2, "description": "CST PIS (saída). Obrigatório." }, "PisAliquot": { "type": "number", "nullable": true, "description": "Alíquota PIS (saída), em decimal (0–0,5). Valores acima de 0,5 (50%) são bloqueados." }, "CofinsCst": { "type": "string", "maxLength": 2, "description": "CST COFINS (saída). Obrigatório." }, "CofinsAliquot": { "type": "number", "nullable": true, "description": "Alíquota COFINS (saída), em decimal (0–0,5)." }, "PisCstInbound": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST PIS (entrada)." }, "PisAliquotInbound": { "type": "number", "nullable": true, "description": "Alíquota PIS (entrada), em decimal." }, "CofinsCstInbound": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST COFINS (entrada)." }, "CofinsAliquotInbound": { "type": "number", "nullable": true, "description": "Alíquota COFINS (entrada), em decimal." }, "IpiCst": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST IPI (saída). Quando informado, exige enquadramento `IpiCEnq` válido para o CST." }, "IpiAliquot": { "type": "number", "nullable": true, "description": "Alíquota IPI (saída), em decimal. Ignorado quando `IpiCst` está em branco." }, "IpiCEnq": { "type": "string", "nullable": true, "maxLength": 3, "description": "Enquadramento legal do IPI. Faixas: CSTs `02/52` exigem 300–399; `04/54` exigem 0–99; `05/55` exigem 100–199." }, "IpiCstInbound": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST IPI (entrada)." }, "IpiAliquotInbound": { "type": "number", "nullable": true, "description": "Alíquota IPI (entrada), em decimal." }, "IDNfCstIbsCbs": { "type": "integer", "nullable": true, "description": "Identificador da classificação tributária IBS/CBS. Quando informado, é validado contra o cadastro." }, "CfopOutboundInState": { "type": "integer", "nullable": true, "description": "CFOP de saída dentro do estado. Deve começar com 5 ou 7 e existir no cadastro." }, "CfopOutboundInStateNfeNatureOperation": { "type": "string", "nullable": true, "maxLength": 60, "description": "Natureza de operação customizada (sobrescreve a descrição padrão do CFOP na nota)." }, "CfopOutboundOutState": { "type": "integer", "nullable": true, "description": "CFOP de saída fora do estado. Deve começar com 6." }, "CfopOutboundOutStateNfeNatureOperation": { "type": "string", "nullable": true, "maxLength": 60, "description": "Natureza de operação customizada." }, "CfopInboundInState": { "type": "integer", "nullable": true, "description": "CFOP de entrada dentro do estado. Deve começar com 1 ou 3." }, "CfopInboundInStateNfeNatureOperation": { "type": "string", "nullable": true, "maxLength": 60, "description": "Natureza de operação customizada." }, "CfopInboundOutState": { "type": "integer", "nullable": true, "description": "CFOP de entrada fora do estado. Deve começar com 2." }, "CfopInboundOutStateNfeNatureOperation": { "type": "string", "nullable": true, "maxLength": 60, "description": "Natureza de operação customizada." }, "IIAliquot": { "type": "number", "nullable": true, "description": "Alíquota de Imposto de Importação, em decimal — relevante quando `NfeExport=1`." }, "TaxSkuCest": { "type": "string", "nullable": true, "maxLength": 15, "description": "CEST que sobrescreve o cadastrado no SKU." } } }, "TaxCfopUpdateBody": { "type": "object", "description": "Atualização parcial — campos não enviados ficam inalterados. Strings vazias em `PisCstInbound` e `CofinsCstInbound` são interpretadas como remoção do CST de entrada.", "properties": { "IDCompanyBranch": { "type": "integer", "description": "Identificador da empresa (matriz ou filial) a que esta regra fiscal se aplica." }, "TypeTaxName": { "type": "string", "maxLength": 100, "description": "Apelido da regra fiscal." }, "Standard": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` marca como regra padrão da operação." }, "NfeindFinal": { "type": "integer", "enum": [ 0, 1 ], "description": "Indicador de consumidor final." }, "NfeTaxPayer": { "type": "integer", "enum": [ 0, 1 ], "description": "Indicador de destinatário contribuinte do ICMS." }, "Gratification": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` para operação de bonificação." }, "NfeExport": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` para operação de importação/exportação." }, "ReverseTaxCalculation": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` aplica cálculo reverso." }, "IssueNFCe": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` emite NFCe modelo 65." }, "PisCst": { "type": "string", "maxLength": 2, "description": "CST PIS (saída)." }, "PisAliquot": { "type": "number", "nullable": true, "description": "Alíquota PIS (saída), em decimal (0–0,5)." }, "CofinsCst": { "type": "string", "maxLength": 2, "description": "CST COFINS (saída)." }, "CofinsAliquot": { "type": "number", "nullable": true, "description": "Alíquota COFINS (saída), em decimal (0–0,5)." }, "PisCstInbound": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST PIS (entrada). String vazia remove o valor (`null`)." }, "PisAliquotInbound": { "type": "number", "nullable": true, "description": "Alíquota PIS (entrada), em decimal." }, "CofinsCstInbound": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST COFINS (entrada). String vazia remove o valor (`null`)." }, "CofinsAliquotInbound": { "type": "number", "nullable": true, "description": "Alíquota COFINS (entrada), em decimal." }, "IpiCst": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST IPI (saída). Quando informado, exige `IpiCEnq` na faixa correspondente." }, "IpiAliquot": { "type": "number", "nullable": true, "description": "Alíquota IPI (saída), em decimal." }, "IpiCEnq": { "type": "string", "nullable": true, "maxLength": 3, "description": "Enquadramento legal do IPI. Faixas válidas por CST IPI." }, "IpiCstInbound": { "type": "string", "nullable": true, "maxLength": 2, "description": "CST IPI (entrada)." }, "IpiAliquotInbound": { "type": "number", "nullable": true, "description": "Alíquota IPI (entrada), em decimal." }, "IDNfCstIbsCbs": { "type": "integer", "nullable": true, "description": "Identificador da classificação tributária IBS/CBS." }, "CfopOutboundInState": { "type": "integer", "nullable": true, "description": "CFOP de saída dentro do estado." }, "CfopOutboundInStateNfeNatureOperation": { "type": "string", "nullable": true, "maxLength": 60, "description": "Natureza de operação customizada para o CFOP de saída no estado." }, "CfopOutboundOutState": { "type": "integer", "nullable": true, "description": "CFOP de saída fora do estado." }, "CfopOutboundOutStateNfeNatureOperation": { "type": "string", "nullable": true, "maxLength": 60, "description": "Natureza de operação customizada para o CFOP de saída fora do estado." }, "CfopInboundInState": { "type": "integer", "nullable": true, "description": "CFOP de entrada dentro do estado." }, "CfopInboundInStateNfeNatureOperation": { "type": "string", "nullable": true, "maxLength": 60, "description": "Natureza de operação customizada para o CFOP de entrada no estado." }, "CfopInboundOutState": { "type": "integer", "nullable": true, "description": "CFOP de entrada fora do estado." }, "CfopInboundOutStateNfeNatureOperation": { "type": "string", "nullable": true, "maxLength": 60, "description": "Natureza de operação customizada para o CFOP de entrada fora do estado." }, "IIAliquot": { "type": "number", "nullable": true, "description": "Alíquota de Imposto de Importação, em decimal." }, "TaxSkuCest": { "type": "string", "nullable": true, "maxLength": 15, "description": "CEST que sobrescreve o cadastrado no SKU." } } }, "TaxInterstate": { "type": "object", "description": "Regra ICMS por estado destino vinculada a uma regra fiscal (CFOP).", "properties": { "IDStockKeepingUnitIcmsTaxInterstate": { "type": "integer", "description": "Identificador da regra ICMS por estado." }, "StateTo": { "type": "string", "maxLength": 2, "description": "UF de destino (sigla — `SP`, `RJ`, etc.)." }, "StateName": { "type": "string", "nullable": true, "description": "Nome do estado destino." }, "IcmsCst": { "type": "string", "maxLength": 3, "description": "CST ICMS — controla quais demais campos da regra são exigidos/ignorados." }, "CstDescription": { "type": "string", "nullable": true, "description": "Descrição do CST ICMS." }, "IcmsModBC": { "type": "integer", "nullable": true, "description": "Modalidade de base de cálculo do ICMS (`0` Margem Valor Agregado; `1` Pauta; `2` Preço Tabelado; `3` Valor da operação)." }, "IcmsModBCDescription": { "type": "string", "nullable": true, "description": "Descrição da modalidade da base de cálculo." }, "IcmsAliquot": { "type": "number", "nullable": true, "description": "Alíquota ICMS, em decimal (0–1)." }, "IcmsPRedBC": { "type": "number", "nullable": true, "description": "Percentual de redução da base de cálculo do ICMS, em decimal." }, "IcmsDifalPRedBC": { "type": "number", "nullable": true, "description": "Percentual de redução da base do ICMS DIFAL, em decimal." }, "FecpAliquot": { "type": "number", "nullable": true, "description": "Alíquota do Fundo de Combate à Pobreza (FCP), em decimal." }, "IcmsModBCST": { "type": "integer", "nullable": true, "description": "Modalidade de base do ICMS ST (`0`–`6`)." }, "IcmsModBCSTDescription": { "type": "string", "nullable": true, "description": "Descrição da modalidade da base do ICMS ST." }, "IcmsPMVAST": { "type": "number", "nullable": true, "description": "MVA — Margem de Valor Agregado para produto nacional (origens fiscais 0/4/5/6/7), em decimal." }, "IcmsPMVASTSimples": { "type": "number", "nullable": true, "description": "MVA para produto nacional quando o cliente é do Simples Nacional, em decimal." }, "IcmsPMVASTMadeOutBrazil": { "type": "number", "nullable": true, "description": "MVA para produto importado (origens fiscais 1/2/3/8), em decimal." }, "IcmsPMVASTSimplesMadeOutBrazil": { "type": "number", "nullable": true, "description": "MVA para produto importado quando o cliente é do Simples Nacional, em decimal." }, "IcmsPRedBCST": { "type": "number", "nullable": true, "description": "Percentual de redução da base do ICMS ST, em decimal." }, "IcmsSTAliquot": { "type": "number", "nullable": true, "description": "Alíquota interna do ICMS ST, em decimal. Vazio usa a `IcmsAliquot`." }, "IcmsStBaseCalMethod": { "type": "integer", "enum": [ 1, 2 ], "description": "Método da base do ICMS ST: `1` Base Simples; `2` Base D. Conv. 06/2009." }, "IcmsStDifalBaseCalMethod": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Método da base do DIFAL ST: `1` Base Simples; `2` Base D. Conv. 148/2018; `3` Base D. Leg. Interna." }, "MethodOutside": { "type": "integer", "enum": [ 0, 1 ], "description": "Método de cálculo do ICMS. `1` Por Fora; `0` Por Dentro." }, "MethodOutsideDescription": { "type": "string", "nullable": true, "description": "Descrição textual de `MethodOutside`." }, "MethodOutsideDifal": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Método de cálculo do DIFAL. `1` Por Fora; `0` Por Dentro." }, "MethodOutsideDifalDescription": { "type": "string", "nullable": true, "description": "Descrição textual de `MethodOutsideDifal`." }, "IcmscBenef": { "type": "string", "nullable": true, "maxLength": 45, "description": "Código de benefício fiscal do estado destino." }, "IcmsPDif": { "type": "number", "nullable": true, "description": "Percentual de diferimento do ICMS, em decimal." }, "FecpPDif": { "type": "number", "nullable": true, "description": "Percentual de diferimento do FCP, em decimal." }, "CfopOutbound": { "type": "integer", "nullable": true, "description": "CFOP de saída específico deste estado — sobrescreve o do CFOP-pai." }, "CfopInbound": { "type": "integer", "nullable": true, "description": "CFOP de entrada específico deste estado — sobrescreve o do CFOP-pai." }, "ItemCommentsInvoice": { "type": "string", "nullable": true, "maxLength": 500, "description": "Texto livre adicionado à tag `infoAdProd` do XML para este estado destino." } } }, "TaxInterstateCreateBody": { "type": "object", "required": [ "IcmsCst", "StateTo" ], "properties": { "StateTo": { "type": "string", "maxLength": 2, "description": "UF de destino. Obrigatório. Não pode coincidir com outra regra já cadastrada para o mesmo CFOP." }, "IcmsCst": { "type": "string", "maxLength": 3, "description": "CST ICMS. Define quais demais campos são obrigatórios. Validado contra `NfCstIcms` segundo o regime tributário da empresa." }, "IcmsModBC": { "type": "integer", "nullable": true, "default": 3, "description": "Modalidade de base de cálculo do ICMS. Padrão `3` (Valor da operação). Aceita `0`–`3`." }, "IcmsAliquot": { "type": "number", "nullable": true, "description": "Alíquota ICMS, em decimal (0–1)." }, "IcmsPRedBC": { "type": "number", "nullable": true, "description": "Percentual de redução da BC do ICMS, em decimal. Para CSTs `20` e `70`, deve ser maior que zero." }, "IcmsDifalPRedBC": { "type": "number", "nullable": true, "default": 0, "description": "Percentual de redução da BC do ICMS DIFAL, em decimal (0–1)." }, "FecpAliquot": { "type": "number", "nullable": true, "description": "Alíquota FCP, em decimal (0–1). `null` é tratado como `0`." }, "IcmsModBCST": { "type": "integer", "nullable": true, "description": "Modalidade de base do ICMS ST (`0`–`6`). Obrigatória nos CSTs com ST." }, "IcmsPMVAST": { "type": "number", "nullable": true, "description": "MVA — produto nacional, em decimal." }, "IcmsPMVASTSimples": { "type": "number", "nullable": true, "description": "MVA — produto nacional, cliente do Simples, em decimal." }, "IcmsPMVASTMadeOutBrazil": { "type": "number", "nullable": true, "description": "MVA — produto importado, em decimal." }, "IcmsPMVASTSimplesMadeOutBrazil": { "type": "number", "nullable": true, "description": "MVA — produto importado, cliente do Simples, em decimal." }, "IcmsPRedBCST": { "type": "number", "nullable": true, "description": "Percentual de redução da BC do ICMS ST, em decimal." }, "IcmsSTAliquot": { "type": "number", "nullable": true, "description": "Alíquota interna do ICMS ST, em decimal. Vazio assume a `IcmsAliquot`." }, "IcmsStBaseCalMethod": { "type": "integer", "enum": [ 1, 2 ], "default": 1, "description": "Método da base do ICMS ST. `1` (default) Base Simples; `2` Base D. Conv. 06/2009." }, "IcmsStDifalBaseCalMethod": { "type": "integer", "enum": [ 1, 2, 3 ], "default": 1, "description": "Método da base do DIFAL ST. `1` (default) Base Simples; `2` Conv. 148/2018; `3` D. Leg. Interna." }, "MethodOutside": { "type": "integer", "enum": [ 0, 1 ], "default": 1, "description": "`1` (default) cálculo Por Fora; `0` Por Dentro." }, "MethodOutsideDifal": { "type": "integer", "enum": [ 0, 1 ], "default": 1, "description": "`1` (default) DIFAL Por Fora; `0` Por Dentro." }, "IcmscBenef": { "type": "string", "nullable": true, "maxLength": 45, "description": "Código de benefício fiscal do estado destino." }, "IcmsPDif": { "type": "number", "nullable": true, "description": "Percentual de diferimento do ICMS, em decimal." }, "FecpPDif": { "type": "number", "nullable": true, "description": "Percentual de diferimento do FCP, em decimal." }, "CfopOutbound": { "type": "integer", "nullable": true, "description": "CFOP de saída específico deste estado (override do CFOP-pai)." }, "CfopInbound": { "type": "integer", "nullable": true, "description": "CFOP de entrada específico deste estado (override do CFOP-pai)." }, "ItemCommentsInvoice": { "type": "string", "nullable": true, "maxLength": 500, "description": "Texto livre adicionado à tag `infoAdProd` do XML para este estado destino." } } }, "TaxInterstateUpdateBody": { "type": "object", "description": "Atualização parcial — campos não enviados mantêm o valor anterior. As validações por CST do `POST` continuam aplicáveis quando os campos relevantes são enviados.", "properties": { "StateTo": { "type": "string", "maxLength": 2, "description": "UF de destino. Quando alterada, o sistema valida novamente duplicidade entre regras do mesmo CFOP e (quando o CFOP é `Standard=1`) contra outras regras padrão do mesmo departamento." }, "IcmsCst": { "type": "string", "maxLength": 3, "description": "CST ICMS." }, "IcmsModBC": { "type": "integer", "nullable": true, "description": "Modalidade de base de cálculo do ICMS (`0`–`3`)." }, "IcmsAliquot": { "type": "number", "nullable": true, "description": "Alíquota ICMS, em decimal." }, "IcmsPRedBC": { "type": "number", "nullable": true, "description": "Percentual de redução da BC do ICMS, em decimal." }, "IcmsDifalPRedBC": { "type": "number", "nullable": true, "description": "Percentual de redução da BC do DIFAL, em decimal." }, "FecpAliquot": { "type": "number", "nullable": true, "description": "Alíquota FCP, em decimal." }, "IcmsModBCST": { "type": "integer", "nullable": true, "description": "Modalidade de base do ICMS ST." }, "IcmsPMVAST": { "type": "number", "nullable": true, "description": "MVA — produto nacional, em decimal." }, "IcmsPMVASTSimples": { "type": "number", "nullable": true, "description": "MVA — produto nacional, cliente do Simples, em decimal." }, "IcmsPMVASTMadeOutBrazil": { "type": "number", "nullable": true, "description": "MVA — produto importado, em decimal." }, "IcmsPMVASTSimplesMadeOutBrazil": { "type": "number", "nullable": true, "description": "MVA — produto importado, cliente do Simples, em decimal." }, "IcmsPRedBCST": { "type": "number", "nullable": true, "description": "Percentual de redução da BC do ICMS ST, em decimal." }, "IcmsSTAliquot": { "type": "number", "nullable": true, "description": "Alíquota interna do ICMS ST, em decimal." }, "IcmsStBaseCalMethod": { "type": "integer", "enum": [ 1, 2 ], "description": "Método da base do ICMS ST." }, "IcmsStDifalBaseCalMethod": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Método da base do DIFAL ST." }, "MethodOutside": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` Por Fora; `0` Por Dentro." }, "MethodOutsideDifal": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` DIFAL Por Fora; `0` Por Dentro." }, "IcmscBenef": { "type": "string", "nullable": true, "maxLength": 45, "description": "Código de benefício fiscal." }, "IcmsPDif": { "type": "number", "nullable": true, "description": "Percentual de diferimento do ICMS, em decimal." }, "FecpPDif": { "type": "number", "nullable": true, "description": "Percentual de diferimento do FCP, em decimal." }, "CfopOutbound": { "type": "integer", "nullable": true, "description": "CFOP de saída específico deste estado (override)." }, "CfopInbound": { "type": "integer", "nullable": true, "description": "CFOP de entrada específico deste estado (override)." }, "ItemCommentsInvoice": { "type": "string", "nullable": true, "maxLength": 500, "description": "Texto livre adicionado à tag `infoAdProd` do XML." } } }, "InvoiceServiceDetail": { "type": "object", "description": "Detalhe completo de uma NFS-e (`ServiceOrder`).", "properties": { "IDServiceOrder": { "type": "integer", "description": "Identificador da NFS-e." }, "AccountName": { "type": "string", "description": "Identificador da conta (subdomínio) emissora." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de criação do registro." }, "IDCompany": { "type": "integer", "description": "Empresa emissora." }, "CityCode": { "type": "integer", "description": "Código IBGE do município emissor." }, "CityName": { "type": "string", "description": "Nome do município emissor." }, "State": { "type": "string", "maxLength": 2, "description": "UF do município emissor." }, "IDConsumer": { "type": "integer", "description": "Cliente tomador do serviço." }, "ConsumerNameCorporateName": { "type": "string", "nullable": true, "maxLength": 200, "description": "Nome/razão social do tomador (snapshot no momento da emissão)." }, "ConsumerCpfCnpj": { "type": "string", "nullable": true, "maxLength": 14, "description": "CPF/CNPJ do tomador (snapshot)." }, "ConsumerEmail": { "type": "string", "nullable": true, "maxLength": 200, "description": "E-mail do tomador (snapshot)." }, "ConsumerTelephone": { "type": "string", "nullable": true, "maxLength": 15, "description": "Telefone do tomador (snapshot)." }, "IDAddress": { "type": "integer", "nullable": true, "description": "Endereço do tomador escolhido para a nota." }, "ShippingStreet": { "type": "string", "nullable": true, "maxLength": 100, "description": "Logradouro do tomador (snapshot)." }, "ShippingNumber": { "type": "string", "nullable": true, "maxLength": 80, "description": "Número do endereço (snapshot)." }, "ShippingComplement": { "type": "string", "nullable": true, "maxLength": 200, "description": "Complemento (snapshot)." }, "ShippingNeighborhood": { "type": "string", "nullable": true, "maxLength": 100, "description": "Bairro (snapshot)." }, "ShippingCity": { "type": "string", "nullable": true, "maxLength": 100, "description": "Cidade (snapshot)." }, "ShippingState": { "type": "string", "nullable": true, "maxLength": 2, "description": "UF (snapshot)." }, "ShippingPostalCode": { "type": "string", "nullable": true, "maxLength": 8, "description": "CEP (snapshot)." }, "ShippingReceiverName": { "type": "string", "nullable": true, "maxLength": 100, "description": "Nome de quem recebe (snapshot)." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Empresa faturadora (quando diferente da emissora)." }, "AccountNameInvoice": { "type": "string", "nullable": true, "description": "Identificador da conta da faturadora." }, "CompanyNameCorporateNameInvoice": { "type": "string", "nullable": true, "description": "Razão social da faturadora." }, "NfsComments": { "type": "string", "nullable": true, "maxLength": 2000, "description": "Observações que vão para a nota." }, "NfsDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de emissão (preenchida quando a NFS-e é emitida)." }, "NfsServiceCode": { "type": "string", "nullable": true, "maxLength": 45, "description": "Código de serviço municipal." }, "ServiceDescription": { "type": "string", "nullable": true, "description": "Descrição do código de serviço." }, "NfsServiceQuantity": { "type": "integer", "nullable": true, "description": "Quantidade do serviço. Default `1`." }, "NfsServiceUnitValue": { "type": "number", "nullable": true, "description": "Valor unitário do serviço." }, "NfsValue": { "type": "number", "nullable": true, "description": "Valor total do serviço (`NfsServiceQuantity * NfsServiceUnitValue`)." }, "NfsIRRFRetentionValue": { "type": "number", "nullable": true, "description": "Valor de retenção de IRRF." }, "NfsPISRetentionValue": { "type": "number", "nullable": true, "description": "Valor de retenção de PIS." }, "NfsCOFINSRetentionValue": { "type": "number", "nullable": true, "description": "Valor de retenção de COFINS." }, "NfsCSLLRetentionValue": { "type": "number", "nullable": true, "description": "Valor de retenção de CSLL." }, "NfsISSAliquot": { "type": "number", "nullable": true, "description": "Alíquota do ISS." }, "ReceiptNumber": { "type": "string", "nullable": true, "maxLength": 45, "description": "Número do recibo provisório (RPS)." }, "RpsNumber": { "type": "integer", "nullable": true, "description": "Número do RPS." }, "NfsNumber": { "type": "integer", "nullable": true, "description": "Número definitivo da NFS-e emitida." }, "NfsVerificationCode": { "type": "string", "nullable": true, "maxLength": 45, "description": "Código de verificação devolvido pela prefeitura." }, "NfsCancelDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de cancelamento." }, "NfsCancelDescription": { "type": "string", "nullable": true, "maxLength": 200, "description": "Motivo do cancelamento." }, "NfsChaveAcesso": { "type": "string", "nullable": true, "maxLength": 60, "description": "Chave de acesso da NFS-e nacional (Ambiente Nacional)." }, "CompanyCityInscription": { "type": "string", "nullable": true, "maxLength": 45, "description": "Inscrição municipal da empresa emissora (snapshot)." }, "IDStatusInvoice": { "type": "integer", "description": "Status da NF: `0` Pendente, `1` Erro, `2` Enviada, `3` Emitida, `4` Processando, `5` Pendente Conciliação EPEC, `6` Erro Conciliação EPEC, `7` Cancelada, `8` Denegada, `9` Inutilizada." }, "StatusInvoice": { "type": "string", "description": "Descrição do status." }, "NfsNBS": { "type": "string", "nullable": true, "description": "Código NBS (Nomenclatura Brasileira de Serviços), formatado em `9.9999.99.99`." }, "NfsNBSDescription": { "type": "string", "nullable": true, "description": "Descrição do NBS." }, "NfsCClassTrib": { "type": "string", "nullable": true, "maxLength": 45, "description": "Código de classificação tributária (Reforma Tributária)." }, "NfsCClassTribName": { "type": "string", "nullable": true, "description": "Nome da classificação tributária." }, "NfsCClassTribDescription": { "type": "string", "nullable": true, "description": "Descrição da classificação tributária." }, "NfsCstIbsCbs": { "type": "string", "nullable": true, "description": "CST IBS/CBS associado à classificação." }, "NfsCstIbsCbsDescription": { "type": "string", "nullable": true, "description": "Descrição do CST IBS/CBS." }, "NfsPRedIBS": { "type": "number", "nullable": true, "description": "Percentual de redução de IBS." }, "NfsPRedCBS": { "type": "number", "nullable": true, "description": "Percentual de redução de CBS." }, "NfsCIndOp": { "type": "string", "nullable": true, "maxLength": 45, "description": "Código indicador de operação (NFS-e nacional)." }, "NfsCIndOpIBSLocation": { "type": "string", "nullable": true, "description": "Local de tributação do IBS associado ao indicador de operação." }, "NfsIndFinal": { "type": "integer", "nullable": true, "enum": [ 0, 1 ], "description": "Indicador de consumidor final. `1` consumidor final, `0` não." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Pedido (`Orders`) vinculado à NFS-e, quando houver." }, "ValuePaid": { "type": "number", "nullable": true, "description": "Soma das contas a receber vinculadas à NFS-e." }, "UrlFileXml": { "type": "string", "nullable": true, "description": "URL assinada para baixar o XML da NFS-e." }, "UrlFileDanfe": { "type": "string", "nullable": true, "description": "URL assinada para baixar a DANFSE em PDF." }, "Events": { "type": "array", "description": "Histórico de eventos da NFS-e (`ServiceOrderLog`), em ordem decrescente.", "items": { "type": "object", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data do evento." }, "Comments": { "type": "string", "nullable": true, "description": "Comentário/corpo do evento." }, "Event": { "type": "string", "description": "Descrição do tipo de evento." }, "RecordUserCreated": { "type": "string", "description": "Login do usuário responsável." }, "Status": { "type": "string", "description": "Cor/cabeçalho do evento (`HeaderMessage`)." } } } }, "Payments": { "type": "array", "description": "Contas a receber vinculadas à NFS-e (`AccountsPayableReceivable` com `IDTypeAccount=0`).", "items": { "type": "object", "properties": { "IDAccountPayableReceivable": { "type": "integer", "description": "Identificador da conta a receber." }, "PaymentDescription": { "type": "string", "description": "Descrição do tipo de pagamento." }, "Category": { "type": "integer", "description": "Categoria do tipo de pagamento." }, "Installment": { "type": "integer", "description": "Número desta parcela." }, "InstallmentTotal": { "type": "integer", "description": "Total de parcelas." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento." }, "Value": { "type": "number", "description": "Valor da parcela." }, "TID": { "type": "string", "nullable": true, "description": "Identificador de transação." }, "NSU": { "type": "string", "nullable": true, "description": "Número Sequencial Único." }, "IDTypePayment": { "type": "integer", "description": "Tipo de pagamento." }, "IDConsumer": { "type": "integer", "nullable": true, "description": "Cliente da conta." }, "IDTypeAccountPayableReceivable": { "type": "integer", "description": "Plano de contas." }, "TypeAccountPaybleDescription": { "type": "string", "nullable": true, "description": "Descrição do plano de contas." }, "IDTypeDocument": { "type": "integer", "description": "Tipo do documento." }, "IDStatusAccountPayableReceivable": { "type": "integer", "description": "Status da conta a receber.", "enum": [ 0, 1, 2, 3, 4, 5, 6 ] }, "IDBankAccountForecast": { "type": "integer", "nullable": true, "description": "Banco previsto." }, "Bank": { "type": "string", "nullable": true, "description": "Nome do banco." }, "BankSlipBarCode": { "type": "string", "nullable": true, "description": "Código de barras do boleto, quando o pagamento é via boleto." }, "BankSlipUrl": { "type": "string", "nullable": true, "description": "URL do boleto, quando aplicável." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração de cobrança vinculada." }, "CompanyIntegration": { "type": "string", "nullable": true, "description": "Nome completo da integração (` - `)." }, "DaysDue": { "type": "integer", "nullable": true, "description": "Dias até o vencimento contados a partir da emissão." } } } } } }, "InvoiceServiceUpdateBody": { "type": "object", "description": "Atualização parcial de uma NFS-e em status Pendente/Erro. Todos os campos são opcionais — campos omitidos não são alterados.", "properties": { "IDConsumer": { "type": "integer", "nullable": true, "description": "Cliente tomador. Quando alterado, os campos snapshot do cliente (nome, CPF/CNPJ, e-mail, telefone) são reescritos a partir do cadastro." }, "IDAddress": { "type": "integer", "nullable": true, "description": "Endereço do cliente escolhido para a nota. Quando alterado, os campos snapshot do endereço (rua, número, complemento, bairro, cidade, UF, CEP, recebedor) são reescritos." }, "IDCompanyInvoice": { "type": "integer", "description": "Empresa faturadora (quando diferente da emissora). Precisa estar relacionada à emissora (`CompanyMain`)." }, "NfsComments": { "type": "string", "nullable": true, "maxLength": 2000, "description": "Observações que vão para a nota." }, "NfsServiceCode": { "type": "string", "nullable": true, "maxLength": 45, "description": "Código de serviço municipal. Validado contra `NfsServiceCode` do município (ou nacional `0` para municípios fora de SP/Rio capital)." }, "NfsServiceQuantity": { "type": "integer", "description": "Quantidade do serviço." }, "NfsServiceUnitValue": { "type": "number", "description": "Valor unitário do serviço." }, "NfsIRRFRetentionValue": { "type": "number", "nullable": true, "description": "Valor de retenção de IRRF. Quando `null`, o sistema calcula a partir do percentual configurado na empresa faturadora (`IRRetentionPercent`)." }, "NfsPISRetentionValue": { "type": "number", "nullable": true, "description": "Valor de retenção de PIS. Mesmo cálculo automático quando `null`." }, "NfsCOFINSRetentionValue": { "type": "number", "nullable": true, "description": "Valor de retenção de COFINS. Mesmo cálculo automático quando `null`." }, "NfsCSLLRetentionValue": { "type": "number", "nullable": true, "description": "Valor de retenção de CSLL. Mesmo cálculo automático quando `null`." }, "NfsISSAliquot": { "type": "number", "nullable": true, "description": "Alíquota do ISS." }, "NfsNBS": { "type": "string", "nullable": true, "description": "Código NBS. O sistema remove pontos antes de validar contra a lista oficial." }, "NfsCClassTrib": { "type": "string", "nullable": true, "description": "Código de classificação tributária (Reforma Tributária). Validado contra `NfCstIbsCbs` para NFSe." }, "NfsCIndOp": { "type": "string", "nullable": true, "description": "Código indicador de operação. Validado contra `NfsCIndOp`." }, "NfsIndFinal": { "type": "integer", "nullable": true, "enum": [ 0, 1 ], "description": "Indicador de consumidor final. `1` consumidor final, `0` não." } } }, "InvoiceServicePaymentCreateBody": { "type": "object", "description": "Corpo do lançamento de pagamento de NFS-e. Todos os campos são opcionais — o sistema preenche com os padrões da empresa.", "properties": { "Comments": { "type": "string", "nullable": true, "description": "Observações." }, "IDTypePayment": { "type": "integer", "description": "Tipo de pagamento. Default: tipo padrão de pedido da empresa." }, "TID": { "type": "string", "nullable": true, "description": "Identificador de transação (gateway)." }, "NSU": { "type": "string", "nullable": true, "description": "Número Sequencial Único (gateway)." }, "Value": { "type": "number", "description": "Valor da parcela (ou total quando `SplitInstallment=0`)." }, "InstallmentTotal": { "type": "integer", "description": "Total de parcelas. Default `1`." }, "Installment": { "type": "integer", "description": "Número da primeira parcela. Default `1`." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data do documento." }, "DateDue": { "type": "string", "format": "date", "nullable": true, "description": "Data de vencimento da primeira parcela. Quando omitida, é calculada com `DaysDue` do tipo de pagamento." }, "DocumentNumber": { "type": "string", "nullable": true, "description": "Número do documento." }, "IDBankAccountForecast": { "type": "integer", "nullable": true, "description": "Banco de recebimento previsto. Default: banco principal de recebimento." }, "IDTypeAccountPayableReceivable": { "type": "integer", "description": "Plano de contas. Default: plano padrão configurado para pedidos." }, "IDTypeDocument": { "type": "integer", "description": "Tipo do documento. Default: tipo padrão." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração de cobrança vinculada." }, "IDCompanyInvoice": { "type": "integer", "nullable": true, "description": "Empresa faturadora. Default: empresa do pedido/NFS-e." }, "DaysDue": { "type": "integer", "nullable": true, "description": "Dias até o vencimento (alternativa a `DateDue`)." } } }, "InvoiceServicePaymentUpdateBody": { "type": "object", "description": "Atualização parcial de uma conta a receber vinculada à NFS-e.", "properties": { "Comments": { "type": "string", "nullable": true, "description": "Observações." }, "IDTypePayment": { "type": "integer", "description": "Tipo de pagamento. Validado contra os cadastrados na empresa." }, "TID": { "type": "string", "nullable": true, "description": "Identificador de transação (gateway)." }, "NSU": { "type": "string", "nullable": true, "description": "Número Sequencial Único (gateway)." }, "Value": { "type": "number", "description": "Valor da parcela." }, "InstallmentTotal": { "type": "integer", "description": "Total de parcelas." }, "Installment": { "type": "integer", "description": "Número desta parcela." }, "IDConsumer": { "type": "integer", "nullable": true, "description": "Cliente vinculado. Não pode ser enviado junto com `IDSupplier`." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência." }, "DateDocument": { "type": "string", "format": "date", "nullable": true, "description": "Data do documento." }, "DateDue": { "type": "string", "format": "date", "description": "Data de vencimento. Quando alterada, `DaysDue` é recalculado." }, "IDBankAccountForecast": { "type": "integer", "description": "Banco de recebimento previsto." }, "DocumentNumber": { "type": "string", "nullable": true, "description": "Número do documento." }, "IDTypeAccountPayableReceivable": { "type": "integer", "description": "Plano de contas." }, "IDTypeDocument": { "type": "integer", "description": "Tipo do documento." }, "IDCompanyIntegration": { "type": "integer", "nullable": true, "description": "Integração de cobrança vinculada." }, "IDCompanyInvoice": { "type": "integer", "description": "Empresa faturadora." }, "ValueDiscount": { "type": "number", "nullable": true, "description": "Valor de desconto." }, "ValueInterest": { "type": "number", "nullable": true, "description": "Valor de juros." }, "ValuePenalty": { "type": "number", "nullable": true, "description": "Valor de multa." }, "IDSupplier": { "type": "integer", "nullable": true, "description": "Fornecedor. Não pode ser enviado junto com `IDConsumer`." }, "Forecast": { "type": "integer", "enum": [ 0, 1 ], "description": "`1` indica conta em previsão." } } }, "BuyOrderLog": { "type": "object", "description": "Linha do histórico de um pedido de compra (`StockKeepingUnitBuyOrderLog`).", "properties": { "IDStockKeepingUnitBuyOrderLog": { "type": "integer", "description": "Identificador da linha do histórico." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data do evento." }, "RecordUserCreated": { "type": "integer", "description": "Identificador do usuário responsável." }, "Login": { "type": "string", "description": "Login do usuário responsável." }, "IDBuyOrder": { "type": "integer", "description": "Pedido de compra do evento." }, "Data": { "type": "string", "maxLength": 5000, "description": "Descrição do evento (texto livre ou JSON com diff de campos quando é alteração)." } } }, "BuyOrderMergeBody": { "type": "object", "required": [ "IDBuyOrder" ], "properties": { "IDBuyOrder": { "type": "integer", "description": "Identificador do pedido de compra de destino — todos os itens do pedido da URL serão movidos para este." } } }, "BuyOrderPaymentCreateBody": { "type": "object", "description": "Corpo do lançamento/atualização de pagamento de pedido de compra. Todos os campos são opcionais; quando não enviados, o `INSERT` grava `NULL`.", "properties": { "IDTypePayment": { "type": "integer", "nullable": true, "description": "Tipo de pagamento. Validado contra os cadastrados na empresa." }, "IDTypeDocument": { "type": "integer", "nullable": true, "description": "Tipo do documento. Validado contra os cadastrados na empresa." }, "IDTypeAccountPayble": { "type": "integer", "nullable": true, "description": "Plano de contas. Precisa ser de último nível (sem filhos em `TypeAccountPayble`)." }, "Value": { "type": "number", "nullable": true, "description": "Valor da conta a pagar." }, "DateDue": { "type": "string", "format": "date", "nullable": true, "description": "Data de vencimento." }, "DateCompetence": { "type": "string", "format": "date", "nullable": true, "description": "Data de competência." }, "Comments": { "type": "string", "nullable": true, "description": "Observações." } } }, "BuyOrderSkuCreateBody": { "type": "object", "required": [ "IDSku", "Quantity" ], "description": "Item a adicionar ao pedido de compra.", "properties": { "IDSku": { "type": "integer", "description": "SKU a comprar. Precisa estar ativo e ser do tipo Sku, Serviço, Matéria-prima ou Uso e consumo (`IDTypeSku` em `3`, `5`, `6`, `7`)." }, "Quantity": { "type": "number", "description": "Quantidade a comprar." }, "ValueCostUnit": { "type": "number", "nullable": true, "description": "Custo unitário." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Validade (quando aplicável)." }, "Comments": { "type": "string", "nullable": true, "maxLength": 200, "description": "Observações sobre o item." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "nullable": true, "description": "Armazém de destino. Quando omitido, usa o armazém padrão da empresa. O centro de distribuição precisa bater com o do pedido." }, "EstimatedDeliveredDate": { "type": "string", "format": "date", "nullable": true, "description": "Data estimada de entrega." }, "IDSkuMovement": { "type": "integer", "nullable": true, "description": "Movimento de SKU de origem (quando o item nasce de outro fluxo)." } } }, "BuyOrderSkuUpdateBody": { "type": "object", "description": "Atualização parcial de item do pedido de compra. Todos os campos são opcionais.", "properties": { "IDSku": { "type": "integer", "description": "Novo SKU. Validado contra `IDTypeSku` em `3`, `5`, `6`, `7`." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Novo armazém. O centro de distribuição precisa bater com o do pedido." }, "Quantity": { "type": "number", "description": "Nova quantidade." }, "ValueCostUnit": { "type": "number", "description": "Novo custo unitário." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Validade." }, "Comments": { "type": "string", "nullable": true, "maxLength": 200, "description": "Observações." }, "EstimatedDeliveredDate": { "type": "string", "format": "date", "nullable": true, "description": "Data estimada de entrega." } } }, "ChargeBankSlipOrderBody": { "type": "object", "description": "Sem campos obrigatórios. O sistema resolve cliente, integração, tipo de pedido e tipo de pagamento a partir do boleto e da configuração da empresa." }, "CompanyBill": { "type": "object", "description": "Empresa com a lista de faturas mensais. Quando não há faturas, `Bills` vem vazio.", "properties": { "AccountName": { "type": "string", "description": "Identificador (subdomínio) da empresa." }, "CompanyNameCorporateName": { "type": "string", "description": "Razão social da empresa." }, "CompanyCpfCnpj": { "type": "string", "description": "CNPJ/CPF da empresa." }, "Bills": { "type": "array", "description": "Faturas mensais ordenadas pela competência mais recente.", "items": { "type": "object", "properties": { "IDCompanyBilling": { "type": "integer", "description": "Identificador da fatura." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de criação da fatura." }, "BillingDateMonth": { "type": "string", "format": "date-time", "description": "Mês de competência da fatura." }, "DueDate": { "type": "string", "format": "date", "description": "Vencimento da fatura." }, "TotalBillValue": { "type": "number", "description": "Soma dos valores cobrados na fatura." }, "IDServiceOrder": { "type": "integer", "nullable": true, "description": "Identificador da ordem de serviço/nota fiscal de serviço." }, "NfsDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de emissão da nota fiscal de serviço." }, "IDStatusInvoice": { "type": "integer", "nullable": true, "description": "Status da nota fiscal de serviço." }, "NfsNumber": { "type": "string", "nullable": true, "description": "Número da nota fiscal de serviço." }, "NfsVerificationCode": { "type": "string", "nullable": true, "description": "Código de verificação da nota fiscal." }, "NfsValue": { "type": "number", "nullable": true, "description": "Valor da nota fiscal (quantidade × valor unitário)." }, "StatusInvoice": { "type": "string", "nullable": true, "description": "Descrição do status da nota fiscal." }, "InvoiceUrl": { "type": "string", "description": "URL externa de consulta da nota fiscal." }, "IDStatusBankSlip": { "type": "integer", "nullable": true, "description": "Status do boleto: `1` Aguardando pagamento, `2` Pago, `3` Pendente, `4` Cancelado, `5` Baixa manual, `6` Protesto.", "enum": [ 1, 2, 3, 4, 5, 6 ] }, "BankSlipUrl": { "type": "string", "nullable": true, "description": "URL para download do boleto." }, "IDBankSlip": { "type": "integer", "nullable": true, "description": "Identificador do boleto." }, "DatePaid": { "type": "string", "format": "date-time", "nullable": true, "description": "Data do pagamento do boleto." }, "StatusBankSlip": { "type": "string", "nullable": true, "description": "Descrição do status do boleto." }, "Charges": { "type": "array", "description": "Itens cobrados na fatura (regras aplicadas no mês).", "items": { "type": "object", "properties": { "IDCompanyBillingCharges": { "type": "integer", "description": "Identificador do item cobrado." }, "TotalValue": { "type": "number", "description": "Valor total do item." }, "TotalQuantity": { "type": "integer", "description": "Quantidade contabilizada no mês." }, "IDCompanyBillingRules": { "type": "integer", "description": "Regra de cobrança aplicada." }, "DateFrom": { "type": "string", "format": "date", "description": "Vigência inicial da regra." }, "DateTo": { "type": "string", "format": "date", "description": "Vigência final da regra." }, "IDTypeCompanyBillingCharges": { "type": "integer", "description": "Identificador do tipo de cobrança." }, "RangeFrom": { "type": "integer", "description": "Limite inferior da faixa de quantidade." }, "RangeTo": { "type": "integer", "description": "Limite superior da faixa de quantidade." }, "UnitValue": { "type": "number", "nullable": true, "description": "Valor unitário da faixa." }, "MinimumValue": { "type": "number", "nullable": true, "description": "Valor mínimo cobrado na faixa." }, "Comments": { "type": "string", "nullable": true, "description": "Observações da regra." }, "TypeCompanyBillingCharges": { "type": "string", "description": "Descrição do tipo de cobrança." } } } } } } } } }, "CompanyDashboardSummary": { "type": "object", "description": "Categoria de painel com os cartões configurados para a empresa.", "properties": { "IDTypeCompanyDashboardCategory": { "type": "integer", "description": "Identificador da categoria do painel." }, "Privilege": { "type": "string", "nullable": true, "description": "Privilégio exigido para visualizar a categoria." }, "TypeCompanyDashboardCategory": { "type": "string", "description": "Descrição amigável da categoria." }, "TypeCompanyDashboard": { "type": "array", "description": "Cartões/blocos exibidos na categoria.", "items": { "type": "object", "properties": { "IDTypeCompanyDashboard": { "type": "integer", "description": "Identificador do bloco." }, "TypeCompanyDashboard": { "type": "string", "description": "Descrição do bloco." }, "Value": { "type": "string", "description": "Valor formatado do bloco (pode incluir total de itens entre parênteses)." }, "URLSearchParams": { "type": "string", "nullable": true, "description": "Querystring para abrir a tela detalhada." }, "component": { "type": "string", "nullable": true, "description": "Componente de UI a renderizar." }, "UpdatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Última atualização do bloco." }, "Difference": { "type": "number", "nullable": true, "description": "Variação em relação à comparação anterior." }, "ValueTotal": { "type": "number", "nullable": true, "description": "Valor consolidado do bloco." }, "UserPrivilege": { "type": "string", "nullable": true, "description": "Privilégio do usuário para ver o bloco." }, "ItemsTotal": { "type": "integer", "nullable": true, "description": "Quantidade de itens contabilizados." } } } } } }, "CompanyDashboardOrderStatus": { "type": "object", "description": "Contagem de pedidos para um status configurado para a empresa.", "properties": { "IDStatusOrder": { "type": "string", "description": "Identificador do status (devolvido como string)." }, "StatusOrder": { "type": "string", "description": "Descrição do status para a empresa." }, "Order": { "type": "integer", "description": "Ordem de exibição do status." }, "StatusOrderDescription": { "type": "string", "nullable": true, "description": "Descrição auxiliar do status." }, "Qty": { "type": "integer", "description": "Quantidade de pedidos no status." } } }, "CompanyModule": { "type": "object", "description": "Grupo de módulos contratados com seus módulos e privilégios.", "properties": { "Module": { "type": "array", "items": { "type": "object", "properties": { "ModuleGroupDescription": { "type": "string", "description": "Nome do grupo de módulos." }, "ModuleDescription": { "type": "string", "description": "Nome do módulo." }, "IDModule": { "type": "integer", "description": "Identificador do módulo." }, "Privilege": { "type": "array", "description": "Privilégios do módulo.", "items": { "type": "object", "properties": { "UserPrivilege": { "type": "string", "description": "Chave técnica do privilégio." }, "IDUserPrivilege": { "type": "integer", "description": "Identificador do privilégio." }, "PrivilegeDescription": { "type": "string", "description": "Descrição amigável." }, "KeyWords": { "type": "string", "nullable": true, "description": "Palavras-chave para busca." } } } } } }, "description": "Módulos contratados pela empresa dentro deste grupo, cada um com seus privilégios." } } }, "CompanyReportCustom": { "type": "object", "description": "Relatório personalizado cadastrado pela empresa, com estrutura completa.", "properties": { "IDTypeCompanyReport": { "type": "integer", "description": "Identificador do relatório." }, "TypeCompanyReport": { "type": "string", "description": "Nome do relatório." }, "IDTypeCompanyReportGroup": { "type": "integer", "description": "Grupo do relatório (sempre `9` para personalizados)." }, "Comments": { "type": "string", "nullable": true, "description": "Observações." }, "Complete": { "type": "integer", "description": "Indica se o relatório terminou de processar." }, "MySQLQuery1": { "type": "string", "nullable": true, "description": "SQL gerada para execução." }, "MySQLQuery2": { "type": "string", "nullable": true, "description": "Segunda variante da SQL gerada (usada quando o relatório precisa de duas consultas — ex.: resumo + detalhe)." }, "BigQueryQuery1": { "type": "string", "nullable": true, "description": "SQL equivalente em BigQuery usada quando o relatório é roteado para o data warehouse externo." }, "BigQueryQuery2": { "type": "string", "nullable": true, "description": "Segunda variante da SQL em BigQuery (par com `MySQLQuery2`)." }, "ReportStructure": { "type": "object", "description": "Estrutura do relatório (campos, filtros, agrupamento, ordenação).", "properties": { "ReportName": { "type": "string", "description": "Nome do relatório." }, "ReportType": { "type": "integer", "description": "Tipo de relatório personalizado." }, "Select": { "type": "array", "description": "Identificadores dos campos selecionados.", "items": { "type": "integer" } }, "Where": { "type": "array", "description": "Filtros aplicados.", "items": { "type": "object", "properties": { "FieldID": { "type": "integer", "description": "Identificador do campo." }, "Value": { "description": "Valor(es) do filtro." }, "Operator": { "type": "string", "description": "Operador inferido pelo tipo do campo: `IN`, `BETWEEN` ou `>=`." } } } }, "GroupBy": { "type": "array", "description": "Identificadores dos campos de agrupamento.", "items": { "type": "integer" } }, "OrderBy": { "type": "array", "description": "Ordenação aplicada.", "items": { "type": "object", "properties": { "FieldID": { "type": "integer", "description": "Identificador do campo." }, "Direction": { "type": "string", "enum": [ "ASC", "DESC" ], "description": "Direção da ordenação." } } } } } }, "RecordTimestamp": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de criação." }, "IDCompanyReport": { "type": "integer", "description": "Vínculo com a empresa." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." }, "IDTypeCustomReport": { "type": "integer", "nullable": true, "description": "Tipo de relatório personalizado (base)." }, "CustomReportType": { "type": "string", "nullable": true, "description": "Descrição da base do relatório." }, "FieldList": { "type": "array", "description": "Catálogo completo dos campos referenciados no relatório.", "items": { "type": "object", "properties": { "IDTypeReportCustomField": { "type": "integer", "description": "Identificador do campo." }, "FieldName": { "type": "string", "description": "Nome da coluna." }, "FieldType": { "type": "string", "nullable": true, "description": "Tipo do campo (`integer`, `decimal`, `date`, `datetime`, `string`)." }, "TableName": { "type": "string", "nullable": true, "description": "Tabela de origem." }, "Expression": { "type": "string", "nullable": true, "description": "Expressão SQL alternativa quando o campo é calculado." }, "Groupable": { "type": "integer", "description": "`1` quando o campo é somável." }, "Active": { "type": "integer", "description": "`1` quando o campo está ativo." } } } } } }, "CompanyReportCustomCreateBody": { "type": "object", "required": [ "ReportName", "ReportType", "Select" ], "properties": { "ReportName": { "type": "string", "description": "Nome do relatório. Default: `\"Relatório Personalizado\"`." }, "ReportType": { "type": "integer", "description": "Identificador do tipo de relatório personalizado (define a tabela base)." }, "Select": { "type": "array", "description": "Identificadores dos campos a retornar.", "items": { "type": "integer" } }, "Where": { "type": "array", "description": "Filtros aplicados. O operador é inferido pelo tipo do campo: `IN` (default), `BETWEEN` (datas) ou `>=` (decimais).", "items": { "type": "object", "required": [ "FieldID" ], "properties": { "FieldID": { "type": "integer", "description": "Identificador do campo." }, "Value": { "description": "Valor(es) do filtro." } } } }, "GroupBy": { "type": "array", "description": "Identificadores dos campos de agrupamento.", "items": { "type": "integer" } }, "OrderBy": { "type": "array", "description": "Ordenação dos campos selecionados.", "items": { "type": "object", "required": [ "FieldID" ], "properties": { "FieldID": { "type": "integer", "description": "Identificador do campo (precisa estar em `Select`)." }, "Direction": { "type": "string", "enum": [ "ASC", "DESC" ], "description": "Direção da ordenação. Default `ASC`." } } } } } }, "Goal": { "type": "object", "description": "Meta cadastrada para a empresa, com o desdobramento conforme o tipo.", "properties": { "IDCompanyGoal": { "type": "integer", "description": "Identificador da meta." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de criação." }, "IDCompany": { "type": "integer", "description": "Identificador da empresa." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." }, "IDTypeGoal": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Tipo da meta: `1` vendedor, `2` faturador, `3` tipo de pedido, `4` integração." }, "TypeGoal": { "type": "string", "description": "Descrição do tipo de meta." }, "GoalName": { "type": "string", "maxLength": 45, "description": "Nome da meta." }, "DateFrom": { "type": "string", "format": "date", "description": "Data inicial de vigência." }, "DateTo": { "type": "string", "format": "date", "description": "Data final de vigência." }, "GoalSalesmans": { "type": "array", "description": "Valores por vendedor (apenas quando `IDTypeGoal=1`).", "items": { "type": "object", "properties": { "IDCompanyGoalSalesmans": { "type": "integer", "description": "Identificador do item." }, "IDUser": { "type": "integer", "description": "Identificador do vendedor." }, "Login": { "type": "string", "description": "Login do vendedor." }, "GoalValue": { "type": "number", "description": "Valor da meta para o vendedor." } } } }, "GoalCompanyInvoices": { "type": "array", "description": "Valores por faturador (apenas quando `IDTypeGoal=2`).", "items": { "type": "object", "properties": { "IDCompanyGoalCompanyInvoices": { "type": "integer", "description": "Identificador do item." }, "IDCompanyInvoice": { "type": "integer", "description": "Identificador do faturador." }, "AccountName": { "type": "string", "description": "Subdomínio do faturador." }, "GoalValue": { "type": "number", "description": "Valor da meta para o faturador." } } } }, "GoalTypeOrders": { "type": "array", "description": "Valores por tipo de pedido (apenas quando `IDTypeGoal=3`).", "items": { "type": "object", "properties": { "IDCompanyGoalTypeOrders": { "type": "integer", "description": "Identificador do item." }, "IDTypeOrder": { "type": "integer", "description": "Identificador do tipo de pedido." }, "TypeOrder": { "type": "string", "description": "Descrição do tipo de pedido." }, "GoalValue": { "type": "number", "description": "Valor da meta para o tipo de pedido." } } } }, "GoalCompanyIntegrations": { "type": "array", "description": "Valores por integração (apenas quando `IDTypeGoal=4`).", "items": { "type": "object", "properties": { "IDCompanyGoalCompanyIntegrations": { "type": "integer", "description": "Identificador do item." }, "IDCompanyIntegration": { "type": "integer", "description": "Identificador da integração da empresa." }, "CompanyIntegration": { "type": "string", "description": "Nome amigável da integração (` - `)." }, "GoalValue": { "type": "number", "description": "Valor da meta para a integração." } } } } } }, "GoalCreateBody": { "type": "object", "required": [ "IDTypeGoal", "GoalName", "DateFrom", "DateTo" ], "properties": { "IDTypeGoal": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Tipo da meta: `1` vendedor, `2` faturador, `3` tipo de pedido, `4` integração." }, "GoalName": { "type": "string", "maxLength": 45, "description": "Nome da meta." }, "DateFrom": { "type": "string", "format": "date", "description": "Data inicial de vigência." }, "DateTo": { "type": "string", "format": "date", "description": "Data final de vigência. Precisa ser maior ou igual a `DateFrom`." }, "GoalSalesmans": { "type": "array", "description": "Desdobramento por vendedor. Obrigatório quando `IDTypeGoal=1`. Cada vendedor precisa pertencer à empresa.", "items": { "type": "object", "required": [ "IDUser", "GoalValue" ], "properties": { "IDUser": { "type": "integer", "description": "Identificador do vendedor." }, "GoalValue": { "type": "number", "description": "Valor da meta para o vendedor." } } } }, "GoalCompanyInvoices": { "type": "array", "description": "Desdobramento por faturador. Obrigatório quando `IDTypeGoal=2`. Cada faturador precisa estar vinculado à empresa principal.", "items": { "type": "object", "required": [ "IDCompanyInvoice", "GoalValue" ], "properties": { "IDCompanyInvoice": { "type": "integer", "description": "Identificador do faturador." }, "GoalValue": { "type": "number", "description": "Valor da meta para o faturador." } } } }, "GoalTypeOrders": { "type": "array", "description": "Desdobramento por tipo de pedido. Obrigatório quando `IDTypeGoal=3`. Cada tipo precisa estar ativo para a empresa.", "items": { "type": "object", "required": [ "IDTypeOrder", "GoalValue" ], "properties": { "IDTypeOrder": { "type": "integer", "description": "Identificador do tipo de pedido." }, "GoalValue": { "type": "number", "description": "Valor da meta para o tipo de pedido." } } } }, "GoalCompanyIntegrations": { "type": "array", "description": "Desdobramento por integração. Obrigatório quando `IDTypeGoal=4`. Cada integração precisa estar visível para a empresa.", "items": { "type": "object", "required": [ "IDCompanyIntegration", "GoalValue" ], "properties": { "IDCompanyIntegration": { "type": "integer", "description": "Identificador da integração da empresa." }, "GoalValue": { "type": "number", "description": "Valor da meta para a integração." } } } } } }, "GoalUpdateBody": { "type": "object", "required": [ "IDTypeGoal", "GoalName", "DateFrom", "DateTo" ], "description": "Mesmo contrato do POST. Todos os campos do desdobramento são opcionais; quando informados, substituem os existentes.", "properties": { "IDTypeGoal": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Tipo da meta: `1` vendedor, `2` faturador, `3` tipo de pedido, `4` integração." }, "GoalName": { "type": "string", "maxLength": 45, "description": "Nome da meta." }, "DateFrom": { "type": "string", "format": "date", "description": "Data inicial de vigência." }, "DateTo": { "type": "string", "format": "date", "description": "Data final de vigência." }, "GoalSalesmans": { "type": "array", "items": { "type": "object" }, "description": "Desdobramento por vendedor." }, "GoalCompanyInvoices": { "type": "array", "items": { "type": "object" }, "description": "Desdobramento por faturador." }, "GoalTypeOrders": { "type": "array", "items": { "type": "object" }, "description": "Desdobramento por tipo de pedido." }, "GoalCompanyIntegrations": { "type": "array", "items": { "type": "object" }, "description": "Desdobramento por integração." } } }, "CorreiosReversa": { "type": "object", "description": "Solicitação de logística reversa Correios para um pedido.", "properties": { "IDCorreiosReverso": { "type": "integer", "description": "Identificador da coleta reversa." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Identificador do pedido vinculado." }, "IDColeta": { "type": "string", "maxLength": 45, "description": "Código da coleta nos Correios." }, "SRO": { "type": "string", "maxLength": 45, "nullable": true, "description": "Código de rastreio (SRO) da reversa." }, "Prazo": { "type": "string", "format": "date", "nullable": true, "description": "Prazo limite da coleta." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de criação da coleta." }, "TipoColeta": { "type": "string", "maxLength": 45, "nullable": true, "description": "Modalidade: domiciliar (`1`/`2`) ou em agência (`0`)." }, "IDCarrier": { "type": "integer", "nullable": true, "description": "Identificador da transportadora." }, "Order": { "type": "string", "nullable": true, "description": "Número do pedido." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social da transportadora." }, "OrderFrom": { "type": "string", "nullable": true, "description": "Origens do pedido separadas por vírgula." } } }, "CorreiosReversaCreateBody": { "type": "object", "required": [ "IDOrder", "IDCarrier" ], "properties": { "IDOrder": { "type": "integer", "description": "Identificador do pedido a ser revertido." }, "QtyObject": { "type": "integer", "description": "Quantidade de objetos da coleta." }, "IDCarrier": { "type": "integer", "description": "Identificador da transportadora Correios." }, "TipoColeta": { "type": "integer", "description": "Modalidade da coleta: `0` em agência (default), demais valores indicam coleta domiciliar." }, "Schedule": { "type": "object", "description": "Agendamento da coleta domiciliar quando aplicável.", "properties": { "DateCollect": { "type": "string", "format": "date", "description": "Data prevista para a coleta." }, "PeriodCollect": { "type": "string", "description": "Período do dia para a coleta." } } } } }, "CorreiosPI": { "type": "object", "description": "Postagem Imediata Correios para um pacote.", "properties": { "IDCorreiosPI": { "type": "integer", "description": "Identificador da PI." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data de criação da PI." }, "IDPackage": { "type": "integer", "description": "Identificador do pacote." }, "PINumber": { "type": "string", "maxLength": 45, "nullable": true, "description": "Número da PI." }, "PICode": { "type": "string", "maxLength": 45, "nullable": true, "description": "Código da PI." }, "IDComplaintReason": { "type": "integer", "nullable": true, "description": "Motivo da reclamação." }, "ComplaintReason": { "type": "string", "nullable": true, "description": "Descrição do motivo da reclamação." }, "DateOpeningPI": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de abertura da PI." }, "DatePostingObject": { "type": "string", "format": "date-time", "nullable": true, "description": "Data de postagem do objeto." }, "DateMaxDelivery": { "type": "string", "format": "date-time", "nullable": true, "description": "Prazo máximo de entrega." }, "DateLastEvent": { "type": "string", "format": "date-time", "nullable": true, "description": "Data do último evento." }, "StatusPI": { "type": "string", "maxLength": 45, "nullable": true, "description": "Status atual da PI." }, "SubStatusPI": { "type": "string", "maxLength": 45, "nullable": true, "description": "Sub-status atual da PI." }, "LastMessageResponse": { "type": "string", "maxLength": 1000, "nullable": true, "description": "Última mensagem retornada pelos Correios." }, "DateLastResponse": { "type": "string", "format": "date-time", "nullable": true, "description": "Data da última resposta dos Correios." }, "ShippingId": { "type": "string", "nullable": true, "description": "Identificador de embarque." }, "ShippingDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data do embarque." }, "IDOrder": { "type": "integer", "description": "Identificador do pedido." }, "Order": { "type": "string", "nullable": true, "description": "Número do pedido." }, "CarrierDeliveryDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Data prevista de entrega pela transportadora." }, "AccountName": { "type": "string", "description": "Subdomínio da empresa." }, "SupplierNameCorporateName": { "type": "string", "nullable": true, "description": "Razão social da transportadora." }, "OrderFrom": { "type": "string", "nullable": true, "description": "Origens do pedido separadas por vírgula." } } }, "FileUploadResponse": { "type": "object", "description": "Registro do arquivo recém-vinculado ao consumidor, com URL pré-assinada de download.", "properties": { "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data/hora de criação do vínculo." }, "IDConsumerFile": { "type": "integer", "format": "int64", "description": "Identificador do arquivo vinculado." }, "IDTypeFile": { "type": "integer", "description": "Tipo do arquivo (mesmos valores aceitos no query `IDTypeFile`).", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] }, "TypeFile": { "type": "string", "description": "Nome legível do tipo do arquivo (ex.: `Documento Fiscal PDF`)." }, "IDConsumer": { "type": "integer", "format": "int64", "description": "Identificador do consumidor dono do arquivo." }, "Key": { "type": "string", "description": "Chave interna do objeto no bucket (`Consumer/.`)." }, "UrlFile": { "type": "string", "format": "uri", "description": "URL pré-assinada para download direto do arquivo (validade aproximada de 48 horas)." } } }, "AppChatTokenResponse": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "JWT assinado para abrir a sessão de chat. Carrega `external_id`, `email`, `name`, `email_verified=true` e `scope=user`; expiração padrão de 12 horas." } } }, "PostalCodeAddress": { "type": "object", "description": "Endereço retornado pela consulta de CEP, combinando dados do cadastro interno de logradouros com o município (IBGE) correspondente à faixa de CEP.", "properties": { "Street": { "type": "string", "nullable": true, "description": "Logradouro." }, "PostalCode": { "type": "string", "description": "CEP (somente dígitos)." }, "Neighborhood": { "type": "string", "nullable": true, "description": "Bairro." }, "AdditionalInfo": { "type": "string", "nullable": true, "description": "Complemento padrão do logradouro (quando cadastrado)." }, "Latitude": { "type": "number", "nullable": true, "description": "Latitude do logradouro (quando disponível)." }, "Longitude": { "type": "number", "nullable": true, "description": "Longitude do logradouro (quando disponível)." }, "State": { "type": "string", "description": "UF do município, derivada da faixa de CEP." }, "CityName": { "type": "string", "description": "Nome do município." }, "CityCodeIBGE": { "type": "integer", "description": "Código IBGE do município (`CityCode`)." } } }, "SkuMovementKardexBatchItem": { "type": "object", "description": "Item do Kardex cronológico de um lote (`Type=KardexBatch`), com saldo e custo acumulados do lote.", "properties": { "AccountName": { "type": "string", "description": "Subdomínio (identificador) da empresa." }, "IDSkuMovement": { "type": "integer", "description": "Identificador da movimentação de estoque." }, "IDSku": { "type": "integer", "description": "Identificador do SKU." }, "RecordTimestamp": { "type": "string", "format": "date-time", "description": "Data e hora da movimentação." }, "Comments": { "type": "string", "nullable": true, "description": "Observações da movimentação." }, "IDStockKeepingUnitProduction": { "type": "integer", "nullable": true, "description": "Identificador da ordem de produção relacionada, quando houver." }, "IDTypeMovement": { "type": "integer", "enum": [ 0, 1 ], "description": "Tipo da movimentação: `0` entrada, `1` saída." }, "IDPurchase": { "type": "integer", "nullable": true, "description": "Identificador do recebimento relacionado, quando houver." }, "IDOrder": { "type": "integer", "nullable": true, "description": "Identificador do pedido relacionado, quando houver." }, "IDStockKeepingUnitWarehouse": { "type": "integer", "description": "Identificador do armazém da movimentação." }, "IDOriginIDSkuMovement": { "type": "integer", "nullable": true, "description": "Identificador da movimentação de origem (transferências/estornos), quando houver." }, "IDStockKeepingUnitInventory": { "type": "integer", "nullable": true, "description": "Identificador do inventário relacionado, quando houver." }, "IDStockKeepingUnitInventorySummary": { "type": "integer", "nullable": true, "description": "Identificador do resumo de inventário relacionado, quando houver." }, "Quantity": { "type": "number", "description": "Quantidade movimentada (positiva para entrada, negativa para saída)." }, "IDBatch": { "type": "integer", "description": "Identificador do lote." }, "WarehouseName": { "type": "string", "description": "Nome do armazém da movimentação." }, "IDStockKeepingUnitLocation": { "type": "integer", "nullable": true, "description": "Identificador do endereço, quando houver." }, "Address": { "type": "string", "nullable": true, "description": "Endereço de estoque, quando houver." }, "BestBeforeDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de validade do lote, quando houver." }, "ManufacturingDate": { "type": "string", "format": "date", "nullable": true, "description": "Data de fabricação do lote, quando houver." }, "BatchComments": { "type": "string", "nullable": true, "description": "Observações do lote, quando houver." }, "ValueCost": { "type": "number", "description": "Custo unitário da movimentação." }, "ValueCostTotal": { "type": "number", "description": "Custo total da movimentação." }, "CardexQty": { "type": "number", "description": "Saldo acumulado do lote após esta movimentação." }, "CardexValueCost": { "type": "number", "description": "Custo total acumulado do lote após esta movimentação." }, "DateCreated": { "type": "string", "format": "date-time", "description": "Data e hora de criação do registro." }, "Login": { "type": "string", "nullable": true, "description": "Login do usuário responsável pela movimentação." }, "TypeMovement": { "type": "string", "nullable": true, "description": "Origem da movimentação: `Recebimento`, `Venda`, `Transferência CD`, `Transferência endereço`, `Ajuste saldo estoque`, `Inventário`, `Produção`." }, "TypeSkuMovement": { "type": "string", "nullable": true, "enum": [ "Entrada", "Saída" ], "description": "Sentido da movimentação: `Entrada` ou `Saída`." }, "CardexAverageValueCost": { "type": "string", "nullable": true, "description": "Custo médio acumulado no kardex, com 2 casas decimais." }, "IsTransfer": { "type": "integer", "enum": [ 0, 1 ], "nullable": true, "description": "Indica se o tipo do pedido é de transferência entre centros de distribuição (`1`) ou não (`0`). Nulo quando a movimentação não está vinculada a um pedido." } } } }, "responses": { "Unauthorized": { "description": "Falha de autenticação: header `Authorization` ausente, malformado ou com token JWT inválido/expirado. O corpo segue o formato padrão (`{ \"message\": \"Unauthorized\" }`), sem o prefixo `[BadRequest]`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Unauthorized" } } } } } } } }, "x-tagGroups": [ { "name": "Catálogo", "tags": [ "Categorias Similares", "Categorias de Produto", "Coleções", "Códigos Similares", "Códigos de Barras", "Códigos de Barras (Embalagem)", "Especificações de SKU", "Especificações por Categoria", "Fornecedores ↔ SKUs", "Grupos de SKU", "Imagens de SKU", "Kits", "Marcas", "Preços", "Produtos e SKUs", "SKU — Etiqueta", "Tags de SKU", "Templates de Importação", "Tipos de Embalagem", "Tipos — Canal de Venda", "Tipos — SKU", "Variações (Grade)" ] }, { "name": "Estoque", "tags": [ "Armazéns", "Centros de Distribuição", "Endereços de Estoque", "Inventário", "Inventário (Legacy)", "Log de SKU", "Lotes", "Movimentação de Estoque", "Números de Série", "Produção", "Recálculo de Custo", "Ressuprimento", "Saldo de Estoque" ] }, { "name": "Vendas", "tags": [ "Pedidos", "Promoção PDV", "Tipos — Pedido" ] }, { "name": "PDV", "tags": [ "Frente de Caixa", "Pagamento PDV", "Tipos — PDV" ] }, { "name": "Fulfillment", "tags": [ "Packing", "Picking", "Tipos — Fulfillment" ] }, { "name": "Frete", "tags": [ "Correios — PI", "Cotação de Frete", "Faixa de Etiquetas Correios", "Logística Reversa Correios", "Modalidades de Transporte", "Templates de Rastreamento", "Tipos — Cotação" ] }, { "name": "Compras", "tags": [ "Agendamento de Recebimento", "DE-PARA CFOP Recebimento", "Feed de NF-e", "Pedido de Compra", "Recebimento", "Tipos — Compras" ] }, { "name": "Nota Fiscal", "tags": [ "CT-e", "NF-e / NFC-e", "NFS-e", "Tipos — CT-e", "Tipos — Nota Fiscal" ] }, { "name": "Impostos", "tags": [ "Departamentos Tributários", "Tipos — Impostos" ] }, { "name": "Financeiro", "tags": [ "Boleto Bancário", "Conciliação Bancária", "Contas Bancárias", "Contas a Pagar", "Contas a Receber", "Fluxo de Caixa", "Tipos — Contas e Pagamento" ] }, { "name": "Clientes", "tags": [ "Cadastro de Clientes", "Tipos — Cliente" ] }, { "name": "Fornecedores", "tags": [ "Cadastro de Fornecedores", "Categorias de Fornecedor", "Tipos — Fornecedor" ] }, { "name": "Marketplaces", "tags": [ "Hub — Anúncios", "Hub — Categorias", "Hub — DE-PARA Adquirentes", "Hub — DE-PARA Transportadora", "Hub — DE-PARA Variações", "Hub — Estoque", "Hub — Marcas", "Hub — Notificações", "Hub — Pagamento", "Hub — Pedidos", "Hub — Política Comercial", "Hub — Recursos", "Hub — Tipos de Referência" ] }, { "name": "Usuários", "tags": [ "Autenticação", "Cadastro de Usuários", "Jornada de Trabalho", "Metas", "Notificações de Versão", "Perfis de Acesso", "Tipos — Metas", "Tipos — Usuário" ] }, { "name": "Empresa", "tags": [ "Cobrança", "Dashboards", "Etiquetas (Empresa)", "Integrações", "Minha Empresa", "Módulos Contratados", "Políticas Comerciais", "Relatórios Customizados", "Tipos — Empresa", "Tipos — Etiquetas", "Tipos — Relatórios", "Transições de Status" ] }, { "name": "Plataforma", "tags": [ "Arquivos", "Jobs e Tarefas", "Logs de Webhook", "Tipos — Jobs", "Webhooks / Callbacks" ] } ] }