Convenções da API

segmentação por área de negócio o contrato é publicado em doze seções , uma por área — o mesmo eixo que os portais de desenvolvedor de erp usam, porque quem integra chega com um objetivo de negócio ("lançar um título", "puxar os fornecedores") e não com uma forma de url seção documento cadastros /v3/api docs/registry compras /v3/api docs/purchasing estoque /v3/api docs/inventory vendas e faturamento /v3/api docs/sales financeiro /v3/api docs/finance contabilidade /v3/api docs/accounting patrimônio /v3/api docs/asset custos e orçamento /v3/api docs/costing frota /v3/api docs/fleet jurídico /v3/api docs/legal folha /v3/api docs/payroll plataforma e gateway /v3/api docs/platform cada seção é um documento openapi independente e gera um pacote independente no sdk o contrato é curado cada seção publica os cenários principais do módulo, não toda a superfície do produto o próprio documento diz isso na descrição se você precisa de algo fora do catálogo de operações docid 825w6ivxqiy 5f88z8ubi fale com o órgão chamar um endereço que existe mas não está publicado costuma funcionar — e é exatamente por isso que é arriscado, porque nada garante que ele continue existindo com aquele formato o contrato vem no seu idioma cada operação publica uma descrição de uma linha — o que ela faz — e essa descrição vem no idioma da requisição mande accept language pt br, en ou es e o mesmo /v3/api docs/\<seção> devolve o summary de cada operação naquele idioma; o console interativo (/swagger ui) reflete o mesmo é o texto que o integrador lê sem depender de adivinhar pela url nem pelo nome do método a frase sai de uma fonte única — um bundle no backend, uma entrada por operação nos três idiomas — e é renderizada em dois lugares aqui no contrato (injetada em tempo de execução) e na referência do sdk typescript docid 3hov7fpn3qwzvzf8ncgm5 , que imprime a versão pt br junto da classe, dos parâmetros tipados e do exemplo a descrição é orientação , não regra o que a operação exige de fato (escopo, corpo, valores aceitos) está no catálogo de operações docid 825w6ivxqiy 5f88z8ubi e na referência do sdk multi tenant um mesmo erp atende vários órgãos o x tenant id diz por qual deles a integração age, e a chave é daquele órgão — chave de um não abre dados de outro erros erros de negócio chegam com código e mensagem já traduzidos para o idioma da requisição os códigos são estáveis; as mensagens não — trate pelo código , nunca comparando o texto faixa significado 400 requisição malformada 401 a chave apresentada não é reconhecida (errada ou revogada) 403 credencial ausente — ou credencial válida sem permissão para a operação (ver autenticação e permissões docid\ uursmhcjyymfej0bzqpkd ) 404 recurso inexistente 409 conflito de estado (ex repetir uma ação já feita) 422 regra de negócio barrou 429 limite de chamadas da chave excedido 401 e 403 respondem perguntas diferentes 401 sai quando a chave foi apresentada e não é reconhecida — errada ou revogada; o corpo traz code appkey invalid 403 sai quando a chave é válida e o escopo não cobre a operação, e também quando nenhuma credencial foi enviada (aí não há o que reconhecer) na dúvida sobre qual dos dois você está vendo, chame /api/v1/integration/health ele responde a qualquer chave válida, então 200 ali prova que a credencial está boa e o problema seguinte é de escopo limite de chamadas há limite por chave, por janela de tempo ao estourar, a resposta é 429 com retry after indicando quantos segundos esperar respeite o cabeçalho em vez de repetir imediatamente nomes das operações o identificador de cada operação é controller método — por exemplo partnercontroller findall é verboso de propósito nomes curtos colidiam entre módulos e o gerador os desempatava com um número posicional , que mudava quando qualquer controller era acrescentado em qualquer lugar do produto um método de cliente que se renomeia por mudança alheia é problema muito pior que um nome longo o que ainda não existe vale saber antes de desenhar a integração idempotência de escrita não há idempotency key um retry após timeout pode duplicar enquanto isso use chave natural de negócio e verifique antes de reenviar paginação por cursor as coleções não paginam por cursor webhooks de saída o erp recebe chamadas; ele não notifica sistemas externos por evento integração baseada em mudança precisa hoje de consulta periódica versionamento do contrato não há v2 paralelo; o contrato evolui no lugar por isso a saída do sdk é versionada no repositório a comparação entre duas gerações é o changelog token de curta duração ver autenticação e permissões docid\ uursmhcjyymfej0bzqpkd