API: campos extras (atributos) — endereços, tipos aceitos e o erro de obrigatório
QUANDO USAR ESTA FONTE
Você integrou seu sistema pela API e precisa ler ou gravar os campos personalizados (campos extras) do ERP. Ou a API recusou a gravação dizendo que falta um campo obrigatório e você não sabe qual é. É disso que esta fonte trata. Como se cria um campo extra pelas telas do ERP e o que ele significa no cadastro são assunto das fontes do módulo correspondente — aqui só entra o que a API faz.
OS ENDEREÇOS DOS CAMPOS EXTRAS
Sob /api existem sete endereços de campos extras. Esta lista é fechada:
atributos_cadastros — os campos de cliente, fornecedor e funcionário. É um cadastro só, compartilhado pelos três.
atributos_produtos
atributos_financeiros — os campos de pagamento e recebimento
atributos_orcamentos
atributos_vendas
atributos_ordens_servicos
atributos_contratos — só leitura
Os seis primeiros se comportam do mesmo jeito. Em cada um: GET no endereço lista os campos, GET com o id numérico no fim mostra um, POST cria, PUT com o id edita e DELETE com o id apaga. Quando a listagem não encontra nada, a resposta é "Nenhum campo extra foi encontrado!".
atributos_contratos só lê: GET no endereço lista os campos extras de contrato e GET com o id mostra um. Criar, editar e apagar campo extra de contrato pela API não é possível — isso se faz pela tela.
Não existe um endereço /api/atributos_pedidos que responda. Se a sua integração chama esse caminho, não é filtro nem permissão: não há controlador atendendo ali e a chamada volta em erro.
Cada endereço enxerga só os campos do seu próprio módulo. Um campo criado em atributos_vendas não aparece na listagem de atributos_orcamentos e não pode ser consultado, editado nem apagado por lá. Ao consultar ou apagar com o id de outro módulo (ou de outra empresa) a resposta é "Você não tem permissão para acessar este registro." — que aqui quase sempre quer dizer endereço errado, e não falta de permissão do usuário. Ao editar, a mesma situação responde que o campo extra não foi encontrado.
OS TIPOS ACEITOS — LISTA FECHADA
Ao criar e ao editar, o campo tipo é conferido contra uma lista fechada de sete valores:
cpf
cnpj
check_list — é o tipo que a tela chama de Seleção única (antes, "Múltipla escolha")
selecao_multipla — é o tipo Múltipla seleção, novo: várias opções marcadas no mesmo campo
data
numeros
texto_simples
O check_list continua valendo: é o mesmo valor de sempre, só o nome na tela mudou. Campos que você já tinha como check_list não mudaram, e a sua integração não precisa trocar nada para eles.
O valor que você envia é passado para minúsculas antes da conferência, então CPF, Cpf e cpf dão no mesmo. Qualquer outra palavra — e também não enviar tipo nenhum — devolve 400 com a lista inteira na mensagem: "Tipo inválido, permitidos: cpf, cnpj, check_list, selecao_multipla, data, numeros, texto_simples.". Não existem outros tipos na API. Se você precisa de um comportamento que não está nessa lista, ele não vai ser aceito.
Repare que o tipo é exigido também na edição. Editar só o nome, sem repetir o tipo, cai no mesmo erro.
CHECK_LIST, SELECAO_MULTIPLA E AS OPÇÕES
Os dois tipos com opções sem opções devolvem 400 "Os tipos check_list e selecao_multipla requerem opções.". Isso vale na criação e também na edição: editar um deles sem mandar as opções não passa, para no mesmo erro.
As opções vão numa lista, cada uma com o seu nome. Dois nomes iguais param em "Existe duplicidade no cadastro das opções!". Existe um teto de quantas opções um campo pode ter, e a mensagem de recusa traz esse número.
No selecao_multipla há uma recusa a mais: uma opção não pode aparecer inteira dentro de outra separada por vírgula e espaço (por exemplo "Azul" e "Azul, Verde"). A mensagem diz que uma "não pode ser usada junto com" a outra porque "uma aparece dentro da outra, o que torna impossível saber quais foram marcadas".
Na edição, o que vale é a lista que você mandou: opção que não for reenviada é apagada. Quando o conjunto de opções muda, a API apaga as antigas e grava as novas — as opções passam a ter ids novos. Por isso, ao editar, reenvie sempre todas as opções que devem continuar existindo.
Trocar o tipo de um campo com opções para um tipo sem opções apaga as opções que ele tinha.
O CAMPO A MAIS DOS DOCUMENTOS
Em atributos_orcamentos, atributos_vendas e atributos_ordens_servicos existe um campo obrigatório a mais, na criação e na edição: exibir_impressao. Ele vai pelo texto, não por número, e os valores são fechados: Quando preenchido, Sim, Não. Qualquer outra coisa devolve 400 'Parâmetro "exibir_impressao" inválido, opções: Quando preenchido, Sim, Não.'. Nas respostas desses três endereços ele também volta em texto.
COMO MANDAR O VALOR DENTRO DE UM CADASTRO
Para gravar o conteúdo de um campo extra em um cliente, fornecedor, funcionário, produto, documento ou movimentação financeira, você envia o bloco de atributos junto com o cadastro. Cada item leva o atributo_id do campo e o conteúdo.
O que vale é o atributo_id. A partir dele a API busca o cadastro do campo na sua empresa e preenche sozinha o tipo, a descrição e a marca de obrigatório. Mandar a descrição no lugar do id não funciona — a descrição é reescrita pela API com o nome que está cadastrado.
No selecao_multipla, o conteúdo é o nome de cada opção marcada, uma depois da outra, separadas por vírgula e espaço — por exemplo "Azul, Verde". No check_list vai o nome de uma opção só.
Se o atributo_id não existir, ou for de outra empresa, a gravação inteira cai com 400 "Falha ao salvar dados, campo extra inválido.". Não é gravação parcial: nada é salvo.
O ERRO DE OBRIGATÓRIO
Quando falta um campo extra marcado como obrigatório, a resposta é 400 com a frase "Os seguintes atributos obrigatórios não foram enviados:" seguida do nome de cada campo e do id entre parênteses, precedido do sinal #. Por exemplo: Placa do veículo (#12), Contrato (#15).
Esse número depois do # é exatamente o atributo_id que a sua chamada tem que enviar. É a informação mais útil da mensagem e é a que costuma passar despercebida. Se o campo estiver sem nome no cadastro, sai só o #id.
ONDE A COBRANÇA ACONTECE E ONDE NÃO
Barra de verdade: cliente, fornecedor, funcionário, produto e ordem de serviço, tanto na criação quanto na edição.
Não barra: pagamento e recebimento. A checagem de obrigatório existe no código, mas está desligada nesses dois. Campo extra financeiro marcado como obrigatório não é cobrado pela API — só a validação do atributo_id continua valendo.
Também não barra em orçamento, venda e pedido da loja virtual. A checagem é chamada, mas procura os obrigatórios por um código de módulo que só coincide na ordem de serviço. Na prática, esses documentos passam sem a cobrança. Não conte com a API para garantir o preenchimento obrigatório neles: se isso é importante para o seu processo, valide no seu sistema antes de enviar.
COMO DESCOBRIR OS IDS DOS CAMPOS
O endereço atributos_produtos tem uma ação a mais, chamada busca, que devolve para cada campo o atributo_id, a descricao e o obrigatorio. É o caminho mais curto para o desenvolvedor levantar os ids e saber quais são obrigatórios. Ela aceita o parâmetro q para filtrar por parte do nome.
Os outros cinco endereços não têm essa ação. Neles use a listagem normal, que já traz id, nome, tipo e obrigatorio de cada campo.
O QUE COSTUMA DAR ERRADO
"Cadastrei o campo personalizado e a API não aceita." Na maioria dos casos é o tipo: ou veio um nome fora da lista fechada, ou o tipo não foi enviado. A mensagem já lista os sete permitidos. Quem escreveu "selecao_unica" usou um nome que não existe: a Seleção única é o check_list.
Criar ou editar um check_list ou selecao_multipla sem enviar as opções. Nos dois casos a resposta é a mesma recusa, não um cadastro sem opções.
Editar um campo com opções mandando só parte delas e estranhar que as outras sumiram. Quem não vai na chamada é apagado.
Não enviar o nome do campo: a resposta cobra o preenchimento do nome.
Enviar a descrição do campo em vez do atributo_id. O ERP não casa campo extra por nome nessa hora.
Usar o id de um campo de outro módulo, ou de outra empresa: cai em "Falha ao salvar dados, campo extra inválido." e nada é gravado.
Procurar um campo de venda pelo endereço de orçamento, e receber "Você não tem permissão para acessar este registro." pensando que é permissão de usuário.
Nome repetido: "Nome já cadastrado.". A conferência é por empresa e por módulo, então o mesmo nome pode existir em vendas e em orçamentos.
Ao apagar: campos que já foram preenchidos em algum registro não saem. Em produtos vem "Este campo extra não pode ser deletada, pois existem produtos relacionados."; em cadastros, a mensagem cita clientes, fornecedores ou usuários e funcionários relacionados. Há ainda campos marcados para não permitir exclusão, que respondem "Este campo extra não pode ser excluído.".
Mensagens genéricas: "Falha ao adicionar campo extra", "Falha ao salvar campo extra.", "Falha ao visualizar campo extra.", "Falha ao deletar campo extra." e "Falha ao listar campos extras.". Elas não dizem a causa. Quando aparecerem, confira o corpo enviado contra as regras acima antes de abrir chamado.
ONDE ISTO NÃO FICA
Token, cabeçalhos, filtros, paginação, formato do retorno e os erros gerais da API são de outras fontes da pasta API. Criar o campo personalizado pela tela, escolher o módulo e marcar como obrigatório é do módulo correspondente do ERP.