Skip to main content

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.
A integração segue o conceito de processamento em lote, permitindo o envio de um ou mais documentos na mesma requisição. Cada documento do lote é processado individualmente, permitindo que um documento seja rejeitado sem impedir o processamento dos demais. São aceitos os seguintes tipos de Documento de Saída:
  • pedido — Pedido de saída;
  • nfe — Nota Fiscal Eletrônica de saída.
Quando um documento ainda não existe no WMS, ele será criado. Quando já existir e ainda não estiver vinculado a um romaneio de saída, seus dados poderão ser atualizados e seus itens serão recriados com base nas informações recebidas na nova requisição. Após o documento ser vinculado a um romaneio, seu reprocessamento através desta integração não será permitido. Método HTTP: 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:
A chave de acesso é normalizada mantendo apenas caracteres numéricos e deve possuir exatamente 44 dígitos.

Regras por tipo de documento

Pedido

Para documentos do tipo pedido:
  • serie não deve ser enviada;
  • chave_acesso nã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 tipo nfe:
  • 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:
Quando nenhum dos dois valores for enviado, o valor do item será considerado 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.
Exemplo:
Caso o item envie diretamente:
o peso informado no item será utilizado.

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:
Somente quantidades positivas são consideradas disponíveis para atendimento.

NF-e

Para documentos do tipo nfe, a análise considera:
Exemplo:

Pedido com lote

Para documentos do tipo pedido que possuem lote informado:

Pedido sem lote

Para documentos do tipo pedido sem lote informado:
Nesse cenário, o estoque poderá existir distribuído entre diferentes lotes.

Classificação do Estoque

Cada item é avaliado conforme o saldo disponível.

Sem estoque

O item é considerado sem disponibilidade para atendimento.

Estoque parcial

O item possui atendimento parcial.

Estoque disponível

O item possui estoque suficiente para atendimento completo.

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:
  1. localiza o documento existente;
  2. atualiza seus dados principais;
  3. remove os itens anteriores;
  4. recria os itens com base no novo payload;
  5. recalcula valores e pesos;
  6. realiza novamente a análise de estoque;
  7. redefine o status do documento.
O retorno apresentará:
Caso o documento já esteja vinculado a um romaneio de saída, o reprocessamento será rejeitado com status 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.
Neste exemplo, como o pedido não informa lote, a análise de disponibilidade considera o saldo total do produto 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:
O status geral representa o processamento do lote. Por isso, uma requisição pode retornar HTTP 200 mesmo quando um Documento de Saída individual apresentar erro. O sistema integrador deve avaliar:
para identificar o resultado individual de cada Documento de Saída. Exemplo:

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_total não for informado, mas valor_unitario estiver 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.