Visão Geral
A API de Documentos de Saída do WMS foi desenvolvida para receber informações de sistemas externos e transformá-las em registros estruturados dentro do processo de expedição do armazém. Seu objetivo é permitir a integração padronizada de pedidos e documentos fiscais de saída, centralizando no backend as regras de:- validação dos dados recebidos;
- identificação da empresa através do usuário autenticado;
- criação e atualização de emitentes e destinatários;
- criação e atualização de produtos;
- cálculo de valores e pesos;
- criação ou atualização do Documento de Saída;
- criação dos respectivos itens;
- análise inicial da disponibilidade de estoque;
- definição automática do status inicial do documento.
pedido— Pedido de saída;nfe— Nota Fiscal Eletrônica de saída.
POST /v1/documentos-saida
Headers
Campos
Documento
O documento é identificado no WMS através da combinação entre empresa, código, tipo, série e emitente.
O campo
codigo é normalizado para letras maiúsculas.
Para documentos do tipo nfe, a série também é normalizada pelo WMS.
Exemplo:
Regras por tipo de documento
Pedido
Para documentos do tipopedido:
serienão deve ser enviada;chave_acessonão deve ser enviada;- o lote dos itens é opcional;
- quando o lote for informado, a análise de estoque considera produto + lote;
- quando o lote não for informado, a análise considera o saldo total disponível do produto.
NF-e
Para documentos do tiponfe:
serieé obrigatória;chave_acessoé obrigatória;- a chave deve possuir 44 dígitos;
loteé obrigatório em todos os itens;- a análise de estoque considera produto + lote exato.
Em fluxos nos quais o WMS recebe inicialmente um pedido, realiza a separação e posteriormente recebe a Nota Fiscal após o faturamento, o fluxo recomendado é utilizar
pedido nesta API e posteriormente utilizar a API de Notas Fiscais de Saída para concluir o processo de faturamento.Emitente
Para localizar um emitente existente, o WMS procura inicialmente pelo
documento e, caso não seja localizado, pelo codigo.
Caso nenhum registro seja encontrado, um novo emitente será criado.
Quando codigo não for informado durante a criação, o WMS gera automaticamente um código interno.
Destinatário
Para localizar um destinatário existente, o WMS procura inicialmente pelo
documento e, caso não seja localizado, pelo codigo.
Caso nenhum registro seja encontrado, um novo destinatário será criado.
Quando codigo não for informado durante a criação, o WMS gera automaticamente um código interno.
Itens [array]
Cada Documento de Saída deve possuir pelo menos um item.
Quando
valor_total não for informado e valor_unitario estiver presente, o WMS calcula:
0.
Para os pesos, quando o peso total não for informado diretamente no item, o WMS utiliza:
Produto
O produto é localizado através do seu
codigo dentro da empresa autenticada.
Caso o produto ainda não exista, será criado automaticamente.
Caso já exista, as informações recebidas poderão atualizar descrição, tipo, unidade de medida e pesos cadastrados.
Cálculo dos Totais
Os totais do Documento de Saída são calculados automaticamente a partir dos itens processados. São calculados:- valor total;
- peso bruto total;
- peso líquido total;
- peso cubado total.
Análise de Estoque
Após criar os itens do Documento de Saída, o WMS realiza uma análise inicial da disponibilidade de estoque. O saldo disponível considerado pela integração é calculado através de:NF-e
Para documentos do tiponfe, a análise considera:
Pedido com lote
Para documentos do tipopedido que possuem lote informado:
Pedido sem lote
Para documentos do tipopedido sem lote informado:
Classificação do Estoque
Cada item é avaliado conforme o saldo disponível.Sem estoque
Estoque parcial
Estoque disponível
Status do Documento
Após analisar todos os itens, o WMS define automaticamente o status do Documento de Saída.
A condição de item sem estoque possui prioridade sobre a condição de estoque parcial.
Exemplo:
A análise realizada nesta API verifica a disponibilidade existente no momento da integração. Ela não realiza a reserva do estoque. A reserva ocorre posteriormente dentro do fluxo operacional de expedição.
Reprocessamento
Enquanto o Documento de Saída ainda não estiver associado a um romaneio, ele poderá ser reenviado através da integração. Neste caso, o WMS:- localiza o documento existente;
- atualiza seus dados principais;
- remove os itens anteriores;
- recria os itens com base no novo payload;
- recalcula valores e pesos;
- realiza novamente a análise de estoque;
- redefine o status do documento.
409.
Exemplo
Exemplo de resposta
O exemplo abaixo considera que pelo menos um dos itens não possui saldo suficiente para atendimento.Exemplo de Pedido
Para pedidos,serie e chave_acesso não devem ser enviados.
PROD001.
Processamento em lote
A API permite o envio de diversos Documentos de Saída em uma mesma requisição. Cada posição do array é processada individualmente. Exemplo conceitual:200 mesmo quando um Documento de Saída individual apresentar erro.
O sistema integrador deve avaliar:
Erros comuns
Status retornados
- Se o produto, emitente ou destinatário ainda não existir, será criado automaticamente e vinculado à empresa do usuário autenticado.
- O Documento de Saída pode ser atualizado através da integração enquanto ainda não estiver vinculado a um romaneio.
- Após o vínculo com um romaneio, o documento não poderá mais ser reprocessado por esta API.
- Para documentos do tipo
nfe, série, chave de acesso e lote dos itens são obrigatórios. - Para documentos do tipo
pedido, série e chave de acesso não devem ser enviadas. - Quando o peso total do item não for informado, o WMS calcula o peso através da quantidade multiplicada pelo peso unitário cadastrado no produto.
- Quando
valor_totalnão for informado, masvalor_unitarioestiver presente, o WMS calcula automaticamente o valor do item. - A análise de estoque não realiza reserva de saldo.
- O processamento de cada documento do lote é isolado. Uma falha em um documento não impede o processamento dos demais.

