Rotas de Fator de Conversão do Produto

Nesse artigo estão as rotas para cadastrar, consultar, alterar e excluir os fatores de conversão dos produtos do cliente SPED.

O fator de conversão relaciona um produto do cliente com o produto de um participante (fornecedor), informando a unidade usada pelo fornecedor e o fator para converter a quantidade para a unidade do produto. Cada fator é identificado pela combinação código do produto + CPF/CNPJ do participante + produto do participante, e recebe um id no cadastro.

O cadastro, a alteração e a exclusão são processados de forma assíncrona. O resultado deve ser acompanhado pela consulta do produto, através do status de cada fator.

• Autenticação
• Cadastrar fator de conversão
• Consultar fatores de conversão
• Alterar fator de conversão
• Excluir fator de conversão
• Status do fator de conversão
• Retornos de erro de autenticação

Autenticação

Todas as rotas abaixo utilizam a mesma autenticação:

Cadastrar fator de conversão

Cadastra de 1 a 50 fatores de conversão em uma única requisição. O produto informado em codigoProduto precisa estar cadastrado para o cliente.

Método HTTP

POST

Endpoint

https://sped.plugstorage.com.br/api/v2/sped/produto/fatorConversao

Body

Array de objetos com os campos abaixo.

Exemplo:

[
    {
        "codigoProduto": "001",
        "cpfCnpjParticipante": "60007800000101",
        "participanteProduto": "255",
        "unFornecedor": "CX",
        "fatorConversao": "12",
        "destinacaoPadrao": "R"
    }
]

Retorno de sucesso

Status code 201

{
    "message": "Inserção de Fator de Conversão iniciada com sucesso.",
    "fatoresConversao": [
        {
            "id": "6aea0000ee003f4b0010099c",
            "codigoProduto": "001",
            "cpfCnpjParticipante": "60007800000101",
            "participanteProduto": "255"
        }
    ]
}

O id retornado é utilizado nas rotas de alteração e exclusão.

Retornos de erro

Status code 400 - Erro de validação de um campo do body.

{
    "error": true,
    "parametro": "0.fatorConversao",
    "message": "Parâmetro deve ter apenas números"
}

Status code 400 - Erro de regra de negócio. Quando qualquer item for inválido, nenhum fator é salvo. O campo indice indica a posição do item no array enviado.

{
    "error": true,
    "message": "Foram encontrados erros nos Fatores de Conversão informados. Nenhum registro foi salvo.",
    "erros": [
        { "indice": 0, "message": "Não há registros de Produto com o codigo 001. " },
        { "indice": 1, "message": "Já existe um Fator de Conversão cadastrado para o Produto 001 com o participante 60007800000101 e produto do participante 255." },
        { "indice": 2, "message": "O Fator de Conversão do Produto 001 com o participante 60007800000101 e produto do participante 255 foi informado mais de uma vez na requisição." }
    ]
}

Consultar fatores de conversão

Os fatores de conversão são retornados no campo fatorConversao da consulta de produtos. Consulte a Rota para Consultar Produtos para todos os filtros disponíveis.

Método HTTP

GET

Endpoint

https://sped.plugstorage.com.br/api/v2/sped/produto?codigo={codigoProduto}

https://sped.plugstorage.com.br/api/v2/sped/produto/{idProduto}

Retorno de sucesso

Status code 200

{
    "produtos": [
        {
            "id": "66f1c2a9b4e8a1d2c3f4e5a6",
            "codigo": "001",
            "descricao": "Produto 1",
            "fatorConversao": [
                {
                    "id": "6aea1807ee783f4b8919799c",
                    "codigoProduto": "001",
                    "cpfCnpjParticipante": "63777822000101",
                    "participanteProduto": "255",
                    "unFornecedor": "CX",
                    "fatorConversao": "12",
                    "destinacaoPadrao": "R",
                    "status": "CADASTRADO",
                    "mensagem": "Fator de conversão cadastrado com sucesso"
                }
            ]
        }
    ]
}

O campo status indica a situação do fator, e o campo mensagem contém o retorno da última operação. Veja Status do fator de conversão.

Alterar fator de conversão

Altera um fator de conversão já cadastrado. Informe ao menos um campo no body; os campos não informados mantêm o valor atual. Não é possível alterar o código do produto nem o CPF/CNPJ do participante.

Método HTTP

PATCH

Endpoint

https://sped.plugstorage.com.br/api/v2/sped/produto/fatorConversao/{id}

Parâmetros de rota

Body

Exemplo:

{
    "fatorConversao": "24"
}

Retorno de sucesso

Status code 200

{
    "message": "Alteração de Fator de Conversão iniciada com sucesso."
}

Retornos de erro

Status code 400 - Nenhum campo informado.

{
    "parametro": "",
    "message": "Informe ao menos um campo para alteração."
}

Status code 400 - Já existe outro fator com o novo produto do participante.

{
    "message": "Já existe um Fator de Conversão cadastrado para o Produto 001 com o participante 63777822000101 e produto do participante 300."
}

Também retorna os erros de fator não encontrado, fator em processamento e id inválido.

Excluir fator de conversão

Exclui um fator de conversão. O produto e os demais fatores de conversão dele não são alterados.

Método HTTP

DELETE

Endpoint

https://sped.plugstorage.com.br/api/v2/sped/produto/fatorConversao/{id}

Parâmetros de rota

Body

Esta rota não possui body.

Retorno de sucesso

Status code 200

{
    "message": "Exclusão de Fator de Conversão iniciada com sucesso."
}

Retornos de erro

Retorna os erros de fator não encontrado, fator em processamento e id inválido.

Erros comuns das rotas de alteração e exclusão

Status code 400 - Fator de conversão não encontrado para o cliente, já excluído ou com status ERRO.

{
    "message": "Nenhum(a) Fator de Conversão localizado(a) com os parâmetros informados."
}

Status code 400 - Fator de conversão com outra operação em processamento (cadastro, alteração ou exclusão).

{
    "message": "Fator de Conversão ainda está sendo processado. Utilize a rota get para consulta."
}

Status code 400 - Id em formato inválido.

{
    "message": "ID abc inválido."
}

Status do fator de conversão

O retorno de sucesso das rotas de cadastro, alteração e exclusão indica apenas que a solicitação foi recebida. A confirmação depende do processamento junto ao parceiro e é refletida no status do fator, retornado na consulta do produto.

Retornos de erro de autenticação

Status code 401

Consulte essa documentação para saber os possíveis retornos de erros de autenticação.