Quando uma integração recusa os dados enviados, a primeira pergunta é qual formato e quais regras estavam combinados. Sem conhecer esse acordo, um campo diferente do esperado pode ser confundido com um defeito do sistema da loja ou do fornecedor.
Quem oferece e quem usa
Em uma API, quem oferece a interface publica o contrato, e quem usa a interface segue a versão aplicável desse contrato. O contrato descreve as operações, os campos, os tipos, as credenciais e as respostas. O gateway de pagamento, por exemplo, define os campos aceitos na criação de uma cobrança, e a plataforma de cotação define como consultar as condições de um produto.
Muitas APIs publicam também uma descrição técnica do contrato, em um formato que os programas conseguem ler, como a descrição no padrão OpenAPI, antigo Swagger. Essa descrição lista as operações, os campos e os tipos. As regras de negócio, como os limites de valor, os prazos e o significado de cada código de resposta, costumam ficar na documentação escrita do fornecedor.
O layout dos arquivos
O layout é a organização dos dados em um arquivo: os nomes ou as posições dos campos, os tipos, os tamanhos e os registros esperados. Um layout pode ser publicado por quem recebe o arquivo, estabelecido por um padrão de mercado ou combinado entre as empresas.
O CNAB é um padrão de arquivos usado na troca de informações de cobrança e de pagamentos com os bancos, associado à Federação Brasileira de Bancos, a FEBRABAN. Mesmo com um padrão, cada banco publica as instruções e a versão que aceita, e essas instruções também fazem parte do contrato. Quando dois sistemas do mesmo fabricante trocam arquivos entre si, o fabricante define o layout e as versões compatíveis.
Mudanças e incompatibilidades
Um contrato pode mudar mesmo sem nenhuma atualização no sistema da loja. Um campo obrigatório novo, uma regra alterada, uma operação desativada ou o fim de uma versão antiga podem interromper uma integração que funcionava. A versão do contrato pode aparecer no endereço da operação, como em /v1/pagamentos, em uma informação enviada junto com a mensagem ou em outro mecanismo, e nem toda API indica a versão no endereço.
Uma diferença entre o arquivo e o layout não mostra, sozinha, qual lado está errado. A comparação envolve a versão usada por quem gerou o arquivo, a versão usada por quem leu, os dados efetivamente enviados e o contrato em vigor naquele período.
Compatível nem sempre quer dizer igual
Acrescentar um campo opcional costuma ser compatível quando o programa que lê ignora os campos desconhecidos. Essa tolerância precisa ser confirmada, porque um programa mais rígido pode recusar o campo novo, e um valor novo de situação pode chegar a um programa que só conhece os valores anteriores. Remover um campo, mudar o tipo de um campo ou tornar obrigatório o que era opcional rompe o contrato, mesmo com o mesmo endereço e o mesmo número de versão.
No gateway de pagamento, por exemplo, o campo valor_total passa de número para texto, e o campo status ganha o valor em_analise. Um programa pode falhar ao converter o valor ou tratar a situação desconhecida como uma recusa. A comparação usa a mensagem preservada, a documentação, a tabela de códigos e a versão do programa que lê. Saber que os dois lados usam a versão 1 não basta.
O ambiente de homologação, o ambiente de testes do fornecedor, pode receber uma mudança antes do ambiente de produção, o ambiente que atende as operações reais. Por isso, um teste bem-sucedido em um ambiente não comprova a compatibilidade no outro. A data de início de cada mudança e a data de desativação das versões antigas também fazem parte do contrato.
No suporte
Diante de um dado recusado, convém reunir a operação, a versão do contrato e o campo recusado. A conferência do que foi realmente enviado vem antes de atribuir a falha a quem gerou a mensagem, a quem a leu ou a uma mudança do fornecedor.
Para guardar
- Quem oferece a interface publica o contrato, e quem usa segue a versão combinada.
- O layout de um arquivo pode vir de quem recebe, de um padrão de mercado ou de um acordo entre as empresas.
- O contrato pode mudar sem nenhuma atualização no sistema da loja.
- Uma diferença entre a mensagem e o contrato não mostra, sozinha, qual lado está errado.
- Um teste bem-sucedido na homologação não comprova a compatibilidade na produção.
A integração parou de funcionar, e nenhuma atualização foi instalada na loja. Isso descarta uma mudança no contrato?
Não. O fornecedor pode ter alterado uma regra, tornado um campo obrigatório ou desativado uma versão. Essa hipótese é conferida na documentação e na resposta da operação, junto com as outras mudanças possíveis.
Um arquivo traz um campo a mais do que o programa de leitura espera. É possível concluir que o gerador está errado?
Ainda não. O gerador pode usar um layout novo, e o programa de leitura continuar no antigo. A comparação das versões dos dois lados com o contrato em vigor mostra onde está a incompatibilidade.