API: nomes de campo, filtros e formato do retorno
O QUE É ESTA FONTE
O aplicativo API é o que liga o seu sistema ao ERP. Quem opera isso não é o usuário do dia a dia. É você, ou o desenvolvedor que você contratou, escrevendo código.
Esta fonte trata das três coisas que mais travam essa pessoa: o nome dos campos, o nome dos filtros e o formato da resposta. Ela não repete o resto da pasta. Frase de erro literal, permissão, identidade do token, CORS e as regras de cada recurso têm fonte própria, e o fim desta fonte diz qual é qual.
AS CREDENCIAIS, EM UMA LINHA
Toda chamada precisa de dois cabeçalhos: access-token e secret-access-token. Um sem o outro não autentica. Nunca cole esses valores numa conversa de suporte, em ticket ou em print: quem tem os dois age em nome da sua empresa, sem tela de login. As mensagens de credencial, uma a uma, estão na fonte de erro por erro.
POR QUE OS CAMPOS TÊM OUTRO NOME
A API não devolve o nome da coluna do ERP. Cada endpoint tem uma lista de campos e, dentro dela, alguns são reapelidados. Por isso "esse campo não existe na API" quase sempre significa "esse campo está aí com outro nome". A troca vale nos dois sentidos: sai renomeado na consulta e tem que entrar renomeado na gravação.
No cliente, os campos de pessoa jurídica e de pessoa física perdem o prefixo. pj_razao_social sai como razao_social, pj_cnpj como cnpj, pj_inscricao_estadual como inscricao_estadual, pj_inscricao_municipal como inscricao_municipal, pj_tipo_contribuinte como tipo_contribuinte, pj_responsavel como responsavel, pf_cpf como cpf, pf_rg como rg, pf_data_nascimento como data_nascimento e pf_sexo como sexo. Ainda no cliente, loja_virtual_email sai como email_acesso; no endereço, nome_pais sai como pais.
No financeiro a troca é maior e é a que mais confunde. nome sai como descricao, categoria_id sai como plano_contas_id, nome_categoria sai como nome_plano_conta, baixado sai como liquidado, data_baixa sai como data_liquidacao e data_emissao sai como data_competencia. Repare no último: data_competencia não é a data de vencimento. data_vencimento existe e se chama igual dos dois lados.
No produto, codigo sai como codigo_interno. Os dados de tributação vêm num bloco à parte chamado fiscal, com ncm, cest, peso_liquido, peso_bruto e valor_aproximado_tributos. Atenção à assimetria: na consulta eles vêm dentro de fiscal, mas na gravação você manda esses mesmos nomes no nível principal do produto, não aninhados.
Na nota fiscal não é um punhado de campos: é um mapa inteiro, quase todo campo muda de nome. ide_nNF sai como numero_nf, ide_natOpe como natureza_operacao, ide_data_emissao como data_emissao, emit_CNPJ como cnpj_emitente, dest_xNome como destinatario_nome, total_ICMS_vNF como valor_total_nf e situacao como situacao_nf. Aqui não vale adivinhar pelo padrão: consulte a documentação do endpoint campo a campo.
OS FILTROS QUE A API TRADUZ — LISTA FECHADA
Nos endpoints em /api/, a API traduz o nome de dezoito parâmetros de consulta antes de repassar a busca ao ERP. Esta lista é fechada, não há outros:
pagina, limite, ordenacao, direcao, cidade_id, centro_custo_id, grupo_id, fornecedor_id, cliente_id, situacao_id, categoria_id, funcionario_id, liquidado, plano_contas_id, conta_bancaria_id, forma_pagamento_id, transportadora_id e marca_id.
Essa tradução vale nos endereços que começam com /api/. Não existe hoje um segundo conjunto de endereços em uso para comparar: a seção sobre o /api/v2/, mais abaixo, explica por quê.
Qualquer outro parâmetro segue adiante com o nome que você mandou. Isso não quer dizer que ele não funcione — vários filtros existem com o mesmo nome nos dois lados. No cliente, por exemplo: nome, codigo, ativo, email, telefone, cpf_cnpj, estado, tipo_pessoa, data_inicio e data_fim. Quer dizer apenas que a tradução não acontece.
E aqui nasce a segunda queixa mais comum. Cada listagem lê só os filtros que ela conhece. O que ela não conhece é descartado em silêncio: sem erro, sem aviso, sem campo ignorado na resposta. A chamada volta 200 com a lista inteira e o cliente lê isso como "o filtro não funciona". Ele nunca chegou a existir.
A armadilha mais frequente é usar como filtro o nome renomeado da saída. No produto, o campo sai como codigo_interno, mas o filtro se chama codigo. Filtrar por codigo_interno não filtra nada e não dá erro.
Duas particularidades do financeiro que valem decorar:
O filtro de situação de baixa é liquidado, e ele só entende três valores: pg (liquidado), ab (em aberto) e at (em atraso). Mandar liquidado=1 ou liquidado=true não filtra nada e não dá erro.
Para filtrar por plano de contas, o parâmetro é plano_contas_id — o mesmo nome que aparece na saída. categoria_id não é lido pela listagem financeira.
Antes de abrir chamado dizendo que o filtro está quebrado, faça um teste de trinta segundos: rode a mesma consulta com e sem o filtro e compare o total_registros das duas respostas. Se der o mesmo número, o parâmetro não foi lido — o problema é o nome, não o dado.
COMO VEM A PAGINAÇÃO
Nenhuma listagem devolve tudo de uma vez. O tamanho de página padrão é o limite de registros por página configurado na sua empresa; quando não há nada configurado, são 20. Você muda na chamada com limite, e o teto é 100: pedir limite=500 devolve 100, sem erro e sem aviso. Valor zero ou negativo vira 1. A contagem de páginas começa em 1.
Nas listagens paginadas a resposta traz um bloco meta com estes campos: total_registros, total_paginas, total_registros_pagina, pagina_atual, limite_por_pagina, pagina_anterior, url_anterior, proxima_pagina e proxima_url. As duas URLs já vêm montadas com os seus filtros preservados, então o jeito seguro de varrer tudo é seguir proxima_url até ela vir nula, em vez de somar página por conta própria.
Cuidado com o par de nomes: a URL da página anterior chama-se url_anterior, mas a da próxima chama-se proxima_url. A ordem das palavras muda. Endpoint que não pagina não traz meta nenhum — não trate a ausência como erro.
Para ordenar, use ordenacao com o nome do campo e direcao com asc ou desc. Qualquer outro valor em direcao é tratado como asc, silenciosamente. E ordenacao trabalha com o nome interno do campo no ERP, não com o nome renomeado que aparece na resposta — um nome que não existe no banco não é ignorado: derruba a consulta e devolve erro 500.
O FORMATO DA RESPOSTA
Os endpoints em /api/ respondem sempre no mesmo envelope: code com o status HTTP, status com success ou error, meta quando houver paginação, e data com o conteúdo.
Onde fica a mensagem depende do caso, e isso confunde quem trata erro por código:
Quando a resposta é um texto solto (por exemplo "Nenhum cliente foi encontrado!"), data vem vazio e a mensagem aparece nos campos error e message.
Nos erros de credencial, de permissão de dados e de formato, a mensagem vem dentro de data, nos campos erro e mensagem.
Trate os dois: leia message e, se vier vazio, leia data.mensagem. Uma consulta que não achou nada pode voltar 200 com message e data vazio — isso não é falha, é lista vazia.
/API/V2/ NÃO É UMA SEGUNDA VERSÃO EM USO
Existiu um conjunto de endereços com /api/v2/ no caminho, com outro envelope de resposta. Ele está desligado.
Hoje qualquer chamada cujo endereço tenha /api/v2/ responde 410 com "Este App foi descontinuado!", e isso acontece antes de qualquer outra coisa: antes do token, do plano, da loja e do corpo do envio.
A consequência prática é importante para quem programa: não há o que comparar entre versões. Nome de campo, filtro traduzido, meta e envelope desta fonte valem para /api/, e não existe uma segunda resposta possível para conferir. Se o seu código foi escrito para o formato do v2, ele não volta a funcionar sozinho — as chamadas precisam ser refeitas para os endereços em /api/.
Se a integração parou inteira de uma vez, este é o primeiro item a conferir: procure o v2 na URL que o seu sistema chama.
DATAS E NÚMEROS
Datas viajam em AAAA-MM-DD. Números decimais usam ponto, nunca vírgula.
Antes de gravar, a API confere o formato de três tipos de campo: inteiro, data e decimal. Os demais passam sem conferência de formato. Quando o valor não bate, a resposta é 400 e a mensagem nomeia o campo entre parênteses, com o valor recusado ao lado, no formato "O campo (nome) não é uma data válida (valor)!".
Atenção ao que aparece entre parênteses: é o nome INTERNO do campo no ERP, que pode ser diferente do nome que você mandou, justamente por causa do renomeio explicado lá em cima. Não conclua que mandou o campo errado só porque o nome da mensagem não bate com o do seu código.
FILTRAR SÓ O QUE MUDOU
Para trazer apenas o que foi alterado desde a última sincronização, existem data_modificado_inicio e data_modificado_fim em clientes, fornecedores, transportadoras, produtos, serviços e no financeiro.
No financeiro eles convivem com data_inicio e data_fim, que continuam definindo a janela principal da busca. E vale lembrar: a listagem financeira sem data_inicio e data_fim traz só o mês corrente. Os outros filtros do financeiro, inclusive os de vínculo, estão na fonte de pagamentos e recebimentos.
O QUE COSTUMA DAR ERRADO
O filtro não funciona. Causa: o parâmetro não foi lido, porque a listagem não conhece esse nome. Teste: mesma consulta com e sem o filtro, comparando total_registros.
Esse campo não existe na API. Causa: quase sempre existe, com outro nome. Confira a lista de renomeios.
Filtrei por codigo_interno e não filtrou nada. Causa: codigo_interno é o nome da saída; o filtro se chama codigo.
Mandei liquidado=1 e veio tudo. Causa: esse filtro só entende pg, ab e at.
Pedi limite=500 e vieram 100. Causa: é o teto, e ele não avisa.
A ordenação derrubou a consulta com erro 500. Causa: ordenacao usa o nome interno do campo, e um nome que não existe no banco não é ignorado.
Meu código lê meta.total_registros e não acha nada. Causa: ou o endpoint não pagina, e aí não traz meta, ou o código foi escrito para o formato do v2, que está desligado.
A integração parou inteira, de uma vez. Causa provável: v2 na URL, com 410.
ONDE ESTÁ O RESTO
Frase de erro literal, código HTTP e os limites de requisições: a fonte de erro por erro.
Resposta que volta vazia, 403 sem motivo aparente, qual usuário e qual loja o token representa: a fonte de identidade do token.
Os dois códigos, sigilo e troca do par: a fonte do token.
Erro de CORS e como testar as chamadas: a fonte de CORS.
O que dá e o que não dá para fazer, e os endereços que confundem: a fonte de visão geral da pasta.
Regra e campo de cada recurso: cliente, fornecedor, transportadora e funcionário na fonte de cadastros de pessoas; produto na fonte de produtos; pagamento e recebimento na fonte de pagamentos e recebimentos; campo extra na fonte de campos extras; orçamento, venda, ordem de serviço e pedido na fonte desses documentos; nota fiscal na fonte da linha FIS.
O conceito de cliente, produto, plano de contas ou nota fiscal se responde pelas fontes do ERP. Aqui só entra o efeito na API.