API: o que da e o que nao da para fazer, e os enderecos que confundem
O QUE E O APLICATIVO API
No catalogo de aplicativos do ERP este item se chama API (Meus aplicativos › Ver todos os aplicativos › API). Ele existe para ligar um sistema de fora ao ERP. A tela inicial dele tem tres cartoes: Credenciais (as chaves de API da empresa), MCP (para conectar um assistente de IA) e Documentacao.
O aplicativo em si nao cadastra nada. Ele so abre a porta. Quem cadastra e o sistema do outro lado, chamando os enderecos. Por isso a pergunta que importa no atendimento e sempre a mesma: esse recurso aceita cadastro pela API, ou e so consulta?
Esta fonte e a visao geral da pasta: o que da e o que nao da para fazer, e para onde ir quando o assunto e mais fundo.
PARA ONDE IR DEPOIS DAQUI
A pasta esta dividida em duas camadas. Esta fonte e o mapa. As outras aprofundam.
Assuntos que valem para a API inteira:
Criar chave com nome e validade, revogar e o segredo que aparece uma vez: a fonte de credenciais da API.
Conectar um assistente de IA ao sistema: a fonte do MCP.
Onde esta a documentacao, a busca nela e o arquivo OpenAPI: a fonte da documentacao.
Quem o token representa, "a API nao traz tudo" e 403: a fonte sobre usuario, loja e permissoes do token.
Os dois codigos, sigilo e troca do par: a fonte do token.
Nome de campo, filtro, paginacao e formato do retorno: a fonte de campos, filtros e retorno.
Mensagem de erro literal e limite de chamadas: a fonte de erro por erro.
Erro de CORS e como testar as chamadas: a fonte de CORS.
Assuntos de um recurso so:
Cliente, fornecedor, transportadora e funcionario, com endereco, contato e o que duplica: a fonte de cadastros de pessoas pela API.
Produto, com o que o sistema preenche sozinho, estoque, variacoes e bloco fiscal: a fonte de produtos pela API.
Pagamento e recebimento, com obrigatorios, rateio e o que nao muda depois: a fonte de pagamentos e recebimentos pela API.
Campos extras (atributos), com os tipos aceitos e o erro de obrigatorio: a fonte de campos extras pela API.
Orcamento, venda, ordem de servico e pedido, com obrigatorios e recalculo do total: a fonte de criacao desses documentos.
Emitir e cancelar nota fiscal: a fonte da linha FIS.
Cliente, produto, financeiro, nota fiscal, usuario e permissao, como conceito, se respondem pelas fontes do ERP. Aqui so entra o efeito na API.
COMO A API SE AUTENTICA
Toda chamada precisa de dois cabecalhos: access-token e secret-access-token. Faltando um deles, a resposta diz qual nao foi informado; errados, diz que estao incorretos. Nunca peca nem repita esses valores na conversa.
A chamada sempre roda em nome de um usuario e de uma loja do ERP. Isso explica a maior parte dos erros: a API obedece as permissoes, ao horario e aos dias de acesso e as restricoes de IP daquele usuario, como se ele estivesse usando o sistema pela tela.
O QUE DA PARA CADASTRAR, EDITAR E EXCLUIR
Confirmado no codigo: clientes, enderecos de clientes, fornecedores, transportadoras, funcionarios, usuarios, produtos, servicos, grades, tipos de valores de produtos, unidades de produtos, centros de custo, formas de pagamento, canais de venda, planos de contas, pagamentos, recebimentos, compras, interacoes, atributos personalizados (de cadastros, produtos, orcamentos, vendas, ordens de servico e financeiro), orcamentos, vendas, ordens de servico, pedidos e notas fiscais de produto, de consumidor e de servico.
O QUE E SOMENTE CONSULTA
Confirmado no codigo: contas bancarias, grupos de produtos, grupos de servicos, marcas, meios de pagamento, meios de envio, estados, cidades, permissoes, grupos de usuarios, lojas, logs (o registro de acoes dos usuarios do ERP, nao um historico das chamadas da API), tipos de contatos, tipos de enderecos, atividades de servicos, naturezas de operacao de servico e todas as situacoes (de atendimentos, compras, contratos, locacoes, orcamentos, ordens de servico, pedidos e vendas).
Conta bancaria, grupo de produto, marca ou situacao nova se cadastram na tela do ERP. O endereco existe, mas so para consultar: a tentativa de cadastro cai em uma acao que nao existe e volta erro.
As duas listas sao o que esta confirmado no codigo, nao um catalogo completo. Recurso que nao aparece em nenhuma delas: verificar antes de responder, em vez de negar.
PRODUTO CRIADO PELA API NASCE SIMPLES
Ao cadastrar um produto pela API, o codigo grava, sem opcao, que ele nao tem variacao e nao tem composicao. Nao existe parametro que mude isso no cadastro. Por isso "cadastrei pela API e o produto veio simples" nao e falha da integracao: e o comportamento do cadastro.
A variacao e a composicao se montam depois, na tela do produto no ERP. A edicao pela API nao atrapalha: ao editar, o sistema le como o produto esta hoje e mantem o que ele ja tiver.
O resto do cadastro de produto pela API — o que o sistema preenche sozinho, como o estoque e gravado, o que sai em variacoes e valores, e a armadilha do bloco fiscal — esta na fonte de produtos pela API.
ORCAMENTO, VENDA, ORDEM DE SERVICO E PEDIDO SAO A MESMA FAMILIA
Oito enderecos apontam para o mesmo recurso e se diferenciam so pelo tipo: orcamentos, orcamentos_produtos, orcamentos_servicos, vendas, vendas_produtos, vendas_servicos, ordens_servicos e pedidos.
Chamando orcamentos sem mais nada, voce recebe orcamento de produto e de servico juntos. O mesmo vale para vendas. O parametro tipo separa: tipo=produto fica no lado de produto, tipo=servico desvia para o lado de servico. Na consulta existe ainda tipo=vendas_balcao; esse valor so e tratado na consulta, nao no cadastro.
Duas armadilhas de nome. Ordens de servico tem sim o seu endereco (ordens_servicos, inclusive para cadastro), mas quem atende e o mesmo recurso desta familia. E pedidos, apesar do nome, e o pedido da loja virtual, nao o pedido de venda do ERP. Quem quer venda usa vendas.
Obrigatorios, minimo de itens, parcelas e recalculo do total estao na fonte de criacao desses documentos.
ENDERECOS QUE CAEM EM OUTRO LUGAR
planos_contas nao tem controlador proprio: a rota manda a chamada para as categorias de movimentacao financeira. E o mesmo cadastro, com outro nome na URL.
pagamentos e recebimentos caem os dois no financeiro, na movimentacao financeira, e e a rota que define para qual lado a chamada vai. Aceitam consulta, cadastro, edicao e exclusao. Na edicao ha uma regra que gera chamado: nao se troca a loja de uma movimentacao ja lancada. Se o corpo mandar loja diferente da gravada, a resposta avisa que alteracoes na loja da movimentacao financeira nao sao permitidas. Obrigatorios, rateio, filtros e o que some da listagem estao na fonte de pagamentos e recebimentos pela API.
Campos extras tambem tem endereco proprio, um para cada modulo. Quais sao, os tipos aceitos e o erro de campo obrigatorio estao na fonte de campos extras pela API.
NOTA FISCAL TEM ENDERECO PROPRIO, E EMITE
Nota fiscal nao atende pelo nome curto. Os enderecos que funcionam sao notas_fiscais_produtos, notas_fiscais_consumidores e notas_fiscais_servicos.
Alem de cadastrar, consultar, editar e excluir, esses enderecos emitem e cancelam a nota. Emitir e cancelar sao chamadas separadas do cadastro, feitas com POST, cada uma com as suas regras de situacao, de loja e de permissao.
Nao responda que emitir nota so se faz na tela do ERP. Da para fazer pela API. Situacao que impede, motivo de cancelamento e mensagens de retorno estao na fonte da linha FIS.
O QUE NAO E A API DE INTEGRACAO
Tres familias de endereco aparecem na mesma pasta e nao servem para integrar o sistema do cliente.
Enderecos com ecommerce_ no nome sao da loja virtual: cliente da loja, vitrine, favoritos, estoque, frete, cupom, pagina, banner, pagamento.
Enderecos com /api/mobile/ sao do aplicativo, com lista propria de recursos e regras proprias, incluindo validade de token, que so e conferida nesse caminho.
Enderecos que comecam com /assinatura_digital/api/ sao da assinatura digital, outro modulo, outro conjunto de rotas.
Apontar a integracao para qualquer um dos tres da erro ou resultado diferente do esperado, e nao e defeito.
/API E /V1 SAO O MESMO ENDERECO
A API responde tanto no endereco que termina em /api quanto no que termina em /v1. E o mesmo destino, com as mesmas regras. Integracao que ja usa um deles nao precisa trocar.
/API/V2/ ESTA DESCONTINUADO
Endereco com /api/v2/ responde 410 com "Este App foi descontinuado!". Isso acontece antes de qualquer outra coisa, antes mesmo de olhar o token. Nao adianta trocar a chave, liberar permissao ou mudar o corpo.
E a primeira coisa a conferir em "a API parou de funcionar do nada". Peca a URL que o sistema esta chamando e procure o v2. O caminho e refazer as chamadas sem v2.
O QUE COSTUMA DAR ERRADO
Chamada em v2. Causa: integracao escrita para a versao descontinuada. Volta 410.
Cadastro recusado em recurso que so consulta. Causa: o recurso e somente leitura. Confira nas duas listas acima antes de abrir chamado.
Cadastro que foi parar no documento errado. Causa: o endereco geral sem o parametro tipo, ou pedidos usado no lugar de vendas.
Produto que chegou sem variacao. Causa: e o comportamento do cadastro, nao um defeito.
"Emitir nota pela API nao existe". Causa: informacao antiga. Existe, e a fonte da linha FIS explica.
Responde mas volta vazio, ou 403 sem motivo aparente. Causa: quase sempre o usuario e a loja que o token representa. Mande para a fonte de identidade do token.
Um filtro que nao filtra, ou um campo que "nao existe". Causa: nome do parametro ou renomeio de campo. Mande para a fonte de campos, filtros e retorno.
Uma frase de erro que o cliente colou. Causa: depende da frase. Peca o texto literal e o codigo HTTP e mande para a fonte de erro por erro.