JSON e XML para integrações: como preparar ficheiros que as APIs possam consumir sem quebrar o fluxo

Um ficheiro válido nem sempre está pronto para ser integrado

O primeiro erro em muitas integrações é confundir sintaxe correta com contrato cumprido. Um JSON pode respeitar a gramática definida pela RFC 8259 e, ainda assim, não conter os campos de que uma API precisa para criar um cliente, atualizar uma encomenda ou publicar um catálogo. O mesmo acontece com XML: pode estar bem formado, com etiquetas corretamente aninhadas, mas não se ajustar ao esquema ou às regras semânticas esperadas pelo sistema recetor.

Antes de automatizar, convém separar três perguntas. A primeira é se o ficheiro pode ser lido como JSON ou XML. A segunda é se a sua estrutura coincide com o esquema esperado. A terceira é se os dados fazem sentido para o processo de negócio. Uma encomenda com sintaxe perfeita, mas sem identificador de produto, pode falhar tal como um ficheiro mal formado; só que a falha aparecerá mais tarde e será mais difícil de depurar.

• Formato: o parser consegue abrir o ficheiro sem erros de sintaxe.
• Contrato: os campos, tipos e hierarquias coincidem com o que está documentado.
• Conteúdo: os valores são aceitáveis para a operação que a API irá executar.

Escolher JSON ou XML segundo o consumidor, não por preferência

JSON costuma ser prático quando o consumidor trabalha com objetos, arrays, cadeias, números, booleanos e nulos. O seu modelo de tipos está definido de forma direta: um valor pode ser objeto, array, número, cadeia, booleano ou null. Por isso, se um campo chamado id chega umas vezes como número e outras como texto, o problema não é estético; é uma inconsistência que obriga o recetor a adivinhar regras que deveriam estar documentadas.

XML encaixa bem quando o sistema recetor já opera com vocabulários XML, estruturas documentais, atributos, namespaces ou contratos herdados. XML permite definir etiquetas próprias e distingue formalmente entre elementos e atributos como pares nome-valor associados a elementos. Ao mapear XML para JSON, essa diferença importa: um atributo não deve desaparecer nem ser confundido com um filho do elemento se o contrato de destino precisar dele.

• Escolha JSON se o contrato esperado se expressa em objetos, arrays e tipos simples.
• Escolha XML se o recetor exige um vocabulário XML, atributos, namespaces ou XSD.
• Não converta por conveniência se o sistema consumidor já impõe um formato.

Checklist mínimo antes de transformar ou enviar

A codificação deve ser revista desde o início. Para JSON trocado entre sistemas abertos, a RFC 8259 exige UTF-8. Em XML, a RFC 7303 recomenda UTF-8 para os tipos de media XML definidos por essa especificação. Se o ficheiro viajar por HTTP, não basta colocar uma extensão correta: Content-Type e Content-Encoding indicam como a representação deve ser interpretada, e o emissor deve gerar Content-Type quando envia conteúdo, salvo se desconhecer o tipo de media.

Também convém alinhar extensão, conteúdo real e tipo MIME. Para JSON, o tipo registado é application/json; para XML genérico, application/xml. Um ficheiro chamado dados.json que contém XML, ou um pedido com Content-Type incorreto, pode provocar erros antes de ser avaliada qualquer regra de negócio. Em integrações repetíveis, esta revisão deve fazer parte do controlo prévio, não da depuração posterior.

• Confirmar UTF-8 antes de processar.
• Verificar a extensão e o conteúdo real do ficheiro.
• Usar application/json para JSON e application/xml para XML genérico.
• Rever Content-Type e Content-Encoding quando for enviado por HTTP.
• Verificar que existe uma estrutura raiz clara e campos obrigatórios documentados.

Nomes de campos e tipos: estabilidade antes de criatividade

Uma API precisa de estabilidade. Alterar nome_cliente para customerName a meio de um fluxo, misturar idiomas ou usar abreviaturas ambíguas obriga a manter exceções. É preferível escolher uma convenção e conservá-la: nomes sem espaços, significado claro e uma correspondência documentada com o sistema de origem. Se o ficheiro for transformado, o mapeamento deve indicar de onde vem cada campo e como é nomeado na saída.

A estabilidade também afeta os tipos. Em JSON, true, false e null devem ser escritos em minúsculas; True, FALSE ou NULL não são JSON conforme à RFC. Além disso, o mesmo campo não deve alternar entre número, cadeia, objeto ou array sem uma regra explícita. Um identificador como 00123 deve ser tratado como texto se esses zeros fizerem parte do valor; se for convertido em número, perder-se-á informação relevante para o sistema que o consome.

• Evitar espaços e mudanças de idioma em nomes de campos.
• Não reutilizar o mesmo campo para significados diferentes.
• Manter identificadores como texto quando o formato exato for importante.
• Não alternar array, objeto, cadeia ou número no mesmo campo sem o documentar.
• Usar true, false e null em minúsculas em JSON.

Erros frequentes que quebram fluxos aparentemente simples

Muitas falhas não aparecem no primeiro registo de teste. Um catálogo pode trazer um único produto como objeto e vários produtos como array; o recetor espera sempre um array e falha quando a cardinalidade muda. Um campo opcional pode aparecer como null, como cadeia vazia ou simplesmente ser omitido; cada opção pode ter um significado diferente se o contrato não o esclarecer. Preparar JSON XML para integrações implica decidir estas regras antes de o ficheiro entrar em produção.

As datas são outro ponto crítico. A RFC 3339 define um formato de data-hora para protocolos de Internet com data completa, separador T, hora completa e fuso horário como Z ou offset numérico. Uma data local sem fuso horário pode ser ambígua se o contrato esperar timestamps de Internet com offset. Em XML, além disso, um fecho de etiqueta fora de ordem quebra a well-formedness, e os namespaces não são adornos: a comparação de nomes depende do namespace associado, não apenas do prefixo visível.

• Zeros iniciais perdidos ao converter identificadores em números.
• Arrays convertidos em objetos quando há apenas um elemento.
• Valores opcionais representados de várias formas sem regra comum.
• Datas locais sem fuso horário quando o recetor espera RFC 3339.
• Namespaces XML tratados como texto decorativo durante uma conversão.

Validar: formato, conteúdo e negócio em separado

A validação mais útil classifica erros. Os erros de formato impedem a leitura do ficheiro: JSON mal formado, XML com etiquetas mal aninhadas ou literais JSON escritos com maiúsculas. Os erros de conteúdo aparecem quando o ficheiro é lido, mas não cumpre tipos, campos obrigatórios ou restrições documentadas. Os erros de negócio ocorrem quando os dados estão estruturalmente corretos, mas a operação não é aceitável para o consumidor.

Para JSON, JSON Schema permite trabalhar com esquemas escritos em JSON e a sua especificação divide-se em Core e Validation. Declarar $schema ajuda a comunicar a leitores e ferramentas que versão se pretende usar. Para XML, XSD permite definir estruturas e tipos esperados. Estas ferramentas não substituem o contrato funcional de uma API, mas ajudam a converter expectativas em regras verificáveis antes de enviar o ficheiro.

• Formato: o documento pode ser analisado como JSON ou XML.
• Conteúdo: campos, tipos e restrições coincidem com JSON Schema, XSD ou regras documentadas.
• Negócio: o recetor aceita a operação com esses valores concretos.
• Depuração: registar um exemplo mínimo que reproduza a falha.

Transformar com segurança: original, saída e versões

Uma transformação segura nunca destrói o ficheiro de entrada. Conserva o original, gera uma saída transformada e compara diferenças antes de partilhar ou automatizar. Isto permite responder a perguntas básicas quando algo falha: que ficheiro chegou, que regra foi aplicada, que saída foi gerada e que versão foi enviada. Se o mapeamento mudar, deve ser versionado como qualquer outro elemento crítico do fluxo.

Na Apification, esta abordagem encaixa com o Cloud: pode organizar ficheiros, serviços e projetos digitais num espaço versionado, pensado para partilha. Também pode rever o histórico de um elemento Cloud, descarregar versões anteriores e restaurar conteúdo de forma segura. Quando for necessário transformar ficheiros, o assistente guiado permite converter, dividir, fundir, otimizar e processar documentos, imagens, vídeo, áudio e dados; a validação específica do contrato externo continua a depender das regras ou esquemas que a equipa tenha definido.

• Guardar sempre o ficheiro original recebido.
• Gerar uma nova saída, não sobrescrever sem controlo.
• Nomear versões de entrada, saída e mapeamento.
• Comparar amostras antes de automatizar entregas.
• Conservar uma amostra mínima reproduzível para depuração.

Onde a Apification se encaixa no fluxo de integração

A Apification pode aportar organização e operação em torno do ficheiro. As equipas podem armazenar originais e saídas no Cloud, partilhar elementos através de links, utilizadores ou grupos, e disponibilizar downloads originais ou transformados. Se o fluxo nascer em formulários, também é possível criar questionários e formulários de captura com validação, controlos de acesso e respostas exportáveis, o que ajuda a reduzir variações antes de os dados serem convertidos em JSON ou XML.

Quando o processo precisa de se ligar a outros sistemas, a Apification permite integrar o Cloud e os seus serviços através de REST API, OpenAPI, webhooks, iframe e JavaScript. As ações do Cloud podem ser ligadas através de APIs e webhooks assinados com novas tentativas, histórico e estatísticas. A decisão prática é clara: use a Apification para organizar, transformar, partilhar e ligar o fluxo; use JSON Schema, XSD ou regras documentadas do consumidor para validar o contrato específico que a API externa exige.

• Cloud para organizar ficheiros originais, transformados e projetos.
• Assistente de transformação para processar dados e outros ficheiros quando aplicável.
• API REST e OpenAPI para integrar serviços Cloud.
• Webhooks assinados para ligar ações com novas tentativas, histórico e estatísticas.
• Permissões, OTP, autenticação externa, restrições e janelas de publicação para proteger acessos.

Perguntas frequentes