Valesoft

Appearance

Recebimento de Documentos via API ​

O sistema valesoft permite a integração de documentos externos através de requisição HTTP GET a uma API de um ERP, ou outro sistema externo.

O comportamento do sistema Valesoft ao receber os dados é de criar novas notas, produtos, locais, clientes e EPC, ou atualizar os mesmos caso já existam, se baseando no campo documentReference como chave única para o documento, placeReference para o local, customerReference para o cliente e productReference para o produto e epc para o epc.

Para isso é necessário configurar o token de acesso e a url da API para integração.

A integração Http Json pode chamar APIs sem autenticação ou com autenticação por meio de token passado no header Authorization, como por exemplo, Basic dXNlcm5hbWU6cGFzc3dvcmQ= ou Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

A consulta ocorre de forma paginada com lotes de 250 registros. Isso ocorre através dos parâmetros pageIndexe pageSize. Exemplo:    GET /api/invoice?pageIndex=0&pageSize=250 ou GET /api/invoice?pageIndex=1&pageSize=500, etc.

Resposta esperada pela integração Http Json ​

O sistema espera um retorno em formato JSON da seguinte forma:

JSON
{
  "items": [
      {
        "documentReference": "123/1234",
        "documentDescription": "Documento 123",
        "documentDate": "2023-10-18",
        "documentBatch": "LOTE 987",
        "placeReference":"123",
        "placeName":"Local 1",
        "placeType": "WAREHOUSE",
        "customerReference":"321",
        "customerName":"Cliente 1",
        "type": "MANUFACTURE",
        "supplierReference": "123457",
        "supplierName": "Fornecedor xyz",
        "productReference": "789",
        "productGridReference":"78915",
        "productType": "RAW",
        "productDescription": "Produto 1",
        "barcode": "9876543210",
        "measureUnit": "Un",
        "size": "M",
        "color": "Azul",
        "batch": "lote 32/2024",
        "fraction": 5,
        "quantity": 10,
        "epc": "ABC456789012345678901234",
        "campoCustom1": false,
        "campoCustom2": "teste"
        "useGrid": false

      }
  ],
  "totalItems": 1
}

Definições dos campos do corpo da requisição: ​

  • items - OBRIGATÓRIO

    • Lista de registros a serem criados/atualizados

  • documentReference - OBRIGATÓRIO

    • Alfanumérico
    • Código do documento
    • Chave Primaria - Utilizado para criação ou alteração do registro

  • documentDescription - OBRIGATÓRIO

    • Texto
    • Descrição do documento

  • documentDate - OBRIGATÓRIO

    • Data no formato AAAA-MM-DD
    • Data de Emissão do documento
      • Ex 2023-11-01

  • documentBatch

    • Texto
    • Lote do documento

  • type - OBRIGATÓRIO

    • Texto Predefinido - Maiúsculo
    • Tipo do documento
    • Valores aceitos:
      • PROCESSING - Ordem de Beneficiamento
      • MANUFACTURE - Ordem de produção
      • ENTRY - Nota de Entrada
      • OUTGOING - Nota de Saída
      • SALES - Pedido de venda
      • CLOUD - Nuvem
      • SHIPPING - Remessa
      • RAW_REQUEST - Requisição de material

  • placeReference - OBRIGATÓRIO quando informado o placeName

    • Alfanumérico
    • Código do Local
    • Chave Primaria - Utilizado para criação ou alteração do registro

  • placeName

    • Texto -Nome do Local

  • placeType - OBRIGATÓRIO quando informado o placeName

    • Texto Predefinido - Maiúsculo
    • Tipo do local
    • Valores aceitos:
      • SITE - Planta/Empresa
      • WAREHOUSE - Depósito
      • SECTOR - Setor/Prateleira
      • CONTAINER - Armazenagem de localização

  • customerReference - OBRIGATÓRIO quando informado o customerName

    • Alfanumérico
    • Código do Cliente
    • Chave Primaria - Utilizado para criação ou alteração do registro

  • customerName

    • Texto
    • Nome do Cliente

  • supplierReference - OBRIGATÓRIO quando informado o supplierName

    • Código do fornecedor
    • Chave Primaria - Utilizado para criação ou alteração do registro

  • supplierName

    • Nome do fornecedor

  • productReference - OBRIGATÓRIO

    • Alfanumérico
    • Código/SKU Único do produto
    • Chave Primaria - Utilizado para criação ou alteração do registro

  • productType - OBRIGATÓRIO

    • Texto Predefinido - Maiúsculo
    • Tipo do produto
    • Valores aceitos:
      • RAW - Matéria-prima
      • PRODUCED - Produto acabado
      • CONTAINER - Armazenagem
      • FIXED_ASSET - Ativo Imobilizado

  • productDescription - OBRIGATÓRIO

    • Alfanumérico
    • Descrição do produto

  • barcode

    • Numérico Inteiro
    • Código de barras EAN-13 ou um sequencial numérico único do produto, utilizado para a criação da etiqueta EPC no padrão GS1-SGTIN

  • measureUnit

    • Texto
    • Unidade de medida do produto
      • Ex. M², Un, KG

  • productGridReference

    • Alfanumérico
    • Código/SKU Único da grade do produto
    • Chave Primaria - Utilizado para criação ou alteração do registro

  • size

    • Alfanumérico
    • Código do tamanho do produto
    • Chave Primaria - Utilizado para criação ou alteração do registro

  • color

    • Alfanumérico
    • Código da cor do produto
    • Chave Primaria - Utilizado para criação ou alteração do registro

  • batch

    • Alfanumérico
    • Lote do item no documento/epc

  • fraction

    • Numérico Decimal
    • Quantidade fracionada do produto/epc
      • Ex. Peso, Metragem, etc

  • quantity - OBRIGATÓRIO

    • Numérico Inteiro
    • Quantidade de etiquetas desse produto no documento

  • epc

    • Alfanumérico com restrição(A-F 0-9)
    • Código EPC da etiqueta a ser cadastrada no sistema.

  • campoCustom1 e campoCustom2

    • Quaisquer nomes de campos personalizados desde que os mesmos estejam devidamente configurados nas configurações de campos personalizados do sistema para as tabelas dessa integração.

  • totalItems

    • Número total de documentos

  • useGrid

    • Booleano
    • Verdadeiro se utiliza grade nos produtos

Tipos de Integrações ​

  • Integração por Tipo de Documento: ​

Na integração por Tipo de Documento, o sistema fará a consulta baseado no tipo de documento selecionado na hora da integração. Retornando apenas documentos deste tipo e seus produtos.

Exemplo de como ficaria a consulta na integração Http Json:  GET /api/invoice?documentType=ENTRY

  • Integração por Referência: ​

Na integração por referência, o sistema fará a consulta baseado no código informado na hora da integração. Retornando apenas esse documento e seus produtos.

Exemplo de como ficaria a consulta na integração Http Json:  GET /api/invoice?documentReference=123456

  • Integração periódica: ​

Na integração  periódica, o sistema fará uma consulta de periodicamente, informando uma data inicial e final.
Assim, o sistema externo deverá retornar os dados dos documentos e seus produtos, cuja data de emissão atenda a esse intervalo de datas recebidos.

Exemplo de consulta: GET /api/invoice?startDate=20230401&endDate=20230402 - Onde 20230401 seria o parâmetro de data inicial e 20230402 o parâmetro de data final.

Resposta esperada em caso de erro ​

Retornar uma resposta padrão HTTP com o respectivo status de erro

JSON
{
    "errorMessage": "Mensagem de erro"
}

Valesoft Sistemas RFID

© Copyright 2024. Todos os Direitos Reservados.