ProtheusFornecedorDocumentacao (STATUS: PARCIAL)

Documentação Técnica

Nome do cliente	OSKLEN
Nome do projeto	Integração LINX → Protheus
Biblioteca	wosk_protheus_fornecedor
Data	02/03/2026

Histórico de Versões

Data	Versão	Modificado por	Descrição da Mudança
02/03/2026	1.0	Maykon/Gustavo	Criação da documentação técnica do processo ProtheusFornecedor.

Descrição

Este endpoint registra e atualiza cadastros de fornecedores, validando consistência e evitando duplicidades por CPF/CNPJ e nome.
O processo persiste os dados nas tabelas internas de cadastro e retorna a confirmação do registro concluído.

Endpoint (API)

Descrição Conceitual

O endpoint recebe os dados cadastrais do fornecedor, valida obrigatoriedade e consistência conforme o dicionário de campos e impede duplicidade por CPF/CNPJ (CGC_CPF) e por nome (FORNECEDOR). Em seguida, persiste o cadastro base em CADASTRO_CLI_FOR e os dados específicos em FORNECEDORES, e opcionalmente cria/atualiza dados adicionais em TRANSPORTADORAS e CLIENTES_ATACADO conforme os indicadores recebidos.

Ao final, retorna Mensagem = OK e Mensagem Detalhada informando sucesso, incluindo complementos de código interno para fornecedor estrangeiro quando aplicável.

Estruturação de Dados

Identificação do endpoint

O conteúdo do item é ajustado para o padrão utilizado na persistência do cadastro e, quando aplicável, para campos de retorno compatíveis com o Protheus (campos A2_*).

Mapeamento de campos aplicado:

Exemplo de payload enviado (valores ilustrativos):

{
  "A2_COD": "",
  "A2_LOJA": "",
  "FORNECEDOR": "FORNECEDOR EXEMPLO",
  "RAZAO_SOCIAL": "RAZAO SOCIAL EXEMPLO",
  "TIPO": "TIPO EXEMPLO",
  "SUBTIPO": "SUBTIPO EXEMPLO",
  "INDICA_TRANSPORTADORA": 0,
  "INDICA_CLIENTE": 0,
  "FORNECE_MATERIAIS": 1,
  "FORNECE_MATERIA_PRIMA": 0,
  "FORNECE_OUTROS": 0,
  "FORNECE_PRODUTO_ACABADO": 0,
  "BENEFICIADOR": 0,
  "FORNECEDOR_PROD_OSK": 1,
  "PJ_PF": 1,
  "CGC_CPF": "00.000.000/0001-00",
  "RG_IE": "ISENTO",
  "IM": null,
  "CADASTRAMENTO": "2026-03-02 00:00:00",
  "UF": "RJ",
  "CEP": "00000-000",
  "ENDERECO": "RUA EXEMPLO",
  "NUMERO": "100",
  "COMPLEMENTO": "SALA 1",
  "CODIGO_IBGE": "0000000",
  "CIDADE": "RIO DE JANEIRO",
  "BAIRRO": "CENTRO",
  "PAIS": "BRASIL",
  "DDI": null,
  "EMAIL": "fornecedor@exemplo.com",
  "EMAIL_NFE": "nfe@exemplo.com",
  "DDD1": null,
  "TELEFONE1": null,
  "DDD2": null,
  "TELEFONE2": null,
  "CONTATO": null,
  "INATIVO": 0,
  "INDICADOR_FISCAL_TERCEIRO": "00",
  "CONTA_CONTABIL": "000000000000000000",
  "MOEDA": "BRL",
  "CONDICAO_PGTO": "000",
  "OBS_DE_FATURAMENTO": null
}

Tratamento de Dados

Pré-validação estrutural: o payload é validado conforme o dicionário de campos, exigindo todos os parâmetros marcados como obrigatórios e respeitando tipo e tamanho. O campo CIDADE é utilizado na persistência do cadastro base para cobrança/entrega mesmo não fazendo parte do dicionário de validação. Quando TIPO estiver preenchido, a lista permitida de SUBTIPO é carregada consultando FORNECEDOR_SUBTIPO com filtro por TIPO.

Validações de unicidade (antes de persistir):
- CPF/CNPJ: consulta FORNECEDORES filtrando por CGC_CPF. Se houver registro e o FORNECEDOR encontrado for diferente do informado, o endpoint retorna erro indicando o conflito (FORNECEDOR, CGC_CPF, CLIFOR).
- Nome do fornecedor: consulta CADASTRO_CLI_FOR filtrando por NOME_CLIFOR = FORNECEDOR. Se houver registro e o CGC_CPF encontrado for diferente do informado, o endpoint retorna erro indicando o conflito (NOME_CLIFOR, CGC_CPF, CLIFOR).

Normalização aplicada antes de gravar:
- CONTA_CONTABIL: ajustada por máscara de conta contábil interna, para padronizar o formato persistido e utilizado nos destinos.

Persistência em CADASTRO_CLI_FOR (transação): o endpoint monta um registro base de cadastro copiando e reestruturando campos do payload (campos exatos):
- NOME_CLIFOR: recebe o valor de FORNECEDOR.
- COBRANCA_ENDERECO, ENTREGA_ENDERECO: copiados de ENDERECO.
- COBRANCA_CIDADE, ENTREGA_CIDADE: copiados de CIDADE (campo esperado no payload para o cadastro base).
- COBRANCA_BAIRRO, ENTREGA_BAIRRO: copiados de BAIRRO.
- COBRANCA_UF, ENTREGA_UF: copiados de UF.
- COBRANCA_CEP, ENTREGA_CEP: copiados de CEP.
- COBRANCA_CGC, ENTREGA_CGC: copiados de CGC_CPF.
- COBRANCA_IE, ENTREGA_IE: copiados de RG_IE.
- COBRANCA_PAIS, ENTREGA_PAIS: copiados de PAIS.
- ENTREGA_RAZAO_SOCIAL: copiado de RAZAO_SOCIAL.
- IM_ENTREGA, IM_COBRANCA: copiados de IM.
- COBRANCA_NUMERO, ENTREGA_NUMERO: copiados de NUMERO.
- COBRANCA_COMPLEMENTO, ENTREGA_COMPLEMENTO: copiados de COMPLEMENTO.
- COD_MUNICIPIO_IBGE, COD_MUNICIPIO_IBGE_ENTREGA: copiados de CODIGO_IBGE.
- COD_MUNICIPIO_IBGE_COBRANCA: é definido internamente a partir de CODIGO_IBGE, porém não é considerado na gravação do cadastro base conforme o mapeamento atual de persistência.
- DATA_PARA_TRANSFERENCIA: para inserção, é gravada como GETDATE() no banco; o retorno da etapa também mantém um valor de data/hora atual para controle do fluxo.

Em seguida, verifica se existe registro anterior em CADASTRO_CLI_FOR filtrando por NOME_CLIFOR, priorizando o mais recente por CADASTRAMENTO descendente:
- Inserção: quando não houver CLIFOR encontrado, é gerado um novo CLIFOR e COD_CLIFOR por sequência (origem da sequência varia conforme INDICA_CLIENTE) e o registro é inserido em CADASTRO_CLI_FOR.
- Atualização: quando houver CLIFOR encontrado, o registro é atualizado em CADASTRO_CLI_FOR por CLIFOR. Se o registro encontrado já possuir CADASTRAMENTO, esse campo não é alterado na atualização.

Persistência em FORNECEDORES (transação): com o CLIFOR definido, o endpoint prepara o registro do fornecedor e grava em FORNECEDORES com as reestruturações (campos exatos):
- SUBTIPO_FORNECEDOR: recebe o valor de SUBTIPO.
- COD_FORNECEDOR: recebe o valor de CLIFOR.
- FORNECE_PROD_ACAB: recebe o valor de FORNECE_PRODUTO_ACABADO.
- FORNECE_MAT_CONSUMO: recebe o valor de FORNECE_MATERIA_PRIMA.
- CTB_CONTA_CONTABIL: recebe o valor de CONTA_CONTABIL.
- DATA_PARA_TRANSFERENCIA: para inserção, é gravada como GETDATE() no banco; em atualização, é enviada data/hora atual como valor do campo (controle de processamento).
Após preparar, insere quando não existir registro em FORNECEDORES por CLIFOR; caso exista, atualiza por CLIFOR.

Persistência opcional em TRANSPORTADORAS (quando INDICA_TRANSPORTADORA = 1): cria/atualiza registro com as transformações (campos exatos):
- TRANSPORTADORA: recebe FORNECEDOR limitado a 25 caracteres.
- CGC: recebe CGC_CPF.
- TELEFONE: recebe TELEFONE1.
- DDD: recebe DDD1.
- INSCRICAO: recebe RG_IE.
- COD_MUNICIPIO_IBGE: recebe CODIGO_IBGE.
- COMPLEMENTO: limitado a 10 caracteres.
- ENDERECO: recebe ENDERECO e, quando NUMERO estiver preenchido, concatena ", <NUMERO>" ao final.
- PF_PJ: recebe 0 quando PJ_PF = 1 (jurídica) e 1 quando PJ_PF = 0 (física).
- DATA_PARA_TRANSFERENCIA: para inserção, é gravada como GETDATE() no banco; em atualização, é enviada data/hora atual como valor do campo (controle de processamento).
A inclusão/atualização é definida consultando TRANSPORTADORAS por TRANSPORTADORA. Se não houver CODIGO_TRANSP, é gerado um novo código sequencial com padding e o registro é inserido; caso exista, atualiza por CODIGO_TRANSP.

Persistência opcional em CLIENTES_ATACADO (quando INDICA_CLIENTE = 1): cria/atualiza registro com valores fixos e reestruturações (campos exatos):
- CLIENTE_ATACADO, MATRIZ_CLIENTE: recebem FORNECEDOR limitado a 25 caracteres.
- COD_CLIENTE: recebe CLIFOR.
- FILIAL: definido como ESTOQUE ATACADO.
- PONTUALIDADE: definido como REGULAR.
- TRANSPORTADORA: definido como BRASPRESS - RIO JANEIRO.
- CONCEITO: definido como BOM.
- TIPO: definido como FORNECEDOR.
- TIPO_BLOQUEIO: definido como INDEFINIDO.
- CONDICAO_PGTO: definido como 020.
- DATA_PARA_TRANSFERENCIA: para inserção, é gravada como GETDATE() no banco; em atualização, é enviada data/hora atual como valor do campo (controle de processamento).
Para inclusão, consulta CLIENTES_ATACADO por CLIENTE_ATACADO e busca REGIAO em CLIENTES_ATACADO por correspondência com a UF; em atualização, atualiza por CLIENTE_ATACADO.

Complemento para fornecedor estrangeiro: quando UF = EX, o retorno preenche A2_COD com CLIFOR e A2_LOJA com 0001.

Integração com o Protheus

Não há chamada de integração externa direta com o Protheus neste endpoint. O processamento consiste em validações, reestruturação e persistência em banco de dados local nas tabelas CADASTRO_CLI_FOR, FORNECEDORES, TRANSPORTADORAS (quando aplicável) e CLIENTES_ATACADO (quando aplicável).

Tratamento de retorno

Sucesso: quando todas as validações passarem e as transações de persistência forem concluídas, o retorno inclui Mensagem = OK e Mensagem Detalhada = Registrado com sucesso..
Erro: quando a validação estrutural falhar, quando houver conflito de unicidade por CGC_CPF ou por nome, quando falhar a obtenção de sequências/códigos, ou quando ocorrer falha de banco durante insert/update, o endpoint interrompe o processamento e retorna exceção com o detalhe correspondente, prefixando a origem quando aplicável (CADASTRO_CLI_FOR, FORNECEDORES, TRANSPORTADORAS, CLIENTES_ATACADO).

Encaminhamento em cenário de erro

Em erro ao inserir/atualizar qualquer uma das tabelas, a transação da etapa correspondente é desfeita (rollback) e o erro é propagado, evitando persistência parcial entre CADASTRO_CLI_FOR, FORNECEDORES, TRANSPORTADORAS e CLIENTES_ATACADO.

Fluxo do Processo

Critérios de Aceitação

Processo	Subprocesso	Descrição	Situação esperada
Endpoint	Validação de entrada	Ao receber o payload, deve exigir os campos obrigatórios (por exemplo FORNECEDOR, CGC_CPF, UF, CONTA_CONTABIL, MOEDA, CONDICAO_PGTO) e rejeitar entradas fora de tipo/tamanho.	Payload inválido deve ser rejeitado com mensagem de validação; payload válido segue para validações de unicidade.
Endpoint	Unicidade por CPF/CNPJ e nome	Deve impedir que o mesmo CGC_CPF esteja associado a um FORNECEDOR diferente (consulta em FORNECEDORES) e impedir que o mesmo nome (FORNECEDOR) esteja associado a um CGC_CPF diferente (consulta em CADASTRO_CLI_FOR).	Em conflito, deve retornar erro com detalhe do registro encontrado, sem gravar alterações.
Endpoint	Persistência e condicionais	Deve criar/atualizar o cadastro base em CADASTRO_CLI_FOR e o cadastro do fornecedor em FORNECEDORES. Quando INDICA_TRANSPORTADORA = 1, deve criar/atualizar em TRANSPORTADORAS; quando INDICA_CLIENTE = 1, deve criar/atualizar em CLIENTES_ATACADO, mantendo transação e rollback por etapa.	Registros devem ser gravados conforme regra e, em falha de banco, não deve haver persistência parcial (rollback) na etapa com erro.