Versões e compatibilidade

A versão da API está na URL: https://api.cartaflow.com.br/v1. Tudo o que esta documentação descreve é a versão 1.

O que muda sem avisoCopiar link da seção

Estas mudanças não quebram uma integração bem feita, então acontecem dentro da versão 1, a qualquer momento:

• novos endpoints;
• novos campos opcionais nas requisições;
• novos campos nas respostas e nos eventos;
• novos valores em campos com lista de valores, como um novo status;
• novos tipos de evento;
• novos códigos de erro e de detalhe;
• mudanças no texto de message.

Todas aparecem em Novidades.

Prepare a sua integraçãoCopiar link da seção

Para que essas mudanças nunca quebrem nada:

• Ignore campos que você não conhece. Não falhe ao ler uma resposta ou um evento com um campo novo. Evite validar as respostas com um esquema que rejeita campos extras.
• Trate valores desconhecidos. Ao ler status, type ou cancellation_reason, tenha um caminho para um valor que você ainda não conhece: registre e siga em frente, em vez de quebrar. Um status desconhecido pode ser tratado como "em andamento".
• Trate erros pelo code e, se ele for desconhecido, pelo type. Veja Erros.
• Não compare o texto de message. Ele pode mudar.
• Assine os eventos que você usa no painel, em vez de aceitar qualquer evento. Assim um tipo novo não chega ao seu servidor sem você pedir.

O que só muda em uma nova versãoCopiar link da seção

Mudanças que podem quebrar uma integração só acontecem em uma nova versão, com outro prefixo, como /v2. Por exemplo:

• remover ou renomear um endpoint, um campo ou um valor;
• tornar obrigatório um campo opcional;
• mudar o tipo ou o significado de um campo;
• mudar o formato dos erros.

Quando uma nova versão sair, a versão anterior continua funcionando por pelo menos 12 meses. Avisamos por e-mail os responsáveis técnicos das contas que usam a versão anterior, com o que muda e como migrar.